doc/verify.texi

   1 @c GNU verify module documentation
   2
   3 @c Copyright (C) 2006, 2009--2020 Free Software Foundation, Inc.
   4
   5 @c Permission is granted to copy, distribute and/or modify this document
   6 @c under the terms of the GNU Free Documentation License, Version 1.3 or
   7 @c any later version published by the Free Software Foundation; with no
   8 @c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
   9 @c copy of the license is at <https://www.gnu.org/licenses/fdl-1.3.en.html>.
  10
  11 @node Compile-time Assertions
  12 @section Compile-time Assertions
  13
  14 @cindex assertion
  15 @findex verify
  16 @findex verify_expr
  17
  18 This module provides a header file @file{verify.h} that defines
  19 macros related to compile-time verification.
  20
  21 Two of these macros are @code{verify (@var{V})} and @code{verify_expr
  22 (@var{V}, @var{EXPR})}.  Both accept an integer constant expression
  23 argument @var{V} and verify that it is nonzero.  If not, a compile-time error
  24 results.
  25
  26 These two macros implement compile-time tests, as opposed to
  27 the standard @code{assert} macro which supports only runtime tests.
  28 Since the tests occur at compile-time, they are more reliable, and
  29 they require no runtime overhead.
  30
  31 @code{verify (@var{V});} is a declaration; it can occur outside of
  32 functions.  In contrast, @code{verify_expr (@var{V}, @var{EXPR})} is
  33 an expression that returns the value of @var{EXPR}; it can be used in
  34 macros that expand to expressions.  If @var{EXPR} is an integer
  35 constant expression, then @code{verify_expr (@var{V}, @var{EXPR})} is
  36 also an integer constant expression.  Although @var{EXPR} and
  37 @code{verify_expr (@var{V}, @var{EXPR})}@ are guaranteed to have the
  38 same side effects and value and type (after integer promotion), they
  39 need not have the same type if @var{EXPR}'s type is an integer that is
  40 narrower than @code{int} or @code{unsigned int}.
  41
  42 @var{V} should be an integer constant expression in the sense
  43 of the C standard.  Its leaf operands should be integer, enumeration,
  44 or character constants; or @code{sizeof} expressions that return
  45 constants; or floating constants that are the immediate operands of
  46 casts.  Outside a @code{sizeof} subexpression, @var{V} should
  47 not contain any assignments, function calls, comma operators, casts to
  48 non-integer types, or subexpressions whose values are outside the
  49 representable ranges for their types.  If @var{V} is not an
  50 integer constant expression, then a compiler might reject a usage like
  51 @samp{verify (@var{V});} even when @var{V} is
  52 nonzero.
  53
  54 Although the standard @code{assert} macro is a runtime test, C2X
  55 specifies a builtin @code{_Static_assert (@var{V})},
  56 its @file{assert.h} header has a similar macro
  57 named @code{static_assert}, and C++17 has a similar
  58 @code{static_assert} builtin.  These builtins and macros differ
  59 from @code{verify} in two major ways.  First, they can also be used
  60 within a @code{struct} or @code{union} specifier, in place of an
  61 ordinary member declaration.  Second, they allow the programmer to
  62 specify, as an optional second argument, a compile-time diagnostic as
  63 a string literal.  If your program is not intended to be portable to
  64 compilers that lack C2X or C++17 @code{static_assert}, the only
  65 advantage of @code{verify} is that its name is a bit shorter.
  66
  67 The @file{verify.h} header defines one more macro, @code{assume
  68 (@var{E})}, which expands to an expression of type @code{void}
  69 that causes the compiler to assume that @var{E} yields a nonzero
  70 value.  @var{E} should be a scalar expression, and should not
  71 have side effects; it may or may not be evaluated.  The behavior is
  72 undefined if @var{E} would yield zero.  The main use of @code{assume}
  73 is optimization, as the compiler may be able to generate better code
  74 if it assumes @var{E}.  For best results, @var{E} should be simple
  75 enough that a compiler can determine that it has no side effects: if
  76 @var{E} calls an external function or accesses volatile storage the
  77 compiler may not be able to optimize @var{E} away and @code{assume
  78 (@var{E})} may therefore slow down the program.
  79
  80 Here are some example uses of these macros.
  81
  82 @example
  83 #include <verify.h>
  84
  85 #include <limits.h>
  86 #include <time.h>
  87
  88 /* Verify that time_t is an integer type.  */
  89 verify ((time_t) 1.5 == 1);
  90
  91 /* Verify that time_t is no smaller than int.  */
  92 verify (sizeof (int) <= sizeof (time_t));
  93
  94 /* Verify that time_t is signed.  */
  95 verify ((time_t) -1 < 0);
  96
  97 /* Verify that time_t uses two's complement representation.  */
  98 verify (~ (time_t) -1 == 0);
  99
 100 /* Return the maximum value of the integer type T,
 101    verifying that T is an unsigned integer type.
 102    The cast to (T) is outside the call to verify_expr
 103    so that the result is of type T
 104    even when T is narrower than unsigned int.  */
 105 #define MAX_UNSIGNED_VAL(t) \
 106    ((T) verify_expr (0 < (T) -1, -1))
 107
 108 /* Return T divided by CHAR_MAX + 1, where behavior is
 109    undefined if T < 0.  In the common case where CHAR_MAX
 110    is 127 the compiler can therefore implement the division
 111    by shifting T right 7 bits, an optimization that would
 112    not be valid if T were negative.  */
 113 time_t
 114 time_index (time_t t)
 115 @{
 116   assume (0 <= t);
 117   return t / (CHAR_MAX + 1);
 118 @}
 119
 120
 121 @end example