| .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .\" References consulted: |
| .\" Linux libc source code |
| .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) |
| .\" 386BSD man pages |
| .\" Modified Sat Jul 24 19:49:27 1993 by Rik Faith (faith@cs.unc.edu) |
| .\" Modified Fri Apr 26 12:38:55 MET DST 1996 by Martin Schulze (joey@linux.de) |
| .\" Modified 2001-11-13, aeb |
| .\" Modified 2001-12-13, joey, aeb |
| .\" Modified 2004-11-16, mtk |
| .\" |
| .TH CTIME 3 2021-03-22 "" "Linux Programmer's Manual" |
| .SH NAME |
| asctime, ctime, gmtime, localtime, mktime, asctime_r, ctime_r, gmtime_r, |
| localtime_r \- transform date and time to broken-down time or ASCII |
| .SH SYNOPSIS |
| .nf |
| .B #include <time.h> |
| .PP |
| .BI "char *asctime(const struct tm *" tm ); |
| .BI "char *asctime_r(const struct tm *restrict " tm ", char *restrict " buf ); |
| .PP |
| .BI "char *ctime(const time_t *" timep ); |
| .BI "char *ctime_r(const time_t *restrict " timep ", char *restrict " buf ); |
| .PP |
| .BI "struct tm *gmtime(const time_t *" timep ); |
| .BI "struct tm *gmtime_r(const time_t *restrict " timep , |
| .BI " struct tm *restrict " result ); |
| .PP |
| .BI "struct tm *localtime(const time_t *" timep ); |
| .BI "struct tm *localtime_r(const time_t *restrict " timep , |
| .BI " struct tm *restrict " result ); |
| .PP |
| .BI "time_t mktime(struct tm *" tm ); |
| .fi |
| .PP |
| .RS -4 |
| Feature Test Macro Requirements for glibc (see |
| .BR feature_test_macros (7)): |
| .RE |
| .PP |
| .BR asctime_r (), |
| .BR ctime_r (), |
| .BR gmtime_r (), |
| .BR localtime_r (): |
| .nf |
| _POSIX_C_SOURCE |
| || /* Glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE |
| .fi |
| .SH DESCRIPTION |
| The |
| .BR ctime (), |
| .BR gmtime (), |
| and |
| .BR localtime () |
| functions all take |
| an argument of data type \fItime_t\fP, which represents calendar time. |
| When interpreted as an absolute time value, it represents the number of |
| seconds elapsed since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). |
| .PP |
| The |
| .BR asctime () |
| and |
| .BR mktime () |
| functions both take an argument |
| representing broken-down time, which is a representation |
| separated into year, month, day, and so on. |
| .PP |
| Broken-down time is stored |
| in the structure \fItm\fP, which is defined in \fI<time.h>\fP as follows: |
| .PP |
| .in +4n |
| .EX |
| struct tm { |
| int tm_sec; /* Seconds (0\-60) */ |
| int tm_min; /* Minutes (0\-59) */ |
| int tm_hour; /* Hours (0\-23) */ |
| int tm_mday; /* Day of the month (1\-31) */ |
| int tm_mon; /* Month (0\-11) */ |
| int tm_year; /* Year \- 1900 */ |
| int tm_wday; /* Day of the week (0\-6, Sunday = 0) */ |
| int tm_yday; /* Day in the year (0\-365, 1 Jan = 0) */ |
| int tm_isdst; /* Daylight saving time */ |
| }; |
| .EE |
| .in |
| .PP |
| The members of the \fItm\fP structure are: |
| .TP 10 |
| .I tm_sec |
| The number of seconds after the minute, normally in the range 0 to 59, |
| but can be up to 60 to allow for leap seconds. |
| .TP |
| .I tm_min |
| The number of minutes after the hour, in the range 0 to 59. |
| .TP |
| .I tm_hour |
| The number of hours past midnight, in the range 0 to 23. |
| .TP |
| .I tm_mday |
| The day of the month, in the range 1 to 31. |
| .TP |
| .I tm_mon |
| The number of months since January, in the range 0 to 11. |
| .TP |
| .I tm_year |
| The number of years since 1900. |
| .TP |
| .I tm_wday |
| The number of days since Sunday, in the range 0 to 6. |
| .TP |
| .I tm_yday |
| The number of days since January 1, in the range 0 to 365. |
| .TP |
| .I tm_isdst |
| A flag that indicates whether daylight saving time is in effect at the |
| time described. |
| The value is positive if daylight saving time is in |
| effect, zero if it is not, and negative if the information is not |
| available. |
| .PP |
| The call |
| .BI ctime( t ) |
| is equivalent to |
| .BI asctime(localtime( t )) \fR. |
| It converts the calendar time \fIt\fP into a |
| null-terminated string of the form |
| .PP |
| .in +4n |
| .EX |
| "Wed Jun 30 21:49:08 1993\en" |
| .EE |
| .in |
| .PP |
| The abbreviations for the days of the week are "Sun", "Mon", "Tue", "Wed", |
| "Thu", "Fri", and "Sat". |
| The abbreviations for the months are "Jan", |
| "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", and |
| "Dec". |
| The return value points to a statically allocated string which |
| might be overwritten by subsequent calls to any of the date and time |
| functions. |
| The function also sets the external |
| variables \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP (see |
| .BR tzset (3)) |
| with information about the current timezone. |
| The reentrant version |
| .BR ctime_r () |
| does the same, but stores the |
| string in a user-supplied buffer |
| which should have room for at least 26 bytes. |
| It need not |
| set \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP. |
| .PP |
| The |
| .BR gmtime () |
| function converts the calendar time \fItimep\fP to |
| broken-down time representation, expressed in Coordinated Universal Time |
| (UTC). |
| It may return NULL when the year does not fit into an integer. |
| The return value points to a statically allocated struct which might be |
| overwritten by subsequent calls to any of the date and time functions. |
| The |
| .BR gmtime_r () |
| function does the same, but stores the data in a |
| user-supplied struct. |
| .PP |
| The |
| .BR localtime () |
| function converts the calendar time \fItimep\fP to |
| broken-down time representation, |
| expressed relative to the user's specified timezone. |
| The function acts as if it called |
| .BR tzset (3) |
| and sets the external variables \fItzname\fP with |
| information about the current timezone, \fItimezone\fP with the difference |
| between Coordinated Universal Time (UTC) and local standard time in |
| seconds, and \fIdaylight\fP to a nonzero value if daylight savings |
| time rules apply during some part of the year. |
| The return value points to a statically allocated struct which might be |
| overwritten by subsequent calls to any of the date and time functions. |
| The |
| .BR localtime_r () |
| function does the same, but stores the data in a |
| user-supplied struct. |
| It need not set \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP. |
| .PP |
| The |
| .BR asctime () |
| function converts the broken-down time value |
| \fItm\fP into a null-terminated string with the same format as |
| .BR ctime (). |
| The return value points to a statically allocated string which might be |
| overwritten by subsequent calls to any of the date and time functions. |
| The |
| .BR asctime_r () |
| function does the same, but stores the string in |
| a user-supplied buffer which should have room for at least 26 bytes. |
| .PP |
| The |
| .BR mktime () |
| function converts a broken-down time structure, expressed |
| as local time, to calendar time representation. |
| The function ignores |
| the values supplied by the caller in the |
| .I tm_wday |
| and |
| .I tm_yday |
| fields. |
| The value specified in the |
| .I tm_isdst |
| field informs |
| .BR mktime () |
| whether or not daylight saving time (DST) |
| is in effect for the time supplied in the |
| .I tm |
| structure: |
| a positive value means DST is in effect; |
| zero means that DST is not in effect; |
| and a negative value means that |
| .BR mktime () |
| should (use timezone information and system databases to) |
| attempt to determine whether DST is in effect at the specified time. |
| .PP |
| The |
| .BR mktime () |
| function modifies the fields of the |
| .IR tm |
| structure as follows: |
| .I tm_wday |
| and |
| .I tm_yday |
| are set to values determined from the contents of the other fields; |
| if structure members are outside their valid interval, they will be |
| normalized (so that, for example, 40 October is changed into 9 November); |
| .I tm_isdst |
| is set (regardless of its initial value) |
| to a positive value or to 0, respectively, |
| to indicate whether DST is or is not in effect at the specified time. |
| Calling |
| .BR mktime () |
| also sets the external variable \fItzname\fP with |
| information about the current timezone. |
| .PP |
| If the specified broken-down |
| time cannot be represented as calendar time (seconds since the Epoch), |
| .BR mktime () |
| returns |
| .I (time_t)\ \-1 |
| and does not alter the |
| members of the broken-down time structure. |
| .SH RETURN VALUE |
| On success, |
| .BR gmtime () |
| and |
| .BR localtime () |
| return a pointer to a |
| .IR "struct\ tm" . |
| .PP |
| On success, |
| .BR gmtime_r () |
| and |
| .BR localtime_r () |
| return the address of the structure pointed to by |
| .IR result . |
| .PP |
| On success, |
| .BR asctime () |
| and |
| .BR ctime () |
| return a pointer to a string. |
| .PP |
| On success, |
| .BR asctime_r () |
| and |
| .BR ctime_r () |
| return a pointer to the string pointed to by |
| .IR buf . |
| .PP |
| On success, |
| .BR mktime () |
| returns the calendar time (seconds since the Epoch), |
| expressed as a value of type |
| .IR time_t . |
| .PP |
| On error, |
| .BR mktime () |
| returns the value |
| .IR "(time_t)\ \-1" . |
| The remaining functions return NULL on error. |
| On error, |
| .I errno |
| is set to indicate the error. |
| .SH ERRORS |
| .TP |
| .B EOVERFLOW |
| The result cannot be represented. |
| .SH ATTRIBUTES |
| For an explanation of the terms used in this section, see |
| .BR attributes (7). |
| .ad l |
| .nh |
| .TS |
| allbox; |
| lb lb lbx |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR asctime () |
| T} Thread safety T{ |
| MT-Unsafe race:asctime locale |
| T} |
| T{ |
| .BR asctime_r () |
| T} Thread safety T{ |
| MT-Safe locale |
| T} |
| T{ |
| .BR ctime () |
| T} Thread safety T{ |
| MT-Unsafe race:tmbuf |
| race:asctime env locale |
| T} |
| T{ |
| .BR ctime_r (), |
| .BR gmtime_r (), |
| .BR localtime_r (), |
| .BR mktime () |
| T} Thread safety T{ |
| MT-Safe env locale |
| T} |
| T{ |
| .BR gmtime (), |
| .BR localtime () |
| T} Thread safety T{ |
| MT-Unsafe race:tmbuf env locale |
| T} |
| .TE |
| .hy |
| .ad |
| .sp 1 |
| .SH CONFORMING TO |
| POSIX.1-2001. |
| C89 and C99 specify |
| .BR asctime (), |
| .BR ctime (), |
| .BR gmtime (), |
| .BR localtime (), |
| and |
| .BR mktime (). |
| POSIX.1-2008 marks |
| .BR asctime (), |
| .BR asctime_r (), |
| .BR ctime (), |
| and |
| .BR ctime_r () |
| as obsolete, |
| recommending the use of |
| .BR strftime (3) |
| instead. |
| .PP |
| POSIX doesn't specify the parameters of |
| .BR ctime_r () |
| to be |
| .IR restrict ; |
| that is specific to glibc. |
| .SH NOTES |
| The four functions |
| .BR asctime (), |
| .BR ctime (), |
| .BR gmtime (), |
| and |
| .BR localtime () |
| return a pointer to static data and hence are not thread-safe. |
| The thread-safe versions, |
| .BR asctime_r (), |
| .BR ctime_r (), |
| .BR gmtime_r (), |
| and |
| .BR localtime_r (), |
| are specified by SUSv2. |
| .PP |
| POSIX.1-2001 says: |
| "The |
| .BR asctime (), |
| .BR ctime (), |
| .BR gmtime (), |
| and |
| .BR localtime () |
| functions shall return values in one of two static objects: |
| a broken-down time structure and an array of type |
| .IR char . |
| Execution of any of the functions may overwrite the information returned |
| in either of these objects by any of the other functions." |
| This can occur in the glibc implementation. |
| .PP |
| In many implementations, including glibc, a 0 in |
| .I tm_mday |
| is interpreted as meaning the last day of the preceding month. |
| .PP |
| The glibc version of \fIstruct tm\fP has additional fields |
| .PP |
| .in +4n |
| .EX |
| const char *tm_zone; /* Timezone abbreviation */ |
| .EE |
| .in |
| .PP |
| defined when |
| .B _BSD_SOURCE |
| was set before including |
| .IR <time.h> . |
| This is a BSD extension, present in 4.3BSD-Reno. |
| .PP |
| According to POSIX.1-2001, |
| .BR localtime () |
| is required to behave as though |
| .BR tzset (3) |
| was called, while |
| .BR localtime_r () |
| does not have this requirement. |
| .\" See http://thread.gmane.org/gmane.comp.time.tz/2034/ |
| For portable code, |
| .BR tzset (3) |
| should be called before |
| .BR localtime_r (). |
| .SH SEE ALSO |
| .BR date (1), |
| .BR gettimeofday (2), |
| .BR time (2), |
| .BR utime (2), |
| .BR clock (3), |
| .BR difftime (3), |
| .BR strftime (3), |
| .BR strptime (3), |
| .BR timegm (3), |
| .BR tzset (3), |
| .BR time (7) |