1*b5677b36Schristos.\" Id: assertions.mdoc,v 1.3 2004/03/09 06:30:06 marka Exp 2*b5677b36Schristos.\" 3*b5677b36Schristos.\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC") 4*b5677b36Schristos.\" Copyright (c) 1997,1999 by Internet Software Consortium. 5*b5677b36Schristos.\" 6*b5677b36Schristos.\" Permission to use, copy, modify, and distribute this software for any 7*b5677b36Schristos.\" purpose with or without fee is hereby granted, provided that the above 8*b5677b36Schristos.\" copyright notice and this permission notice appear in all copies. 9*b5677b36Schristos.\" 10*b5677b36Schristos.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES 11*b5677b36Schristos.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12*b5677b36Schristos.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR 13*b5677b36Schristos.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14*b5677b36Schristos.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15*b5677b36Schristos.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT 16*b5677b36Schristos.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17*b5677b36Schristos.\" 18*b5677b36Schristos.Dd November 17, 1997 19*b5677b36Schristos.Dt ASSERTIONS 3 20*b5677b36Schristos.Os ISC 21*b5677b36Schristos.Sh NAME 22*b5677b36Schristos.Nm REQUIRE , 23*b5677b36Schristos.Nm REQUIRE_ERR , 24*b5677b36Schristos.Nm ENSURE , 25*b5677b36Schristos.Nm ENSURE_ERR , 26*b5677b36Schristos.Nm INSIST , 27*b5677b36Schristos.Nm INSIST_ERR , 28*b5677b36Schristos.Nm INVARIANT , 29*b5677b36Schristos.Nm INVARIANT_ERR , 30*b5677b36Schristos.Nm set_assertion_failure_callback 31*b5677b36Schristos.Nd assertion system 32*b5677b36Schristos.Sh SYNOPSIS 33*b5677b36Schristos.Fd #include <isc/assertions.h> 34*b5677b36Schristos.Fo "typedef void (*assertion_failure_callback)" 35*b5677b36Schristos.Fa "char *filename" 36*b5677b36Schristos.Fa "int line" 37*b5677b36Schristos.Fa "assertion_type type" 38*b5677b36Schristos.Fa "char *condition" 39*b5677b36Schristos.Fa "int print_errno" 40*b5677b36Schristos.Fc 41*b5677b36Schristos.Fn REQUIRE "int boolean_expression" 42*b5677b36Schristos.Fn REQUIRE_ERR "int boolean_expression" 43*b5677b36Schristos.Fn ENSURE "int boolean_expression" 44*b5677b36Schristos.Fn ENSURE_ERR "int boolean_expression" 45*b5677b36Schristos.Fn INSIST "int boolean_expression" 46*b5677b36Schristos.Fn INSIST_ERR "int boolean_expression" 47*b5677b36Schristos.Fn INVARIANT "int boolean_expression" 48*b5677b36Schristos.Fn INVARIANT_ERR "int boolean_expression" 49*b5677b36Schristos.Ft void 50*b5677b36Schristos.Fn set_assertion_failure_callback "assertion_failure_callback callback" 51*b5677b36Schristos.Ft char * 52*b5677b36Schristos.Fn assertion_type_to_text "assertion_type type" 53*b5677b36Schristos.Sh DESCRIPTION 54*b5677b36SchristosThe 55*b5677b36Schristos.Fn REQUIRE , 56*b5677b36Schristos.Fn ENSURE , 57*b5677b36Schristos.Fn INSIST , 58*b5677b36Schristosand 59*b5677b36Schristos.Fn INVARIANT 60*b5677b36Schristosmacros evaluate a boolean expression, and if it is false, they invoke the 61*b5677b36Schristoscurrent assertion failure callback. The default callback will print a message 62*b5677b36Schristosto 63*b5677b36Schristos.Li stderr 64*b5677b36Schristosdescribing the failure, and then cause the program to dump core. 65*b5677b36SchristosIf the 66*b5677b36Schristos.Dq Fn _ERR 67*b5677b36Schristosvariant of the assertion is used, the callback will include 68*b5677b36Schristos.Fn strerror "errno" 69*b5677b36Schristosin its message. 70*b5677b36Schristos.Pp 71*b5677b36SchristosEach assertion type has an associated 72*b5677b36Schristos.Li CHECK 73*b5677b36Schristosmacro. If this macro's value is 74*b5677b36Schristos.Dq 0 75*b5677b36Schristoswhen 76*b5677b36Schristos.Dq "<isc/assertions.h>" 77*b5677b36Schristosis included, then assertions of that type will not be checked. E.g. 78*b5677b36Schristos.Pp 79*b5677b36Schristos.Dl #define CHECK_ENSURE 0 80*b5677b36Schristos.Pp 81*b5677b36Schristoswill disable checking of 82*b5677b36Schristos.Fn ENSURE 83*b5677b36Schristosand 84*b5677b36Schristos.Fn ENSURE_ERR . 85*b5677b36SchristosThe macros 86*b5677b36Schristos.Li CHECK_ALL 87*b5677b36Schristosand 88*b5677b36Schristos.Li CHECK_NONE 89*b5677b36Schristosmay also be used, respectively specifying that either all or none of the 90*b5677b36Schristosassertion types should be checked. 91*b5677b36Schristos.Pp 92*b5677b36Schristos.Fn set_assertion_failure_callback 93*b5677b36Schristosspecifies the function to call when an assertion fails. 94*b5677b36Schristos.Pp 95*b5677b36SchristosWhen an 96*b5677b36Schristos.Fn assertion_failure_callback 97*b5677b36Schristosis called, the 98*b5677b36Schristos.Fa filename 99*b5677b36Schristosand 100*b5677b36Schristos.Fa line 101*b5677b36Schristosarguments specify the filename and line number of the failing assertion. 102*b5677b36SchristosThe 103*b5677b36Schristos.Fa type 104*b5677b36Schristosis one of: 105*b5677b36Schristos.Bd -literal -offset indent 106*b5677b36Schristosassert_require 107*b5677b36Schristosassert_ensure 108*b5677b36Schristosassert_insist 109*b5677b36Schristosassert_invariant 110*b5677b36Schristos.Ed 111*b5677b36Schristos.Pp 112*b5677b36Schristosand may be used by the callback to determine the type of the failing 113*b5677b36Schristosassertion. 114*b5677b36Schristos.Fa condition 115*b5677b36Schristosis the literal text of the assertion that failed. 116*b5677b36Schristos.Fa print_errno 117*b5677b36Schristoswill be non-zero if the callback should print 118*b5677b36Schristos.Fa strerror "errno" 119*b5677b36Schristosas part of its output. 120*b5677b36Schristos.Pp 121*b5677b36Schristos.Fn assertion_type_to_text 122*b5677b36Schristosreturns a textual representation of 123*b5677b36Schristos.Fa type . 124*b5677b36SchristosFor example, 125*b5677b36Schristos.Fn assertion_type_to_text "assert_require" 126*b5677b36Schristosreturns the string 127*b5677b36Schristos.Dq REQUIRE . 128*b5677b36Schristos.Sh SEE ALSO 129*b5677b36Schristos.Rs 130*b5677b36Schristos.%A Bertrand Meyer 131*b5677b36Schristos.%B Object-Oriented Software Construction, 2nd edition 132*b5677b36Schristos.%Q Prentice\-Hall 133*b5677b36Schristos.%D 1997 134*b5677b36Schristos.%O ISBN 0\-13\-629155\-4 135*b5677b36Schristos.%P chapter 11 136*b5677b36Schristos.Re 137*b5677b36Schristos.Sh AUTHOR 138*b5677b36SchristosBob Halley (ISC). 139