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