| blob | 0ca032bd08d1133ed5babb282d38fe6048869bbc |
1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright 1989 AT&T
44 .\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved.
45 .\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved.
46 .\"
47 .TH CTIME 3C "May 27, 2005"
48 .SH NAME
49 ctime, ctime_r, localtime, localtime_r, gmtime, gmtime_r, asctime, asctime_r,
50 tzset \- convert date and time to string
51 .SH SYNOPSIS
52 .LP
53 .nf
54 #include <time.h>
56 \fBchar *\fR\fBctime\fR(\fBconst time_t *\fR\fIclock\fR);
57 .fi
59 .LP
60 .nf
61 \fBstruct tm *\fR\fBlocaltime\fR(\fBconst time_t *\fR\fIclock\fR);
62 .fi
64 .LP
65 .nf
66 \fBstruct tm *\fR\fBgmtime\fR(\fBconst time_t *\fR\fIclock\fR);
67 .fi
69 .LP
70 .nf
71 \fBchar *\fR\fBasctime\fR(\fBconst struct tm *\fR\fItm\fR);
72 .fi
74 .LP
75 .nf
76 extern time_t timezone, altzone;
77 extern int daylight;
78 extern char *tzname[2];
80 \fBvoid\fR \fBtzset\fR(\fBvoid\fR);
81 .fi
83 .LP
84 .nf
85 \fBchar *\fR\fBctime_r\fR(\fBconst time_t *\fR\fIclock\fR, \fBchar *\fR\fIbuf\fR, \fBint\fR \fIbuflen\fR);
86 .fi
88 .LP
89 .nf
90 \fBstruct tm *\fR\fBlocaltime_r\fR(\fBconst time_t *restrict\fR \fIclock\fR,
91 \fBstruct tm *restrict\fR \fIres\fR);
92 .fi
94 .LP
95 .nf
96 \fBstruct tm *\fR\fBgmtime_r\fR(\fBconst time_t *restrict\fR \fIclock\fR,
97 \fBstruct tm *restrict\fR \fIres\fR);
98 .fi
100 .LP
101 .nf
102 \fBchar *\fR\fBasctime_r\fR(\fBconst struct tm *restrict\fR \fItm\fR, \fBchar *restrict\fR \fIbuf\fR,
103 \fBint\fR \fIbuflen\fR);
104 .fi
106 .SS "Standard conforming"
107 .LP
108 .nf
109 cc [ \fIflag\fR... ] \fIfile\fR... \fB-D_POSIX_PTHREAD_SEMANTICS\fR [ \fIlibrary\fR... ]
111 \fBchar *\fR\fBctime_r\fR(\fBconst time_t *\fR\fIclock\fR, \fBchar *\fR\fIbuf\fR);
112 .fi
114 .LP
115 .nf
116 \fBchar *\fR\fBasctime_r\fR(\fBconst struct tm *\fR\fItm\fR, \fBchar *\fR\fIbuf\fR);
117 .fi
119 .SH DESCRIPTION
120 .sp
121 .LP
122 The \fBctime()\fR function converts the time pointed to by \fIclock\fR,
123 representing the time in seconds since the Epoch (00:00:00 UTC, January 1,
124 1970), to local time in the form of a 26-character string, as shown below. Time
125 zone and daylight savings corrections are made before string generation. The
126 fields are in constant width:
127 .sp
128 .LP
129 Fri Sep 13 00:00:00 1986\en\e0
130 .sp
131 .LP
132 The \fBctime()\fR function is equivalent to:
133 .sp
134 .LP
135 \fBasctime(localtime(\fR\fIclock\fR\fB\fR\fB))\fR
136 .sp
137 .LP
138 The \fBctime()\fR, \fBasctime()\fR, \fBgmtime()\fR, and \fBlocaltime()\fR
139 functions return values in one of two thread-specific data objects: a
140 broken-down time structure and an array of \fBchar\fR. Execution of any of the
141 functions can overwrite the information returned in either of these objects by
142 any of the other functions executed by the same thread.
143 .sp
144 .LP
145 The \fBctime_r()\fR function has the same functionality as \fBctime()\fR except
146 that the caller must supply a buffer \fIbuf\fR with length \fIbuflen\fR to
147 store the result; \fIbuf\fR must be at least 26 bytes. The standard-conforming
148 \fBctime_r()\fR function does not take a \fIbuflen\fR parameter.
149 .sp
150 .LP
151 The \fBlocaltime()\fR and \fBgmtime()\fR functions return pointers to \fBtm\fR
152 structures (see below). The \fBlocaltime()\fR function corrects for the main
153 time zone and possible alternate ("daylight savings") time zone; the
154 \fBgmtime()\fR function converts directly to Coordinated Universal Time (UTC),
155 which is what the UNIX system uses internally.
156 .sp
157 .LP
158 The \fBlocaltime_r()\fR and \fBgmtime_r()\fR functions have the same
159 functionality as \fBlocaltime()\fR and \fBgmtime()\fR respectively, except that
160 the caller must supply a buffer \fIres\fR to store the result.
161 .sp
162 .LP
163 The \fBasctime()\fR function converts a \fBtm\fR structure to a 26-character
164 string, as shown in the previous example, and returns a pointer to the string.
165 .sp
166 .LP
167 The \fBasctime_r()\fR function has the same functionality as \fBasctime()\fR
168 except that the caller must supply a buffer \fIbuf\fR with length \fIbuflen\fR
169 for the result to be stored. The \fIbuf\fR argument must be at least 26 bytes.
170 The standard-conforming \fBasctime_r()\fR function does not take a \fIbuflen\fR
171 parameter. The \fBasctime_r()\fR function returns a pointer to \fIbuf\fR upon
172 success. In case of failure, \fINULL\fR is returned and \fBerrno\fR is set.
173 .sp
174 .LP
175 Declarations of all the functions and externals, and the \fBtm\fR structure,
176 are in the <\fBtime.h\fR> header. The members of the \fBtm\fR structure are:
177 .sp
178 .in +2
179 .nf
180 int tm_sec; /* seconds after the minute \(em [0, 60] */
181 /* for leap seconds */
182 int tm_min; /* minutes after the hour \(em [0, 59] */
183 int tm_hour; /* hour since midnight \(em [0, 23] */
184 int tm_mday; /* day of the month \(em [1, 31] */
185 int tm_mon; /* months since January \(em [0, 11] */
186 int tm_year; /* years since 1900 */
187 int tm_wday; /* days since Sunday \(em [0, 6] */
188 int tm_yday; /* days since January 1 \(em [0, 365] */
189 int tm_isdst; /* flag for alternate daylight savings time */
190 .fi
191 .in -2
193 .sp
194 .LP
195 The value of \fBtm_isdst\fR is positive if daylight savings time is in effect,
196 zero if daylight savings time is not in effect, and negative if the information
197 is not available. Previously, the value of \fBtm_isdst\fR was defined as
198 non-zero if daylight savings was in effect.
199 .sp
200 .LP
201 The external \fBtime_t\fR variable \fBaltzone\fR contains the difference, in
202 seconds, between Coordinated Universal Time and the alternate time zone. The
203 external variable \fBtimezone\fR contains the difference, in seconds, between
204 UTC and local standard time. The external variable \fBdaylight\fR indicates
205 whether time should reflect daylight savings time. Both \fBtimezone\fR and
206 \fBaltzone\fR default to 0 (UTC). The external variable \fBdaylight\fR is
207 non-zero if an alternate time zone exists. The time zone names are contained in
208 the external variable \fBtzname\fR, which by default is set to:
209 .sp
210 .LP
211 char *tzname[2] = { "GMT", "\|" };
212 .sp
213 .LP
214 These functions know about the peculiarities of this conversion for various
215 time periods for the \fBU.S.\fR (specifically, the years 1974, 1975, and 1987).
216 They start handling the new daylight savings time starting with the first
217 Sunday in April, 1987.
218 .sp
219 .LP
220 The \fBtzset()\fR function uses the contents of the environment variable
221 \fBTZ\fR to override the value of the different external variables. It is
222 called by \fBasctime()\fR and can also be called by the user. If \fBTZ\fR is
223 not specified or has an invalid setting, \fBtzset()\fR uses \fBGMT0\fR. See
224 \fBenviron\fR(5) for a description of the \fBTZ\fR environment variable.
225 .sp
226 .LP
227 Starting and ending times are relative to the current local time zone. If the
228 alternate time zone start and end dates and the time are not provided, the days
229 for the United States that year will be used and the time will be 2 AM. If the
230 start and end dates are provided but the time is not provided, the time will be
231 2 AM. The effects of \fBtzset()\fR change the values of the external variables
232 \fBtimezone\fR, \fBaltzone\fR, \fBdaylight\fR, and \fBtzname\fR.
233 .sp
234 .LP
235 Note that in most installations, \fBTZ\fR is set to the correct value by
236 default when the user logs on, using the local \fB/etc/default/init\fR file
237 (see \fBTIMEZONE\fR(4)).
238 .SH RETURN VALUES
239 .sp
240 .LP
241 Upon successful completion, the \fBgmtime()\fR and \fBlocaltime()\fR functions
242 return a pointer to a \fBstruct tm\fR. If an error is detected, \fBgmtime()\fR
243 and \fBlocaltime()\fR return a null pointer.
244 .sp
245 .LP
246 Upon successful completion, the \fBgmtime_r()\fR and \fBlocaltime_r()\fR
247 functions return the address of the structure pointed to by the \fIres\fR
248 argument. If an error is detected, \fBgmtime_r()\fR and \fBlocaltime_r()\fR
249 return a null pointer and set \fBerrno\fR to indicate the error.
250 .SH ERRORS
251 .sp
252 .LP
253 The \fBctime_r()\fR and \fBasctime_r()\fR functions will fail if:
254 .sp
255 .ne 2
256 .na
257 \fB\fBERANGE\fR\fR
258 .ad
259 .RS 10n
260 The length of the buffer supplied by the caller is not large enough to store
261 the result.
262 .RE
264 .sp
265 .LP
266 The \fBgmtime()\fR, \fBgmtime_r()\fR, \fBlocaltime()\fR, and
267 \fBlocaltime_r()\fR functions will fail if:
268 .sp
269 .ne 2
270 .na
271 \fB\fBEOVERFLOW\fR\fR
272 .ad
273 .RS 13n
274 The result cannot be represented.
275 .RE
277 .SH USAGE
278 .sp
279 .LP
280 These functions do not support localized date and time formats. The
281 \fBstrftime\fR(3C) function can be used when localization is required.
282 .sp
283 .LP
284 The \fBlocaltime()\fR, \fBlocaltime_r()\fR, \fBgmtime()\fR, \fBgmtime_r()\fR,
285 \fBctime()\fR, and \fBctime_r()\fR functions assume Gregorian dates. Times
286 before the adoption of the Gregorian calendar will not match historial records.
287 .SH EXAMPLES
288 .LP
289 \fBExample 1 \fRExamples of the \fBtzset()\fR function.
290 .sp
291 .LP
292 The \fBtzset()\fR function scans the contents of the environment variable and
293 assigns the different fields to the respective variable. For example, the most
294 complete setting for New Jersey in 1986 could be:
296 .sp
297 .in +2
298 .nf
299 EST5EDT4,116/2:00:00,298/2:00:00
300 .fi
301 .in -2
303 .sp
304 .LP
305 or simply
307 .sp
308 .in +2
309 .nf
310 EST5EDT
311 .fi
312 .in -2
314 .sp
315 .LP
316 An example of a southern hemisphere setting such as the Cook Islands could be
318 .sp
319 .in +2
320 .nf
321 KDT9:30KST10:00,63/5:00,302/20:00
322 .fi
323 .in -2
325 .sp
326 .LP
327 In the longer version of the New Jersey example of \fBTZ,\fR
328 \fBtzname\fR[\fB0\fR] is EST, \fBtimezone\fR is set to 5*60*60,
329 \fBtzname\fR[\fB1\fR] is EDT, \fBaltzone\fR is set to 4*60*60, the starting
330 date of the alternate time zone is the 117th day at 2 AM, the ending date of
331 the alternate time zone is the 299th day at 2 AM (using zero-based Julian
332 days), and \fBdaylight\fR is set positive. Starting and ending times are
333 relative to the current local time zone. If the alternate time zone start and
334 end dates and the time are not provided, the days for the United States that
335 year will be used and the time will be 2 AM. If the start and end dates are
336 provided but the time is not provided, the time will be 2 AM. The effects of
337 \fBtzset()\fR are thus to change the values of the external variables
338 \fBtimezone\fR, \fBaltzone\fR, \fBdaylight\fR, and \fBtzname\fR. The
339 \fBctime()\fR, \fBlocaltime()\fR, \fBmktime()\fR, and \fBstrftime()\fR
340 functions also update these external variables as if they had called
341 \fBtzset()\fR at the time specified by the \fBtime_t\fR or \fBstruct tm\fR
342 value that they are converting.
344 .SH BUGS
345 .sp
346 .LP
347 The \fBzoneinfo\fR timezone data files do not transition past Tue Jan 19
348 03:14:07 2038 UTC. Therefore for 64-bit applications using \fBzoneinfo\fR
349 timezones, calculations beyond this date might not use the correct offset from
350 standard time, and could return incorrect values. This affects the 64-bit
351 version of \fBlocaltime()\fR, \fBlocaltime_r()\fR, \fBctime()\fR, and
352 \fBctime_r()\fR.
353 .SH ATTRIBUTES
354 .sp
355 .LP
356 See \fBattributes\fR(5) for descriptions of the following attributes:
357 .sp
359 .sp
360 .TS
361 box;
362 c | c
363 l | l .
364 ATTRIBUTE TYPE ATTRIBUTE VALUE
365 _
366 CSI Enabled
367 _
368 Interface Stability Standard
369 _
370 MT-Level MT-Safe with exceptions
371 .TE
373 .sp
374 .LP
375 The \fBasctime()\fR, \fBctime()\fR, \fBgmtime()\fR, and \fBlocaltime()\fR
376 functions are safe to use in multithread applications because they employ
377 thread-specific data. However, their use is discouraged because standards do
378 not require them to be thread-safe. The \fBasctime_r()\fR and \fBgmtime_r()\fR
379 functions are MT-Safe. The \fBctime_r()\fR, \fBlocaltime_r()\fR, and
380 \fBtzset()\fR functions are MT-Safe in multithread applications, as long as no
381 user-defined function directly modifies one of the following variables:
382 \fBtimezone\fR, \fBaltzone\fR, \fBdaylight\fR, and \fBtzname\fR. These four
383 variables are not MT-Safe to access. They are modified by the \fBtzset()\fR
384 function in an MT-Safe manner. The \fBmktime()\fR, \fBlocaltime_r()\fR, and
385 \fBctime_r()\fR functions call \fBtzset()\fR.
386 .SH SEE ALSO
387 .sp
388 .LP
389 \fBtime\fR(2), \fBIntro\fR(3), \fBgetenv\fR(3C), \fBmktime\fR(3C),
390 \fBprintf\fR(3C), \fBputenv\fR(3C), \fBsetlocale\fR(3C), \fBstrftime\fR(3C),
391 \fBTIMEZONE\fR(4), \fBattributes\fR(5), \fBenviron\fR(5), \fBstandards\fR(5)
392 .SH NOTES
393 .sp
394 .LP
395 When compiling multithreaded programs, see \fBIntro\fR(3).
396 .sp
397 .LP
398 The return values for \fBasctime()\fR, \fBctime()\fR, \fBgmtime()\fR, and
399 \fBlocaltime()\fR point to thread-specific data whose content is overwritten by
400 each call by the same thread.
401 .sp
402 .LP
403 Setting the time during the interval of change from \fBtimezone\fR to
404 \fBaltzone\fR or vice versa can produce unpredictable results. The system
405 administrator must change the Julian start and end days annually.
406 .sp
407 .LP
408 If \fBtzset()\fR has previously evaluated the timezone identified by the value
409 of the \fBTZ\fR environment variable, \fBtzset()\fR can reuse the previous
410 settings of the external variables \fBaltzone\fR, \fBdaylight\fR,
411 \fBtimezone\fR, and \fBtzname\fR[] associated with that timezone.
412 .sp
413 .LP
414 Solaris 2.4 and earlier releases provided definitions of the \fBctime_r()\fR,
415 \fBlocaltime_r()\fR, \fBgmtime_r()\fR, and \fBasctime_r()\fR functions as
416 specified in POSIX.1c Draft 6. The final POSIX.1c standard changed the
417 interface for \fBctime_r()\fR and \fBasctime_r()\fR. Support for the Draft 6
418 interface is provided for compatibility only and might not be supported in
419 future releases. New applications and libraries should use the
420 standard-conforming interface.
421 .sp
422 .LP
423 For POSIX.1c-conforming applications, the \fB_POSIX_PTHREAD_SEMANTICS\fR and
424 \fB_REENTRANT\fR flags are automatically turned on by defining the
425 \fB_POSIX_C_SOURCE\fR flag with a value >= 199506L.
426 .sp
427 .LP
428 In Solaris 10, \fBgmtime()\fR, \fBgmtime_r()\fR, \fBlocaltime()\fR, and
429 \fBlocaltime_r()\fR were updated to return a null pointer if an error is
430 detected. This change was based on the SUSv3 specification. See
431 \fBstandards\fR(5).