Export (0) Print
Expand All
div
eof
Expand Minimize
This topic has not yet been rated - Rate this topic

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 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
buffer

Buffer to hold error string.

numberOfElements

Size of buffer.

errnum

Error number.

strErrMsg

User-supplied message.

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

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

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.

See the example for perror.

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.