strftime() — Convert Date/Time to String
Format
#include <time.h>
size_t strftime(char *s, size_t maxsize, const char *format,
const struct tm *timeptr);
Language Level
ANSI
Threadsafe
Yes
Locale Sensitive
The behavior of this function might be affected by the LC_CTYPE, LC_TIME, and LC_TOD categories of the current locale. For more information, see Understanding CCSIDs and Locales.
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 behavior of the conversion.
All ordinary characters (including the terminating null byte, and
multi-byte chars) are copied unchanged into the array. If copying
takes place between objects that overlap, then the behavior is undefined.
No more than maxsize bytes are placed in the array. The appropriate
characters are determined by the values contained in the structure
pointed to by timeptr, and by the values stored in the current
locale.
Each standard conversion specification is replaced by appropriate characters as described in the following table:
Specifier | Meaning |
---|---|
%a | Abbreviated weekday name. |
%A | Full weekday name. |
%b | Abbreviated month name. |
%B | Full month name. |
%c | Date/Time in the format of the locale. |
%C | Century number [00-99], the year divided by 100 and truncated to an integer. |
%d | Day of the month [01-31]. |
%D | Date Format, same as %m/%d/%y. |
%e | Same as %d, except single digit is preceded by a space [1-31]. |
%g | 2 digit year portion of ISO week date [00,99]. |
%F | ISO Date Format, same as %Y-%m-%d. |
%G | 4 digit year portion of ISO week date. Can be negative. |
%h | Same as %b. |
%H | Hour in 24-hour format [00-23]. |
%I | Hour in 12-hour format [01-12]. |
%j | Day of the year [001-366]. |
%m | Month [01-12]. |
%M | Minute [00-59]. |
%n | Newline character. |
%p | AM or PM string. |
%r | Time in AM/PM format of the locale. If not available in the locale time format, defaults to the POSIX time AM/PM format: %I:%M:%S %p. |
%R | 24-hour time format without seconds, same as %H:%M. |
%S | Second [00-61]. The range for seconds allows for a leap second and a double leap second. |
%t | Tab character. |
%T | 24-hour time format with seconds, same as %H:%M:%S. |
%u | Weekday [1,7]. Monday is 1 and Sunday is 7. |
%U | Week number of the year [00-53]. Sunday is the first day of the week. |
%V | ISO week number of the year [01-53]. Monday is the first day of the week. If the week containing January 1st 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 year is week 1 of the new year. |
%w | Weekday [0,6], Sunday is 0. |
%W | Week number of the year [00-53]. Monday is the first day of the week. |
%x | Date in the format of the locale. |
%X | Time in the format of the locale. |
%y | 2 digit year [00,99]. |
%Y | 4-digit year. Can be negative. |
%z | UTC offset. Output is a string with
format +HHMM or -HHMM , where + indicates
east of GMT, - indicates west of GMT, HH indicates the number of hours
from GMT, and MM indicates the number of minutes from GMT. |
%Z | Time zone name. |
%% | % character. |
Modified Conversion Specifiers
Some conversion specifiers can be modified by the E or O modifier characters to indicate that an alternate format or specification should be used rather than the one normally used by the unmodified conversion specifier. If a modified conversion specifier uses a field in the current locale that is unavailable, then the behavior will be as if the unmodified conversion specification were used. For example, if the era string is the empty string "", which means that the string is unavailable, then %EY would act like %Y.
Specifier | Meaning |
---|---|
%Ec | Date/time for current era. |
%EC | Era name. |
%Ex | Date for current era. |
%EX | Time for current era. |
%Ey | Era year. This is the offset from the base year. |
%EY | Year for current era. |
%Od | Day of the month using alternate digits. |
%Oe | Same as %Od. |
%OH | Hour in 24 hour format using alternate digits. |
%OI | Hour in 12 hour format using alternate digits. |
%Om | Month using alternate digits. |
%OM | Minutes using alternate digits. |
%OS | Seconds using alternate digits. |
%Ou | Weekday using alternate digits. Monday is 1 and Sunday is 7. |
%OU | Week number of the year using alternate digits. Sunday is the first day of the week. |
%OV | ISO week number of the year using alternate digits. See %V for explanation of ISO week number. |
%Ow | Weekday using alternate digits. Sunday is 0. |
%OW | Week number of the year using alternate digits. Monday is the first day of the week. |
%Oy | 2-digit year using alternate digits. |
%OZ | If the time zone name exists in the current locale, this is the same as %Z; otherwise, the abbreviated time zone name of the current job is returned. |
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.
If a conversion error occurs, errno
may
be set to ECONVERT.
Example
#include <stdio.h>
#include <time.h>
int main(void)
{
char s[100];
int rc;
time_t temp;
struct tm *timeptr;
temp = time(NULL);
timeptr = localtime(&temp);
rc = strftime(s,sizeof(s),"Today is %A, %b %d.\nTime: %r", timeptr);
printf("%d characters written.\n%s\n",rc,s);
return 0;
}
/*************************************************
The output should be similar to:
46 characters written
Today is Wednesday, Oct 24.
Time: 01:01:15 PM
************************************************************/
Related Information
- asctime() — Convert Time to Character String
- asctime_r() — Convert Time to Character String (Restartable)
- ctime() — Convert Time to Character String
- ctime64() — Convert Time to Character String
- ctime64_r() — Convert Time to Character String (Restartable)
- ctime_r() — Convert Time to Character String (Restartable)
- gmtime() — Convert Time
- gmtime64() — Convert Time
- gmtime64_r() — Convert Time (Restartable)
- gmtime_r() — Convert Time (Restartable)
- localtime() — Convert Time
- localtime64() — Convert Time
- localtime64_r() — Convert Time (Restartable)
- localtime_r() — Convert Time (Restartable)
- setlocale() — Set Locale
- strptime() — Convert String to Date/Time
- time() — Determine Current Time
- time64() — Determine Current Time
- <time.h>