From 1c032ec5855551c44b88f94fc35fa87db4279f0a Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Fri, 9 Jan 2015 01:00:59 +0000 Subject: tai conversion functions overhaul. API change -> rc for 2.2.0.0 Doc updated. --- doc/libstddjb/tai.html | 107 ++++++++++++++++++++++++++++++++++++------------- 1 file changed, 79 insertions(+), 28 deletions(-) (limited to 'doc/libstddjb/tai.html') diff --git a/doc/libstddjb/tai.html b/doc/libstddjb/tai.html index 3617959..0b1be3c 100644 --- a/doc/libstddjb/tai.html +++ b/doc/libstddjb/tai.html @@ -178,7 +178,7 @@ has been configured with (resp. without) the --enable-clock option. Returns 1 if it succeeds or 0 (and sets errno) if it fails. - Here a contains a valid TAI stamp, no matter what the + Here a contains a valid TAI64N stamp, no matter what the system clock is set to: arithmetic operations can be performed on it.

@@ -190,7 +190,7 @@ Sets the current time to *a, with a 1-nanosecond with (resp. without) the --enable-clock option. Returns 1 if it succeeds or 0 (and sets errno) if it -fails. a must contain a valid TAI stamp; proper +fails. a must contain a valid TAI64N stamp; proper operations will be automatically run to convert that stamp into the right format for the system clock.

@@ -273,43 +273,92 @@ computations.

Converting to/from libc representations

- int tai_from_timeval (tai_t *t, struct timeval const *tv)
-int tai_from_timespec (tai_t *t, struct timespec const *ts)
-int tai_relative_from_timeval (tai_t *t, struct timeval const *tv)
-int tai_relative_from_timespec (tai_t *t, struct timespec const *ts)
+ The following functions only convert from a certain structure +format to another; they do not make any assumption about the +format of the time contained in those structures. For instance, +for the tai_from_timeval function, if the struct timeval +contains an absolute UTC time, then the tai_t will also contain +the same UTC time. Despite being a tai_t, it may contain +something else than TAI time. +

+ +

+If you need conversion from the native machine +system clock format to TAI, see the next section. +

+ +

+ int tai_from_time (tai_t *t, time_t u)
+int tai_relative_from_time (tai_t *t, time_t u)
Those functions convert an absolute (resp. relative) time in a -struct timeval (resp. struct timespec) to an absolute (resp. relative) -time in a tai_t, with a 1-second precision. They return 1. +time_t to an absolute (resp. relative) +time in a tai_t, with a 1-second precision. They return 1, +unless the time_t value is invalid (in which case they return 0).

- int timeval_from_tai (struct timeval *tv, tai_t const *t)
-int timespec_from_tai (struct timespec *ts, tai_t const *t)
-int timeval_from_tai_relative (struct timeval *tv, tai_t const *t)
-int timespec_from_tai_relative (struct timespec *ts, tai_t const *t)
-Those functions do the opposite conversion. They normally return 1; -however, struct timeval and struct timespec cannot -represent an absolute date before the Epoch, or a negative relative time; -if *t cannot be converted, 0 EINVAL is returned. + int time_from_tai (time_t *u, tai_t const *t)
+int time_from_tai_relative (time_t *u, tai_t const *t)
+The inverse functions of the previous ones. Be aware that +time_t is 32 bits on some systems and cannot store all values +of a tai_t (in which case the functions will return 0 EOVERFLOW).

int tain_from_timeval (tain_t *a, struct timeval const *tv)
-int tain_from_timespec (tain_t *a, struct timespec const *ts)
int tain_relative_from_timeval (tain_t *a, struct timeval const *tv)
+int tain_from_timespec (tain_t *a, struct timespec const *ts)
int tain_relative_from_timespec (tain_t *a, struct timespec const *ts)
int timeval_from_tain (struct timeval *tv, tain_t const *a)
-int timespec_from_tain (struct timespec *ts, tain_t const *a)
int timeval_from_tain_relative (struct timeval *tv, tain_t const *a)
+int timespec_from_tain (struct timespec *ts, tain_t const *a)
int timespec_from_tain_relative (struct timespec *ts, tain_t const *a)
-Same conversion operations, but with a tain_t. The 1-microsecond +Same conversion operations, between tain_t and a +struct timeval or struct timespec. The 1-microsecond (for struct timeval) or 1-nanosecond (for struct timespec) precision is preserved.

+

Conversion between TAI and the system clock format

+ +

+ Unlike the previous functions, the functions listed here will +always operate on valid absolute timestamps. Only TAI64 time is +stored in tai_t structures, and only TAI64N time is stored in +tain_t structures. These functions will convert to/from TAI, +from/to the machine system clock format, i.e. TAI-10 or UTC +depending on whether skalibs was +compiled with the --enable-tai-clock configure option). +This is useful to get valid TAI/TAI64N timestamps out of +information exported by the system, for instance the time_t +returned by time(), +or in the st_atim, st_mtim or +st_ctim fields of a struct stat. +

+ +

+ The functions return 1 in case of success, or 0 if the conversion +could not be performed; in which case errno is set to EINVAL if +the input argument was not a valid timestamp, to EOVERFLOW if the +output could not be represented in the chosen format (which may +happen on systems with a 32 bit time_t), or other error +codes - for instance related to the leap second table when a +lookup was necessary. +

+ + int tai_from_time_sysclock (tai_t *a, time_t t)
+int time_sysclock_from_tai (time_t *t, tai_t const *a)
+int tain_from_timeval_sysclock (tain_t *a, struct timeval const *tv)
+int timeval_sysclock_from_tain (struct timeval *tv, tain_t const *a)
+int timespec_sysclock_from_tain (struct timespec *ts, tain_t const *a) + +

Conversions to/from basic types

+

- void tain_uint (tain_t *a, unsigned int c)
+ int tain_uint (tain_t *a, unsigned int c)
Stores a relative time of c seconds into a. +Normally returns 1, but may return 0 EINVAL on pathological numbers.

@@ -330,26 +379,28 @@ number. Else it returns -1 EINVAL.

Time computations

- void tai_add (tai_t *t, tai_t const *t1, tai_t const *t2)
+ int tai_add (tai_t *t, tai_t const *t1, tai_t const *t2)
Stores *t1 + *t2 into t. Of course, *t1 and *t2 must not both represent absolute times. +The function normally returns 1, but will return 0 on bad inputs.

- void tai_sub (tai_t *t, tai_t const *t1, tai_t const *t2)
-Stores *t1 - *t2 into t. Of course, *t1 -and *t2 must be of the same type (relative or absolute), and -*t will always be relative. + int tai_sub (tai_t *t, tai_t const *t1, tai_t const *t2)
+Stores *t1 - *t2 into t. *t1 cannot +be relative if *t2 is absolute. If they are both relative or +both absolute, then *t is relative, else it's absolute. +The function normally returns 1, but will return 0 on bad inputs.

- void tain_add (tain_t *a, tain_t const *a1, tain_t const *a2)
-void tain_sub (tain_t *a, tain_t const *a1, tain_t const *a2)
+ int tain_add (tain_t *a, tain_t const *a1, tain_t const *a2)
+int tain_sub (tain_t *a, tain_t const *a1, tain_t const *a2)
Same thing with tain_t.

- void tain_addsec (tain_t *a, tain_t const *a1, int c)
+ int tain_addsec (tain_t *a, tain_t const *a1, int c)
Adds c seconds to *a1 and stores the result into a. c may be negative.

-- cgit v1.3.1