1CTIME(3) Library Functions Manual CTIME(3)
2
6 ctime, localtime, gmtime, asctime, timezone - convert date and time to
7 ASCII
8
10 char *ctime(clock)
11 long *clock;
12 #include <time.h>
14 struct tm *localtime(clock)
16 long *clock;
17 struct tm *gmtime(clock)
19 long *clock;
20 char *asctime(tm)
22 struct tm *tm;
23 char *timezone(zone, dst)
25
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 Sun Sep 16 01:03:52 1973\n\0
32 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 The structure declaration from the include file is:
40 /* Copyright (C) 1991-2012 Free Software Foundation, Inc.
42 This file is part of the GNU C Library.
43 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 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 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 /*
59 * ISO C99 Standard: 7.23 Date and time <time.h>
60 */
61 #ifndef _TIME_H
63 #if (! defined __need_time_t && !defined __need_clock_t && ! defined __need_timespec)
65 # define _TIME_H 1
66 # include <features.h>
67 __BEGIN_DECLS
69 #endif
71 #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 /* This defines CLOCKS_PER_SEC, which is the number of processor clock
79 ticks per second. */
80 # include <bits/time.h>
81 /* 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 #endif /* <time.h> included. */
90 #if !defined __clock_t_defined && (defined _TIME_H || defined __need_clock_t)
92 # define __clock_t_defined 1
93 # include <bits/types.h>
95 __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 #endif /* clock_t not defined and <time.h> or need clock_t. */
105 #undef __need_clock_t
106 #if !defined __time_t_defined && (defined _TIME_H || defined __need_time_t)
108 # define __time_t_defined 1
109 # include <bits/types.h>
111 __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 #endif /* time_t not defined and <time.h> or need time_t. */
121 #undef __need_time_t
122 #if !defined __clockid_t_defined && ((defined _TIME_H && defined __USE_POSIX199309) || defined __need_clockid_t)
124 # define __clockid_t_defined 1
125 # include <bits/types.h>
127 /* Clock ID used in clock and timer functions. */
129 typedef __clockid_t clockid_t;
130 #endif /* clockid_t not defined and <time.h> or need clockid_t. */
132 #undef __clockid_time_t
133 #if !defined __timer_t_defined && ((defined _TIME_H && defined __USE_POSIX199309) || defined __need_timer_t)
135 # define __timer_t_defined 1
136 # include <bits/types.h>
138 /* Timer ID returned by `timer_create'. */
140 typedef __timer_t timer_t;
141 #endif /* timer_t not defined and <time.h> or need timer_t. */
143 #undef __need_timer_t
144 #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 # include <bits/types.h> /* This defines __time_t for us. */
150 /* 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 #endif /* timespec not defined and <time.h> or need timespec. */
160 #undef __need_timespec
161 #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 # 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 # 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 /* We can use a simple forward declaration. */
201 struct sigevent;
202 # endif /* POSIX.1b */
204 # ifdef __USE_XOPEN2K
206 # ifndef __pid_t_defined
207 typedef __pid_t pid_t;
208 # define __pid_t_defined
209 # endif
210 # endif
211 # ifdef __USE_ISOC11
214 /* Time base values for timespec_get. */
215 # define TIME_UTC 1
216 # endif
217 __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 /* Return the current time and put it in *TIMER if TIMER is not NULL. */
225 extern time_t time (time_t *__timer) __THROW;
226 /* Return the difference between TIME1 and TIME0. */
228 extern double difftime (time_t __time1, time_t __time0)
229 __THROW __attribute__ ((__const__));
230 /* Return the `time_t' representation of TP and normalize TP. */
232 extern time_t mktime (struct tm *__tp) __THROW;
233 /* 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 # 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 # 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 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 # 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 __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 /* 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 # 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 /* 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 __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 /* Equivalent to `asctime (localtime (timer))'. */
297 extern char *ctime (const time_t *__timer) __THROW;
298 __END_NAMESPACE_STD
299 # if defined __USE_POSIX || defined __USE_MISC
301 /* Reentrant versions of the above functions. */
302 /* 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 /* 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 /* 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 # ifdef __USE_POSIX
321 /* Same as above. */
322 extern char *tzname[2];
323 /* 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 # if defined __USE_SVID || defined __USE_XOPEN
330 extern int daylight;
331 extern long int timezone;
332 # endif
333 # 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 /* 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 # ifdef __USE_MISC
347 /* Miscellaneous functions many Unices inherited from the public domain
348 localtime package. These are included only for compatibility. */
349 /* Like `mktime', but for TP represents Universal Time, not local time. */
351 extern time_t timegm (struct tm *__tp) __THROW;
352 /* Another name for `mktime'. */
354 extern time_t timelocal (struct tm *__tp) __THROW;
355 /* Return the number of days in YEAR. */
357 extern int dysize (int __year) __THROW __attribute__ ((__const__));
358 # endif
359 # ifdef __USE_POSIX199309
362 /* Pause execution for a number of nanoseconds.
363 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 /* Get resolution of clock CLOCK_ID. */
371 extern int clock_getres (clockid_t __clock_id, struct timespec *__res) __THROW;
372 /* 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 /* Set clock CLOCK_ID to value TP. */
377 extern int clock_settime (clockid_t __clock_id, const struct timespec *__tp)
378 __THROW;
379 # ifdef __USE_XOPEN2K
381 /* High-resolution sleep with the specified clock.
382 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 /* Return clock ID for CPU-time clock. */
390 extern int clock_getcpuclockid (pid_t __pid, clockid_t *__clock_id) __THROW;
391 # endif
392 /* 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 /* Delete timer TIMERID. */
400 extern int timer_delete (timer_t __timerid) __THROW;
401 /* 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 /* 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 /* Get expiration overrun for timer TIMERID. */
412 extern int timer_getoverrun (timer_t __timerid) __THROW;
413 # endif
414 # 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 # 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 /* 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 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 # 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 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 __END_DECLS
463 #endif /* <time.h> included. */
465 #endif /* <time.h> not already included. */
467 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 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 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
488 time(2)
489
491 The return values point to static data whose content is overwritten by
492 each call.
493 CTIME(3)