View source for c/error/set constraint handler s

{{c/title|set_constraint_handler_s|constraint_handler_t}}
{{c/error/navbar}}
{{dcl begin}}
{{dcl header|stdlib.h}}
{{dcl|num=1|since=c11|
constraint_handler_t set_constraint_handler_s( constraint_handler_t handler );
}}
{{dcl|num=2|since=c11|
typedef void (*constraint_handler_t)( const char* restrict msg,
                                      void* restrict ptr,
                                      errno_t error );
}}
{{dcl end}}

@1@ Configures the handler to be called by all [[c/error#Bounds checking|bounds-checked functions]] on a runtime constraint violation or restores the default handler (if {{c|handler}} is a null pointer).

@2@ The pointer to a handler that will be called on a runtime constraint violation.

If {{tt|set_constraint_handler_s}} is never called, the default handler is implementation-defined: it may be {{lc|abort_handler_s}}, {{lc|ignore_handler_s}}, or some other implementation-defined handler.

As with all bounds-checked functions, {{tt|set_constraint_handler_s}} and {{tt|constraint_handler_t}} are only guaranteed to be available if {{c|__STDC_LIB_EXT1__}} is defined by the implementation and if the user defines {{c|__STDC_WANT_LIB_EXT1__}} to the integer constant {{c|1}} before including {{header|stdlib.h}}.

===Parameters===
{{par begin}}
{{par|handler|pointer to function of type {{tt|constraint_handler_t}} or a null pointer}}
{{par|msg|pointer to character string that describes the error}}
{{par|ptr|pointer to an implementation-defined object or a null pointer. Examples of implementation-defined objects are objects that give the name of the function that detected the violation and the line number when the violation was detected}}
{{par|error|the error about to be returned by the calling function, if it happens to be one of the functions that return {{tt|errno_t}}}}
{{par end}}

===Return value===
A pointer to the previously-installed runtime constraints handler. (Note: this pointer is never a null pointer because calling {{c|set_constraint_handler_s(NULL)}} sets up the system default handler).

===Example===
{{c/error/set_constraint_handler_example}}

===References===
{{ref std c23}}
{{ref std|section=K.3.6/2|title=constraint_handler_t|p=TBD}}
{{ref std|section=K.3.6.1.1|title=The set_constraint_handler_s function|p=TBD}}
{{ref std end}}
{{ref std c17}}
{{ref std|section=K.3.6/2|title=constraint_handler_t|p=TBD}}
{{ref std|section=K.3.6.1.1|title=The set_constraint_handler_s function|p=TBD}}
{{ref std end}}
{{ref std c11}}
{{ref std|section=K.3.6/2|title=constraint_handler_t|p=604}}
{{ref std|section=K.3.6.1.1|title=The set_constraint_handler_s function|p=604-605}}
{{ref std end}}

===See also===
{{dsc begin}}
{{dsc inc|c/error/abort_handler_s}}
{{dsc inc|c/error/ignore_handler_s}}
{{dsc end}}

{{langlinks|ar|cs|de|es|fr|it|ja|ko|pl|pt|ru|tr|zh}}