_strtime_s, _wstrtime_s
Copy the current time to a buffer. These are versions of _strtime, _wstrtime with security enhancements as described in Security Enhancements in the CRT.
errno_t _strtime_s( char *buffer, size_t numberOfElements ); errno_t _wstrtime_s( wchar_t *buffer, size_t numberOfElements ); template <size_t size> errno_t _strtime_s( char (&buffer)[size] ); // C++ only template <size_t size> errno_t _wstrtime_s( wchar_t (&buffer)[size] ); // C++ only
Zero if successful.
If an error condition occurs, the invalid parameter handler is invoked, as described in Parameter Validation. The return value is an error code if there is a failure. Error codes are defined in ERRNO.H; see the following table for the exact errors generated by this function. For more information on error codes, see errno Constants.
buffer | numberOfElements | Return | Contents of buffer |
|---|---|---|---|
NULL | (any) | EINVAL | Not modified |
Not NULL (pointing to valid buffer) | 0 | EINVAL | Not modified |
Not NULL (pointing to valid buffer) | 0 < size < 9 | EINVAL | Empty string |
Not NULL (pointing to valid buffer) | Size > 9 | 0 | Current time formatted as specified in the remarks |
These functions provide more secure versions of _strtime and _wstrtime. The _strtime_s function copies the current local time into the buffer pointed to by timestr. The time is formatted as hh:mm:ss where hh is two digits representing the hour in 24-hour notation, mm is two digits representing the minutes past the hour, and ss is two digits representing seconds. For example, the string 18:23:44 represents 23 minutes and 44 seconds past 6 P.M. The buffer must be at least 9 bytes long; the actual size is specified by the second parameter.
_wstrtime is a wide-character version of _strtime; the argument and return value of _wstrtime are wide-character strings. These functions behave identically otherwise.
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) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see Secure Template Overloads.
TCHAR.H routine | _UNICODE & _MBCS not defined | _MBCS defined | _UNICODE defined |
|---|---|---|---|
_tstrtime_s | _strtime_s | _strtime_s | _wstrtime_s |
Routine | Required header |
|---|---|
_strtime_s | <time.h> |
_wstrtime_s | <time.h> or <wchar.h> |
For additional compatibility information, see Compatibility in the Introduction.
// strtime_s.c
#include <time.h>
#include <stdio.h>
int main()
{
char tmpbuf[9];
errno_t err;
// 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.
err = _strtime_s( tmpbuf, 9 );
if (err)
{
printf("_strdate_s failed due to an invalid argument.");
exit(1);
}
printf( "OS time:\t\t\t\t%s\n", tmpbuf );
err = _strdate_s( tmpbuf, 9 );
if (err)
{
printf("_strdate_s failed due to an invalid argument.");
exit(1);
}
printf( "OS date:\t\t\t\t%s\n", tmpbuf );
}
