cpp.texi

一个能在WIN32环境下使用GCC的功能进行程序设计的SHE

@file{.h}.  It is most portable to use only letters, digits, dashes, and
underscores in header file names, and at most one dot.

@menu
* Include Syntax::
* Include Operation::
* Search Path::
* Once-Only Headers::
* Computed Includes::
* Wrapper Headers::
* System Headers::
@end menu

@node Include Syntax
@section Include Syntax

@findex #include
Both user and system header files are included using the preprocessing
directive @samp{#include}.  It has two variants:

@table @code
@item #include <@var{file}>
This variant is used for system header files.  It searches for a file
named @var{file} in a standard list of system directories.  You can prepend
directories to this list with the @option{-I} option (@pxref{Invocation}).

@item #include "@var{file}"
This variant is used for header files of your own program.  It searches
for a file named @var{file} first in the directory containing the
current file, then in the same directories used for @code{<@var{file}>}.
@end table

The argument of @samp{#include}, whether delimited with quote marks or
angle brackets, behaves like a string constant in that comments are not
recognized, and macro names are not expanded.  Thus, @code{@w{#include
<x/*y>}} specifies inclusion of a system header file named @file{x/*y}.

However, if backslashes occur within @var{file}, they are considered
ordinary text characters, not escape characters.  None of the character
escape sequences appropriate to string constants in C are processed.
Thus, @code{@w{#include "x\n\\y"}} specifies a filename containing three
backslashes.  (Some systems interpret @samp{\} as a pathname separator.
All of these also interpret @samp{/} the same way.  It is most portable
to use only @samp{/}.)

It is an error if there is anything (other than comments) on the line
after the file name.

@node Include Operation
@section Include Operation

The @samp{#include} directive works by directing the C preprocessor to
scan the specified file as input before continuing with the rest of the
current file.  The output from the preprocessor contains the output
already generated, followed by the output resulting from the included
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
char *test (void);
@end example

@noindent
and a main program called @file{program.c} that uses the header file,
like this,

@example
int x;
#include "header.h"

int
main (void)
@{
  puts (test ());
@}
@end example

@noindent
the compiler will see the same token stream as it would if
@file{program.c} read

@example
int x;
char *test (void);

int
main (void)
@{
  puts (test ());
@}
@end example

Included files are not limited to declarations and macro definitions;
those are merely the typical uses.  Any fragment of a C program can be
included from another file.  The include file could even contain the
beginning of a statement that is concluded in the containing file, or
the end of a statement that was started in the including file.  However,
a comment or a string or character constant may not start in the
included file and finish in the including file.  An unterminated
comment, string constant or character constant in an included file is
considered to end (with an error message) at the end of the file.

To avoid confusion, it is best if header files contain only complete
syntactic units---function declarations or definitions, type
declarations, etc.

The line following the @samp{#include} directive is always treated as a
separate line by the C preprocessor, even if the included file lacks a
final newline.

@node Search Path
@section Search Path

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
/usr/local/include
/usr/lib/gcc-lib/@var{target}/@var{version}/include
/usr/@var{target}/include
/usr/include
@end example

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
GCC was configured to compile code for; often but not always the same as
the canonical name of the system it runs on.  @var{version} is the
version of GCC in use.

You can add to this list with the @option{-I@var{dir}} command line
option.  All the directories named by @option{-I} are searched, in
left-to-right order, @emph{before} the default directories.  You can
also prevent GCC from searching any of the default directories with the
@option{-nostdinc} option.  This is useful when you are compiling an
operating system kernel or some other program that does not use the
standard C library facilities, or the standard C library itself.

GCC looks for headers requested with @code{@w{#include "@var{file}"}}
first in the directory containing the current file, then in the same
places it would have looked for a header requested with angle brackets.
For example, if @file{/usr/include/sys/stat.h} contains
@code{@w{#include "types.h"}}, GCC looks for @file{types.h} first in
@file{/usr/include/sys}, then in its usual search path.

@samp{#line} (@pxref{Line Control}) does not change GCC's idea of the
directory containing the current file.

You may put @option{-I-} at any point in your list of @option{-I} options.
This has two effects.  First, directories appearing before the
@option{-I-} in the list are searched only for headers requested with
quote marks.  Directories after @option{-I-} are searched for all
headers.  Second, the directory containing the current file is not
searched for anything, unless it happens to be one of the directories
named by an @option{-I} switch.

@option{-I. -I-} is not the same as no @option{-I} options at all, and does
not cause the same behavior for @samp{<>} includes that @samp{""}
includes get with no special options.  @option{-I.} searches the
compiler's current working directory for header files.  That may or may
not be the same as the directory containing the current file.

If you need to look for headers in a directory named @file{-}, write
@option{-I./-}.

There are several more ways to adjust the header search path.  They are
less generally useful.  @xref{Invocation}.

@node Once-Only Headers
@section Once-Only Headers
@cindex repeated inclusion
@cindex including just once
@cindex wrapper @code{#ifndef}

If a header file happens to be included twice, the compiler will process
its contents twice.  This is very likely to cause an error, e.g. when the
compiler sees the same structure definition twice.  Even if it does not,
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
@group
/* File foo.  */
#ifndef FILE_FOO_SEEN
#define FILE_FOO_SEEN

@var{the entire file}

#endif /* FILE_FOO_SEEN */
@end group
@end example

This construct is commonly known as a @dfn{wrapper #ifndef}.
When the header is included again, the conditional will be false,
because @code{FILE_FOO_SEEN} is defined.  The preprocessor will skip
over the entire contents of the file, and the compiler will not see it
twice.

GNU CPP optimizes even further.  It remembers when a header file has a
wrapper @samp{#ifndef}.  If a subsequent @samp{#include} specifies that
header, and the macro in the @samp{#ifndef} is still defined, it does
not bother to rescan the file at all.

You can put comments outside the wrapper.  They will not interfere with
this optimization.

@cindex controlling macro
@cindex guard macro
The macro @code{FILE_FOO_SEEN} is called the @dfn{controlling macro} or
@dfn{guard macro}.  In a user header file, the macro name should not
begin with @samp{_}.  In a system header file, it should begin with
@samp{__} to avoid conflicts with user programs.  In any kind of header
file, the macro name should contain the name of the file and some
additional text, to avoid conflicts with other header files.

@node Computed Includes
@section Computed Includes
@cindex computed includes
@cindex macros in include

Sometimes it is necessary to select one of several different header
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
#if SYSTEM_1
# include "system_1.h"
#elif SYSTEM_2
# include "system_2.h"
#elif SYSTEM_3
@dots{}
#endif
@end example

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
#define SYSTEM_H "system_1.h"
@dots{}
#include SYSTEM_H
@end example

@noindent
@code{SYSTEM_H} will be expanded, and the preprocessor will look for
@file{system_1.h} as if the @samp{#include} had been written that way
originally.  @code{SYSTEM_H} could be defined by your Makefile with a
@option{-D} option.

You must be careful when you define the macro.  @samp{#define} saves
tokens, not text.  The preprocessor has no way of knowing that the macro
will be used as the argument of @samp{#include}, so it generates
ordinary tokens, not a header name.  This is unlikely to cause problems
if you use double-quote includes, which are close enough to string
constants.  If you use angle brackets, however, you may have trouble.

The syntax of a computed include is actually a bit more general than the
above.  If the first non-whitespace character after @samp{#include} is
not @samp{"} or @samp{<}, then the entire line is macro-expanded
like running text would be.

If the line expands to a single string constant, the contents of that
string constant are the file to be included.  CPP does not reexamine the
string for embedded quotes, but neither does it process backslash
escapes in the string.  Therefore

@example
#define HEADER "a\"b"
#include HEADER
@end example

@noindent
looks for a file named @file{a\"b}.  CPP searches for the file according
to the rules for double-quoted includes.

If the line expands to a token stream beginning with a @samp{<} token
and including a @samp{>} token, then the tokens between the @samp{<} and
the first @samp{>} are combined to form the filename to be included.
Any whitespace between tokens is reduced to a single space; then any
space after the initial @samp{<} is retained, but a trailing space
before the closing @samp{>} is ignored.  CPP searches for the file
according to the rules for angle-bracket includes.

In either case, if there are any tokens on the line after the file name,
an error occurs and the directive is not processed.  It is also an error
if the result of expansion does not match either of the two expected
forms.

These rules are implementation-defined behavior according to the C
standard.  To minimize the risk of different compilers interpreting your
computed includes differently, we recommend you use only a single
object-like macro which expands to a string constant.  This will also
minimize confusion of people reading your program.

@node Wrapper Headers
@section Wrapper Headers
@cindex wrapper headers
@cindex overriding a header file
@findex #include_next

Sometimes it is necessary to adjust the contents of a system-provided
header file without editing it directly.  GCC's @command{fixincludes}
operation does this, for example.  One way to do that would be to create
a new header file with the same name and insert it in the search path
before the original header.  That works fine as long as you're willing
to replace the old header entirely.  But what if you want to refer to
the old header from the new one?

You cannot simply include the old header with @samp{#include}.  That
will start from the beginning, and find your new header again.  If your
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
#include "/usr/include/old-header.h"
@end example
@noindent
This works, but is not clean; should the system headers ever move, you
would have to edit the new headers to match.

There is no way to solve this problem within the C standard, but you can
use the GNU extension @samp{#include_next}.  It means, ``Include the
@emph{next} file with this name.''  This directive works like
@samp{#include} except in searching for the specified file: it starts
searching the list of header file directories @emph{after} the directory
in which the current file was found.

Suppose you specify @option{-I /usr/local/include}, and the list of
directories to search also includes @file{/usr/include}; and suppose
both directories contain @file{signal.h}.  Ordinary @code{@w{#include
<signal.h>}} finds the file under @file{/usr/local/include}.  If that
file contains @code{@w{#include_next <signal.h>}}, it starts searching
after that directory, and finds the file in @file{/usr/include}.

@samp{#include_next} does not distinguish between @code{<@var{file}>}
and @code{"@var{file}"} inclusion, nor does it check that the file you
specify has the same name as the current file.  It simply looks for the
file named, starting with the directory in the search path after the one