src/kits/network/netresolv/isc/assertions.mdoc

   1 .\" $Id: assertions.mdoc,v 1.3 2004/03/09 06:30:06 marka Exp $
   2 .\"
   3 .\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC")
   4 .\" Copyright (c) 1997,1999 by Internet Software Consortium.
   5 .\"
   6 .\" Permission to use, copy, modify, and distribute this software for any
   7 .\" purpose with or without fee is hereby granted, provided that the above
   8 .\" copyright notice and this permission notice appear in all copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
  11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12 .\" MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR
  13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
  16 .\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17 .\"
  18 .Dd November 17, 1997
  19 .Dt ASSERTIONS 3
  20 .Os ISC
  21 .Sh NAME
  22 .Nm REQUIRE ,
  23 .Nm REQUIRE_ERR ,
  24 .Nm ENSURE ,
  25 .Nm ENSURE_ERR ,
  26 .Nm INSIST ,
  27 .Nm INSIST_ERR ,
  28 .Nm INVARIANT ,
  29 .Nm INVARIANT_ERR ,
  30 .Nm set_assertion_failure_callback
  31 .Nd assertion system
  32 .Sh SYNOPSIS
  33 .Fd #include <isc/assertions.h>
  34 .Fo "typedef void (*assertion_failure_callback)"
  35 .Fa "char *filename"
  36 .Fa "int line"
  37 .Fa "assertion_type type"
  38 .Fa "char *condition"
  39 .Fa "int print_errno"
  40 .Fc
  41 .Fn REQUIRE "int boolean_expression"
  42 .Fn REQUIRE_ERR "int boolean_expression"
  43 .Fn ENSURE "int boolean_expression"
  44 .Fn ENSURE_ERR "int boolean_expression"
  45 .Fn INSIST "int boolean_expression"
  46 .Fn INSIST_ERR "int boolean_expression"
  47 .Fn INVARIANT "int boolean_expression"
  48 .Fn INVARIANT_ERR "int boolean_expression"
  49 .Ft void
  50 .Fn set_assertion_failure_callback "assertion_failure_callback callback"
  51 .Ft char *
  52 .Fn assertion_type_to_text "assertion_type type"
  53 .Sh DESCRIPTION
  54 The
  55 .Fn REQUIRE ,
  56 .Fn ENSURE ,
  57 .Fn INSIST ,
  58 and
  59 .Fn INVARIANT
  60 macros evaluate a boolean expression, and if it is false, they invoke the
  61 current assertion failure callback.  The default callback will print a message
  62 to
  63 .Li stderr
  64 describing the failure, and then cause the program to dump core.
  65 If the
  66 .Dq Fn _ERR
  67 variant of the assertion is used, the callback will include
  68 .Fn strerror "errno"
  69 in its message.
  70 .Pp
  71 Each assertion type has an associated
  72 .Li CHECK
  73 macro.  If this macro's value is
  74 .Dq 0
  75 when
  76 .Dq "<isc/assertions.h>"
  77 is included, then assertions of that type will not be checked.  E.g.
  78 .Pp
  79 .Dl #define CHECK_ENSURE 0
  80 .Pp
  81 will disable checking of
  82 .Fn ENSURE
  83 and
  84 .Fn ENSURE_ERR .
  85 The macros
  86 .Li CHECK_ALL
  87 and
  88 .Li CHECK_NONE
  89 may also be used, respectively specifying that either all or none of the
  90 assertion types should be checked.
  91 .Pp
  92 .Fn set_assertion_failure_callback
  93 specifies the function to call when an assertion fails.
  94 .Pp
  95 When an
  96 .Fn assertion_failure_callback
  97 is called, the
  98 .Fa filename
  99 and
 100 .Fa line
 101 arguments specify the filename and line number of the failing assertion.
 102 The
 103 .Fa type
 104 is one of:
 105 .Bd -literal -offset indent
 106 assert_require
 107 assert_ensure
 108 assert_insist
 109 assert_invariant
 110 .Ed
 111 .Pp
 112 and may be used by the callback to determine the type of the failing
 113 assertion.
 114 .Fa condition
 115 is the literal text of the assertion that failed.
 116 .Fa print_errno
 117 will be non-zero if the callback should print
 118 .Fa strerror "errno"
 119 as part of its output.
 120 .Pp
 121 .Fn assertion_type_to_text
 122 returns a textual representation of
 123 .Fa type .
 124 For example,
 125 .Fn assertion_type_to_text "assert_require"
 126 returns the string
 127 .Dq REQUIRE .
 128 .Sh SEE ALSO
 129 .Rs
 130 .%A Bertrand Meyer
 131 .%B Object-Oriented Software Construction, 2nd edition
 132 .%Q Prentice\-Hall
 133 .%D 1997
 134 .%O ISBN 0\-13\-629155\-4
 135 .%P chapter 11
 136 .Re
 137 .Sh AUTHOR
 138 Bob Halley (ISC).