Previous Page
Next Page

strftime

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( )


Previous Page
Next Page