1ctime(3C)                Standard C Library Functions                ctime(3C)
2
3
4

NAME

6       ctime, ctime_r, localtime, localtime_r, gmtime, gmtime_r, asctime, asc‐
7       time_r, tzset - convert date and time to string
8

SYNOPSIS

10       #include <time.h>
11
12       char *ctime(const time_t *clock);
13
14
15       struct tm *localtime(const time_t *clock);
16
17
18       struct tm *gmtime(const time_t *clock);
19
20
21       char *asctime(const struct tm *tm);
22
23
24       extern time_t timezone, altzone;
25       extern int daylight;
26       extern char *tzname[2];
27
28       void tzset(void);
29
30
31       char *ctime_r(const time_t *clock, char *buf, int buflen);
32
33
34       struct tm *localtime_r(const time_t *restrict clock,
35            struct tm *restrict res);
36
37
38       struct tm *gmtime_r(const time_t *restrict clock,
39            struct tm *restrict res);
40
41
42       char *asctime_r(const struct tm *restrict tm, char *restrict buf,
43            int buflen);
44
45
46   Standard conforming
47       cc [ flag... ] file... -D_POSIX_PTHREAD_SEMANTICS [ library... ]
48
49       char *ctime_r(const time_t *clock, char *buf);
50
51
52       char *asctime_r(const struct tm *tm, char *buf);
53
54

DESCRIPTION

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
62
63       Fri Sep 13 00:00:00 1986\n\0
64
65
66       The ctime() function is equivalent to:
67
68
69       asctime(localtime(clock))
70
71
72       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
78
79       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
84
85       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
91
92       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
96
97       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
101
102       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
109
110       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
113         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
124
125
126       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
131
132       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
141
142       char *tzname[2] = { "GMT", "" };
143
144
145       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
150
151       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
157
158       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
166
167       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

RETURN VALUES

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
176
177       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

ERRORS

183       The ctime_r() and asctime_r() functions will fail if:
184
185       ERANGE    The  length of the buffer supplied by the caller is not large
186                 enough to store the result.
187
188
189
190       The gmtime(), gmtime_r(), localtime(), and localtime_r() functions will
191       fail if:
192
193       EOVERFLOW    The result cannot be represented.
194
195

USAGE

197       These  functions  do  not  support localized date and time formats. The
198       strftime(3C) function can be used when localization is required.
199
200
201       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

EXAMPLES

206       Example 1 Examples of the tzset() function.
207
208
209       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
213
214         EST5EDT4,116/2:00:00,298/2:00:00
215
216
217
218       or simply
219
220
221         EST5EDT
222
223
224
225       An example of a southern hemisphere setting such as  the  Cook  Islands
226       could be
227
228
229         KDT9:30KST10:00,63/5:00,302/20:00
230
231
232
233       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
249

BUGS

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

ATTRIBUTES

259       See attributes(5) for descriptions of the following attributes:
260
261
262
263
264       ┌─────────────────────────────┬─────────────────────────────┐
265       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
266       ├─────────────────────────────┼─────────────────────────────┤
267       │CSI                          │Enabled                      │
268       ├─────────────────────────────┼─────────────────────────────┤
269       │Interface Stability          │Standard                     │
270       ├─────────────────────────────┼─────────────────────────────┤
271       │MT-Level                     │MT-Safe with exceptions      │
272       └─────────────────────────────┴─────────────────────────────┘
273
274
275       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

SEE ALSO

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

NOTES

292       When compiling multithreaded programs, see Intro(3).
293
294
295       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
299
300       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
304
305       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
310
311       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
319
320       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
324
325       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).
328
329
330
331SunOS 5.11                        27 May 2005                        ctime(3C)
Impressum