strerror_s, _strerror_s, _wcserror_s, __wcserror_s

Receba uma mensagem de erro do sistema (strerror_s, _wcserror_s) ou imprima uma mensagem de erro fornecida pelo usuário (_strerror_s, __wcserror_s). Essas funções são versões de , _strerror, _wcserror, __wcserror com aprimoramentos destrerror segurança, conforme descrito em Recursos de segurança no CRT.

Sintaxe

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

Parâmetros

buffer
Buffer para conter a cadeia de caracteres de erro.

sizeInBytes
O número de bytes no buffer.

sizeInWords
O número de palavras no buffer.

errnum
Número de erro.

strErrMsg
Mensagem fornecida pelo usuário.

Valor retornado

Zero se for bem-sucedido ou um código de erro em caso de falha.

Condições de erro

buffer	sizeInBytes/sizeInWords	strErrMsg	Conteúdo de buffer
NULL	any	any	N/D
any	0	any	não modificado

Comentários

A função strerror_s é thread-safe.

A função strerror_s mapeia errnum para uma cadeia de caracteres de mensagens, retornando a cadeia de caracteres em buffer. _strerror_s não usa o número de erro; ele usa o valor atual de errno para determinar a mensagem apropriada. A mensagem não é impressa ou exibida por strerror_s ou _strerror_s. Para gerar a mensagem, você precisa chamar uma função de saída, como fprintf:

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

Se strErrMsg for NULL, _strerror_s retorna uma cadeia de caracteres que buffer contém a mensagem de erro do sistema para a última chamada de biblioteca que produziu um erro. Se strErrMsg não for igual a NULL, então _strerror_s retorna uma cadeia de caracteres que buffer contém (em ordem) sua mensagem de cadeia de caracteres, dois pontos, um espaço, a mensagem de erro do sistema para a última chamada de biblioteca que produziu um erro. Sua mensagem da cadeia de caracteres pode ter, no máximo, 94 caracteres de comprimento.

Essas funções truncam a mensagem de erro se o comprimento exceder o tamanho do buffer - 1. A cadeia de caracteres resultante em buffer é sempre terminada em nulo.

O número de erro real para _strerror_s é memorizado na variável errno. As mensagens de erro do sistema são acessadas por meio da variável _sys_errlist, que é uma matriz de mensagens ordenadas por número de erro. _strerror_s acessa a mensagem de erro apropriada usando o valor errno como um índice para a variável _sys_errlist. O valor da variável _sys_nerr é definido como o número máximo de elementos na _sys_errlist matriz. Para produzir resultados precisos, ligue _strerror_s imediatamente após um retorno de rotina de biblioteca com um erro. Caso contrário, chamadas subsequentes para strerror_s ou _strerror_s podem substituir o valor errno.

_wcserror_s e __wcserror_s são as versões de caractere largo de strerror_s e _strerror_s, respectivamente.

Essas funções validam seus parâmetros. Se buffer for NULL ou se o parâmetro de tamanho for 0, o manipulador de parâmetro inválido será invocado, conforme descrito em Validação de parâmetro. Se a execução tiver permissão para continuar, essas funções retornarão EINVAL e definirão errno como EINVAL.

_strerror_s, _wcserror_se __wcserror_s não fazem parte da definição ANSI, mas são extensões da Microsoft para ela. Não os use onde a portabilidade é desejada; para compatibilidade ANSI, use strerror_s em vez disso.

No C++, o uso dessas funções é simplificado por sobrecargas de modelo. As sobrecargas podem inferir automaticamente o tamanho do buffer, eliminando a necessidade de especificar um argumento de tamanho. Para obter mais informações, consulte Sobrecargas de modelo seguras.

As versões de biblioteca de depuração dessas funções preenchem o buffer com 0xFE. Para desabilitar esse comportamento, use _CrtSetDebugFillThreshold.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, confira Estado global no CRT.

Mapeamentos de rotina de texto genérico

Rotina TCHAR.H	_UNICODE e _MBCS não definidos	_MBCS definido	_UNICODE definido
_tcserror_s	strerror_s	strerror_s	_wcserror_s

Requisitos

Rotina	Cabeçalho necessário
strerror_s, _strerror_s	<string.h>
_wcserror_s, __wcserror_s	<string.h> ou <wchar.h>

Para obter informações sobre compatibilidade, consulte Compatibilidade.

Exemplo

Confira o exemplo de perror.

Confira também

Manipulação de cadeia de caracteres
clearerr
ferror
perror, _wperror