[Previous]
[Contents]
[Next]

strftime()

format the time into a string

Synopsis:

#include <time.h>

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

Description:

The strftime() function formats the time in the argument timeptr into the array pointed to by the argument s, according to the format argument.

The format string consists of zero or more directives and ordinary characters. A directive consists of a '%' character followed by a character that determines the substitution that is to take place. All ordinary characters are copied unchanged into the array. No more than maxsize characters are placed in the array. The format directives %D, %h, %n, %r, %t, and %T are from POSIX.

%a
locale's abbreviated weekday name
%A
locale's full weekday name
%b
locale's abbreviated month name
%B
locale's full month name
%c
locale's appropriate date and time representation
%d
day of the month as a decimal number (01-31)
%D
date in the format mm/dd/yy (POSIX)
%h
locale's abbreviated month name (POSIX)
%H
hour (24-hour clock) as a decimal number (00-23)
%I
hour (12-hour clock) as a decimal number (01-12)
%j
day of the year as a decimal number (001-366)
%m
month as a decimal number (01-12)
%M
minute as a decimal number (00-59)
%n
newline character (POSIX)
%p
locale's equivalent of either AM or PM
%r
12-hour clock time (01-12) using the AM/PM notation in the format HH:MM:SS (AM|PM) (POSIX)
%S
second as a decimal number (00-59)
%t
tab character (POSIX)
%T
24-hour clock time in the format HH:MM:SS (POSIX)
%U
week number of the year as a decimal number (00-52), where Sunday is the first day of the week
%w
weekday as a decimal number (0-6), where 0 is Sunday
%W
week number of the year as a decimal number (00-52), where Monday is the first day of the week
%x
locale's appropriate date representation
%X
locale's appropriate time representation
%y
year without century, as a decimal number (00-99)
%Y
year with century, as a decimal number
%Z
time zone name, or no characters if no time zone exists
%%
character %

When the %Z directive is specified, the tzset() function is called.

Returns:

If the number of characters to be placed into the array is less than maxsize, the strftime() function returns the number of characters placed into the array pointed to by s, not including the terminating null character. Otherwise, zero is returned.

When an error has occurred, errno contains a value that indicates the type of error that has been detected.

Examples:

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

void main()
  {
    time_t time_of_day;
    char buffer[ 80 ];

    time_of_day = time( NULL );
    strftime( buffer, 80, "Today is %A %B %d, %Y",
           localtime( &time_of_day ) );
    printf( "%s\n", buffer );
  }

produces the output:

Today is Friday December 25, 1987

Classification:

ANSI, POSIX

Safety:
Interrupt handler No
Signal handler Yes, but modifies errno
Thread Yes

See also:

asctime(), clock(), ctime(), difftime(), errno, gmtime(), localtime(), mktime(), setlocale(), time(), tzset()

The tm structure is described in the section on <time.h> in the Header Files chapter.


[Previous]
[Contents]
[Next]