strerror_s, _strerror_s, _wcserror_s, __wcserror_s

Article
11/16/2012

Get a system error message (strerror_s, _wcserror_s) or print a user-supplied error message (_strerror_s, __wcserror_s). These are versions of strerror, _strerror, _wcserror, __wcserror with security enhancements as described in Security Enhancements in the CRT.

errno_t strerror_s(
   char *buffer,
   size_t numberOfElements,
   int errnum 
);
errno_t _strerror_s(
   char *buffer,
   size_t numberOfElements,
   const char *strErrMsg 
);
errno_t _wcserror_s(
   wchar_t *buffer,
   size_t numberOfElements,
   int errnum 
);
errno_t __wcserror_s(
   wchar_t *buffer,
   size_t numberOfElements,
   const wchar_t *strErrMsg 
);
template <size_t size>
errno_t strerror_s(
   char (&buffer)[size],
   int errnum 
); // C++ only
template <size_t size>
errno_t _strerror_s(
   char (&buffer)[size],
   const char *strErrMsg 
); // C++ only
template <size_t size>
errno_t _wcserror_s(
   wchar_t (&buffer)[size],
   int errnum 
); // C++ only
template <size_t size>
errno_t __wcserror_s(
   wchar_t (&buffer)[size],
   const wchar_t *strErrMsg 
); // C++ only

Parameters

buffer
Buffer to hold error string.
numberOfElements
Size of buffer.
errnum
Error number.
strErrMsg
User-supplied message.

Return Value

Zero if successful, an error code on failure.

Error Condtions

buffer	numberOfElements	strErrMsg	Contents of buffer
NULL	any	any	n/a
any	0	any	not modified

Remarks

The strerror_s function maps errnum to an error-message string, returning a pointer to the string. _strerror_s doesn't take the error number; it uses the current value of errno to determine the appropriate message. Neither strerror_s nor _strerror_s actually prints the message: For that, you need to call an output function such as fprintf:

if (( _access( "datafile",2 )) == -1 )
{
   _strerror_s(buffer, 80);
   fprintf( stderr, buffer );
}

If strErrMsg is NULL, _strerror_s returns a pointer to a string containing the system error message for the last library call that produced an error. The error-message string is terminated by the newline character ('\n'). If strErrMsg is not equal to NULL, then _strerror_s returns a pointer to a string containing (in order) your string message, a colon, a space, the system error message for the last library call producing an error, and a newline character. Your string message can be, at most, 94 characters long.

These functions truncate the error message if its length exceeds numberOfElements -1. The resulting string in buffer is always null-terminated.

The actual error number for _strerror_s is stored in the variable errno. The system error messages are accessed through the variable _sys_errlist, which is an array of messages ordered by error number. _strerror_s accesses the appropriate error message by using the errno value as an index to the variable _sys_errlist. The value of the variable _sys_nerr is defined as the maximum number of elements in the _sys_errlist array. To produce accurate results, call _strerror_s immediately after a library routine returns with an error. Otherwise, subsequent calls to strerror_s or _strerror_s can overwrite the errno value.

_wcserror_sand __wcserror_sare wide-character versions of strerror_sand _strerror_s, respectively.

These functions validate their parameters. If buffer is NULL or if the size parameter is 0, the invalid parameter handler is invoked, as described in Parameter Validation . If execution is allowed to continue, the functions return EINVAL and set errno to EINVAL.

_strerror_s, _wcserror_s, and __wcserror_s are not part of the ANSI definition but are instead Microsoft extensions to it. Do not use them where portability is desired; for ANSI compatibility, use strerror_s instead.

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.

The debug versions of these functions first fill the buffer with 0xFD. To disable this behavior, use _CrtSetDebugFillThreshold.

Generic-Text Routine Mappings

TCHAR.H routine	_UNICODE & _MBCS not defined	_MBCS defined	_UNICODE defined
_tcserror_s	strerror_s	strerror_s	_wcserror_s

Requirements

Routine	Required header
strerror_s, _strerror_s	<string.h>
_wcserror_s, __wcserror_s	<string.h> or <wchar.h>

For additional compatibility information, see Compatibility in the Introduction.

Example

See the example for perror.

.NET Framework Equivalent

System::Exception::Message

Share via