1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
3 .\" Permission is granted to make and distribute verbatim copies of this
4 .\" manual provided the copyright notice and this permission notice are
5 .\" preserved on all copies.
7 .\" Permission is granted to copy and distribute modified versions of this
8 .\" manual under the conditions for verbatim copying, provided that the
9 .\" entire resulting derived work is distributed under the terms of a
10 .\" permission notice identical to this one.
12 .\" Since the Linux kernel and libraries are constantly changing, this
13 .\" manual page may be incorrect or out-of-date. The author(s) assume no
14 .\" responsibility for errors or omissions, or for damages resulting from
15 .\" the use of the information contained herein. The author(s) may not
16 .\" have taken the same level of care in the production of this manual,
17 .\" which is licensed free of charge, as they might when working
20 .\" Formatted or processed versions of this manual, if unaccompanied by
21 .\" the source, must acknowledge the copyright and authors of this work.
23 .\" References consulted:
24 .\" Linux libc source code
25 .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
27 .\" Modified Sat Jul 24 19:49:27 1993 by Rik Faith (faith@cs.unc.edu)
28 .\" Modified Fri Apr 26 12:38:55 MET DST 1996 by Martin Schulze (joey@linux.de)
29 .\" Modified 2001-11-13, aeb
30 .\" Modified 2001-12-13, joey, aeb
31 .\" Modified 2004-11-16, mtk
33 .TH CTIME 3 2008-09-26 "" "Linux Programmer's Manual"
35 asctime, ctime, gmtime, localtime, mktime, asctime_r, ctime_r, gmtime_r,
36 localtime_r \- transform date and time to broken-down time or ASCII
41 .BI "char *asctime(const struct tm *" tm );
43 .BI "char *asctime_r(const struct tm *" tm ", char *" buf );
45 .BI "char *ctime(const time_t *" timep );
47 .BI "char *ctime_r(const time_t *" timep ", char *" buf );
49 .BI "struct tm *gmtime(const time_t *" timep );
51 .BI "struct tm *gmtime_r(const time_t *" timep ", struct tm *" result );
53 .BI "struct tm *localtime(const time_t *" timep );
55 .BI "struct tm *localtime_r(const time_t *" timep ", struct tm *" result );
57 .BI "time_t mktime(struct tm *" tm );
61 Feature Test Macro Requirements for glibc (see
62 .BR feature_test_macros (7)):
70 _POSIX_C_SOURCE\ >=\ 1 || _XOPEN_SOURCE || _BSD_SOURCE ||
71 _SVID_SOURCE || _POSIX_SOURCE
79 an argument of data type \fItime_t\fP which represents calendar time.
80 When interpreted as an absolute time value, it represents the number of
81 seconds elapsed since 00:00:00 on January 1, 1970, Coordinated Universal
88 functions both take an argument
89 representing broken-down time which is a representation
90 separated into year, month, day, etc.
92 Broken-down time is stored
93 in the structure \fItm\fP which is defined in \fI<time.h>\fP as follows:
98 int tm_sec; /* seconds */
99 int tm_min; /* minutes */
100 int tm_hour; /* hours */
101 int tm_mday; /* day of the month */
102 int tm_mon; /* month */
103 int tm_year; /* year */
104 int tm_wday; /* day of the week */
105 int tm_yday; /* day in the year */
106 int tm_isdst; /* daylight saving time */
111 The members of the \fItm\fP structure are:
114 The number of seconds after the minute, normally in the range 0 to 59,
115 but can be up to 60 to allow for leap seconds.
118 The number of minutes after the hour, in the range 0 to 59.
121 The number of hours past midnight, in the range 0 to 23.
124 The day of the month, in the range 1 to 31.
127 The number of months since January, in the range 0 to 11.
130 The number of years since 1900.
133 The number of days since Sunday, in the range 0 to 6.
136 The number of days since January 1, in the range 0 to 365.
139 A flag that indicates whether daylight saving time is in effect at the
141 The value is positive if daylight saving time is in
142 effect, zero if it is not, and negative if the information is not
148 .BI asctime(localtime( t )) \fR.
149 It converts the calendar time \fIt\fP into a
150 null-terminated string of the form
153 "Wed Jun 30 21:49:08 1993\\n"
156 The abbreviations for the days of the week are "Sun", "Mon", "Tue", "Wed",
157 "Thu", "Fri", and "Sat".
158 The abbreviations for the months are "Jan",
159 "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", and
161 The return value points to a statically allocated string which
162 might be overwritten by subsequent calls to any of the date and time
164 The function also sets the external
165 variables \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP (see
167 with information about the current timezone.
168 The reentrant version
170 does the same, but stores the
171 string in a user-supplied buffer
172 which should have room for at least 26 bytes.
174 set \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP.
178 function converts the calendar time \fItimep\fP to
179 broken-down time representation, expressed in Coordinated Universal Time
181 It may return NULL when the year does not fit into an integer.
182 The return value points to a statically allocated struct which might be
183 overwritten by subsequent calls to any of the date and time functions.
186 function does the same, but stores the data in a
187 user-supplied struct.
191 function converts the calendar time \fItimep\fP to
192 broken-time representation, expressed relative to the user's specified
194 The function acts as if it called
196 and sets the external variables \fItzname\fP with
197 information about the current timezone, \fItimezone\fP with the difference
198 between Coordinated Universal Time (UTC) and local standard time in
199 seconds, and \fIdaylight\fP to a non-zero value if daylight savings
200 time rules apply during some part of the year.
201 The return value points to a statically allocated struct which might be
202 overwritten by subsequent calls to any of the date and time functions.
205 function does the same, but stores the data in a
206 user-supplied struct.
207 It need not set \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP.
211 function converts the broken-down time value
212 \fItm\fP into a null-terminated string with the same format as
214 The return value points to a statically allocated string which might be
215 overwritten by subsequent calls to any of the date and time functions.
218 function does the same, but stores the string in
219 a user-supplied buffer which should have room for at least 26 bytes.
223 function converts a broken-down time structure, expressed
224 as local time, to calendar time representation.
226 the values supplied by the caller in the
231 The value specified in the
235 whether or not daylight saving time (DST)
236 is in effect for the time supplied in the
239 a positive value means DST is in effect;
240 zero means that DST is not in effect;
241 and a negative value means that
243 should (use timezone information and system databases to)
244 attempt to determine whether DST is in effect at the specified time.
248 function modifies the fields of the
250 structure as follows:
254 are set to values determined from the contents of the other fields;
255 if structure members are outside their valid interval, they will be
256 normalized (so that, for example, 40 October is changed into 9 November);
258 is set (regardless of its initial value)
259 to a positive value or to 0, respectively,
260 to indicate whether DST is or is not in effect at the specified time.
263 also sets the external variable \fItzname\fP with
264 information about the current timezone.
266 If the specified broken-down
267 time cannot be represented as calendar time (seconds since the Epoch),
271 and does not alter the
272 members of the broken-down time structure.
274 Each of these functions returns the value described, or NULL
277 in case an error was detected.
301 return a pointer to static data and hence are not thread-safe.
308 are specified by SUSv2, and available since libc 5.2.5.
317 functions shall return values in one of two static objects:
318 a broken-down time structure and an array of type
320 Execution of any of the functions may overwrite the information returned
321 in either of these objects by any of the other functions."
322 This can occur in the glibc implementation.
324 In many implementations, including glibc, a 0 in
326 is interpreted as meaning the last day of the preceding month.
328 The glibc version of \fIstruct tm\fP has additional fields
332 long tm_gmtoff; /* Seconds east of UTC */
333 const char *tm_zone; /* Timezone abbreviation */
339 was set before including
341 This is a BSD extension, present in 4.3BSD-Reno.
343 According to POSIX.1-2004,
345 is required to behave as though
349 does not have this requirement.
350 .\" See http://thread.gmane.org/gmane.comp.time.tz/2034/
353 should be called before
357 .BR gettimeofday (2),
projects / thirdparty / man-pages.git / blob