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