271 lines
13 KiB
Plaintext
271 lines
13 KiB
Plaintext
NAME
|
|
strftime - convert date and time to a string
|
|
|
|
SYNOPSIS
|
|
#include <time.h>
|
|
|
|
size_t strftime(char *restrict s, size_t maxsize,
|
|
const char *restrict format, const struct tm *restrict
|
|
timeptr);
|
|
|
|
DESCRIPTION
|
|
The strftime() function shall place bytes into the array pointed to by
|
|
s as controlled by the string pointed to by format. The format is a
|
|
character string, beginning and ending in its initial shift state, if
|
|
any. The format string consists of zero or more conversion specifica-
|
|
tions and ordinary characters. A conversion specification consists of
|
|
a â%â character, possibly followed by an E or O modifier, and a termi-
|
|
nating conversion specifier character that determines the conversion
|
|
specificationâs behavior. All ordinary characters (including the ter-
|
|
minating null byte) are copied unchanged into the array. If copying
|
|
takes place between objects that overlap, the behavior is undefined.
|
|
No more than maxsize 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
|
|
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 timeptr,
|
|
as specified in brackets in the description. If any of the specified
|
|
values are outside the normal range, the characters stored are unspec-
|
|
ified.
|
|
|
|
Local timezone information is used as though strftime() called
|
|
tzset().
|
|
|
|
The following conversion specifications are supported:
|
|
|
|
%a Replaced by the localeâs abbreviated weekday name. [ tm_wday]
|
|
|
|
%A Replaced by the localeâs full weekday name. [ tm_wday]
|
|
|
|
%b Replaced by the localeâs abbreviated month name. [ tm_mon]
|
|
|
|
%B Replaced by the localeâs full month name. [ tm_mon]
|
|
|
|
%c Replaced by the localeâs appropriate date and time representa-
|
|
tion. (See the Base Definitions volume of
|
|
IEEE Std 1003.1-2001, <time.h>.)
|
|
|
|
%C Replaced by the year divided by 100 and truncated to an inte-
|
|
ger, as a decimal number [00,99]. [ tm_year]
|
|
|
|
%d Replaced by the day of the month as a decimal number [01,31]. [
|
|
tm_mday]
|
|
|
|
%D Equivalent to %m / %d / %y . [ tm_mon, tm_mday, tm_year]
|
|
|
|
%e Replaced by the day of the month as a decimal number [1,31]; a
|
|
single digit is preceded by a space. [ tm_mday]
|
|
|
|
%F Equivalent to %Y - %m - %d (the ISO 8601:2000 standard date
|
|
format). [ tm_year, tm_mon, tm_mday]
|
|
|
|
%g Replaced by the last 2 digits of the week-based year (see
|
|
below) as a decimal number [00,99]. [ tm_year, tm_wday,
|
|
tm_yday]
|
|
|
|
%G Replaced by the week-based year (see below) as a decimal number
|
|
(for example, 1977). [ tm_year, tm_wday, tm_yday]
|
|
|
|
%h Equivalent to %b . [ tm_mon]
|
|
|
|
%H Replaced by the hour (24-hour clock) as a decimal number
|
|
[00,23]. [ tm_hour]
|
|
|
|
%I Replaced by the hour (12-hour clock) as a decimal number
|
|
[01,12]. [ tm_hour]
|
|
|
|
%j Replaced by the day of the year as a decimal number [001,366].
|
|
[ tm_yday]
|
|
|
|
%m Replaced by the month as a decimal number [01,12]. [ tm_mon]
|
|
|
|
%M Replaced by the minute as a decimal number [00,59]. [ tm_min]
|
|
|
|
%n Replaced by a <newline>.
|
|
|
|
%p Replaced by the localeâs equivalent of either a.m. or p.m. [
|
|
tm_hour]
|
|
|
|
%r Replaced by the time in a.m. and p.m. notation; in the POSIX
|
|
locale this shall be equivalent to %I : %M : %S %p . [
|
|
tm_hour, tm_min, tm_sec]
|
|
|
|
%R Replaced by the time in 24-hour notation ( %H : %M ). [
|
|
tm_hour, tm_min]
|
|
|
|
%S Replaced by the second as a decimal number [00,60]. [ tm_sec]
|
|
|
|
%t Replaced by a <tab>.
|
|
|
|
%T Replaced by the time ( %H : %M : %S ). [ tm_hour, tm_min,
|
|
tm_sec]
|
|
|
|
%u Replaced by the weekday as a decimal number [1,7], with 1 rep-
|
|
resenting Monday. [ tm_wday]
|
|
|
|
%U 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. [ tm_year,
|
|
tm_wday, tm_yday]
|
|
|
|
%V 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 con-
|
|
taining 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. [
|
|
tm_year, tm_wday, tm_yday]
|
|
|
|
%w Replaced by the weekday as a decimal number [0,6], with 0 rep-
|
|
resenting Sunday. [ tm_wday]
|
|
|
|
%W 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. [ tm_year,
|
|
tm_wday, tm_yday]
|
|
|
|
%x Replaced by the localeâs appropriate date representation. (See
|
|
the Base Definitions volume of IEEE Std 1003.1-2001, <time.h>.)
|
|
|
|
%X Replaced by the localeâs appropriate time representation. (See
|
|
the Base Definitions volume of IEEE Std 1003.1-2001, <time.h>.)
|
|
|
|
%y Replaced by the last two digits of the year as a decimal number
|
|
[00,99]. [ tm_year]
|
|
|
|
%Y Replaced by the year as a decimal number (for example, 1997). [
|
|
tm_year]
|
|
|
|
%z Replaced by the offset from UTC in the ISO 8601:2000 standard
|
|
format ( +hhmm or -hhmm ), or by no characters if no timezone
|
|
is determinable. For example, "-0430" means 4 hours 30 minutes
|
|
behind UTC (west of Greenwich). If tm_isdst is zero, the
|
|
standard time offset is used. If tm_isdst is greater than zero,
|
|
the daylight savings time offset is used. If tm_isdst is nega-
|
|
tive, no characters are returned. [ tm_isdst]
|
|
|
|
%Z Replaced by the timezone name or abbreviation, or by no bytes
|
|
if no timezone information exists. [ tm_isdst]
|
|
|
|
%% Replaced by % .
|
|
|
|
If a conversion specification does not correspond to any of the above,
|
|
the behavior is undefined.
|
|
|
|
If a struct tm broken-down time structure is created by localtime() or
|
|
localtime_r(), or modified by mktime(), and the value of TZ is subse-
|
|
quently modified, the results of the %Z and %z strftime() conversion
|
|
specifiers are undefined, when strftime() is called with such a bro-
|
|
ken-down time structure.
|
|
|
|
If a struct tm broken-down time structure is created or modified by
|
|
gmtime() or gmtime_r(), it is unspecified whether the result of the %Z
|
|
and %z conversion specifiers shall refer to UTC or the current local
|
|
timezone, when strftime() is called with such a broken-down time
|
|
structure.
|
|
|
|
Modified Conversion Specifiers
|
|
Some conversion specifiers can be modified by the E or O 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 vol-
|
|
ume of IEEE Std 1003.1-2001, Section 7.3.5, LC_TIME), the behavior
|
|
shall be as if the unmodified conversion specification were used.
|
|
|
|
%Ec Replaced by the localeâs alternative appropriate date and time
|
|
representation.
|
|
|
|
%EC Replaced by the name of the base year (period) in the localeâs
|
|
alternative representation.
|
|
|
|
%Ex Replaced by the localeâs alternative date representation.
|
|
|
|
%EX Replaced by the localeâs alternative time representation.
|
|
|
|
%Ey Replaced by the offset from %EC (year only) in the localeâs
|
|
alternative representation.
|
|
|
|
%EY Replaced by the full alternative year representation.
|
|
|
|
%Od Replaced by the day of the month, using the localeâs alterna-
|
|
tive numeric symbols, filled as needed with leading zeros if
|
|
there is any alternative symbol for zero; otherwise, with lead-
|
|
ing spaces.
|
|
|
|
%Oe Replaced by the day of the month, using the localeâs alterna-
|
|
tive numeric symbols, filled as needed with leading spaces.
|
|
|
|
%OH Replaced by the hour (24-hour clock) using the localeâs alter-
|
|
native numeric symbols.
|
|
|
|
%OI Replaced by the hour (12-hour clock) using the localeâs alter-
|
|
native numeric symbols.
|
|
|
|
%Om Replaced by the month using the localeâs alternative numeric
|
|
symbols.
|
|
|
|
%OM Replaced by the minutes using the localeâs alternative numeric
|
|
symbols.
|
|
|
|
%OS Replaced by the seconds using the localeâs alternative numeric
|
|
symbols.
|
|
|
|
%Ou Replaced by the weekday as a number in the localeâs alternative
|
|
representation (Monday=1).
|
|
|
|
%OU Replaced by the week number of the year (Sunday as the first
|
|
day of the week, rules corresponding to %U ) using the localeâs
|
|
alternative numeric symbols.
|
|
|
|
%OV Replaced by the week number of the year (Monday as the first
|
|
day of the week, rules corresponding to %V ) using the localeâs
|
|
alternative numeric symbols.
|
|
|
|
%Ow Replaced by the number of the weekday (Sunday=0) using the
|
|
localeâs alternative numeric symbols.
|
|
|
|
%OW Replaced by the week number of the year (Monday as the first
|
|
day of the week) using the localeâs alternative numeric sym-
|
|
bols.
|
|
|
|
%Oy Replaced by the year (offset from %C ) using the localeâs
|
|
alternative numeric symbols.
|
|
|
|
%g , %G , and %V 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,
|
|
%G is replaced by 1998 and %V 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, %G is
|
|
replaced by 1998 and %V is replaced by 01.
|
|
|
|
If a conversion specifier is not one of the above, the behavior is
|
|
undefined.
|
|
|
|
RETURN VALUE
|
|
If the total number of resulting bytes including the terminating null
|
|
byte is not more than maxsize, strftime() shall return the number of
|
|
bytes placed into the array pointed to by s, not including the termi-
|
|
nating null byte. Otherwise, 0 shall be returned and the contents of
|
|
the array are unspecified.
|
|
|
|
ERRORS
|
|
No errors are defined.
|
|
|
|
COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technol-
|
|
ogy -- 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 .
|
|
|