.\" Id: assertions.mdoc,v 1.3 2004/03/09 06:30:06 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 DESCRIPTION
The
.Fn REQUIRE ,
.Fn ENSURE ,
.Fn INSIST ,
and
.Fn 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 
.Li stderr
describing the failure, and then cause the program to dump core.
If the
.Dq Fn _ERR
variant of the assertion is used, the callback will include
.Fn strerror "errno"
in its message.
.Pp
Each assertion type has an associated
.Li CHECK
macro.  If this macro's value is
.Dq 0
when
.Dq "<isc/assertions.h>"
is included, then assertions of that type will not be checked.  E.g.
.Pp
.Dl #define CHECK_ENSURE 0
.Pp
will disable checking of
.Fn ENSURE
and
.Fn ENSURE_ERR .
The macros
.Li CHECK_ALL
and
.Li CHECK_NONE
may also be used, respectively specifying that either all or none of the
assertion types should be checked.
.Pp
.Fn set_assertion_failure_callback
specifies the function to call when an assertion fails.
.Pp
When an
.Fn assertion_failure_callback
is called, the 
.Fa filename
and
.Fa line
arguments specify the filename and line number of the failing assertion.
The
.Fa type
is one of:
.Bd -literal -offset indent
assert_require
assert_ensure
assert_insist
assert_invariant
.Ed
.Pp
and may be used by the callback to determine the type of the failing
assertion.
.Fa condition
is the literal text of the assertion that failed. 
.Fa print_errno
will be non-zero if the callback should print
.Fa strerror "errno"
as part of its output.
.Pp
.Fn assertion_type_to_text
returns 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 AUTHOR
Bob Halley (ISC).