1ctime(3C) Standard C Library Functions ctime(3C)
2
6 ctime, ctime_r, localtime, localtime_r, gmtime, gmtime_r, asctime, asc‐
7 time_r, tzset - convert date and time to string
8
10 #include <time.h>
11 char *ctime(const time_t *clock);
13 struct tm *localtime(const time_t *clock);
16 struct tm *gmtime(const time_t *clock);
19 char *asctime(const struct tm *tm);
22 extern time_t timezone, altzone;
25 extern int daylight;
26 extern char *tzname[2];
27 void tzset(void);
29 char *ctime_r(const time_t *clock, char *buf, int buflen);
32 struct tm *localtime_r(const time_t *restrict clock,
35 struct tm *restrict res);
36 struct tm *gmtime_r(const time_t *restrict clock,
39 struct tm *restrict res);
40 char *asctime_r(const struct tm *restrict tm, char *restrict buf,
43 int buflen);
44 Standard conforming
47 cc [ flag... ] file... -D_POSIX_PTHREAD_SEMANTICS [ library... ]
48 char *ctime_r(const time_t *clock, char *buf);
50 char *asctime_r(const struct tm *tm, char *buf);
53
56 The ctime() function converts the time pointed to by clock, represent‐
57 ing the time in seconds since the Epoch (00:00:00 UTC, January 1,
58 1970), to local time in the form of a 26-character string, as shown
59 below. Time zone and daylight savings corrections are made before
60 string generation. The fields are in constant width:
61 Fri Sep 13 00:00:00 1986\n\0
64 The ctime() function is equivalent to:
67 asctime(localtime(clock))
70 The ctime(), asctime(), gmtime(), and localtime() functions return val‐
73 ues in one of two thread-specific data objects: a broken-down time
74 structure and an array of char. Execution of any of the functions can
75 overwrite the information returned in either of these objects by any of
76 the other functions executed by the same thread.
77 The ctime_r() function has the same functionality as ctime() except
80 that the caller must supply a buffer buf with length buflen to store
81 the result; buf must be at least 26 bytes. The standard-conforming
82 ctime_r() function does not take a buflen parameter.
83 The localtime() and gmtime() functions return pointers to tm structures
86 (see below). The localtime() function corrects for the main time zone
87 and possible alternate ("daylight savings") time zone; the gmtime()
88 function converts directly to Coordinated Universal Time (UTC), which
89 is what the UNIX system uses internally.
90 The localtime_r() and gmtime_r() functions have the same functionality
93 as localtime() and gmtime() respectively, except that the caller must
94 supply a buffer res to store the result.
95 The asctime() function converts a tm structure to a 26-character
98 string, as shown in the previous example, and returns a pointer to the
99 string.
100 The asctime_r() function has the same functionality as asctime() except
103 that the caller must supply a buffer buf with length buflen for the
104 result to be stored. The buf argument must be at least 26 bytes. The
105 standard-conforming asctime_r() function does not take a buflen parame‐
106 ter. The asctime_r() function returns a pointer to buf upon success.
107 In case of failure, NULL is returned and errno is set.
108 Declarations of all the functions and externals, and the tm structure,
111 are in the <time.h> header. The members of the tm structure are:
112 int tm_sec; /* seconds after the minute — [0, 60] */
114 /* for leap seconds */
115 int tm_min; /* minutes after the hour — [0, 59] */
116 int tm_hour; /* hour since midnight — [0, 23] */
117 int tm_mday; /* day of the month — [1, 31] */
118 int tm_mon; /* months since January — [0, 11] */
119 int tm_year; /* years since 1900 */
120 int tm_wday; /* days since Sunday — [0, 6] */
121 int tm_yday; /* days since January 1 — [0, 365] */
122 int tm_isdst; /* flag for alternate daylight savings time */
123 The value of tm_isdst is positive if daylight savings time is in
127 effect, zero if daylight savings time is not in effect, and negative if
128 the information is not available. Previously, the value of tm_isdst was
129 defined as non-zero if daylight savings was in effect.
130 The external time_t variable altzone contains the difference, in sec‐
133 onds, between Coordinated Universal Time and the alternate time zone.
134 The external variable timezone contains the difference, in seconds,
135 between UTC and local standard time. The external variable daylight
136 indicates whether time should reflect daylight savings time. Both time‐
137 zone and altzone default to 0 (UTC). The external variable daylight is
138 non-zero if an alternate time zone exists. The time zone names are con‐
139 tained in the external variable tzname, which by default is set to:
140 char *tzname[2] = { "GMT", "" };
143 These functions know about the peculiarities of this conversion for
146 various time periods for the U.S. (specifically, the years 1974, 1975,
147 and 1987). They start handling the new daylight savings time starting
148 with the first Sunday in April, 1987.
149 The tzset() function uses the contents of the environment variable TZ
152 to override the value of the different external variables. It is called
153 by asctime() and can also be called by the user. If TZ is not specified
154 or has an invalid setting, tzset() uses GMT0. See environ(5) for a
155 description of the TZ environment variable.
156 Starting and ending times are relative to the current local time zone.
159 If the alternate time zone start and end dates and the time are not
160 provided, the days for the United States that year will be used and the
161 time will be 2 AM. If the start and end dates are provided but the time
162 is not provided, the time will be 2 AM. The effects of tzset() change
163 the values of the external variables timezone, altzone, daylight, and
164 tzname.
165 Note that in most installations, TZ is set to the correct value by
168 default when the user logs on, using the local /etc/default/init file
169 (see TIMEZONE(4)).
170
172 Upon successful completion, the gmtime() and localtime() functions
173 return a pointer to a struct tm. If an error is detected, gmtime() and
174 localtime() return a null pointer.
175 Upon successful completion, the gmtime_r() and localtime_r() functions
178 return the address of the structure pointed to by the res argument. If
179 an error is detected, gmtime_r() and localtime_r() return a null
180 pointer and set errno to indicate the error.
181
183 The ctime_r() and asctime_r() functions will fail if:
184 ERANGE The length of the buffer supplied by the caller is not large
186 enough to store the result.
187 The gmtime(), gmtime_r(), localtime(), and localtime_r() functions will
191 fail if:
192 EOVERFLOW The result cannot be represented.
194
197 These functions do not support localized date and time formats. The
198 strftime(3C) function can be used when localization is required.
199 The localtime(), localtime_r(), gmtime(), gmtime_r(), ctime(), and
202 ctime_r() functions assume Gregorian dates. Times before the adoption
203 of the Gregorian calendar will not match historial records.
204
206 Example 1 Examples of the tzset() function.
207 The tzset() function scans the contents of the environment variable and
210 assigns the different fields to the respective variable. For example,
211 the most complete setting for New Jersey in 1986 could be:
212 EST5EDT4,116/2:00:00,298/2:00:00
215 or simply
219 EST5EDT
222 An example of a southern hemisphere setting such as the Cook Islands
226 could be
227 KDT9:30KST10:00,63/5:00,302/20:00
230 In the longer version of the New Jersey example of TZ, tzname[0] is
234 EST, timezone is set to 5*60*60, tzname[1] is EDT, altzone is set to
235 4*60*60, the starting date of the alternate time zone is the 117th day
236 at 2 AM, the ending date of the alternate time zone is the 299th day at
237 2 AM (using zero-based Julian days), and daylight is set positive.
238 Starting and ending times are relative to the current local time zone.
239 If the alternate time zone start and end dates and the time are not
240 provided, the days for the United States that year will be used and the
241 time will be 2 AM. If the start and end dates are provided but the time
242 is not provided, the time will be 2 AM. The effects of tzset() are thus
243 to change the values of the external variables timezone, altzone, day‐
244 light, and tzname. The ctime(), localtime(), mktime(), and strftime()
245 functions also update these external variables as if they had called
246 tzset() at the time specified by the time_t or struct tm value that
247 they are converting.
248
251 The zoneinfo timezone data files do not transition past Tue Jan 19
252 03:14:07 2038 UTC. Therefore for 64-bit applications using zoneinfo
253 timezones, calculations beyond this date might not use the correct off‐
254 set from standard time, and could return incorrect values. This affects
255 the 64-bit version of localtime(), localtime_r(), ctime(), and
256 ctime_r().
257
259 See attributes(5) for descriptions of the following attributes:
260 ┌─────────────────────────────┬─────────────────────────────┐
265 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
266 ├─────────────────────────────┼─────────────────────────────┤
267 │CSI │Enabled │
268 ├─────────────────────────────┼─────────────────────────────┤
269 │Interface Stability │Standard │
270 ├─────────────────────────────┼─────────────────────────────┤
271 │MT-Level │MT-Safe with exceptions │
272 └─────────────────────────────┴─────────────────────────────┘
273 The asctime(), ctime(), gmtime(), and localtime() functions are safe to
276 use in multithread applications because they employ thread-specific
277 data. However, their use is discouraged because standards do not
278 require them to be thread-safe. The asctime_r() and gmtime_r() func‐
279 tions are MT-Safe. The ctime_r(), localtime_r(), and tzset() functions
280 are MT-Safe in multithread applications, as long as no user-defined
281 function directly modifies one of the following variables: timezone,
282 altzone, daylight, and tzname. These four variables are not MT-Safe to
283 access. They are modified by the tzset() function in an MT-Safe manner.
284 The mktime(), localtime_r(), and ctime_r() functions call tzset().
285
287 time(2), Intro(3), getenv(3C), mktime(3C), printf(3C), putenv(3C), set‐
288 locale(3C), strftime(3C), TIMEZONE(4), attributes(5), environ(5), stan‐
289 dards(5)
290
292 When compiling multithreaded programs, see Intro(3).
293 The return values for asctime(), ctime(), gmtime(), and localtime()
296 point to thread-specific data whose content is overwritten by each call
297 by the same thread.
298 Setting the time during the interval of change from timezone to altzone
301 or vice versa can produce unpredictable results. The system administra‐
302 tor must change the Julian start and end days annually.
303 If tzset() has previously evaluated the timezone identified by the
306 value of the TZ environment variable, tzset() can reuse the previous
307 settings of the external variables altzone, daylight, timezone, and
308 tzname[] associated with that timezone.
309 Solaris 2.4 and earlier releases provided definitions of the ctime_r(),
312 localtime_r(), gmtime_r(), and asctime_r() functions as specified in
313 POSIX.1c Draft 6. The final POSIX.1c standard changed the interface for
314 ctime_r() and asctime_r(). Support for the Draft 6 interface is pro‐
315 vided for compatibility only and might not be supported in future
316 releases. New applications and libraries should use the standard-con‐
317 forming interface.
318 For POSIX.1c-conforming applications, the _POSIX_PTHREAD_SEMANTICS and
321 _REENTRANT flags are automatically turned on by defining the
322 _POSIX_C_SOURCE flag with a value >= 199506L.
323 In Solaris 10, gmtime(), gmtime_r(), localtime(), and localtime_r()
326 were updated to return a null pointer if an error is detected. This
327 change was based on the SUSv3 specification. See standards(5).
328SunOS 5.11 27 May 2005 ctime(3C)