]> git.saurik.com Git - apple/libc.git/blame - stdtime/FreeBSD/ctime.3
Libc-1158.50.2.tar.gz
[apple/libc.git] / stdtime / FreeBSD / ctime.3
CommitLineData
5b2abdfb
A
1.\" Copyright (c) 1989, 1991, 1993
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" This code is derived from software contributed to Berkeley by
5.\" Arthur Olson.
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\" notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\" notice, this list of conditions and the following disclaimer in the
13.\" documentation and/or other materials provided with the distribution.
5b2abdfb
A
14.\" 4. Neither the name of the University nor the names of its contributors
15.\" may be used to endorse or promote products derived from this software
16.\" without specific prior written permission.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28.\" SUCH DAMAGE.
29.\"
30.\" From: @(#)ctime.3 8.1 (Berkeley) 6/4/93
1f2f436a 31.\" $FreeBSD: src/lib/libc/stdtime/ctime.3,v 1.24 2007/01/09 00:28:11 imp Exp $
5b2abdfb
A
32.\"
33.Dd January 2, 1999
34.Dt CTIME 3
35.Os
36.Sh NAME
37.Nm asctime ,
38.Nm asctime_r ,
39.Nm ctime ,
40.Nm ctime_r ,
41.Nm difftime ,
42.Nm gmtime ,
43.Nm gmtime_r ,
44.Nm localtime ,
45.Nm localtime_r ,
46.Nm mktime ,
47.Nm timegm
48.Nd transform binary date and time values
49.Sh LIBRARY
50.Lb libc
51.Sh SYNOPSIS
52.In time.h
53.Vt extern char *tzname[2] ;
54.Ft char *
ad3c9f2a
A
55.Fn asctime "const struct tm *timeptr"
56.Ft char *
57.Fn asctime_r "const struct tm *restrict timeptr" "char *restrict buf"
58.Ft char *
5b2abdfb 59.Fn ctime "const time_t *clock"
ad3c9f2a
A
60.Ft char *
61.Fn ctime_r "const time_t *clock" "char *buf"
5b2abdfb
A
62.Ft double
63.Fn difftime "time_t time1" "time_t time0"
ad3c9f2a
A
64.Ft struct tm *
65.Fn gmtime "const time_t *clock"
66.Ft struct tm *
67.Fn gmtime_r "const time_t *clock" "struct tm *result"
5b2abdfb
A
68.Ft struct tm *
69.Fn localtime "const time_t *clock"
70.Ft struct tm *
ad3c9f2a 71.Fn localtime_r "const time_t *clock" "struct tm *result"
5b2abdfb 72.Ft time_t
ad3c9f2a 73.Fn mktime "struct tm *timeptr"
5b2abdfb 74.Ft time_t
ad3c9f2a 75.Fn timegm "struct tm *timeptr"
5b2abdfb
A
76.Sh DESCRIPTION
77The functions
78.Fn ctime ,
ad3c9f2a 79.Fn gmtime ,
5b2abdfb
A
80and
81.Fn localtime
82all take as an argument a time value representing the time in seconds since
83the Epoch (00:00:00
84.Tn UTC ,
85January 1, 1970; see
86.Xr time 3 ) .
6465356a
A
87When encountering an error, these functions return
88.Dv NULL
89and set
90.Dv errno
91to an appropriate value.
5b2abdfb
A
92.Pp
93The function
94.Fn localtime
95converts the time value pointed at by
ad3c9f2a
A
96.Fa clock .
97It returns a pointer to a
5b2abdfb 98.Dq Fa struct tm
ad3c9f2a 99(described below), which contains
5b2abdfb
A
100the broken-out time information for the value after adjusting for the current
101time zone (and any other factors such as Daylight Saving Time).
102Time zone adjustments are performed as specified by the
103.Ev TZ
104environment variable (see
105.Xr tzset 3 ) .
106The function
107.Fn localtime
108uses
109.Xr tzset 3
ad3c9f2a 110to initialize time conversion information, if
5b2abdfb
A
111.Xr tzset 3
112has not already been called by the process.
113.Pp
114After filling in the tm structure,
115.Fn localtime
116sets the
117.Fa tm_isdst Ns 'th
118element of
119.Fa tzname
120to a pointer to an
121.Tn ASCII
ad3c9f2a 122string containing the time zone abbreviation to be
5b2abdfb
A
123used with
124.Fn localtime Ns 's
125return value.
126.Pp
127The function
128.Fn gmtime
ad3c9f2a
A
129also converts the time value, but makes no time zone adjustment.
130It returns a pointer to a tm structure (described below).
5b2abdfb
A
131.Pp
132The
133.Fn ctime
134function
ad3c9f2a
A
135adjusts the time value for the current time zone, in the same manner as
136.Fn localtime .
137It returns a pointer to a 26-character string of the form:
5b2abdfb
A
138.Bd -literal -offset indent
139Thu Nov 24 18:22:48 1986\en\e0
140.Ed
141.Pp
ad3c9f2a 142All of the fields have constant width.
5b2abdfb 143.Pp
9385eb3d 144The
5b2abdfb 145.Fn ctime_r
9385eb3d 146function
5b2abdfb 147provides the same functionality as
ad3c9f2a
A
148.Fn ctime ,
149except that the caller must provide the output buffer
5b2abdfb 150.Fa buf
ad3c9f2a 151(which must be at least 26 characters long) to store the result.
9385eb3d 152The
5b2abdfb
A
153.Fn localtime_r
154and
155.Fn gmtime_r
9385eb3d 156functions
5b2abdfb
A
157provide the same functionality as
158.Fn localtime
159and
ad3c9f2a 160.Fn gmtime ,
5b2abdfb
A
161respectively, except the caller must provide the output buffer
162.Fa result .
163.Pp
164The
165.Fn asctime
166function
ad3c9f2a 167converts the broken-out time in the structure
5b2abdfb 168.Fa tm
ad3c9f2a
A
169(pointed at by
170.Fa *timeptr )
5b2abdfb
A
171to the form
172shown in the example above.
173.Pp
9385eb3d 174The
5b2abdfb 175.Fn asctime_r
9385eb3d 176function
5b2abdfb 177provides the same functionality as
ad3c9f2a
A
178.Fn asctime ,
179except that the caller provides the output buffer
5b2abdfb 180.Fa buf
ad3c9f2a 181(which must be at least 26 characters long) to store the result.
5b2abdfb
A
182.Pp
183The functions
184.Fn mktime
185and
186.Fn timegm
ad3c9f2a
A
187convert the broken-out time
188(in the structure pointed to by
189.Fa *timeptr )
190into a time value with the same encoding as that of the
5b2abdfb
A
191values returned by the
192.Xr time 3
193function (that is, seconds from the Epoch,
194.Tn UTC ) .
9385eb3d 195The
5b2abdfb 196.Fn mktime
9385eb3d 197function
5b2abdfb
A
198interprets the input structure according to the current timezone setting
199(see
200.Xr tzset 3 ) .
9385eb3d 201The
5b2abdfb 202.Fn timegm
ad3c9f2a
A
203function interprets the input structure
204as representing Universal Coordinated Time
5b2abdfb
A
205.Pq Tn UTC .
206.Pp
207The original values of the
208.Fa tm_wday
209and
210.Fa tm_yday
ad3c9f2a
A
211components of the structure are ignored. The original values of the
212other components are not restricted to their normal ranges and will be
213normalized, if need be.
5b2abdfb
A
214For example,
215October 40 is changed into November 9,
216a
217.Fa tm_hour
218of \-1 means 1 hour before midnight,
219.Fa tm_mday
220of 0 means the day preceding the current month, and
221.Fa tm_mon
222of \-2 means 2 months before January of
223.Fa tm_year .
224(A positive or zero value for
225.Fa tm_isdst
226causes
227.Fn mktime
228to presume initially that summer time (for example, Daylight Saving Time)
ad3c9f2a 229is or is not (respectively) in effect for the specified time.
5b2abdfb
A
230A negative value for
231.Fa tm_isdst
232causes the
233.Fn mktime
234function to attempt to divine whether summer time is in effect for the
235specified time.
236The
237.Fa tm_isdst
238and
239.Fa tm_gmtoff
240members are forced to zero by
241.Fn timegm . )
242.Pp
243On successful completion, the values of the
244.Fa tm_wday
245and
246.Fa tm_yday
247components of the structure are set appropriately, and the other components
248are set to represent the specified calendar time, but with their values
249forced to their normal ranges; the final value of
250.Fa tm_mday
251is not set until
252.Fa tm_mon
253and
254.Fa tm_year
255are determined.
9385eb3d
A
256The
257.Fn mktime
258function
5b2abdfb
A
259returns the specified calendar time; if the calendar time cannot be
260represented, it returns \-1;
261.Pp
262The
263.Fn difftime
264function
265returns the difference between two calendar times,
266.Pf ( Fa time1
267-
268.Fa time0 ) ,
269expressed in seconds.
270.Pp
ad3c9f2a
A
271External declarations, as well as the tm structure definition,
272are contained in the
3d9156a7 273.In time.h
5b2abdfb
A
274include file.
275The tm structure includes at least the following fields:
276.Bd -literal -offset indent
277int tm_sec; /\(** seconds (0 - 60) \(**/
278int tm_min; /\(** minutes (0 - 59) \(**/
279int tm_hour; /\(** hours (0 - 23) \(**/
280int tm_mday; /\(** day of month (1 - 31) \(**/
281int tm_mon; /\(** month of year (0 - 11) \(**/
282int tm_year; /\(** year \- 1900 \(**/
283int tm_wday; /\(** day of week (Sunday = 0) \(**/
284int tm_yday; /\(** day of year (0 - 365) \(**/
285int tm_isdst; /\(** is summer time in effect? \(**/
286char \(**tm_zone; /\(** abbreviation of timezone name \(**/
287long tm_gmtoff; /\(** offset from UTC in seconds \(**/
288.Ed
289.Pp
290The
291field
292.Fa tm_isdst
ad3c9f2a 293is non-zero if summer (i.e., Daylight Saving) time is in effect.
5b2abdfb
A
294.Pp
295The field
296.Fa tm_gmtoff
297is the offset (in seconds) of the time represented from
298.Tn UTC ,
299with positive
ad3c9f2a 300values indicating locations east of the Prime Meridian.
5b2abdfb
A
301.Sh SEE ALSO
302.Xr date 1 ,
303.Xr gettimeofday 2 ,
304.Xr getenv 3 ,
305.Xr time 3 ,
306.Xr tzset 3 ,
307.Xr tzfile 5
308.Sh STANDARDS
309The
310.Fn asctime ,
311.Fn ctime ,
312.Fn difftime ,
313.Fn gmtime ,
314.Fn localtime ,
315and
316.Fn mktime
317functions conform to
318.St -isoC ,
319and conform to
320.St -p1003.1-96
321provided the selected local timezone does not contain a leap-second table
322(see
323.Xr zic 8 ) .
324.Pp
325The
326.Fn asctime_r ,
327.Fn ctime_r ,
328.Fn gmtime_r ,
329and
330.Fn localtime_r
331functions are expected to conform to
332.St -p1003.1-96
333(again provided the selected local timezone does not contain a leap-second
334table).
335.Pp
336The
337.Fn timegm
338function is not specified by any standard; its function cannot be
339completely emulated using the standard functions described above.
340.Sh HISTORY
341This manual page is derived from
342the time package contributed to Berkeley by
343.An Arthur Olson
344and which appeared in
345.Bx 4.3 .
346.Sh BUGS
347Except for
348.Fn difftime ,
349.Fn mktime ,
350and the
351.Fn \&_r
352variants of the other functions,
353these functions leaves their result in an internal static object and return
354a pointer to that object.
355Subsequent calls to these
356function will modify the same object.
357.Pp
358The C Standard provides no mechanism for a program to modify its current
359local timezone setting, and the
360.Tn POSIX Ns No \&-standard
3d9156a7
A
361method is not reentrant.
362(However, thread-safe implementations are provided
5b2abdfb
A
363in the
364.Tn POSIX
365threaded environment.)
366.Pp
367The
9385eb3d
A
368.Va tm_zone
369field of a returned
370.Vt tm
371structure points to a static array of characters,
5b2abdfb
A
372which will also be overwritten by any subsequent calls (as well as by
373subsequent calls to
374.Xr tzset 3
375and
376.Xr tzsetwall 3 ) .
377.Pp
378Use of the external variable
379.Fa tzname
380is discouraged; the
381.Fa tm_zone
382entry in the tm structure is preferred.