_invalid_parameter, _invalid_parameter_noinfo, _invalid_parameter_noinfo_noreturn, _invoke_watson

Essas funções são usadas pela Biblioteca em Runtime do C para lidar com parâmetros inválidos passados para funções da biblioteca do CRT. Seu código também pode usar essas funções para dar suporte à manipulação padrão ou personalizável de parâmetros inválidos.

Sintaxe

extern "C" void __cdecl
_invalid_parameter(
    wchar_t const* const expression,
    wchar_t const* const function_name,
    wchar_t const* const file_name,
    unsigned int   const line_number,
    uintptr_t      const reserved);

extern "C" void __cdecl
_invalid_parameter_noinfo(void);

extern "C" __declspec(noreturn) void __cdecl
_invalid_parameter_noinfo_noreturn(void);

extern "C" __declspec(noreturn) void __cdecl
_invoke_watson(
    wchar_t const* const expression,
    wchar_t const* const function_name,
    wchar_t const* const file_name,
    unsigned int   const line_number,
    uintptr_t      const reserved);

Parâmetros

expression
Uma cadeia de caracteres que representa a expressão do parâmetro do código-fonte que não é válida.

function_name
O nome da função que chamou o manipulador.

file_name
O arquivo de código-fonte em que o manipulador foi chamado.

line_number
O número de linha no código-fonte em que o manipulador foi chamado.

reserved
Não utilizado.

Valor retornado

Essas funções não retornam um valor. As funções _invalid_parameter_noinfo_noreturn e _invoke_watson não são retornadas ao chamador e, em alguns casos, _invalid_parameter e _invalid_parameter_noinfo podem não ser retornadas ao chamador.

Comentários

Quando funções da biblioteca de runtime do C recebem parâmetros inválidos, as funções da biblioteca chamam um manipulador de parâmetro inválido, que é uma função que pode ser especificada pelo programador para realizar várias ações. Por exemplo, ela pode informar o problema para o usuário, gravar em um log, interrompê-lo em um depurador, encerrar o programa ou não fazer nada. Se nenhuma função for especificada pelo programador, um manipulador padrão, _invoke_watson, será chamado.

Por padrão, quando um parâmetro inválido é identificado no código de depuração, funções da biblioteca do CRT chamam a função _invalid_parameter usando parâmetros detalhados. No código sem depuração, a função _invalid_parameter_noinfo é chamada, o que chama a função _invalid_parameter usando parâmetros vazios. Se a função da biblioteca do CRT sem depuração exigir o encerramento do programa, a função _invalid_parameter_noinfo_noreturn será chamada, o que chama a função _invalid_parameter usando parâmetros vazios, seguidos por uma chamada para a função _invoke_watson para forçar o encerramento do programa.

A função _invalid_parameter verifica se um manipulador de parâmetro inválido definido pelo usuário foi definido e, nesse caso, o chama. Por exemplo, se um manipulador local do thread definido pelo usuário tiver sido definido por uma chamada para set_thread_local_invalid_parameter_handler no thread atual, ele será chamado e a função retornará. Caso contrário, se um manipulador de parâmetro inválido global definido pelo usuário tiver sido definido por uma chamada para set_invalid_parameter_handler, ele será chamado e a função retornará. Caso contrário, o manipulador padrão _invoke_watson será chamado. O comportamento padrão de _invoke_watson é encerrar o programa. Manipuladores definidos pelo usuário podem ser encerrados ou retornados. Recomendamos que manipuladores definidos pelo usuário finalizem o programa, a menos que a recuperação seja certa.

Quando o manipulador padrão _invoke_watson é chamado, se o processador der suporte a uma operação __fastfail, ele será invocado usando um parâmetro de FAST_FAIL_INVALID_ARG e o processo será encerrado. Caso contrário, uma exceção de falha rápida será gerada, o que pode ser capturado por um depurador anexado. Se o processo puder continuar, ele será encerrado por uma chamada à função TerminateProcess do Windows usando um status de código de exceção STATUS_INVALID_CRUNTIME_PARAMETER.

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

Requisitos

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

Confira também

Referência alfabética de função
_get_invalid_parameter_handler, _get_thread_local_invalid_parameter_handler
_set_invalid_parameter_handler, _set_thread_local_invalid_parameter_handler
Validação de parâmetros