ASSERTIONS(3)

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

SYNOPSIS
#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
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
Bertrand Meyer, Object-Oriented Software Construction, 2nd edition, Prentice-Hall, 1997, ISBN 0-13-629155-4, chapter 11.

AUTHOR
Bob Halley (ISC).