.\" $Id: assertions.mdoc,v 1.1.2.1.10.1 2004/03/09 08:33:39 marka Exp $.\".\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC").\" Copyright (c) 1997,1999 by Internet Software Consortium..\".\" Permission to use, copy, modify, and distribute this software for any.\" purpose with or without fee is hereby granted, provided that the above.\" copyright notice and this permission notice appear in all copies..\".\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF.\" MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE..\".Dd November 17, 1997.Dt ASSERTIONS 3.Os ISC.Sh NAME.Nm REQUIRE ,.Nm REQUIRE_ERR ,.Nm ENSURE ,.Nm ENSURE_ERR ,.Nm INSIST ,.Nm INSIST_ERR ,.Nm INVARIANT ,.Nm INVARIANT_ERR ,.Nm set_assertion_failure_callback.Nd assertion system.Sh SYNOPSIS.Fd #include <isc/assertions.h>.Fo "typedef void (*assertion_failure_callback)".Fa "char *filename".Fa "int line".Fa "assertion_type type".Fa "char *condition".Fa "int print_errno".Fc.Fn REQUIRE "int boolean_expression".Fn REQUIRE_ERR "int boolean_expression".Fn ENSURE "int boolean_expression".Fn ENSURE_ERR "int boolean_expression".Fn INSIST "int boolean_expression".Fn INSIST_ERR "int boolean_expression".Fn INVARIANT "int boolean_expression".Fn INVARIANT_ERR "int boolean_expression".Ft void.Fn set_assertion_failure_callback "assertion_failure_callback callback".Ft char *.Fn assertion_type_to_text "assertion_type type".Sh DESCRIPTIONThe.Fn REQUIRE ,.Fn ENSURE ,.Fn INSIST ,and.Fn INVARIANTmacros evaluate a boolean expression, and if it is false, they invoke thecurrent assertion failure callback.  The default callback will print a messageto .Li stderrdescribing the failure, and then cause the program to dump core.If the.Dq Fn _ERRvariant of the assertion is used, the callback will include.Fn strerror "errno"in its message..PpEach assertion type has an associated.Li CHECKmacro.  If this macro's value is.Dq 0when.Dq "<isc/assertions.h>"is included, then assertions of that type will not be checked.  E.g..Pp.Dl #define CHECK_ENSURE 0.Ppwill disable checking of.Fn ENSUREand.Fn ENSURE_ERR .The macros.Li CHECK_ALLand.Li CHECK_NONEmay also be used, respectively specifying that either all or none of theassertion types should be checked..Pp.Fn set_assertion_failure_callbackspecifies the function to call when an assertion fails..PpWhen an.Fn assertion_failure_callbackis called, the .Fa filenameand.Fa linearguments specify the filename and line number of the failing assertion.The.Fa typeis one of:.Bd -literal -offset indentassert_requireassert_ensureassert_insistassert_invariant.Ed.Ppand may be used by the callback to determine the type of the failingassertion..Fa conditionis the literal text of the assertion that failed. .Fa print_errnowill be non-zero if the callback should print.Fa strerror "errno"as part of its output..Pp.Fn assertion_type_to_textreturns a textual representation of.Fa type .For example,.Fn assertion_type_to_text "assert_require"returns the string.Dq REQUIRE ..Sh SEE ALSO.Rs.%A Bertrand Meyer.%B Object-Oriented Software Construction, 2nd edition.%Q Prentice\-Hall.%D 1997.%O ISBN 0\-13\-629155\-4.%P chapter 11.Re.Sh AUTHORBob Halley (ISC).