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
31                  || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_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 (0-60) */
48               int tm_min;    /* Minutes (0-59) */
49               int tm_hour;   /* Hours (0-23) */
50               int tm_mday;   /* Day of the month (1-31) */
51               int tm_mon;    /* Month (0-11) */
52               int tm_year;   /* Year - 1900 */
53               int tm_wday;   /* Day of the week (0-6, Sunday = 0) */
54               int tm_yday;   /* Day in the year (0-365, 1 Jan = 0) */
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           ,in
87
88       The abbreviations for the days of the week  are  "Sun",  "Mon",  "Tue",
89       "Wed",  "Thu",  "Fri", and "Sat".  The abbreviations for the months are
90       "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug",  "Sep",  "Oct",
91       "Nov",  and  "Dec".   The return value points to a statically allocated
92       string which might be overwritten by subsequent calls  to  any  of  the
93       date and time functions.  The function also sets the external variables
94       tzname, timezone, and daylight (see tzset(3))  with  information  about
95       the  current  timezone.  The reentrant version ctime_r() does the same,
96       but stores the string in a user-supplied buffer which should have  room
97       for at least 26 bytes.  It need not set tzname, timezone, and daylight.
98
99       The  gmtime()  function converts the calendar time timep to broken-down
100       time representation, expressed in Coordinated Universal Time (UTC).  It
101       may return NULL when the year does not fit into an integer.  The return
102       value points to a statically allocated struct which might be  overwrit‐
103       ten  by  subsequent  calls  to any of the date and time functions.  The
104       gmtime_r() function does the same, but stores the data in  a  user-sup‐
105       plied struct.
106
107       The  localtime()  function  converts the calendar time timep to broken-
108       down time representation, expressed relative to  the  user's  specified
109       timezone.   The  function  acts  as  if it called tzset(3) and sets the
110       external variables tzname with information about the current  timezone,
111       timezone  with  the difference between Coordinated Universal Time (UTC)
112       and local standard time in seconds, and daylight to a nonzero value  if
113       daylight  savings  time  rules apply during some part of the year.  The
114       return value points to a statically allocated  struct  which  might  be
115       overwritten  by subsequent calls to any of the date and time functions.
116       The localtime_r() function does the same, but  stores  the  data  in  a
117       user-supplied struct.  It need not set tzname, timezone, and daylight.
118
119       The  asctime()  function  converts the broken-down time value tm into a
120       null-terminated string with the same format  as  ctime().   The  return
121       value  points to a statically allocated string which might be overwrit‐
122       ten by subsequent calls to any of the date  and  time  functions.   The
123       asctime_r()  function  does  the same, but stores the string in a user-
124       supplied buffer which should have room for at least 26 bytes.
125
126       The mktime() function converts a broken-down time structure,  expressed
127       as  local  time, to calendar time representation.  The function ignores
128       the values supplied by the caller in the tm_wday  and  tm_yday  fields.
129       The  value  specified in the tm_isdst field informs mktime() whether or
130       not daylight saving time (DST) is in effect for the  time  supplied  in
131       the  tm  structure: a positive value means DST is in effect; zero means
132       that DST is not in effect; and a negative  value  means  that  mktime()
133       should  (use  timezone  information and system databases to) attempt to
134       determine whether DST is in effect at the specified time.
135
136       The mktime() function modifies the fields of the tm structure  as  fol‐
137       lows:  tm_wday  and  tm_yday are set to values determined from the con‐
138       tents of the other fields; if structure members are outside their valid
139       interval,  they will be normalized (so that, for example, 40 October is
140       changed into 9 November); tm_isdst is set (regardless  of  its  initial
141       value)  to  a positive value or to 0, respectively, to indicate whether
142       DST is or is not in effect at the  specified  time.   Calling  mktime()
143       also  sets the external variable tzname with information about the cur‐
144       rent timezone.
145
146       If the specified broken-down time cannot  be  represented  as  calendar
147       time  (seconds  since the Epoch), mktime() returns (time_t) -1 and does
148       not alter the members of the broken-down time structure.
149

RETURN VALUE

