diff options
author | Konstantin Belousov <kib@FreeBSD.org> | 2018-08-19 14:39:57 +0000 |
---|---|---|
committer | Konstantin Belousov <kib@FreeBSD.org> | 2018-08-19 14:39:57 +0000 |
commit | 540cc17f7b96475db0c4c59741639b041cc77007 (patch) | |
tree | 9423493a0e82b25dbded733fbbf024fcfe480827 | |
parent | f9f8ac94cd4d6d357784bb1c0bfdc2906608e123 (diff) | |
download | src-540cc17f7b96475db0c4c59741639b041cc77007.tar.gz src-540cc17f7b96475db0c4c59741639b041cc77007.zip |
Provide set_constraint_handler_s(3) man page.
Mention abort_handler_s(3) and ignore_handler_s(3), provide
cross-reference from memset(3).
Submitted by: Yuri Pankov <yuripv@yuripv.net>
MFC after: 3 days
Differential revision: https://reviews.freebsd.org/D16797
Notes
Notes:
svn path=/head/; revision=338051
-rw-r--r-- | lib/libc/stdlib/Makefile.inc | 7 | ||||
-rw-r--r-- | lib/libc/stdlib/set_constraint_handler_s.3 | 149 | ||||
-rw-r--r-- | lib/libc/string/memset.3 | 1 |
3 files changed, 155 insertions, 2 deletions
diff --git a/lib/libc/stdlib/Makefile.inc b/lib/libc/stdlib/Makefile.inc index 3994ea3453be..ee6d98e9cf6a 100644 --- a/lib/libc/stdlib/Makefile.inc +++ b/lib/libc/stdlib/Makefile.inc @@ -36,8 +36,9 @@ MAN+= a64l.3 abort.3 abs.3 alloca.3 atexit.3 atof.3 \ hcreate.3 imaxabs.3 imaxdiv.3 insque.3 labs.3 ldiv.3 llabs.3 lldiv.3 \ lsearch.3 memory.3 ptsname.3 qsort.3 \ quick_exit.3 \ - radixsort.3 rand.3 random.3 reallocarray.3 reallocf.3 \ - realpath.3 strfmon.3 strtod.3 strtol.3 strtonum.3 strtoul.3 system.3 \ + radixsort.3 rand.3 random.3 reallocarray.3 reallocf.3 realpath.3 \ + set_constraint_handler_s.3 \ + strfmon.3 strtod.3 strtol.3 strtonum.3 strtoul.3 system.3 \ tsearch.3 MLINKS+=a64l.3 l64a.3 a64l.3 l64a_r.3 @@ -55,6 +56,8 @@ MLINKS+=rand.3 rand_r.3 rand.3 srand.3 rand.3 sranddev.3 MLINKS+=random.3 initstate.3 random.3 setstate.3 random.3 srandom.3 \ random.3 srandomdev.3 MLINKS+=radixsort.3 sradixsort.3 +MLINKS+=set_constraint_handler_s.3 abort_handler_s.3 +MLINKS+=set_constraint_handler_s.3 ignore_handler_s.3 MLINKS+=strfmon.3 strfmon_l.3 MLINKS+=strtod.3 strtof.3 strtod.3 strtold.3 MLINKS+=strtol.3 strtoll.3 strtol.3 strtoq.3 strtol.3 strtoimax.3 diff --git a/lib/libc/stdlib/set_constraint_handler_s.3 b/lib/libc/stdlib/set_constraint_handler_s.3 new file mode 100644 index 000000000000..85956d2a9997 --- /dev/null +++ b/lib/libc/stdlib/set_constraint_handler_s.3 @@ -0,0 +1,149 @@ +.\" Copyright 2018 Yuri Pankov <yuripv@yuripv.net> +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd August 18, 2018 +.Dt SET_CONSTRAINT_HANDLER_S 3 +.Os +.Sh NAME +.Nm set_constraint_handler_s , +.Nm abort_handler_s , +.Nm ignore_handler_s +.Nd runtime-constraint violation handling +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.Fd #define __STDC_WANT_LIB_EXT1__ 1 +.In stdlib.h +.Ft constraint_handler_t +.Fo set_constraint_handler_s +.Fa "constraint_handler_t handler" +.Fc +.Ss Handler Prototype +.Ft typedef void +.Fo (*constraint_handler_t) +.Fa "const char * restrict msg" +.Fa "void * restrict ptr" +.Fa "errno_t error" +.Fc +.Ss Predefined Handlers +.Ft void +.Fo abort_handler_s +.Fa "const char * restrict msg" +.Fa "void * restrict ptr" +.Fa "errno_t error" +.Fc +.Ft void +.Fo ignore_handler_s +.Fa "const char * restrict msg" +.Fa "void * restrict ptr" +.Fa "errno_t error" +.Fc +.Sh DESCRIPTION +The +.Fn set_constraint_handler_s +function sets the runtime-constraint violation handler to be +.Fa handler . +.Pp +The runtime-constraint handler is the callback function invoked when a library +function detects a runtime-constraint violation. +.Pp +The arguments are as follows: +.Bl -tag -width "error" +.It Fa msg +A pointer to a character string describing the runtime-constraint violation. +.It Fa ptr +A +.Dv NULL +pointer. +.It Fa error +If the function calling the handler has a return type declared as +.Vt errno_t , +the return value of the function is passed. +Otherwise, a positive value of type +.Vt errno_t +is passed. +.El +.Pp +Only the most recent handler registered with +.Fn set_constraint_handler_s +is called when a runtime-constraint violation occurs. +.Pp +The implementation has a default constraint handler that is used if no calls to +the +.Fn set_constraint_handler_s +function have been made. +If the +.Fa handler +argument to +.Fn set_constraint_handler_s +is a +.Dv NULL +pointer, the default handler becomes the current constraint handler. +.Pp +The +.Fn abort_handler_s +and +.Fn ignore_handler_s +are the standard-defined runtime-constraint handlers provided by the C library. +.Pp +The +.Fn abort_handler_s +function writes the error message including the +.Fa msg +to +.Dv stderr +and calls the +.Xr abort 3 +function. +The +.Fn abort_handler_s +is currently the default runtime-constraint handler. +.Pp +The +.Fn ignore_handler_s +simply returns to its caller. +.Sh RETURN VALUES +The +.Fn set_constraint_handler_s +function returns a pointer to the previously registered handler, or +.Dv NULL +if none was previously registered. +.Pp +The +.Fn abort_handler_s +function does not return to its caller. +.Pp +The +.Fn ignore_handler_s +function returns no value. +.Sh STANDARDS +The +.Fn set_constraint_handler_s +function conforms to +.St -isoC-2011 +K.3.6.1.1. +.Sh AUTHORS +This manual page was written by +.An Yuri Pankov Aq Mt yuripv@yuripv.net . diff --git a/lib/libc/string/memset.3 b/lib/libc/string/memset.3 index 3f4b777a9e86..590bc08531b9 100644 --- a/lib/libc/string/memset.3 +++ b/lib/libc/string/memset.3 @@ -117,6 +117,7 @@ function returns zero on success, non-zero on error. .Sh SEE ALSO .Xr bzero 3 , .Xr explicit_bzero 3 , +.Xr set_constraint_handler_s 3 , .Xr swab 3 , .Xr wmemset 3 .Sh STANDARDS |