libstddjb
skalibs
Software
www.skarnet.org

The djbtime library interface

The following functions are declared in the djbtime.h header, and implemented in the libstddjb.a or libstddjb.so library.

General information

djbtime is a set of functions to convert struct tai and struct taia structures, and TAI time, from and to other time formats and user-friendly representations.

The /etc/leapsecs.dat file

User-friendly time is calculated from UTC. Internal time computations should be performed on TAI time - because TAI flows linearly whereas UTC does not. To convert between UTC and TAI time, you need a leap second table. skalibs provides such a file in /package/prog/skalibs/etc/leapsecs.dat, which is copied to /etc/leapsecs.dat at installation time. The /etc/leapsecs.dat file must remain accessible on your system, else time conversions will not be computed properly.

Data structures

Functions

UTC

int utc_from_tai (uint64 *u, struct tai const *t)
Converts the absolute TAI64 time in *t to an UTC time, stored in *u as an unsigned 64-bit integer. *u is actually 2^62 plus the number of seconds since the Epoch. The function returns 1 if it succeeds, or 0 (and sets errno) if an error occurs (for instance: the leap second table cannot be found).

int tai_from_utc (struct tai *t, uint64 u)
Converts the UTC time in u, stored as an unsigned 64-bit integer (2^62 plus the number of seconds since the Epoch), to a TAI64 time in *t. The function returns 1 if it succeeds, or 0 (and sets errno) if an error occurs (for instance: the leap second table cannot be found).

NTP

int ntp_from_taia (uint64 *ntp, struct taia const *a)
Converts the absolute TAI64NA time in *a to a 64-bit NTP timestamp, stored in *ntp. The higher 32 bits of *ntp represent a number of seconds ; the lower 32 bits are the fractional part of the timestamp. The function returns 1 if it succeeds, or 0 (and sets errno) if an error occurs (for instance: the leap second table cannot be found, or *a cannot be represented in the valid NTP range).

int taia_from_ntp (struct taia *a, uint64 ntp)
Converts the NTP timestamp in ntp to a TAI64NA time in *a. The function returns 1 if it succeeds, or 0 (and sets errno) if an error occurs (for instance: the leap second table cannot be found).

Local time

The following functions convert time between an internal representation and a broken-down struct tm. The flag-tzisright flag is used in determining how the conversion should proceed. If flag-clockistai and flag-tzisright have the same value, everything is naturally converted as it should be. If flag-clockistai and flag-tzisright have different values, unholy magic happens here to get the correct broken-down time despite the timezone definition being wrong.

int localtm_from_tai (struct tm *tm, struct tai const *t, int lo)
Converts the TAI time in *t to broken-down GMT (if lo is zero) or local (if lo is nonzero) time in *tm. The function returns 1 if it succeeds, or 0 (and sets errno) if an error occurs (for instance: *t cannot be validly represented in a struct tm).

int localtm_from_utc (struct tm *tm, uint64 u, int lo)
Converts the UTC time in u to broken-down GMT (if lo is zero) or local (if lo is nonzero) time in *tm. The function returns 1 if it succeeds, or 0 (and sets errno) if an error occurs (for instance: u cannot be validly represented in a struct tm).

int localtm_from_sysclock (struct tm *tm, uint64 u, int lo)
Converts the time in u to broken-down GMT (if lo is zero) or local (if lo is nonzero) time in *tm. u will be interpreted as a TAI-10 value (if flag-clockistai is set) or as a UTC value (if flag-clockistai is clear). The function returns 1 if it succeeds, or 0 (and sets errno) if an error occurs (for instance: u cannot be validly represented in a struct tm).

int utc_from_localtm (uint64 *u, struct tm const *tm)
Converts the broken-down local time in *tm to an UTC value in *u. The function returns 1 if it succeeds, or 0 (and sets errno) if an error occurs.

int tai_from_localtm (struct tai *t, struct tm const *tm)
Converts the broken-down local time in *tm to a TAI value in *t. The function returns 1 if it succeeds, or 0 (and sets errno) if an error occurs.

int sysclock_from_localtm (uint64 *u, struct tm const *tm)
Converts the broken-down local time in *tm to a value in *u - either TAI-10 or UTC depending on your system clock. The function returns 1 if it succeeds, or 0 (and sets errno) if an error occurs.

The following functions use the localtmn_t type to hold both a broken-down time and a nanosecond count:

typedef struct localtmn_s localtmn_t, *localtmn_t_ref ;
struct localtmn_s
{
  struct tm tm ;
  unsigned long nano ;
} ;

The prototypes are self-explaining:

int localtmn_from_taia (localtmn_t_ref tmn, struct taia const *a, int lo) ;
int taia_from_localtmn (struct taia *a, localtmn_t const *tmn) ;
int localtmn_from_sysclock (localtmn_t_ref tmn, struct taia const *a, int lo) ;
int sysclock_from_localtmn (struct taia *a, localtmn_t const *tmn) ;

Leap second calculations

The leapsecs_* functions are used internally in the conversions between TAI and UTC. You should never use them manually.