_set_invalid_parameter_handler, _set_thread_local_invalid_parameter_handler

Article
06/05/2017

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at _set_invalid_parameter_handler, _set_thread_local_invalid_parameter_handler.

Sets a function to be called when the CRT detects an invalid argument.

Syntax

_invalid_parameter_handler _set_invalid_parameter_handler(  
   _invalid_parameter_handler pNew  
);  
_invalid_parameter_handler _set_thread_local_invalid_parameter_handler(  
   _invalid_parameter_handler pNew  
);

Parameters

[in] pNew
The function pointer to the new invalid parameter handler.

Return Value

A pointer to the invalid parameter handler before the call.

Remarks

Many C runtime functions check the validity of arguments passed to them. If an invalid argument is passed, the function can set the errno error number or return an error code. In such cases, the invalid parameter handler is also called. The C runtime supplies a default global invalid parameter handler that terminates the program and displays a runtime error message. You can use the _set_invalid_parameter_handler to set your own function as the global invalid parameter handler. The C runtime also supports a thread-local invalid parameter handler. If a thread-local parameter handler is set in a thread by using _set_thread_local_invalid_parameter_handler, the C runtime functions called from the thread use that handler instead of the global handler. Only one function can be specified as the global invalid argument handler at a time. Only one function can be specified as the thread-local invalid argument handler per thread, but different threads can have different thread-local handlers. This allows you to change the handler used in one part of your code without affecting the behavior of other threads.

When the runtime calls the invalid parameter function, it usually means that a nonrecoverable error occurred. The invalid parameter handler function you supply should save any data it can and then abort. It should not return control to the main function unless you are confident that the error is recoverable.

The invalid parameter handler function must have the following prototype:

void _invalid_parameter(  
   const wchar_t * expression,  
   const wchar_t * function,   
   const wchar_t * file,   
   unsigned int line,  
   uintptr_t pReserved  
);

The expression argument is a wide string representation of the argument expression that raised the error. The function argument is the name of the CRT function that received the invalid argument. The file argument is the name of the CRT source file that contains the function. The line argument is the line number in that file. The last argument is reserved. The parameters all have the value NULL unless a debug version of the CRT library is used.

Requirements

Routine	Required header
`_set_invalid_parameter_handler`, `_set_thread_local_invalid_parameter_handler`	C: <stdlib.h> C++: <cstdlib> or <stdlib.h>

The _set_invalid_parameter_handler and _set_thread_local_invalid_parameter_handler functions are Microsoft specific. For compatibility information, see Compatibility.

Example

In the following example, an invalid parameter error handler is used to print the function that received the invalid parameter and the file and line in CRT sources. When the debug CRT library is used, invalid parameter errors also raise an assertion, which is disabled in this example using _CrtSetReportMode.

// crt_set_invalid_parameter_handler.c  
// compile with: /Zi /MTd  
#include <stdio.h>  
#include <stdlib.h>  
#include <crtdbg.h>  // For _CrtSetReportMode  
  
void myInvalidParameterHandler(const wchar_t* expression,  
   const wchar_t* function,   
   const wchar_t* file,   
   unsigned int line,   
   uintptr_t pReserved)  
{  
   wprintf(L"Invalid parameter detected in function %s."  
            L" File: %s Line: %d\n", function, file, line);  
   wprintf(L"Expression: %s\n", expression);  
   abort();  
}  
  
int main( )  
{  
   char* formatString;  
  
   _invalid_parameter_handler oldHandler, newHandler;  
   newHandler = myInvalidParameterHandler;  
   oldHandler = _set_invalid_parameter_handler(newHandler);  
  
   // Disable the message box for assertions.  
   _CrtSetReportMode(_CRT_ASSERT, 0);  
  
   // Call printf_s with invalid parameters.  
  
   formatString = NULL;  
   printf(formatString);  
}

Invalid parameter detected in function common_vfprintf. File: minkernel\crts\ucrt\src\appcrt\stdio\output.cpp Line: 32  
Expression: format != nullptr