wcsftime() — Format date and time

Standards

Standards / Extensions	C or C++	Dependencies
ISO C Amendment XPG4 XPG4.2 C99 Single UNIX Specification, Version 3	both

Format

Non-XPG4:

#include <wchar.h>

size_t wcsftime(wchar_t * __restrict__ wcs, size_t maxsize, 
                const wchar_t * __restrict__ format,
                const struct tm * __restrict__ time_ptr)

XPG4:

#define _XOPEN_SOURCE
#include <wchar.h>

size_t wcsftime(wchar_t * __restrict__ wcs, size_t maxsize, 
                const char * __restrict__ format,
                const struct tm * __restrict__ time_ptr)

XPG4 and MSE:

#define _XOPEN_SOURCE
#define _MSE_PROTOS
#include <wchar.h>

size_t wcsftime(wchar_t * __restrict__ wcs, size_t maxsize, 
                const wchar_t * __restrict__ format,
                const struct tm * __restrict__ time_ptr)

General description

Format date and time into a wide character string. The wcsftime() function is equivalent to the strftime() function, except that:

The argument wcs specifies an array of a wide string into which the generated output is to be placed.
The argument maxsize indicates a number of wide characters.
The argument *format specifies an array of wide characters comprising the format string.
The returned value indicates a number of wide characters.

Special behavior for XPG4: If you define any feature test macro specifying XPG4 behavior before the statement in your program source file to include the wchar header, then the compiler assumes that your program is using the XPG4 variety of the wcsftime() function unless you also define the _MSE_PROTOS feature test macro. Please see Table 1 for a list of XPG4 and other feature test macros.

The prototype for the XPG4 variety of the wcsftime() function is:

size_t wcsftime(wchar_t *wcs, size_t maxsize, const char *format,
                const struct tm *time_ptr)

The difference between this variety and the MSE variety of the wcsftime() function is that the third argument *format specifies an array of characters rather than an array of wide characters comprising the format string.

Returned value

If the total number of resulting wide characters including the terminating NULL wide character is not more than maxsize, wcsftime() returns the number of wide characters placed into the array pointed to by wcs not including the terminating NULL wide character.

If unsuccessful, wcsftime() returns 0 and the contents of the array are indeterminate.

Example

CELEBW10

⁄* CELEBW10 *⁄                                   
#include <stdio.h>                                                              
#include <time.h>                                                               
#include <wchar.h>                                                              
                                                                                
int main(void)                                                                  
{                                                                               
   struct tm *timeptr;                                                          
   wchar_t dest[100];                                                           
   time_t  temp;                                                                
   size_t  rc;                                                                  
                                                                                
   temp = time(NULL);                                                           
   timeptr = localtime(&temp);                                                  
   rc = wcsftime(dest, sizeof(dest)-1, L" Today is %A,"                         
                 L" %b %d.\n Time: %I:%M %p", timeptr);                         
   printf("%d characters placed in string to make:\n\n%S", rc, dest);           
}

Output: