How to convert between GPS time and UTC or local time

Peter Shawhan
February 25, 2002

There are a few interactive ways to convert back and forth between UTC or local time (expressed as a date/time string) and GPS time (expressed as a number of seconds since the beginning of the GPS epoch, 6 January 1980 0:00 UTC). One of these, tconvert, is a command-line utility that can just as well be used within a shell script. There is also a Tcl library package to do the same thing more efficiently within a Tcl script. Finally, there are C functions to convert back and forth between GPS time and Unix system time (seconds since 1 January 1970 0:00 UTC).

tconvert

The first interactive way is to use the tconvert command-line utility, which is part of the LIGOtools dataflow package. tconvert takes free-form input, for example: 
  tconvert jan 23, 1999
  tconvert june 14 1999 5:44
  tconvert 1/4/03 6:15:04 pm pst
  tconvert 2002-7-22 5:00am +180sec
  tconvert now
  tconvert now - 5 days
  tconvert 674828383
  tconvert "674828383.34-5*3600"
The first six examples above print out an integer GPS time, while the last two print out a date/time string. (Note that "now" refers to the time according to the system clock of the computer on which tconvert is executed.) There are additional options to convert to/from local time rather than UTC, to specify the format of the output date/time string, and to convert a series of values read from standard input. Type tconvert without any arguments for complete usage information. Note that tconvert is designed to automatically know about future leap seconds as they are announced.

tconvert is also handy for doing in-line conversions when constructing the arguments to other commands, by executing it within backticks. Here is an example using the getMeta utility: 

  getMeta -d lho -q "select count(*) from sngl_inspiral where end_time > `tconvert jan 3, 2002` and snr>10.0"

guild

The second interactive tool is the Time Converter utility that is built into guild. To use it:

In all guild dialog boxes, any entry widget which asks for a time will accept either a GPS time or a date/time string. If a date/time string is entered, it will be converted to a GPS time using the same rules as the Time Converter utility.

Note that all copies of guild should know about future leap-second additions without any action on the part of individual users, thanks to the "web-patch" mechanism. (However, unlike the tconvert case, a human does have to update the central guild source file to keep the leap-second information up to date.)

gpsclock

Typing gpsclock on the unix command line brings up a little window to display the current time in GPS seconds, as well as the UTC time. Unlike the other time-conversion utilities, which get the current time according to the local system clock, gpsclock synchronizes itself to the frame builder at one of the observatory sites, with a precision of about one second.

One handy feature is that you can click on the GPS or UTC time to select it, then paste it into another window. (The GPS time is shown with some internal spaces for improved readability, but these are stripped out when pasting into another window.) There is also a button labeled "Converter" which opens a copy of the same Time Converter utility that is included in guild.

tconvert Tcl library package

The functionality of the tconvert unix command-line utility, described above, can be made available for direct use within a Tcl script by including the line 
  package require tconvert
in the script. This creates a Tcl command, tconvert, which behaves the same as the unix command-line utility. (Even without this, you could perform time conversions in a Tcl script by executing the command-line utility using Tcl's exec function, but that involves spawning a subshell.) In fact, the tconvert and gpsclock utilities both use the tconvert library package to do the actual time conversions.

C functions

The "dataflow" library (libdataflow.a) includes two functions to convert between GPS time and Unix system time: 
time_t TConvertSysToGPS( time_t systime );
time_t TConvertGPSToSys( time_t gpstime );
Both functions return -1 if an error occurs. These functions use the same leap-second information as the tconvert command-line utility, and have the same ability to automatically update the local disk file if necessary. (In fact, they execute tconvert to do the update.)