MirOS Manual: exporttai(3), importtai(3), mjd2tai(3), mjd2tm(3), tai2mjd(3), tai2timet(3), tai2utc(3), taina_time(3), taitime(3), tai_isleap(3), tai_leaps(3), tai_time(3), timet2tai(3), tm2mjd(3), utc2tai(3)

TAITIME(3)                 BSD Programmer's Manual                  TAITIME(3)

NAME

     tai_leaps, tai_isleap, timet2tai, tai2timet, utc2tai, tai2utc, mjd2tai,
     tai2mjd, mjd2tm, tm2mjd, tai_time, taina_time, exporttai, importtai -
     year-2038-safe leap second compliant 64 bit time functions

SYNOPSIS

     #include <sys/types.h>
     #include <sys/taitime.h>

     tai64_t
     tai_time(tai64_t *t);

     void
     taina_time(tai64na_t *t);

     tai64_t *
     tai_leaps(void);

     int
     tai_isleap(tai64_t t);

     tai64_t
     timet2tai(time_t tv);

     time_t
     tai2timet(tai64_t t);

     tai64_t
     utc2tai(int64_t t);

     int64_t
     tai2utc(tai64_t t);

     tai64_t
     mjd2tai(mjd_t mjd);

     mjd_t
     tai2mjd(tai64_t t);

     struct tm
     mjd2tm(mjd_t mjd);

     mjd_t
     tm2mjd(struct tm tm);

     void
     exporttai(u_int8_t *dst, tai64na_t *src);

     void
     importtai(u_int8_t *src, tai64na_t *dst);

DESCRIPTION

     The tai_time() and taina_time() functions return the current time in the
     TAI64 format into the tai64_t or tai64na_t variable pointed to by the t
     argument, if the argument is not NULL. Additionally, tai_time() returns
     the value.

     The tai64_t and tai64na_t data types are specified further below.

     The tai_leaps() function returns a pointer, which is guaranteed to be not
     NULL, to a zero-terminated array of tai64_t values, each denoting a posi-
     tive leap second. DJB says, negative leap seconds are not likely to hap-
     pen; if they should, a new interface will be published. This function
     uses a table which should be initialised with tzset() beforehand if
     mechanisms such as chroot(2) are employed.

     The tai_isleap() function returns 1 if t is known to be a (positive) leap
     second, 0 if otherwise.

     The timet2tai() and tai2timet() routines convert their argument between
     the TAI64 format and the time_t data type which is generally used in time
     keeping, for example by the gettimeofday(2) system call. Generally speak-
     ing, a time_t counts the number of real seconds that have happened since
     January 1, 1970, 00:00:00 UTC (coordinated universal time).

     The utc2tai() and tai2utc() functions convert between the TAI64 format
     and an UTC value expressed as int64_t. The UTC value equals the time_t
     value as shown above, with the difference that not real seconds are
     counted, but seconds that would have happened if every full day had ex-
     actly 86400 seconds. Because there are leap seconds, in reality some days
     have 86401 and some 86399 seconds, that's why this format cannot be used
     for reliable time keeping (it is being used by the NTP protocol), but
     it's useful for conversion between calendar dates and second-counting
     dates. IEEE Std 1003.1 ("POSIX") compliant systems, unlike MirOS, force
     their time_t type and internal kernel time to be in this format, com-
     pletely ignoring the existence of leap seconds.

     The mjd2tai() and tai2mjd() functions convert between the TAI64 type and
     the MJD structure described further below, which keeps time in a calendar
     format.

     The mjd2tm() and tm2mjd() functions convert between the MJD structure and
     the more common struct tm as used by mktime(3). tm2mjd() converts the
     fields tm_sec, tm_min, tm_hour, tm_mday, tm_mon, tm_year, tm_gmtoff of
     struct tm; mjd2tm() fills the fields tm_sec, tm_min, tm_hour, tm_mday,
     tm_mon, tm_year, tm_wday, tm_yday with sensible values and tm_isdst,
     tm_gmtoff, tm_zone with null values.

     The exporttai() and importtai() functions convert between internal
     TAI64NA format and DJB-compatible on-the-wire TAI64NA/TAICLOCK format.
     See below for further documentation.

     The functions and data types described above are defined in the <time.h>
     header file. The data type tai64_t is aliased to int64_t. The data type
     tai64na_t includes the following fields:

                   tai64_t secs;           /* seconds (see below) */
                   uint32_t nano;          /* nanoseconds */
                   uint32_t atto;          /* attoseconds */

     The data type mjd_t includes the following fields:

                   time_t mjd;             /* day of modified julian calendar */
                   int32_t sec;            /* second within the day */

FILES

     /usr/share/zoneinfo             time zone information directory
     /usr/share/zoneinfo/UTC         default source of leap second information
     /usr/share/zoneinfo/posixrules  alternative source of leap second infor-
                                     mation, if UTC is absent.

SEE ALSO

     chroot(2), gettimeofday(2), mktime(3), ntpd(8), tzset(3)

STANDARDS

     This set of functions expects your operating system to not conform to
     IEEE Std 1003.1 ("POSIX") for correct time_t handling.

     The exported TAI64NA datatype and the TAI64 second offset have been stan-
     dardised by Dan J. Bernstein, see http://cr.yp.to/proto/utctai.html for a
     general overview of UTC, TAI and the NTP/POSIX problems,
     http://cr.yp.to/libtai/tai64.html for the various data types and
     http://cr.yp.to/proto/taiclock.txt for the specification of the on-wire
     TAICLOCK format, which contains the result of the exporttai() function in
     bytes 4 to 19.

HISTORY

     The TAI function suite appeared in MirOS #8.

AUTHORS

     The original author of the TAI64 data types and the libtai library for
     TAI64 manipulation, which was placed into public domain, is Dan J.
     Bernstein <djb@cr.yp.to>.

     The libc implementation of TAI64 functions are authored by
     Thorsten "mirabilos" Glaser <tg@mirbsd.org>.

CAVEATS

     The libc TAI functions have different function names and data types (ex-
     cept the exported TAI64NA on-the-wire format) than the DJB libtai ones.
     This allows one to use both libraries at the same time. The functions are
     exchangable, it is feasible to patch djb libtai to use this set of func-
     tions provided by libc internally.

     A tai64_t value is, in contrast to time_t, not zero-based, but has a bias
     of __TAI64_BIAS, which is implementation-defined to 0x4000000000000000ULL
     for the MirOS operating system. You will have to be extra carefully when
     adding values of type tai64_t or storing time values versus time dis-
     tances in variables.

BUGS

     The leap second table is read from the timezone information file. This
     has implications on the location of the file and its up-to-dateness.

     There is no method to select POSIX-conformant behaviour. It's probably
     better this way, though.

     Few sanitising of values is done, but the functions are considered safe.

MirOS BSD #10-current          February 7, 2007                              2

Generated on 2011-09-14 21:16:01 by $MirOS: src/scripts/roff2htm,v 1.67 2011/09/14 21:08:34 tg Exp $

These manual pages and other documentation are copyrighted by their respective writers; their source is available at our CVSweb, AnonCVS, and other mirrors. The rest is Copyright © 2002‒2011 The MirOS Project, Germany.
This product includes material provided by Thorsten Glaser.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report – diffs preferred.