cid b37c1135b84b9e12b298d7d479f2fb824daebb40293a89a047031240fe10726b · original · open access · via man
Title: ctime(3) - Linux manual page
Authors:
Venue: man
Year: 1993
Canonical: man:man3/localtime.3
URL: https://man7.org/linux/man-pages/man3/localtime.3.html
Collector: man
OA: true
ABSTRACT
ctime(3) - Linux manual page man7.org Linux man-pages Linux/UNIX system programming training ctime(3) — Linux manual page NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | ATTRIBUTES | VERSIONS | STANDARDS | HISTORY | CAVEATS | EXAMPLES | SEE ALSO | COLOPHON ctime(3) Library Functions Manual ctime(3) NAME top asctime, ctime, gmtime, localtime, mktime, asctime_r, ctime_r, gmtime_r, localtime_r - transform date and time to broken-down time or ASCII LIBRARY top Standard C library (libc, -lc) SYNOPSIS top #include char *asctime(const struct tm *tm); char *asctime_r(const struct tm *restrict tm, char buf[restrict 26]); char *ctime(const time_t *timep); char *ctime_r(const time_t *restrict timep, char buf[restrict 26]); struct tm *gmtime(const time_t *timep); struct tm *gmtime_r(const time_t *restrict timep, struct tm *restrict result); struct tm *localtime(const time_t *timep); struct tm *localtime_r(const time_t *restrict timep, struct tm *restrict result); time_t mktime(struct tm *tm); Feature Test Macro Requirements for glibc (see feature_test_macros(7)): asctime_r(), ctime_r(), gmtime_r(), localtime_r(): _POSIX_C_SOURCE || /* glibc tm_wday member unmodified. The remaining functions return NULL on error. On error, errno is set to indicate the error. ERRORS top EOVERFLOW The result cannot be represented. ATTRIBUTES top For an explanation of the terms used in this section, see attributes(7). ┌────────────────┬───────────────┬───────────────────────────────┐ │ Interface │ Attribute │ Value │ ├────────────────┼───────────────┼───────────────────────────────┤ │ asctime() │ Thread safety │ MT-Unsafe race:asctime locale │ ├────────────────┼───────────────┼───────────────────────────────┤ │ asctime_r() │ Thread safety │ MT-Safe locale │ ├────────────────┼───────────────┼───────────────────────────────┤ │ ctime() │ Thread safety │ MT-Unsafe race:tmbuf │ │ │ │ race:asctime env locale │ ├────────────────┼───────────────┼───────────────────────────────┤ │ ctime_r(), │ Thread safety │ MT-Safe env locale │ │ gmtime_r(), │ │ │ │ localtime_r(), │ │ │ │ mktime() │ │ │ ├────────────────┼───────────────┼───────────────────────────────┤ │ gmtime(), │ Thread safety │ MT-Unsafe race:tmbuf env │ │ localtime() │ │ locale │ └────────────────┴───────────────┴───────────────────────────────┘ VERSIONS top POSIX doesn't specify the parameters of ctime_r() to be restrict; that is specific to glibc. In many implementations, including glibc, a 0 in tm_mday is interpreted as meaning the last day of the preceding month. According to POSIX.1, localtime() is required to behave as though tzset(3) was called, while localtime_r() does not have this requirement. For portable code, tzset(3) should be called before localtime_r(). STANDARDS top asctime() ctime() gmtime() localtime() mktime() C23, POSIX.1-2024. gmtime_r() localtime_r() POSIX.1-2024. asctime_r() ctime_r() None. HISTORY top gmtime() localtime() mktime() C89, POSIX.1-1988. asctime() ctime() C89, POSIX.1-1988. Marked obsolescent in C23 and in POSIX.1-2008 (recommending strftime(3)). gmtime_r() localtime_r() POSIX.1-1996. asctime_r() ctime_r() POSIX.1-1996. Marked obsolescent in POSIX.1-2008. Removed in POSIX.1-2024 (recommending strftime(3)). CAVEATS top Thread safety The four functions asctime(), ctime(), gmtime(), and localtime() return a pointer to static data and hence are not thread-safe. The thread-safe versions, asctime_r(), ctime_r(), gmtime_r(), and localtime_r(), are specified by SUSv2. POSIX.1 says: "The asctime(), ctime(), gmtime(), and localtime() functions shall return values in one of two static objects: a broken-down time structure and an array of type char. Execution of any of the functions that return a pointer to one of these object types may overwrite the information in any object of the same type pointed to by the value returned from any previous call to any of them." This can occur in the glibc implementation. mktime() (time_t) -1 can represent a valid time (one second before the Epoch). To determine whether mktime() failed, one must use the tm-tm_wday field. See the example program in EXAMPLES. The handling of a non-negative tm_isdst in mktime() is poorly specified, and passing a value that is incorrect for the time specified yields unspecified results. Since mktime() is one of the few functions that knows when DST is in effect, providing a correct value may be difficult. One workaround for this is to call mktime() twice, once with tm_isdst set to zero, and once with tm_isdst set to a positive value, and discarding the results from the call that changes it. If neither call changes tm_isdst then the time specified probably happens during a fall-back period where DST begins or ends, and both results are valid but represent two different times. If both calls change it, that could indicate a fall-forward transition, or some other reason why the time specified does not exist. The specification of time zones and daylight saving time are up to regional governments, change often, and may include discontinuities beyond mktime's ability to document a result. For example, a change in the timezone definition may cause a clock time to be repeated or skipped without a corresponding DST change. EXAMPLES top The program below defines a wrapper that allows detecting invalid and ambiguous times, with EINVAL and ENOTUNIQ, respectively. The following shell session shows sample runs of the program: $ TZ=UTC ./a.out 1969 12 31 23 59 59 0; -1 $ $ export TZ=Europe/Madrid; $ $ ./a.out 2147483647 2147483647 00 00 00 00 -1; a.out: mktime: Value too large for defined data type $ $ ./a.out 2024 08 23 00 17 53 -1; 1724365073 $ ./a.out 2024 08 23 00 17 53 0; a.out: my_mktime: Invalid argument 1724368673 $ ./a.out 2024 08 23 00 17 53 1; 1724365073 $ $ ./a.out 2024 02 23 00 17 53 -1; 1708643873 $ ./a.out 2024 02 23 00 17 53 0; 1708643873 $ ./a.out 2024 02 23 00 17 53 1; a.out: my_mktime: Invalid argument 1708640273 $ $ ./a.out 2023 03 26 02 17 53 -1; a.out: my_mktime: Invalid argument 1679793473 $ $ ./a.out 2023 10 29 02 17 53 -1; a.out: my_mktime: Name not unique on network 1698542273 $ ./a.out 2023 10 29 02 17 53 0; 1698542273 $ ./a.out 2023 10 29 02 17 53 1; 1698538673 $ $ ./a.out 2023 02 29 12 00 00 -1; a.out: my_mktime: Invalid argument 1677668400 Program source: mktime.c #include #include #include #include #include #include #include #define is_signed(T) ((T) -1 tm_wday)]; e = errno; tm = *tp; isdst = tp-tm_isdst; memcpy(wday, &tp-tm_wday, sizeof(wday)); tp-tm_wday = -1; t = mktime(tp); if (tp-tm_wday == -1) { memcpy(&tp-tm_wday, wday, sizeof(wday)); return -1; } if (isdst == -1) tm.tm_isdst = tp-tm_isdst; if ( tm.tm_sec != tp-tm_sec || tm.tm_min != tp-tm_min || tm.tm_hour != tp-tm_hour || tm.tm_mday != tp-tm_mday || tm.tm_mon != tp-tm_mon || tm.tm_year != tp-tm_year || tm.tm_isdst != tp-tm_isdst) { errno = EINVAL; return t; } if (isdst != -1) goto out; tm = *tp; tm.tm_isdst = !tm.tm_isdst; tm.tm_wday = -1; mktime(&tm); if (tm.tm_wday == -1) goto out; if (tm.tm_isdst != tp-tm_isdst) { errno = ENOTUNIQ; return t; } out: errno = e; return t; } SEE ALSO top date(1), gettimeofday(2), time(2), utime(2), clock(3), difftime(3), strftime(3), strptime(3), timegm(3), tzset(3), time(7) COLOPHON top This page is part of the man-pages (Linux kernel and C library user-space interface documentation) project. Information about the project can be found at ⟨https://www.kernel.org/doc/man-pages/⟩. If you have a bug report for this manual page, see ⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩. This page was obtained from the tarball man-pages-6.19.tar.gz fetched from ⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on 2026-09-09. If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up- to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which is not part of the original manual page), send a mail to man-pages@man7.org Linux man-pages 6.19 2026-02-08 ctime(3) Pages that refer to this page: find(1), pcp-iostat(1), pcp-ss(1), pcp-tapestat(1), pmie(1), utmpdump(1), clock_getres(2), gettimeofday(2), time(2), difftime(3), getdate(3), pmctime(3), pmlocaltime(3), __pmmktime(3), pmnotifyerr(3), __pmparsectime(3), strftime(3), timegm(3), time_t(3type), tm(3type), tzset(3), rtc(4), localtime(5), tzfile(5), environ(7), time(7), audispd-zos-remote(8), lsof(8), rtcwake(8), zdump(8) HTML rendering created 2026-09-09 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH.