home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 8 / FreshFishVol8-CD1.bin / gnu / info / cpp.info-2 (.txt) < prev    next >
GNU Info File  |  1994-12-22  |  40KB  |  729 lines
  1. This is Info file cpp.info, produced by Makeinfo-1.55 from the input
  2. file cpp.texi.
  3.    This file documents the GNU C Preprocessor.
  4.    Copyright 1987, 1989, 1991, 1992, 1993, 1994 Free Software
  5. Foundation, Inc.
  6.    Permission is granted to make and distribute verbatim copies of this
  7. manual provided the copyright notice and this permission notice are
  8. preserved on all copies.
  9.    Permission is granted to copy and distribute modified versions of
  10. this manual under the conditions for verbatim copying, provided also
  11. that the entire resulting derived work is distributed under the terms
  12. of a permission notice identical to this one.
  13.    Permission is granted to copy and distribute translations of this
  14. manual into another language, under the above conditions for modified
  15. versions.
  16. File: cpp.info,  Node: Macro Parentheses,  Next: Swallow Semicolon,  Prev: Misnesting,  Up: Macro Pitfalls
  17. Unintended Grouping of Arithmetic
  18. .................................
  19.    You may have noticed that in most of the macro definition examples
  20. shown above, each occurrence of a macro argument name had parentheses
  21. around it.  In addition, another pair of parentheses usually surround
  22. the entire macro definition.  Here is why it is best to write macros
  23. that way.
  24.    Suppose you define a macro as follows,
  25.      #define ceil_div(x, y) (x + y - 1) / y
  26. whose purpose is to divide, rounding up.  (One use for this operation is
  27. to compute how many `int' objects are needed to hold a certain number
  28. of `char' objects.)  Then suppose it is used as follows:
  29.      a = ceil_div (b & c, sizeof (int));
  30. This expands into
  31.      a = (b & c + sizeof (int) - 1) / sizeof (int);
  32. which does not do what is intended.  The operator-precedence rules of C
  33. make it equivalent to this:
  34.      a = (b & (c + sizeof (int) - 1)) / sizeof (int);
  35. But what we want is this:
  36.      a = ((b & c) + sizeof (int) - 1)) / sizeof (int);
  37. Defining the macro as
  38.      #define ceil_div(x, y) ((x) + (y) - 1) / (y)
  39. provides the desired result.
  40.    However, unintended grouping can result in another way.  Consider
  41. `sizeof ceil_div(1, 2)'.  That has the appearance of a C expression
  42. that would compute the size of the type of `ceil_div (1, 2)', but in
  43. fact it means something very different.  Here is what it expands to:
  44.      sizeof ((1) + (2) - 1) / (2)
  45. This would take the size of an integer and divide it by two.  The
  46. precedence rules have put the division outside the `sizeof' when it was
  47. intended to be inside.
  48.    Parentheses around the entire macro definition can prevent such
  49. problems.  Here, then, is the recommended way to define `ceil_div':
  50.      #define ceil_div(x, y) (((x) + (y) - 1) / (y))
  51. File: cpp.info,  Node: Swallow Semicolon,  Next: Side Effects,  Prev: Macro Parentheses,  Up: Macro Pitfalls
  52. Swallowing the Semicolon
  53. ........................
  54.    Often it is desirable to define a macro that expands into a compound
  55. statement.  Consider, for example, the following macro, that advances a
  56. pointer (the argument `p' says where to find it) across whitespace
  57. characters:
  58.      #define SKIP_SPACES (p, limit)  \
  59.      { register char *lim = (limit); \
  60.        while (p != lim) {            \
  61.          if (*p++ != ' ') {          \
  62.            p--; break; }}}
  63. Here Backslash-Newline is used to split the macro definition, which must
  64. be a single line, so that it resembles the way such C code would be
  65. laid out if not part of a macro definition.
  66.    A call to this macro might be `SKIP_SPACES (p, lim)'.  Strictly
  67. speaking, the call expands to a compound statement, which is a complete
  68. statement with no need for a semicolon to end it.  But it looks like a
  69. function call.  So it minimizes confusion if you can use it like a
  70. function call, writing a semicolon afterward, as in `SKIP_SPACES (p,
  71. lim);'
  72.    But this can cause trouble before `else' statements, because the
  73. semicolon is actually a null statement.  Suppose you write
  74.      if (*p != 0)
  75.        SKIP_SPACES (p, lim);
  76.      else ...
  77. The presence of two statements--the compound statement and a null
  78. statement--in between the `if' condition and the `else' makes invalid C
  79. code.
  80.    The definition of the macro `SKIP_SPACES' can be altered to solve
  81. this problem, using a `do ... while' statement.  Here is how:
  82.      #define SKIP_SPACES (p, limit)     \
  83.      do { register char *lim = (limit); \
  84.           while (p != lim) {            \
  85.             if (*p++ != ' ') {          \
  86.               p--; break; }}}           \
  87.      while (0)
  88.    Now `SKIP_SPACES (p, lim);' expands into
  89.      do {...} while (0);
  90. which is one statement.
  91. File: cpp.info,  Node: Side Effects,  Next: Self-Reference,  Prev: Swallow Semicolon,  Up: Macro Pitfalls
  92. Duplication of Side Effects
  93. ...........................
  94.    Many C programs define a macro `min', for "minimum", like this:
  95.      #define min(X, Y)  ((X) < (Y) ? (X) : (Y))
  96.    When you use this macro with an argument containing a side effect,
  97. as shown here,
  98.      next = min (x + y, foo (z));
  99. it expands as follows:
  100.      next = ((x + y) < (foo (z)) ? (x + y) : (foo (z)));
  101. where `x + y' has been substituted for `X' and `foo (z)' for `Y'.
  102.    The function `foo' is used only once in the statement as it appears
  103. in the program, but the expression `foo (z)' has been substituted twice
  104. into the macro expansion.  As a result, `foo' might be called two times
  105. when the statement is executed.  If it has side effects or if it takes
  106. a long time to compute, the results might not be what you intended.  We
  107. say that `min' is an "unsafe" macro.
  108.    The best solution to this problem is to define `min' in a way that
  109. computes the value of `foo (z)' only once.  The C language offers no
  110. standard way to do this, but it can be done with GNU C extensions as
  111. follows:
  112.      #define min(X, Y)                     \
  113.      ({ typeof (X) __x = (X), __y = (Y);   \
  114.         (__x < __y) ? __x : __y; })
  115.    If you do not wish to use GNU C extensions, the only solution is to
  116. be careful when *using* the macro `min'.  For example, you can
  117. calculate the value of `foo (z)', save it in a variable, and use that
  118. variable in `min':
  119.      #define min(X, Y)  ((X) < (Y) ? (X) : (Y))
  120.      ...
  121.      {
  122.        int tem = foo (z);
  123.        next = min (x + y, tem);
  124.      }
  125. (where we assume that `foo' returns type `int').
  126. File: cpp.info,  Node: Self-Reference,  Next: Argument Prescan,  Prev: Side Effects,  Up: Macro Pitfalls
  127. Self-Referential Macros
  128. .......................
  129.    A "self-referential" macro is one whose name appears in its
  130. definition.  A special feature of ANSI Standard C is that the
  131. self-reference is not considered a macro call.  It is passed into the
  132. preprocessor output unchanged.
  133.    Let's consider an example:
  134.      #define foo (4 + foo)
  135. where `foo' is also a variable in your program.
  136.    Following the ordinary rules, each reference to `foo' will expand
  137. into `(4 + foo)'; then this will be rescanned and will expand into `(4
  138. + (4 + foo))'; and so on until it causes a fatal error (memory full) in
  139. the preprocessor.
  140.    However, the special rule about self-reference cuts this process
  141. short after one step, at `(4 + foo)'.  Therefore, this macro definition
  142. has the possibly useful effect of causing the program to add 4 to the
  143. value of `foo' wherever `foo' is referred to.
  144.    In most cases, it is a bad idea to take advantage of this feature.  A
  145. person reading the program who sees that `foo' is a variable will not
  146. expect that it is a macro as well.  The reader will come across the
  147. identifier `foo' in the program and think its value should be that of
  148. the variable `foo', whereas in fact the value is four greater.
  149.    The special rule for self-reference applies also to "indirect"
  150. self-reference.  This is the case where a macro X expands to use a
  151. macro `y', and the expansion of `y' refers to the macro `x'.  The
  152. resulting reference to `x' comes indirectly from the expansion of `x',
  153. so it is a self-reference and is not further expanded.  Thus, after
  154.      #define x (4 + y)
  155.      #define y (2 * x)
  156. `x' would expand into `(4 + (2 * x))'.  Clear?
  157.    But suppose `y' is used elsewhere, not from the definition of `x'.
  158. Then the use of `x' in the expansion of `y' is not a self-reference
  159. because `x' is not "in progress".  So it does expand.  However, the
  160. expansion of `x' contains a reference to `y'