diff options
Diffstat (limited to 'missing_d/strftime.3')
| -rw-r--r-- | missing_d/strftime.3 | 359 |
1 files changed, 359 insertions, 0 deletions
diff --git a/missing_d/strftime.3 b/missing_d/strftime.3 new file mode 100644 index 00000000..b017bf45 --- /dev/null +++ b/missing_d/strftime.3 @@ -0,0 +1,359 @@ +.TH STRFTIME 3 +.SH NAME +strftime \- generate formatted time information +.SH SYNOPSIS +.ft B +.nf +#include <sys/types.h> +#include <time.h> +.sp +size_t strftime(char *s, size_t maxsize, const char *format, + const struct tm *timeptr); +.fi +.SH DESCRIPTION +The following description is transcribed verbatim from the January 18, 1999 +draft standard for ISO C. +This draft is essentially identical in technical content +to the final version of the standard. +.LP +``The +.B strftime +function places characters into the array pointed to by +.B s +as controlled by the string pointed to by +.BR format . +The format shall be a multibyte character sequence, beginning and ending in +its initial shift state. +The +.B format +string consists of zero or more conversion specifiers and ordinary +multibyte characters. A conversion specifier consists of a +.B % +character, possibly followed by an +.B E +or +.B O +modifier character (described below), +followed by a character that determines the behavior of the +conversion specifier. +All ordinary multibyte characters (including the terminating null +character) are copied unchanged into the array. +If copying takes place between objects that overlap the behavior is undefined. +No more than +.B maxsize +characters are placed into the array. +.PP +``Each conversion specifier is replaced by appropriate characters as described +in the following list. +The appropriate characters are determined by the +.B LC_TIME +category of the current locale and by the values +of zero or more members of the broken-down time +structure pointed to by +.BR timeptr , +as specified by brackets in the description. +If any of the specified values is outside the normal range, the characters +stored are unspecified.'' +.TP +.B %a +is replaced by the locale's abbreviated weekday name. +.TP +.B %A +is replaced by the locale's full weekday name. +.TP +.B %b +is replaced by the locale's abbreviated month name. +.TP +.B %B +is replaced by the locale's full month name. +.TP +.B %c +is replaced by the locale's appropriate date and time representation. +(This is +.B "%A %B %d %T %Y" +in the \fB"C"\fR +locale.) +.TP +.B %C +is replaced by the year divided by 100 and truncated to an integer, +as a decimal number +.RB ( 00 - 99 ). +.TP +.B %d +is replaced by the day of the month as a decimal number +.RB ( 01 - 31 ). +.TP +.B %D +is equivalent to +.BR %m/%d/%y . +.TP +.B %e +is replaced by the day of the month as a decimal number +.RB ( 1 - 31 ); +a single digit is preceded by a space. +.TP +.B %F +is equivalent to +.B %Y\-%m\-%d +(the ISO 8601 date format). +.TP +.B %g +is replaced by the year without century of the ISO week number +as a decimal number +.RB ( 00 - 99 ). +.TP +.B %G +is replaced by the year with century of the ISO week number +as a decimal number. +.TP +.B %h +is equivalent to +.BR %b . +.TP +.B %H +is replaced by the hour (24-hour clock) as a decimal number +.RB ( 00 - 23 ). +.TP +.B %I +is replaced by the hour (12-hour clock) as a decimal number +.RB ( 01 - 12 ). +.TP +.B %j +is replaced by the day of the year as a decimal number +.RB ( 001 - 366 ). +.TP +.B %m +is replaced by the month as a decimal number +.RB ( 01 - 12 ). +.TP +.B %M +is replaced by the minute as a decimal number +.RB ( 00 - 59 ). +.TP +.B %n +is replaced with a newline character (\s-1ASCII LF\s+1). +.TP +.B %p +is replaced by the locale's equivalent of the AM/PM designations associated +with a 12-hour clock. +.TP +.B %r +is replaced by the locale's 12-hour clock time. +(This is +.B "%I:%M:%S %p" +in the \fB"C"\fR +locale.) +.TP +.B %R +is equivalent to +.BR %H:%M . +.TP +.B %S +is replaced by the second as a decimal number +.RB ( 00 - 60 ). +.TP +.B %t +is replaced with a \s-1TAB\s+1 character. +.TP +.B %T +is equivalent to +.BR %H:%M:%S . +.TP +.B %u +is replaced by the ISO 8601 weekday as a decimal number +.RB [ "1 " (Monday)- 7 ]. +.TP +.B %U +is replaced by the week number of the year (the first Sunday as the first +day of week 1) as a decimal number +.RB ( 00 - 53 ). +.TP +.B %V +is replaced by the ISO 8601 week number of the year (the first Monday as the first +day of week 1) as a decimal number +.RB ( 01 - 53 ). +.TP +.B %w +is replaced by the weekday as a decimal number +.RB [ "0 " (Sunday)- 6 ]. +.TP +.B %W +is replaced by the week number of the year (the first Monday as the first +day of week 1) as a decimal number +.RB ( 00 - 53 ). +.TP +.B %x +is replaced by the locale's appropriate date representation. +(This is +.B "%A %B %d %Y" +in the \fB"C"\fR +locale.) +.TP +.B %X +is replaced by the locale's appropriate time representation. +(This is +.B "%T" +in the \fB"C"\fR +locale.) +.TP +.B %y +is replaced by the year without century as a decimal number +.RB ( 00 - 99 ). +.TP +.B %Y +is replaced by the year with century as a decimal number. +.TP +.B %z +The timezone offset in a +HHMM format (e.g. the format necessary to +produce RFC-822/RFC-1036 date headers). +.TP +.B %Z +is replaced by the time zone name or abbreviation, or by no characters if +no time zone is determinable. +.TP +.B %% +is replaced by +.BR % . +.LP +If a conversion specifier is not one of the above, the behavior is +undefined. +.SH RETURNS +If the total number of resulting characters including the terminating null +character is not more than +.BR maxsize , +the +.B strftime +function returns the number of characters placed into the array pointed to +by +.B s +not including the terminating null character. +Otherwise, zero is returned and the contents of the array are indeterminate. +.SH ISO 8601 +The method for determining the week number as specified by ISO 8601 is: +if the week containing January 1 has four or more days in the +new year, then it is week 1, otherwise it is the highest numbered +week of the previous year (52 or 53) +and the next week is week 1. +All days in a new year preceding the first Monday are considered to be +in week 0. +.PP +For example, January 1, 1993, is in week 53 of 1992. Thus, the year +of its ISO week number is 1992, even though its year is 1993. +Similarly, December 31, 1973, is in week 1 of 1974. Thus, the year +of its ISO week number is 1974, even though its year is 1973. +.SH ALTERNATE REPRESENTATIONS +The alternate representations +.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 , +and +.B %Oy +are recognized, but their normal representations are used. +.SH NON-ISO EXTENSIONS +.SS SunOS Extensions +If +.B SUNOS_EXT +is defined when the routine is compiled, then the following additional +conversions will be available. +These are borrowed from the SunOS version of +.IR strftime . +.TP +.B %k +is replaced by the hour (24-hour clock) as a decimal number +.RB ( 0 - 23 ). +Single digit numbers are padded with a blank. +.TP +.B %l +is replaced by the hour (12-hour clock) as a decimal number +.RB ( 1 - 12 ). +Single digit numbers are padded with a blank. +.SS HP/UX Extensions +If +.B HPUX_EXT +is defined when the routine is compiled, then the following additional +conversions will be available. +These are borrowed from the HP-UX version of +.IR date . +.TP +.B %N +The ``Emporer/Era'' name. +Typically, this is equivalent to the century +(same as +.B %C ). +.TP +.B %o +The ``Emporer/Era'' year. +Typically, this is equivalent to the year +(same as +.B %y ). +.SS VMS Extensions +If +.B VMS_EXT +is defined, then the following additional conversion is available: +.TP +.B %v +The date in VMS format (e.g. 20-JUN-1991). +.SS Other Extensions +If +.B HAVE_MKTIME +is defined, then this conversion is available: +.TP +.B %s +The time in ``seconds since the Epoch,'' +usually Midnight January 1, 1970, UTC. +.SH SEE ALSO +.IR time (2), +.IR ctime (3), +.IR localtime (3), +.IR mktime (3), +.IR tzset (3) +.SH BUGS +This version does not handle multibyte characters or pay attention to the +setting of the +.B LC_TIME +environment variable. +.LP +The ``appropriate'' values used for +.BR %c , +.BR %x , +are +.B %X +are always those specified by the 1999 ISO C standard for the \fB"C"\fR locale. +.SH CAVEATS +The pre-processor symbol +.B POSIX_SEMANTICS +is automatically defined, which forces the code to call +.IR tzset (3) +whenever the +.B TZ +environment variable has changed. +If this routine will be used in an application that will not be changing +.BR TZ , +then there may be some performance improvements by not defining +.BR POSIX_SEMANTICS . +.SH AUTHOR +Arnold Robbins <arnold@skeeve.com> +.SH ACKNOWLEDGEMENTS +Thanks to Geoff Clare <gwc@root.co.uk> for helping debug earlier +versions of this routine, and for advice about POSIX semantics. +Additional thanks to Arthur David Olsen <ado@elsie.nci.nih.gov> +for some code improvements. +Thanks also to Tor Lillqvist <tml@tik.vtt.fi> +for code fixes to the ISO 8601 code. +Thanks to Hume Smith for pointing out a problem with the ISO 8601 code +and to Arthur David Olsen for further discussions. |