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
  44 The
  45 .Fn set_constraint_handler_s
  46 function sets the runtime-constraint handler to be
  47 .Fa handler .
  48 .Pp
  49 The runtime-constraint handler is the callback function invoked when a library
  50 function detects a runtime-constraint violation, having the following prototype:
  51 .Bd -literal -offset indent
  52 void (*constraint_handler_t)(const char *restrict msg,
  53     void *restrict ptr, errno_t error);
  54 .Ed
  55 .Pp
  56 The arguments are as follows:
  57 .Bl -tag -width "error"
  58 .It Fa msg
  59 A pointer to a character string describing the runtime-constraint violation.
  60 .It Fa ptr
  61 A
  62 .Dv NULL
  63 pointer.
  64 .It Fa error
  65 If the function calling the handler has a return type declared as
  66 .Vt errno_t ,
  67 the return value of the function is passed.
  68 Otherwise, a positive value of type
  69 .Vt errno_t
  70 is passed.
  71 .El
  72 .Pp
  73 Only the most recent handler registered with
  74 .Fn set_constraint_handler_s
  75 is called when a runtime-constraint violation occurs.
  76 .Pp
  77 The implementation has a default constraint handler that is used if no calls to
  78 the
  79 .Fn set_constraint_handler_s
  80 function have been made.
  81 If the
  82 .Fa handler
  83 argument to
  84 .Fn set_constraint_handler_s
  85 is a
  86 .Dv NULL
  87 pointer, the default handler becomes the current constraint handler.
  88 .Pp
  89 The
  90 .Fn abort_handler_s
  91 and
  92 .Fn ignore_handler_s
  93 are the standard-defined runtime-constraint handlers provided by the C library.
  94 .Pp
  95 The
  96 .Fn abort_handler_s
  97 function writes the error message including the
  98 .Fa msg
  99 to
 100 .Dv stderr
 101 and calls the
 102 .Xr abort 3C
 103 function.
 104 The
 105 .Fn abort_handler_s
 106 is currently the default runtime-constraint handler.
 107 .Pp
 108 The
 109 .Fn ignore_handler_s
 110 simply returns to its caller.
 111 .Sh RETURN VALUES
 112 The
 113 .Fn set_constraint_handler_s
 114 function returns a pointer to the previously registered handler, or
 115 .Dv NULL
 116 if none was previously registered.
 117 .Pp
 118 The
 119 .Fn abort_handler_s
 120 function does not return to its caller.
 121 .Pp
 122 The
 123 .Fn ignore_handler_s
 124 function returns no value.
 125 .Sh INTERFACE STABILITY
 126 .Sy Standard
 127 .Sh MT-LEVEL
 128 .Sy Safe
 129 .Sh STANDARDS
 130 The
 131 .Fn set_constraint_handler_s
 132 function conforms to
 133 .St -isoC-2011 .