NAME

strftime - convert date and time to a string

 SYNOPSIS

#include <time.h>

size_t strftime(char *s, size_t maxsize, const char *format,
    const struct tm *timptr);

 DESCRIPTION

The strftime() function places bytes into the array pointed to by s as controlled by the string pointed to by format. The format string consists of zero or more conversion specifications and ordinary characters. A conversion specification consists of a % character and a terminating conversion character that determines the conversion specification's behaviour. All ordinary characters (including the terminating null byte) are copied unchanged into the array. If copying takes place between objects that overlap, the behaviour is undefined. No more than maxsize bytes are placed into the array. Each conversion specification is replaced by appropriate characters as described in the following list. The appropriate characters are determined by the program's locale and by the values contained in the structure pointed to by timptr.

Local timezone information is used as though strftime() called tzset().

%a

is replaced by the locale's abbreviated weekday name.

%A

is replaced by the locale's full weekday name.

%b

is replaced by the locale's abbreviated month name.

%B

is replaced by the locale's full month name.

%c

is replaced by the locale's appropriate date and time representation.

%C

is replaced by the century number (the year divided by 100 and truncated to an integer) as a decimal number [00-99].

%d

is replaced by the day of the month as a decimal number [01,31].

%D

same as %m/%d/%y.

%e

is replaced by the day of the month as a decimal number [1,31]; a single digit is preceded by a space.

%h

same as %b.

%H

is replaced by the hour (24-hour clock) as a decimal number [00,23].

%I

is replaced by the hour (12-hour clock) as a decimal number [01,12].

%j

is replaced by the day of the year as a decimal number [001,366].

%m

is replaced by the month as a decimal number [01,12].

%M

is replaced by the minute as a decimal number [00,59].

%n

is replaced by a newline character.

%p

is replaced by the locale's equivalent of either a.m. or p.m.

%r

is replaced by the time in a.m. and p.m. notation; in the POSIX locale this is equivalent to %I:%M:%S %p.

%R

is replaced by the time in 24 hour notation (%H:%M).

%S

is replaced by the second as a decimal number [00,61].

%t

is replaced by a tab character.

%T

is replaced by the time (%H:%M:%S).

%u

is replaced by the weekday as a decimal number [1,7], with 1 representing Monday.

%U

is replaced by the week number of the year (Sunday as the first day of the week) as a decimal number [00,53].

%V

is replaced by the week number of the year (Monday as the first day of the week) as a decimal number [01,53]. If the week containing 1 January 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

is replaced by the weekday as a decimal number [0,6], with 0 representing Sunday.

%W

is replaced by the week number of the year (Monday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Monday are considered to be in week 0.

%x

is replaced by the locale's appropriate date representation.

%X

is replaced by the locale's appropriate time representation.

%y

is replaced by the year without century as a decimal number [00,99].

%Y

is replaced by the year with century as a decimal number.

%Z

is replaced by the timezone name or abbreviation, or by no bytes if no timezone information exists.

%%

is replaced by %.

If a conversion specification does not correspond to any of the above, the behaviour is undefined.

 Modified Conversion Specifiers

Some conversion specifiers can be modified by the E or O modifier characters to indicate that an alternative format or specification should be used rather than the one normally used by the unmodified conversion specifier. If the alternative format or specification does not exist for the current locale, (see ERA in the XBD specification, Section 5.3.5) the behaviour will be as if the unmodified conversion specification were used.

%Ec

is replaced by the locale's alternative appropriate date and time representation.

%EC

is replaced by the name of the base year (period) in the locale's alternative representation.

%Ex

is replaced by the locale's alternative date representation.

%EX

is replaced by the locale' alternative time representation.

%Ey

is replaced by the offset from %EC (year only) in the locale's alternative representation.

%EY

is replaced by the full alternative year representation.

%Od

is replaced by the day of the month, using the locale's alternative numeric symbols, filled as needed with leading zeros if there is any alternative symbol for zero, otherwise with leading spaces.

%Oe

is replaced by the day of month, using the locale's alternative numeric symbols, filled as needed with leading spaces.

%OH

is replaced by the hour (24-hour clock) using the locale's alternative numeric symbols.

%OI

is replaced by the hour (12-hour clock) using the locale's alternative numeric symbols.

%Om

is replaced by the month using the locale's alternative numeric symbols.

%OM

is replaced by the minutes using the locale's alternative numeric symbols.

%OS

is replaced by the seconds using the locale's alternative numeric symbols.

%Ou

is replaced by the weekday as a number in the locale's alternative representation (Monday=1).

%OU

is replaced by the week number of the year (Sunday as the first day of the week, rules corresponding to %U) using the locale's alternative numeric symbols.

%OV

is replaced by 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

is replaced by the number of the weekday (Sunday=0) using the locale's alternative numeric symbols.

%OW

is replaced by the week number of the year (Monday as the first day of the week) using the locale's alternative numeric symbols.

%Oy

is replaced by the year (offset from %C) using the locale's alternative numeric symbols.

 RETURN VALUE

If the total number of resulting bytes including the terminating null byte is not more than maxsize, strftime() returns the number of bytes placed into the array pointed to by s, not including the terminating null byte. Otherwise, 0 is returned and the contents of the array are indeterminate.

 ERRORS

No errors are defined.

 EXAMPLES

None.

 APPLICATION USAGE

The range of values for %S is [00,61] rather than [00,59] to allow for the occasional leap second and even more infrequent double leap second.

Some of the conversion specifications marked EX are duplicates of others. They are included for compatibility with nl_cxtime() and nl_ascxtime(), which were published in Issue 2.

Applications should use %Y (4-digit years) in preference to %y (2-digit years).

 FUTURE DIRECTIONS

None.

 SEE ALSO

asctime(), clock(), ctime(), difftime(), gmtime(), localtime(), mktime(), strptime(), time(), utime(), <time.h>.