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.\" $FreeBSD$ 25.\" 26.Dd August 18, 2018 27.Dt SET_CONSTRAINT_HANDLER_S 3 28.Os 29.Sh NAME 30.Nm set_constraint_handler_s , 31.Nm abort_handler_s , 32.Nm ignore_handler_s 33.Nd runtime-constraint violation handling 34.Sh LIBRARY 35.Lb libc 36.Sh SYNOPSIS 37.Fd #define __STDC_WANT_LIB_EXT1__ 1 38.In stdlib.h 39.Ft constraint_handler_t 40.Fo set_constraint_handler_s 41.Fa "constraint_handler_t handler" 42.Fc 43.Ss Handler Prototype 44.Ft typedef void 45.Fo (*constraint_handler_t) 46.Fa "const char * restrict msg" 47.Fa "void * restrict ptr" 48.Fa "errno_t error" 49.Fc 50.Ss Predefined Handlers 51.Ft void 52.Fo abort_handler_s 53.Fa "const char * restrict msg" 54.Fa "void * restrict ptr" 55.Fa "errno_t error" 56.Fc 57.Ft void 58.Fo ignore_handler_s 59.Fa "const char * restrict msg" 60.Fa "void * restrict ptr" 61.Fa "errno_t error" 62.Fc 63.Sh DESCRIPTION 64The 65.Fn set_constraint_handler_s 66function sets the runtime-constraint violation handler to be 67.Fa handler . 68.Pp 69The runtime-constraint handler is the callback function invoked when a library 70function detects a runtime-constraint violation. 71.Pp 72The arguments are as follows: 73.Bl -tag -width "error" 74.It Fa msg 75A pointer to a character string describing the runtime-constraint violation. 76.It Fa ptr 77A 78.Dv NULL 79pointer. 80.It Fa error 81If the function calling the handler has a return type declared as 82.Vt errno_t , 83the return value of the function is passed. 84Otherwise, a positive value of type 85.Vt errno_t 86is passed. 87.El 88.Pp 89Only the most recent handler registered with 90.Fn set_constraint_handler_s 91is called when a runtime-constraint violation occurs. 92.Pp 93The implementation has a default constraint handler that is used if no calls to 94the 95.Fn set_constraint_handler_s 96function have been made. 97If the 98.Fa handler 99argument to 100.Fn set_constraint_handler_s 101is a 102.Dv NULL 103pointer, the default handler becomes the current constraint handler. 104.Pp 105The 106.Fn abort_handler_s 107and 108.Fn ignore_handler_s 109are the standard-defined runtime-constraint handlers provided by the C library. 110.Pp 111The 112.Fn abort_handler_s 113function writes the error message including the 114.Fa msg 115to 116.Dv stderr 117and calls the 118.Xr abort 3 119function. 120The 121.Fn abort_handler_s 122is currently the default runtime-constraint handler. 123.Pp 124The 125.Fn ignore_handler_s 126simply returns to its caller. 127.Sh RETURN VALUES 128The 129.Fn set_constraint_handler_s 130function returns a pointer to the previously registered handler, or 131.Dv NULL 132if none was previously registered. 133.Pp 134The 135.Fn abort_handler_s 136function does not return to its caller. 137.Pp 138The 139.Fn ignore_handler_s 140function returns no value. 141.Sh STANDARDS 142The 143.Fn set_constraint_handler_s 144function conforms to 145.St -isoC-2011 146K.3.6.1.1. 147.Sh AUTHORS 148This manual page was written by 149.An Yuri Pankov Aq Mt yuripv@yuripv.net . 150