summaryrefslogtreecommitdiff
path: root/doc/libstddjb/djbtime.html
blob: 417fa7d278cbe92332679173c5ff3176e1f7e16f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
<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>. Conversions are performed to
get leap seconds handling right, depending on whether skalibs has been
configured for a TAI-10 or a UTC system clock, and on whether the current
timezone takes leap seconds into account or not.
</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 *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 *tmn, tain_t const *a, int lo) ; <br />
int sysclock_from_localtmn (tain_t *a, localtmn_t const *tmn) ; </code> <br />
</p>

</body>
</html>