strftime()

Format a time into a string

Synopsis:

#include <time.h>

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

Arguments:

s

A pointer to a buffer where the function can store the formatted time.

maxsize

The maximum size of the buffer.

format

The format that you want to use for the time; see “Formats,” below.

timeptr

A pointer to a tm structure that contains the time that you want to format.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

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.

Formats

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's to take place. All ordinary characters are copied unchanged into the array. No more than maxsize characters are placed in the array.

Local timezone information is used as if from a call to tzset().

%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.

%e

Day of the month as a decimal number (1-31); single digits are preceded by a space.

%F

The ISO standard date format; equivalent to %Y-%m-%d.

%g

The last two digits of the week-based year as a decimal number (00-99).

%G

The week-based year as a decimal number (e.g. 1998).

%h

Locale's abbreviated month name.

%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.

%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).

%R

24-hour notation; %H:%M.

%S

Second as a decimal number (00-59).

%t

Tab character.

%T

24-hour clock time in the format HH:MM:SS.

%u

Weekday as a decimal number (1-7), where Monday is 1.

%U

Week number of the year as a decimal number (00-52), where Sunday is the first day of the week.

%V

Week number of the year as a decimal number (01-53), where Monday is the first day of the week. The week containing January 1 is in the new year if four or more days are in the new year, otherwise it is the last week of the previous year.

%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

Offset from UTC -0430 (4 hrs, 30 minutes behind UTC, west of Greenwich), or no characters if time zone isn't specified.

%Z

Time zone name, or no characters if time zone isn't specified.

%%

Character %.

Some of the above conversion specifiers can be modified with the prefix E or O. If alternative formats don't exist for the locale, they behave as if the unmodified conversion specifiers were called:

%Ec

Alternative date and time representation.

%EC

Alternative name of the the base year (period).

%Ex

Alternative date representation.

%EX

Alternative time representation.

%Ey

Offset from %EC of the alternative year (only) representation.

%EY

Alternative year representation.

%Od

Day of the month using alternative numeric symbols. Leading zeros are added if an alternative symbol for zero exists, otherwise leading spaces are used.

%Oe

Day of the month using alternative numeric symbols. Leading spaces are used.

%OH

24-hour clock using alternative numeric symbols.

%OI

12-hour clock using alternative numeric symbols.

%Om

Month using alternative numeric symbols.

%OM

Minutes using alternative numeric symbols.

%OS

Seconds using alternative numeric symbols.

%Ou

Alternative week day number representation (Monday=1).

%OU

Alternative week day number representation (Rules correspond with %U).

%OV

Alternative week number representation. (Rules correspond with %V).

%Ow

Weekday as a number using alternative numeric symbols (Sunday=0).

%OW

Week number of the year using alternative numeric symbols (Monday is the first day of the week).

%Oy

Year offset from %C using alternative numeric symbols.

Returns:

The number of characters placed into the array, not including the terminating null character, or 0 if the number of characters exceeds maxsize; the string contents are indeterminate.

If an error occurs, errno is set.

Examples:

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

int main( void )
  {
    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 );

    return EXIT_SUCCESS;
  }

This produces the output:

Today is Thursday February 25, 1999

Classification:

ANSI, POSIX 1003.1

See also:

asctime(), asctime_r(), ctime(), ctime_r(), sprintf(), tm, tzset(), wcsftime()