1 @c GNU verify module documentation
3 @c Copyright (C) 2006, 2009-2013 Free Software Foundation, Inc.
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
7 @c or any later version published by the Free Software Foundation;
8 @c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
9 @c Texts. A copy of the license is included in the ``GNU Free
10 @c Documentation License'' file as part of this distribution.
12 @node Compile-time Assertions
13 @section Compile-time Assertions
19 This module provides a header file @file{verify.h} that defines
20 macros related to compile-time verification.
22 Two of these macros are @code{verify (@var{V})} and @code{verify_expr
23 (@var{V}, @var{EXPR})}. Both accept an integer constant expression
24 argument @var{V} and verify that it is nonzero. If not, a compile-time error
27 These two macros implement compile-time tests, as opposed to
28 the standard @code{assert} macro which supports only runtime tests.
29 Since the tests occur at compile-time, they are more reliable, and
30 they require no runtime overhead.
32 @code{verify (@var{V});} is a declaration; it can occur outside of
33 functions. In contrast, @code{verify_expr (@var{V}, @var{EXPR})} is
34 an expression that returns the value of @var{EXPR}; it can be used in
35 macros that expand to expressions. If @var{EXPR} is an integer
36 constant expression, then @code{verify_expr (@var{V}, @var{EXPR})} is
37 also an integer constant expression. Although @var{EXPR} and
38 @code{verify_expr (@var{V}, @var{EXPR})}@ are guaranteed to have the
39 same side effects and value and type (after integer promotion), they
40 need not have the same type if @var{EXPR}'s type is an integer that is
41 narrower than @code{int} or @code{unsigned int}.
43 @var{V} should be an integer constant expression in the sense
44 of the C standard. Its leaf operands should be integer, enumeration,
45 or character constants; or @code{sizeof} expressions that return
46 constants; or floating constants that are the immediate operands of
47 casts. Outside a @code{sizeof} subexpression, @var{V} should
48 not contain any assignments, function calls, comma operators, casts to
49 non-integer types, or subexpressions whose values are outside the
50 representable ranges for their types. If @var{V} is not an
51 integer constant expression, then a compiler might reject a usage like
52 @samp{verify (@var{V});} even when @var{V} is
55 Although the standard @code{assert} macro is a runtime test, C11
56 specifies a builtin @code{_Static_assert (@var{V},
57 @var{STRING-LITERAL})}, its @file{assert.h} header has a similar macro
58 named @code{static_assert}, and C++11 has a similar
59 @code{static_assert} builtin. These builtins and macros differ
60 from @code{verify} in two major ways. First, they can also be used
61 within a @code{struct} or @code{union} specifier, in place of an
62 ordinary member declaration. Second, they require the programmer to
63 specify a compile-time diagnostic as a string literal.
65 The @file{verify.h} header defines one more macro, @code{assume
66 (@var{E})}. This macro expands to an expression of type @code{void}
67 that causes the compiler to assume that the expression @var{E} yields
68 a nonzero value. @var{E} should be of a scalar type, and should not
69 have side effects; it may or may not be evaluated. The behavior is
70 undefined if @var{E} would yield zero. The main use of @code{assume}
71 is optimization, as the compiler may be able to generate better code
72 if it knows that @var{E} is true.
74 Here are some example uses of @code{verify} and @code{verify_expr}.
82 /* Verify that time_t is an integer type. */
83 verify ((time_t) 1.5 == 1);
85 /* Verify that time_t is no smaller than int. */
86 verify (sizeof (int) <= sizeof (time_t));
88 /* Verify that time_t is signed. */
89 verify ((time_t) -1 < 0);
91 /* Verify that time_t uses two's complement representation. */
92 verify (~ (time_t) -1 == 0);
94 /* Return the maximum value of the integer type T,
95 verifying that T is an unsigned integer type.
96 The cast to (T) is outside the call to verify_expr
97 so that the result is of type T
98 even when T is narrower than unsigned int. */
99 #define MAX_UNSIGNED_VAL(t) \
100 ((T) verify_expr (0 < (T) -1, -1))
102 /* Return T divided by UCHAR_MAX + 1. Behavior is undefined
103 if T is negative, and in the typical case where UCHAR_MAX
104 is 255 the compiler can therefore implement the division
105 by shifting T right 8 bits, an optimization that would
106 not be valid if T were negative. */
108 time_index (time_t t)
111 return t / (UCHAR_MAX + 1);