151       On success, gmtime() and localtime() return a pointer to a struct tm.
152
153       On success, gmtime_r() and localtime_r()  return  the  address  of  the
154       structure pointed to by result.
155
156       On success, asctime() and ctime() return a pointer to a string.
157
158       On  success,  asctime_r()  and ctime_r() return a pointer to the string
159       pointed to by buf.
160
161       On success, mktime() returns  the  calendar  time  (seconds  since  the
162       Epoch), expressed as a value of type time_t.
163
164       On  error, mktime() returns the value (time_t) -1.  The remaining func‐
165       tions return NULL on error.  On error, errno is  set  to  indicate  the
166       cause of the error.
167

ERRORS

169       EOVERFLOW
170              The result cannot be represented.
171

ATTRIBUTES

173       For   an   explanation   of   the  terms  used  in  this  section,  see
174       attributes(7).
175
176       ┌───────────────┬───────────────┬─────────────────────────────────┐
177Interface      Attribute     Value                           
178       ├───────────────┼───────────────┼─────────────────────────────────┤
179asctime()      │ Thread safety │ MT-Unsafe race:asctime locale   │
180       ├───────────────┼───────────────┼─────────────────────────────────┤
181asctime_r()    │ Thread safety │ MT-Safe locale                  │
182       ├───────────────┼───────────────┼─────────────────────────────────┤
183ctime()        │ Thread safety │ MT-Unsafe race:tmbuf            │
184       │               │               │ race:asctime env locale         │
185       ├───────────────┼───────────────┼─────────────────────────────────┤
186ctime_r(),     │ Thread safety │ MT-Safe env locale              │
187gmtime_r(),    │               │                                 │
188localtime_r(), │               │                                 │
189mktime()       │               │                                 │
190       ├───────────────┼───────────────┼─────────────────────────────────┤
191gmtime(),      │ Thread safety │ MT-Unsafe race:tmbuf env locale │
192localtime()    │               │                                 │
193       └───────────────┴───────────────┴─────────────────────────────────┘

CONFORMING TO

195       POSIX.1-2001.  C89 and C99 specify asctime(), ctime(), gmtime(), local‐
196       time(),  and  mktime().   POSIX.1-2008  marks  asctime(),  asctime_r(),
197       ctime(), and ctime_r() as obsolete, recommending the use of strftime(3)
198       instead.
199

NOTES

201       The  four functions asctime(), ctime(), gmtime() and localtime() return
202       a pointer to static data and hence are not  thread-safe.   The  thread-
203       safe  versions,  asctime_r(),  ctime_r(), gmtime_r() and localtime_r(),
204       are specified by SUSv2.
205
206       POSIX.1-2001 says: "The asctime(), ctime(), gmtime(),  and  localtime()
207       functions  shall  return values in one of two static objects: a broken-
208       down time structure and an array of type char.  Execution of any of the
209       functions  may  overwrite  the  information returned in either of these
210       objects by any of the other functions."  This can occur  in  the  glibc
211       implementation.
212
213       In many implementations, including glibc, a 0 in tm_mday is interpreted
214       as meaning the last day of the preceding month.
215
216       The glibc version of struct tm has additional fields
217
218           const char *tm_zone;      /* Timezone abbreviation */
219
220       defined when _BSD_SOURCE was set before including <time.h>.  This is  a
221       BSD extension, present in 4.3BSD-Reno.
222
223       According  to POSIX.1-2004, localtime() is required to behave as though
224       tzset(3) was called, while localtime_r() does not  have  this  require‐
225       ment.   For  portable  code,  tzset(3)  should  be called before local‐
226       time_r().
227

SEE ALSO

229       date(1), gettimeofday(2),  time(2),  utime(2),  clock(3),  difftime(3),
230       strftime(3), strptime(3), timegm(3), tzset(3), time(7)
231

COLOPHON

233       This  page  is  part of release 4.15 of the Linux man-pages project.  A
234       description of the project, information about reporting bugs,  and  the
235       latest     version     of     this    page,    can    be    found    at
236       https://www.kernel.org/doc/man-pages/.
237
238
239
240                                  2017-09-15                          CTIME(3)
Impressum