Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 429 insertions, 0 deletions

diff --git a/man/man3/ctime.3 b/man/man3/ctime.3
new file mode 100644
index 0000000..cb33421
--- /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 2024-05-02 "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)