| @@ -1,321 +1,332 @@ | | | @@ -1,321 +1,332 @@ |
1 | .\" $NetBSD: ctime.3,v 1.32 2010/05/15 13:54:52 pgoyette Exp $ | | 1 | .\" $NetBSD: ctime.3,v 1.33 2010/10/27 19:16:04 christos Exp $ |
2 | .Dd February 2, 2010 | | 2 | .Dd October 27, 2010 |
3 | .Dt CTIME 3 | | 3 | .Dt CTIME 3 |
4 | .Os | | 4 | .Os |
5 | .Sh NAME | | 5 | .Sh NAME |
6 | .Nm asctime , | | 6 | .Nm asctime , |
7 | .Nm asctime_r , | | 7 | .Nm asctime_r , |
8 | .Nm ctime , | | 8 | .Nm ctime , |
9 | .Nm ctime_r , | | 9 | .Nm ctime_r , |
10 | .Nm difftime , | | 10 | .Nm difftime , |
11 | .Nm gmtime , | | 11 | .Nm gmtime , |
12 | .Nm gmtime_r , | | 12 | .Nm gmtime_r , |
13 | .Nm localtime , | | 13 | .Nm localtime , |
14 | .Nm localtime_r , | | 14 | .Nm localtime_r , |
15 | .Nm mktime | | 15 | .Nm mktime |
16 | .Nd convert date and time to ASCII | | 16 | .Nd convert date and time to ASCII |
17 | .Sh LIBRARY | | 17 | .Sh LIBRARY |
18 | .Lb libc | | 18 | .Lb libc |
19 | .Sh SYNOPSIS | | 19 | .Sh SYNOPSIS |
20 | .In time.h | | 20 | .In time.h |
21 | .Dv extern char *tzname[2]; | | 21 | .Dv extern char *tzname[2]; |
22 | .Ft char * | | 22 | .Ft char * |
23 | .Fn ctime "const time_t *clock" | | 23 | .Fn ctime "const time_t *clock" |
24 | .Ft char * | | 24 | .Ft char * |
25 | .Fn ctime_r "const time_t *clock" "char *buf" | | 25 | .Fn ctime_r "const time_t *clock" "char *buf" |
26 | .Ft double | | 26 | .Ft double |
27 | .Fn difftime "time_t time1" "time_t time0" | | 27 | .Fn difftime "time_t time1" "time_t time0" |
28 | .Ft char * | | 28 | .Ft char * |
29 | .Fn asctime "const struct tm *tm" | | 29 | .Fn asctime "const struct tm *tm" |
30 | .Ft char * | | 30 | .Ft char * |
31 | .Fn asctime_r "const struct tm restrict tm" "char * restrict buf" | | 31 | .Fn asctime_r "const struct tm restrict tm" "char * restrict buf" |
32 | .Ft struct tm * | | 32 | .Ft struct tm * |
33 | .Fn localtime "const time_t *clock" | | 33 | .Fn localtime "const time_t *clock" |
34 | .Ft struct tm * | | 34 | .Ft struct tm * |
35 | .Fn localtime_r "const time_t * restrict clock" "struct tm * restrict result" | | 35 | .Fn localtime_r "const time_t * restrict clock" "struct tm * restrict result" |
36 | .Ft struct tm * | | 36 | .Ft struct tm * |
37 | .Fn gmtime "const time_t *clock" | | 37 | .Fn gmtime "const time_t *clock" |
38 | .Ft struct tm * | | 38 | .Ft struct tm * |
39 | .Fn gmtime_r "const time_t * restrict clock" "struct tm * restrict result" | | 39 | .Fn gmtime_r "const time_t * restrict clock" "struct tm * restrict result" |
40 | .Ft time_t | | 40 | .Ft time_t |
41 | .Fn mktime "struct tm *tm" | | 41 | .Fn mktime "struct tm *tm" |
42 | .Sh DESCRIPTION | | 42 | .Sh DESCRIPTION |
43 | .Fn ctime | | 43 | .Fn ctime |
44 | converts a long integer, pointed to by | | 44 | converts a |
| | | 45 | .Tp time_t , |
| | | 46 | pointed to by |
45 | .Fa clock , | | 47 | .Fa clock , |
46 | representing the time in seconds since | | 48 | representing the time in seconds since |
47 | 00:00:00 UTC, 1970-01-01, | | 49 | 00:00:00 UTC, 1970-01-01, |
48 | and returns a pointer to a | | 50 | and returns a pointer to a |
49 | string of the form | | 51 | string of the form |
50 | .D1 Thu Nov 24 18:22:48 1986\en\e0 | | 52 | .D1 Thu Nov 24 18:22:48 1986\en\e0 |
51 | Years requiring fewer than four characters are padded with leading zeroes. | | 53 | Years requiring fewer than four characters are padded with leading zeroes. |
52 | For years longer than four characters, the string is of the form | | 54 | For years longer than four characters, the string is of the form |
53 | .D1 Thu Nov 24 18:22:48 81986\en\e0 | | 55 | .D1 Thu Nov 24 18:22:48 81986\en\e0 |
54 | with five spaces before the year. | | 56 | with five spaces before the year. |
55 | These unusual formats are designed to make it less likely that older | | 57 | These unusual formats are designed to make it less likely that older |
56 | software that expects exactly 26 bytes of output will mistakenly output | | 58 | software that expects exactly 26 bytes of output will mistakenly output |
57 | misleading values for out-of-range years. | | 59 | misleading values for out-of-range years. |
58 | .Pp | | 60 | .Pp |
59 | .Fn Localtime | | 61 | .Fn ctime_r |
| | | 62 | is similar to |
| | | 63 | .Fn ctime , |
| | | 64 | except it places the result of the convertion on the |
| | | 65 | .Fa buf |
| | | 66 | argument which should be 26 or more bytes long, instead of using a global |
| | | 67 | static buffer. |
| | | 68 | .Pp |
| | | 69 | .Fn localtime |
60 | and | | 70 | and |
61 | .Fn gmtime | | 71 | .Fn gmtime |
62 | return pointers to | | 72 | return pointers to |
63 | .Va tm | | 73 | .Va tm |
64 | structures, described below. | | 74 | structures, described below. |
65 | .Fn localtime | | 75 | .Fn localtime |
66 | corrects for the time zone and any time zone adjustments | | 76 | corrects for the time zone and any time zone adjustments |
67 | (such as Daylight Saving Time in the U.S.A.). | | 77 | (such as Daylight Saving Time in the U.S.A.). |
68 | After filling in the | | 78 | After filling in the |
69 | .Va tm | | 79 | .Va tm |
70 | structure, | | 80 | structure, |
71 | .Fn localtime | | 81 | .Fn localtime |
72 | sets the | | 82 | sets the |
73 | .Fa tm_isdst Ns 'th | | 83 | .Fa tm_isdst Ns 'th |
74 | element of | | 84 | element of |
75 | .Fa tzname | | 85 | .Fa tzname |
76 | to a pointer to an | | 86 | to a pointer to an |
77 | ASCII string that's the time zone abbreviation to be used with | | 87 | ASCII string that's the time zone abbreviation to be used with |
78 | .Fn localtime Ns 's | | 88 | .Fn localtime Ns 's |
79 | return value. | | 89 | return value. |
80 | .Pp | | 90 | .Pp |
81 | .Fn gmtime | | 91 | .Fn gmtime |
82 | converts to Coordinated Universal Time. | | 92 | converts to Coordinated Universal Time. |
83 | .Pp | | 93 | .Pp |
84 | The | | 94 | The |
85 | .Fn gmtime_r | | 95 | .Fn gmtime_r |
86 | and | | 96 | and |
87 | .Fn localtime_r | | 97 | .Fn localtime_r |
88 | functions provide the same functionality as | | 98 | functions provide the same functionality as |
89 | .Fn gmtime | | 99 | .Fn gmtime |
90 | and | | 100 | and |
91 | .Fn localtime | | 101 | .Fn localtime |
92 | differing in that the caller must supply a buffer area | | 102 | differing in that the caller must supply a buffer area |
93 | .Fa result | | 103 | .Fa result |
94 | in which the result is stored; also, | | 104 | in which the result is stored; also, |
95 | .Fn localtime_r | | 105 | .Fn localtime_r |
96 | does not imply initialization of the local time conversion information; | | 106 | does not imply initialization of the local time conversion information; |
97 | the application may need to do so by calling | | 107 | the application may need to do so by calling |
98 | .Xr tzset 3 . | | 108 | .Xr tzset 3 . |
99 | .Pp | | 109 | .Pp |
100 | .Fn asctime | | 110 | .Fn asctime |
101 | converts a time value contained in a | | 111 | converts a time value contained in a |
102 | ``tm'' structure to a string, | | 112 | .Dq tm |
| | | 113 | structure to a string, |
103 | as shown in the above example, | | 114 | as shown in the above example, |
104 | and returns a pointer to the string. | | 115 | and returns a pointer to the string. |
105 | .Pp | | 116 | .Pp |
106 | .Fn mktime | | 117 | .Fn mktime |
107 | converts the broken-down time, | | 118 | converts the broken-down time, |
108 | expressed as local time, | | 119 | expressed as local time, |
109 | in the structure pointed to by | | 120 | in the structure pointed to by |
110 | .Fa tm | | 121 | .Fa tm |
111 | into a calendar time value with the same encoding as that of the values | | 122 | into a calendar time value with the same encoding as that of the values |
112 | returned by the | | 123 | returned by the |
113 | .Xr time 3 | | 124 | .Xr time 3 |
114 | function. | | 125 | function. |
115 | The original values of the | | 126 | The original values of the |
116 | .Fa tm_wday | | 127 | .Fa tm_wday |
117 | and | | 128 | and |
118 | .Fa tm_yday | | 129 | .Fa tm_yday |
119 | components of the structure are ignored, | | 130 | components of the structure are ignored, |
120 | and the original values of the other components are not restricted | | 131 | and the original values of the other components are not restricted |
121 | to their normal ranges. | | 132 | to their normal ranges. |
122 | (A positive or zero value for | | 133 | (A positive or zero value for |
123 | .Fa tm_isdst | | 134 | .Fa tm_isdst |
124 | causes | | 135 | causes |
125 | .Fn mktime | | 136 | .Fn mktime |
126 | to presume initially that summer time (for example, Daylight Saving Time | | 137 | to presume initially that summer time (for example, Daylight Saving Time |
127 | in the U.S.A.) respectively, | | 138 | in the U.S.A.) respectively, |
128 | is or is not in effect for the specified time. | | 139 | is or is not in effect for the specified time. |
129 | A negative value for | | 140 | A negative value for |
130 | .Fa tm_isdst | | 141 | .Fa tm_isdst |
131 | causes the | | 142 | causes the |
132 | .Fn mktime | | 143 | .Fn mktime |
133 | function to attempt to divine whether summer time is in effect | | 144 | function to attempt to divine whether summer time is in effect |
134 | for the specified time; in this case it does not use a consistent | | 145 | for the specified time; in this case it does not use a consistent |
135 | rule and may give a different answer when later | | 146 | rule and may give a different answer when later |
136 | presented with the same argument.) | | 147 | presented with the same argument.) |
137 | On successful completion, the values of the | | 148 | On successful completion, the values of the |
138 | .Fa tm_wday | | 149 | .Fa tm_wday |
139 | and | | 150 | and |
140 | .Fa tm_yday | | 151 | .Fa tm_yday |
141 | components of the structure are set appropriately, | | 152 | components of the structure are set appropriately, |
142 | and the other components are set to represent the specified calendar time, | | 153 | and the other components are set to represent the specified calendar time, |
143 | but with their values forced to their normal ranges; the final value of | | 154 | but with their values forced to their normal ranges; the final value of |
144 | .Fa tm_mday | | 155 | .Fa tm_mday |
145 | is not set until | | 156 | is not set until |
146 | .Fa tm_mon | | 157 | .Fa tm_mon |
147 | and | | 158 | and |
148 | .Fa tm_year | | 159 | .Fa tm_year |
149 | are determined. | | 160 | are determined. |
150 | .Fn mktime | | 161 | .Fn mktime |
151 | returns the specified calendar time; if the calendar time cannot be | | 162 | returns the specified calendar time; if the calendar time cannot be |
152 | represented, it returns | | 163 | represented, it returns |
153 | .Va "(time_t)-1" . | | 164 | .Va "(time_t)-1" . |
154 | .Pp | | 165 | .Pp |
155 | .Fn difftime | | 166 | .Fn difftime |
156 | returns the difference between two calendar times, | | 167 | returns the difference between two calendar times, |
157 | .Fa ( time1 No - Fa time0 ) , | | 168 | .Fa ( time1 No - Fa time0 ) , |
158 | expressed in seconds. | | 169 | expressed in seconds. |
159 | .Pp | | 170 | .Pp |
160 | The structure (of type) | | 171 | The structure (of type) |
161 | .Va "struct tm" | | 172 | .Va "struct tm" |
162 | includes the following fields: | | 173 | includes the following fields: |
163 | .Bd -literal -offset indent | | 174 | .Bd -literal -offset indent |
164 | int tm_sec; /* seconds after the minute [0,61] */ | | 175 | int tm_sec; /* seconds after the minute [0,61] */ |
165 | int tm_min; /* minutes after the hour [0,59] */ | | 176 | int tm_min; /* minutes after the hour [0,59] */ |
166 | int tm_hour; /* hours since midnight [0,23] */ | | 177 | int tm_hour; /* hours since midnight [0,23] */ |
167 | int tm_mday; /* day of the month [1,31] */ | | 178 | int tm_mday; /* day of the month [1,31] */ |
168 | int tm_mon; /* months since January [0,11] */ | | 179 | int tm_mon; /* months since January [0,11] */ |
169 | int tm_year; /* years since 1900 */ | | 180 | int tm_year; /* years since 1900 */ |
170 | int tm_wday; /* day of week [0,6] (Sunday = 0) */ | | 181 | int tm_wday; /* day of week [0,6] (Sunday = 0) */ |
171 | int tm_yday; /* day of year [0,365] (Jan 1 = 0) */ | | 182 | int tm_yday; /* day of year [0,365] (Jan 1 = 0) */ |
172 | int tm_isdst; /* daylight savings flag */ | | 183 | int tm_isdst; /* daylight savings flag */ |
173 | long tm_gmtoff; /* offset from UTC in seconds */ | | 184 | long tm_gmtoff; /* offset from UTC in seconds */ |
174 | char *tm_zone; /* abbreviation of timezone name */ | | 185 | char *tm_zone; /* abbreviation of timezone name */ |
175 | .Ed | | 186 | .Ed |
176 | .Pp | | 187 | .Pp |
177 | The | | 188 | The |
178 | .Fa tm_zone | | 189 | .Fa tm_zone |
179 | and | | 190 | and |
180 | .Fa tm_gmtoff | | 191 | .Fa tm_gmtoff |
181 | fields exist, and are filled in, only if arrangements to do | | 192 | fields exist, and are filled in, only if arrangements to do |
182 | so were made when the library containing these functions was | | 193 | so were made when the library containing these functions was |
183 | created. | | 194 | created. |
184 | There is no guarantee that these fields will continue to exist | | 195 | There is no guarantee that these fields will continue to exist |
185 | in this form in future releases of this code. | | 196 | in this form in future releases of this code. |
186 | .Pp | | 197 | .Pp |
187 | .Fa tm_isdst | | 198 | .Fa tm_isdst |
188 | is non-zero if summer time is in effect. | | 199 | is non-zero if summer time is in effect. |
189 | .Pp | | 200 | .Pp |
190 | .Fa tm_gmtoff | | 201 | .Fa tm_gmtoff |
191 | is the offset (in seconds) of the time represented | | 202 | is the offset (in seconds) of the time represented |
192 | from UTC, with positive values indicating east | | 203 | from UTC, with positive values indicating east |
193 | of the Prime Meridian. | | 204 | of the Prime Meridian. |
194 | .Sh RETURN VALUES | | 205 | .Sh RETURN VALUES |
195 | On success the | | 206 | On success the |
196 | .Fn asctime | | 207 | .Fn asctime |
197 | and | | 208 | and |
198 | .Fn ctime | | 209 | .Fn ctime |
199 | functions return a pointer to a static character buffer, and the | | 210 | functions return a pointer to a static character buffer, and the |
200 | .Fn asctime_r | | 211 | .Fn asctime_r |
201 | and | | 212 | and |
202 | .Fn ctime_r | | 213 | .Fn ctime_r |
203 | function return a pointer to the user-supplied buffer. | | 214 | function return a pointer to the user-supplied buffer. |
204 | On failure they all return | | 215 | On failure they all return |
205 | .Dv NULL | | 216 | .Dv NULL |
206 | and no errors are defined for them. | | 217 | and no errors are defined for them. |
207 | On success the | | 218 | On success the |
208 | .Fn gmtime , | | 219 | .Fn gmtime , |
209 | and | | 220 | and |
210 | .Fn localtime | | 221 | .Fn localtime |
211 | functions return a pointer to a statically allocated | | 222 | functions return a pointer to a statically allocated |
212 | .Va "struct tm" | | 223 | .Va "struct tm" |
213 | whereas the | | 224 | whereas the |
214 | .Fn gmtime_r | | 225 | .Fn gmtime_r |
215 | and | | 226 | and |
216 | .Fn localtime_r | | 227 | .Fn localtime_r |
217 | functions return a pointer to the user-supplied | | 228 | functions return a pointer to the user-supplied |
218 | .Va "struct tm" . | | 229 | .Va "struct tm" . |
219 | On failure they all return | | 230 | On failure they all return |
220 | .Dv NULL | | 231 | .Dv NULL |
221 | and the global variable | | 232 | and the global variable |
222 | .Va errno | | 233 | .Va errno |
223 | is set to indicate the error. | | 234 | is set to indicate the error. |
224 | The | | 235 | The |
225 | .Fn mktime | | 236 | .Fn mktime |
226 | function returns the specified time since the Epoch as a | | 237 | function returns the specified time since the Epoch as a |
227 | .Va time_t | | 238 | .Va time_t |
228 | type value. | | 239 | type value. |
229 | If the time cannot be represented, then | | 240 | If the time cannot be represented, then |
230 | .Fn mktime | | 241 | .Fn mktime |
231 | returns | | 242 | returns |
232 | .Va "(time_t)-1" | | 243 | .Va "(time_t)-1" |
233 | setting the global variable | | 244 | setting the global variable |
234 | .Va errno | | 245 | .Va errno |
235 | to indicate the error. | | 246 | to indicate the error. |
236 | .Sh FILES | | 247 | .Sh FILES |
237 | .Bl -tag -width /usr/share/zoneinfo/posixrules -compact | | 248 | .Bl -tag -width /usr/share/zoneinfo/posixrules -compact |
238 | .It Pa /etc/localtime | | 249 | .It Pa /etc/localtime |
239 | local time zone file | | 250 | local time zone file |
240 | .It Pa /usr/share/zoneinfo | | 251 | .It Pa /usr/share/zoneinfo |
241 | time zone information directory | | 252 | time zone information directory |
242 | .It Pa /usr/share/zoneinfo/posixrules | | 253 | .It Pa /usr/share/zoneinfo/posixrules |
243 | used with POSIX-style TZ's | | 254 | used with POSIX-style TZ's |
244 | .It Pa /usr/share/zoneinfo/GMT | | 255 | .It Pa /usr/share/zoneinfo/GMT |
245 | for UTC leap seconds | | 256 | for UTC leap seconds |
246 | .El | | 257 | .El |
247 | .Pp | | 258 | .Pp |
248 | If | | 259 | If |
249 | .Pa /usr/share/zoneinfo/GMT | | 260 | .Pa /usr/share/zoneinfo/GMT |
250 | is absent, UTC leap seconds are loaded from | | 261 | is absent, UTC leap seconds are loaded from |
251 | .Pa /usr/share/zoneinfo/posixrules . | | 262 | .Pa /usr/share/zoneinfo/posixrules . |
252 | .Sh ERRORS | | 263 | .Sh ERRORS |
253 | The | | 264 | The |
254 | .Fn gmtime_r , | | 265 | .Fn gmtime_r , |
255 | .Fn localtime_r , | | 266 | .Fn localtime_r , |
256 | .Fn gmtime , | | 267 | .Fn gmtime , |
257 | .Fn localtime , | | 268 | .Fn localtime , |
258 | and | | 269 | and |
259 | .Fn mktime | | 270 | .Fn mktime |
260 | will fail when: | | 271 | will fail when: |
261 | .Bl -tag -width Er | | 272 | .Bl -tag -width Er |
262 | .It Bq Er EOVERFLOW | | 273 | .It Bq Er EOVERFLOW |
263 | The result cannot be represented. | | 274 | The result cannot be represented. |
264 | .El | | 275 | .El |
265 | .Sh SEE ALSO | | 276 | .Sh SEE ALSO |
266 | .Xr getenv 3 , | | 277 | .Xr getenv 3 , |
267 | .Xr strftime 3 , | | 278 | .Xr strftime 3 , |
268 | .Xr time 3 , | | 279 | .Xr time 3 , |
269 | .Xr tzset 3 , | | 280 | .Xr tzset 3 , |
270 | .Xr tzfile 5 | | 281 | .Xr tzfile 5 |
271 | .Sh STANDARDS | | 282 | .Sh STANDARDS |
272 | The | | 283 | The |
273 | .Fn ctime , | | 284 | .Fn ctime , |
274 | .Fn difftime , | | 285 | .Fn difftime , |
275 | .Fn asctime , | | 286 | .Fn asctime , |
276 | .Fn localtime , | | 287 | .Fn localtime , |
277 | .Fn gmtime | | 288 | .Fn gmtime |
278 | and | | 289 | and |
279 | .Fn mktime | | 290 | .Fn mktime |
280 | functions conform to | | 291 | functions conform to |
281 | .St -ansiC | | 292 | .St -ansiC |
282 | The | | 293 | The |
283 | .Fn ctime_r , | | 294 | .Fn ctime_r , |
284 | .Fn asctime_r , | | 295 | .Fn asctime_r , |
285 | .Fn localtime_r | | 296 | .Fn localtime_r |
286 | and | | 297 | and |
287 | .Fn gmtime_r | | 298 | .Fn gmtime_r |
288 | functions conform to | | 299 | functions conform to |
289 | .St -p1003.1c-95 . | | 300 | .St -p1003.1c-95 . |
290 | .Sh NOTES | | 301 | .Sh NOTES |
291 | The return values point to static data; the data is overwritten by | | 302 | The return values point to static data; the data is overwritten by |
292 | each call. | | 303 | each call. |
293 | The | | 304 | The |
294 | .Fa tm_zone | | 305 | .Fa tm_zone |
295 | field of a returned | | 306 | field of a returned |
296 | .Va "struct tm" | | 307 | .Va "struct tm" |
297 | points to a static array of characters, which | | 308 | points to a static array of characters, which |
298 | will also be overwritten at the next call | | 309 | will also be overwritten at the next call |
299 | (and by calls to | | 310 | (and by calls to |
300 | .Xr tzset 3 ) . | | 311 | .Xr tzset 3 ) . |
301 | .Pp | | 312 | .Pp |
302 | .Fn asctime | | 313 | .Fn asctime |
303 | and | | 314 | and |
304 | .Fn ctime | | 315 | .Fn ctime |
305 | behave strangely for years before 1000 or after 9999. | | 316 | behave strangely for years before 1000 or after 9999. |
306 | The 1989 and 1999 editions of the C Standard say | | 317 | The 1989 and 1999 editions of the C Standard say |
307 | that years from \-99 through 999 are converted without | | 318 | that years from \-99 through 999 are converted without |
308 | extra spaces, but this conflicts with longstanding | | 319 | extra spaces, but this conflicts with longstanding |
309 | tradition and with this implementation. | | 320 | tradition and with this implementation. |
310 | Traditional implementations of these two functions are | | 321 | Traditional implementations of these two functions are |
311 | restricted to years in the range 1900 through 2099. | | 322 | restricted to years in the range 1900 through 2099. |
312 | To avoid this portability mess, new programs should use | | 323 | To avoid this portability mess, new programs should use |
313 | .Fn strftime | | 324 | .Fn strftime |
314 | instead. | | 325 | instead. |
315 | .Pp | | 326 | .Pp |
316 | Avoid using out-of-range values with | | 327 | Avoid using out-of-range values with |
317 | .Fn mktime | | 328 | .Fn mktime |
318 | when setting up lunch with promptness sticklers in Riyadh. | | 329 | when setting up lunch with promptness sticklers in Riyadh. |
319 | .\" @(#)newctime.3 8.3 | | 330 | .\" @(#)newctime.3 8.3 |
320 | .\" This file is in the public domain, so clarified as of | | 331 | .\" This file is in the public domain, so clarified as of |
321 | .\" 2009-05-17 by Arthur David Olson. | | 332 | .\" 2009-05-17 by Arthur David Olson. |