ctime_s, _ctime32_s, _ctime64_s, _wctime_s, _wctime32_s, _wctime64_s

 

Convert a time value to a string and adjust for local time zone settings. These are versions of ctime, _ctime64, _wctime, _wctime64 with security enhancements as described in Security Features in the CRT.

errno_t ctime_s(   
   char* buffer,  
   size_t numberOfElements,  
   const time_t *time   
);  
errno_t _ctime32_s(   
   char* buffer,  
   size_t numberOfElements,  
   const __time32_t *time   
);  
errno_t _ctime64_s(   
   char* buffer,  
   size_t numberOfElements,  
   const __time64_t *time )  
;  
errno_t _wctime_s(   
   wchar_t* buffer,  
   size_t numberOfElements,  
   const time_t *time   
);  
errno_t _wctime32_s(   
   wchar_t* buffer,  
   size_t numberOfElements,  
   const __time32_t *time   
);  
errno_t _wctime64_s(   
   wchar_t* buffer,  
   size_t numberOfElements,  
   const __time64_t *time   
);  
template <size_t size>  
errno_t _ctime32_s(   
   char (&buffer)[size],  
   const __time32_t *time   
); // C++ only  
template <size_t size>  
errno_t _ctime64_s(   
   char (&buffer)[size],  
   const __time64_t *time  
); // C++ only  
template <size_t size>  
errno_t _wctime32_s(   
   wchar_t (&buffer)[size],  
   const __time32_t *time   
); // C++ only  
template <size_t size>  
errno_t _wctime64_s(   
   wchar_t (&buffer)[size],  
   const __time64_t *time   
); // C++ only  

Parameters

[out] buffer
Must be large enough to hold 26 characters. A pointer to the character string result, or NULLif:

  • time represents a date before midnight, January 1, 1970, UTC.

  • If you use _ctime32_s or _wctime32_s and time represents a date after 23:59:59 January 18, 2038, UTC.

  • If you use _ctime64_s or _wctime64_s and time represents a date after 23:59:59, December 31, 3000, UTC.

  • If you use _ctime_s or _wctime_s, these functions are wrappers to the previous functions. See the Remarks section.

[in] numberOfElements
The size of the buffer.

[in] time
Pointer to stored time.

Zero if successful. If there is a failure due to an invalid parameter, the invalid parameter handler is invoked, as described in Parameter Validation. If execution is allowed to continue, an error code is returned. Error codes are defined in ERRNO.H; for a listing of these errors, see errno. The actual error codes thrown for each error condition are shown in the following table.

buffernumberOfElementstimeReturnValue in buffer
NULLanyanyEINVALNot modified
Not NULL (points to valid memory)0anyEINVALNot modified
Not NULL0< size < 26anyEINVALEmpty string
Not NULL>= 26NULLEINVALEmpty string
Not NULL>= 26< 0EINVALEmpty string

The ctime_s function converts a time value stored as a time_t structure into a character string. The time value is usually obtained from a call to time, which returns the number of seconds elapsed since midnight (00:00:00), January 1, 1970, coordinated universal time (UTC). The return value string contains exactly 26 characters and has the form:

Wed Jan 02 02:03:55 1980\n\0  

A 24-hour clock is used. All fields have a constant width. The new line character ('\n') and the null character ('\0') occupy the last two positions of the string.

The converted character string is also adjusted according to the local time zone settings. See the time, _ftime, and localtime32_s functions for information about configuring the local time and the _tzset function for information about defining the time zone environment and global variables.

_wctime32_s and _wctime64_s are the wide-character version of _ctime32_s and _ctime64_s; returning a pointer to wide-character string. Otherwise, _ctime64_s, _wctime32_s, and _wctime64_s behave identically to _ctime32_s.

ctime_s is an inline function that evaluates to _ctime64_s and time_t is equivalent to __time64_t. If you need to force the compiler to interpret time_t as the old 32-bit time_t, you can define _USE_32BIT_TIME_T. Doing this will cause ctime_s to evaluate to _ctime32_s. This is not recommended because your application may fail after January 18, 2038, and it is not allowed on 64-bit platforms.

In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see Secure Template Overloads.

Generic-Text Routine Mappings

TCHAR.H routine_UNICODE & _MBCS not defined_MBCS defined_UNICODE defined
_tctime_sctime_sctime_s_wctime_s
_tctime32_s_ctime32_s_ctime32_s_wctime32_s
_tctime64_s_ctime64_s_ctime64_s_wctime64_s
RoutineRequired header
ctime_s,

 _ctime32_s,

 _ctime64_s
<time.h>
_wctime_s,

 _wctime32_s,

 _wctime64_s
<time.h> or <wchar.h>

For additional compatibility information, see Compatibility in the Introduction.

All versions of the C run-time libraries.

// crt_wctime_s.c  
/* This program gets the current  
 * time in time_t form and then uses _wctime_s to  
 * display the time in string form.  
 */  
  
#include <time.h>  
#include <stdio.h>  
  
#define SIZE 26  
  
int main( void )  
{  
   time_t ltime;  
   wchar_t buf[SIZE];  
   errno_t err;  
  
   time( &ltime );  
  
   err = _wctime_s( buf, SIZE, &ltime );  
   if (err != 0)  
   {  
      printf("Invalid Arguments for _wctime_s. Error Code: %d\n", err);  
   }  
   wprintf_s( L"The time is %s\n", buf );  
}  

The time is Fri Apr 25 13:03:39 2003  

Time Management
asctime_s, _wasctime_s
ctime, _ctime32, _ctime64, _wctime, _wctime32, _wctime64
_ftime, _ftime32, _ftime64
gmtime_s, _gmtime32_s, _gmtime64_s
localtime_s, _localtime32_s, _localtime64_s
time, _time32, _time64

Show: