strerror_s, _strerror_s, _wcserror_s, __wcserror_s

Article
06/05/2017

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at strerror_s, _strerror_s, _wcserror_s, __wcserror_s.

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 Features in the CRT.

Syntax

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 the string in buffer. _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 string in buffer 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 string in buffer 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_s and __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