1*00efb5e1SYuri Pankov.\" 2*00efb5e1SYuri Pankov.\" This file and its contents are supplied under the terms of the 3*00efb5e1SYuri Pankov.\" Common Development and Distribution License ("CDDL"), version 1.0. 4*00efb5e1SYuri Pankov.\" You may only use this file in accordance with the terms of version 5*00efb5e1SYuri Pankov.\" 1.0 of the CDDL. 6*00efb5e1SYuri Pankov.\" 7*00efb5e1SYuri Pankov.\" A full copy of the text of the CDDL should have accompanied this 8*00efb5e1SYuri Pankov.\" source. A copy of the CDDL is also available via the Internet at 9*00efb5e1SYuri Pankov.\" http://www.illumos.org/license/CDDL. 10*00efb5e1SYuri Pankov.\" 11*00efb5e1SYuri Pankov.\" 12*00efb5e1SYuri Pankov.\" Copyright 2018 Nexenta Systems, Inc. 13*00efb5e1SYuri Pankov.\" 14*00efb5e1SYuri Pankov.Dd August 12, 2017 15*00efb5e1SYuri Pankov.Dt SET_CONSTRAINT_HANDLER_S 3C 16*00efb5e1SYuri Pankov.Os 17*00efb5e1SYuri Pankov.Sh NAME 18*00efb5e1SYuri Pankov.Nm set_constraint_handler_s , 19*00efb5e1SYuri Pankov.Nm abort_handler_s , 20*00efb5e1SYuri Pankov.Nm ignore_handler_s 21*00efb5e1SYuri Pankov.Nd runtime-constraint handling 22*00efb5e1SYuri Pankov.Sh LIBRARY 23*00efb5e1SYuri Pankov.Lb libc 24*00efb5e1SYuri Pankov.Sh SYNOPSIS 25*00efb5e1SYuri Pankov.Fd #define __STDC_WANT_LIB_EXT1__ 1 26*00efb5e1SYuri Pankov.In stdlib.h 27*00efb5e1SYuri Pankov.Ft constraint_handler_t 28*00efb5e1SYuri Pankov.Fo set_constraint_handler_s 29*00efb5e1SYuri Pankov.Fa "constraint_handler_t handler" 30*00efb5e1SYuri Pankov.Fc 31*00efb5e1SYuri Pankov.Ft void 32*00efb5e1SYuri Pankov.Fo abort_handler_s 33*00efb5e1SYuri Pankov.Fa "const char *restrict msg" 34*00efb5e1SYuri Pankov.Fa "void *restrict ptr" 35*00efb5e1SYuri Pankov.Fa "errno_t error" 36*00efb5e1SYuri Pankov.Fc 37*00efb5e1SYuri Pankov.Ft void 38*00efb5e1SYuri Pankov.Fo ignore_handler_s 39*00efb5e1SYuri Pankov.Fa "const char *restrict msg" 40*00efb5e1SYuri Pankov.Fa "void *restrict ptr" 41*00efb5e1SYuri Pankov.Fa "errno_t error" 42*00efb5e1SYuri Pankov.Fc 43*00efb5e1SYuri Pankov.Sh DESCRIPTION 44*00efb5e1SYuri PankovThe 45*00efb5e1SYuri Pankov.Fn set_constraint_handler_s 46*00efb5e1SYuri Pankovfunction sets the runtime-constraint handler to be 47*00efb5e1SYuri Pankov.Fa handler . 48*00efb5e1SYuri Pankov.Pp 49*00efb5e1SYuri PankovThe runtime-constraint handler is the callback function invoked when a library 50*00efb5e1SYuri Pankovfunction detects a runtime-constraint violation, having the following prototype: 51*00efb5e1SYuri Pankov.Bd -literal -offset indent 52*00efb5e1SYuri Pankovvoid (*constraint_handler_t)(const char *restrict msg, 53*00efb5e1SYuri Pankov void *restrict ptr, errno_t error); 54*00efb5e1SYuri Pankov.Ed 55*00efb5e1SYuri Pankov.Pp 56*00efb5e1SYuri PankovThe arguments are as follows: 57*00efb5e1SYuri Pankov.Bl -tag -width "error" 58*00efb5e1SYuri Pankov.It Fa msg 59*00efb5e1SYuri PankovA pointer to a character string describing the runtime-constraint violation. 60*00efb5e1SYuri Pankov.It Fa ptr 61*00efb5e1SYuri PankovA 62*00efb5e1SYuri Pankov.Dv NULL 63*00efb5e1SYuri Pankovpointer. 64*00efb5e1SYuri Pankov.It Fa error 65*00efb5e1SYuri PankovIf the function calling the handler has a return type declared as 66*00efb5e1SYuri Pankov.Vt errno_t , 67*00efb5e1SYuri Pankovthe return value of the function is passed. 68*00efb5e1SYuri PankovOtherwise, a positive value of type 69*00efb5e1SYuri Pankov.Vt errno_t 70*00efb5e1SYuri Pankovis passed. 71*00efb5e1SYuri Pankov.El 72*00efb5e1SYuri Pankov.Pp 73*00efb5e1SYuri PankovOnly the most recent handler registered with 74*00efb5e1SYuri Pankov.Fn set_constraint_handler_s 75*00efb5e1SYuri Pankovis called when a runtime-constraint violation occurs. 76*00efb5e1SYuri Pankov.Pp 77*00efb5e1SYuri PankovThe implementation has a default constraint handler that is used if no calls to 78*00efb5e1SYuri Pankovthe 79*00efb5e1SYuri Pankov.Fn set_constraint_handler_s 80*00efb5e1SYuri Pankovfunction have been made. 81*00efb5e1SYuri PankovIf the 82*00efb5e1SYuri Pankov.Fa handler 83*00efb5e1SYuri Pankovargument to 84*00efb5e1SYuri Pankov.Fn set_constraint_handler_s 85*00efb5e1SYuri Pankovis a 86*00efb5e1SYuri Pankov.Dv NULL 87*00efb5e1SYuri Pankovpointer, the default handler becomes the current constraint handler. 88*00efb5e1SYuri Pankov.Pp 89*00efb5e1SYuri PankovThe 90*00efb5e1SYuri Pankov.Fn abort_handler_s 91*00efb5e1SYuri Pankovand 92*00efb5e1SYuri Pankov.Fn ignore_handler_s 93*00efb5e1SYuri Pankovare the standard-defined runtime-constraint handlers provided by the C library. 94*00efb5e1SYuri Pankov.Pp 95*00efb5e1SYuri PankovThe 96*00efb5e1SYuri Pankov.Fn abort_handler_s 97*00efb5e1SYuri Pankovfunction writes the error message including the 98*00efb5e1SYuri Pankov.Fa msg 99*00efb5e1SYuri Pankovto 100*00efb5e1SYuri Pankov.Dv stderr 101*00efb5e1SYuri Pankovand calls the 102*00efb5e1SYuri Pankov.Xr abort 3C 103*00efb5e1SYuri Pankovfunction. 104*00efb5e1SYuri PankovThe 105*00efb5e1SYuri Pankov.Fn abort_handler_s 106*00efb5e1SYuri Pankovis currently the default runtime-constraint handler. 107*00efb5e1SYuri Pankov.Pp 108*00efb5e1SYuri PankovThe 109*00efb5e1SYuri Pankov.Fn ignore_handler_s 110*00efb5e1SYuri Pankovsimply returns to its caller. 111*00efb5e1SYuri Pankov.Sh RETURN VALUES 112*00efb5e1SYuri PankovThe 113*00efb5e1SYuri Pankov.Fn set_constraint_handler_s 114*00efb5e1SYuri Pankovfunction returns a pointer to the previously registered handler, or 115*00efb5e1SYuri Pankov.Dv NULL 116*00efb5e1SYuri Pankovif none was previously registered. 117*00efb5e1SYuri Pankov.Pp 118*00efb5e1SYuri PankovThe 119*00efb5e1SYuri Pankov.Fn abort_handler_s 120*00efb5e1SYuri Pankovfunction does not return to its caller. 121*00efb5e1SYuri Pankov.Pp 122*00efb5e1SYuri PankovThe 123*00efb5e1SYuri Pankov.Fn ignore_handler_s 124*00efb5e1SYuri Pankovfunction returns no value. 125*00efb5e1SYuri Pankov.Sh INTERFACE STABILITY 126*00efb5e1SYuri Pankov.Sy Standard 127*00efb5e1SYuri Pankov.Sh MT-LEVEL 128*00efb5e1SYuri Pankov.Sy Safe 129*00efb5e1SYuri Pankov.Sh STANDARDS 130*00efb5e1SYuri PankovThe 131*00efb5e1SYuri Pankov.Fn set_constraint_handler_s 132*00efb5e1SYuri Pankovfunction conforms to 133*00efb5e1SYuri Pankov.St -isoC-2011 . 134