354 lines
8.4 KiB
Groff
354 lines
8.4 KiB
Groff
.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);
|
|
.SH DESCRIPTION
|
|
The following description is transcribed verbatim from the December 7, 1988
|
|
draft standard for ANSI 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 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.
|
|
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 contained in the
|
|
structure pointed to by
|
|
.BR timeptr .
|
|
.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.
|
|
.TP
|
|
.B %d
|
|
is replaced by the day of the month as a decimal number
|
|
.RB ( 01 - 31 ).
|
|
.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 %p
|
|
is replaced by the locale's equivalent of the AM/PM designations associated
|
|
with a 12-hour clock.
|
|
.TP
|
|
.B %S
|
|
is replaced by the second as a decimal number
|
|
.RB ( 00 - 60 ).
|
|
.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 %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.
|
|
.TP
|
|
.B %X
|
|
is replaced by the locale's appropriate time representation.
|
|
.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
|
|
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 NON-ANSI EXTENSIONS
|
|
If
|
|
.B SYSV_EXT
|
|
is defined when the routine is compiled, then the following additional
|
|
conversions will be available.
|
|
These are borrowed from the System V
|
|
.IR cftime (3)
|
|
and
|
|
.IR ascftime (3)
|
|
routines.
|
|
.TP
|
|
.B %D
|
|
is equivalent to specifying
|
|
.BR %m/%d/%y .
|
|
.TP
|
|
.B %e
|
|
is replaced by the day of the month,
|
|
padded with a blank if it is only one digit.
|
|
.TP
|
|
.B %h
|
|
is equivalent to
|
|
.BR %b ,
|
|
above.
|
|
.TP
|
|
.B %n
|
|
is replaced with a newline character (\s-1ASCII LF\s+1).
|
|
.TP
|
|
.B %r
|
|
is equivalent to specifying
|
|
.BR "%I:%M:%S %p" .
|
|
.TP
|
|
.B %R
|
|
is equivalent to specifying
|
|
.BR %H:%M .
|
|
.TP
|
|
.B %T
|
|
is equivalent to specifying
|
|
.BR %H:%M:%S .
|
|
.TP
|
|
.B %t
|
|
is replaced with a \s-1TAB\s+1 character.
|
|
.PP
|
|
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.
|
|
.SH POSIX 1003.2 EXTENSIONS
|
|
If
|
|
.B POSIX2_DATE
|
|
is defined, then all of the conversions available with
|
|
.B SYSV_EXT
|
|
and
|
|
.B SUNOS_EXT
|
|
are available, as well as the
|
|
following additional conversions:
|
|
.TP
|
|
.B %C
|
|
The century, as a number between 00 and 99.
|
|
.TP
|
|
.B %u
|
|
is replaced by the weekday as a decimal number
|
|
.RB [ "1 " (Monday)- 7 ].
|
|
.TP
|
|
.B %V
|
|
is replaced by the week number of the year (the first Monday as the first
|
|
day of week 1) as a decimal number
|
|
.RB ( 01 - 53 ).
|
|
The method for determining the week number is as specified by ISO 8601
|
|
(to wit: 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).
|
|
.LP
|
|
The text of the POSIX standard for the
|
|
.I date
|
|
utility describes
|
|
.B %U
|
|
and
|
|
.B %W
|
|
this way:
|
|
.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 ).
|
|
All days in a new year preceding the first Sunday are considered to be
|
|
in week 0.
|
|
.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 ).
|
|
All days in a new year preceding the first Monday are considered to be
|
|
in week 0.
|
|
.LP
|
|
In addition, the alternate representations
|
|
.BR %Ec ,
|
|
.BR %EC ,
|
|
.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 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).
|
|
.SH MAIL HEADER EXTENSIONS
|
|
If
|
|
.B MAILHEADER_EXT
|
|
is defined, then the following additional conversion is available:
|
|
.TP
|
|
.B %z
|
|
The timezone offset in a +HHMM format (e.g. the format necessary to
|
|
produce RFC-822/RFC-1036 date headers).
|
|
.SH ISO DATE FORMAT EXTENSIONS
|
|
If
|
|
.B ISO_DATE_EXT
|
|
is defined, then all of the conversions available with
|
|
.BR POSIX2_DATE,
|
|
.BR SYSV_EXT,
|
|
and
|
|
.B SUNOS_EXT
|
|
are available, as well as the
|
|
following additional conversions:
|
|
.TP
|
|
.B %G
|
|
is replaced by the year with century of the ISO week number (see
|
|
.BR %V ,
|
|
above) as a decimal number.
|
|
.TP
|
|
.B %g
|
|
is replaced by the year without century of the ISO week number,
|
|
as a decimal number
|
|
.RB ( 00 - 99 ).
|
|
.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 SEE ALSO
|
|
.IR time (2),
|
|
.IR ctime (3),
|
|
.IR localtime (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 those specified by the 1003.2 standard for the POSIX 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
|
|
.nf
|
|
Arnold Robbins
|
|
.sp
|
|
INTERNET: arnold@gnu.ai.mit.edu
|
|
.fi
|
|
.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.
|