Merging upstream version 6.8.

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

1 files changed, 777 insertions, 0 deletions

diff --git a/man/man3/strftime.3 b/man/man3/strftime.3
new file mode 100644
index 0000000..e94a3ef
--- /dev/null
+++ b/man/man3/strftime.3
@@ -0,0 +1,777 @@
+'\" 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
+.\"     GNU texinfo documentation on glibc date/time functions.
+.\" Modified Sat Jul 24 18:03:44 1993 by Rik Faith (faith@cs.unc.edu)
+.\" Applied fix by Wolfgang Franke, aeb, 961011
+.\" Corrected return value, aeb, 970307
+.\" Added Single UNIX Spec conversions and %z, aeb/esr, 990329.
+.\" 2005-11-22 mtk, added glibc Notes covering optional 'flag' and
+.\"           'width' components of conversion specifications.
+.\"
+.TH strftime 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+strftime \- format date and time
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <time.h>
+.P
+.BI "size_t strftime(char " s "[restrict ." max "], size_t " max ,
+.BI "                const char *restrict " format ,
+.BI "                const struct tm *restrict " tm );
+.P
+.BI "size_t strftime_l(char " s "[restrict ." max "], size_t " max ,
+.BI "                const char *restrict " format ,
+.BI "                const struct tm *restrict " tm ,
+.BI "                locale_t " locale );
+.fi
+.SH DESCRIPTION
+The
+.BR strftime ()
+function formats the broken-down time
+.I tm
+according to the format specification
+.I format
+and places the
+result in the character array
+.I s
+of size
+.IR max .
+The broken-down time structure
+.I tm
+is defined in
+.IR <time.h> .
+See also
+.BR ctime (3).
+.\" FIXME . POSIX says: Local timezone information is used as though
+.\" strftime() called tzset().  But this doesn't appear to be the case
+.P
+The format specification is a null-terminated string and may contain
+special character sequences called
+.IR "conversion specifications",
+each of which is introduced by a \[aq]%\[aq] character and terminated by
+some other character known as a
+.IR "conversion specifier character".
+All other character sequences are
+.IR "ordinary character sequences".
+.P
+The characters of ordinary character sequences (including the null byte)
+are copied verbatim from
+.I format
+to
+.IR s .
+However, the characters
+of conversion specifications are replaced as shown in the list below.
+In this list, the field(s) employed from the
+.I tm
+structure are also shown.
+.TP
+.B %a
+The abbreviated name of the day of the week according to the current locale.
+(Calculated from
+.IR tm_wday .)
+(The specific names used in the current locale can be obtained by calling
+.BR nl_langinfo (3)
+with
+.BR ABDAY_ { 1 \[en] 7 }
+as an argument.)
+.TP
+.B %A
+The full name of the day of the week according to the current locale.
+(Calculated from
+.IR tm_wday .)
+(The specific names used in the current locale can be obtained by calling
+.BR nl_langinfo (3)
+with
+.BR DAY_ { 1 \[en] 7 }
+as an argument.)
+.TP
+.B %b
+The abbreviated month name according to the current locale.
+(Calculated from
+.IR tm_mon .)
+(The specific names used in the current locale can be obtained by calling
+.BR nl_langinfo (3)
+with
+.BR ABMON_ { 1 \[en] 12 }
+as an argument.)
+.TP
+.B %B
+The full month name according to the current locale.
+(Calculated from
+.IR tm_mon .)
+(The specific names used in the current locale can be obtained by calling
+.BR nl_langinfo (3)
+with
+.BR MON_ { 1 \[en] 12 }
+as an argument.)
+.TP
+.B %c
+The preferred date and time representation for the current locale.
+(The specific format used in the current locale can be obtained by calling
+.BR nl_langinfo (3)
+with
+.B D_T_FMT
+as an argument for the
+.B %c
+conversion specification, and with
+.B ERA_D_T_FMT
+for the
+.B %Ec
+conversion specification.)
+(In the POSIX locale this is equivalent to
+.BR "%a %b %e %H:%M:%S %Y" .)
+.TP
+.B %C
+The century number (year/100) as a 2-digit integer. (SU)
+(The
+.B %EC
+conversion specification corresponds to the name of the era.)
+(Calculated from
+.IR tm_year .)
+.TP
+.B %d
+The day of the month as a decimal number (range 01 to 31).
+(Calculated from
+.IR tm_mday .)
+.TP
+.B %D
+Equivalent to
+.BR %m/%d/%y .
+(Yecch\[em]for Americans only.
+Americans should note that in other countries
+.B %d/%m/%y
+is rather common.
+This means that in international context this format is
+ambiguous and should not be used.) (SU)
+.TP
+.B %e
+Like
+.BR %d ,
+the day of the month as a decimal number, but a leading
+zero is replaced by a space. (SU)
+(Calculated from
+.IR tm_mday .)
+.TP
+.B %E
+Modifier: use alternative ("era-based") format, see below. (SU)
+.TP
+.B %F
+Equivalent to
+.B %Y\-%m\-%d
+(the ISO\~8601 date format). (C99)
+.TP
+.B %G
+The ISO\~8601 week-based year (see NOTES) with century as a decimal number.
+The 4-digit year corresponding to the ISO week number (see
+.BR %V ).
+This has the same format and value as
+.BR %Y ,
+except that if the ISO week number belongs to the previous or next year,
+that year is used instead. (TZ)
+(Calculated from
+.IR tm_year ,
+.IR tm_yday ,
+and
+.IR tm_wday .)
+.TP
+.B %g
+Like
+.BR %G ,
+but without century, that is, with a 2-digit year (00\[en]99). (TZ)
+(Calculated from
+.IR tm_year ,
+.IR tm_yday ,
+and
+.IR tm_wday .)
+.TP
+.B %h
+Equivalent to
+.BR %b .
+(SU)
+.TP
+.B %H
+The hour as a decimal number using a 24-hour clock (range 00 to 23).
+(Calculated from
+.IR tm_hour .)
+.TP
+.B %I
+The hour as a decimal number using a 12-hour clock (range 01 to 12).
+(Calculated from
+.IR tm_hour .)
+.TP
+.B %j
+The day of the year as a decimal number (range 001 to 366).
+(Calculated from
+.IR tm_yday .)
+.TP
+.B %k
+The hour (24-hour clock) as a decimal number (range 0 to 23);
+single digits are preceded by a blank.
+(See also
+.BR %H .)
+(Calculated from
+.IR tm_hour .)
+(TZ)
+.TP
+.B %l
+The hour (12-hour clock) as a decimal number (range 1 to 12);
+single digits are preceded by a blank.
+(See also
+.BR %I .)
+(Calculated from
+.IR tm_hour .)
+(TZ)
+.TP
+.B %m
+The month as a decimal number (range 01 to 12).
+(Calculated from
+.IR tm_mon .)
+.TP
+.B %M
+The minute as a decimal number (range 00 to 59).
+(Calculated from
+.IR tm_min .)
+.TP
+.B %n
+A newline character. (SU)
+.TP
+.B %O
+Modifier: use alternative numeric symbols, see below. (SU)
+.TP
+.B %p
+Either "AM" or "PM" according to the given time value, or the
+corresponding strings for the current locale.
+Noon is treated as "PM" and midnight as "AM".
+(Calculated from
+.IR tm_hour .)
+(The specific string representations used for "AM" and "PM"
+in the current locale can be obtained by calling
+.BR nl_langinfo (3)
+with
+.BR AM_STR " and " PM_STR ,
+respectively.)
+.TP
+.B %P
+Like
+.B %p
+but in lowercase: "am" or "pm" or a corresponding
+string for the current locale.
+(Calculated from
+.IR tm_hour .)
+(GNU)
+.TP
+.B %r
+The time in a.m. or p.m. notation.
+(SU)
+(The specific format used in the current locale can be obtained by calling
+.BR nl_langinfo (3)
+with
+.B T_FMT_AMPM
+as an argument.)
+(In the POSIX locale this is equivalent to
+.BR "%I:%M:%S %p" .)
+.TP
+.B %R
+The time in 24-hour notation
+.RB ( %H:%M ).
+(SU)
+For a version including the seconds, see
+.B %T
+below.
+.TP
+.B %s
+The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). (TZ)
+(Calculated from
+.IR mktime(tm) .)
+.TP
+.B %S
+The second as a decimal number (range 00 to 60).
+(The range is up to 60 to allow for occasional leap seconds.)
+(Calculated from
+.IR tm_sec .)
+.TP
+.B %t
+A tab character. (SU)
+.TP
+.B %T
+The time in 24-hour notation
+.RB ( %H:%M:%S ).
+(SU)
+.TP
+.B %u
+The day of the week as a decimal, range 1 to 7, Monday being 1.
+See also
+.BR %w .
+(Calculated from
+.IR tm_wday .)
+(SU)
+.TP
+.B %U
+The week number of the current year as a decimal number,
+range 00 to 53, starting with the first Sunday as the first day
+of week 01.
+See also
+.B %V
+and
+.BR %W .
+(Calculated from
+.I tm_yday
+and
+.IR tm_wday .)
+.TP
+.B %V
+The ISO\~8601 week number (see NOTES) of the current year as a decimal number,
+range 01 to 53, where week 1 is the first week that has at least
+4 days in the new year.
+See also
+.B %U
+and
+.BR %W .
+(Calculated from
+.IR tm_year ,
+.IR tm_yday ,
+and
+.IR tm_wday .)
+(SU)
+.TP
+.B %w
+The day of the week as a decimal, range 0 to 6, Sunday being 0.
+See also
+.BR %u .
+(Calculated from
+.IR tm_wday .)
+.TP
+.B %W
+The week number of the current year as a decimal number,
+range 00 to 53, starting with the first Monday as the first day of week 01.
+(Calculated from
+.I tm_yday
+and
+.IR tm_wday .)
+.TP
+.B %x
+The preferred date representation for the current locale without the time.
+(The specific format used in the current locale can be obtained by calling
+.BR nl_langinfo (3)
+with
+.B D_FMT
+as an argument for the
+.B %x
+conversion specification, and with
+.B ERA_D_FMT
+for the
+.B %Ex
+conversion specification.)
+(In the POSIX locale this is equivalent to
+.BR %m/%d/%y .)
+.TP
+.B %X
+The preferred time representation for the current locale without the date.
+(The specific format used in the current locale can be obtained by calling
+.BR nl_langinfo (3)
+with
+.B T_FMT
+as an argument for the
+.B %X
+conversion specification, and with
+.B ERA_T_FMT
+for the
+.B %EX
+conversion specification.)
+(In the POSIX locale this is equivalent to
+.BR %H:%M:%S .)
+.TP
+.B %y
+The year as a decimal number without a century (range 00 to 99).
+(The
+.B %Ey
+conversion specification corresponds to the year since the beginning of the era
+denoted by the
+.B %EC
+conversion specification.)
+(Calculated from
+.IR tm_year )
+.TP
+.B %Y
+The year as a decimal number including the century.
+(The
+.B %EY
+conversion specification corresponds to
+the full alternative year representation.)
+(Calculated from
+.IR tm_year )
+.TP
+.B %z
+The
+.I +hhmm
+or
+.I \-hhmm
+numeric timezone (that is, the hour and minute offset from UTC). (SU)
+.TP
+.B %Z
+The timezone name or abbreviation.
+.TP
+.B %+
+.\" Nov 05 -- Not in Linux/glibc, but is in some BSDs (according to
+.\" their man pages)
+The date and time in
+.BR date (1)
+format. (TZ)
+(Not supported in glibc2.)
+.TP
+.B %%
+A literal \[aq]%\[aq] character.
+.P
+Some conversion specifications can be modified by preceding the
+conversion specifier character by the
+.B E
+or
+.B O
+.I modifier
+to indicate that an alternative format should be used.
+If the alternative format or specification does not exist for
+the current locale, the behavior will be as if the unmodified
+conversion specification were used. (SU)
+The Single UNIX Specification mentions
+.BR %Ec ,
+.BR %EC ,
+.BR %Ex ,
+.BR %EX ,
+.BR %Ey ,
+.BR %EY ,
+.BR %Od ,
+.BR %Oe ,
+.BR %OH ,
+.BR %OI ,
+.BR %Om ,
+.BR %OM ,
+.BR %OS ,
+.BR %Ou ,
+.BR %OU ,
+.BR %OV ,
+.BR %Ow ,
+.BR %OW ,
+.BR %Oy ,
+where the effect of the
+.B O
+modifier is to use
+alternative numeric symbols (say, roman numerals), and that of the
+.B E
+modifier is to use a locale-dependent alternative representation.
+The rules governing date representation with the
+.B E
+modifier can be obtained by supplying
+.B ERA
+as an argument to a
+.BR nl_langinfo (3).
+One example of such alternative forms is the Japanese era calendar scheme in the
+.B ja_JP
+glibc locale.
+.P
+.BR strftime_l ()
+is equivalent to
+.BR strftime (),
+except it uses the specified
+.I locale
+instead of the current locale.
+The behaviour is undefined if
+.I locale
+is invalid or
+.BR LC_GLOBAL_LOCALE .
+.SH RETURN VALUE
+Provided that the result string,
+including the terminating null byte, does not exceed
+.I max
+bytes,
+.BR strftime ()
+returns the number of bytes (excluding the terminating null byte)
+placed in the array
+.IR s .
+If the length of the result string (including the terminating null byte)
+would exceed
+.I max
+bytes, then
+.BR strftime ()
+returns 0, and the contents of the array are undefined.
+.\" (This behavior applies since at least libc 4.4.4;
+.\" very old versions of libc, such as libc 4.4.1,
+.\" would return
+.\" .I max
+.\" if the array was too small.)
+.P
+Note that the return value 0 does not necessarily indicate an error.
+For example, in many locales
+.B %p
+yields an empty string.
+An empty
+.I format
+string will likewise yield an empty string.
+.SH ENVIRONMENT
+The environment variables
+.B TZ
+and
+.B LC_TIME
+are used.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR strftime (),
+.BR strftime_l ()
+T}	Thread safety	MT-Safe env locale
+.TE
+.SH STANDARDS
+.TP
+.BR strftime ()
+C11, POSIX.1-2008.
+.TP
+.BR strftime_l ()
+POSIX.1-2008.
+.SH HISTORY
+.TP
+.BR strftime ()
+SVr4, C89.
+.\" FIXME strftime() is in POSIX.1-2001 and POSIX.1-2008, but the details
+.\" in the standards changed across versions. Investigate and
+.\" write up.
+.TP
+.BR strftime_l ()
+POSIX.1-2008.
+.P
+There are strict inclusions between the set of conversions
+given in ANSI C (unmarked), those given in the Single UNIX Specification
+(marked SU), those given in Olson's timezone package (marked TZ),
+and those given in glibc (marked GNU), except that
+.B %+
+is not supported in glibc2.
+On the other hand glibc2 has several more extensions.
+POSIX.1 only refers to ANSI C; POSIX.2 describes under
+.BR date (1)
+several extensions that could apply to
+.BR strftime ()
+as well.
+The
+.B %F
+conversion is in C99 and POSIX.1-2001.
+.P
+In SUSv2, the
+.B %S
+specifier allowed a range of 00 to 61,
+to allow for the theoretical possibility of a minute that
+included a double leap second
+(there never has been such a minute).
+.SH NOTES
+.SS ISO\~8601 week dates
+.BR %G ,
+.BR %g ,
+and
+.B %V
+yield values calculated from the week-based year defined by the
+ISO\~8601 standard.
+In this system, weeks start on a Monday, and are numbered from 01,
+for the first week, up to 52 or 53, for the last week.
+Week 1 is the first week where four or more days fall within the
+new year (or, synonymously, week 01 is:
+the first week of the year that contains a Thursday;
+or, the week that has 4 January in it).
+When three or fewer days of the first calendar week of the new year fall
+within that year,
+then the ISO\~8601 week-based system counts those days as part of week 52
+or 53 of the preceding year.
+For example, 1 January 2010 is a Friday,
+meaning that just three days of that calendar week fall in 2010.
+Thus, the ISO\~8601 week-based system considers these days to be part of
+week 53
+.RB ( %V )
+of the year 2009
+.RB ( %G );
+week 01 of ISO\~8601 year 2010 starts on Monday, 4 January 2010.
+Similarly, the first two days of January 2011 are considered to be part
+of week 52 of the year 2010.
+.SS glibc notes
+glibc provides some extensions for conversion specifications.
+(These extensions are not specified in POSIX.1-2001, but a few other
+systems provide similar features.)
+.\" HP-UX and Tru64 also have features like this.
+Between the \[aq]%\[aq] character and the conversion specifier character,
+an optional
+.I flag
+and field
+.I width
+may be specified.
+(These precede the
+.B E
+or
+.B O
+modifiers, if present.)
+.P
+The following flag characters are permitted:
+.TP
+.B _
+(underscore)
+Pad a numeric result string with spaces.
+.TP
+.B \-
+(dash)
+Do not pad a numeric result string.
+.TP
+.B 0
+Pad a numeric result string with zeros even if the conversion
+specifier character uses space-padding by default.
+.TP
+.B \[ha]
+Convert alphabetic characters in result string to uppercase.
+.TP
+.B #
+Swap the case of the result string.
+(This flag works only with certain conversion specifier characters,
+and of these, it is only really useful with
+.BR %Z .)
+.P
+An optional decimal width specifier may follow the (possibly absent) flag.
+If the natural size of the field is smaller than this width,
+then the result string is padded (on the left) to the specified width.
+.SH BUGS
+If the output string would exceed
+.I max
+bytes,
+.I errno
+is
+.I not
+set.
+This makes it impossible to distinguish this error case from cases where the
+.I format
+string legitimately produces a zero-length output string.
+POSIX.1-2001
+does
+.I not
+specify any
+.I errno
+settings for
+.BR strftime ().
+.P
+Some buggy versions of
+.BR gcc (1)
+complain about the use of
+.BR %c :
+.IR "warning: \`%c\[aq] yields only last 2 digits of year in some locales" .
+Of course programmers are encouraged to use
+.BR %c ,
+as it gives the preferred date and time representation.
+One meets all kinds of strange obfuscations
+to circumvent this
+.BR gcc (1)
+problem.
+A relatively clean one is to add an
+intermediate function
+.P
+.in +4n
+.EX
+size_t
+my_strftime(char *s, size_t max, const char *fmt,
+            const struct tm *tm)
+{
+    return strftime(s, max, fmt, tm);
+}
+.EE
+.in
+.P
+Nowadays,
+.BR gcc (1)
+provides the
+.I \-Wno\-format\-y2k
+option to prevent the warning,
+so that the above workaround is no longer required.
+.SH EXAMPLES
+.B RFC\~2822-compliant date format
+(with an English locale for %a and %b)
+.P
+.in +4n
+.EX
+"%a,\ %d\ %b\ %Y\ %T\ %z"
+.EE
+.in
+.P
+.B RFC\~822-compliant date format
+(with an English locale for %a and %b)
+.P
+.in +4n
+.EX
+"%a,\ %d\ %b\ %y\ %T\ %z"
+.EE
+.in
+.SS Example program
+The program below can be used to experiment with
+.BR strftime ().
+.P
+Some examples of the result string produced by the glibc implementation of
+.BR strftime ()
+are as follows:
+.P
+.in +4n
+.EX
+.RB "$" " ./a.out \[aq]%m\[aq]"
+Result string is "11"
+.RB "$" " ./a.out \[aq]%5m\[aq]"
+Result string is "00011"
+.RB "$" " ./a.out \[aq]%_5m\[aq]"
+Result string is "   11"
+.EE
+.in
+.SS Program source
+\&
+.\" SRC BEGIN (strftime.c)
+.EX
+#include <stdio.h>
+#include <stdlib.h>
+#include <time.h>
+\&
+int
+main(int argc, char *argv[])
+{
+    char outstr[200];
+    time_t t;
+    struct tm *tmp;
+\&
+    t = time(NULL);
+    tmp = localtime(&t);
+    if (tmp == NULL) {
+        perror("localtime");
+        exit(EXIT_FAILURE);
+    }
+\&
+    if (strftime(outstr, sizeof(outstr), argv[1], tmp) == 0) {
+        fprintf(stderr, "strftime returned 0");
+        exit(EXIT_FAILURE);
+    }
+\&
+    printf("Result string is \e"%s\e"\en", outstr);
+    exit(EXIT_SUCCESS);
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.BR date (1),
+.BR time (2),
+.BR ctime (3),
+.BR nl_langinfo (3),
+.BR setlocale (3),
+.BR sprintf (3),
+.BR strptime (3)