mirror of https://github.com/mkerrisk/man-pages
430 lines
14 KiB
Plaintext
430 lines
14 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "STRFTIME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" strftime
|
|
.SH NAME
|
|
strftime \- convert date and time to a string
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <time.h>
|
|
.br
|
|
.sp
|
|
size_t strftime(char *restrict\fP \fIs\fP\fB, size_t\fP \fImaxsize\fP\fB,
|
|
.br
|
|
\ \ \ \ \ \ const char *restrict\fP \fIformat\fP\fB, const struct
|
|
tm *restrict\fP
|
|
\fItimeptr\fP\fB);
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fIstrftime\fP() function shall place bytes into the array pointed
|
|
to by \fIs\fP as controlled by the string pointed to by
|
|
\fIformat\fP. The format is a character string, beginning and ending
|
|
in its initial shift state, if any. The \fIformat\fP string
|
|
consists of zero or more conversion specifications and ordinary characters.
|
|
A conversion specification consists of a \fB'%'\fP
|
|
character, possibly followed by an \fBE\fP or \fBO\fP modifier, and
|
|
a terminating conversion specifier character that
|
|
determines the conversion specification's behavior. All ordinary characters
|
|
(including the terminating null byte) are copied
|
|
unchanged into the array. If copying takes place between objects that
|
|
overlap, the behavior is undefined. No more than
|
|
\fImaxsize\fP bytes are placed into the array. Each conversion specifier
|
|
is replaced by appropriate characters as described in the
|
|
following list. The appropriate characters are determined using the
|
|
\fILC_TIME\fP category of the current locale and by the values
|
|
of zero or more members of the broken-down time structure pointed
|
|
to by \fItimeptr\fP, as specified in brackets in the
|
|
description. If any of the specified values are outside the normal
|
|
range, the characters stored are unspecified.
|
|
.LP
|
|
Local timezone information is used as though \fIstrftime\fP() called
|
|
\fItzset\fP().
|
|
.LP
|
|
The following conversion specifications are supported:
|
|
.TP 7
|
|
\fB%a\fP
|
|
Replaced by the locale's abbreviated weekday name. [ \fItm_wday\fP]
|
|
.TP 7
|
|
\fB%A\fP
|
|
Replaced by the locale's full weekday name. [ \fItm_wday\fP]
|
|
.TP 7
|
|
\fB%b\fP
|
|
Replaced by the locale's abbreviated month name. [ \fItm_mon\fP]
|
|
.TP 7
|
|
\fB%B\fP
|
|
Replaced by the locale's full month name. [ \fItm_mon\fP]
|
|
.TP 7
|
|
\fB%c\fP
|
|
Replaced by the locale's appropriate date and time representation.
|
|
(See the Base Definitions volume of
|
|
IEEE\ Std\ 1003.1-2001, \fI<time.h>\fP.)
|
|
.TP 7
|
|
\fB%C\fP
|
|
Replaced by the year divided by 100 and truncated to an integer, as
|
|
a decimal number [00,99]. [ \fItm_year\fP]
|
|
.TP 7
|
|
\fB%d\fP
|
|
Replaced by the day of the month as a decimal number [01,31]. [ \fItm_mday\fP]
|
|
.TP 7
|
|
\fB%D\fP
|
|
Equivalent to \fB%m\fP / \fB%d\fP / \fB%y\fP . [ \fItm_mon\fP, \fItm_mday\fP,
|
|
\fItm_year\fP]
|
|
.TP 7
|
|
\fB%e\fP
|
|
Replaced by the day of the month as a decimal number [1,31]; a single
|
|
digit is preceded by a space. [ \fItm_mday\fP]
|
|
.TP 7
|
|
\fB%F\fP
|
|
Equivalent to \fB%Y\fP - \fB%m\fP - \fB%d\fP (the ISO\ 8601:2000 standard
|
|
date format). [ \fItm_year\fP,
|
|
\fItm_mon\fP, \fItm_mday\fP]
|
|
.TP 7
|
|
\fB%g\fP
|
|
Replaced by the last 2 digits of the week-based year (see below) as
|
|
a decimal number [00,99]. [ \fItm_year\fP, \fItm_wday\fP,
|
|
\fItm_yday\fP]
|
|
.TP 7
|
|
\fB%G\fP
|
|
Replaced by the week-based year (see below) as a decimal number (for
|
|
example, 1977). [ \fItm_year\fP, \fItm_wday\fP,
|
|
\fItm_yday\fP]
|
|
.TP 7
|
|
\fB%h\fP
|
|
Equivalent to \fB%b\fP . [ \fItm_mon\fP]
|
|
.TP 7
|
|
\fB%H\fP
|
|
Replaced by the hour (24-hour clock) as a decimal number [00,23].
|
|
[ \fItm_hour\fP]
|
|
.TP 7
|
|
\fB%I\fP
|
|
Replaced by the hour (12-hour clock) as a decimal number [01,12].
|
|
[ \fItm_hour\fP]
|
|
.TP 7
|
|
\fB%j\fP
|
|
Replaced by the day of the year as a decimal number [001,366]. [ \fItm_yday\fP]
|
|
.TP 7
|
|
\fB%m\fP
|
|
Replaced by the month as a decimal number [01,12]. [ \fItm_mon\fP]
|
|
.TP 7
|
|
\fB%M\fP
|
|
Replaced by the minute as a decimal number [00,59]. [ \fItm_min\fP]
|
|
.TP 7
|
|
\fB%n\fP
|
|
Replaced by a <newline>.
|
|
.TP 7
|
|
\fB%p\fP
|
|
Replaced by the locale's equivalent of either a.m. or p.m. [ \fItm_hour\fP]
|
|
.TP 7
|
|
\fB%r\fP
|
|
Replaced by the time in a.m. and p.m. notation; \ in the POSIX locale
|
|
this shall be equivalent to \fB%I\fP :
|
|
\fB%M\fP : \fB%S\fP \fB%p\fP . [ \fItm_hour\fP,
|
|
\fItm_min\fP, \fItm_sec\fP]
|
|
.TP 7
|
|
\fB%R\fP
|
|
Replaced by the time in 24-hour notation ( \fB%H\fP : \fB%M\fP ).
|
|
[ \fItm_hour\fP, \fItm_min\fP]
|
|
.TP 7
|
|
\fB%S\fP
|
|
Replaced by the second as a decimal number [00,60]. [ \fItm_sec\fP]
|
|
.TP 7
|
|
\fB%t\fP
|
|
Replaced by a <tab>.
|
|
.TP 7
|
|
\fB%T\fP
|
|
Replaced by the time ( \fB%H\fP : \fB%M\fP : \fB%S\fP ). [ \fItm_hour\fP,
|
|
\fItm_min\fP, \fItm_sec\fP]
|
|
.TP 7
|
|
\fB%u\fP
|
|
Replaced by the weekday as a decimal number [1,7], with 1 representing
|
|
Monday. [ \fItm_wday\fP]
|
|
.TP 7
|
|
\fB%U\fP
|
|
Replaced by the week number of the year as a decimal number [00,53].
|
|
The first Sunday of January is the first day of week 1;
|
|
days in the new year before this are in week 0. [ \fItm_year\fP, \fItm_wday\fP,
|
|
\fItm_yday\fP]
|
|
.TP 7
|
|
\fB%V\fP
|
|
Replaced by the week number of the year (Monday as the first day of
|
|
the week) as a decimal number [01,53]. If the week
|
|
containing 1 January has four or more days in the new year, then it
|
|
is considered week 1. Otherwise, it is the last week of the
|
|
previous year, and the next week is week 1. Both January 4th and the
|
|
first Thursday of January are always in week 1. [
|
|
\fItm_year\fP, \fItm_wday\fP, \fItm_yday\fP]
|
|
.TP 7
|
|
\fB%w\fP
|
|
Replaced by the weekday as a decimal number [0,6], with 0 representing
|
|
Sunday. [ \fItm_wday\fP]
|
|
.TP 7
|
|
\fB%W\fP
|
|
Replaced by the week number of the year as a decimal number [00,53].
|
|
The first Monday of January is the first day of week 1;
|
|
days in the new year before this are in week 0. [ \fItm_year\fP, \fItm_wday\fP,
|
|
\fItm_yday\fP]
|
|
.TP 7
|
|
\fB%x\fP
|
|
Replaced by the locale's appropriate date representation. (See the
|
|
Base Definitions volume of IEEE\ Std\ 1003.1-2001,
|
|
\fI<time.h>\fP.)
|
|
.TP 7
|
|
\fB%X\fP
|
|
Replaced by the locale's appropriate time representation. (See the
|
|
Base Definitions volume of IEEE\ Std\ 1003.1-2001,
|
|
\fI<time.h>\fP.)
|
|
.TP 7
|
|
\fB%y\fP
|
|
Replaced by the last two digits of the year as a decimal number [00,99].
|
|
[ \fItm_year\fP]
|
|
.TP 7
|
|
\fB%Y\fP
|
|
Replaced by the year as a decimal number (for example, 1997). [ \fItm_year\fP]
|
|
.TP 7
|
|
\fB%z\fP
|
|
Replaced by the offset from UTC in the ISO\ 8601:2000 standard format
|
|
( \fB+hhmm\fP or \fB-hhmm\fP ), or by no
|
|
characters if no timezone is determinable. For example, \fB"-0430"\fP
|
|
means 4 hours 30 minutes behind UTC (west of Greenwich).
|
|
\ If \fItm_isdst\fP is zero, the standard time offset is used. If
|
|
\fItm_isdst\fP is greater than zero, the daylight savings
|
|
time offset is used. If \fItm_isdst\fP is negative, no characters
|
|
are returned. [ \fItm_isdst\fP]
|
|
.TP 7
|
|
\fB%Z\fP
|
|
Replaced by the timezone name or abbreviation, or by no bytes if no
|
|
timezone information exists. [ \fItm_isdst\fP]
|
|
.TP 7
|
|
\fB%%\fP
|
|
Replaced by \fB%\fP .
|
|
.sp
|
|
.LP
|
|
If a conversion specification does not correspond to any of the above,
|
|
the behavior is undefined.
|
|
.LP
|
|
If
|
|
a \fBstruct tm\fP broken-down time structure is created by \fIlocaltime\fP()
|
|
or \fIlocaltime_r\fP(), or modified by \fImktime\fP(), and the value
|
|
of \fITZ\fP is subsequently modified, the results of the \fB%Z\fP
|
|
and \fB%z\fP \fIstrftime\fP() conversion specifiers are undefined,
|
|
when \fIstrftime\fP() is called with such a broken-down
|
|
time structure.
|
|
.LP
|
|
If a \fBstruct tm\fP broken-down time structure is created or modified
|
|
by \fIgmtime\fP() or \fIgmtime_r\fP(), it is unspecified
|
|
whether the result of the \fB%Z\fP and \fB%z\fP conversion specifiers
|
|
shall refer to UTC or the current local timezone, when
|
|
\fIstrftime\fP() is called with such a broken-down time structure.
|
|
.SS Modified Conversion Specifiers
|
|
.LP
|
|
Some conversion specifiers can be modified by the \fBE\fP or \fBO\fP
|
|
modifier characters to indicate that an alternative
|
|
format or specification should be used rather than the one normally
|
|
used by the unmodified conversion specifier. If the alternative
|
|
format or specification does not exist for the current locale (see
|
|
ERA in the Base Definitions volume of
|
|
IEEE\ Std\ 1003.1-2001, Section 7.3.5, LC_TIME), the behavior shall
|
|
be as if the unmodified conversion specification were used.
|
|
.TP 7
|
|
\fB%Ec\fP
|
|
Replaced by the locale's alternative appropriate date and time representation.
|
|
.TP 7
|
|
\fB%EC\fP
|
|
Replaced by the name of the base year (period) in the locale's alternative
|
|
representation.
|
|
.TP 7
|
|
\fB%Ex\fP
|
|
Replaced by the locale's alternative date representation.
|
|
.TP 7
|
|
\fB%EX\fP
|
|
Replaced by the locale's alternative time representation.
|
|
.TP 7
|
|
\fB%Ey\fP
|
|
Replaced by the offset from \fB%EC\fP (year only) in the locale's
|
|
alternative representation.
|
|
.TP 7
|
|
\fB%EY\fP
|
|
Replaced by the full alternative year representation.
|
|
.TP 7
|
|
\fB%Od\fP
|
|
Replaced by the day of the month, using the locale's alternative numeric
|
|
symbols, filled as needed with leading zeros if there
|
|
is any alternative symbol for zero; otherwise, with leading spaces.
|
|
.TP 7
|
|
\fB%Oe\fP
|
|
Replaced by the day of the month, using the locale's alternative numeric
|
|
symbols, filled as needed with leading spaces.
|
|
.TP 7
|
|
\fB%OH\fP
|
|
Replaced by the hour (24-hour clock) using the locale's alternative
|
|
numeric symbols.
|
|
.TP 7
|
|
\fB%OI\fP
|
|
Replaced by the hour (12-hour clock) using the locale's alternative
|
|
numeric symbols.
|
|
.TP 7
|
|
\fB%Om\fP
|
|
Replaced by the month using the locale's alternative numeric symbols.
|
|
.TP 7
|
|
\fB%OM\fP
|
|
Replaced by the minutes using the locale's alternative numeric symbols.
|
|
.TP 7
|
|
\fB%OS\fP
|
|
Replaced by the seconds using the locale's alternative numeric symbols.
|
|
.TP 7
|
|
\fB%Ou\fP
|
|
Replaced by the weekday as a number in the locale's alternative representation
|
|
(Monday=1).
|
|
.TP 7
|
|
\fB%OU\fP
|
|
Replaced by the week number of the year (Sunday as the first day of
|
|
the week, rules corresponding to \fB%U\fP ) using the
|
|
locale's alternative numeric symbols.
|
|
.TP 7
|
|
\fB%OV\fP
|
|
Replaced by the week number of the year (Monday as the first day of
|
|
the week, rules corresponding to \fB%V\fP ) using the
|
|
locale's alternative numeric symbols.
|
|
.TP 7
|
|
\fB%Ow\fP
|
|
Replaced by the number of the weekday (Sunday=0) using the locale's
|
|
alternative numeric symbols.
|
|
.TP 7
|
|
\fB%OW\fP
|
|
Replaced by the week number of the year (Monday as the first day of
|
|
the week) using the locale's alternative numeric
|
|
symbols.
|
|
.TP 7
|
|
\fB%Oy\fP
|
|
Replaced by the year (offset from \fB%C\fP ) using the locale's alternative
|
|
numeric symbols.
|
|
.sp
|
|
.LP
|
|
\fB%g\fP , \fB%G\fP , and \fB%V\fP give values according to the ISO\ 8601:2000
|
|
standard week-based year. In this
|
|
system, weeks begin on a Monday and week 1 of the year is the week
|
|
that includes January 4th, which is also the week that includes
|
|
the first Thursday of the year, and is also the first week that contains
|
|
at least four days in the year. If the first Monday of
|
|
January is the 2nd, 3rd, or 4th, the preceding days are part of the
|
|
last week of the preceding year; thus, for Saturday 2nd January
|
|
1999, \fB%G\fP is replaced by 1998 and \fB%V\fP is replaced by 53.
|
|
If December 29th, 30th, or 31st is a Monday, it and any
|
|
following days are part of week 1 of the following year. Thus, for
|
|
Tuesday 30th December 1997, \fB%G\fP is replaced by 1998 and
|
|
\fB%V\fP is replaced by 01.
|
|
.LP
|
|
If a conversion specifier is not one of the above, the behavior is
|
|
undefined.
|
|
.SH RETURN VALUE
|
|
.LP
|
|
If the total number of resulting bytes including the terminating null
|
|
byte is not more than \fImaxsize\fP, \fIstrftime\fP()
|
|
shall return the number of bytes placed into the array pointed to
|
|
by \fIs\fP, not including the terminating null byte. Otherwise,
|
|
0 shall be returned and the contents of the array are unspecified.
|
|
.SH ERRORS
|
|
.LP
|
|
No errors are defined.
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.SS Getting a Localized Date String
|
|
.LP
|
|
The following example first sets the locale to the user's default.
|
|
The locale information will be used in the \fInl_langinfo\fP() and
|
|
\fIstrftime\fP() functions. The \fInl_langinfo\fP() function returns
|
|
the localized date string which specifies how the date is
|
|
laid out. The \fIstrftime\fP() function takes this information and,
|
|
using the \fBtm\fP structure for values, places the date and
|
|
time information into \fIdatestring\fP.
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB#include <time.h>
|
|
#include <locale.h>
|
|
#include <langinfo.h>
|
|
\&...
|
|
struct tm *tm;
|
|
char datestring[256];
|
|
\&...
|
|
setlocale (LC_ALL, "");
|
|
\&...
|
|
strftime (datestring, sizeof(datestring), nl_langinfo (D_T_FMT), tm);
|
|
\&...
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
The range of values for \fB%S\fP is [00,60] rather than [00,59] to
|
|
allow for the occasional leap second.
|
|
.LP
|
|
Some of the conversion specifications are duplicates of others. They
|
|
are included for compatibility with \fInl_cxtime\fP() and
|
|
\fInl_ascxtime\fP(), which were published in Issue 2.
|
|
.LP
|
|
Applications should use \fB%Y\fP (4-digit years) in preference to
|
|
\fB%y\fP (2-digit years).
|
|
.LP
|
|
In the C locale, the \fBE\fP and \fBO\fP modifiers are ignored and
|
|
the replacement strings for the following specifiers
|
|
are:
|
|
.TP 7
|
|
\fB%a\fP
|
|
The first three characters of \fB%A\fP .
|
|
.TP 7
|
|
\fB%A\fP
|
|
One of Sunday, Monday, ..., Saturday.
|
|
.TP 7
|
|
\fB%b\fP
|
|
The first three characters of \fB%B\fP .
|
|
.TP 7
|
|
\fB%B\fP
|
|
One of January, February, ..., December.
|
|
.TP 7
|
|
\fB%c\fP
|
|
Equivalent to \fB%a\fP \fB%b\fP \fB%e\fP \fB%T\fP \fB%Y\fP .
|
|
.TP 7
|
|
\fB%p\fP
|
|
One of AM or PM.
|
|
.TP 7
|
|
\fB%r\fP
|
|
Equivalent to \fB%I\fP : \fB%M\fP : \fB%S\fP \fB%p\fP .
|
|
.TP 7
|
|
\fB%x\fP
|
|
Equivalent to \fB%m\fP / \fB%d\fP / \fB%y\fP .
|
|
.TP 7
|
|
\fB%X\fP
|
|
Equivalent to \fB%T\fP .
|
|
.TP 7
|
|
\fB%Z\fP
|
|
Implementation-defined.
|
|
.sp
|
|
.SH RATIONALE
|
|
.LP
|
|
None.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIasctime\fP() , \fIclock\fP() , \fIctime\fP()
|
|
, \fIdifftime\fP() , \fIgetdate\fP() , \fIgmtime\fP() , \fIlocaltime\fP()
|
|
, \fImktime\fP() ,
|
|
\fIstrptime\fP() , \fItime\fP() , \fItzset\fP() ,
|
|
\fIutime\fP() , Base Definitions volume of IEEE\ Std\ 1003.1-2001,
|
|
Section 7.3.5, LC_TIME, \fI<time.h>\fP
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
event of any discrepancy between this version and the original IEEE and
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
is the referee document. The original Standard can be obtained online at
|
|
http://www.opengroup.org/unix/online.html .
|