LIGOtools Package: time

This package contains utilities to convert to/from GPS time, plus a handy GPS clock:

The tconvert command-line utility, which converts a free-form date/time string to GPS seconds and vice versa.
A Tcl library package called tconvert which has the same capabilities as the command-line utility, but can be used from within a Tcl script by including the line package require tconvert.
A library (libTConvert.a) which allows a C program to convert between Unix system time and GPS seconds.
The gpsclock utility, which pops up a little window to display the current GPS time, synchronized to the U.S. Naval Observatory's master clock.

Author: Peter Shawhan

Version 6.0

Release date: October 28, 2005
History of changes

Frequently Asked Questions related to this package

How can I convert between GPS time and UTC or local time?

Notes

This package is distributed via 'ligotools_update' only as a SOURCE distribution. The C code components are compiled with gcc and made into a library automatically when the package is installed. If for some reason you aren't able to compile them, you can get the precompiled binary distribution files below.
The utilities in this package use the tclshexe and wishexe programs from the LIGOtools package 'tclexe', so that package must be installed and active.
Note that the functions TConvertGPSToSys() and TConvertSYSToGPS() assume that the Unix system clock (i.e. the time_t value returned by the time() function) is the number of non-leap seconds since January 1, 1970. This is the POSIX standard and is true for most Unix systems, but there may be exceptions. I (Peter) would be interested to hear if you encounter any of these exceptions.

Documentation

Typing tconvert without any arguments will print out detailed usage information.
A common use of the tconvert utility is to do tconvert now, which prints the current GPS time according to the system clock of the computer on which tconvert is executed. If a more accurate GPS time is needed for human consumption, use the gpsclock utility, which is synchronized to the U.S. Naval Observatory's master clock with a precision of roughly 1 second.
The tconvert and gpsclock command-line utilities, the tconvert Tcl library package, and the C library functions TConvertGPSToSys() and TConvertSYSToGPS(), are all designed to automatically know about new leap seconds as they are announced. The initial information source is the leapseconds file from an LDAS web server (which is itself updated daily from a Navy ftp site), plus the latest Bulletin C of the International Earth Rotation Service. This leap-second information is normally stored in the file $LIGOTOOLS/config/public/tcleaps.txt along with a "valid through" time, so that future time conversions will generally be able to get leap-second information from the disk file rather than having to use the web. When the disk file expires, it is automatically updated, so leap seconds should be known about some time before they actually take effect. (Of course, if you perform a conversion on a time several months in the future, it may not yet be known whether there will be a leap second added in the meantime.) It is hoped that these web files will continue to exist, in basically the same format, for the forseeable future; if not, a warning or error message will be printed to standard error.
You can specify another location for the tcleaps.txt file, other than the default of $LIGOTOOLS/config/public, by setting the environment variable TCLEAPSDIR . Also, if $LIGOTOOLS/config/public/tcleaps.txt exists but is not writable by you (e.g. it is on a read-only filesystem), then the code uses $HOME/tcleaps.txt as the location.
Example C program to do some conversions between Unix system time and GPS time: example_TConvert.c To compile this, do:
gcc example_TConvert.c $LIGOTOOLS/lib/libTConvert.a -I$LIGOTOOLS/include -o example_TConvert

Distribution files

Normally, you should use the ligotools_update utility to download and install new packages or new versions of existing packages, since it automatically figures out what packages need to be updated. However, if you wish to do so manually, then click on the name of the appropriate distribution file (below) with the right mouse button and choose "Save Link As..." from the popup menu. Note that you must save it on your disk with exactly the same name as it has on this web site. After the file has been downloaded, do:
ligotools_install <file>
where <file> is the file which was downloaded. This procedure will be quicker if the environment variable LIGOTOOLS is set to the main LIGOtools directory.

Binary distribution for Solaris: time_6.0_SunOS.tar.gz (29 kb)
Binary distribution for Intel Linux: time_6.0_Linux.tar.gz (29 kb)
Source distribution: time_6.0_SOURCE.tar.gz (22 kb)
This is known to build properly on Solaris and Linux using gcc; other operating systems or compilers may require some modifications. If you figure out how to do this, please let me know.