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 Enhancements 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 03:14:07 January 19, 2038.

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

Return Value

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.

Error Conditions

buffer	numberOfElements	time	Return	Value in buffer
NULL	any	any	EINVAL	Not modified
Not NULL (points to valid memory)	0	any	EINVAL	Not modified
Not NULL	0< size < 26	any	EINVAL	Empty string
Not NULL	>= 26	NULL	EINVAL	Empty string
Not NULL	>= 26	< 0	EINVAL	Empty string

Remarks

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.

In Visual C++ 2005, 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_s	ctime_s	ctime_s	_wctime_s
_tctime32_s	_ctime32_s	_ctime32_s	_wctime32_s
_tctime64_s	_ctime64_s	_ctime64_s	_wctime64_s

Requirements

Routine	Required 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.

Libraries

All versions of the C run-time libraries.

Example

// 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( L"The time is %s\n", buf );
}

Sample Output

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

.NET Framework Equivalent

• System::DateTime::GetDateTimeFormats

• System::DateTime::ToString

• System::DateTime::ToLongTimeString

• System::DateTime::ToShortTimeString

See Also

Concepts

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