Edit

Share via

_invalid_parameter, _invalid_parameter_noinfo, _invalid_parameter_noinfo_noreturn, _invoke_watson

  • Article

These functions are used by the C Runtime Library to handle non-valid parameters passed to CRT Library functions. Your code may also use these functions to support default or customizable handling of non-valid parameters.

Syntax

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);

Parameters

expression
A string representing the source code parameter expression that isn't valid.

function_name
The name of the function that called the handler.

file_name
The source code file where the handler was called.

line_number
The line number in the source code where the handler was called.

reserved
Unused.

Return value

These functions don't return a value. The _invalid_parameter_noinfo_noreturn and _invoke_watson functions don't return to the caller, and in some cases, _invalid_parameter and _invalid_parameter_noinfo may not return to the caller.

Remarks

When C runtime library functions are passed non-valid parameters, the library functions call an invalid parameter handler, a function that may be specified by the programmer to do any of several things. For example, it may report the issue to the user, write to a log, break in a debugger, terminate the program, or do nothing at all. If no function is specified by the programmer, a default handler, _invoke_watson, is called.

By default, when a non-valid parameter is identified in debug code, CRT library functions call the function _invalid_parameter using verbose parameters. In non-debug code, the _invalid_parameter_noinfo function is called, which calls the _invalid_parameter function using empty parameters. If the non-debug CRT library function requires program termination, the _invalid_parameter_noinfo_noreturn function is called, which calls the _invalid_parameter function using empty parameters, followed by a call to the _invoke_watson function to force program termination.

The _invalid_parameter function checks whether a user-defined invalid parameter handler was set, and if so, calls it. For example, if a user-defined thread-local handler was set by a call to set_thread_local_invalid_parameter_handler in the current thread, it's called, then the function returns. Otherwise, if a user-defined global invalid parameter handler was set by a call to set_invalid_parameter_handler, it's called, then the function returns. Otherwise, the default handler _invoke_watson is called. The default behavior of _invoke_watson is to terminate the program. User-defined handlers may terminate or return. We recommend that user-defined handlers terminate the program unless recovery is certain.

When the default handler _invoke_watson is called, if the processor supports a __fastfail operation, it's invoked using a parameter of FAST_FAIL_INVALID_ARG and the process terminates. Otherwise, a fast fail exception is raised, which can be caught by an attached debugger. If the process is allowed to continue, it's terminated by a call to the Windows TerminateProcess function using an exception code status of STATUS_INVALID_CRUNTIME_PARAMETER.

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

Requirements

Function Required header
_invalid_parameter, _invalid_parameter_noinfo, _invalid_parameter_noinfo_noreturn, _invoke_watson <corecrt.h>

For more compatibility information, see Compatibility.

See also

Alphabetical function reference
_get_invalid_parameter_handler, _get_thread_local_invalid_parameter_handler
_set_invalid_parameter_handler, _set_thread_local_invalid_parameter_handler
Parameter validation