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