NAME

strftime, wcsftime − Converts a date and time to a string

LIBRARY

Standard C Library (libc.a)

SYNOPSIS

#include <time.h>

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

#include <wchar.h>

size_t wcsftime(
        wchar_t ∗wcs,
        size_t maxsize,
        const char ∗format,
        const struct tm ∗timptr);

PARAMETERS

sPoints to the array containing the output date and time string. 

maxsizeSpecifies the maximum number of bytes or wide characters to be written to the array pointed to by the s or wcs parameter. 

formatPoints to a sequence of format codes that specify the format of the date and time to be written to the output string. See the DESCRIPTION section for more information. 

timeptrPoints to a type tm structure that contains broken-down time information. 

wcsPoints to the wide-character array containing the output date and time string. 

DESCRIPTION

The strftime() function places characters into the array pointed to by the s parameter as controlled by the string pointed to by the format parameter. The string pointed to by the format parameter is a sequence of characters. Depending on the locale setting, the characters may be single-byte or multibyte characters. 

Local time zone information is used as though the strftime() function called the tzset() function. Time information used in this subroutine is fetched from space containing type tm structure data, which is defined in the time.h include file. The type tm structure must contain the time information used by this subroutine to construct the time and date string. 

The format string consists of characters that represent zero or more conversion specifications and ordinary characters that represent the date and time values and null string terminator.  A conversion specification consists of a % (percent sign) character followed by a character that determines how the conversion specification constructs the formatted string. 

All ordinary characters (including the terminating null character) are copied unchanged into the s array. When copying between objects that overlap, behavior of this function is undefined. No more than the number of bytes specified by the maxsize parameter are written to the array (including the terminating null byte).  Each conversion specification is replaced by the appropriate characters as described in the following list. The appropriate characters are determined by the LC_TIME category of the current locale and by values specified by the type tm structure pointed to by the timeptr parameter. 

The wcsftime() function formats the data in the timptr parameter according to the specification contained in the format parameter and places the resulting wide-character string into the wcs parameter. No more than the number of wide characters specified by the maxsize parameter are written to the array (including the terminating null wide character). 

The wcsftime() function behaves as if the character string generated by the strftime() function is passed to the mbstowcs() function as the character-string parameter and the mbstowcs function places the result in the wcs parameter of the wcsftime() function, up to the limit of wide-character codes specified by the maxsize parameter. Only the wchar.h include file needs to be specified for the wcsftime() function. 

These functions use the local timezone information. 

The format parameter consists of a series of zero or more conversion specifiers and ordinary characters. Each conversion specification starts with a % (percent sign) and ends with a conversion code character specifying the conversion format. The functions replace the conversion specification with the appropriately formatted date or time value.  Ordinary characters are written to the output buffer unchanged. 

The format parameter has the following syntax:

[ordinary-text] [%[[-|0]width] [.precision] format-code [ordinary-text]]... 

ordinary-textText that is copied to the output parameter with no changes. 

widthA decimal digit string that specifies the minimum field width. If the width of the item equals or exceeds the minimum field width, the minimum is ignored. If the width of the item is less than the minimum field width, the function justifies and pads the item. The optional - (minus sign) or 0 (zero digit) control the justification and padding as follows:

NoneItem is right justified and spaces are added to the beginning of the item to fill the minimum width. 

Minus signItem is left justified and spaces are added to the end of the item to fill the minimum width. 

Zero digitItem is right justified and zeros are added to the beginning of the item to fill the minimum width. 

precisionA decimal string that specifies the minimum number of digits to appear for the d, H, I, j, m, M, o, S, U, w, W, y, and Y conversion formats and the maximum number of characters to used from the a, A, b, B, c, D, E, h, n, N, p, r, t, T, x, X, Z, and % conversion formats. 

If no field width or precision is specified for the d, H, I, m, M, S, U, W, or y conversion character, a default precision of .2 is used.  If no field width or precision is specified for the j conversion character, a default precision of 3 is used. 

format-codeA single character that specifies the date and time conversion to perform.  The following list describes the conversion code characters:

aThe short day of the week is output as a string as defined for the current locale (Mon, for example). 

AThe long day of the week is output as defined for the current locale (Monday, for example). 

b (or h)
The short month is output as a string as defined for the current locale (Jan, for example).

BThe long month is output as a string as defined for the current locale (January, for example). 

cThe date and time is output with the default date and time as defined for the current locale. 

CThe century is output as a decimal number in the range 00 to 99. 

dThe day of the month is output as a number between 01 and 31. 

DThe format is fixed to return %m/%d/%y. (For example, 20 Jun 1990 will return 06/20/90.) 

eThe day of the month is output as a number between 1 and 31 in a 2-digit field with leading space fill. 

EcSpecifies the locale’s alternative appropriate date and time representation. 

ECSpecifies the name of the base year (period) in the locale’s alternative representation. 

