NAME    [Toc]    [Back]

     REQUIRE, REQUIRE_ERR, ENSURE, ENSURE_ERR, INSIST, INSIST_ERR, INVARIANT,
     INVARIANT_ERR, set_assertion_failure_callback -- assertion system

SYNOPSIS    [Toc]    [Back]

     #include <isc/assertions.h>

     typedef void (*assertion_failure_callback)(char *filename, int line,
	 assertion_type type, char *condition, int print_errno);

     REQUIRE(int boolean_expression);

     REQUIRE_ERR(int boolean_expression);

     ENSURE(int boolean_expression);

     ENSURE_ERR(int boolean_expression);

     INSIST(int boolean_expression);

     INSIST_ERR(int boolean_expression);

     INVARIANT(int boolean_expression);

     INVARIANT_ERR(int boolean_expression);

     void
     set_assertion_failure_callback(assertion_failure_callback callback);

     char *
     assertion_type_to_text(assertion_type type);

DESCRIPTION    [Toc]    [Back]

     The REQUIRE(), ENSURE(), INSIST(), and INVARIANT() macros evaluate a
     boolean expression, and if it is false, they invoke the current assertion
     failure callback.	The default callback will print a message to stderr
     describing the failure, and then cause the program to dump core.  If the
     ``_ERR()'' variant of the assertion is used, the callback will include
     strerror(errno) in its message.

     Each assertion type has an associated CHECK macro.  If this macro's value
     is ``0'' when ``<isc/assertions.h>'' is included, then assertions of that
     type will not be checked.	E.g.

	   #define CHECK_ENSURE 0

     will disable checking of ENSURE() and ENSURE_ERR().  The macros CHECK_ALL
     and CHECK_NONE may also be used, respectively specifying that either all
     or none of the assertion types should be checked.

     set_assertion_failure_callback() specifies the function to call when an
     assertion fails.

     When an assertion_failure_callback() is called, the filename and line
     arguments specify the filename and line number of the failing assertion.
     The type is one of:

	   assert_require
	   assert_ensure
	   assert_insist
	   assert_invariant

     and may be used by the callback to determine the type of the failing
     assertion.  condition is the literal text of the assertion that failed.
     print_errno will be non-zero if the callback should print strerror errno
     as part of its output.

     assertion_type_to_text() returns a textual representation of type.  For
     example, assertion_type_to_text(assert_require) returns the string
     ``REQUIRE''.

SEE ALSO    [Toc]    [Back]

     Bertrand Meyer, Object-Oriented Software Construction, 2nd edition,
     chapter 11, Prentice-Hall, 1997, ISBN 0-13-629155-4.

AUTHOR    [Toc]    [Back]

     Bob Halley (ISC).

ISC			       November 17, 1997			   ISC