From 3534b428629be185e096be99e3bd5fdfe32d5544 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Thu, 18 Sep 2014 18:55:44 +0000 Subject: initial commit with rc for skalibs-2.0.0.0 --- doc/libstddjb/djbtime.html | 201 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 201 insertions(+) create mode 100644 doc/libstddjb/djbtime.html (limited to 'doc/libstddjb/djbtime.html') diff --git a/doc/libstddjb/djbtime.html b/doc/libstddjb/djbtime.html new file mode 100644 index 0000000..45876c8 --- /dev/null +++ b/doc/libstddjb/djbtime.html @@ -0,0 +1,201 @@ + + + + + skalibs: the djbtime library interface + + + + + + +

+libstddjb
+skalibs
+skalibs
+Software
+skarnet.org +

+ +

The djbtime library interface

+ +

+ The following functions are declared in the skalibs/djbtime.h header, +and implemented in the libskarnet.a or libskarnet.so library. +

+ +

General information

+ +

+ djbtime is a set of functions to convert +tai_t and tain_t 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 its +src/etc/leapsecs.dat subdirectory, which is copied +to /etc/leapsecs.dat at installation time (unless you specify +a --prefix or --datadir option to configure). +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, tai_t 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 (tai_t *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_tain (uint64 *ntp, tain_t const *a)
+Converts the absolute TAI64N 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 tain_from_ntp (tain_t *a, uint64 ntp)
+Converts the NTP timestamp in ntp to a TAI64N 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 +--enable-right-tz configure option is used in +determining how the conversion should proceed. If the --enable-tai-clock +and --enable-right-tz configure options have been both enabled +or both disabled, everything is naturally +converted as it should be. If only one of them has been enabled, +unholy magic happens here +to get the correct broken-down time despite the timezone definition being +wrong. +

+ +

+ int localtm_from_tai (struct tm *tm, tai_t 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 (with +--enable-tai-clock) or as a UTC value (without --enable-tai-clock). +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 (tai_t *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 ;
+  uint32 nano ;
+} ;
+
+ +

+ The prototypes are self-explaining: +

+ +

+ int localtmn_from_tain (localtmn_t_ref tmn, tain_t const *a, int lo) ;
+int tain_from_localtmn (tain_t *a, localtmn_t const *tmn) ;
+int localtmn_from_sysclock (localtmn_t_ref tmn, tain_t const *a, int lo) ;
+int sysclock_from_localtmn (tain_t *a, localtmn_t const *tmn) ;
+

+ + + -- cgit v1.2.3