diff options
Diffstat (limited to 'gcc/doc/cpp.texi')
-rw-r--r-- | gcc/doc/cpp.texi | 402 |
1 files changed, 201 insertions, 201 deletions
diff --git a/gcc/doc/cpp.texi b/gcc/doc/cpp.texi index 0ab1b3203ec..89e30660b45 100644 --- a/gcc/doc/cpp.texi +++ b/gcc/doc/cpp.texi @@ -9,7 +9,7 @@ @copying @c man begin COPYRIGHT Copyright @copyright{} 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, -1997, 1998, 1999, 2000, 2001, 2002, 2003 +1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document @@ -351,10 +351,10 @@ do not recognize these idioms. The nine trigraphs and their replacements are -@example +@smallexample Trigraph: ??( ??) ??< ??> ??= ??/ ??' ??! ??- Replacement: [ ] @{ @} # \ ^ | ~ -@end example +@end smallexample @item @cindex continued lines @@ -385,23 +385,23 @@ There are two kinds of comments. @dfn{Block comments} begin with @samp{/*} and continue until the next @samp{*/}. Block comments do not nest: -@example +@smallexample /* @r{this is} /* @r{one comment} */ @r{text outside comment} -@end example +@end smallexample @dfn{Line comments} begin with @samp{//} and continue to the end of the current line. Line comments do not nest either, but it does not matter, because they would end in the same place anyway. -@example +@smallexample // @r{this is} // @r{one comment} @r{text outside comment} -@end example +@end smallexample @end enumerate It is safe to put line comments inside block comments, or vice versa. -@example +@smallexample @group /* @r{block comment} // @r{contains line comment} @@ -410,17 +410,17 @@ It is safe to put line comments inside block comments, or vice versa. // @r{line comment} /* @r{contains block comment} */ @end group -@end example +@end smallexample But beware of commenting out one end of a block comment with a line comment. -@example +@smallexample @group // @r{l.c.} /* @r{block comment begins} @r{oops! this isn't a comment anymore} */ @end group -@end example +@end smallexample Comments are not recognized within string literals. @t{@w{"/* blah */"}} is the string constant @samp{@w{/* blah */}}, not @@ -437,7 +437,7 @@ next line with backslash-newline. You can even split @samp{/*}, @samp{*/}, and @samp{//} onto multiple lines with backslash-newline. For example: -@example +@smallexample @group /\ * @@ -447,7 +447,7 @@ ne FO\ O 10\ 20 @end group -@end example +@end smallexample @noindent is equivalent to @code{@w{#define FOO 1020}}. All these tricks are @@ -482,7 +482,7 @@ Once the input file is broken into tokens, the token boundaries never change, except when the @samp{##} preprocessing operator is used to paste tokens together. @xref{Concatenation}. For example, -@example +@smallexample @group #define foo() bar foo()baz @@ -490,7 +490,7 @@ foo()baz @emph{not} @expansion{} barbaz @end group -@end example +@end smallexample The compiler does not re-tokenize the preprocessor's output. Each preprocessing token becomes one compiler token. @@ -590,10 +590,10 @@ punctuation in obsolete systems. It has no negative side effects, unlike trigraphs, but does not cover as much ground. The digraphs and their corresponding normal punctuators are: -@example +@smallexample Digraph: <% %> <: :> %: %:%: Punctuator: @{ @} [ ] # ## -@end example +@end smallexample @cindex other tokens Any other single character is considered ``other.'' It is passed on to @@ -613,10 +613,10 @@ silently ignored, just as any other character would be. In running text, NUL is considered white space. For example, these two directives have the same meaning. -@example +@smallexample #define X^@@1 #define X 1 -@end example +@end smallexample @noindent (where @samp{^@@} is ASCII NUL)@. Within string or character constants, @@ -791,15 +791,15 @@ file, followed by the output that comes from the text after the @samp{#include} directive. For example, if you have a header file @file{header.h} as follows, -@example +@smallexample char *test (void); -@end example +@end smallexample @noindent and a main program called @file{program.c} that uses the header file, like this, -@example +@smallexample int x; #include "header.h" @@ -808,13 +808,13 @@ main (void) @{ puts (test ()); @} -@end example +@end smallexample @noindent the compiler will see the same token stream as it would if @file{program.c} read -@example +@smallexample int x; char *test (void); @@ -823,7 +823,7 @@ main (void) @{ puts (test ()); @} -@end example +@end smallexample Included files are not limited to declarations and macro definitions; those are merely the typical uses. Any fragment of a C program can be @@ -850,12 +850,12 @@ GCC looks in several different places for headers. On a normal Unix system, if you do not instruct it otherwise, it will look for headers requested with @code{@w{#include <@var{file}>}} in: -@example +@smallexample /usr/local/include @var{libdir}/gcc/@var{target}/@var{version}/include /usr/@var{target}/include /usr/include -@end example +@end smallexample For C++ programs, it will also look in @file{/usr/include/g++-v3}, first. In the above, @var{target} is the canonical name of the system @@ -926,7 +926,7 @@ it will certainly waste time. The standard way to prevent this is to enclose the entire real contents of the file in a conditional, like this: -@example +@smallexample @group /* File foo. */ #ifndef FILE_FOO_SEEN @@ -936,7 +936,7 @@ of the file in a conditional, like this: #endif /* !FILE_FOO_SEEN */ @end group -@end example +@end smallexample This construct is commonly known as a @dfn{wrapper #ifndef}. When the header is included again, the conditional will be false, @@ -971,7 +971,7 @@ files to be included into your program. They might specify configuration parameters to be used on different sorts of operating systems, for instance. You could do this with a series of conditionals, -@example +@smallexample #if SYSTEM_1 # include "system_1.h" #elif SYSTEM_2 @@ -979,18 +979,18 @@ systems, for instance. You could do this with a series of conditionals, #elif SYSTEM_3 @dots{} #endif -@end example +@end smallexample That rapidly becomes tedious. Instead, the preprocessor offers the ability to use a macro for the header name. This is called a @dfn{computed include}. Instead of writing a header name as the direct argument of @samp{#include}, you simply put a macro name there instead: -@example +@smallexample #define SYSTEM_H "system_1.h" @dots{} #include SYSTEM_H -@end example +@end smallexample @noindent @code{SYSTEM_H} will be expanded, and the preprocessor will look for @@ -1015,10 +1015,10 @@ string constant are the file to be included. CPP does not re-examine the string for embedded quotes, but neither does it process backslash escapes in the string. Therefore -@example +@smallexample #define HEADER "a\"b" #include HEADER -@end example +@end smallexample @noindent looks for a file named @file{a\"b}. CPP searches for the file according @@ -1063,9 +1063,9 @@ header is not protected from multiple inclusion (@pxref{Once-Only Headers}), it will recurse infinitely and cause a fatal error. You could include the old header with an absolute pathname: -@example +@smallexample #include "/usr/include/old-header.h" -@end example +@end smallexample @noindent This works, but is not clean; should the system headers ever move, you would have to edit the new headers to match. @@ -1184,27 +1184,27 @@ followed by the name of the macro and then the token sequence it should be an abbreviation for, which is variously referred to as the macro's @dfn{body}, @dfn{expansion} or @dfn{replacement list}. For example, -@example +@smallexample #define BUFFER_SIZE 1024 -@end example +@end smallexample @noindent defines a macro named @code{BUFFER_SIZE} as an abbreviation for the token @code{1024}. If somewhere after this @samp{#define} directive there comes a C statement of the form -@example +@smallexample foo = (char *) malloc (BUFFER_SIZE); -@end example +@end smallexample @noindent then the C preprocessor will recognize and @dfn{expand} the macro @code{BUFFER_SIZE}. The C compiler will see the same tokens as it would if you had written -@example +@smallexample foo = (char *) malloc (1024); -@end example +@end smallexample By convention, macro names are written in uppercase. Programs are easier to read when it is possible to tell at a glance which names are @@ -1215,13 +1215,13 @@ continue the definition onto multiple lines, if necessary, using backslash-newline. When the macro is expanded, however, it will all come out on one line. For example, -@example +@smallexample #define NUMBERS 1, \ 2, \ 3 int x[] = @{ NUMBERS @}; @expansion{} int x[] = @{ 1, 2, 3 @}; -@end example +@end smallexample @noindent The most common visible consequence of this is surprising line numbers @@ -1236,25 +1236,25 @@ The C preprocessor scans your program sequentially. Macro definitions take effect at the place you write them. Therefore, the following input to the C preprocessor -@example +@smallexample foo = X; #define X 4 bar = X; -@end example +@end smallexample @noindent produces -@example +@smallexample foo = X; bar = 4; -@end example +@end smallexample When the preprocessor expands a macro name, the macro's expansion replaces the macro invocation, then the expansion is examined for more macros to expand. For example, -@example +@smallexample @group #define TABLESIZE BUFSIZE #define BUFSIZE 1024 @@ -1262,7 +1262,7 @@ TABLESIZE @expansion{} BUFSIZE @expansion{} 1024 @end group -@end example +@end smallexample @noindent @code{TABLESIZE} is expanded first to produce @code{BUFSIZE}, then that @@ -1280,12 +1280,12 @@ at some point in the source file. @code{TABLESIZE}, defined as shown, will always expand using the definition of @code{BUFSIZE} that is currently in effect: -@example +@smallexample #define BUFSIZE 1020 #define TABLESIZE BUFSIZE #undef BUFSIZE #define BUFSIZE 37 -@end example +@end smallexample @noindent Now @code{TABLESIZE} expands (in two stages) to @code{37}. @@ -1304,24 +1304,24 @@ are called @dfn{function-like macros}. To define a function-like macro, you use the same @samp{#define} directive, but you put a pair of parentheses immediately after the macro name. For example, -@example +@smallexample #define lang_init() c_init() lang_init() @expansion{} c_init() -@end example +@end smallexample A function-like macro is only expanded if its name appears with a pair of parentheses after it. If you write just the name, it is left alone. This can be useful when you have a function and a macro of the same name, and you wish to use the function sometimes. -@example +@smallexample extern void foo(void); #define foo() /* optimized inline version */ @dots{} foo(); funcptr = foo; -@end example +@end smallexample Here the call to @code{foo()} will use the macro, but the function pointer will get the address of the real function. If the macro were to @@ -1332,11 +1332,11 @@ macro definition, that does not define a function-like macro, it defines an object-like macro whose expansion happens to begin with a pair of parentheses. -@example +@smallexample #define lang_init () c_init() lang_init() @expansion{} () c_init()() -@end example +@end smallexample The first two pairs of parentheses in this expansion come from the macro. The third is the pair that was originally after the macro @@ -1368,12 +1368,12 @@ macro body.) As an example, here is a macro that computes the minimum of two numeric values, as it is defined in many C programs, and some uses. -@example +@smallexample #define min(X, Y) ((X) < (Y) ? (X) : (Y)) x = min(a, b); @expansion{} x = ((a) < (b) ? (a) : (b)); y = min(1, 2); @expansion{} y = ((1) < (2) ? (1) : (2)); z = min(a + 28, *p); @expansion{} z = ((a + 28) < (*p) ? (a + 28) : (*p)); -@end example +@end smallexample @noindent (In this small example you can already see several of the dangers of @@ -1386,9 +1386,9 @@ such parentheses does not end the argument. However, there is no requirement for square brackets or braces to balance, and they do not prevent a comma from separating arguments. Thus, -@example +@smallexample macro (array[x = y, x + 1]) -@end example +@end smallexample @noindent passes two arguments to @code{macro}: @code{array[x = y} and @code{x + @@ -1406,20 +1406,20 @@ Prescan}, for detailed discussion. For example, @code{min (min (a, b), c)} is first expanded to -@example +@smallexample min (((a) < (b) ? (a) : (b)), (c)) -@end example +@end smallexample @noindent and then to -@example +@smallexample @group ((((a) < (b) ? (a) : (b))) < (c) ? (((a) < (b) ? (a) : (b))) : (c)) @end group -@end example +@end smallexample @noindent (Line breaks shown here for clarity would not actually be generated.) @@ -1431,7 +1431,7 @@ You cannot leave out arguments entirely; if a macro takes two arguments, there must be exactly one comma at the top level of its argument list. Here are some silly examples using @code{min}: -@example +@smallexample min(, b) @expansion{} (( ) < (b) ? ( ) : (b)) min(a, ) @expansion{} ((a ) < ( ) ? (a ) : ( )) min(,) @expansion{} (( ) < ( ) ? ( ) : ( )) @@ -1439,7 +1439,7 @@ min((,),) @expansion{} (((,)) < ( ) ? ((,)) : ( )) min() @error{} macro "min" requires 2 arguments, but only 1 given min(,,) @error{} macro "min" passed 3 arguments, but takes just 2 -@end example +@end smallexample Whitespace is not a preprocessing token, so if a macro @code{foo} takes one argument, @code{@w{foo ()}} and @code{@w{foo ( )}} both supply it an @@ -1451,10 +1451,10 @@ empty argument was required. Macro parameters appearing inside string literals are not replaced by their corresponding actual arguments. -@example +@smallexample #define foo(x) x, "x" foo(bar) @expansion{} bar, "x" -@end example +@end smallexample @node Stringification @section Stringification @@ -1478,7 +1478,7 @@ long string. Here is an example of a macro definition that uses stringification: -@example +@smallexample @group #define WARN_IF(EXP) \ do @{ if (EXP) \ @@ -1488,7 +1488,7 @@ WARN_IF (x == 0); @expansion{} do @{ if (x == 0) fprintf (stderr, "Warning: " "x == 0" "\n"); @} while (0); @end group -@end example +@end smallexample @noindent The argument for @code{EXP} is substituted once, as-is, into the @@ -1521,7 +1521,7 @@ There is no way to convert a macro argument into a character constant. If you want to stringify the result of expansion of a macro argument, you have to use two levels of macros. -@example +@smallexample #define xstr(s) str(s) #define str(s) #s #define foo 4 @@ -1531,7 +1531,7 @@ xstr (foo) @expansion{} xstr (4) @expansion{} str (4) @expansion{} "4" -@end example +@end smallexample @code{s} is stringified when it is used in @code{str}, so it is not macro-expanded first. But @code{s} is an ordinary argument to @@ -1588,7 +1588,7 @@ Consider a C program that interprets named commands. There probably needs to be a table of commands, perhaps an array of structures declared as follows: -@example +@smallexample @group struct command @{ @@ -1605,7 +1605,7 @@ struct command commands[] = @dots{} @}; @end group -@end example +@end smallexample It would be cleaner not to have to give each command name twice, once in the string constant and once in the function name. A macro which takes the @@ -1613,7 +1613,7 @@ name of a command as an argument can make this unnecessary. The string constant can be created with stringification, and the function name by concatenating the argument with @samp{_command}. Here is how it is done: -@example +@smallexample #define COMMAND(NAME) @{ #NAME, NAME ## _command @} struct command commands[] = @@ -1622,7 +1622,7 @@ struct command commands[] = COMMAND (help), @dots{} @}; -@end example +@end smallexample @node Variadic Macros @section Variadic Macros @@ -1634,9 +1634,9 @@ A macro can be declared to accept a variable number of arguments much as a function can. The syntax for defining the macro is similar to that of a function. Here is an example: -@example +@smallexample #define eprintf(@dots{}) fprintf (stderr, __VA_ARGS__) -@end example +@end smallexample This kind of macro is called @dfn{variadic}. When the macro is invoked, all the tokens in its argument list after the last named argument (this @@ -1645,10 +1645,10 @@ argument}. This sequence of tokens replaces the identifier @code{@w{__VA_ARGS__}} in the macro body wherever it appears. Thus, we have this expansion: -@example +@smallexample eprintf ("%s:%d: ", input_file, lineno) @expansion{} fprintf (stderr, "%s:%d: ", input_file, lineno) -@end example +@end smallexample The variable argument is completely macro-expanded before it is inserted into the macro expansion, just like an ordinary argument. You may use @@ -1662,9 +1662,9 @@ this, as an extension. You may write an argument name immediately before the @samp{@dots{}}; that name is used for the variable argument. The @code{eprintf} macro above could be written -@example +@smallexample #define eprintf(args@dots{}) fprintf (stderr, args) -@end example +@end smallexample @noindent using this extension. You cannot use @code{@w{__VA_ARGS__}} and this @@ -1673,9 +1673,9 @@ extension in the same macro. You can have named arguments as well as variable arguments in a variadic macro. We could define @code{eprintf} like this, instead: -@example +@smallexample #define eprintf(format, @dots{}) fprintf (stderr, format, __VA_ARGS__) -@end example +@end smallexample @noindent This formulation looks more descriptive, but unfortunately it is less @@ -1685,26 +1685,26 @@ argument from the variable arguments. Furthermore, if you leave the variable argument empty, you will get a syntax error, because there will be an extra comma after the format string. -@example +@smallexample eprintf("success!\n", ); @expansion{} fprintf(stderr, "success!\n", ); -@end example +@end smallexample GNU CPP has a pair of extensions which deal with this problem. First, you are allowed to leave the variable argument out entirely: -@example +@smallexample eprintf ("success!\n") @expansion{} fprintf(stderr, "success!\n", ); -@end example +@end smallexample @noindent Second, the @samp{##} token paste operator has a special meaning when placed between a comma and a variable argument. If you write -@example +@smallexample #define eprintf(format, @dots{}) fprintf (stderr, format, ##__VA_ARGS__) -@end example +@end smallexample @noindent and the variable argument is left out when the @code{eprintf} macro is @@ -1712,10 +1712,10 @@ used, then the comma before the @samp{##} will be deleted. This does @emph{not} happen if you pass an empty argument, nor does it happen if the token preceding @samp{##} is anything other than a comma. -@example +@smallexample eprintf ("success!\n") @expansion{} fprintf(stderr, "success!\n"); -@end example +@end smallexample @noindent The above explanation is ambiguous about the case where the only macro @@ -1748,9 +1748,9 @@ previous versions of GCC, the token preceding the special @samp{##} must be a comma, and there must be white space between that comma and whatever comes immediately before it: -@example +@smallexample #define eprintf(format, args@dots{}) fprintf (stderr, format , ##args) -@end example +@end smallexample @noindent @xref{Differences from previous versions}, for the gory details. @@ -1803,12 +1803,12 @@ message to report an inconsistency detected by the program; the message can state the source line at which the inconsistency was detected. For example, -@example +@smallexample fprintf (stderr, "Internal error: " "negative string length " "%d at %s, line %d.", length, __FILE__, __LINE__); -@end example +@end smallexample An @samp{#include} directive changes the expansions of @code{__FILE__} and @code{__LINE__} to correspond to the included file. At the end of @@ -1942,26 +1942,26 @@ minor version and patch level are reset. If you wish to use the predefined macros directly in the conditional, you will need to write it like this: -@example +@smallexample /* @r{Test for GCC > 3.2.0} */ #if __GNUC__ > 3 || \ (__GNUC__ == 3 && (__GNUC_MINOR__ > 2 || \ (__GNUC_MINOR__ == 2 && \ __GNUC_PATCHLEVEL__ > 0)) -@end example +@end smallexample @noindent Another approach is to use the predefined macros to calculate a single number, then compare that against a threshold: -@example +@smallexample #define GCC_VERSION (__GNUC__ * 10000 \ + __GNUC_MINOR__ * 100 \ + __GNUC_PATCHLEVEL__) @dots{} /* @r{Test for GCC > 3.2.0} */ #if GCC_VERSION > 30200 -@end example +@end smallexample @noindent Many people find this form easier to understand. @@ -2176,12 +2176,12 @@ macro is function-like. It is an error if anything appears on the line after the macro name. @samp{#undef} has no effect if the name is not a macro. -@example +@smallexample #define FOO 4 x = FOO; @expansion{} x = 4; #undef FOO x = FOO; @expansion{} x = FOO; -@end example +@end smallexample Once a macro has been undefined, that identifier may be @dfn{redefined} as a macro by a subsequent @samp{#define} directive. The new definition @@ -2201,19 +2201,19 @@ count as whitespace. @noindent These definitions are effectively the same: -@example +@smallexample #define FOUR (2 + 2) #define FOUR (2 + 2) #define FOUR (2 /* two */ + 2) -@end example +@end smallexample @noindent but these are not: -@example +@smallexample #define FOUR (2 + 2) #define FOUR ( 2+2 ) #define FOUR (2 * 2) #define FOUR(score,and,seven,years,ago) (2 + 2) -@end example +@end smallexample If a macro is redefined with a definition that is not effectively the same as the old one, the preprocessor issues a warning and changes the @@ -2294,25 +2294,25 @@ the input file, for more macro calls. It is possible to piece together a macro call coming partially from the macro body and partially from the arguments. For example, -@example +@smallexample #define twice(x) (2*(x)) #define call_with_1(x) x(1) call_with_1 (twice) @expansion{} twice(1) @expansion{} (2*(1)) -@end example +@end smallexample Macro definitions do not have to have balanced parentheses. By writing an unbalanced open parenthesis in a macro body, it is possible to create a macro call that begins inside the macro body but ends outside of it. For example, -@example +@smallexample #define strange(file) fprintf (file, "%s %d", @dots{} strange(stderr) p, 35) @expansion{} fprintf (stderr, "%s %d", p, 35) -@end example +@end smallexample The ability to piece together a macro call can be useful, but the use of unbalanced open parentheses in a macro body is just confusing, and @@ -2330,41 +2330,41 @@ way. Suppose you define a macro as follows, -@example +@smallexample #define ceil_div(x, y) (x + y - 1) / y -@end example +@end smallexample @noindent whose purpose is to divide, rounding up. (One use for this operation is to compute how many @code{int} objects are needed to hold a certain number of @code{char} objects.) Then suppose it is used as follows: -@example +@smallexample a = ceil_div (b & c, sizeof (int)); @expansion{} a = (b & c + sizeof (int) - 1) / sizeof (int); -@end example +@end smallexample @noindent This does not do what is intended. The operator-precedence rules of C make it equivalent to this: -@example +@smallexample a = (b & (c + sizeof (int) - 1)) / sizeof (int); -@end example +@end smallexample @noindent What we want is this: -@example +@smallexample a = ((b & c) + sizeof (int) - 1)) / sizeof (int); -@end example +@end smallexample @noindent Defining the macro as -@example +@smallexample #define ceil_div(x, y) ((x) + (y) - 1) / (y) -@end example +@end smallexample @noindent provides the desired result. @@ -2374,9 +2374,9 @@ ceil_div(1, 2)}. That has the appearance of a C expression that would compute the size of the type of @code{ceil_div (1, 2)}, but in fact it means something very different. Here is what it expands to: -@example +@smallexample sizeof ((1) + (2) - 1) / (2) -@end example +@end smallexample @noindent This would take the size of an integer and divide it by two. The @@ -2386,9 +2386,9 @@ was intended to be inside. Parentheses around the entire macro definition prevent such problems. Here, then, is the recommended way to define @code{ceil_div}: -@example +@smallexample #define ceil_div(x, y) (((x) + (y) - 1) / (y)) -@end example +@end smallexample @node Swallowing the Semicolon @subsection Swallowing the Semicolon @@ -2399,13 +2399,13 @@ statement. Consider, for example, the following macro, that advances a pointer (the argument @code{p} says where to find it) across whitespace characters: -@example +@smallexample #define SKIP_SPACES(p, limit) \ @{ char *lim = (limit); \ while (p < lim) @{ \ if (*p++ != ' ') @{ \ p--; break; @}@}@} -@end example +@end smallexample @noindent Here backslash-newline is used to split the macro definition, which must @@ -2422,11 +2422,11 @@ like a function call, writing a semicolon afterward, as in This can cause trouble before @code{else} statements, because the semicolon is actually a null statement. Suppose you write -@example +@smallexample if (*p != 0) SKIP_SPACES (p, lim); else @dots{} -@end example +@end smallexample @noindent The presence of two statements---the compound statement and a null @@ -2436,20 +2436,20 @@ makes invalid C code. The definition of the macro @code{SKIP_SPACES} can be altered to solve this problem, using a @code{do @dots{} while} statement. Here is how: -@example +@smallexample #define SKIP_SPACES(p, limit) \ do @{ char *lim = (limit); \ while (p < lim) @{ \ if (*p++ != ' ') @{ \ p--; break; @}@}@} \ while (0) -@end example +@end smallexample Now @code{SKIP_SPACES (p, lim);} expands into -@example +@smallexample do @{@dots{}@} while (0); -@end example +@end smallexample @noindent which is one statement. The loop executes exactly once; most compilers @@ -2462,23 +2462,23 @@ generate no extra code for it. @cindex unsafe macros Many C programs define a macro @code{min}, for ``minimum'', like this: -@example +@smallexample #define min(X, Y) ((X) < (Y) ? (X) : (Y)) -@end example +@end smallexample When you use this macro with an argument containing a side effect, as shown here, -@example +@smallexample next = min (x + y, foo (z)); -@end example +@end smallexample @noindent it expands as follows: -@example +@smallexample next = ((x + y) < (foo (z)) ? (x + y) : (foo (z))); -@end example +@end smallexample @noindent where @code{x + y} has been substituted for @code{X} and @code{foo (z)} @@ -2496,12 +2496,12 @@ computes the value of @code{foo (z)} only once. The C language offers no standard way to do this, but it can be done with GNU extensions as follows: -@example +@smallexample #define min(X, Y) \ (@{ typeof (X) x_ = (X); \ typeof (Y) y_ = (Y); \ (x_ < y_) ? x_ : y_; @}) -@end example +@end smallexample The @samp{(@{ @dots{} @})} notation produces a compound statement that acts as an expression. Its value is the value of its last statement. @@ -2515,7 +2515,7 @@ careful when @emph{using} the macro @code{min}. For example, you can calculate the value of @code{foo (z)}, save it in a variable, and use that variable in @code{min}: -@example +@smallexample @group #define min(X, Y) ((X) < (Y) ? (X) : (Y)) @dots{} @@ -2524,7 +2524,7 @@ that variable in @code{min}: next = min (x + y, tem); @} @end group -@end example +@end smallexample @noindent (where we assume that @code{foo} returns type @code{int}). @@ -2540,9 +2540,9 @@ macro, it would produce an infinitely large expansion. To prevent this, the self-reference is not considered a macro call. It is passed into the preprocessor output unchanged. Let's consider an example: -@example +@smallexample #define foo (4 + foo) -@end example +@end smallexample @noindent where @code{foo} is also a variable in your program. @@ -2565,9 +2565,9 @@ of the variable @code{foo}, whereas in fact the value is four greater. One common, useful use of self-reference is to create a macro which expands to itself. If you write -@example +@smallexample #define EPERM EPERM -@end example +@end smallexample @noindent then the macro @code{EPERM} expands to @code{EPERM}. Effectively, it is @@ -2581,15 +2581,15 @@ If a macro @code{x} expands to use a macro @code{y}, and the expansion of self-reference} of @code{x}. @code{x} is not expanded in this case either. Thus, if we have -@example +@smallexample #define x (4 + y) #define y (2 * x) -@end example +@end smallexample @noindent then @code{x} and @code{y} expand as follows: -@example +@smallexample @group x @expansion{} (4 + y) @expansion{} (4 + (2 * x)) @@ -2597,7 +2597,7 @@ x @expansion{} (4 + y) y @expansion{} (2 * x) @expansion{} (2 * (4 + y)) @end group -@end example +@end smallexample @noindent Each macro is expanded when it appears in the definition of the other @@ -2658,12 +2658,12 @@ concatenate its expansion, you can do that by causing one macro to call another macro that does the stringification or concatenation. For instance, if you have -@example +@smallexample #define AFTERX(x) X_ ## x #define XAFTERX(x) AFTERX(x) #define TABLESIZE 1024 #define BUFSIZE TABLESIZE -@end example +@end smallexample then @code{AFTERX(BUFSIZE)} expands to @code{X_BUFSIZE}, and @code{XAFTERX(BUFSIZE)} expands to @code{X_1024}. (Not to @@ -2675,11 +2675,11 @@ Macros used in arguments, whose expansions contain unshielded commas. This can cause a macro expanded on the second scan to be called with the wrong number of arguments. Here is an example: -@example +@smallexample #define foo a,b #define bar(x) lose(x) #define lose(x) (1 + (x)) -@end example +@end smallexample We would like @code{bar(foo)} to turn into @code{(1 + (foo))}, which would then turn into @code{(1 + (a,b))}. Instead, @code{bar(foo)} @@ -2688,11 +2688,11 @@ requires a single argument. In this case, the problem is easily solved by the same parentheses that ought to be used to prevent misnesting of arithmetic operations: -@example +@smallexample #define foo (a,b) @exdent or #define bar(x) lose((x)) -@end example +@end smallexample The extra pair of parentheses prevents the comma in @code{foo}'s definition from being interpreted as an argument separator. @@ -2711,13 +2711,13 @@ different to the line containing the argument causing the problem. Here is an example illustrating this: -@example +@smallexample #define ignore_second_arg(a,b,c) a; c ignore_second_arg (foo (), ignored (), syntax error); -@end example +@end smallexample @noindent The syntax error triggered by the tokens @code{syntax error} results in @@ -2818,7 +2818,7 @@ directive}: @samp{#if}, @samp{#ifdef} or @samp{#ifndef}. The simplest sort of conditional is -@example +@smallexample @group #ifdef @var{MACRO} @@ -2826,7 +2826,7 @@ The simplest sort of conditional is #endif /* @var{MACRO} */ @end group -@end example +@end smallexample @cindex conditional group This block is called a @dfn{conditional group}. @var{controlled text} @@ -2899,7 +2899,7 @@ automated by a tool such as @command{autoconf}, or done by hand. The @samp{#if} directive allows you to test the value of an arithmetic expression, rather than the mere existence of one macro. Its syntax is -@example +@smallexample @group #if @var{expression} @@ -2907,7 +2907,7 @@ expression, rather than the mere existence of one macro. Its syntax is #endif /* @var{expression} */ @end group -@end example +@end smallexample @var{expression} is a C expression of integer type, subject to stringent restrictions. It may contain @@ -2977,9 +2977,9 @@ defined MACRO}} is precisely equivalent to @code{@w{#ifdef MACRO}}. @code{defined} is useful when you wish to test more than one macro for existence at once. For example, -@example +@smallexample #if defined (__vax__) || defined (__ns16000__) -@end example +@end smallexample @noindent would succeed if either of the names @code{__vax__} or @@ -2987,9 +2987,9 @@ would succeed if either of the names @code{__vax__} or Conditionals written like this: -@example +@smallexample #if defined BUFSIZE && BUFSIZE >= 1024 -@end example +@end smallexample @noindent can generally be simplified to just @code{@w{#if BUFSIZE >= 1024}}, @@ -3010,7 +3010,7 @@ The @samp{#else} directive can be added to a conditional to provide alternative text to be used if the condition fails. This is what it looks like: -@example +@smallexample @group #if @var{expression} @var{text-if-true} @@ -3018,7 +3018,7 @@ looks like: @var{text-if-false} #endif /* Not @var{expression} */ @end group -@end example +@end smallexample @noindent If @var{expression} is nonzero, the @var{text-if-true} is included and @@ -3034,7 +3034,7 @@ You can use @samp{#else} with @samp{#ifdef} and @samp{#ifndef}, too. One common case of nested conditionals is used to check for more than two possible alternatives. For example, you might have -@example +@smallexample #if X == 1 @dots{} #else /* X != 1 */ @@ -3044,12 +3044,12 @@ possible alternatives. For example, you might have @dots{} #endif /* X != 2 */ #endif /* X != 1 */ -@end example +@end smallexample Another conditional directive, @samp{#elif}, allows this to be abbreviated as follows: -@example +@smallexample #if X == 1 @dots{} #elif X == 2 @@ -3057,7 +3057,7 @@ abbreviated as follows: #else /* X != 2 and X != 1*/ @dots{} #endif /* X != 2 and X != 1*/ -@end example +@end smallexample @samp{#elif} stands for ``else if''. Like @samp{#else}, it goes in the middle of a conditional group and subdivides it; it does not require a @@ -3117,23 +3117,23 @@ combination of parameters which you know the program does not properly support. For example, if you know that the program will not run properly on a VAX, you might write -@example +@smallexample @group #ifdef __vax__ #error "Won't work on VAXen. See comments at get_last_object." #endif @end group -@end example +@end smallexample If you have several configuration parameters that must be set up by the installation in a consistent way, you can use conditionals to detect an inconsistency and report it with @samp{#error}. For example, -@example +@smallexample #if !defined(UNALIGNED_INT_ASM_OP) && defined(DWARF2_DEBUGGING_INFO) #error "DWARF2_DEBUGGING_INFO requires UNALIGNED_INT_ASM_OP." #endif -@end example +@end smallexample @findex #warning The directive @samp{#warning} is like @samp{#error}, but causes the @@ -3267,18 +3267,18 @@ literal. It is destringized, by replacing all @samp{\\} with a single processed as if it had appeared as the right hand side of a @samp{#pragma} directive. For example, -@example +@smallexample _Pragma ("GCC dependency \"parse.y\"") -@end example +@end smallexample @noindent has the same effect as @code{#pragma GCC dependency "parse.y"}. The same effect could be achieved using macros, for example -@example +@smallexample #define DO_PRAGMA(x) _Pragma (#x) DO_PRAGMA (GCC dependency "parse.y") -@end example +@end smallexample The standard is unclear on where a @code{_Pragma} operator can appear. The preprocessor does not accept it within a preprocessing conditional @@ -3300,10 +3300,10 @@ other file is searched for using the normal include search path. Optional trailing text can be used to give more information in the warning message. -@example +@smallexample #pragma GCC dependency "parse.y" #pragma GCC dependency "/usr/include/time.h" rerun fixincludes -@end example +@end smallexample @item #pragma GCC poison Sometimes, there is an identifier that you want to remove completely @@ -3313,10 +3313,10 @@ enforce this, you can @dfn{poison} the identifier with this pragma. poison. If any of those identifiers appears anywhere in the source after the directive, it is a hard error. For example, -@example +@smallexample #pragma GCC poison printf sprintf fprintf sprintf(some_string, "hello"); -@end example +@end smallexample @noindent will produce an error. @@ -3328,11 +3328,11 @@ about system headers defining macros that use it. For example, -@example +@smallexample #define strrchr rindex #pragma GCC poison rindex strrchr(some_string, 'h'); -@end example +@end smallexample @noindent will not produce an error. @@ -3401,9 +3401,9 @@ necessary to prevent an accidental token paste. Source file name and line number information is conveyed by lines of the form -@example +@smallexample # @var{linenum} @var{filename} @var{flags} -@end example +@end smallexample @noindent These are called @dfn{linemarkers}. They are inserted as needed into @@ -3924,9 +3924,9 @@ all. @cindex predicates An assertion looks like this: -@example +@smallexample #@var{predicate} (@var{answer}) -@end example +@end smallexample @noindent @var{predicate} must be a single identifier. @var{answer} can be any @@ -3942,26 +3942,26 @@ To test an assertion, you write it in an @samp{#if}. For example, this conditional succeeds if either @code{vax} or @code{ns16000} has been asserted as an answer for @code{machine}. -@example +@smallexample #if #machine (vax) || #machine (ns16000) -@end example +@end smallexample @noindent You can test whether @emph{any} answer is asserted for a predicate by omitting the answer in the conditional: -@example +@smallexample #if #machine -@end example +@end smallexample @findex #assert Assertions are made with the @samp{#assert} directive. Its sole argument is the assertion to make, without the leading @samp{#} that identifies assertions in conditionals. -@example +@smallexample #assert @var{predicate} (@var{answer}) -@end example +@end smallexample @noindent You may make several assertions with the same predicate and different @@ -3977,9 +3977,9 @@ answer which was specified on the @samp{#unassert} line; other answers for that predicate remain true. You can cancel an entire predicate by leaving out the answer: -@example +@smallexample #unassert @var{predicate} -@end example +@end smallexample @noindent In either form, if no such assertion has been made, @samp{#unassert} has |