strftime -- Convert to Formatted Time

Format

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

Language Level: ANSI, XPG4, POSIX
strftime converts the time and date specification in the timeptr structure into a character string. It then stores the null-terminated string in the array pointed to by dest according to the format string pointed to by format. maxsize specifies the maximum number of characters that can be copied into the array.

The format string is a multibyte character string containing:

If data has the form of a conversion specifier, but is not one of the accepted specifiers, the characters following the % are copied to the output.

The characters that are converted are determined by the LC_TIME category of the current locale and by the values in the time structure pointed to by timeptr. The time structure pointed to by timeptr is usually obtained by calling the gmtime or localtime function.

When objects to be copied overlap, the behavior is undefined.

strftime obtains time zone information from an internal structure. You can set the values in this structure by calling either tzset or setlocale. tzset sets the structure according to the information in the TZ environment variable; setlocale sets it according to the LC_TOD category in the current locale. If you do not set the values by calling these functions, the defaults used are null string for both time zone name and Daylight Savings time zone name, and 0 minutes for the difference between the standard time zone and the universal coordinate time.

Note: Although none of the locales shipped with this product have the LC_TOD category, you can modify the locale to add the category.

The following table lists the strftime conversion specifiers:

Conversion Specifiers Used by strftime:

Specifier Meaning
%a Replace with abbreviated weekday name of locale.
%A Replace with full weekday name of locale.
%b Replace with abbreviated month name of locale.
%B Replace with full month name of locale.
%c Replace with date and time of locale.
%C Replace with locale's century number (year divided by 100 and truncated)
%d Replace with day of the month (01-31).
%D Insert date in mm/dd/yy form, regardless of locale.
%e Insert month of the year as a decimal number (01-12).

Under POSIX, it's a 2-character, right-justified, blank-filled field.

%E[cCxXyY] If the alternate date/time format is not available, the %E descriptors are mapped to their unextended counterparts. For example, %EC is mapped to %C.
%Ec Replace with the locale's alternative date and time representation.
%EC Replace with the name of the base year (period) in the locale's alternate representation.
%Ex Replace with the locale's alternative date representation.
%EX Replace with the locale's alternative time representation.
%Ey Replace with the offset from %EC (year only) in the locale's alternate representation.
%EY Replace with the full alternative year representation.
%h Replace with locale's abbreviated month name. This is the same as %b.
%H Replace with hour (24-hour clock) as a decimal number (00-23).
%I Replace with hour (12-hour clock) as a decimal number (01-12).
%j Replace with day of the year (001-366).
%m Replace with month (01-12).
%M Replace with minute (00-59).
%n Replace with a new line.
%O[deHImMSUwWy] If the alternative date/time format is not available, the %O descriptors are mapped to their unextended counterparts. For example, %Od is mapped to %d.
%Od Replace with the day of month, using the locale's alternative numeric symbols, filled as needed with leading zeroes if there is any alternative symbol for zero; otherwise fill with leading spaces.
%Oe Replace with the day of the month, using the locale's alternative numeric symbols, filled as needed with leading spaces.
%OH Replace with the hour (24-hour clock), using the locale's alternative numeric symbols.
%OI Replace with the hour (12-hour clock), using the locale's alternative numeric symbols.
%Om Replace with the month, using the locale's alternative numeric symbols.
%OM Replace with the minutes, using the locale's alternative numeric symbols.
%OS Replace with the seconds, using the locale's alternative numeric symbols.
%Ou Replace with the weekday as a decimal number (1 to 7), with 1 representing Monday, using the locale's alternative numeric symbols.
%OU Replace with the week number of the year (00-53), where Sunday is the first day of the week, using the locale's alternative numeric symbols.
%OV Replace with week number of the year (01-53), where Monday is the first day of the week, using the locale's alternative numeric symbols.
%Ow Replace with the weekday (Sunday=0), using the locale's alternative numeric symbols.
%OW Replace with the week number of the year (01-53), where Monday is the first day of the week, using the locale's alternative numeric symbols.
%Oy Replace with the year (offset from %C) in the locale's alternative representation, using the locale's alternative numeric symbols.
%p Replace with the locale's equivalent of AM or PM.
%r Replace with a string equivalent to %I:%M:%S %p; or use t_fmt_ampm from LC_TIME, if present.
%R Replace with time in 24 hour notation (%H:%M)
%S Replace with second (00-61).
%t Replace with a tab.
%T Replace with a string equivalent to %H:%M:%S.
%u Replace with the weekday as a decimal number (1 to 7), with 1 representing Monday.
%U Replace with week number of the year (00-53), where Sunday is the first day of the week.
%V Replace with week number of the year (01-53), where Monday is the first day of the week.
%w Replace with weekday (0-6), where Sunday is 0.
%W Replace with week number of the year (00-53), where Monday is the first day of the week.
%x Replace with date representation of locale.
%X Replace with time representation of locale.
%y Replace with year without the century (00-99).
%Y Replace with year including the century.
%Z Replace with name of time zone, or no characters if time zone is not available.
%% Replace with %.

For %Z, the tm_isdst flag in the tm structure passed to strftime specifies whether the time zone is standard or Daylight Savings time.

If data has the form of a directive, but is not one of the above, the characters following the % are copied to the output.

Return Value
If the total number of characters in the resulting string, including the terminating null character, does not exceed maxsize, strftime returns the number of bytes placed into dest, not including the terminating null character. Otherwise, strftime returns 0 and the content of the string is indeterminate.

Example
This example gets the time and date from localtime, calls strftime to format it, and prints the resulting string.

#include <stdio.h>
#include <time.h>
int main(void)
{
   char dest[70];
   int ch;
   time_t temp;
   struct tm *timeptr;
   temp = time(NULL);
   timeptr = localtime(&temp);
   ch = strftime(dest, sizeof(dest)-1, "Today is %A,"" %b %d. \n Time: %I:%M %p"
      , timeptr);
   printf("%d characters placed in string to make: \n \n %s", ch, dest);
   return 0;
   /****************************************************************************
      The output should be similar to:
      41 characters placed in string to make:
       Today is Monday, Sep 16.
       Time: 06:31 pm
   ****************************************************************************/
}


setlocale -- Set Locale
strptime -- Convert to Formatted Date and Time
time -- Determine Current Time
wcsftime -- Convert to Formatted Date and Time
<time.h>