home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Fresh Fish 1
/
FFMCD01.bin
/
useful
/
info
/
cpp.info-1
(
.txt
)
< prev
next >
Wrap
GNU Info File
|
1993-09-05
|
51KB
|
935 lines
This is Info file cpp.info, produced by Makeinfo-1.54 from the input
file cpp.texi.
This file documents the GNU C Preprocessor.
Copyright 1987, 1989, 1991, 1992, 1993 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the entire resulting derived work is distributed under the terms
of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.
File: cpp.info, Node: Top, Next: Global Actions, Up: (DIR)
The C Preprocessor
******************
The C preprocessor is a "macro processor" that is used automatically
by the C compiler to transform your program before actual compilation.
It is called a macro processor because it allows you to define "macros",
which are brief abbreviations for longer constructs.
The C preprocessor provides four separate facilities that you can
use as you see fit:
* Inclusion of header files. These are files of declarations that
can be substituted into your program.
* Macro expansion. You can define "macros", which are abbreviations
for arbitrary fragments of C code, and then the C preprocessor will
replace the macros with their definitions throughout the program.
* Conditional compilation. Using special preprocessor commands, you
can include or exclude parts of the program according to various
conditions.
* Line control. If you use a program to combine or rearrange source
files into an intermediate file which is then compiled, you can
use line control to inform the compiler of where each source line
originally came from.
C preprocessors vary in some details. This manual discusses the GNU
C preprocessor, the C Compatible Compiler Preprocessor. The GNU C
preprocessor provides a superset of the features of ANSI Standard C.
ANSI Standard C requires the rejection of many harmless constructs
commonly used by today's C programs. Such incompatibility would be
inconvenient for users, so the GNU C preprocessor is configured to
accept these constructs by default. Strictly speaking, to get ANSI
Standard C, you must use the options `-trigraphs', `-undef' and
`-pedantic', but in practice the consequences of having strict ANSI
Standard C make it undesirable to do this. *Note Invocation::.
* Menu:
* Global Actions:: Actions made uniformly on all input files.
* Commands:: General syntax of preprocessor commands.
* Header Files:: How and why to use header files.
* Macros:: How and why to use macros.
* Conditionals:: How and why to use conditionals.
* Combining Sources:: Use of line control when you combine source files.
* Other Commands:: Miscellaneous preprocessor commands.
* Output:: Format of output from the C preprocessor.
* Invocation:: How to invoke the preprocessor; command options.
* Concept Index:: Index of concepts and terms.
* Index:: Index of commands, predefined macros and options.
File: cpp.info, Node: Global Actions, Next: Commands, Prev: Top, Up: Top
Transformations Made Globally
=============================
Most C preprocessor features are inactive unless you give specific
commands to request their use. (Preprocessor commands are lines
starting with `#'; *note Commands::.). But there are three
transformations that the preprocessor always makes on all the input it
receives, even in the absence of commands.
* All C comments are replaced with single spaces.
* Backslash-Newline sequences are deleted, no matter where. This
feature allows you to break long lines for cosmetic purposes
without changing their meaning.
* Predefined macro names are replaced with their expansions (*note
Predefined::.).
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 behavior is unclean: in all other contexts, a Backslash can be
inserted in a string constant as an ordinary character by writing a
double Backslash, and this creates an exception. But the ANSI C
standard requires it. (Strict ANSI C does not allow Newlines in string
constants, so they do not consider this a problem.)
But there are a few exceptions to all three transformations.
* C comments and predefined macro names are not recognized inside a
`#include' command in which the file name is delimited with `<'
and `>'.
* C comments and predefined macro names are never recognized within a
character or string constant. (Strictly speaking, this is the
rule, not an exception, but it is worth noting here anyway.)
* Backslash-Newline may not safely be used within an ANSI "trigraph".
Trigraphs are converted before Backslash-Newline is deleted. If
you write what looks like a trigraph with a Backslash-Newline
inside, the Backslash-Newline is deleted as usual, but it is then
too late to recognize the trigraph.
This exception is relevant only if you use the `-trigraphs' option
to enable trigraph processing. *Note Invocation::.
File: cpp.info, Node: Commands, Next: Header Files, Prev: Global Actions, Up: Top
Preprocessor Commands
=====================
Most preprocessor features are active only if you use preprocessor
commands to request their use.
Preprocessor commands are lines in your program that start with `#'.
The `#' is followed by an identifier that is the "command name". For
example, `#define' is the command that defines a macro. Whitespace is
also allowed before and after the `#'.
The set of valid command names is fixed. Programs 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.
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 Newline can occur in a preprocessor command is within a
string constant or character constant. Note that most C compilers that
might be applied to the output from the preprocessor do not accept
string or character constants containing Newlines.
The `#' and the command name cannot come from a macro expansion. For
example, if `foo' is defined as a macro expanding to `define', that
does not make `#foo' a valid preprocessor command.
File: cpp.info, Node: Header Files, Next: Macros, Prev: Commands, Up: Top
Header Files
============
A header file is a file containing C declarations and macro
definitions (*note 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'.
* Menu:
* Header Uses:: What header files are used for.
* Include Syntax:: How to write `#include' commands.
* Include Operation:: What `#include' does.
* Once-Only:: Preventing multiple inclusion of one header file.
* Inheritance:: Including one header file in another header file.
File: cpp.info, Node: Header Uses, Next: Include Syntax, Prev: Header Files, Up: Header Files
Uses of Header Files
-------------