diff options
Diffstat (limited to 'man/man3/ctime.3')
| -rw-r--r-- | man/man3/ctime.3 | 429 |
1 files changed, 429 insertions, 0 deletions
diff --git a/man/man3/ctime.3 b/man/man3/ctime.3 new file mode 100644 index 000000000..b8543a1cf --- /dev/null +++ b/man/man3/ctime.3 @@ -0,0 +1,429 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 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 (date) "Linux man-pages (unreleased)" +.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 LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <time.h> +.P +.BI "char *asctime(const struct tm *" tm ); +.BI "char *asctime_r(const struct tm *restrict " tm , +.BI " char " buf "[restrict 26]);" +.P +.BI "char *ctime(const time_t *" timep ); +.BI "char *ctime_r(const time_t *restrict " timep , +.BI " char " buf "[restrict 26]);" +.P +.BI "struct tm *gmtime(const time_t *" timep ); +.BI "struct tm *gmtime_r(const time_t *restrict " timep , +.BI " struct tm *restrict " result ); +.P +.BI "struct tm *localtime(const time_t *" timep ); +.BI "struct tm *localtime_r(const time_t *restrict " timep , +.BI " struct tm *restrict " result ); +.P +.BI "time_t mktime(struct tm *" tm ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.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). +.P +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. +.P +Broken-down time is stored in the structure +.IR tm , +described in +.BR tm (3type). +.P +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 +.P +.in +4n +.EX +"Wed Jun 30 21:49:08 1993\en" +.EE +.in +.P +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. +.P +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. +.P +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. +.P +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. +.P +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. +.P +The +.BR mktime () +function modifies the fields of the +.I 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. +.P +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" . +.P +On success, +.BR gmtime_r () +and +.BR localtime_r () +return the address of the structure pointed to by +.IR result . +.P +On success, +.BR asctime () +and +.BR ctime () +return a pointer to a string. +.P +On success, +.BR asctime_r () +and +.BR ctime_r () +return a pointer to the string pointed to by +.IR buf . +.P +On success, +.BR mktime () +returns the calendar time (seconds since the Epoch), +expressed as a value of type +.IR time_t . +.P +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). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR asctime () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:asctime locale +T} +T{ +.na +.nh +.BR asctime_r () +T} Thread safety T{ +.na +.nh +MT-Safe locale +T} +T{ +.na +.nh +.BR ctime () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:tmbuf +race:asctime env locale +T} +T{ +.na +.nh +.BR ctime_r (), +.BR gmtime_r (), +.BR localtime_r (), +.BR mktime () +T} Thread safety T{ +.na +.nh +MT-Safe env locale +T} +T{ +.na +.nh +.BR gmtime (), +.BR localtime () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:tmbuf env locale +T} +.TE +.SH VERSIONS +POSIX doesn't specify the parameters of +.BR ctime_r () +to be +.IR restrict ; +that is specific to glibc. +.P +In many implementations, including glibc, a 0 in +.I tm_mday +is interpreted as meaning the last day of the preceding month. +.P +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 STANDARDS +.TP +.BR asctime () +.TQ +.BR ctime () +.TQ +.BR gmtime () +.TQ +.BR localtime () +.TQ +.BR mktime () +C11, POSIX.1-2008. +.TP +.BR asctime_r () +.TQ +.BR ctime_r () +.TQ +.BR gmtime_r () +.TQ +.BR localtime_r () +POSIX.1-2008. +.SH HISTORY +.TP +.BR gmtime () +.TQ +.BR localtime () +.TQ +.BR mktime () +C89, POSIX.1-2001. +.TP +.BR asctime () +.TQ +.BR ctime () +C89, POSIX.1-2001. +Marked obsolete in POSIX.1-2008 (recommending +.BR strftime (3)). +.TP +.BR gmtime_r () +.TQ +.BR localtime_r () +POSIX.1-2001. +.TP +.BR asctime_r () +.TQ +.BR ctime_r () +POSIX.1-2001. +Marked obsolete in POSIX.1-2008 (recommending +.BR strftime (3)). +.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. +.P +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. +.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) |