strftime(3)strftime(3)NAME
strftime, wcsftime - Convert a date and time to a string or wide-char‐
acter 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 stan‐
dards as follows:
strftime(), wcsftime(): XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Points to the array containing the output date and time string. Speci‐
fies 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 writ‐
ten to the output string or wide-character string. See the DESCRIPTION
section for more information. Points to a type tm structure that con‐
tains broken-down time information. 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 speci‐
fication starts with a % (percent sign) character followed by one or
more characters that determine how the conversion specification con‐
structs 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 terminat‐
ing 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-charac‐
ter string and the conversion specifications are replaced by corre‐
sponding sequences of wide characters.
In the obsolete version of the wcsftime() function (which con‐
forms 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 infor‐
mation about using compile-time options and compilation environ‐
ments 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 speci‐
fication that is included in the format parameter starts with a percent
sign (%). In portable applications, the % character is immediately fol‐
lowed 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 spa‐
ces 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 charac‐
ters 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 speci‐
fied 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 run‐
ning. 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, conver‐
sion proceeds as though the conversion-code character were
unmodified. The following list describes the modified and unmod‐
ified 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 exam‐
ple). 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 out‐
put 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 out‐
put. Specifies the day of the month using the locale's alterna‐
tive 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 alterna‐
tive 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 (Sun‐
day = 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 min‐
utes (%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; other‐
wise, 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 speci‐
fied for the current locale. The time is output in the format
specified for the current locale. The year is output as a num‐
ber (without the century) between 00 and 99. Because this con‐
version 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.
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 termi‐
nating null byte in the number of bytes written into the array. Other‐
wise, 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 charac‐
ter, 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)strftime(3)