strerror_s, _strerror_s, _wcserror_s, __wcserror_s

Статья
06/09/2015

Получает сообщение о системной ошибке (strerror_s, _wcserror_s) или печатает указанное пользователем сообщение об ошибке (_strerror_s, __wcserror_s). Здесь представлены версии strerror, _strerror, _wcserror, __wcserror с усовершенствованной безопасностью, как описано в разделе Функции безопасности в 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
Буфер для хранения строки ошибок.
numberOfElements
Размер buffer.
errnum
Номер ошибки.
strErrMsg
Предоставленное пользователем сообщение.

Возвращаемое значение

Нуль, если успешно; код ошибки при неудаче.

Условия возникновения ошибки

buffer	numberOfElements	strErrMsg	Содержимое buffer.
NULL	any	any	Н/Д
any	0	any	без изменений

Заметки

Функция strerror_s сопоставляет errnum в строку сообщения об ошибке, возвращая строку в buffer. _strerror_s не принимает номер ошибки; он использует текущее значение errno для определения соответствующего сообщения. Ни strerror_s, ни _strerror_s не печатает сообщения: Для этого необходимо вызвать функцию вывода, например fprintf.

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

Если strErrMsg равен NULL, _strerror_s возвращает строку в buffer, содержащий сообщение о системной ошибке для последнего вызова библиотеки, создавшего ошибку. Строка сообщения об ошибке заканчивается символом новой строки ('\n'). Если strErrMsg не равно NULL, то _strerror_s возвращает строку в buffer, содержащий (в таком порядке) строку сообщения, двоеточие, пробел, сообщение о системной ошибке для последнего вызова библиотеки, создавшего ошибку, и символ новой строки. Строка сообщения может быть длиной не более 94 символа.

Эти функции усекают сообщение об ошибке, если его длина превышает numberOfElements -1. Результирующая строка в buffer всегда завершается символом null.

Фактический номер ошибки для _strerror_s хранится в переменной errno. Доступ к сообщениям о системной ошибке осуществляется через переменную _sys_errlist, которая представляет собой массив сообщений об ошибке, отсортированный по номеру ошибки. _strerror_s получает доступ к соответствующему сообщению об ошибке, используя значение errno в качестве индекса для массива _sys_errlist. Значение переменной _sys_nerr определено как максимальное количество элементов в массиве _sys_errlist. Для предоставления точных результатов следует вызывать _strerror_s сразу после того, как библиотечная подпрограммы возвращается с ошибкой. В противном случае последующие вызовы strerror_s или _strerror_s могут перезаписать значение errno.

_wcserror_sи __wcserror_sверсии с расширенными символами функций strerror_sи _strerror_s соответственно.

Эти функции проверяют свои параметры. Если буфер равен NULL, или если параметр размера равен 0, то вызывается обработчик недопустимого параметра, как описано в разделе Проверка параметров. Если продолжение выполнения разрешено, эти функции возвращают EINVAL и устанавливают для errno значение EINVAL.

_strerror_s, _wcserror_s, и __wcserror_s не являются частью определения ANSI, а вместо этого они - расширения Майкрософт для него. Их не следует использовать там, где отдается предпочтение переносимости; для обеспечения совместимости с ANSI, используйте вместо них strerror_s .

В C++ использование этих функций упрощено шаблонными перегрузками; перегрузки могут определить длину буфера автоматически, устранена необходимость указывать аргумент size. Дополнительные сведения см. в разделе Безопасные перегрузки шаблонов.

Отладочные версии этих функций сначала заполняют буфер значением 0xFD. Для отключения данного поведения используйте _CrtSetDebugFillThreshold.

Универсальное текстовое сопоставление функций