Detailed Description

Provides routines for manipulating date and time information.

Author: D.W. Chin, J.D.E. Creighton and Kipp Cannon

Synopsis

#include <lal/Date.h>

This header covers routines for manipulating date and time information. The various time systems are discussed in [25] .

Modules
	CivilTime
	XLAL routines for converting civil time structures to GPS times.

	SideralTime
	XLAL routines for computing the sidereal time.

	GPS Time
	GPS time manipulation functions.

Prototypes
LIGOTimeGPS *	XLALGPSTimeNow (LIGOTimeGPS *gpstime)
	Populate the LIGOTimeGPS argument with the current system time as returned by time(2) converted to GPS seconds. More...

char *	XLALGPSToStr (char s, const LIGOTimeGPS t)
	Return a string containing the ASCII base 10 representation of a LIGOTimeGPS. More...

Data Structures
struct	LALPlaceAndGPS
	This structure stores pointers to a `LALDetector` and a `LIGOTimeGPS`. More...

Macros
#define	XLAL_EPOCH_UNIX_GPS 315964800
	The UNIX time of the GPS origin epoch. More...

#define	XLAL_EPOCH_J2000_0_JD 2451545.0
	Julian Day (UTC) of the J2000.0 epoch (2000 JAN 1 12h UTC). More...

#define	XLAL_EPOCH_J2000_0_TAI_UTC 32
	Leap seconds (TAI-UTC) on the J2000.0 epoch (2000 JAN 1 12h UTC). More...

#define	XLAL_EPOCH_J2000_0_GPS 630763213
	GPS seconds of the J2000.0 epoch (2000 JAN 1 12h UTC). More...

#define	XLAL_EPOCH_GPS_JD 2444244.5
	Julian Day (UTC) of the GPS epoch (1980 JAN 6 0h UTC) More...

#define	XLAL_EPOCH_GPS_TAI_UTC 19
	Leap seconds (TAI-UTC) on the GPS epoch (1980 JAN 6 0h UTC) More...

#define	XLAL_MJD_REF 2400000.5
	Reference Julian Day for Mean Julian Day. More...

#define	XLAL_JD_TO_MJD(jd) ((jd) - XLAL_MJD_REF)
	Modified Julian Day for specified civil time structure. More...

Format macros for printing LIGOTimeGPS
Example LIGOTimeGPS t = { 1122334455, 666777888 }; printf("The time is %" LAL_GPS_FORMAT "\n", LAL_GPS_PRINT(t)); LAL_GPS_FORMAT #define LAL_GPS_FORMAT Definition: Date.h:119 LAL_GPS_PRINT #define LAL_GPS_PRINT(gps) Definition: Date.h:120 LIGOTimeGPS Epoch relative to GPS epoch, see LIGOTimeGPS type for more details. Definition: LALDatatypes.h:458
#define	LAL_GPS_FORMAT LAL_INT8_FORMAT ".%09" LAL_INT4_FORMAT

#define	LAL_GPS_PRINT(gps) (INT8)(XLALGPSToINT8NS(&(gps)) / XLAL_BILLION_INT8), (INT4)labs(XLALGPSToINT8NS(&(gps)) % XLAL_BILLION_INT8)

Function Documentation

◆ XLALGPSTimeNow()

LIGOTimeGPS* XLALGPSTimeNow ( LIGOTimeGPS * gpstime )

Populate the LIGOTimeGPS argument with the current system time as returned by time(2) converted to GPS seconds.

Returns the address of the LIGOTimeGPS argument or NULL on error. On error, the GPS time is undefined.

Bugs:

This function cannot return negative GPS times. If the current system time indicates a time prior to Sun Jan 06 00:00:00 GMT 1980, this function returns NULL.

Definition at line 43 of file GPSTimeNow.c.

◆ XLALGPSToStr()

char* XLALGPSToStr	(	char *	s,
		const LIGOTimeGPS *	t
	)

Return a string containing the ASCII base 10 representation of a LIGOTimeGPS.

If s is not NULL, then the string is written to that location which must be large enough to hold the string plus a 0 terminator. If s is NULL then a new buffer is allocated, and the string written to it; free the buffer with XLALFree(). The return value is the address of the string or NULL on failure.

Definition at line 274 of file StrToGPS.c.

Macro Definition Documentation

◆ XLAL_EPOCH_UNIX_GPS

#define XLAL_EPOCH_UNIX_GPS 315964800

The UNIX time of the GPS origin epoch.

1980 6 JAN 0h UTC is 3657 days after 1970 1 JAN 0h UTC: 8 standard years of 365 days = 2920 days 2 leap years of 366 days = 734 days 5 extra days. Hence 3657*86400=315964800.

Note that this deliberately does not account for any leap seconds in the interval. POSIX:2001 defines the relation between the UNIX time time_t t and a broken down time struct tm utc as

t = utc.tm_sec + utc.tm_min*60 + utc.tm_hour*3600
+ utc.tm_yday*86400 + (utc.tm_year-70)*31536000
+ ((utc.tm_year-69)/4)*86400 - ((utc.tm_year-1)/100)*86400
+ ((utc.tm_year+299)/400)*86400;

so if you were to set utc.tm_sec=utc.tm_min=utc.tm_hour=0, utc.tm_yday=5, and utc.tm_year=80, then you get t=315964800. That is what this is.

Definition at line 82 of file Date.h.

◆ XLAL_EPOCH_J2000_0_JD

#define XLAL_EPOCH_J2000_0_JD 2451545.0

Julian Day (UTC) of the J2000.0 epoch (2000 JAN 1 12h UTC).

Definition at line 84 of file Date.h.

◆ XLAL_EPOCH_J2000_0_TAI_UTC

#define XLAL_EPOCH_J2000_0_TAI_UTC 32

Leap seconds (TAI-UTC) on the J2000.0 epoch (2000 JAN 1 12h UTC).

Definition at line 85 of file Date.h.

◆ XLAL_EPOCH_J2000_0_GPS

#define XLAL_EPOCH_J2000_0_GPS 630763213

GPS seconds of the J2000.0 epoch (2000 JAN 1 12h UTC).

Definition at line 86 of file Date.h.

◆ XLAL_EPOCH_GPS_JD

#define XLAL_EPOCH_GPS_JD 2444244.5

Julian Day (UTC) of the GPS epoch (1980 JAN 6 0h UTC)

Definition at line 87 of file Date.h.

◆ XLAL_EPOCH_GPS_TAI_UTC

#define XLAL_EPOCH_GPS_TAI_UTC 19

Leap seconds (TAI-UTC) on the GPS epoch (1980 JAN 6 0h UTC)

Definition at line 88 of file Date.h.

◆ XLAL_MJD_REF

#define XLAL_MJD_REF 2400000.5

Reference Julian Day for Mean Julian Day.

Definition at line 89 of file Date.h.

◆ XLAL_JD_TO_MJD

#define XLAL_JD_TO_MJD ( jd ) ((jd) - XLAL_MJD_REF)

Modified Julian Day for specified civil time structure.

Definition at line 90 of file Date.h.

◆ LAL_GPS_FORMAT

#define LAL_GPS_FORMAT LAL_INT8_FORMAT ".%09" LAL_INT4_FORMAT

Definition at line 119 of file Date.h.

◆ LAL_GPS_PRINT

#define LAL_GPS_PRINT ( gps ) (INT8)(XLALGPSToINT8NS(&(gps)) / XLAL_BILLION_INT8), (INT4)labs(XLALGPSToINT8NS(&(gps)) % XLAL_BILLION_INT8)

Definition at line 120 of file Date.h.