الملاحظات تحرير

strerror_s, _strerror_s, _wcserror_s, __wcserror_s

  • مقالة
  • قراءة خلال 3 دقائق

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 sizeInBytes,
   int errnum
);
errno_t _strerror_s(
   char *buffer,
   size_t sizeInBytes,
   const char *strErrMsg
);
errno_t _wcserror_s(
   wchar_t *buffer,
   size_t sizeInWords,
   int errnum
);
errno_t __wcserror_s(
   wchar_t *buffer,
   size_t sizeInWords,
   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.

sizeInBytes
The number of bytes in the buffer.

sizeInWords
The number of words in the buffer.

errnum
Error number.

strErrMsg
User-supplied message.

Return Value

Zero if successful, an error code on failure.

Error conditions

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

Remarks

The strerror_s function is thread-safe.

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, NULL);
   fprintf( stderr, buffer );
}

If strErrMsg is NULL, _strerror_s returns a string in buffer that contains 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 isn't equal to NULL, then _strerror_s returns a string in buffer that contains (in order) your string message, a colon, a space, the system error message for the last library call that produced 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 the size of the buffer - 1. The resulting string in buffer will always be 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_s are wide-character versions of strerror_s and _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 aren't part of the ANSI definition but are instead Microsoft extensions to it. Don't 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 library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use _CrtSetDebugFillThreshold.

By default, this function's global state is scoped to the application. To change this, see Global state in the CRT.

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.

Example

See the example for perror.

See also

String Manipulation
clearerr
ferror
perror, _wperror