djbtime.html (6571B)
1 <html> 2 <head> 3 <meta name="viewport" content="width=device-width, initial-scale=1.0" /> 4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 5 <meta http-equiv="Content-Language" content="en" /> 6 <title>skalibs: the djbtime library interface</title> 7 <meta name="Description" content="skalibs: the djbtime library interface" /> 8 <meta name="Keywords" content="skalibs c unix djbtime library libstddjb" /> 9 <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> 10 </head> 11 <body> 12 13 <p> 14 <a href="index.html">libstddjb</a><br /> 15 <a href="../libskarnet.html">skalibs</a><br /> 16 <a href="../index.html">skalibs</a><br /> 17 <a href="//skarnet.org/software/">Software</a><br /> 18 <a href="//skarnet.org/">skarnet.org</a> 19 </p> 20 21 <h1> The <tt>djbtime</tt> library interface </h1> 22 23 <p> 24 The following functions are declared in the <tt>skalibs/djbtime.h</tt> header, 25 and implemented in the <tt>libskarnet.a</tt> or <tt>libskarnet.so</tt> library. 26 </p> 27 28 <h2> General information </h2> 29 30 <p> 31 <tt>djbtime</tt> is a set of functions to convert 32 <a href="tai.html">tai and tain</a> structures, and 33 <a href="https://cr.yp.to/libtai/tai64.html">TAI time</a>, from and to 34 other time formats and user-friendly representations. 35 </p> 36 37 <h2> Data structures </h2> 38 39 <ul> 40 <li> TAI time with 1-second precision is represented as a <a href="tai.html">tai</a>. </li> 41 <li> TAI time with more precision is represented as a <a href="tai.html">tain</a>. </li> 42 <li> UTC time is represented as an unsigned 64-bit integer 43 equal to 2^62 added to the number of seconds since the Epoch. It's a trivial extension of 44 the standard 32-bit Unix time that will expire in 2038. </li> 45 <li> Broken-down GMT or local time with more than a 1-second precision is stored in a 46 <tt>localtmn</tt> structure, containing a <tt>struct tm</tt> <em>tm</em> 47 field and an unsigned long <em>nano</em> field. </li> 48 </ul> 49 50 <h2> Functions </h2> 51 52 <h3> UTC </h3> 53 54 <p> 55 <code> int utc_from_tai (uint64_t *u, tai const *t) </code> <br /> 56 Converts the absolute TAI64 time in *<em>t</em> to an UTC time, stored in 57 *<em>u</em> as an unsigned 64-bit integer. *<em>u</em> is actually 2^62 58 plus the number of seconds since the Epoch. 59 The function returns 1 if it succeeds, or 0 (and sets errno) if an 60 error occurs. If *<em>t</em> happens to hit a leap second, the function 61 returns 2 instead of 1. 62 </p> 63 64 <p> 65 <code> int tai_from_utc (tai *t, uint64_t u) </code> <br /> 66 Converts the UTC time in <em>u</em>, stored 67 as an unsigned 64-bit integer (2^62 plus the number of seconds since 68 the Epoch), to a TAI64 time in *<em>t</em>. 69 The function returns 1 if it succeeds, or 0 (and sets errno) if an 70 error occurs. 71 </p> 72 73 <h3> NTP </h3> 74 75 <p> 76 <code> int ntp_from_tain (uint64_t *ntp, tain const *a) </code> <br /> 77 Converts the absolute TAI64N time in *<em>a</em> to a 64-bit NTP timestamp, 78 stored in *<em>ntp</em>. The higher 32 bits of *<em>ntp</em> represent a number 79 of seconds ; the lower 32 bits are the fractional part of the timestamp. 80 The function returns 1 if it succeeds, or 0 (and sets errno) if an 81 error occurs (for instance: 82 *<em>a</em> cannot be represented in the valid NTP range). 83 </p> 84 85 <p> 86 <code> int tain_from_ntp (tain *a, uint64_t ntp) </code> <br /> 87 Converts the NTP timestamp in <em>ntp</em> to a TAI64N time in 88 *<em>a</em>. 89 The function returns 1 if it succeeds, or 0 (and sets errno) if an 90 error occurs. 91 </p> 92 93 <h3> Local time </h3> 94 95 <p> 96 The following functions convert time between an internal representation 97 and a broken-down <tt>struct tm</tt>. Conversions are performed to 98 get leap seconds handling right, depending on whether skalibs has been 99 configured for a TAI-10 or a UTC system clock, and on whether the current 100 timezone takes leap seconds into account or not. 101 </p> 102 103 <p> 104 <code> int localtm_from_tai (struct tm *tm, tai const *t, int lo) </code> <br /> 105 Converts the TAI time in *<em>t</em> to broken-down GMT (if 106 <em>lo</em> is zero) or local (if <em>lo</em> is nonzero) time in 107 *<em>tm</em>. 108 The function returns 1 if it succeeds, or 0 (and sets errno) if an 109 error occurs (for instance: *<em>t</em> cannot be validly represented 110 in a struct tm). If *<em>t</em> happens to hit a leap second, the 111 value of <em>tm→tm_sec</em> is 60. 112 </p> 113 114 <p> 115 <code> int localtm_from_utc (struct tm *tm, uint64_t u, int lo) </code> <br /> 116 Converts the UTC time in <em>u</em> to broken-down GMT (if 117 <em>lo</em> is zero) or local (if <em>lo</em> is nonzero) time in 118 *<em>tm</em>. 119 The function returns 1 if it succeeds, or 0 (and sets errno) if an 120 error occurs (for instance: <em>u</em> cannot be validly represented 121 in a struct tm). 122 </p> 123 124 <p> 125 <code> int localtm_from_sysclock (struct tm *tm, uint64_t u, int lo) </code> <br /> 126 Converts the time in <em>u</em> to broken-down GMT (if 127 <em>lo</em> is zero) or local (if <em>lo</em> is nonzero) time in 128 *<em>tm</em>. <em>u</em> will be interpreted as a TAI-10 value (with 129 <tt>--enable-tai-clock</tt>) or as a UTC value (without <tt>--enable-tai-clock</tt>). 130 The function returns 1 if it succeeds, or 0 (and sets errno) if an 131 error occurs (for instance: <em>u</em> cannot be validly represented 132 in a struct tm). 133 </p> 134 135 <p> 136 <code> int utc_from_localtm (uint64_t *u, struct tm const *tm) </code> <br /> 137 Converts the broken-down local time in *<em>tm</em> to an UTC value 138 in *<em>u</em>. 139 The function returns 1 if it succeeds, or 0 (and sets errno) if an 140 error occurs. 141 </p> 142 143 <p> 144 <code> int tai_from_localtm (tai *t, struct tm const *tm) </code> <br /> 145 Converts the broken-down local time in *<em>tm</em> to a TAI value 146 in *<em>t</em>. 147 The function returns 1 if it succeeds, or 0 (and sets errno) if an 148 error occurs. 149 </p> 150 151 <p> 152 <code> int sysclock_from_localtm (uint64_t *u, struct tm const *tm) </code> <br /> 153 Converts the broken-down local time in *<em>tm</em> to a value 154 in *<em>u</em> - either TAI-10 or UTC depending on your system clock. 155 The function returns 1 if it succeeds, or 0 (and sets errno) if an 156 error occurs. 157 </p> 158 159 <p> 160 The following functions use the <tt>localtmn</tt> type to hold both 161 a broken-down time and a nanosecond count: 162 </p> 163 164 <pre>typedef struct localtmn_s localtmn, *localtmn_ref ; 165 struct localtmn_s 166 { 167 struct tm tm ; 168 uint32_t nano ; 169 } ; 170 </pre> 171 172 <p> 173 The prototypes are self-explaining: 174 </p> 175 176 <p> 177 <code> int localtmn_from_tain (localtmn *tmn, tain const *a, int lo) ; <br /> 178 int tain_from_localtmn (tain *a, localtmn const *tmn) ; <br /> 179 int localtmn_from_sysclock (localtmn *tmn, tain const *a, int lo) ; <br /> 180 int sysclock_from_localtmn (tain *a, localtmn const *tmn) ; </code> <br /> 181 </p> 182 183 </body> 184 </html>