Generates a formatted time and date string

#include <time.h>
size_t strftime ( char * restrict s , size_t n ,
                 const char * restrict format ,
                 const struct tm * restrict timeptr  );

The strftime( ) function converts date and time information from a struct tm object addressed by the last pointer argument into a character string, following a format specified by the string addressed by the pointer argument format. The strftime( ) function stores the resulting string in the buffer addressed by the first pointer argument, without exceeding the buffer length specified by the second argument, n. The locations that strftime( ) reads from and writes to using its restricted pointer parameters must not overlap.

Typically, the struct tm object is obtained by calling localtime( ) or gmtime( ). For a description of this structure type, see mktime( ) in this chapter.

The generation of the output string is governed by the format string. In this way, strftime( ) is similar to the functions in the printf( ) family. The format string consists of ordinary characters, which are copied to the output buffer unchanged, and conversion specifications, which direct strftime( ) to convert a data item from the struct tm object and include it in the output string.

Conversion specification syntax

The conversion specifications have the following syntax:

%[modifier]specifier

The modifier, if present, instructs strftime( ) to use an alternative, locale-specific conversion for the specified data item, and is either E, for locale-specific calendars and clocks, or O, for locale-specific numeric symbols. The E modifier can be prefixed to the specifiers c, C, x, X, y, and Y. The O modifier can be prefixed to the specifiers d, e, H, I, m, M, S, u, U, V, w, W, and Y. All of the conversion specifiers are listed, with the struct tm members they refer to, in Table 17-10. The replacement value for the conversion specifiers depend on the LC_TIME category of the current locale, which can be changed by the setlocale( ) function.

Table 17-10. The strftime( ) conversion specifiers

Conversion specifier	Structure member(s)	Output notation
a	tm_wday	The name of the day of the week, abbreviated
A	tm_wday	The name of the day of the week, in full
b or h	tm_mon	The name of the month, abbreviated
B	tm_mon	The name of the month, in full
c	(all)	The date and time
C	tm_year	The year, divided by 100, as a decimal integer (00 to 99)
d	tm_mday	The day of the month, in decimal, with a leading zero on values less than 10 (01 to 31)
D	tm_mon, tm_mday, tm_year	Shorthand for %m/%d/%y
d	tm_mday	The day of the month, in decimal, with a leading space on values less than 10 ( 1 to 31)
F	tm_mon, tm_mday, tm_year	Shorthand for %Y-%m-%d
g	tm_year, tm_wday, tm_yday	The last two digits of the year in the ISO 8601 week-based calendar (00 to 99)[*]
G	tm_year, tm_wday, tm_yday	The four-digit year in the ISO 8601 week-based calendar
H	tm_hour	The hour of the 24-hour clock as a two-digit decimal number (00 to 23)
I	tm_hour	The hour of the 12-hour clock as a two-digit decimal number (01 to 12)
j	tm_yday	The day of the year as a three-digit decimal number (001 to 366)
m	tm_mon	The month as a two-digit decimal number (01 to 12)
M	tm_min	The minutes after the hour as a two-digit decimal number (00 to 59)
n	(none)	A newline character ('\n')
p	tm_hour	The AM or PM indication used with a 12-hour clock
r	tm_hour, tm_min, tm_sec	The time of day on the 12-hour clock
R	tm_hour, tm_min	Shorthand for %H:%M
S	tm_sec	The seconds after the minute as a two-digit decimal number (00 to 60)
t	(none)	A tab character ('\t')
T	tm_hour, tm_min, tm_sec	Shorthand for %H:%M:%S
u	tm_wday	The day of the week as a one-digit decimal number (1 to 7, where 1 is Monday)
U	tm_year, tm_wday, tm_yday	The week of the year as a two-digit decimal number (00 to 53), where week 1 begins on the first Sunday in January
V	tm_year, tm_wday, tm_yday	The week of the year in the ISO 8601 week-based calendar, as a two-digit decimal number (01 to 53), where week 1 begins on the last Monday that falls on or before January 4
w	tm_wday	The day of the week as a one-digit decimal number (0 to 6, where 0 is Sunday)
W	tm_year, tm_wday, tm_yday	The week of the year as a two-digit decimal number (00 to 53), where week 1 begins on the first Monday in January
x	(all)	The date
X	(all)	The time
y	tm_year	The last two digits of the year, as a decimal number (00 to 99)
Y	tm_year	The year as a decimal number (example: 2005)
z	tm_isdst	The offset from Greenwich Mean Time if available; otherwise nothing (example: +0200 for two hours and no minutes east of GMT)
Z	tm_isdst	The name or abbreviation of the time zone if available; otherwise nothing
%	(none)	A percent sign (%)

^[*] In this calendar, the week begins on Monday, and the first week of the year is the week that contains January 4. Up to the first three days of January may belong to week 53 of the old year, or up to the last three days of December may belong to week 1 of the new year.

The strftime( ) function returns the length of the string written to the output buffer, not counting the terminating null character. If the output is longer than the argument n allows, strftime( ) returns 0, and the contents of the output buffer are undetermined.

Example

time_t now;
struct tm *localnow;
char hdr_date[999] = "";

time( &now );
localnow = localtime( &now );

if ( strftime( hdr_date, 78, "Date: %a, %d %b %Y %T %z", localnow ) )
  puts( hdr_date );
else
  return -1;

This code prints a date field in RFC 2822 style, such as this one:

Date: Thu, 10 Mar 2005 13:44:18 +0100

See Also

asctime( ), ctime( ), mktime( ), localtime( ), gmtime( ), wcsftime( ), snprintf( ), setlocale( )