1.\" Copyright 2018 Yuri Pankov <yuripv@yuripv.net> 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions 5.\" are met: 6.\" 1. Redistributions of source code must retain the above copyright 7.\" notice, this list of conditions and the following disclaimer. 8.\" 2. Redistributions in binary form must reproduce the above copyright 9.\" notice, this list of conditions and the following disclaimer in the 10.\" documentation and/or other materials provided with the distribution. 11.\" 12.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 13.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 14.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 15.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 16.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 17.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 18.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 19.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 20.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 21.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 22.\" SUCH DAMAGE. 23.\" 24.Dd August 18, 2018 25.Dt SET_CONSTRAINT_HANDLER_S 3 26.Os 27.Sh NAME 28.Nm set_constraint_handler_s , 29.Nm abort_handler_s , 30.Nm ignore_handler_s 31.Nd runtime-constraint violation handling 32.Sh LIBRARY 33.Lb libc 34.Sh SYNOPSIS 35.Fd #define __STDC_WANT_LIB_EXT1__ 1 36.In stdlib.h 37.Ft constraint_handler_t 38.Fo set_constraint_handler_s 39.Fa "constraint_handler_t handler" 40.Fc 41.Ss Handler Prototype 42.Ft typedef void 43.Fo (*constraint_handler_t) 44.Fa "const char * restrict msg" 45.Fa "void * restrict ptr" 46.Fa "errno_t error" 47.Fc 48.Ss Predefined Handlers 49.Ft void 50.Fo abort_handler_s 51.Fa "const char * restrict msg" 52.Fa "void * restrict ptr" 53.Fa "errno_t error" 54.Fc 55.Ft void 56.Fo ignore_handler_s 57.Fa "const char * restrict msg" 58.Fa "void * restrict ptr" 59.Fa "errno_t error" 60.Fc 61.Sh DESCRIPTION 62The 63.Fn set_constraint_handler_s 64function sets the runtime-constraint violation handler to be 65.Fa handler . 66.Pp 67The runtime-constraint handler is the callback function invoked when a library 68function detects a runtime-constraint violation. 69.Pp 70The arguments are as follows: 71.Bl -tag -width "error" 72.It Fa msg 73A pointer to a character string describing the runtime-constraint violation. 74.It Fa ptr 75A 76.Dv NULL 77pointer. 78.It Fa error 79If the function calling the handler has a return type declared as 80.Vt errno_t , 81the return value of the function is passed. 82Otherwise, a positive value of type 83.Vt errno_t 84is passed. 85.El 86.Pp 87Only the most recent handler registered with 88.Fn set_constraint_handler_s 89is called when a runtime-constraint violation occurs. 90.Pp 91The implementation has a default constraint handler that is used if no calls to 92the 93.Fn set_constraint_handler_s 94function have been made. 95If the 96.Fa handler 97argument to 98.Fn set_constraint_handler_s 99is a 100.Dv NULL 101pointer, the default handler becomes the current constraint handler. 102.Pp 103The 104.Fn abort_handler_s 105and 106.Fn ignore_handler_s 107are the standard-defined runtime-constraint handlers provided by the C library. 108.Pp 109The 110.Fn abort_handler_s 111function writes the error message including the 112.Fa msg 113to 114.Dv stderr 115and calls the 116.Xr abort 3 117function. 118The 119.Fn abort_handler_s 120is currently the default runtime-constraint handler. 121.Pp 122The 123.Fn ignore_handler_s 124simply returns to its caller. 125.Sh RETURN VALUES 126The 127.Fn set_constraint_handler_s 128function returns a pointer to the previously registered handler, or 129.Dv NULL 130if none was previously registered. 131.Pp 132The 133.Fn abort_handler_s 134function does not return to its caller. 135.Pp 136The 137.Fn ignore_handler_s 138function returns no value. 139.Sh STANDARDS 140The 141.Fn set_constraint_handler_s 142function conforms to 143.St -isoC-2011 144K.3.6.1.1. 145.Sh AUTHORS 146This manual page was written by 147.An Yuri Pankov Aq Mt yuripv@yuripv.net . 148