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
|
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<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="//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="//skarnet.org/software/">Software</a><br />
<a href="//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 and tain</a> structures, and
<a href="https://cr.yp.to/libtai/tai64.html">TAI time</a>, from and to
other time formats and user-friendly representations.
</p>
<h2> Data structures </h2>
<ul>
<li> TAI time with 1-second precision is represented as a <a href="tai.html">tai</a>. </li>
<li> TAI time with more precision is represented as a <a href="tai.html">tain</a>. </li>
<li> UTC time is represented as an unsigned 64-bit integer
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</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_t *u, tai 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. If *<em>t</em> happens to hit a leap second, the function
returns 2 instead of 1.
</p>
<p>
<code> int tai_from_utc (tai *t, uint64_t 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.
</p>
<h3> NTP </h3>
<p>
<code> int ntp_from_tain (uint64_t *ntp, tain 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:
*<em>a</em> cannot be represented in the valid NTP range).
</p>
<p>
<code> int tain_from_ntp (tain *a, uint64_t 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.
</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 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). If *<em>t</em> happens to hit a leap second, the
value of <em>tm→tm_sec</em> is 60.
</p>
<p>
<code> int localtm_from_utc (struct tm *tm, uint64_t 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_t 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_t *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, 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_t *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</tt> type to hold both
a broken-down time and a nanosecond count:
</p>
<pre>typedef struct localtmn_s localtmn, *localtmn_ref ;
struct localtmn_s
{
struct tm tm ;
uint32_t nano ;
} ;
</pre>
<p>
The prototypes are self-explaining:
</p>
<p>
<code> int localtmn_from_tain (localtmn *tmn, tain const *a, int lo) ; <br />
int tain_from_localtmn (tain *a, localtmn const *tmn) ; <br />
int localtmn_from_sysclock (localtmn *tmn, tain const *a, int lo) ; <br />
int sysclock_from_localtmn (tain *a, localtmn const *tmn) ; </code> <br />
</p>
</body>
</html>
|
