cpp.texi

早期freebsd实现

@node Include Operation, Once-Only, Include Syntax, Header Files
@subsection How @samp{#include} Works

The @samp{#include} command 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}
command.  For example, given two files as follows:

@example
/* File program.c */
int x;
#include "header.h"

main ()
@{
  printf (test ());
@}


/* File header.h */
char *test ();
@end example

@noindent
the output generated by the C preprocessor for @file{program.c} as input
would be

@example
int x;
char *test ();

main ()
@{
  printf (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.

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

@node Once-Only, Inheritance, Include Operation, Header Files
@subsection Once-Only Include Files
@cindex repeated inclusion

Very often, one header file includes another.  It can easily result that a
certain header file is included more than once.  This may lead to errors,
if the header file defines structure types or typedefs, and is certainly
wasteful.  Therefore, we often wish to prevent multiple inclusion of a
header file.

The standard way to do this is to enclose the entire real contents of the
file in a conditional, like this:

@example
#ifndef __FILE_FOO_SEEN__
#define __FILE_FOO_SEEN__

@var{the entire file}

#endif /* __FILE_FOO_SEEN__ */
@end example

The macro @code{__FILE_FOO_SEEN__} indicates that the file has been
included once already; its name should begin with @samp{__} to avoid
conflicts with user programs, and it should contain the name of the file
and some additional text, to avoid conflicts with other header files.

The GNU C preprocessor is programmed to notice when a header file uses
this particular construct and handle it efficiently.  If a header file
is contained entirely in a @samp{#ifndef} conditional, then it records
that fact.  If a subsequent @samp{#include} specifies the same file,
and the macro in the @samp{#ifndef} is already defined, then the file
is entirely skipped, without even reading it.

@findex #pragma once
There is also an explicit command to tell the preprocessor that it need
not include a file more than once.  This is called @samp{#pragma once},
and was used @emph{in addition to} the @samp{#ifndef} conditional around
the contents of the header file.  @samp{#pragma once} is now obsolete
and should not be used at all.

In the Objective C language, there is a variant of @samp{#include}
called @samp{#import} which includes a file, but does so at most once.
If you use @samp{#import} @emph{instead of} @samp{#include}, then you
don't need the conditionals inside the header file to prevent multiple
execution of the contents.

@samp{#import} is obsolete because it is not a well-designed feature.
It requires the users of a header file---the applications
programmers---to know that a certain header file should only be included
once.  It is much better for the header file's implementor to write the
file so that users don't need to know this.  Using @samp{#ifndef}
accomplishes this goal.

@node Inheritance,, Once-Only, Header Files
@section Inheritance and Header Files
@cindex inheritance
@cindex overriding a header file

@dfn{Inheritance} is what happens when one object or file derives some
of its contents by virtual copying from another object or file.  In
the case of C header files, inheritance means that one header file 
includes another header file and then replaces or adds something.

If the inheriting header file and the base header file have different
names, then inheritance is straightforward: simply write @samp{#include
"@var{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
@file{sys/signal.h}, but the version of @file{/usr/include/sys/signal.h}
on a particular system doesn't do what the application program expects.
It might be convenient to define a ``local'' version, perhaps under the
name @file{/usr/local/include/sys/signal.h}, to override or add to the
one supplied by the system.

You can do this by using the option @samp{-I.} for compilation, and
writing a file @file{sys/signal.h} that does what the application
program expects.  But making this file include the standard
@file{sys/signal.h} is not so easy---writing @samp{#include
<sys/signal.h>} in that file doesn't work, because it includes your own
version of the file, not the standard system version.  Used in that file
itself, this leads to an infinite recursion and a fatal error in
compilation.

@samp{#include </usr/include/sys/signal.h>} would find the proper file,
but that is not clean, since it makes an assumption about where the
system header file is found.  This is bad for maintenance, since it
means that any change in where the system's header files are kept
requires a change somewhere else.

@findex #include_next
The clean way to solve this problem is to use 
@samp{#include_next}, which means, ``Include the @emph{next} file with
this name.''  This command 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 @samp{-I /usr/local/include}, and the list of
directories to search also includes @file{/usr/include}; and suppose that
both directories contain a file named @file{sys/signal.h}.  Ordinary
@samp{#include <sys/signal.h>} finds the file under
@file{/usr/local/include}.  If that file contains @samp{#include_next
<sys/signal.h>}, it starts searching after that directory, and finds the
file in @file{/usr/include}.

@node Macros, Conditionals, Header Files, Top
@section Macros

A macro is a sort of abbreviation which you can define once and then
use later.  There are many complicated features associated with macros
in the C preprocessor.

@menu
* Simple Macros::    Macros that always expand the same way.
* Argument Macros::  Macros that accept arguments that are substituted
                       into the macro expansion.
* Predefined::       Predefined macros that are always available.
* Stringification::  Macro arguments converted into string constants.
* Concatenation::    Building tokens from parts taken from macro arguments.
* Undefining::       Cancelling a macro's definition.
* Redefining::       Changing a macro's definition.
* Macro Pitfalls::   Macros can confuse the unwary.  Here we explain
                       several common problems and strange features.
@end menu

@node Simple Macros, Argument Macros, Macros, Macros
@subsection Simple Macros

A @dfn{simple macro} is a kind of abbreviation.  It is a name which
stands for a fragment of code.  Some people refer to these as
@dfn{manifest constants}.

Before you can use a macro, you must @dfn{define} it explicitly with the
@samp{#define} command.  @samp{#define} is followed by the name of the
macro and then the code it should be an abbreviation for.  For example,

@example
#define BUFFER_SIZE 1020
@end example

@noindent
defines a macro named @samp{BUFFER_SIZE} as an abbreviation for the text
@samp{1020}.  Therefore, if somewhere after this @samp{#define} command
there comes a C statement of the form

@example
foo = (char *) xmalloc (BUFFER_SIZE);
@end example

@noindent
then the C preprocessor will recognize and @dfn{expand} the macro
@samp{BUFFER_SIZE}, resulting in

@example
foo = (char *) xmalloc (1020);
@end example

@noindent
the definition must be a single line; however, it may not end in the
middle of a multi-line string constant or character constant.

The use of all upper case for macro names is a standard convention.
Programs are easier to read when it is possible to tell at a glance which
names are macros.

Normally, a macro definition must be a single line, like all C preprocessor
commands.  (You can split a long macro definition cosmetically with
Backslash-Newline.)  There is one exception: Newlines can be included in
the macro definition if within a string or character constant.  By the same
token, it is not possible for a macro definition to contain an unbalanced
quote character; the definition automatically extends to include the
matching quote character that ends the string or character constant.
Comments within a macro definition may contain Newlines, which make no
difference since the comments are entirely replaced with Spaces regardless
of their contents.

Aside from the above, there is no restriction on what can go in a macro
body.  Parentheses need not balance.  The body need not resemble valid C
code.  (Of course, you might get error messages from the C compiler when
you use the macro.)

The C preprocessor scans your program sequentially, so macro definitions
take effect at the place you write them.  Therefore, the following input to
the C preprocessor

@example
foo = X;
#define X 4
bar = X;
@end example

@noindent
produces as output

@example
foo = X;

bar = 4;
@end example

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

@example
#define BUFSIZE 1020
#define TABLESIZE BUFSIZE
@end example

@noindent
the name @samp{TABLESIZE} when used in the program would go through two
stages of expansion, resulting ultimately in @samp{1020}.

This is not at all the same as defining @samp{TABLESIZE} to be @samp{1020}.
The @samp{#define} for @samp{TABLESIZE} uses exactly the body you
specify---in this case, @samp{BUFSIZE}---and does not check to see whether
it too is the name of a macro.  It's only when you @emph{use} @samp{TABLESIZE}
that the result of its expansion is checked for more macro names.
@xref{Cascaded Macros}.

@node Argument Macros, Predefined, Simple Macros, Macros
@subsection Macros with Arguments

A simple macro always stands for exactly the same text, each time it is
used.  Macros can be more flexible when they accept @dfn{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.

To define a macro that uses arguments, you write a @samp{#define} command
with a list of @dfn{argument names} in parentheses after the name of the
macro.  The argument names may be any valid C identifiers, separated by
commas and optionally whitespace.  The open-parenthesis must follow the
macro name immediately, with no space in between.

For example, here is a macro that computes the minimum of two numeric
values, as it is defined in many C programs:

@example
#define min(X, Y)  ((X) < (Y) ? (X) : (Y))
@end example

@noindent
(This is not the best way to define a ``minimum'' macro in GNU C.
@xref{Side Effects}, for more information.)

To use a macro that expects arguments, you write the name of the macro
followed by a list of @dfn{actual arguments} in parentheses. separated by
commas.  The number of actual arguments you give must match the number of
arguments the macro expects.   Examples of use of the macro @samp{min}
include @samp{min (1, 2)} and @samp{min (x + 28, *p)}.

The expansion text of the macro depends on the arguments 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 @samp{min} defined above, @samp{min (1, 2)} expands into

@example
((1) < (2) ? (1) : (2))
@end example

@noindent
where @samp{1} has been substituted for @samp{X} and @samp{2} for @samp{Y}.

Likewise, @samp{min (x + 28, *p)} expands into

@example
((x + 28) < (*p) ? (x + 28) : (*p))
@end example

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,

@example
macro (array[x = y, x + 1])
@end example

@noindent
passes two arguments to @code{macro}: @samp{array[x = y} and @samp{x +
1]}.  If you want to supply @samp{array[x = y, x + 1]} as an argument,
you must write it as @samp{array[(x = y, x + 1)]}, which is equivalent C
code.

After the actual arguments are substituted into the macro body, the entire
result is appended to the front of the remaining input, and the check for
macro calls continues.  Therefore, the actual arguments can contain calls
to other macros, either with or without arguments, or even to the same
macro.  The macro body can also contain calls to other macros.  For
example, @samp{min (min (a, b), c)} expands into this text: