1CTIME(3) Linux Programmer's Manual CTIME(3)
2
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
11 #include <time.h>
12 char *asctime(const struct tm *tm);
14 char *asctime_r(const struct tm *tm, char *buf);
15 char *ctime(const time_t *timep);
17 char *ctime_r(const time_t *timep, char *buf);
18 struct tm *gmtime(const time_t *timep);
20 struct tm *gmtime_r(const time_t *timep, struct tm *result);
21 struct tm *localtime(const time_t *timep);
23 struct tm *localtime_r(const time_t *timep, struct tm *result);
24 time_t mktime(struct tm *tm);
26
28 The ctime(), gmtime() and localtime() functions all take an argument of
29 data type time_t which represents calendar time. When interpreted as
30 an absolute time value, it represents the number of seconds elapsed
31 since 00:00:00 on January 1, 1970, Coordinated Universal Time (UTC).
32 The asctime() and mktime() functions both take an argument representing
34 broken-down time which is a representation separated into year, month,
35 day, etc.
36 Broken-down time is stored in the structure tm which is defined in
38 <time.h> as follows:
39 struct tm {
41 int tm_sec; /* seconds */
42 int tm_min; /* minutes */
43 int tm_hour; /* hours */
44 int tm_mday; /* day of the month */
45 int tm_mon; /* month */
46 int tm_year; /* year */
47 int tm_wday; /* day of the week */
48 int tm_yday; /* day in the year */
49 int tm_isdst; /* daylight saving time */
50 };
51 The members of the tm structure are:
53 tm_sec The number of seconds after the minute, normally in the range 0
55 to 59, but can be up to 60 to allow for leap seconds.
56 tm_min The number of minutes after the hour, in the range 0 to 59.
58 tm_hour
60 The number of hours past midnight, in the range 0 to 23.
61 tm_mday
63 The day of the month, in the range 1 to 31.
64 tm_mon The number of months since January, in the range 0 to 11.
66 tm_year
68 The number of years since 1900.
69 tm_wday
71 The number of days since Sunday, in the range 0 to 6.
72 tm_yday
74 The number of days since January 1, in the range 0 to 365.
75 tm_isdst
77 A flag that indicates whether daylight saving time is in effect
78 at the time described. The value is positive if daylight saving
79 time is in effect, zero if it is not, and negative if the infor‐
80 mation is not available.
81 The call ctime(t) is equivalent to asctime(localtime(t)). It converts
83 the calendar time t into a string of the form
84 "Wed Jun 30 21:49:08 1993\n"
86 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 variable
93 tzname (see tzset(3)) with information about the current time zone.
94 The re-entrant version ctime_r() does the same, but stores the string
95 in a user-supplied buffer of length at least 26. It need not set
96 tzname.
97 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 The localtime() function converts the calendar time timep to broken-
107 time representation, expressed relative to the user's specified time
108 zone. The function acts as if it called tzset(3) and sets the exter‐
109 nal variables tzname with information about the current time zone,
110 timezone with the difference between Coordinated Universal Time (UTC)
111 and local standard time in seconds, and daylight to a non-zero 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.
117 The asctime() function converts the broken-down time value tm into a
119 string with the same format as ctime(). The return value points to a
120 statically allocated string which might be overwritten by subsequent
121 calls to any of the date and time functions. The asctime_r() function
122 does the same, but stores the string in a user-supplied buffer of
123 length at least 26.
124 The mktime() function converts a broken-down time structure, expressed
126 as local time, to calendar time representation. The function ignores
127 the specified contents of the structure members tm_wday and tm_yday and
128 recomputes them from the other information in the broken-down time
129 structure. If structure members are outside their legal interval, they
130 will be normalized (so that, e.g., 40 October is changed into 9 Novem‐
131 ber). Calling mktime() also sets the external variable tzname with
132 information about the current time zone. If the specified broken-down
133 time cannot be represented as calendar time (seconds since the epoch),
134 mktime() returns a value of (time_t)(-1) and does not alter the tm_wday
135 and tm_yday members of the broken-down time structure.
136
138 Each of these functions returns the value described, or NULL (-1 in
139 case of mktime()) in case an error was detected.
140
142 The four functions asctime(), ctime(), gmtime() and localtime() return
143 a pointer to static data and hence are not thread-safe. Thread-safe
144 versions asctime_r(), ctime_r(), gmtime_r() and localtime_r() are spec‐
145 ified by SUSv2, and available since libc 5.2.5.
146 In many implementations, including glibc, a 0 in tm_mday is interpreted
148 as meaning the last day of the preceding month.
149 The glibc version of struct tm has additional fields
151 long tm_gmtoff; /* Seconds east of UTC */
153 const char *tm_zone; /* Timezone abbreviation */
154 defined when _BSD_SOURCE was set before including <time.h>. This is a
156 BSD extension, present in 4.3BSD-Reno.
157
159 POSIX.1-2001. C89 and C99 specify asctime(), ctime(), gmtime(), local‐
160 time(), and mktime()
161
163 date(1), gettimeofday(2), time(2), utime(2), clock(3), difftime(3),
164 strftime(3), strptime(3), tzset(3), time(7)
165 2004-11-16 CTIME(3)