1CTIME(3)                   Linux Programmer's Manual                  CTIME(3)
2
3
4

NAME

6       asctime,   ctime,   gmtime,   localtime,  mktime,  asctime_r,  ctime_r,
7       gmtime_r, localtime_r - transform date and time to broken-down time  or
8       ASCII
9

SYNOPSIS

11       #include <time.h>
12
13       char *asctime(const struct tm *tm);
14       char *asctime_r(const struct tm *tm, char *buf);
15
16       char *ctime(const time_t *timep);
17       char *ctime_r(const time_t *timep, char *buf);
18
19       struct tm *gmtime(const time_t *timep);
20       struct tm *gmtime_r(const time_t *timep, struct tm *result);
21
22       struct tm *localtime(const time_t *timep);
23       struct tm *localtime_r(const time_t *timep, struct tm *result);
24
25       time_t mktime(struct tm *tm);
26
27   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
28
29       asctime_r(), ctime_r(), gmtime_r(), localtime_r():
30              _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _BSD_SOURCE ||
31              _SVID_SOURCE || _POSIX_SOURCE
32

DESCRIPTION

34       The ctime(), gmtime() and localtime() functions all take an argument of
35       data  type  time_t which represents calendar time.  When interpreted as
36       an absolute time value, it represents the  number  of  seconds  elapsed
37       since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).
38
39       The asctime() and mktime() functions both take an argument representing
40       broken-down time which is a representation separated into year,  month,
41       day, and so on.
42
43       Broken-down  time  is  stored  in  the structure tm which is defined in
44       <time.h> as follows:
45
46           struct tm {
47               int tm_sec;         /* seconds */
48               int tm_min;         /* minutes */
49               int tm_hour;        /* hours */
50               int tm_mday;        /* day of the month */
51               int tm_mon;         /* month */
52               int tm_year;        /* year */
53               int tm_wday;        /* day of the week */
54               int tm_yday;        /* day in the year */
55               int tm_isdst;       /* daylight saving time */
56           };
57
58       The members of the tm structure are:
59
60       tm_sec    The number of seconds after the minute, normally in the range
61                 0 to 59, but can be up to 60 to allow for leap seconds.
62
63       tm_min    The number of minutes after the hour, in the range 0 to 59.
64
65       tm_hour   The number of hours past midnight, in the range 0 to 23.
66
67       tm_mday   The day of the month, in the range 1 to 31.
68
69       tm_mon    The number of months since January, in the range 0 to 11.
70
71       tm_year   The number of years since 1900.
72
73       tm_wday   The number of days since Sunday, in the range 0 to 6.
74
75       tm_yday   The number of days since January 1, in the range 0 to 365.
76
77       tm_isdst  A  flag  that  indicates  whether  daylight saving time is in
78                 effect at the time described.  The value is positive if  day‐
79                 light  saving time is in effect, zero if it is not, and nega‐
80                 tive if the information is not available.
81
82       The call ctime(t) is equivalent to asctime(localtime(t)).  It  converts
83       the calendar time t into a null-terminated string of the form
84
85              "Wed Jun 30 21:49:08 1993\n"
86
87       The  abbreviations  for  the  days of the week are "Sun", "Mon", "Tue",
88       "Wed", "Thu", "Fri", and "Sat".  The abbreviations for the  months  are
89       "Jan",  "Feb",  "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct",
90       "Nov", and "Dec".  The return value points to  a  statically  allocated
91       string  which  might  be  overwritten by subsequent calls to any of the
92       date and time functions.  The function also sets the external variables
93       tzname,  timezone,  and  daylight (see tzset(3)) with information about
94       the current timezone.  The reentrant version ctime_r() does  the  same,
95       but  stores the string in a user-supplied buffer which should have room
96       for at least 26 bytes.  It need not set tzname, timezone, and daylight.
97
98       The gmtime() function converts the calendar time timep  to  broken-down
99       time representation, expressed in Coordinated Universal Time (UTC).  It
100       may return NULL when the year does not fit into an integer.  The return
101       value  points to a statically allocated struct which might be overwrit‐
102       ten by subsequent calls to any of the date  and  time  functions.   The
103       gmtime_r()  function  does the same, but stores the data in a user-sup‐
104       plied struct.
105
106       The localtime() function converts the calendar time  timep  to  broken-
107       down  time  representation,  expressed relative to the user's specified
108       timezone.  The function acts as if it  called  tzset(3)  and  sets  the
109       external  variables tzname with information about the current timezone,
110       timezone with the difference between Coordinated Universal  Time  (UTC)
111       and  local standard time in seconds, and daylight to a nonzero value if
112       daylight savings time rules apply during some part of  the  year.   The
113       return  value  points  to  a statically allocated struct which might be
114       overwritten by subsequent calls to any of the date and time  functions.
115       The  localtime_r()  function  does  the  same, but stores the data in a
116       user-supplied struct.  It need not set tzname, timezone, and daylight.
117
118       The asctime() function converts the broken-down time value  tm  into  a
119       null-terminated  string  with  the  same format as ctime().  The return
120       value points to a statically allocated string which might be  overwrit‐
121       ten  by  subsequent  calls  to any of the date and time functions.  The
122       asctime_r() function does the same, but stores the string  in  a  user-
123       supplied buffer which should have room for at least 26 bytes.
124
125       The  mktime() function converts a broken-down time structure, expressed
126       as local time, to calendar time representation.  The  function  ignores
127       the  values  supplied  by the caller in the tm_wday and tm_yday fields.
128       The value specified in the tm_isdst field informs mktime()  whether  or
129       not  daylight  saving  time (DST) is in effect for the time supplied in
130       the tm structure: a positive value means DST is in effect;  zero  means
131       that  DST  is  not  in effect; and a negative value means that mktime()
132       should (use timezone information and system databases  to)  attempt  to
133       determine whether DST is in effect at the specified time.
134
135       The  mktime()  function modifies the fields of the tm structure as fol‐
136       lows: tm_wday and tm_yday are set to values determined  from  the  con‐
137       tents of the other fields; if structure members are outside their valid
138       interval, they will be normalized (so that, for example, 40 October  is
139       changed  into  9  November); tm_isdst is set (regardless of its initial
140       value) to a positive value or to 0, respectively, to  indicate  whether
141       DST  is  or  is  not in effect at the specified time.  Calling mktime()
142       also sets the external variable tzname with information about the  cur‐
143       rent timezone.
144
145       If  the  specified  broken-down  time cannot be represented as calendar
146       time (seconds since the Epoch), mktime() returns (time_t) -1  and  does
147       not alter the members of the broken-down time structure.
148

