initial commit with rc for skalibs-2.0.0.0

author: Laurent Bercot <ska-skaware@skarnet.org> 2014-09-18 18:55:44 +0000
committer: Laurent Bercot <ska-skaware@skarnet.org> 2014-09-18 18:55:44 +0000
commit: 3534b428629be185e096be99e3bd5fdfe32d5544 (patch)
tree: 210ef3198ed66bc7f7b7bf6a85e4579f455e5a36 /doc/libstddjb/djbtime.html
download: skalibs-3534b428629be185e096be99e3bd5fdfe32d5544.tar.xz
1 files changed, 201 insertions, 0 deletions
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 @@
+<html>
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>skalibs: the djbtime library interface</title>
+    <meta name="Description" content="skalibs: the djbtime library interface" />
+    <meta name="Keywords" content="skalibs c unix djbtime library libstddjb" />
+    <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">libstddjb</a><br />
+<a href="../libskarnet.html">skalibs</a><br />
+<a href="../index.html">skalibs</a><br />
+<a href="http://skarnet.org/software/">Software</a><br />
+<a href="http://skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The <tt>djbtime</tt> library interface </h1>
+
+<p>
+ The following functions are declared in the <tt>skalibs/djbtime.h</tt> header,
+and implemented in the <tt>libskarnet.a</tt> or <tt>libskarnet.so</tt> library.
+</p>
+
+<h2> General information </h2>
+
+<p>
+ <tt>djbtime</tt> is a set of functions to convert
+<a href="tai.html">tai_t and tain_t</a> structures, and
+<a href="http://cr.yp.to/libtai/tai64.html">TAI time</a>, from and to
+other time formats and user-friendly representations.
+</p>
+
+<h2> The <tt>/etc/leapsecs.dat</tt> file </h2>
+
+<p>
+ 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
+<em>leap second table</em>. skalibs provides such a file in its
+<tt>src/etc/leapsecs.dat</tt> subdirectory, which is copied
+to <tt>/etc/leapsecs.dat</tt> at installation time (unless you specify
+a --prefix or --datadir option to configure).
+<strong>The <tt>/etc/leapsecs.dat</tt> file must remain accessible
+on your system, else time conversions will not be computed
+properly.</strong>
+</p>
+
+<h2> Data structures </h2>
+
+<ul>
+ <li> TAI time with 1-second precision is represented as a <a href="tai.html">tai_t</a>. </li>
+ <li> TAI time with more precision is represented as a <a href="tai.html">tain_t</a>. </li>
+ <li> UTC time is represented as an <a href="headers.html#uint64">unsigned 64-bit integer</a>
+equal to 2^62 added to the number of seconds since the Epoch. It's a trivial extension of
+the standard 32-bit Unix time that will expire in 2038. </li>
+ <li> Broken-down GMT or local time with more than a 1-second precision is stored in a
+<tt>localtmn_t</tt> structure, containing a <tt>struct tm</tt> <em>tm</em>
+field and an unsigned long <em>nano</em> field. </li>
+</ul>
+
+<h2> Functions </h2>
+
+<h3> UTC </h3>
+
+<p>
+<code> int utc_from_tai (uint64 *u, tai_t const *t) </code> <br />
+Converts the absolute TAI64 time in *<em>t</em> to an UTC time, stored in
+*<em>u</em> as an unsigned 64-bit integer. *<em>u</em> 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).
+</p>
+
+<p>
+<code> int tai_from_utc (tai_t *t, uint64 u) </code> <br />
+Converts the UTC time in <em>u</em>, stored
+as an unsigned 64-bit integer (2^62 plus the number of seconds since
+the Epoch), to a TAI64 time in *<em>t</em>.
+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).
+</p>
+
+<h3> NTP </h3>
+
+<p>
+<code> int ntp_from_tain (uint64 *ntp, tain_t const *a) </code> <br />
+Converts the absolute TAI64N time in *<em>a</em> to a 64-bit NTP timestamp,
+stored in *<em>ntp</em>. The higher 32 bits of *<em>ntp</em> 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
+*<em>a</em> cannot be represented in the valid NTP range).
+</p>
+
+<p>
+<code> int tain_from_ntp (tain_t *a, uint64 ntp) </code> <br />
+Converts the NTP timestamp in <em>ntp</em> to a TAI64N time in
+*<em>a</em>.
+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).
+</p>
+
+<h3> Local time </h3>
+
+<p>
+ The following functions convert time between an internal representation
+and a broken-down <tt>struct tm</tt>. The
+<a href="../flags.html#tzisright">--enable-right-tz</a> configure option is used in
+determining how the conversion should proceed. If the <tt>--enable-tai-clock</tt>
+and <tt>--enable-right-tz</tt> 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.
+</p>
+
+<p>
+<code> int localtm_from_tai (struct tm *tm, tai_t const *t, int lo) </code> <br />
+Converts the TAI time in *<em>t</em> to broken-down GMT (if
+<em>lo</em> is zero) or local (if <em>lo</em> is nonzero) time in
+*<em>tm</em>.
+The function returns 1 if it succeeds, or 0 (and sets errno) if an
+error occurs (for instance: *<em>t</em> cannot be validly represented
+in a struct tm).
+</p>
+
+<p>
+<code> int localtm_from_utc (struct tm *tm, uint64 u, int lo) </code> <br />
+Converts the UTC time in <em>u</em> to broken-down GMT (if
+<em>lo</em> is zero) or local (if <em>lo</em> is nonzero) time in
+*<em>tm</em>.
+The function returns 1 if it succeeds, or 0 (and sets errno) if an
+error occurs (for instance: <em>u</em> cannot be validly represented
+in a struct tm).
+</p>
+
+<p>
+<code> int localtm_from_sysclock (struct tm *tm, uint64 u, int lo) </code> <br />
+Converts the time in <em>u</em> to broken-down GMT (if
+<em>lo</em> is zero) or local (if <em>lo</em> is nonzero) time in
+*<em>tm</em>. <em>u</em> will be interpreted as a TAI-10 value (with
+<tt>--enable-tai-clock</tt>) or as a UTC value (without <tt>--enable-tai-clock</tt>).
+The function returns 1 if it succeeds, or 0 (and sets errno) if an
+error occurs (for instance: <em>u</em> cannot be validly represented
+in a struct tm).
+</p>
+
+<p>
+<code> int utc_from_localtm (uint64 *u, struct tm const *tm) </code> <br />
+Converts the broken-down local time in *<em>tm</em> to an UTC value
+in *<em>u</em>.
+The function returns 1 if it succeeds, or 0 (and sets errno) if an
+error occurs.
+</p>
+
+<p>
+<code> int tai_from_localtm (tai_t *t, struct tm const *tm) </code> <br />
+Converts the broken-down local time in *<em>tm</em> to a TAI value
+in *<em>t</em>.
+The function returns 1 if it succeeds, or 0 (and sets errno) if an
+error occurs.
+</p>
+
+<p>
+<code> int sysclock_from_localtm (uint64 *u, struct tm const *tm) </code> <br />
+Converts the broken-down local time in *<em>tm</em> to a value
+in *<em>u</em> - 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.
+</p>
+
+<p>
+ The following functions use the <tt>localtmn_t</tt> type to hold both
+a broken-down time and a nanosecond count:
+</p>
+
+<pre>typedef struct localtmn_s localtmn_t, *localtmn_t_ref ;
+struct localtmn_s
+{
+  struct tm tm ;
+  uint32 nano ;
+} ;
+</pre>
+
+<p>
+ The prototypes are self-explaining:
+</p>
+
+<p>
+<code> int localtmn_from_tain (localtmn_t_ref tmn, tain_t const *a, int lo) ; <br />
+int tain_from_localtmn (tain_t *a, localtmn_t const *tmn) ; <br />
+int localtmn_from_sysclock (localtmn_t_ref tmn, tain_t const *a, int lo) ; <br />
+int sysclock_from_localtmn (tain_t *a, localtmn_t const *tmn) ; </code> <br />
+</p>
+
+</body>
+</html>
author	Laurent Bercot <ska-skaware@skarnet.org>	2014-09-18 18:55:44 +0000
committer	Laurent Bercot <ska-skaware@skarnet.org>	2014-09-18 18:55:44 +0000
commit	3534b428629be185e096be99e3bd5fdfe32d5544 (patch)
tree	210ef3198ed66bc7f7b7bf6a85e4579f455e5a36 /doc/libstddjb/djbtime.html
download	skalibs-3534b428629be185e096be99e3bd5fdfe32d5544.tar.xz