text: Go to the next section.. See section Invoking the C Preprocessor.
  Most C preprocessor features are inactive unless you give specific commands to request their use. (Preprocessor commands are lines starting with `#'; see section Preprocessor Commands). But there are three transformations that the preprocessor always makes on all the input it receives, even in the absence of commands.
  The first two transformations are done before nearly all other parsing and before preprocessor commands are recognized. Thus, for example, you can split a line cosmetically with Backslash-Newline anywhere (except when trigraphs are in use; see below).
  /* */ # /* */ defi\ ne FO\ O 10\ 20
  is equivalent into `#define FOO 1020'. You can split even an escape
  sequence with Backslash-Newline. For example, you can split
  "foo\bar"
  between the `\' and the `b' to get
  "foo\\ bar".
  This exception is relevant only if you use the `-trigraphs' option to enable trigraph processing. See section Invoking the C Preprocessor. cannot define new preprocessor commands.
  Some command names require arguments; these make up the rest of the command line and must be separated from the command name by whitespace. For example, `#define' must be followed by a macro name and the intended expansion of the macro. See section Simple Macros.
  A preprocessor command cannot be more than one line in normal circumstances. It may be split cosmetically with Backslash-Newline, but that has no effect on its meaning. Comments containing Newlines can also divide the command into multiple lines, but the comments are changed to Spaces before the command is interpreted. The only way a significant expanding to `define', that does not make `#foo' a valid preprocessor command.
  A header file is a file containing C declarations and macro definitions (see section Macros) to be shared between several source files. You request the use of a header file in your program with the C preprocessor command `#include'.
  Header files serve two kinds of purposes. `.h'. Avoid unusual characters in header file names, as they reduce portability.
  Both user and system header files are included using the preprocessor command `#include'. It has three variants:
  #include <file>
  The parsing of this form of `#include' is slightly special because comments are not recognized within the `<...>'. Thus, in `#include <x/*y>' the `/*' does not start a comment and the command.
  #include "file".
  #include anything else.
  The `#include' command' command. For example, given a header file `header.h' as follows,
  char *test ();
  and a main program called `program.c' that uses the header file, like this,
  int x; #include "header.h" main () { printf (test ()); }
  the output generated by the C preprocessor for `program.c' as input would be
  int x; char *test (); main () { printf  `#include' command is always treated as a separate line by the C preprocessor even if the included file lacks a final newline.:
  #ifndef FILE_FOO_SEEN #define FILE_FOO_SEEN the entire file #endif /* FILE_FOO_SEEN */
  The macro
  FILE_FOO_SEEN indicates that the file has been included
  once already. In a user header file, the macro name should not begin
  with `_'. In a system header file, this name should begin with
  `__' `#ifndef' conditional, then it records that fact. If a subsequent `#include' specifies the same file, and the macro in the `#ifndef' is already defined, then the file is entirely skipped, without even reading it.
  There is also an explicit command.
  In the Objective C language, there is a variant of `#include' called `#import' which includes a file, but does so at most once. If you use `#import' instead of `#include', then you don't need the conditionals inside the header file to prevent multiple execution of the contents.
  ` `#ifndef' accomplishes this goal. `#include "base"' in the inheriting file.
  Sometimes it is necessary to give the inheriting file the same name as the base file. This is less straightforward.
  For example, suppose an application program uses the system header file  using the option `-I.' for compilation,.
  `.
  The clean way to solve this problem is to use `#include_next', which means, "Include the next file with this name." This command that both directories contain a file named '. If somewhere after this `#define' commandprocessor commands. 
  foo = X; #define X 4 bar = X;
  produces as output
  foo = X; bar = 4;
  After the preprocessor expands a macro name, the macro's definition body is appended to the front of the remaining input, and the check for macro calls continues. Therefore, the macro body can contain calls to other macros. For example, after
  #define BUFSIZE 1020 #define TABLESIZE BUFSIZE
  the name `TABLESIZE' when used in the program would go through two stages of expansion, resulting ultimately in `1020'.. See section Cascaded Use of Macros.
  A simple macro always stands for exactly the same text, each time it is used. Macros can be more flexible when they accept arguments. Arguments are fragments of code that you supply each time the macro is used. These fragments are included in the expansion of the macro according to the directions in the macro definition. A macro that accepts arguments is called a function-like macro because the syntax for using it looks like a function call.
  To define a macro that uses arguments, you write a `#define' command with a list of:
  #define min(X, Y) ((X) < (Y) ? (X) : (Y))
  (This is not the best way to define a "minimum" macro in GNU C. See section you use. Each of the argument names of the macro is replaced, throughout the macro definition, with the corresponding actual argument. Using the same macro `min' defined above, `min (1, 2)' expands into
  ((1) < (2) ? (1) : (2))
  where `1' has been substituted for `X' and `2' for `Y'.
  Likewise, `min (x + 28, *p)' expands into
  ((x + 28) < (*p) ? (x + 28) : (*p))
  Parentheses in the actual arguments must balance; a comma within parentheses does not end an argument. However, there is no requirement for brackets or braces to balance, and they do not prevent a comma from separating arguments. Thus,
  macro (array[x = y, x + 1])
  passes two arguments to
  macro: `array[x = y' and `x +
  1]'. If you want to supply `array[x = y, x + 1]' as an argument,
  you must write it as , `min (min (a, b), c)' expands into this text:
  ((((a) < (b) ? (a) : (b))) < (c) ? (((a) < (b) ? (a) : (b))) : () ... `min' in the same source file that defines the macro. If you write `&min' with no argument list, you refer to the function. If you write `min (x, bb)', with an argument list, the macro is expanded. If you write `(min) (a, bb)', where the name `min' is not followed by an open-parenthesis, the macro is not expanded, so you wind up with a call to the function :
  #define FOO(x) - 1 / (x)
  (which defines `FOO' to take an argument and expand into minus the reciprocal of that argument) or this:
   macros.
  The standard predefined macros are available with the same meanings
  regardless of the machine or operating system on which you are using GNU C.
  Their names all start and end with double underscores. Those preceding
  __GNUC__ in this table are standardized by ANSI C; the rest are
  GNU C extensions.
  __FILE__
  __LINE____);
  A `#include' command changes the expansions of `__FILE__' and `__LINE__' to correspond to the included file. At the end of that file, when processing resumes on the input file that contained the `#include' command, the expansions of `__FILE__' and `__LINE__' revert to the values they had before the `#include' (but `__LINE__' is then incremented by one as processing moves to the line after the `#include').
  The expansions of both `__FILE__' and `__LINE__' are altered if a `#line' command is used. See section Combining Source Files.
  __INCLUDE_LEVEL__
  __DATE__
  __TIME__
  __STDC__
  __GNUC__
  __GNUG__
  __cplusplus
  __STRICT_ANSI__
  __BASE_FILE__
  __VERSION__
  __OPTIMIZE__
  __CHAR_UNSIGNED__
  charis unsigned on the target machine. It exists to cause the standard header file `limit.h' to work correctly. It is bad practice to refer to this macro yourself; instead, refer to the standard macros defined in `limit.h'. The preprocessor uses this macro to determine whether or not to sign-extend large character constants written in octal; see section The `#if' Command. `cpp -dM' to see the values of predefined macros; see section Invoking the C Preprocessor.
  Some nonstandard predefined macros describe the operating system in use, with more or less specificity. For example,
  unix
  BSD
  Other nonstandard predefined macros describe the kind of CPU, with more or less specificity. For example,
  vax
  mc68000
  m68k
  M68020
  _AM29K
  _AM29000
  ns32000
  Yet other nonstandard predefined macros describe the manufacturer of the system. For example,
  sun
  pyr
  sequent
  These predefined symbols are not only nonstandard, they are contrary to the ANSI standard because their names do not start with underscores. Therefore, the option `-ansi' inhibits the definition of these symbols.
  This tends to make ` `__' at the beginning
  and end. Thus, the symbol
  __vax__ would be available on a Vax,
  and so on.
  The set of nonstandard predefined names in the GNU C preprocessor is
  controlled (when
  cpp is itself compiled) by the macro
  `CPP_PREDEFINES', which should be a string containing `-D'
  options, separated by spaces. For example, on the Sun 3, we use the
  following definition:
  #define CPP_PREDEFINES "-Dmc68000 -Dsun -Dunix -Dm68k"
  This macro is usually specified in `tm.h'.
  Stringification means turning a code fragment into a string constant whose contents are the text for the code fragment. For example, stringifying `foo (z)' results in `"foo (z)"'.
  In the C preprocessor, stringification is an option available when macro arguments are substituted into the macro definition. In the body of the definition, when an argument name appears, the character `#' before the name specifies stringification of the corresponding actual argument when it is substituted at that point in the definition. The same argument may be substituted in other places in the definition without stringification if the argument name appears in those places with no `#'.
  Here is an example of a macro definition that uses stringification:
  #define WARN_IF(EXP) \ do { if (EXP) \ fprintf (stderr, "Warning: " #EXP "\n"); } \ while (0)
  Here the actual argument for `EXP' is substituted once as given, into the `if' statement, and once as stringified, into the argument to `fprintf'. The `do' and `while (0)' are a kludge to make it possible to write `WARN_IF (arg);', which the resemblance of `WARN_IF' to a function would make C programmers want to do; see section Swallowing) `p = "foo\n";' results in `"p = \"foo\\n\";"'. However, backslashes that are not inside of string or character constants are not duplicated: `\n' by.
  When you define a macro, you request concatenation with the special operator `##' in the macro body. When the macro is called, after actual arguments are substituted, all `##' operators are deleted, and so is any whitespace next to them (including whitespace that was part of an actual argument). The result is to concatenate the syntactic tokens on either side of the `##'.
  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:
  struct command { char *name; void (*function) (); };), ... };
  The usual case of concatenation is concatenating two names (or a name and a number) into a longer name. But this isn't the only valid case. It is also possible to concatenate two numbers (or a number and a name, such as `1.5' and `e3') into a number. Also, multi-character operators such as `+=' can be formed by concatenation. In some cases it is even possible to piece together a string constant. However, two pieces of text that don't together form a valid lexical unit cannot be concatenated. For example, concatenation with `x' on one side and `+' `x' and `+' side by side with no particular special results.
  Keep in mind that the C preprocessor converts comments to whitespace before macros are even considered. Therefore, you cannot create a comment by concatenating `/' and `*': the `/*' sequence that starts a comment is not a lexical unit, but rather the beginning of a "long" space' command. `,
  #define FOO 4 x = FOO; #undef FOO x = FOO;
  expands into
  x = 4; x = FOO;
  In this example, `FOO' had better be a variable or function as well as (temporarily) a macro, in order for the result of the expansion to be valid C code.
  The same form of `#undef' command will cancel definitions with arguments or definitions that don't expect arguments. The `#undef' command has no effect when used on a name not currently defined as a macro.
  Redefining a macro means defining (with ` (see section `.,
  #define double(x) (2*(x)) #define call_with_1(x) x(1)
  would expand `call_with_1 (double)' into `)
  This bizarre example expands to `fprintf (stderr, "%s %d", p, 35)'!));
  This expands into
  a = (b & c + sizeof (int) - 1) / sizeof (int);
  which does not do what is intended. The operator-precedence rules of C make it equivalent to this:
  a = (b & (c + sizeof (int) - 1)) / sizeof (int);
  But what we want is this:
  a = ((b & c) + sizeof (int) - 1)) / sizeof (int);
  Defining the macro as
  #define ceil_div(x, y) ((x) + (y) - 1) / (y)
  provides the desired result.
  However, can) \ { register char *lim = (limit); \ while (p != lim) { \ if (*p++ != ' ') { \ p--; break; }}}
  Here Backslash-Newline is used to split the macro definition, which must be a single line, so that it resembles the way such C code would be laid out if not part of a macro definition.
  A call to this macro might be  `SKIP_SPACES (p, lim);'
  But { register char *lim = (limit); \ while (p != lim) { \ if (*p++ != ' ') { \ p--; break; }}} \ while (0)
  Now `SKIP_SPACES (p, lim);' expands into
  do {...} while (0);
  which is one statement. C extensions as follows:
  #define min(X, Y) \ ({ typeof (X) __x = (X), __y = (Y); \ (__x < __y) ? __x : __y; }). A special feature of ANSI Standard C is it causes a fatal error (memory full) in the preprocessor.
  However, the special rule about self-reference.
  The special rule for self-reference applies also to indirect self-reference. This is the case where a macro x expands to use a macro `y', and the expansion of `y' refers to the macro `x'. The resulting reference to `x' comes indirectly from the expansion of `x', so it is a self-reference and is not further expanded. Thus, after
  #define x (4 + y) #define y (2 * x)
  `x' would expand into `(4 + (2 * x))'. Clear?
  But suppose `y' is used elsewhere, not from the definition of `x'. Then the use of `x' in the expansion of `y' is not a self-reference because `x' is not "in progress". So it does expand. However, the expansion of `x' contains a reference to `y', and that is an indirect self-reference now because `y' is "in progress". The result is that `y' expands to `(2 * (4 + y))'.
  It is not clear that this behavior would ever be useful, but it is specified by the ANSI C standard, so you may need to understand it. (see section Self-Referential Macros):,
  #define str(s) #s #define foo 4 str (foo)
  expands to `.
  #define str(s) #s lose(s) #define foo 4 str (foo)
  expands to `"foo" lose(4)'.
  You might now ask, "Why mention the prescan, if it makes no difference? And why not skip it and make the preprocessor faster?" The answer is that the prescan does make a difference in three special cases:
  We say that nested calls to a macro occur when a macro's actual actual argument, and the inner use of :
  #define foo a,b #define bar(x) lose(x) #define lose(x) (1 + (x)) bar(foo)
  We would like `bar(foo)' to turn into `(1 + (foo))', which
  would then turn into `(1 + (a,b))'. But instead, `bar(foo)'
  expands into `lose(a,b)', and you get an error because
  lose
  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:
  #define foo (a,b) #define bar(x) lose((x))
  The problem is more serious when the operands of the macro are not expressions; for example, when they are statements. Then parentheses are unacceptable because they would make for invalid C code:
  #define foo { int a, b; ... }
  In GNU C you can shield the commas using the `({...})' construct which turns a compound statement into an expression:
  #define foo ({ int a, b; ... })
  Or you can rewrite the macro definition to avoid such commas:
  #define foo { int a; int b; ... }
  There is also one case where prescan is useful. It is possible to use prescan to expand an argument and then stringify it--if you use two levels of macros. Let's add a new macro `xstr' to the example shown above:
  #define xstr(s) str(s) #define str(s) #s #define foo 4 xstr (foo)
  This expands into `"4"', not `"foo"'. The reason for the difference is that the argument of `xstr' is expanded at prescan (because `xstr' does not specify stringification or concatenation of the argument). The result of prescan then forms the actual argument for `str'. `str' uses its argument without prescan because it performs stringification; but it cannot prevent or undo the prescanning already done by `xstr'.
  A cascade of macros is when one macro's body contains a reference to another macro. This is very common practice. For example,
  #define BUFSIZE 1020 #define TABLESIZE BUFSIZE'. (The
  `#undef' is to prevent any warning about the nontrivial
  redefinition of
  BUFSIZE.):
   command that allows a part of the program to be ignored during compilation, on some conditions. In the C preprocessor, a conditional can test either an arithmetic expression or whether a name is defined as a macro.processor conditional command is tested when your program is compiled. Its purpose is to allow different code to be included in the program depending on the situation at the time of compilation.
  Generally there are three kinds of reason to use a conditional.
  Most simple programs that are intended to run on only one machine will not need to use preprocessor conditionals.
  A conditional in the C preprocessor begins with a conditional command: `#if', `#ifdef' or `#ifndef'. See section Conditionals and Macros, for information on `#ifdef' and `#ifndef'; only `#if' is explained here.
  The `#if' command in its simplest form consists of
  #if expression controlled text #endif /* expression */
  The comment following the `#endif' is not required, but it is a good practice because it helps people match the `#endif' to the corresponding `#if'. Such comments should always be used, except in short conditionals that are not nested. In fact, you can put anything at all after the `#endif' and it will be ignored by the GNU C preprocessor, but only comments are acceptable in ANSI Standard C.
  expression is a C expression of integer type, subject to stringent restrictions. It may contain
  longor
  unsigned long.
  Note that `sizeof' operators and
  enum-type values are not allowed.
  enum-type values, like all other identifiers that are not taken
  as macro calls and expanded, are treated as zero.
  The controlled text inside of a conditional can include preprocessor commands. Then the commands inside the conditional are obeyed only if that branch of the conditional succeeds. The text can also contain other conditional groups. However, the `#if' and `#endif' commands must balance.
  The `#else' command succeeds. More than one `#elif' can go in the same `#if'-`#endif' group. Then the text after each `#elif' is processed only if the `#elif' condition succeeds after the original `#if' and any previous `#elif' commands within it have failed. `#else' is equivalent to `#elif 1', and `#else' is allowed after any number of `#elif' commands,' command commands for this case.
  #ifdef name
  #ifndef name
  Macro definitions can vary between compilations for several reasons.
  Assertions are a more systematic alternative to macros in writing conditionals to test what sort of computer or system the compiled program will run on. Assertions are usually predefined, but you can define them with preprocessor commands or command-line options. command `#error' causes the preprocessor to report a fatal error. The rest of the line that follows `#error'
  See section Nonstandard Predefined Macros, for why this works.
  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 `#error'. For example,
  #if HASH_TABLE_SIZE % 2 == 0 || HASH_TABLE_SIZE % 3 == 0 \ || HASH_TABLE_SIZE % 5 == 0 #error HASH_TABLE_SIZE should not be divisible by a small prime #endif
  The command `#warning' is like the command `#error', but causes the preprocessor to issue a warning and continue preprocessing. The rest of the line that follows `#warning' is used as the warning message.
  You might use `#warning' in obsolete header files, with a message directing the user to the header file which should be used instead.
  One of the jobs of the C preprocessor is to inform the C compiler of where each line of C code came from: which source file and which line number.
  C code can come from multiple source files if you use `#include'; both ` command by which
  you can control the feature explicitly. This is useful when a file for
  input to the C preprocessor is the output from another program such as the
  bison parser generator, which operates on another file that is the
  true source file. Parts of the output from
  bison are generated from
  scratch, other parts come from a standard parser file. The rest are copied
  nearly verbatim from the source file, but their line numbers in the
  bison output are not the same as their original line numbers.
  Naturally you would like compiler error messages and symbolic debuggers to
  know the original source file and line number of each line in the
  bison input.
  bison arranges this by writing `#line' commands into the output
  file. `#line' is a command that specifies the original line number
  and source file name for subsequent input in the current preprocessor input
  file. `#line' has three variants:
  #line linenum
  #line linenum filename
  #line anything else
  `#line' commands alter the results of the `__FILE__' and `__LINE__' predefined macros from that point on. See section Standard Predefined Macros.
  The output of the preprocessor (which is the input for the rest of the compiler) contains commands that look much like `#line' commands. They start with just `#' instead of `#line', but this is followed by a line number and file name as in `#line'. See section C Preprocessor Output.
  This section describes three additional preprocessor commands. They are not very useful, but are mentioned for completeness.
  The null command consists of a `#' followed by a Newline, with only whitespace (including comments) in between. A null command is understood as a preprocessor command but has no effect on the preprocessor output. The primary significance of the existence of the null command is that an input line consisting of just a `#' will produce no output, rather than a line of output containing just a `#'. Supposedly some old C programs contain such lines.
  The ANSI standard specifies that the `#pragma' command has an arbitrary, implementation-defined effect. In the GNU C preprocessor, `#pragma' commands are not used, except for `#pragma once' (see section Once-Only Include Files). However, they are left in the preprocessor output, so they are available to the compilation pass.
  The `#ident' command is supported for compatibility with certain other systems. It is followed by a line of text. On some systems, the text is copied into a special place in the object file; on most systems, the text is ignored and this command has no effect. Typically `#ident' is only used in header files supplied with those systems where it is meaningful.' or `3'. If there are multiple flags, spaces separate them. Here is what the flags mean:
  Most often when you use the C preprocessor you will not have to invoke it explicitly: the C compiler will do so automatically. However, the preprocessor is sometimes useful on its own..
  Here is a table of command options accepted by the C preprocessor. These options can also be given when' commands..
  gccautomatically supplies this option to the preprocessor if you specify `-ansi', but
  gccdoesn't recognize the `-$' option itself--to use it without the other effects of `-ansi', you must call the preprocessor directly.
  Go to the next section.