RETURN VALUE

150       Each  of  these  functions  returns the value described, or NULL (-1 in
151       case of mktime()) in case an error was detected.
152

CONFORMING TO

154       POSIX.1-2001.  C89 and C99 specify asctime(), ctime(), gmtime(), local‐
155       time(),  and  mktime().   POSIX.1-2008  marks  asctime(),  asctime_r(),
156       ctime(), and ctime_r() as obsolete, recommending the use of strftime(3)
157       instead.
158

NOTES

160       The  four functions asctime(), ctime(), gmtime() and localtime() return
161       a pointer to static data and hence are  not  thread-safe.   Thread-safe
162       versions asctime_r(), ctime_r(), gmtime_r() and localtime_r() are spec‐
163       ified by SUSv2, and available since libc 5.2.5.
164
165       POSIX.1-2001 says: "The asctime(), ctime(), gmtime(),  and  localtime()
166       functions  shall  return values in one of two static objects: a broken-
167       down time structure and an array of type char.  Execution of any of the
168       functions  may  overwrite  the  information returned in either of these
169       objects by any of the other functions."  This can occur  in  the  glibc
170       implementation.
171
172       In many implementations, including glibc, a 0 in tm_mday is interpreted
173       as meaning the last day of the preceding month.
174
175       The glibc version of struct tm has additional fields
176
177              long tm_gmtoff;           /* Seconds east of UTC */
178              const char *tm_zone;      /* Timezone abbreviation */
179
180       defined when _BSD_SOURCE was set before including <time.h>.  This is  a
181       BSD extension, present in 4.3BSD-Reno.
182
183       According  to POSIX.1-2004, localtime() is required to behave as though
184       tzset(3) was called, while localtime_r() does not  have  this  require‐
185       ment.   For  portable  code  tzset(3)  should  be  called before local‐
186       time_r().
187

SEE ALSO

189       date(1), gettimeofday(2),  time(2),  utime(2),  clock(3),  difftime(3),
190       strftime(3), strptime(3), timegm(3), tzset(3), time(7)
191

COLOPHON

193       This  page  is  part of release 3.53 of the Linux man-pages project.  A
194       description of the project, and information about reporting  bugs,  can
195       be found at http://www.kernel.org/doc/man-pages/.
196
197
198
199                                  2010-02-25                          CTIME(3)
Impressum