1CTIME(3)                   Library Functions Manual                   CTIME(3)
2
3
4

NAME

6       ctime, localtime, gmtime, asctime, timezone -  convert date and time to
7       ASCII
8

SYNOPSIS

10       char *ctime(clock)
11       long *clock;
12
13       #include <time.h>
14
15       struct tm *localtime(clock)
16       long *clock;
17
18       struct tm *gmtime(clock)
19       long *clock;
20
21       char *asctime(tm)
22       struct tm *tm;
23
24       char *timezone(zone, dst)
25

DESCRIPTION

27       Ctime converts a time pointed to by clock such as returned  by  time(2)
28       into  ASCII  and returns a pointer to a 26-character string in the fol‐
29       lowing form.  All the fields have constant width.
30
31           Sun Sep 16 01:03:52 1973\n\0
32
33       Localtime and gmtime return pointers to structures containing the  bro‐
34       ken-down  time.  Localtime corrects for the time zone and possible day‐
35       light savings time; gmtime converts directly to GMT, which is the  time
36       UNIX  uses.  Asctime converts a broken-down time to ASCII and returns a
37       pointer to a 26-character string.
38
39       The structure declaration from the include file is:
40
41              /* Copyright (C) 1991-2012 Free Software Foundation, Inc.
42                 This file is part of the GNU C Library.
43
44                 The GNU C Library is free software; you can redistribute it and/or
45                 modify it under the terms of the GNU Lesser General Public
46                 License as published by the Free Software Foundation; either
47                 version 2.1 of the License, or (at your option) any later version.
48
49                 The GNU C Library is distributed in the hope that it will be useful,
50                 but WITHOUT ANY WARRANTY; without even the implied warranty of
51                 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
52                 Lesser General Public License for more details.
53
54                 You should have received a copy of the GNU Lesser General Public
55                 License along with the GNU C Library; if not, see
56                 <http://www.gnu.org/licenses/>.  */
57
58              /*
59               *   ISO C99 Standard: 7.23 Date and time    <time.h>
60               */
61
62              #ifndef   _TIME_H
63
64              #if (! defined __need_time_t && !defined __need_clock_t &&      ! defined __need_timespec)
65              # define _TIME_H    1
66              # include <features.h>
67
68              __BEGIN_DECLS
69
70              #endif
71
72              #ifdef    _TIME_H
73              /* Get size_t and NULL from <stddef.h>.  */
74              # define __need_size_t
75              # define __need_NULL
76              # include <stddef.h>
77
78              /* This defines CLOCKS_PER_SEC, which is the number of processor clock
79                 ticks per second.  */
80              # include <bits/time.h>
81
82              /* This is the obsolete POSIX.1-1988 name for the same constant.  */
83              # if !defined __STRICT_ANSI__ && !defined __USE_XOPEN2K
84              #  ifndef CLK_TCK
85              #   define CLK_TCK  CLOCKS_PER_SEC
86              #  endif
87              # endif
88
89              #endif /* <time.h> included.  */
90
91              #if !defined __clock_t_defined && (defined _TIME_H || defined __need_clock_t)
92              # define __clock_t_defined    1
93
94              # include <bits/types.h>
95
96              __BEGIN_NAMESPACE_STD
97              /* Returned by `clock'.  */
98              typedef __clock_t clock_t;
99              __END_NAMESPACE_STD
100              #if defined __USE_XOPEN || defined __USE_POSIX || defined __USE_MISC
101              __USING_NAMESPACE_STD(clock_t)
102              #endif
103
104              #endif /* clock_t not defined and <time.h> or need clock_t.  */
105              #undef    __need_clock_t
106
107              #if !defined __time_t_defined && (defined _TIME_H || defined __need_time_t)
108              # define __time_t_defined     1
109
110              # include <bits/types.h>
111
112              __BEGIN_NAMESPACE_STD
113              /* Returned by `time'.  */
114              typedef __time_t time_t;
115              __END_NAMESPACE_STD
116              #if defined __USE_POSIX || defined __USE_MISC || defined __USE_SVID
117              __USING_NAMESPACE_STD(time_t)
118              #endif
119
120              #endif /* time_t not defined and <time.h> or need time_t.  */
121              #undef    __need_time_t
122
123              #if !defined __clockid_t_defined &&    ((defined _TIME_H && defined __USE_POSIX199309) || defined __need_clockid_t)
124              # define __clockid_t_defined  1
125
126              # include <bits/types.h>
127
128              /* Clock ID used in clock and timer functions.  */
129              typedef __clockid_t clockid_t;
130
131              #endif /* clockid_t not defined and <time.h> or need clockid_t.  */
132              #undef    __clockid_time_t
133
134              #if !defined __timer_t_defined &&     ((defined _TIME_H && defined __USE_POSIX199309) || defined __need_timer_t)
135              # define __timer_t_defined    1
136
137              # include <bits/types.h>
138
139              /* Timer ID returned by `timer_create'.  */
140              typedef __timer_t timer_t;
141
142              #endif /* timer_t not defined and <time.h> or need timer_t.  */
143              #undef    __need_timer_t
144
145
146              #if (!defined __timespec_defined                            && ((defined _TIME_H                                     && (defined __USE_POSIX199309 || defined __USE_MISC                  || defined __USE_ISOC11))                              || defined __need_timespec))
147              # define __timespec_defined   1
148
149              # include <bits/types.h> /* This defines __time_t for us.  */
150
151              /* POSIX.1b structure for a time value.  This is like a `struct timeval' but
152                 has nanoseconds instead of microseconds.  */
153              struct timespec
154                {
155                  __time_t tv_sec;          /* Seconds.  */
156                  __syscall_slong_t tv_nsec;     /* Nanoseconds.  */
157                };
158
159              #endif /* timespec not defined and <time.h> or need timespec.  */
160              #undef    __need_timespec
161
162
163              #ifdef    _TIME_H
164              __BEGIN_NAMESPACE_STD
165              /* Used by other time functions.  */
166              struct tm
167              {
168                int tm_sec;            /* Seconds.    [0-60] (1 leap second) */
169                int tm_min;            /* Minutes.    [0-59] */
170                int tm_hour;           /* Hours. [0-23] */
171                int tm_mday;           /* Day.        [1-31] */
172                int tm_mon;            /* Month. [0-11] */
173                int tm_year;           /* Year   - 1900.  */
174                int tm_wday;           /* Day of week.     [0-6] */
175                int tm_yday;           /* Days in year.[0-365]  */
176                int tm_isdst;               /* DST.        [-1/0/1]*/
177
178              # ifdef   __USE_BSD
179                long int tm_gmtoff;         /* Seconds east of UTC.  */
180                const char *tm_zone;        /* Timezone abbreviation.  */
181              # else
182                long int __tm_gmtoff;       /* Seconds east of UTC.  */
183                const char *__tm_zone; /* Timezone abbreviation.  */
184              # endif
185              };
186              __END_NAMESPACE_STD
187              #if defined __USE_XOPEN || defined __USE_POSIX || defined __USE_MISC
188              __USING_NAMESPACE_STD(tm)
189              #endif
190
191
192              # ifdef __USE_POSIX199309
193              /* POSIX.1b structure for timer start values and intervals.  */
194              struct itimerspec
195                {
196                  struct timespec it_interval;
197                  struct timespec it_value;
198                };
199
200              /* We can use a simple forward declaration.  */
201              struct sigevent;
202
203              # endif   /* POSIX.1b */
204
205              # ifdef __USE_XOPEN2K
206              #  ifndef __pid_t_defined
207              typedef __pid_t pid_t;
208              #   define __pid_t_defined
209              #  endif
210              # endif
211
212
213              # ifdef __USE_ISOC11
214              /* Time base values for timespec_get.  */
215              # define TIME_UTC 1
216              # endif
217
218
219              __BEGIN_NAMESPACE_STD
220              /* Time used by the program so far (user time + system time).
221                 The result / CLOCKS_PER_SECOND is program time in seconds.  */
222              extern clock_t clock (void) __THROW;
223
224              /* Return the current time and put it in *TIMER if TIMER is not NULL.  */
225              extern time_t time (time_t *__timer) __THROW;
226
227              /* Return the difference between TIME1 and TIME0.  */
228              extern double difftime (time_t __time1, time_t __time0)
229                   __THROW __attribute__ ((__const__));
230
231              /* Return the `time_t' representation of TP and normalize TP.  */
232              extern time_t mktime (struct tm *__tp) __THROW;
233
234
235              /* Format TP into S according to FORMAT.
236                 Write no more than MAXSIZE characters and return the number
237                 of characters written, or 0 if it would exceed MAXSIZE.  */
238              extern size_t strftime (char *__restrict __s, size_t __maxsize,
239                             const char *__restrict __format,
240                             const struct tm *__restrict __tp) __THROW;
241              __END_NAMESPACE_STD
242
243              # ifdef __USE_XOPEN
244              /* Parse S according to FORMAT and store binary time information in TP.
245                 The return value is a pointer to the first unparsed character in S.  */
246              extern char *strptime (const char *__restrict __s,
247                               const char *__restrict __fmt, struct tm *__tp)
248                   __THROW;
249              # endif
250
251              # ifdef __USE_XOPEN2K8
252              /* Similar to the two functions above but take the information from
253                 the provided locale and not the global locale.  */
254              # include <xlocale.h>
255
256              extern size_t strftime_l (char *__restrict __s, size_t __maxsize,
257                               const char *__restrict __format,
258                               const struct tm *__restrict __tp,
259                               __locale_t __loc) __THROW;
260              # endif
261
262              # ifdef __USE_GNU
263              extern char *strptime_l (const char *__restrict __s,
264                              const char *__restrict __fmt, struct tm *__tp,
265                              __locale_t __loc) __THROW;
266              # endif
267
268
269              __BEGIN_NAMESPACE_STD
270              /* Return the `struct tm' representation of *TIMER
271                 in Universal Coordinated Time (aka Greenwich Mean Time).  */
272              extern struct tm *gmtime (const time_t *__timer) __THROW;
273
274              /* Return the `struct tm' representation
275                 of *TIMER in the local timezone.  */
276              extern struct tm *localtime (const time_t *__timer) __THROW;
277              __END_NAMESPACE_STD
278
279              # if defined __USE_POSIX || defined __USE_MISC
280              /* Return the `struct tm' representation of *TIMER in UTC,
281                 using *TP to store the result.  */
282              extern struct tm *gmtime_r (const time_t *__restrict __timer,
283                                 struct tm *__restrict __tp) __THROW;
284
285              /* Return the `struct tm' representation of *TIMER in local time,
286                 using *TP to store the result.  */
287              extern struct tm *localtime_r (const time_t *__restrict __timer,
288                                    struct tm *__restrict __tp) __THROW;
289              # endif   /* POSIX or misc */
290
291              __BEGIN_NAMESPACE_STD
292              /* Return a string of the form "Day Mon dd hh:mm:ss yyyy0
293                 that is the representation of TP in this format.  */
294              extern char *asctime (const struct tm *__tp) __THROW;
295
296              /* Equivalent to `asctime (localtime (timer))'.  */
297              extern char *ctime (const time_t *__timer) __THROW;
298              __END_NAMESPACE_STD
299
300              # if defined __USE_POSIX || defined __USE_MISC
301              /* Reentrant versions of the above functions.  */
302
303              /* Return in BUF a string of the form "Day Mon dd hh:mm:ss yyyy0
304                 that is the representation of TP in this format.  */
305              extern char *asctime_r (const struct tm *__restrict __tp,
306                             char *__restrict __buf) __THROW;
307
308              /* Equivalent to `asctime_r (localtime_r (timer, *TMP*), buf)'.  */
309              extern char *ctime_r (const time_t *__restrict __timer,
310                              char *__restrict __buf) __THROW;
311              # endif   /* POSIX or misc */
312
313
314              /* Defined in localtime.c.  */
315              extern char *__tzname[2];     /* Current timezone names.  */
316              extern int __daylight;        /* If daylight-saving time is ever in use.  */
317              extern long int __timezone;   /* Seconds west of UTC.  */
318
319
320              # ifdef   __USE_POSIX
321              /* Same as above.  */
322              extern char *tzname[2];
323
324              /* Set time conversion information from the TZ environment variable.
325                 If TZ is not defined, a locale-dependent default is used.  */
326              extern void tzset (void) __THROW;
327              # endif
328
329              # if defined __USE_SVID || defined __USE_XOPEN
330              extern int daylight;
331              extern long int timezone;
332              # endif
333
334              # ifdef __USE_SVID
335              /* Set the system time to *WHEN.
336                 This call is restricted to the superuser.  */
337              extern int stime (const time_t *__when) __THROW;
338              # endif
339
340
341              /* Nonzero if YEAR is a leap year (every 4 years,
342                 except every 100th isn't, and every 400th is).  */
343              # define __isleap(year)    ((year) % 4 == 0 && ((year) % 100 != 0 || (year) % 400 == 0))
344
345
346              # ifdef __USE_MISC
347              /* Miscellaneous functions many Unices inherited from the public domain
348                 localtime package.  These are included only for compatibility.  */
349
350              /* Like `mktime', but for TP represents Universal Time, not local time.  */
351              extern time_t timegm (struct tm *__tp) __THROW;
352
353              /* Another name for `mktime'.  */
354              extern time_t timelocal (struct tm *__tp) __THROW;
355
356              /* Return the number of days in YEAR.  */
357              extern int dysize (int __year) __THROW  __attribute__ ((__const__));
358              # endif
359
360
361              # ifdef __USE_POSIX199309
362              /* Pause execution for a number of nanoseconds.
363
364                 This function is a cancellation point and therefore not marked with
365                 __THROW.  */
366              extern int nanosleep (const struct timespec *__requested_time,
367                              struct timespec *__remaining);
368
369
370              /* Get resolution of clock CLOCK_ID.  */
371              extern int clock_getres (clockid_t __clock_id, struct timespec *__res) __THROW;
372
373              /* Get current value of clock CLOCK_ID and store it in TP.  */
374              extern int clock_gettime (clockid_t __clock_id, struct timespec *__tp) __THROW;
375
376              /* Set clock CLOCK_ID to value TP.  */
377              extern int clock_settime (clockid_t __clock_id, const struct timespec *__tp)
378                   __THROW;
379
380              #  ifdef __USE_XOPEN2K
381              /* High-resolution sleep with the specified clock.
382
383                 This function is a cancellation point and therefore not marked with
384                 __THROW.  */
385              extern int clock_nanosleep (clockid_t __clock_id, int __flags,
386                                 const struct timespec *__req,
387                                 struct timespec *__rem);
388
389              /* Return clock ID for CPU-time clock.  */
390              extern int clock_getcpuclockid (pid_t __pid, clockid_t *__clock_id) __THROW;
391              #  endif
392
393
394              /* Create new per-process timer using CLOCK_ID.  */
395              extern int timer_create (clockid_t __clock_id,
396                              struct sigevent *__restrict __evp,
397                              timer_t *__restrict __timerid) __THROW;
398
399              /* Delete timer TIMERID.  */
400              extern int timer_delete (timer_t __timerid) __THROW;
401
402              /* Set timer TIMERID to VALUE, returning old value in OVALUE.  */
403              extern int timer_settime (timer_t __timerid, int __flags,
404                               const struct itimerspec *__restrict __value,
405                               struct itimerspec *__restrict __ovalue) __THROW;
406
407              /* Get current value of timer TIMERID and store it in VALUE.  */
408              extern int timer_gettime (timer_t __timerid, struct itimerspec *__value)
409                   __THROW;
410
411              /* Get expiration overrun for timer TIMERID.  */
412              extern int timer_getoverrun (timer_t __timerid) __THROW;
413              # endif
414
415
416              # ifdef __USE_ISOC11
417              /* Set TS to calendar time based in time base BASE.  */
418              extern int timespec_get (struct timespec *__ts, int __base)
419                   __THROW __nonnull ((1));
420              # endif
421
422
423              # ifdef __USE_XOPEN_EXTENDED
424              /* Set to one of the following values to indicate an error.
425                   1  the DATEMSK environment variable is null or undefined,
426                   2  the template file cannot be opened for reading,
427                   3  failed to get file status information,
428                   4  the template file is not a regular file,
429                   5  an error is encountered while reading the template file,
430                   6  memory allication failed (not enough memory available),
431                   7  there is no line in the template that matches the input,
432                   8  invalid input specification Example: February 31 or a time is
433                   specified that can not be represented in a time_t (representing
434                   the time in seconds since 00:00:00 UTC, January 1, 1970) */
435              extern int getdate_err;
436
437              /* Parse the given string as a date specification and return a value
438                 representing the value.  The templates from the file identified by
439                 the environment variable DATEMSK are used.  In case of an error
440                 `getdate_err' is set.
441
442                 This function is a possible cancellation point and therefore not
443                 marked with __THROW.  */
444              extern struct tm *getdate (const char *__string);
445              # endif
446
447              # ifdef __USE_GNU
448              /* Since `getdate' is not reentrant because of the use of `getdate_err'
449                 and the static buffer to return the result in, we provide a thread-safe
450                 variant.  The functionality is the same.  The result is returned in
451                 the buffer pointed to by RESBUFP and in case of an error the return
452                 value is != 0 with the same values as given above for `getdate_err'.
453
454                 This function is not part of POSIX and therefore no official
455                 cancellation point.  But due to similarity with an POSIX interface
456                 or due to the implementation it is a cancellation point and
457                 therefore not marked with __THROW.  */
458              extern int getdate_r (const char *__restrict __string,
459                              struct tm *__restrict __resbufp);
460              # endif
461
462              __END_DECLS
463
464              #endif /* <time.h> included.  */
465
466              #endif /* <time.h> not already included.  */
467
468       These quantities give the time on a 24-hour clock, day of month (1-31),
469       month  of  year  (0-11),  day of week (Sunday = 0), year - 1900, day of
470       year (0-365), and a flag that is nonzero if daylight saving time is  in
471       effect.
472
473       When  local  time  is  called  for,  the program consults the system to
474       determine the time zone and whether the standard U.S.A. daylight saving
475       time adjustment is appropriate.  The program knows about the peculiari‐
476       ties of this conversion in 1974 and 1975; if  necessary,  a  table  for
477       these years can be extended.
478
479       Timezone  returns  the  name of the time zone associated with its first
480       argument, which is measured in minutes westward from Greenwich.  If the
481       second argument is 0, the standard name is used, otherwise the Daylight
482       Saving version.  If the required name does not appear in a table  built
483       into  the  routine,  the  difference  from  GMT  is  produced; e.g.  in
484       Afghanistan timezone(-(60*4+30), 0) is appropriate because it  is  4:30
485       ahead of GMT and the string GMT+4:30 is produced.
486

SEE ALSO

488       time(2)
489

BUGS

491       The  return values point to static data whose content is overwritten by
492       each call.
493
494
495
496                                                                      CTIME(3)
Impressum