Unix time, or POSIX time, is a system for describing points in time: it is the number of seconds elapsed since midnight UTC on the morning of January 1, 1970, not counting leap seconds.  It is widely used not only on Unix-like operating systems but in many other computing systems, including the Java programming language.

Epoch (reference date), from Wikipedia, The Free Encyclopedia

In chronology, an epoch is an instant chosen as the origin of a particular time scale.  The epoch serves as a reference point from which time is measured.  Days, hours and other time units are counted from the epoch, so that the date and time of events can be specified.  Events that took place earlier can be dated by counting negatively from the epoch.  Epochs are generally chosen to be convenient or significant by a consensus of the time scale's initial users.

My fascination with date algorithms brought me to Unix Epoch time calculations and later, conversions of such dates.  At first, this was purely an academic study on my part, done over a really boring weekend.  However, months later, it came in handy when I was charged with pruning timestamped logs--the timestamps were in Unix Epoch time format.

You can find Epoch to UTC conversion routines online, and although it wouldn't be much help in converting thousands of log lines from Unix epoch time to UTC (Coordinated Universal Time), an online Unix time conversion tool was very helpful in validating the conversions that I came up with during development.  ("Online Conversion--Unix time conversion" is available at: http://www.onlineconversion.com/unix_time.htm.)

I chose AWK as my tool for its ease of use and its portability (OK, so "ease of use" is not one of its strong points ). Some versions of AWK have a wrapper for the standard C strftime function to convert Unix Epoch time. For example, with Gawk (GNU Awk) you can use the following:

                gawk 'BEGIN{print strftime("%c",1144279759)}'
            

This returns "Wed Apr 5 19:29:19 2006".  A one-liner is available for such conversions if you're using Gawk, but that function is not available for all versions of AWK.  That was enough for me.

I've included two versions of the program: A barren version and a fully-documented version.  The barren version is, as the term implies, barren.  It has no blank lines nor comments.  As such it is only 167 lines long.  The fully documented and commented version is 329 lines (almost twice as long).  I prefer that degree of documentation because I reuse so much code.  I don't have time to analyze each program every time I want to use some of its code.  Code reuse, by the way, is also why I put so much of the program into functions--again for code reusability.  I'll provide examples of that here.

Epoch_time.awk

As the documentation shows (located at the bottom of the script), the purpose of this script is to return either the current Unix Epoch time (ssssssssss) or to convert an Epoch seconds argument (seconds since January 1, 1970 00:00:00) into yyyymmddhhmiss datetime form -- or -- to convert yyyymmddhhmiss datetime argument into Unix Epoch seconds.  By default, the script uses the host's time zone, but adjustments can be made via the time zone (-z) option.  The optarg is specified in hours and may be specified negatively.

Usage (also contained in the documentation) says to call the script as follows:

   [gn]awk -f epoch_time.awk -- -h -z [-]hh [yyyymmddhhmiss|ssssssssss]

You can also use the shebang line method where the first line calls the gawk/nawk program (i.e.,  #!/usr/bin/nawk -f).  In which case the script may be called like this:

   epoch_time.awk -- -h -z [-]hh [yyyymmddhhmiss|ssssssssss]

Regardless of how you call the script, the options are as follows:

               --             = This option must come first for it tells Awk
                                to pass on all options that follow to the script
                                itself.
               -h             = Help (usage brief)
               -z [-]hh       = Timezone adjustment in hours
               yyyymmddhhmiss = Converts UTC datetime to epoch seconds
               ssssssssss     = Converts Epoch seconds to yyyymmddhhmiss datetime
            

Here are six examples:

               Examples: 1. epoch_time.awk # No options or argument
                         2. epoch_time.awk          1164718505
                         3. epoch_time.awk          20061128125505
                         4. epoch_time.awk -- -z  2 1164718505
                         5. epoch_time.awk -- -z  2 20061128125505
                         6. epoch_time.awk -- -z -2 1164718505

               Displays: 1. 1164718505     # Current datetime to Epoch seconds
                         2. 20061128125505 # Epoch seconds to yyyymmddhhmiss
                         3. 1164718505     # yyyymmddhhmiss to epoch seconds
                         4. 20061128145505 # Adjusted by 2 hour timezone
                         5. 1164725705     # Adjusted by 2 hours
                         6. 20061128105505 # Adjusted by -2 hours
            

epoch_sss_log_conversion.awk

To see how we can reuse so much of what we've already put together, let's take a look at epoch_sss_log_conversion.awk.  This script takes a Nagios log, extracts its epoch time, and outputs log entries with UTC timestamps.  You can do any number of things with the output from there.  Here are a few input lines, followed by the converted output.

               </nagios> head /logs/nagios-02-02-2007-00.log
               [1170306001] LOG ROTATION: DAILY
               [1170306088] SERVICE ALERT: wxpden07;Load;WARNING;HARD;3;CPU Load (30 min. 91%)
                  (60 min. 91%)
               [1170306088] SERVICE NOTIFICATION: netcool;wxpden07;Load;WARNING;send-trap-service;
                  CPU Load (30 min. 91%) (60 min. 91%)
               [1170306089] SERVICE NOTIFICATION: intel_email;wxpden07;Load;WARNING;notify-by-email;
                  CPU Load (30 min. 91%) (60 min. 91%)
               [1170306303] SERVICE FLAPPING ALERT: wxpden66;DiskUsage_Q;STOPPED; Service appears to
                  have stopped flapping (14.0% change < 15.0% threshold)
               [1170306513] SERVICE ALERT: wxpden72;DiskUsage_D;CRITICAL;HARD;3;Socket timeout after
                  10 seconds

               </nagios> epoch_sss_log_conversion.awk /logs/nagios-02-02-2007-00.log | head
               [2007-02-01 00:00:01] LOG ROTATION: DAILY
               [2007-02-01 00:01:28] SERVICE ALERT: wxpden07;Load;WARNING;HARD;3;CPU Load (30 min.
                  91%) (60 min. 91%)
               [2007-02-01 00:01:28] SERVICE NOTIFICATION: netcool;wxpden07;Load;WARNING;
                  send-trap-service;CPU Load (30 min. 91%) (60 min. 91%)
               [2007-02-01 00:01:29] SERVICE NOTIFICATION: intel_email;wxpden07;Load;WARNING;
                  notify-by-email;CPU Load (30 min. 91%) (60 min. 91%)
               [2007-02-01 00:05:03] SERVICE FLAPPING ALERT: wxpden66;DiskUsage_Q;STOPPED; Service
                  appears to have stopped flapping (14.0% change < 15.0% threshold)
               [2007-02-01 00:08:33] SERVICE ALERT: wxpden72;DiskUsage_D;CRITICAL;HARD;3;Socket
                  timeout after 10 seconds
            

Of the seven functions in epoch_sss_log_conversion.awk, six were taken directly from epoch_time.awk.

             basedate()
             ddddd_to_yyyymmdd()
             julian_table()
             leap_year()
             reduce()
             shift_ARGV()