xref: /freebsd/lib/libc/stdtime/ctime.3 (revision 39beb93c3f8bdbf72a61fda42300b5ebed7390c8)
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.
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
31.\" $FreeBSD$
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 *
55.Fn ctime "const time_t *clock"
56.Ft double
57.Fn difftime "time_t time1" "time_t time0"
58.Ft char *
59.Fn asctime "const struct tm *tm"
60.Ft struct tm *
61.Fn localtime "const time_t *clock"
62.Ft struct tm *
63.Fn gmtime "const time_t *clock"
64.Ft time_t
65.Fn mktime "struct tm *tm"
66.Ft time_t
67.Fn timegm "struct tm *tm"
68.Ft char *
69.Fn ctime_r "const time_t *clock" "char *buf"
70.Ft struct tm *
71.Fn localtime_r "const time_t *clock" "struct tm *result"
72.Ft struct tm *
73.Fn gmtime_r "const time_t *clock" "struct tm *result"
74.Ft char *
75.Fn asctime_r "const struct tm *tm" "char *buf"
76.Sh DESCRIPTION
77The functions
78.Fn ctime ,
79.Fn gmtime
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 ) .
87.Pp
88The function
89.Fn localtime
90converts the time value pointed at by
91.Fa clock ,
92and returns a pointer to a
93.Dq Fa struct tm
94(described below) which contains
95the broken-out time information for the value after adjusting for the current
96time zone (and any other factors such as Daylight Saving Time).
97Time zone adjustments are performed as specified by the
98.Ev TZ
99environment variable (see
100.Xr tzset 3 ) .
101The function
102.Fn localtime
103uses
104.Xr tzset 3
105to initialize time conversion information if
106.Xr tzset 3
107has not already been called by the process.
108.Pp
109After filling in the tm structure,
110.Fn localtime
111sets the
112.Fa tm_isdst Ns 'th
113element of
114.Fa tzname
115to a pointer to an
116.Tn ASCII
117string that is the time zone abbreviation to be
118used with
119.Fn localtime Ns 's
120return value.
121.Pp
122The function
123.Fn gmtime
124similarly converts the time value, but without any time zone adjustment,
125and returns a pointer to a tm structure (described below).
126.Pp
127The
128.Fn ctime
129function
130adjusts the time value for the current time zone in the same manner as
131.Fn localtime ,
132and returns a pointer to a 26-character string of the form:
133.Bd -literal -offset indent
134Thu Nov 24 18:22:48 1986\en\e0
135.Ed
136.Pp
137All the fields have constant width.
138.Pp
139The
140.Fn ctime_r
141function
142provides the same functionality as
143.Fn ctime
144except the caller must provide the output buffer
145.Fa buf
146to store the result, which must be at least 26 characters long.
147The
148.Fn localtime_r
149and
150.Fn gmtime_r
151functions
152provide the same functionality as
153.Fn localtime
154and
155.Fn gmtime
156respectively, except the caller must provide the output buffer
157.Fa result .
158.Pp
159The
160.Fn asctime
161function
162converts the broken down time in the structure
163.Fa tm
164pointed at by
165.Fa *tm
166to the form
167shown in the example above.
168.Pp
169The
170.Fn asctime_r
171function
172provides the same functionality as
173.Fn asctime
174except the caller provide the output buffer
175.Fa buf
176to store the result, which must be at least 26 characters long.
177.Pp
178The functions
179.Fn mktime
180and
181.Fn timegm
182convert the broken-down time in the structure
183pointed to by tm into a time value with the same encoding as that of the
184values returned by the
185.Xr time 3
186function (that is, seconds from the Epoch,
187.Tn UTC ) .
188The
189.Fn mktime
190function
191interprets the input structure according to the current timezone setting
192(see
193.Xr tzset 3 ) .
194The
195.Fn timegm
196function
197interprets the input structure as representing Universal Coordinated Time
198.Pq Tn UTC .
199.Pp
200The original values of the
201.Fa tm_wday
202and
203.Fa tm_yday
204components of the structure are ignored, and the original values of the
205other components are not restricted to their normal ranges, and will be
206normalized if needed.
207For example,
208October 40 is changed into November 9,
209a
210.Fa tm_hour
211of \-1 means 1 hour before midnight,
212.Fa tm_mday
213of 0 means the day preceding the current month, and
214.Fa tm_mon
215of \-2 means 2 months before January of
216.Fa tm_year .
217(A positive or zero value for
218.Fa tm_isdst
219causes
220.Fn mktime
221to presume initially that summer time (for example, Daylight Saving Time)
222is or is not in effect for the specified time, respectively.
223A negative value for
224.Fa tm_isdst
225causes the
226.Fn mktime
227function to attempt to divine whether summer time is in effect for the
228specified time.
229The
230.Fa tm_isdst
231and
232.Fa tm_gmtoff
233members are forced to zero by
234.Fn timegm . )
235.Pp
236On successful completion, the values of the
237.Fa tm_wday
238and
239.Fa tm_yday
240components of the structure are set appropriately, and the other components
241are set to represent the specified calendar time, but with their values
242forced to their normal ranges; the final value of
243.Fa tm_mday
244is not set until
245.Fa tm_mon
246and
247.Fa tm_year
248are determined.
249The
250.Fn mktime
251function
252returns the specified calendar time; if the calendar time cannot be
253represented, it returns \-1;
254.Pp
255The
256.Fn difftime
257function
258returns the difference between two calendar times,
259.Pf ( Fa time1
260-
261.Fa time0 ) ,
262expressed in seconds.
263.Pp
264External declarations as well as the tm structure definition are in the
265.In time.h
266include file.
267The tm structure includes at least the following fields:
268.Bd -literal -offset indent
269int tm_sec;	/\(** seconds (0 - 60) \(**/
270int tm_min;	/\(** minutes (0 - 59) \(**/
271int tm_hour;	/\(** hours (0 - 23) \(**/
272int tm_mday;	/\(** day of month (1 - 31) \(**/
273int tm_mon;	/\(** month of year (0 - 11) \(**/
274int tm_year;	/\(** year \- 1900 \(**/
275int tm_wday;	/\(** day of week (Sunday = 0) \(**/
276int tm_yday;	/\(** day of year (0 - 365) \(**/
277int tm_isdst;	/\(** is summer time in effect? \(**/
278char \(**tm_zone;	/\(** abbreviation of timezone name \(**/
279long tm_gmtoff;	/\(** offset from UTC in seconds \(**/
280.Ed
281.Pp
282The
283field
284.Fa tm_isdst
285is non-zero if summer time is in effect.
286.Pp
287The field
288.Fa tm_gmtoff
289is the offset (in seconds) of the time represented from
290.Tn UTC ,
291with positive
292values indicating east of the Prime Meridian.
293.Sh SEE ALSO
294.Xr date 1 ,
295.Xr gettimeofday 2 ,
296.Xr getenv 3 ,
297.Xr time 3 ,
298.Xr tzset 3 ,
299.Xr tzfile 5
300.Sh STANDARDS
301The
302.Fn asctime ,
303.Fn ctime ,
304.Fn difftime ,
305.Fn gmtime ,
306.Fn localtime ,
307and
308.Fn mktime
309functions conform to
310.St -isoC ,
311and conform to
312.St -p1003.1-96
313provided the selected local timezone does not contain a leap-second table
314(see
315.Xr zic 8 ) .
316.Pp
317The
318.Fn asctime_r ,
319.Fn ctime_r ,
320.Fn gmtime_r ,
321and
322.Fn localtime_r
323functions are expected to conform to
324.St -p1003.1-96
325(again provided the selected local timezone does not contain a leap-second
326table).
327.Pp
328The
329.Fn timegm
330function is not specified by any standard; its function cannot be
331completely emulated using the standard functions described above.
332.Sh HISTORY
333This manual page is derived from
334the time package contributed to Berkeley by
335.An Arthur Olson
336and which appeared in
337.Bx 4.3 .
338.Sh BUGS
339Except for
340.Fn difftime ,
341.Fn mktime ,
342and the
343.Fn \&_r
344variants of the other functions,
345these functions leaves their result in an internal static object and return
346a pointer to that object.
347Subsequent calls to these
348function will modify the same object.
349.Pp
350The C Standard provides no mechanism for a program to modify its current
351local timezone setting, and the
352.Tn POSIX Ns No \&-standard
353method is not reentrant.
354(However, thread-safe implementations are provided
355in the
356.Tn POSIX
357threaded environment.)
358.Pp
359The
360.Va tm_zone
361field of a returned
362.Vt tm
363structure points to a static array of characters,
364which will also be overwritten by any subsequent calls (as well as by
365subsequent calls to
366.Xr tzset 3
367and
368.Xr tzsetwall 3 ) .
369.Pp
370Use of the external variable
371.Fa tzname
372is discouraged; the
373.Fa tm_zone
374entry in the tm structure is preferred.
375