doc/intprops.texi

   1 @node Integer Properties
   2 @section Integer Properties
   3
   4 @c Copyright (C) 2011--2021 Free Software Foundation, Inc.
   5
   6 @c Permission is granted to copy, distribute and/or modify this document
   7 @c under the terms of the GNU Free Documentation License, Version 1.3 or
   8 @c any later version published by the Free Software Foundation; with no
   9 @c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
  10 @c copy of the license is at <https://www.gnu.org/licenses/fdl-1.3.en.html>.
  11
  12 @c Written by Paul Eggert.
  13
  14 @cindex integer properties
  15
  16 The @code{intprops} module consists of an include file @code{<intprops.h>}
  17 that defines several macros useful for testing properties of integer
  18 types.
  19
  20 @cindex integer overflow
  21 @cindex overflow, integer
  22
  23 Integer overflow is a common source of problems in programs written in
  24 C and other languages.  In some cases, such as signed integer
  25 arithmetic in C programs, the resulting behavior is undefined, and
  26 practical platforms do not always behave as if integers wrap around
  27 reliably.  In other cases, such as unsigned integer arithmetic in C,
  28 the resulting behavior is well-defined, but programs may still
  29 misbehave badly after overflow occurs.
  30
  31 Many techniques have been proposed to attack these problems.  These
  32 include precondition testing, wraparound behavior where signed integer
  33 arithmetic is guaranteed to be modular, saturation semantics where
  34 overflow reliably yields an extreme value, undefined behavior
  35 sanitizers where overflow is guaranteed to trap, and various static
  36 analysis techniques.
  37
  38 Gnulib supports wraparound arithmetic and precondition testing, as
  39 these are relatively easy to support portably and efficiently.  There
  40 are two families of precondition tests: the first, for integer types,
  41 is easier to use, while the second, for integer ranges, has a simple
  42 and straightforward portable implementation.
  43
  44 Like other Gnulib modules, the implementation of the @code{intprops}
  45 module assumes that integers use a two's complement representation,
  46 but it does not assume that signed integer arithmetic wraps around.
  47 @xref{Other portability assumptions}.
  48
  49 @menu
  50 * Arithmetic Type Properties::  Determining properties of arithmetic types.
  51 * Integer Bounds::              Bounds on integer values and representations.
  52 * Checking Integer Overflow::   Checking for overflow while computing integers.
  53 * Wraparound Arithmetic::       Well-defined behavior on integer overflow.
  54 * Integer Type Overflow::       General integer overflow checking.
  55 * Integer Range Overflow::      Integer overflow checking if bounds are known.
  56 @end menu
  57
  58 @node Arithmetic Type Properties
  59 @subsection Arithmetic Type Properties
  60
  61 @findex TYPE_IS_INTEGER
  62 @code{TYPE_IS_INTEGER (@var{t})} is an arithmetic constant
  63 expression that is 1 if the arithmetic type @var{t} is an integer type.
  64 @code{_Bool} counts as an integer type.
  65
  66 @findex TYPE_SIGNED
  67 @code{TYPE_SIGNED (@var{t})} is an arithmetic constant expression
  68 that is 1 if the real type @var{t} is a signed integer type or a
  69 floating type.  If @var{t} is an integer type, @code{TYPE_SIGNED (@var{t})}
  70 is an integer constant expression.
  71
  72 @findex EXPR_SIGNED
  73 @code{EXPR_SIGNED (@var{e})} is 1 if the real expression @var{e}
  74 has a signed integer type or a floating type.  If @var{e} is an
  75 integer constant expression or an arithmetic constant expression,
  76 @code{EXPR_SIGNED (@var{e})} is likewise.  The expression
  77 @var{e} is not evaluated, and @code{EXPR_SIGNED
  78 (@var{e})} is typically optimized to a constant.
  79
  80 Example usage:
  81
  82 @example
  83 #include <intprops.h>
  84 #include <time.h>
  85
  86 enum
  87 @{
  88   time_t_is_signed_integer =
  89     TYPE_IS_INTEGER (time_t) && TYPE_SIGNED (time_t)
  90 @};
  91
  92 int
  93 CLOCKS_PER_SEC_is_signed (void)
  94 @{
  95   return EXPR_SIGNED (CLOCKS_PER_SEC);
  96 @}
  97 @end example
  98
  99 @node Integer Bounds
 100 @subsection Integer Bounds
 101
 102 @cindex integer bounds
 103
 104 @findex INT_BUFSIZE_BOUND
 105 @code{INT_BUFSIZE_BOUND (@var{t})} is an integer constant
 106 expression that is a bound on the size of the string representing an
 107 integer type or expression @var{t} in decimal notation, including the
 108 terminating null character and any leading @code{-} character.  For
 109 example, if @code{INT_BUFSIZE_BOUND (int)} is 12, any value of type
 110 @code{int} can be represented in 12 bytes or less, including the
 111 terminating null.  The bound is not necessarily tight.
 112
 113 Example usage:
 114
 115 @example
 116 #include <intprops.h>
 117 #include <stdio.h>
 118 int
 119 int_strlen (int i)
 120 @{
 121   char buf[INT_BUFSIZE_BOUND (int)];
 122   return sprintf (buf, "%d", i);
 123 @}
 124 @end example
 125
 126 @findex INT_STRLEN_BOUND
 127 @code{INT_STRLEN_BOUND (@var{t})} is an integer constant
 128 expression that is a bound on the length of the string representing an
 129 integer type or expression @var{t} in decimal notation, including any
 130 leading @code{-} character.  This is one less than
 131 @code{INT_BUFSIZE_BOUND (@var{t})}.
 132
 133 @findex TYPE_MINIMUM
 134 @findex TYPE_MAXIMUM
 135 @code{TYPE_MINIMUM (@var{t})} and @code{TYPE_MAXIMUM (@var{t})} are
 136 integer constant expressions equal to the minimum and maximum
 137 values of the integer type @var{t}.  These expressions are of the type
 138 @var{t} (or more precisely, the type @var{t} after integer
 139 promotions).
 140
 141 Example usage:
 142
 143 @example
 144 #include <stdint.h>
 145 #include <sys/types.h>
 146 #include <intprops.h>
 147 int
 148 in_off_t_range (intmax_t a)
 149 @{
 150   return TYPE_MINIMUM (off_t) <= a && a <= TYPE_MAXIMUM (off_t);
 151 @}
 152 @end example
 153
 154 @node Checking Integer Overflow
 155 @subsection Checking Integer Overflow
 156
 157 @cindex integer overflow checking
 158
 159 Signed integer arithmetic has undefined behavior on overflow in C@.
 160 Although almost all modern computers use two's complement signed
 161 arithmetic that is well-defined to wrap around, C compilers routinely
 162 optimize assuming that signed integer overflow cannot occur, which
 163 means that a C program cannot easily get at the underlying machine
 164 arithmetic.  For example:
 165
 166 @example
 167 if ((a + b < b) == (a < 0))
 168   a += b;
 169 else
 170   printf ("overflow\n");
 171 @end example
 172
 173 @noindent
 174 might not work as expected if @code{a} and @code{b} are signed,
 175 because a compiler can assume that signed overflow cannot occur and
 176 treat the entire @code{if} expression as if it were true.  And even if
 177 @code{a} is unsigned, the expression might not work as expected if
 178 @code{b} is negative or is wider than @code{a}.
 179
 180 The following macros work around this problem by returning an overflow
 181 indication while computing the sum, difference, or product of two
 182 integers.  For example, if @code{i} is of type @code{int},
 183 @code{INT_ADD_OK (INT_MAX - 1, 1, &i)} sets @code{i} to
 184 @code{INT_MAX} and returns true, whereas @code{INT_ADD_OK (INT_MAX, 1,
 185 &i)} returns false.
 186
 187 Example usage:
 188
 189 @example
 190 #include <intprops.h>
 191 #include <stdio.h>
 192
 193 /* Compute A * B, reporting whether overflow occurred.  */
 194 void
 195 print_product (long int a, long int b)
 196 @{
 197   long int r;
 198   if (INT_MULTIPLY_OK (a, b, r))
 199     printf ("result is %ld\n", r);
 200   else
 201     printf ("overflow\n");
 202 @}
 203 @end example
 204
 205 These macros work for both signed and unsigned integers, so they can
 206 be used with integer types like @code{time_t} that may or may not be
 207 signed, depending on the platform.
 208
 209 These macros have the following restrictions:
 210
 211 @itemize @bullet
 212 @item
 213 Their first two arguments must be integer expressions.
 214
 215 @item
 216 Their last argument must be a non-null pointer to an integer.
 217
 218 @item
 219 They may evaluate their arguments zero or multiple times, so the
 220 arguments should not have side effects.
 221
 222 @item
 223 They are not necessarily constant expressions, even if all their
 224 arguments are constant expressions.
 225 @end itemize
 226
 227 @table @code
 228 @item INT_ADD_OK (@var{a}, @var{b}, @var{r})
 229 @findex INT_ADD_OK
 230 Compute the sum of @var{a} and @var{b}.  If it fits into
 231 @code{*@var{r}}, store it there and return true.  Otherwise return
 232 false, possibly modifying @code{*@var{r}} to an unspecified value.
 233 See above for restrictions.
 234
 235 @item INT_SUBTRACT_OK (@var{a}, @var{b}, @var{r})
 236 @findex INT_SUBTRACT_OK
 237 Compute the difference between @var{a} and @var{b}.  If it fits into
 238 @code{*@var{r}}, store it there and return true.  Otherwise return
 239 false, possibly modifying @code{*@var{r}} to an unspecified value.
 240 See above for restrictions.
 241
 242 @item INT_MULTIPLY_OK (@var{a}, @var{b}, @var{r})
 243 @findex INT_MULTIPLY_OK
 244 Compute the product of @var{a} and @var{b}.  If it fits into
 245 @code{*@var{r}}, store it there and return true.  Otherwise return
 246 false, possibly modifying @code{*@var{r}} to an unspecified value.
 247 See above for restrictions.
 248 @end table
 249
 250 Other macros are available if you need wrapped-around results when
 251 overflow occurs (@pxref{Wraparound Arithmetic}), or if you need to
 252 check for overflow in operations other than addition, subtraction, and
 253 multiplication (@pxref{Integer Type Overflow}).
 254
 255 @node Wraparound Arithmetic
 256 @subsection Wraparound Arithmetic with Integers
 257
 258 @cindex wraparound integer arithmetic
 259
 260 Signed integer arithmetic has undefined behavior on overflow in C@.
 261 Although almost all modern computers use two's complement signed
 262 arithmetic that is well-defined to wrap around, C compilers routinely
 263 optimize assuming that signed integer overflow cannot occur, which
 264 means that a C program cannot easily get at the underlying machine
 265 arithmetic.  For example, on a typical machine with 32-bit two's
 266 complement @code{int} the expression @code{INT_MAX + 1} does not
 267 necessarily yield @code{INT_MIN}, because the compiler may do
 268 calculations with a 64-bit register, or may generate code that
 269 traps on signed integer overflow.
 270
 271 The following macros work around this problem by storing the
 272 wraparound value, i.e., the low-order bits of the correct answer, and
 273 by returning an overflow indication.  For example, if @code{i} is of
 274 type @code{int}, @code{INT_ADD_WRAPV (INT_MAX, 1, &i)} sets @code{i}
 275 to @code{INT_MIN} and returns 1 on a two's complement machine.
 276 @xref{Integer Type Overflow}.
 277
 278 Example usage:
 279
 280 @example
 281 #include <intprops.h>
 282 #include <stdio.h>
 283
 284 /* Print the low order bits of A * B,
 285    reporting whether overflow occurred.  */
 286 void
 287 print_product (long int a, long int b)
 288 @{
 289   long int r;
 290   int overflow = INT_MULTIPLY_WRAPV (a, b, &r);
 291   printf ("result is %ld (%s)\n", r,
 292           (overflow
 293            ? "after overflow"
 294            : "no overflow"));
 295 @}
 296 @end example
 297
 298 These macros work for both signed and unsigned integers, so they can
 299 be used with integer types like @code{time_t} that may or may not be
 300 signed, depending on the platform.
 301
 302 These macros have the following restrictions:
 303
 304 @itemize @bullet
 305 @item
 306 Their first two arguments must be integer expressions.
 307
 308 @item
 309 Their last argument must be a non-null pointer to an integer.
 310
 311 @item
 312 They may evaluate their arguments zero or multiple times, so the
 313 arguments should not have side effects.
 314
 315 @item
 316 They are not necessarily constant expressions, even if all their
 317 arguments are constant expressions.
 318 @end itemize
 319
 320 @table @code
 321 @item INT_ADD_WRAPV (@var{a}, @var{b}, @var{r})
 322 @findex INT_ADD_WRAPV
 323 Store the low-order bits of the sum of @var{a} and @var{b} into
 324 @code{*@var{r}}.  Return true if overflow occurred, false if the
 325 low-order bits are the mathematically-correct sum.  See above for
 326 restrictions.
 327
 328 @item INT_SUBTRACT_WRAPV (@var{a}, @var{b}, @var{r})
 329 @findex INT_SUBTRACT_WRAPV
 330 Store the low-order bits of the difference between @var{a} and @var{b}
 331 into @code{*@var{r}}.  Return true if overflow occurred, false if the
 332 low-order bits are the mathematically-correct difference.  See above
 333 for restrictions.
 334
 335 @item INT_MULTIPLY_WRAPV (@var{a}, @var{b}, @var{r})
 336 @findex INT_MULTIPLY_WRAPV
 337 Store the low-order bits of the product of @var{a} and @var{b} into
 338 @code{*@var{r}}.  Return true if overflow occurred, false if the
 339 low-order bits are the mathematically-correct product.  See above for
 340 restrictions.
 341 @end table
 342
 343 Other macros are available if you do not need wrapped-around results
 344 when overflow occurs (@pxref{Checking Integer Overflow}), or if you
 345 need to check for overflow in operations other than addition,
 346 subtraction, and multiplication (@pxref{Integer Type Overflow}).
 347
 348 @node Integer Type Overflow
 349 @subsection Integer Type Overflow
 350
 351 @cindex integer type overflow
 352 @cindex overflow, integer type
 353
 354 Although unsigned integer arithmetic wraps around modulo a power of
 355 two, signed integer arithmetic has undefined behavior on overflow in
 356 C@.  Almost all modern computers use two's complement signed
 357 arithmetic that is well-defined to wrap around, but C compilers
 358 routinely optimize based on the assumption that signed integer
 359 overflow cannot occur, which means that a C program cannot easily get
 360 at the underlying machine behavior.  For example, the signed integer
 361 expression @code{(a + b < b) != (a < 0)} is not a reliable test for
 362 whether @code{a + b} overflows, because a compiler can assume that
 363 signed overflow cannot occur and treat the entire expression as if it
 364 were false.
 365
 366 These macros yield 1 if the corresponding C operators might not yield
 367 numerically correct answers due to arithmetic overflow of an integer
 368 type.  They work correctly on all known practical hosts, and do not
 369 rely on undefined behavior due to signed arithmetic overflow.  They
 370 are integer constant expressions if their arguments are.  They
 371 are typically easier to use than the integer range overflow macros
 372 (@pxref{Integer Range Overflow}), and they support more operations and
 373 evaluation contexts than the wraparound macros (@pxref{Wraparound
 374 Arithmetic}).
 375
 376 Example usage:
 377
 378 @example
 379 #include <intprops.h>
 380 #include <limits.h>
 381 #include <stdio.h>
 382
 383 /* Print A * B if in range, an overflow
 384    indicator otherwise.  */
 385 void
 386 print_product (long int a, long int b)
 387 @{
 388   if (INT_MULTIPLY_OVERFLOW (a, b))
 389     printf ("multiply would overflow");
 390   else
 391     printf ("product is %ld", a * b);
 392 @}
 393
 394 /* Does the product of two ints always fit
 395    in a long int?  */
 396 enum @{
 397   INT_PRODUCTS_FIT_IN_LONG
 398     = ! (INT_MULTIPLY_OVERFLOW
 399          ((long int) INT_MIN, INT_MIN))
 400 @};
 401 @end example
 402
 403 @noindent
 404 These macros have the following restrictions:
 405
 406 @itemize @bullet
 407 @item
 408 Their arguments must be integer expressions.
 409
 410 @item
 411 They may evaluate their arguments zero or multiple times, so the
 412 arguments should not have side effects.
 413 @end itemize
 414
 415 @noindent
 416 These macros are tuned for their last argument being a constant.
 417
 418 @table @code
 419 @item INT_ADD_OVERFLOW (@var{a}, @var{b})
 420 @findex INT_ADD_OVERFLOW
 421 Yield 1 if @code{@var{a} + @var{b}} would overflow.  See above for
 422 restrictions.
 423
 424 @item INT_SUBTRACT_OVERFLOW (@var{a}, @var{b})
 425 @findex INT_SUBTRACT_OVERFLOW
 426 Yield 1 if @code{@var{a} - @var{b}} would overflow.  See above for
 427 restrictions.
 428
 429 @item INT_NEGATE_OVERFLOW (@var{a})
 430 @findex INT_NEGATE_OVERFLOW
 431 Yields 1 if @code{-@var{a}} would overflow.  See above for restrictions.
 432
 433 @item INT_MULTIPLY_OVERFLOW (@var{a}, @var{b})
 434 @findex INT_MULTIPLY_OVERFLOW
 435 Yield 1 if @code{@var{a} * @var{b}} would overflow.  See above for
 436 restrictions.
 437
 438 @item INT_DIVIDE_OVERFLOW (@var{a}, @var{b})
 439 @findex INT_DIVIDE_OVERFLOW
 440 Yields 1 if @code{@var{a} / @var{b}} would overflow.  See above for
 441 restrictions.  Division overflow can happen on two's complement hosts
 442 when dividing the most negative integer by @minus{}1.  This macro does
 443 not check for division by zero.
 444
 445 @item INT_REMAINDER_OVERFLOW (@var{a}, @var{b})
 446 @findex INT_REMAINDER_OVERFLOW
 447 Yield 1 if @code{@var{a} % @var{b}} would overflow.  See above for
 448 restrictions.  Remainder overflow can happen on two's complement hosts
 449 when dividing the most negative integer by @minus{}1; although the
 450 mathematical result is always 0, in practice some implementations
 451 trap, so this counts as an overflow.  This macro does not check for
 452 division by zero.
 453
 454 @item INT_LEFT_SHIFT_OVERFLOW (@var{a}, @var{b})
 455 @findex INT_LEFT_SHIFT_OVERFLOW
 456 Yield 1 if @code{@var{a} << @var{b}} would overflow.  See above for
 457 restrictions.  The C standard says that behavior is undefined for
 458 shifts unless 0@leq{}@var{b}<@var{w} where @var{w} is @var{a}'s word
 459 width, and that when @var{a} is negative then @code{@var{a} <<
 460 @var{b}} has undefined behavior, but this macro does not check these
 461 other restrictions.
 462 @end table
 463
 464 @node Integer Range Overflow
 465 @subsection Integer Range Overflow
 466
 467 @cindex integer range overflow
 468 @cindex overflow, integer range
 469
 470 These macros yield 1 if the corresponding C operators might not yield
 471 numerically correct answers due to arithmetic overflow.  They do not
 472 rely on undefined or implementation-defined behavior.  They are
 473 integer constant expressions if their arguments are.  Their
 474 implementations are simple and straightforward, but they are typically
 475 harder to use than the integer type overflow macros.  @xref{Integer
 476 Type Overflow}.
 477
 478 Although the implementation of these macros is similar to that
 479 suggested in the SEI CERT C Secure Coding Standard,
 480 in its two sections
 481 ``@url{https://www.securecoding.cert.org/confluence/display/c/INT30-C.+Ensure+that+unsigned+integer+operations+do+not+wrap,
 482 INT30-C@. Ensure that unsigned integer operations do not wrap}'' and
 483 ``@url{https://www.securecoding.cert.org/confluence/display/c/INT32-C.+Ensure+that+operations+on+signed+integers+do+not+result+in+overflow,
 484 INT32-C@. Ensure that operations on signed integers do not result in
 485 overflow}'', Gnulib's implementation was derived independently of
 486 CERT's suggestions.
 487
 488 Example usage:
 489
 490 @example
 491 #include <intprops.h>
 492 #include <limits.h>
 493 #include <stdio.h>
 494
 495 void
 496 print_product (long int a, long int b)
 497 @{
 498   if (INT_MULTIPLY_RANGE_OVERFLOW (a, b, LONG_MIN, LONG_MAX))
 499     printf ("multiply would overflow");
 500   else
 501     printf ("product is %ld", a * b);
 502 @}
 503
 504 /* Does the product of two ints always fit
 505    in a long int?  */
 506 enum @{
 507   INT_PRODUCTS_FIT_IN_LONG
 508     = ! (INT_MULTIPLY_RANGE_OVERFLOW
 509          ((long int) INT_MIN, (long int) INT_MIN,
 510           LONG_MIN, LONG_MAX))
 511 @};
 512 @end example
 513
 514 @noindent
 515 These macros have the following restrictions:
 516
 517 @itemize @bullet
 518 @item
 519 Their arguments must be integer expressions.
 520
 521 @item
 522 They may evaluate their arguments zero or multiple times, so
 523 the arguments should not have side effects.
 524
 525 @item
 526 The arithmetic arguments (including the @var{min} and @var{max}
 527 arguments) must be of the same integer type after the usual arithmetic
 528 conversions, and the type must have minimum value @var{min} and
 529 maximum @var{max}.  Unsigned values should use a zero @var{min} of the
 530 proper type, for example, @code{(unsigned int) 0}.
 531 @end itemize
 532
 533 @noindent
 534 These macros are tuned for constant @var{min} and @var{max}.  For
 535 commutative operations such as @code{@var{a} + @var{b}}, they are also
 536 tuned for constant @var{b}.
 537
 538 @table @code
 539 @item INT_ADD_RANGE_OVERFLOW (@var{a}, @var{b}, @var{min}, @var{max})
 540 @findex INT_ADD_RANGE_OVERFLOW
 541 Yield 1 if @code{@var{a} + @var{b}} would overflow in
 542 [@var{min},@var{max}] integer arithmetic.  See above for restrictions.
 543
 544 @item INT_SUBTRACT_RANGE_OVERFLOW (@var{a}, @var{b}, @var{min}, @var{max})
 545 @findex INT_SUBTRACT_RANGE_OVERFLOW
 546 Yield 1 if @code{@var{a} - @var{b}} would overflow in
 547 [@var{min},@var{max}] integer arithmetic.  See above for restrictions.
 548
 549 @item INT_NEGATE_RANGE_OVERFLOW (@var{a}, @var{min}, @var{max})
 550 @findex INT_NEGATE_RANGE_OVERFLOW
 551 Yield 1 if @code{-@var{a}} would overflow in [@var{min},@var{max}]
 552 integer arithmetic.  See above for restrictions.
 553
 554 @item INT_MULTIPLY_RANGE_OVERFLOW (@var{a}, @var{b}, @var{min}, @var{max})
 555 @findex INT_MULTIPLY_RANGE_OVERFLOW
 556 Yield 1 if @code{@var{a} * @var{b}} would overflow in
 557 [@var{min},@var{max}] integer arithmetic.  See above for restrictions.
 558
 559 @item INT_DIVIDE_RANGE_OVERFLOW (@var{a}, @var{b}, @var{min}, @var{max})
 560 @findex INT_DIVIDE_RANGE_OVERFLOW
 561 Yield 1 if @code{@var{a} / @var{b}} would overflow in
 562 [@var{min},@var{max}] integer arithmetic.  See above for restrictions.
 563 Division overflow can happen on two's complement hosts when dividing
 564 the most negative integer by @minus{}1.  This macro does not check for
 565 division by zero.
 566
 567 @item INT_REMAINDER_RANGE_OVERFLOW (@var{a}, @var{b}, @var{min}, @var{max})
 568 @findex INT_REMAINDER_RANGE_OVERFLOW
 569 Yield 1 if @code{@var{a} % @var{b}} would overflow in
 570 [@var{min},@var{max}] integer arithmetic.  See above for restrictions.
 571 Remainder overflow can happen on two's complement hosts when dividing
 572 the most negative integer by @minus{}1; although the mathematical
 573 result is always 0, in practice some implementations trap, so this
 574 counts as an overflow.  This macro does not check for division by
 575 zero.
 576
 577 @item INT_LEFT_SHIFT_RANGE_OVERFLOW (@var{a}, @var{b}, @var{min}, @var{max})
 578 @findex INT_LEFT_SHIFT_RANGE_OVERFLOW
 579 Yield 1 if @code{@var{a} << @var{b}} would overflow in
 580 [@var{min},@var{max}] integer arithmetic.  See above for restrictions.
 581 Here, @var{min} and @var{max} are for @var{a} only, and @var{b} need
 582 not be of the same type as the other arguments.  The C standard says
 583 that behavior is undefined for shifts unless 0@leq{}@var{b}<@var{w}
 584 where @var{w} is @var{a}'s word width, and that when @var{a} is negative
 585 then @code{@var{a} << @var{b}} has undefined behavior, but this macro
 586 does not check these other restrictions.
 587 @end table