ExSpecifies the locale’s alternative date representation. 

EXSpecifies the locale’s alternative time representation. 

EySpecifies the offset from %EC (year only) in the locale’s alternative representation. 

EYSpecifies the full alternative year representation. 

HThe hour of the day is output as a number between 00 and 23. 

hSame as b. 

IThe hour of the day is output as a number between 01 and 12. 

jThe Julian day of the year is output as a number between 001 and 366. 

mThe month of the year is output as a number between 01 and 12. 

MThe minute is output as a number between 00 and 59. 

nOnly a newline character is output. 

NThe locale-dependent Emperor/Era name is output. 

oThe locale-dependent Emperor/Era year is output. 

OdSpecifies the day of the month using the locale’s alternative numeric symbols. 

OeSpecifies the day of the month using the locale’s alternative numeric symbols. 

OHSpecifies the hour (24-hour clock) using the locale’s alternative numeric symbols. 

OISpecifies the hour (12-hour clock) using the locale’s alternative numeric symbols. 

OmSpecifies the month using the locale’s alternative numeric symbols. 

OMSpecifies the minutes using the locale’s alternative numeric symbols. 

OSSpecifies the seconds using the locale’s alternative numeric symbols. 

OuSpecifies the weekday as a number in the locale’s alternative representation (Monday=1). 

OUSpecifies the week number of the year (Sunday as the first day of the week) using the locale’s alternative numeric symbols. 

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

OwSpecifies the week day as a number in the locale’s alternative representation (Sunday = 0). 

OWSpecifies the week number of the year (Monday as the first day of the week) using the locale’s alternative numeric symbols. 

OySpecifies the year (offset from %C) in alternative representation. 

pThe AM or PM indicator is output as a string specified for the current locale. 

rThe time in AM/PM notation is output, according to British/US conventions (%I:%M:%S [AM|PM]). 

RThe time in hours (24-hour clock) and minutes (%H:%M). 

SThe second is output as a number between 00 and 61. 

tOnly a tab character is output. 

TThe time is output as %H:%M:%S. 

uSpecifies the weekday as a decimal number [1,7], with 1 representing Monday. 

UThe week number of the year (Sunday as the first day of the week). Output format is a decimal number between 0 and 53. 

VThe week number of the year (Monday as the first day of the week). Output format is a decimal number between 1 and 53.  If the week containing January 1 has four or more days in the new year, then it is considered week 1; otherwise, it is week 53 or the previous year, and the next week is week 1. 

wThe day of the week is output as a number between 0 (Sunday) and 6. 

WThe week number of the year (Monday as the first day of the week). Output format is a decimal number between 0 and 53. 

xThe short date is output in the format specified for the current locale. 

XThe time is output in the format specified for the current locale. 

yThe year is output as a number (without the century) between 00 and 99. 

YThe year is output as a number (with the century) between 0000 and 9999. 

ZThe (standard time or daylight saving time) time zone name is output as a string from the environment variable TZ (CDT, for example).  If no time zone information exists, no characters are output. 

%The % (percent) character is output. 

When a conversion code character is not from the preceding list, the behavior of this function is undefined. 

EXAMPLES

The following example uses strftime() to display the current date:

#include <time.h>
#include <locale.h>
#include <stdio.h>
#define SLENGTH 80
main()
{
    char nowstr[SLENGTH];
    time_t nowbin;
    struct tm ∗nowstruct;
    (void)setlocale(LC_ALL, "");
    if (time(&nowbin) == (time_t) - 1)
        printf("Could not get time of day from time()\n");
    nowstruct = localtime(&nowbin);
    if (strftime(nowstr, SLENGTH, "%A %x", nowstruct) == (size_t) 0)
        printf("Could not get string from strftime()\n");
    printf("Today’s date is %s\n", nowstr);
}

NOTES

The %S seconds field can contain a value up to 61 seconds rather than up to 59 seconds to allow leap seconds that are sometimes added to years to keep clocks in correspondence with the solar year. 

AES Support Level:
Full use (strftime()). 

RETURN VALUES

The strftime() function returns the number of bytes written into the array pointed to by the s parameter when the total number of resulting bytes, including the terminating null character, is not more than the value of the maxsize parameter.  The returned value does not count the terminating null byte in the number of bytes written into the array.  Otherwise, a value of 0 cast to size_t is returned and the contents of the array are undefined. 

The wcsftime() function returns the number of wide characters written into the array pointed to by the wcs parameter when the total number of resulting wide characters, including the terminating null character, is not more than the value of the maxsize parameter.  The returned value does not count the terminating null wide character in the number of wide characters written into the array.  Otherwise, a value of 0 cast to size_t is returned and the contents of the array are undefined. 

RELATED INFORMATION

Functions: ctime(3), mbstowcs(3), setlocale(3), strptime(3).