 |
Index for
Section 3 |
|
 |
Alphabetical
listing for S |
|
 |
Bottom of
page |
|
strftime(3)
NAME
strftime, wcsftime - Convert a date and time to a string or wide-character
string
SYNOPSIS
#include <time.h>
size_t strftime(
char *s,
size_t maxsize,
const char *format,
const struct tm *timeptr );
#include <wchar.h>
size_t wcsftime(
wchar_t *wcs,
size_t maxsize,
const wchar_t *format,
const struct tm *timeptr );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry standards
as follows:
strftime(), wcsftime(): XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
s Points to the array containing the output date and time string.
maxsize
Specifies the maximum number of bytes or wide characters to be written
to the array pointed to by the s or wcs parameter.
format
Points to a sequence of characters that specify the format of the date
and time to be written to the output string or wide-character string.
See the DESCRIPTION section for more information.
timeptr
Points to a type tm structure that contains broken-down time
information.
wcs Points to the wide-character array containing the output date and time
string.
DESCRIPTION
The strftime() function places characters into the array pointed to by the
s parameter as controlled by the string pointed to by the format parameter.
Local time zone information is used as though the strftime() function
called the tzset() function. Time information used in this subroutine is
fetched from space containing type tm structure data, which is defined in
the time.h include file. The type tm structure must contain the time
information used by this subroutine to construct the time and date string.
The format string consists of characters that represent zero or more
conversion specifications and ordinary characters that represent the date
and time values and null string terminator. Each conversion specification
starts with a % (percent sign) character followed by one or more characters
that determine how the conversion specification constructs the formatted
string. Any ordinary characters (including the terminating null character)
in the format string are copied unchanged into the s array. When copying
between objects that overlap, function behavior is undefined. No more than
the number of bytes specified by the maxsize parameter are written to the
array (including the terminating null character).
The strftime() function replaces the conversion specification with the
appropriately formatted date or time value. Ordinary characters are written
to the output buffer unchanged.
Each conversion specification is replaced by the appropriate characters as
described later in this section. The appropriate characters are determined
by the LC_TIME category of the current locale and by values specified by
the type tm structure pointed to by the timeptr parameter.
The wcsftime() function is equivalent to the strftime() function, except
that:
· The wcs parameter points to the initial element of an array of wide
characters into which the generated output is to be placed.
· The maxsize parameter indicates the maximum number of wide characters
to be placed in wcs.
· The format parameter is a wide-character string and the conversion
specifications are replaced by corresponding sequences of wide
characters.
In the obsolete version of the wcsftime() function (which conforms to
Issue 4 Revision 2 and earlier versions of the XSH specification), the
format parameter is defined to be const char* rather than const
wchar_t* as currently required by the ISO C standard and XSH Issue 5.
See standards(5) for more information about using compile-time options
and compilation environments to conform to different levels of
industry standards.
· The return value indicates the number of wide characters placed in
wcs.
The format parameter has the following syntax. Each conversion
specification that is included in the format parameter starts with a
percent sign (%). In portable applications, the % character is immediately
followed by format-code.
[ordinary-text]\
[%[[-|0]width][.precision]format-code[ordinary-text]]...
In this syntax:
ordinary-text
Text that is copied to the output parameter with no changes.
width
[Tru64 UNIX] A decimal digit string that specifies the minimum field
width. If the width of the item equals or exceeds the minimum field
width, the minimum is ignored. If the width of the item is less than
the minimum field width, the function justifies and pads the item. The
optional - (minus sign) or 0 (zero digit) control the justification and
padding as follows:
None
Item is right justified and spaces are added to the beginning of the
item to fill the minimum width.
Minus sign
Item is left justified and spaces are added to the end of the item to
fill the minimum width.
Zero digit
Item is right justified and zeros are added to the beginning of the
item to fill the minimum width.
precision
[Tru64 UNIX] A decimal string that specifies the minimum number of
digits to appear for the d, H, I, j, m, M, o, S, U, w, W, y, and Y
conversion formats and the maximum number of characters to used from
the a, A, b, B, c, D, E, h, n, N, p, r, t, T, x, X, Z, and % conversion
formats.
[Tru64 UNIX] If no field width or precision is specified for the d, H,
I, m, M, S, U, W, or y conversion character, a default precision of .2
is used. If no field width or precision is specified for the j
conversion character, a default precision of 3 is used.
format-code
A conversion-code character that specifies the date and time conversion
to perform. Some conversion-code characters can be preceded by an E or
an O modifier. The E modifier indicates that an alternative date and
time representation should be used if one is defined by the locale in
which the application is running. Th O modifier indicates that
alternative numeric symbols should be used if they are defined by the
locale in which the application is running. If the application
specifies a modified conversion-code for format-code and the
application runs in a locale that does not define the alternative
conversion, conversion proceeds as though the conversion-code character
were unmodified. The following list describes the modified and
unmodified conversion-code characters:
a The short day of the week is output as a string as defined for the
current locale (Mon, for example).
A The long day of the week is output as defined for the current locale
(Monday, for example).
b (or h)
The short month is output as a string as defined for the current locale
(Jan, for example).
B The long month is output as a string as defined for the current locale
(January, for example).
c The date and time is output with the default date and time as defined
for the current locale.
C The century is output as a decimal number in the range 00 to 99.
d The day of the month is output as a number between 01 and 31.
D The format is fixed to return %m/%d/%y. (For example, 20 Jun 1990 will
return 06/20/90.)
e The day of the month is output as a number between 1 and 31 in a 2-
digit field with leading space fill.
Ec Specifies the locale's alternative appropriate date and time
representation.
EC Specifies the name of the base year (period) in the locale's
alternative representation.
Ex Specifies the locale's alternative date representation.
EX Specifies the locale's alternative time representation.
Ey Specifies the offset from %EC (year only) in the locale's alternative
representation.
EY Specifies the full alternative year representation.
H The hour of the day is output as a number between 00 and 23.
h Same as b.
I The hour of the day is output as a number between 01 and 12.
j The Julian day of the year is output as a number between 001 and 366.
m The month of the year is output as a number between 01 and 12.
M The minute is output as a number between 00 and 59.
n Only a newline character is output.
N The locale-dependent Emperor/Era name is output.
o The locale-dependent Emperor/Era year is output.
Od Specifies the day of the month using the locale's alternative numeric
symbols.
Oe Specifies the day of the month using the locale's alternative numeric
symbols.
OH Specifies the hour (24-hour clock) using the locale's alternative
numeric symbols.
OI Specifies the hour (12-hour clock) using the locale's alternative
numeric symbols.
Om Specifies the month using the locale's alternative numeric symbols.
OM Specifies the minutes using the locale's alternative numeric symbols.
OS Specifies the seconds using the locale's alternative numeric symbols.
Ou Specifies the weekday as a number in the locale's alternative
representation (Monday=1).
OU Specifies the week number of the year (Sunday as the first day of the
week) using the locale's alternative numeric symbols.
OV Specifies 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 Specifies the week day as a number in the locale's alternative
representation (Sunday = 0).
OW Specifies the week number of the year (Monday as the first day of the
week) using the locale's alternative numeric symbols.
Oy Specifies the year (offset from %C) by using the locale's alternative
numeric symbols.
p The AM or PM indicator is output as a string specified for the current
locale.
r The time in AM/PM notation is output, according to British/US
conventions (%I:%M:%S [AM|PM]).
R The time in hours (24-hour clock) and minutes (%H:%M).
S The second is output as a number between 00 and 61.
t Only a tab character is output.
T The time is output as %H:%M:%S.
u Specifies the weekday as a decimal number [1,7], with 1 representing
Monday.
U The week number of the year (Sunday as the first day of the week).
Output format is a decimal number between 0 and 53.
V The week number of the year (Monday as the first day of the week).
Output format is a decimal number between 1 and 53. If the week
containing January 1 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.
w The day of the week is output as a number between 0 (Sunday) and 6.
W The week number of the year (Monday as the first day of the week).
Output format is a decimal number between 0 and 53.
x The short date is output in the format specified for the current
locale.
X The time is output in the format specified for the current locale.
y The year is output as a number (without the century) between 00 and 99.
Because this conversion code relies on a two-digit representation of
the year, it is not recommended. Use Y instead.
Y The year is output as a number (with the century) between 0000 and
9999.
Z The (standard time or daylight saving time) time zone name or
abbreviation is output as a string from the environment variable TZ
(CDT, for example). If no time zone information exists, no characters
are output.
% The % (percent) character is output.
When a modified or unmodified conversion-code is not from the preceding
list, the behavior of these functions is undefined.
NOTES
The %S seconds field can contain a value up to 61 seconds rather than up to
59 seconds to allow leap seconds that are sometimes added to years to keep
clocks in correspondence with the solar year.
RETURN VALUES
The strftime() function returns the number of bytes written into the array
pointed to by the s parameter when the total number of resulting bytes,
including the terminating null byte, is not more than the value of the
maxsize parameter. The returned value does not count the terminating null
byte in the number of bytes written into the array. Otherwise, a value of 0
cast to size_t is returned and the contents of the array are undefined.
The wcsftime() function returns the number of wide characters written into
the array pointed to by the wcs parameter when the total number of
resulting wide characters, including the terminating null wide character,
is not more than the value of the maxsize parameter. The returned value
does not count the terminating null wide character in the number of wide
characters written into the array. Otherwise, a value of 0 cast to size_t
is returned and the contents of the array are undefined.
EXAMPLES
The following example uses strftime() to display the current date:
#include <time.h>
#include <locale.h>
#include <stdio.h>
#define SLENGTH 80
main()
{
char nowstr[SLENGTH];
time_t nowbin;
const struct tm *nowstruct;
(void)setlocale(LC_ALL, );
if (time(&nowbin) == (time_t) - 1)
printf("Could not get time of day from time()\n");
nowstruct = localtime(&nowbin);
if (strftime(nowstr, SLENGTH, "%A %x", nowstruct) == (size_t) 0)
printf("Could not get string from strftime()\n");
printf("Today's date is %s\n", nowstr);
}
SEE ALSO
Functions: ctime(3), mbstowcs(3), setlocale(3), strptime(3)
Standards: standards(5)
|
Index for
Section 3 |
|
|
Alphabetical
listing for S |
|
 |
Top of
page |
|