strftime() — Convert to formatted time

Standards

Standards / Extensions	C or C++	Dependencies
ISO C POSIX.1 XPG4 XPG4.2 C99 Single UNIX Specification, Version 3	both

Format

#include <time.h>

size_t strftime(char * __restrict__ dest, size_t maxsize,
                const char * __restrict__ format, const struct tm * __restrict__ timeptr);

General description

Places characters into the array pointed to by dest according to the string pointed to by format. The format string is a multibyte character string which contains:

Conversion specification characters
Ordinary multibyte characters, which are copied into an array unchanged.

The characters that are converted are determined by the LC_CTYPE 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.

Table 1. 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 day of the month as a decimal number (`01`–`31`). Under C POSIX only, it's a 2-character, right-justified, blank-filled field.
%E[cCxyY]	If the alternative 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 alternative 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 alternative representation.
%EY	Replace with the full alternative year representation.
%F	Replace with the ISO 8601:2000 standard date format, equivalent to %Y-%m-%d. Values are taken from struct tm members, tm_year, tm_mon, and tm_mday.
%g	Replace with the last two digits of the week-based year as a decimal number (00-99).
%G	Replace with the week-based year as a four digit decimal.
%h	Replace with locale's abbreviated month name. This is the same as %b. %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 newline.
%O[deHImMSUwWy]	If the alternative date/time format is not available, the %E 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 zeros if there is any alternative symbol for zero, otherwise with leading spaces.
%Oe	Replace with the day of the month, using the locale's alternative symbols, filled as needed with leading spaces.
%OH	Replace with the hour (24-hour clock) using the locale's alternative symbols.
%OI	Replace with the hour (12-hour clock) using the locale's alternative 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 number in the locale's alternative representation (Monday=1).
%OU	Replace with 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	Replace with 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	Replace with the weekday (Sunday=0) using the locale's alternative numeric symbols.
%OW	Replace with the week number of the year (Monday as 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 and 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 seconds as a decimal number (00-60).
%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. The first Sunday of January is the first day of week 1; days in the new year before this are in week 0.
%V	Replace with week number of the year (01-53) where Monday is the first day of the week. 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. Both January 4th and the first Thursday of January are always in week 1.
%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 with century.
%z	Replace with the offset from UTC in ISO8601:2000 standard format ( +hhmm or -hhmm ). For example, "-0430" means 4 hours 30 minutes behind UTC (west of Greenwich). If tm_isdst is zero, the standard time offset is used. If tm_isdst is greater than zero, the daylight savings time offset is used. If tm_isdst is negative, or if no timezone can be determined, then no characters are returned.
%Z	Replace with name of time zone, or no characters if time zone is not available.
%%	Replace with %.

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

The behavior is undefined when objects being copied overlap. maxsize specifies the maximum number of characters that can be copied into the array.

If strftime() is called by a non-POSIX application, it obtains appropriate time zone name information from LC_TOD locale category. Time zone name defaults to STD for Standard time name, DST for Daylight Savings time name, or UTC for Coordinated Universal Time (UTC), name, as appropriate, if time zone name information is unspecified in the current LC_TOD locale category.

Note: The strftime() function requires time zone name information to convert the %Z conversion specifier. It is obtained as follows:

The strftime() functions calls the tzset() function to obtain time zone information by parsing the TZ (POSIX) or _TZ (non_POSIX) environment variable or from the current LC_TOD locale category. If the tm structure input to strftime() was produced by calling localtime(), strftime() converts %Z to the Standard or Daylight Savings name characters specified by the TZ environment variable or LC_TOD category (if TZ cannot be found or parsed).
When neither TZ nor _TZ is defined, the current locale is interrogated for time zone information. If neither TZ nor _TZ is defined and LC_TOD time zone information is not present in the current locale, a default value is applied to local time. POSIX programs simply default to Coordinated Universal Time (UTC), while non-POSIX programs establish an offset from UTC based on the setting of the system clock. For more information about customizing a time zone to work with local time, see “Customizing a time zone” in z/OS XL C/C++ Programming Guide.

The tm_isdst flag in the time structure input to strftime() determines whether %Z is replaced by the Standard or Daylight Savings name characters. If Standard or Daylight Savings name characters are not available in the current LC_TOD locale category or from parsing TZ, strftime() uses the characters STD for Standard or DST for Daylight Savings time name.

If the tm structure input to strftime() was produced by the gmtime() function, strftime() replaces %Z by UCTNAME characters specified in the current LC_TOD locale category or by UTC if UCTNAME is not specified.

Returned value

If successful, strftime() returns the number of characters (bytes) placed into the array, not including the terminating NULL character.

If unsuccessful, strftime() returns 0 and the content of the string is indeterminate.

Example

CELEBS42

/* CELEBS42                                      

   This example places characters into the array dest 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);         
}

Output

44 characters placed in string to make:

 Today is Friday, Jun 16.
 Time: 03:07 PM