summaryrefslogtreecommitdiffstats
path: root/man3/ctime.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/ctime.3')
-rw-r--r--man3/ctime.3429
1 files changed, 0 insertions, 429 deletions
diff --git a/man3/ctime.3 b/man3/ctime.3
deleted file mode 100644
index 817e964..0000000
--- a/man3/ctime.3
+++ /dev/null
@@ -1,429 +0,0 @@
-'\" 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 2023-10-31 "Linux man-pages 6.7"
-.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)