home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 8 / FreshFishVol8-CD1.bin / gnu / info / cpp.info-1 (.txt) < prev    next >
GNU Info File  |  1994-12-22  |  49KB  |  909 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: Top,  Next: Global Actions,  Up: (DIR)
  17. The C Preprocessor
  18. ******************
  19.    The C preprocessor is a "macro processor" that is used automatically
  20. by the C compiler to transform your program before actual compilation.
  21. It is called a macro processor because it allows you to define "macros",
  22. which are brief abbreviations for longer constructs.
  23.    The C preprocessor provides four separate facilities that you can
  24. use as you see fit:
  25.    * Inclusion of header files.  These are files of declarations that
  26.      can be substituted into your program.
  27.    * Macro expansion.  You can define "macros", which are abbreviations
  28.      for arbitrary fragments of C code, and then the C preprocessor will
  29.      replace the macros with their definitions throughout the program.
  30.    * Conditional compilation.  Using special preprocessor commands, you
  31.      can include or exclude parts of the program according to various
  32.      conditions.
  33.    * Line control.  If you use a program to combine or rearrange source
  34.      files into an intermediate file which is then compiled, you can
  35.      use line control to inform the compiler of where each source line
  36.      originally came from.
  37.    C preprocessors vary in some details.  This manual discusses the GNU
  38. C preprocessor, the C Compatible Compiler Preprocessor.  The GNU C
  39. preprocessor provides a superset of the features of ANSI Standard C.
  40.    ANSI Standard C requires the rejection of many harmless constructs
  41. commonly used by today's C programs.  Such incompatibility would be
  42. inconvenient for users, so the GNU C preprocessor is configured to
  43. accept these constructs by default.  Strictly speaking, to get ANSI
  44. Standard C, you must use the options `-trigraphs', `-undef' and
  45. `-pedantic', but in practice the consequences of having strict ANSI
  46. Standard C make it undesirable to do this.  *Note Invocation::.
  47. * Menu:
  48. * Global Actions::    Actions made uniformly on all input files.
  49. * Commands::          General syntax of preprocessor commands.
  50. * Header Files::      How and why to use header files.
  51. * Macros::            How and why to use macros.
  52. * Conditionals::      How and why to use conditionals.
  53. * Combining Sources:: Use of line control when you combine source files.
  54. * Other Commands::    Miscellaneous preprocessor commands.
  55. * Output::            Format of output from the C preprocessor.
  56. * Invocation::        How to invoke the preprocessor; command options.
  57. * Concept Index::     Index of concepts and terms.
  58. * Index::             Index of commands, predefined macros and options.
  59. File: cpp.info,  Node: Global Actions,  Next: Commands,  Prev: Top,  Up: Top
  60. Transformations Made Globally
  61. =============================
  62.    Most C preprocessor features are inactive unless you give specific
  63. commands to request their use.  (Preprocessor commands are lines
  64. starting with `#'; *note Commands::.).  But there are three
  65. transformations that the preprocessor always makes on all the input it
  66. receives, even in the absence of commands.
  67.    * All C comments are replaced with single spaces.
  68.    * Backslash-Newline sequences are deleted, no matter where.  This
  69.      feature allows you to break long lines for cosmetic purposes
  70.      without changing their meaning.
  71.    * Predefined macro names are replaced with their expansions (*note
  72.      Predefined::.).
  73.    The first two transformations are done *before* nearly all other
  74. parsing and before preprocessor commands are recognized.  Thus, for
  75. example, you can split a line cosmetically with Backslash-Newline
  76. anywhere (except when trigraphs are in use; see below).
  77.      /*
  78.      */ # /*
  79.      */ defi\
  80.      ne FO\
  81.      O 10\
  82.      20
  83. is equivalent into `#define FOO 1020'.  You can split even an escape
  84. sequence with Backslash-Newline.  For example, you can split `"foo\bar"'
  85. between the `\' and the `b' to get
  86.      "foo\\
  87.      bar"
  88. This behavior is unclean: in all other contexts, a Backslash can be
  89. inserted in a string constant as an ordinary character by writing a
  90. double Backslash, and this creates an exception.  But the ANSI C
  91. standard requires it.  (Strict ANSI C does not allow Newlines in string
  92. constants, so they do not consider this a problem.)
  93.    But there are a few exceptions to all three transformations.
  94.    * C comments and predefined macro names are not recognized inside a
  95.      `#include' command in which the file name is delimited with `<'
  96.      and `>'.
  97.    * C comments and predefined macro names are never recognized within a
  98.      character or string constant.  (Strictly speaking, this is the
  99.      rule, not an exception, but it is worth noting here anyway.)
  100.    * Backslash-Newline may not safely be used within an ANSI "trigraph".
  101.      Trigraphs are converted before Backslash-Newline is deleted.  If
  102.      you write what looks like a trigraph with a Backslash-Newline
  103.      inside, the Backslash-Newline is deleted as usual, but it is then
  104.      too late to recognize the trigraph.
  105.      This exception is relevant only if you use the `-trigraphs' option
  106.      to enable trigraph processing.  *Note Invocation::.
  107. File: cpp.info,  Node: Commands,  Next: Header Files,  Prev: Global Actions,  Up: Top
  108. Preprocessor Commands
  109. =====================
  110.    Most preprocessor features are active only if you use preprocessor
  111. commands to request their use.
  112.    Preprocessor commands are lines in your program that start with `#'.
  113. The `#' is followed by an identifier that is the "command name".  For
  114. example, `#define' is the command that defines a macro.  Whitespace is
  115. also allowed before and after the `#'.
  116.    The set of valid command names is fixed.  Programs cannot define new
  117. preprocessor commands.
  118.    Some command names require arguments; these make up the rest of the
  119. command line and must be separated from the command name by whitespace.
  120. For example, `#define' must be followed by a macro name and the
  121. intended expansion of the macro.  *Note Simple Macros::.
  122.    A preprocessor command cannot be more than one line in normal
  123. circumstances.  It may be split cosmetically with Backslash-Newline,
  124. but that has no effect on its meaning.  Comments containing Newlines
  125. can also divide the command into multiple lines, but the comments are
  126. changed to Spaces before the command is interpreted.  The only way a
  127. significant Newline can occur in a preprocessor command is within a
  128. string constant or character constant.  Note that most C compilers that
  129. might be applied to the output from the preprocessor do not accept
  130. string or character constants containing Newlines.
  131.    The `#' and the command name cannot come from a macro expansion.  For
  132. example, if `foo' is defined as a macro expanding to `define', that
  133. does not make `#foo' a valid preprocessor command.
  134. File: cpp.info,  Node: Header Files,  Next: Macros,  Prev: Commands,  Up: Top
  135. Header Files
  136. ============
  137.    A header file is a file containing C declarations and macro
  138. definitions (*note Macros::.) to be shared between several source
  139. files.  You request the use of a header file in your program with the C
  140. preprocessor command `#include'.
  141. * Menu:
  142. * Header Uses::         What header files are used for.
  143. * Include Syntax::      How to write `#include' commands.
  144. * Include Operation::   What `#include' does.
  145. * Once-Only::        Preventing multiple inclusion of one header file.
  146. * Inheritance::         Including one header file in another header file.
  147. File: cpp.info,  Node: Header Uses,  Next: Include Syntax,  Prev: Header Files,  Up: Header Files
  148. Uses