diff options
Diffstat (limited to 'man3/strftime.3')
| -rw-r--r-- | man3/strftime.3 | 780 |
1 files changed, 0 insertions, 780 deletions
diff --git a/man3/strftime.3 b/man3/strftime.3 deleted file mode 100644 index 6d77faf14..000000000 --- a/man3/strftime.3 +++ /dev/null @@ -1,780 +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 (date) "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> -.PP -.BI "size_t strftime(char " s "[restrict ." max "], size_t " max , -.BI " const char *restrict " format , -.BI " const struct tm *restrict " tm ); -.PP -.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 -.PP -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". -.PP -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. -.PP -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. -.PP -.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.) -.PP -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). -.ad l -.nh -.TS -allbox; -lbx lb lb -l l l. -Interface Attribute Value -T{ -.BR strftime (), -.BR strftime_l () -T} Thread safety MT-Safe env locale -.TE -.hy -.ad -.sp 1 -.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. -.PP -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. -.PP -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.) -.PP -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 .) -.PP -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 (). -.PP -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 -.PP -.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 -.PP -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) -.PP -.in +4n -.EX -"%a,\ %d\ %b\ %Y\ %T\ %z" -.EE -.in -.PP -.B RFC\~822-compliant date format -(with an English locale for %a and %b) -.PP -.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 (). -.PP -Some examples of the result string produced by the glibc implementation of -.BR strftime () -are as follows: -.PP -.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) |