strftime, wcsftime
Format a time string.
size_tstrftime(char*strDest,size_tmaxsize**,constchar*format,conststructtm*timeptr);**
size_twcsftime(wchar_t*strDest,size_tmaxsize**,constwchar_t*format,conststructtm*timeptr);**
| Routine | Required Header | Compatibility |
| strftime | <time.h> | ANSI, Win 95, Win NT |
| wcsftime | <time.h> or <wchar.h> | ANSI, Win 95, Win NT |
For additional compatibility information, see Compatibility in the Introduction.
Libraries
| LIBC.LIB | Single thread static library, retail version |
| LIBCMT.LIB | Multithread static library, retail version |
| MSVCRT.LIB | Import library for MSVCRT.DLL, retail version |
Return Value
strftime returns the number of characters placed in strDest if the total number of resulting characters, including the terminating null, is not more than maxsize. wcsftime returns the corresponding number of wide characters. Otherwise, the functions return 0, and the contents of strDest is indeterminate.
Parameters
strDest
Output string
maxsize
Maximum length of string
format
Format-control string
timeptr
tm data structure
Remarks
The strftime and wcsftime functions format the tm time value in timeptr according to the supplied format argument and store the result in the buffer strDest. At most, maxsize characters are placed in the string. For a description of the fields in the timeptr structure, see asctime. wcsftime is the wide-character equivalent of strftime; its string-pointer argument points to a wide-character string. These functions behave identically otherwise.
Note Prior to this version of Visual C++, the documentation described the format parameter of wcsftime as having the datatype const wchar_t *, but the actual implementation of the format datatype was const char *. In this version, the implementation of the format datatype has been updated to reflect the previous and current documentation, that is: const wchar_t *.
Generic-Text Routine Mappings
| TCHAR.H Routine | _UNICODE & _MBCS Not Defined | _MBCS Defined | _UNICODE Defined |
| _tcsftime | strftime | strftime | wcsftime |
The format argument consists of one or more codes; as in printf, the formatting codes are preceded by a percent sign (%). Characters that do not begin with % are copied unchanged to strDest. The LC_TIME category of the current locale affects the output formatting of strftime.(For more information on LC_TIME, see setlocale.) The formatting codes for strftime are listed below:
%a
Abbreviated weekday name
%A
Full weekday name
%b
Abbreviated month name
%B
Full month name
%c
Date and time representation appropriate for locale
%d
Day of month as decimal number (01 – 31)
%H
Hour in 24-hour format (00 – 23)
%I
Hour in 12-hour format (01 – 12)
%j
Day of year as decimal number (001 – 366)
%m
Month as decimal number (01 – 12)
%M
Minute as decimal number (00 – 59)
%p
Current locale’s A.M./P.M. indicator for 12-hour clock
%S
Second as decimal number (00 – 59)
%U
Week of year as decimal number, with Sunday as first day of week (00 – 53)
%w
Weekday as decimal number (0 – 6; Sunday is 0)
%W
Week of year as decimal number, with Monday as first day of week (00 – 53)
%x
Date representation for current locale
%X
Time representation for current locale
%y
Year without century, as decimal number (00 – 99)
%Y
Year with century, as decimal number
%z, %Z
Time-zone name or abbreviation; no characters if time zone is unknown
%%
Percent sign
As in the printf function, the # flag may prefix any formatting code. In that case, the meaning of the format code is changed as follows.
| Format Code | Meaning |
| %#a, %#A, %#b, %#B, %#p, %#X, %#z, %#Z, %#% | # flag is ignored. |
| %#c | Long date and time representation, appropriate for current locale. For example: “Tuesday, March 14, 1995, 12:41:29”. |
| %#x | Long date representation, appropriate to current locale. For example: “Tuesday, March 14, 1995”. |
| %#d, %#H, %#I, %#j, %#m, %#M, %#S, %#U, %#w, %#W, %#y, %#Y | Remove leading zeros (if any). |
Example
/* TIMES.C illustrates various time and date functions including:
* time _ftime ctime asctime
* localtime gmtime mktime _tzset
* _strtime _strdate strftime
* Also the global variable:
* _tzname
*/
#include <time.h>
#include <stdio.h>
#include <sys/types.h>
#include <sys/timeb.h>
#include <string.h>
void main()
{
char tmpbuf[128], ampm[] = "AM";
time_t ltime;
struct _timeb tstruct;
struct tm *today, *gmt, xmas = { 0, 0, 12, 25, 11, 93 };
/* Set time zone from TZ environment variable. If TZ is not set,
* the operating system is queried to obtain the default value
* for the variable.
*/
_tzset();
/* Display operating system-style date and time. */
_strtime( tmpbuf );
printf( "OS time:\t\t\t\t%s\n", tmpbuf );
_strdate( tmpbuf );
printf( "OS date:\t\t\t\t%s\n", tmpbuf );
/* Get UNIX-style time and display as number and string. */
time( <ime );
printf( "Time in seconds since UTC 1/1/70:\t%ld\n", ltime );
printf( "UNIX time and date:\t\t\t%s", ctime( <ime ) );
/* Display UTC. */
gmt = gmtime( <ime );
printf( "Coordinated universal time:\t\t%s", asctime( gmt ) );
/* Convert to time structure and adjust for PM if necessary. */
today = localtime( <ime );
if( today->tm_hour > 12 )
{
strcpy( ampm, "PM" );
today->tm_hour -= 12;
}
if( today->tm_hour == 0 ) /* Adjust if midnight hour. */
today->tm_hour = 12;
/* Note how pointer addition is used to skip the first 11
* characters and printf is used to trim off terminating
* characters.
*/
printf( "12-hour time:\t\t\t\t%.8s %s\n",
asctime( today ) + 11, ampm );
/* Print additional time information. */
_ftime( &tstruct );
printf( "Plus milliseconds:\t\t\t%u\n", tstruct.millitm );
printf( "Zone difference in seconds from UTC:\t%u\n",
tstruct.timezone );
printf( "Time zone name:\t\t\t\t%s\n", _tzname[0] );
printf( "Daylight savings:\t\t\t%s\n",
tstruct.dstflag ? "YES" : "NO" );
/* Make time for noon on Christmas, 1993. */
if( mktime( &xmas ) != (time_t)-1 )
printf( "Christmas\t\t\t\t%s\n", asctime( &xmas ) );
/* Use time structure to build a customized time string. */
today = localtime( <ime );
/* Use strftime to build a customized time string. */
strftime( tmpbuf, 128,
"Today is %A, day %d of %B in the year %Y.\n", today );
printf( tmpbuf );
}
Output
OS time: 21:51:03
OS date: 05/03/94
Time in seconds since UTC 1/1/70: 768027063
UNIX time and date: Tue May 03 21:51:03 1994
Coordinated universal time: Wed May 04 04:51:03 1994
12-hour time: 09:51:03 PM
Plus milliseconds: 279
Zone difference in seconds from UTC: 480
Time zone name:
Daylight savings: YES
Christmas Sat Dec 25 12:00:00 1993
Today is Tuesday, day 03 of May in the year 1994.
Locale Routines, Time Management Routines | String Manipulation Routines
See Also localeconv, setlocale, strcoll, _stricoll, strxfrm