diff options
Diffstat (limited to 'man3/strftime.3')
| -rw-r--r-- | man3/strftime.3 | 272 |
1 files changed, 272 insertions, 0 deletions
diff --git a/man3/strftime.3 b/man3/strftime.3 new file mode 100644 index 000000000..45029e2f7 --- /dev/null +++ b/man3/strftime.3 @@ -0,0 +1,272 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" 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. +.\" +.TH STRFTIME 3 1999-03-29 "GNU" "Linux Programmer's Manual" +.SH NAME +strftime \- format date and time +.SH SYNOPSIS +.nf +.B #include <time.h> +.sp +.BI "size_t strftime(char *" s ", size_t " max ", const char *" format , +.BI " const struct tm *" tm ); +.fi +.SH DESCRIPTION +The \fBstrftime()\fP function formats the broken-down time \fItm\fP +according to the format specification \fIformat\fP and places the +result in the character array \fIs\fP of size \fImax\fP. +.PP +Ordinary characters placed in the format string are copied to \fIs\fP +without conversion. Conversion specifiers are introduced by a `%' +character, and are replaced in \fIs\fP as follows: +.TP +.B %a +The abbreviated weekday name according to the current locale. +.TP +.B %A +The full weekday name according to the current locale. +.TP +.B %b +The abbreviated month name according to the current locale. +.TP +.B %B +The full month name according to the current locale. +.TP +.B %c +The preferred date and time representation for the current locale. +.TP +.B %C +The century number (year/100) as a 2-digit integer. (SU) +.TP +.B %d +The day of the month as a decimal number (range 01 to 31). +.TP +.B %D +Equivalent to %m/%d/%y. (Yecch - for Americans only. +Americans should note that in other countries %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 %d, the day of the month as a decimal number, but a leading +zero is replaced by a space. (SU) +.TP +.B %E +Modifier: use alternative format, see below. (SU) +.TP +.B %F +Equivalent to %Y-%m-%d (the ISO 8601 date format). (C99) +.TP +.B %G +The ISO 8601 year with century as a decimal number. +The 4-digit year corresponding to the ISO week number (see %V). +This has the same format and value as %y, except that if the +ISO week number belongs to the previous or next year, +that year is used instead. (TZ) +.TP +.B %g +Like %G, but without century, i.e., with a 2-digit year (00-99). (TZ) +.TP +.B %h +Equivalent to %b. (SU) +.TP +.B %H +The hour as a decimal number using a 24-hour clock (range 00 to 23). +.TP +.B %I +The hour as a decimal number using a 12-hour clock (range 01 to 12). +.TP +.B %j +The day of the year as a decimal number (range 001 to 366). +.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 %H.) (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 %I.) (TZ) +.TP +.B %m +The month as a decimal number (range 01 to 12). +.TP +.B %M +The minute as a decimal number (range 00 to 59). +.TP +.B %n +A newline character. (SU) +.TP +.B %O +Modifier: use alternative format, 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'. +.TP +.B %P +Like %p but in lowercase: `am' or `pm' or a corresponding +string for the current locale. (GNU) +.TP +.B %r +The time in a.m. or p.m. notation. +In the POSIX locale this is equivalent to `%I:%M:%S %p'. (SU) +.TP +.B %R +The time in 24-hour notation (%H:%M). (SU) +For a version including the seconds, see %T below. +.TP +.B %s +The number of seconds since the Epoch, i.e., since 1970-01-01 +00:00:00 UTC. (TZ) +.TP +.B %S +The second as a decimal number (range 00 to 61). +.TP +.B %t +A tab character. (SU) +.TP +.B %T +The time in 24-hour notation (%H:%M:%S). (SU) +.TP +.B %u +The day of the week as a decimal, range 1 to 7, Monday being 1. +See also %w. (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 %V and %W. +.TP +.B %V +The ISO 8601:1988 week number 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 current year, and with Monday as the first day of +the week. See also %U and %W. (SU) +.TP +.B %w +The day of the week as a decimal, range 0 to 6, Sunday being 0. +See also %u. +.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. +.TP +.B %x +The preferred date representation for the current locale without the time. +.TP +.B %X +The preferred time representation for the current locale without the date. +.TP +.B %y +The year as a decimal number without a century (range 00 to 99). +.TP +.B %Y +The year as a decimal number including the century. +.TP +.B %z +The time-zone as hour offset from GMT. +Required to emit RFC822-conformant dates +(using "%a, %d %b %Y %H:%M:%S %z"). (GNU) +.TP +.B %Z +The time zone or name or abbreviation. +.TP +.B %+ +The date and time in date(1) format. (TZ) +.TP +.B %% +A literal `%' character. +.PP +Some conversion specifiers can be modified by preceding them +by the E or O modifier to indicate that an alternative format +should be used. +If the alternative format or specification does not exist for +the current locale, the behaviour will be as if the unmodified +conversion specification were used. (SU) +The Single Unix Specification mentions %Ec, %EC, %Ex, %EX, +%Ry, %EY, %Od, %Oe, %OH, %OI, %Om, %OM, %OS, %Ou, %OU, %OV, +%Ow, %OW, %Oy, where the effect of the O modifier is to use +alternative numeric symbols (say, roman numerals), and that of the +E modifier is to use a locale-dependent alternative representation. +.PP +The broken-down time structure \fItm\fP is defined in \fI<time.h>\fP. +See also +.BR ctime (3). + +.SH "RETURN VALUE" +The \fBstrftime()\fP function returns the number of characters placed +in the array \fIs\fP, not including the terminating NUL character, +provided the string, including the terminating NUL, fits. +Otherwise, it returns 0, and the contents of the array is undefined. +(Thus at least since libc 4.4.4; very old versions of libc, +such as libc 4.4.1, would return \fImax\fP if the array was too small.) +.LP +Note that the return value 0 does not necessarily indicate an error; +for example, in many locales %p yields an empty string. +.SH ENVIRONMENT +The environment variables TZ and LC_TIME are used. +.SH "CONFORMING TO" +ANSI C, SVID 3, ISO 9899. +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 %+ 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 +.B strftime +as well. +The %F conversion is in C99 and POSIX 1003.1-2001. +.SH BUGS +Some buggy versions of gcc complain about the use of %c: +.IR "warning: `%c' yields only last 2 digits of year in some locales" . +Of course programmers are encouraged to use %c, it gives the preferred +date and time representation. One meets all kinds of strange obfuscations +to circumvent this gcc problem. A relatively clean one is to add an +intermediate function +.RS +size_t my_strftime(char *s, size_t max, const char *fmt, +const struct tm *tm) { +.br + return strftime(s, max, fmt, tm); +.br +} +.RE +.SH "SEE ALSO" +.BR date (1), +.BR time (2), +.BR ctime (3), +.BR setlocale (3), +.BR sprintf (3), +.BR strptime (3) |