139 lines
3.6 KiB
Plaintext
139 lines
3.6 KiB
Plaintext
.\" $Id: assertions.mdoc,v 8.3 2001/08/08 07:50:20 marka Exp $
|
|
.\"
|
|
.\"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 INTERNET SOFTWARE CONSORTIUM DISCLAIMS
|
|
.\"ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
|
|
.\"OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL INTERNET SOFTWARE
|
|
.\"CONSORTIUM 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).
|