Chapter Contents

Previous

Next
strftime

strftime



Convert Time to String

Portability: ISO/ANSI C conforming, POSIX.1 conforming


SYNOPSIS
DESCRIPTION
RETURN VALUE
CAUTION
EXAMPLE
RELATED FUNCTIONS
SEE ALSO


SYNOPSIS

#include <time.h>

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


DESCRIPTION

strftime converts a time value into a string according to the format specified by format . The string is placed in the array pointed to by s . No more than maxsize characters are placed into the array.

The format is a character sequence consisting of zero or more conversion specifications and regular characters. The conversion specifications are described below; ordinary characters, including the terminating-null character, are copied into the string without being converted.

The conversion specifications for format are as follows. Remember that the behavior of these specifications depend on the current locale. (See Chapter 10, "Localization," in the SAS/C Library Reference, Volume 2 for more information on locales.) The "C" locale values for each of the specifications below are listed in Chapter 2, "Language Definition," in the SAS/C Compiler and Library User's Guide. strftime is affected by time zone information contained in the TZ environment variable, if it is defined.
%a is replaced by the locale's abbreviated weekday name.
%A is replaced by the locale's full weekday name.
%b is replaced by the locale's abbreviated month name.
%B is replaced by the locale's full month name.
%c is replaced by the locale's date and time representation.
%d is replaced by the day of the month as a decimal number from 01 to 31.
%H is replaced by the hour as a decimal number from 00 to 23.
%I is replaced by the hour as a decimal number from 01 to 12.
%j is replaced by the day of the year as a decimal number from 001 to 366.
%m is replaced by the month as a decimal number from 01 to 12.
%M is replaced by the minute as a decimal number from 00 to 59.
%p is replaced by the locale's equivalent of either a.m. or p.m.
%S is replaced by the second as a decimal number from 00 to 59.
%U is replaced by the week number of the year as a decimal number from 00 to 53, counting Sunday as the first day of the week.
%w is replaced by the weekday as a decimal number from 0 to 6, with Sunday as 0.
%W is replaced by the week number of the year as a decimal number from 00 to 53, counting Monday as the first day of the week.
%x is replaced by the locale's date representation.
%X is replaced by the locale's time representation.
%y is replaced by the year without century as a decimal number from 00 to 99.
%Y is replaced by the year with century as a decimal number.
%Z is replaced by the time zone name or by no characters if a time zone cannot be determined.
%% is replaced by %.

See Chapter 10, "Localization," in the SAS/C Library Reference, Volume 2 for a discussion of how locale affects the behavior of strftime . See Chapter 11, "Multibyte Character Functions," in the SAS/C Library Reference, Volume 2 for a discussion of the relationship between the format string for strftime and multibyte characters.


RETURN VALUE

If the conversion results in no more than maxsize characters, including the terminating-null character, strftime returns the number of resulting characters. This return value does not include the terminating-null character.

If the conversion results in more than maxsize characters, strftime returns 0. In this case, the contents of the array pointed to by s are indeterminate. The return value will be zero also if strftime is given an invalid format specifier, or if strftime fails for some reason other than the conversion resulting in more than maxsize characters.


CAUTION

If copying takes place between overlapping objects, the behavior of strftime is undefined.

If a conversion specification is not one of those listed above or some other error occurs while processing a specification, strftime issues a diagnostic, null terminates the conversion output array up to the specification that caused the error, and returns 0.


EXAMPLE

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

main()
{
   time_t now;
   struct tm *tm_ptr;
   char date_str[80];
   size_t nchar;

   time(&now);                /* Obtain today's date/time. */
   tm_ptr = localtime(&now); /* Convert value to a tm struct. */
   nchar = strftime(date_str, sizeof(date_str),
           "Today is %A, %B %d, %Y and %I:%M:%S %p is the time.",
            tm_ptr);
   printf("%.80s", date_str);
}


RELATED FUNCTIONS

asctime , tzset


SEE ALSO


Chapter Contents

Previous

Next

Top of Page

Copyright © 2001 by SAS Institute Inc., Cary, NC, USA. All rights reserved.