function

<ctime>

strftime

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

Format time as string

Copies into ptr the content of format, expanding its format specifiers into the corresponding values that represent the time described in timeptr, with a limit of maxsize characters.

Parameters

ptr

Pointer to the destination array where the resulting C string is copied.

maxsize

Maximum number of characters to be copied to ptr, including the terminating null-character.

format

C string containing any combination of regular characters and special format specifiers. These format specifiers are replaced by the function to the corresponding values to represent the time specified in timeptr. They all begin with a percentage (%) sign, and are:

specifier	Replaced by	Example
%a	Abbreviated weekday name *	Thu
%a	Full weekday name *	Thursday
%b	Abbreviated month name *	Aug
%b	Full month name *	August
%c	Date and time representation *	Thu Aug 23 14:55:02 2001
%c	Year divided by 100 and truncated to integer (00-99)	20
%d	Day of the month, zero-padded (01-31)	23
%d	Short MM/DD/YY date, equivalent to %m/%d/%y	08/23/01
%e	Day of the month, space-padded ( 1-31)	23
%F	Short YYYY-MM-DD date, equivalent to %Y-%m-%d	2001-08-23
%g	Week-based year, last two digits (00-99)	01
%g	Week-based year	2001
%h	Abbreviated month name * (same as %b)	Aug
%h	Hour in 24h format (00-23)	14
%I	Hour in 12h format (01-12)	02
%j	Day of the year (001-366)	235
%m	Month as a decimal number (01-12)	08
%m	Minute (00-59)	55
%n	New-line character ('\n')
%p	AM or PM designation	PM
%r	12-hour clock time *	02:55:02 pm
%r	24-hour HH:MM time, equivalent to %H:%M	14:55
%S	Second (00-61)	02
%t	Horizontal-tab character ('\t')
%t	ISO 8601 time format (HH:MM:SS), equivalent to %H:%M:%S	14:55:02
%u	ISO 8601 weekday as number with Monday as 1 (1-7)	4
%u	Week number with the first Sunday as the first day of week one (00-53)	33
%V	ISO 8601 week number (01-53)	34
%w	Weekday as a decimal number with Sunday as 0 (0-6)	4
%w	Week number with the first Monday as the first day of week one (00-53)	34
%x	Date representation *	08/23/01
%x	Time representation *	14:55:02
%y	Year, last two digits (00-99)	01
%y	Year	2001
%z	ISO 8601 offset from UTC in timezone (1 minute=1, 1 hour=100) If timezone cannot be determined, no characters	+100
%z	Timezone name or abbreviation * If timezone cannot be determined, no characters	CDT
%%	A % sign	%

* The specifiers marked with an asterisk (*) are locale-dependent.
Note: Yellow rows indicate specifiers and sub-specifiers introduced by C99. Since C99, two locale-specific modifiers can also be inserted between the percentage sign (%) and the specifier proper to request an alternative format, where applicable:

Modifier	Meaning	Applies to
E	Uses the locale's alternative representation	%Ec %EC %Ex %EX %Ey %EY
O	Uses the locale's alternative numeric symbols	%Od %Oe %OH %OI %Om %OM %OS %Ou %OU %OV %Ow %OW %Oy

timeptr

Pointer to atm structure that contains a calendar time broken down into its components (seestruct tm).

Return Value

If the length of the resulting C string, including the terminating null-character, doesn't exceed maxsize, the function returns the total number of characters copied to ptr (not including the terminating null-character).
Otherwise, it returns zero, and the contents of the array pointed by ptr are indeterminate.

Compatibility

Particular library implementations may support additional specifiers or combinations.
Those listed here are supported by the latest C and C++ standards (both published in 2011), but those in yellow were introduced in C99 (only required for C++ implementations since C++11), and may not be supported by libraries that comply with older standards.

Example

1<br />2<br />3<br />4<br />5<br />6<br />7<br />8<br />9<br />10<br />11<br />12<br />13<br />14<br />15<br />16<br />17<br />18<br />

<cite>/* strftime example */</cite>
<dfn>#include <stdio.h>      </dfn><cite>/* puts */</cite><dfn></dfn>
<dfn>#include <time.h>       </dfn><cite>/* time_t, struct tm, time, localtime, strftime */</cite><dfn></dfn>

<var>int</var> main ()
{
  time_t rawtime;
  <var>struct</var> tm * timeinfo;
  <var>char</var> buffer [80];

  time (&rawtime);
  timeinfo = localtime (&rawtime);

  strftime (buffer,80,<kbd>"Now it's %I:%M%p."</kbd>,timeinfo);
  puts (buffer);

  <var>return</var> 0;
}

Example output:

<samp>
Now it's 03:21PM.
</samp>