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