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