strftime Function

Formats the time structure to a string based on the format parameter.

Attention: This function is not implemented by MPLAB XC8 C compilers.

Include

<time.h>

Prototype

size_t strftime(char *s, size_t n, const char *format, const struct tm *tptr);

Arguments

s
output string
n
maximum length of string
format
format-control string
tptr
pointer to tm data structure

Return Value

Returns the number of characters placed in the array, s, if the total, including the terminating null, is not greater than n. Otherwise, the function returns 0 and the contents of array s are indeterminate.

Remarks

The function places no more than maxsize characters into the array pointed to by s as controlled by the format string, which consists of zero or more conversion specifiers and ordinary characters. A conversion specifier consists of a % character, possibly followed by an E or O modifier character, followed by a character that determines the behavior of the conversion specifier. All ordinary characters (including the terminating null character) are copied unchanged into the array. If copying takes place between objects that overlap, the behavior is undefined.

Each conversion specifier is replaced by appropriate characters, which are determined using the LC_TIME category of the current locale and by the values of zero or more members of the broken-down time structure pointed to by timeptr, as indicated in the description. In the "C" locale, the E and O modifiers are ignored and some specifiers are replaced by different strings, which are indicated in square brackets. The %g, %G, and %V specifiers give values according to the ISO 8601 week-based year. If any of the specified values are outside the normal range, the characters stored are unspecified.

Specifier Replacement
%a abbreviated weekday name, derived from tm_wday ["C" locale: the first three characters of %A]
%A full weekday name, derived from tm_wday ["C" locale: one of Sunday, Monday, ... , Saturday]
%b abbreviated month name, derived from tm_mon ["C" locale: the first three characters of %B]
%B full month name, derived from tm_mon ["C" locale: one of January, February, ... , December. %c equivalent to %a %b %e %T %Y]
%c appropriate date and time representation [C locale: equivalent to %a %b %e %T %Y]
%C year, derived from tm_year, divided by 100 and truncated to an integer, as a decimal number (00−99)
%d day of the month as a decimal number (01-31), derived from tm_mday
%D equivalent to %m/%d/%y, derived from tm_mon, tm_mday, and tm_year
%e day of the month, derived from tm_mday, as a decimal number (1−31); a single digit is preceded by a space
%F equivalent to %Y−%m−%d, derived from tm_year, tm_mon, and tm_mday
%g last 2 digits of the week-based year, derived from tm_year, tm_wday, and tm_yday, as a decimal number (00−99)
%G week-based year, derived from tm_year, tm_wday, and tm_yday, as a decimal number (e.g., 1997)
%H equivalent to %b, derived from tm_mon
%H hour (24-hour clock), derived from tm_hour, as a decimal number (00−23)
%I hour (12-hour clock), derived from tm_hour, as a decimal number (01−12)
%j day of the year, derived from tm_yday, as a decimal number (001−366)
%m month, derived from tm_mon, as a decimal number (01−12)
%M minute, derived from tm_min, as a decimal number (00-59)
%n new-line character
%p AM/PM designator, derived from tm_hour ["C" locale" one of AM or PM]
%r 12-hour clock time, derived from tm_hour, tm_min, and tm_sec ["C" locale: equivalent to %I:%M:%S %p]
%R equivalent to %H:%M, derived from tm_hour and tm_min
%S second, derived from tm_sec, as a decimal number (00-60)
%t horizontal-tab character
%T equivalent to %H:%M:%S, derived from tm_hour, tm_min, and tm_sec ["C" locale: equivalent to %T]
%u ISO 8601 weekday, derived from tm_wday, as a decimal number (1−7), with Monday being 1.
%U week number of the year, derived from tm_year, tm_wday, tm_yday, where Sunday is the first day of week 1 (00-53)
%V ISO 8601 week number, derived from tm_year, tm_wday, tm_yday, as a decimal number (01−53)
%w weekday, derived from tm_wday, as a decimal number (0−6), where Sunday is 0
%W week number of the year (the first Monday as the first day of week 1), derived from tm_year, tm_wday, tm_yday, as a decimal number (00−53)
%x appropriate date representation ["C" locale: equivalent to %m/%d/%y]
%X appropriate time representation[ C locale: equivalent to %T]
%y last 2 digits of the year, derived from tm_year, as a decimal number (00−99)
%Y year, derived from tm_year, as a decimal number (e.g., 1997)
%z offset from UTC in ISO 8601 format, derived from tm_isdst, where −0430 implies 4 hours 30 minutes behind UTC, west of Greenwich; or no characters if no time zone is determinable
%Z time zone name or abbreviation, derived from tm_isdst, or no characters if no time zone is determinable
%% percent character, %
Some of the above specified can be modified using the E or O modifier characters to indicate an alternative format or specification. In the "C" locale, these modifiers are ignored. If the alternative format or specification does not exist for the current locale, the modifier is ignored.
Table 1. Modifiers used with specifiers
Modified specifier Replacement
%Ec locale’s alternative date and time representation
%EC name of the base year (period) in the locale’s alternative representation
%Ex locale’s alternative date representation
%EX locale’s alternative time representation
%Ey offset from %EC (year only) in the locale’s alternative representation
%EY locale’s full alternative year representation
%Od day of the month, using the locale’s alternative numeric symbols (filled as needed with leading zeros, or with leading spaces if there is no alternative symbol for zero)
%Oe day of the month, using the locale’s alternative numeric symbols (filled as needed with leading spaces)
%OH hour (24-hour clock), using the locale’s alternative numeric symbol
%OI hour (12-hour clock), using the locale’s alternative numeric symbols
%Om month, using the locale’s alternative numeric symbols
%OM minutes, using the locale’s alternative numeric symbol
%OS seconds, using the locale’s alternative numeric symbols
%Ou ISO 8601 weekday as a number in the locale’s alternative representation, where Monday is 1
%OU week number, using the locale’s alternative numeric symbols
%OV ISO 8601 week number, using the locale’s alternative numeric symbols
%Ow weekday as a number, using the locale’s alternative numeric symbols
%OW week number of the year, using the locale’s alternative numeric symbols
%Oy last 2 digits of the year, using the locale’s alternative numeric symbols

Example

See the notes at the beginning of this chapter or section for information on using printf() or scanf() (and other functions reading and writing the stdin or stdout streams) in the example code.

#include <time.h>
#include <stdio.h>

int main(void)
{
  time_t timer, whattime;
  struct tm *newtime;
  char buf[128];
  timer = 1066668182; /* Mon Oct 20 16:43:02 2003 */
  /* localtime allocates space for structure */
  newtime = localtime(&timer);
  strftime(buf, 128, "It was a %A, %d days into the "
           "month of %B in the year %Y.\n", newtime);
  printf(buf);
  strftime(buf, 128, "It was %W weeks into the year "
           "or %j days into the year.\n", newtime);
  printf(buf);
}

Example Output

It was a Monday, 20 days into the month of October in the year 2003.
It was 42 weeks into the year or 293 days into the year.