summaryrefslogtreecommitdiffstats
path: root/man3/strftime.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/strftime.3')
-rw-r--r--man3/strftime.3777
1 files changed, 0 insertions, 777 deletions
diff --git a/man3/strftime.3 b/man3/strftime.3
deleted file mode 100644
index 191c0f4..0000000
--- a/man3/strftime.3
+++ /dev/null
@@ -1,777 +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
-.\" 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-01-28 "Linux man-pages 6.7"
-.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)