strftime, wcsftime - Convert a date and time to a string
or wide-character string
#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 );
Standard C Library (libc)
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.
Points to the array containing the output date and time
string. Specifies the maximum number of bytes or wide
characters to be written to the array pointed to by the s
or wcs parameter. 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. Points to a
type tm structure that contains broken-down time information.
Points to the wide-character array containing the
output date and time string.
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:
Text that is copied to the output parameter with no
changes. [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: Item is right justified
and spaces are added to the beginning of the item to fill
the minimum width. Item is left justified and spaces are
added to the end of the item to fill the minimum width.
Item is right justified and zeros are added to the beginning
of the item to fill the minimum width. [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 is used.
If no field width or precision is specified for the
j conversion character, a default precision of 3 is
used. 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: The short
day of the week is output as a string as defined
for the current locale (Mon, for example). The
long day of the week is output as defined for the
current locale (Monday, for example). The short
month is output as a string as defined for the current
locale (Jan, for example). The long month is
output as a string as defined for the current
locale (January, for example). The date and time
is output with the default date and time as defined
for the current locale. The century is output as a
decimal number in the range 00 to 99. The day of
the month is output as a number between 01 and 31.
The format is fixed to return %m/%d/%y. (For example,
20 Jun 1990 will return 06/20/90.) The day of
the month is output as a number between 1 and 31 in
a 2-digit field with leading space fill. Specifies
the locale's alternative appropriate date and time
representation. Specifies the name of the base
year (period) in the locale's alternative representation.
Specifies the locale's alternative date
representation. Specifies the locale's alternative
time representation. Specifies the offset from %EC
(year only) in the locale's alternative representation.
Specifies the full alternative year representation.
The hour of the day is output as a number
between 00 and 23. Same as b. The hour of the
day is output as a number between 01 and 12. The
Julian day of the year is output as a number
between 001 and 366. The month of the year is output
as a number between 01 and 12. The minute is
output as a number between 00 and 59. Only a newline
character is output. The locale-dependent
Emperor/Era name is output. The locale-dependent
Emperor/Era year is output. Specifies the day of
the month using the locale's alternative numeric
symbols. Specifies the day of the month using the
locale's alternative numeric symbols. Specifies
the hour (24-hour clock) using the locale's alternative
numeric symbols. Specifies the hour
(12-hour clock) using the locale's alternative
numeric symbols. Specifies the month using the
locale's alternative numeric symbols. Specifies
the minutes using the locale's alternative numeric
symbols. Specifies the seconds using the locale's
alternative numeric symbols. Specifies the weekday
as a number in the locale's alternative representation
(Monday=1). Specifies the week number of the
year (Sunday as the first day of the week) using
the locale's alternative numeric symbols. 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.
Specifies the week day as a number in the locale's
alternative representation (Sunday = 0). Specifies
the week number of the year (Monday as the first
day of the week) using the locale's alternative
numeric symbols. Specifies the year (offset from
%C) by using the locale's alternative numeric symbols.
The AM or PM indicator is output as a string
specified for the current locale. The time in
AM/PM notation is output, according to British/US
conventions (%I:%M:%S [AM|PM]). The time in hours
(24-hour clock) and minutes (%H:%M). The second is
output as a number between 00 and 61. Only a tab
character is output. The time is output as
%H:%M:%S. Specifies the weekday as a decimal number
[1,7], with 1 representing Monday. The week
number of the year (Sunday as the first day of the
week). Output format is a decimal number between 0
and 53. 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. The day of the week is output as a number
between 0 (Sunday) and 6. The week number of
the year (Monday as the first day of the week).
Output format is a decimal number between 0 and 53.
The short date is output in the format specified
for the current locale. The time is output in the
format specified for the current locale. 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. The year is output as
a number (with the century) between 0000 and 9999.
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.
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.
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.
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);
}
Functions: ctime(3), mbstowcs(3), setlocale(3), strptime(3)
Standards: standards(5)
strftime(3)
[ Back ] |
