Subversion Repositories openrisc

\input texinfo

@setfilename cpp.info

@settitle The C Preprocessor

@setchapternewpage off

@c @smallbook

@c @cropmarks

@c @finalout

@include gcc-common.texi

@copying

@c man begin COPYRIGHT

Copyright @copyright{} 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996,

1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005

Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document

under the terms of the GNU Free Documentation License, Version 1.1 or

any later version published by the Free Software Foundation.  A copy of

the license is included in the

@c man end

section entitled ``GNU Free Documentation License''.

@ignore

@c man begin COPYRIGHT

man page gfdl(7).

@c man end

@end ignore

@c man begin COPYRIGHT

This manual contains no Invariant Sections.  The Front-Cover Texts are

(a) (see below), and the Back-Cover Texts are (b) (see below).

(a) The FSF's Front-Cover Text is:

     A GNU Manual

(b) The FSF's Back-Cover Text is:

     You have freedom to copy and modify this GNU Manual, like GNU

     software.  Copies published by the Free Software Foundation raise

     funds for GNU development.

@c man end

@end copying

@c Create a separate index for command line options.

@defcodeindex op

@syncodeindex vr op

@c Used in cppopts.texi and cppenv.texi.

@set cppmanual

@ifinfo

@dircategory Software development

@direntry

* Cpp: (cpp).                  The GNU C preprocessor.

@end direntry

@end ifinfo

@titlepage

@title The C Preprocessor

@versionsubtitle

@author Richard M. Stallman, Zachary Weinberg

@page

@c There is a fill at the bottom of the page, so we need a filll to

@c override it.

@vskip 0pt plus 1filll

@insertcopying

@end titlepage

@contents

@page

@ifnottex

@node Top

@top

The C preprocessor implements the macro language used to transform C,

C++, and Objective-C programs before they are compiled.  It can also be

useful on its own.

@menu

* Overview::

* Header Files::

* Macros::

* Conditionals::

* Diagnostics::

* Line Control::

* Pragmas::

* Other Directives::

* Preprocessor Output::

* Traditional Mode::

* Implementation Details::

* Invocation::

* Environment Variables::

* GNU Free Documentation License::

* Index of Directives::

* Option Index::

* Concept Index::

@detailmenu

 --- The Detailed Node Listing ---

Overview

* Character sets::

* Initial processing::

* Tokenization::

* The preprocessing language::

Header Files

* Include Syntax::

* Include Operation::

* Search Path::

* Once-Only Headers::

* Computed Includes::

* Wrapper Headers::

* System Headers::

Macros

* Object-like Macros::

* Function-like Macros::

* Macro Arguments::

* Stringification::

* Concatenation::

* Variadic Macros::

* Predefined Macros::

* Undefining and Redefining Macros::

* Directives Within Macro Arguments::

* Macro Pitfalls::

Predefined Macros

* Standard Predefined Macros::

* Common Predefined Macros::

* System-specific Predefined Macros::

* C++ Named Operators::

Macro Pitfalls

* Misnesting::

* Operator Precedence Problems::

* Swallowing the Semicolon::

* Duplication of Side Effects::

* Self-Referential Macros::

* Argument Prescan::

* Newlines in Arguments::

Conditionals

* Conditional Uses::

* Conditional Syntax::

* Deleted Code::

Conditional Syntax

* Ifdef::

* If::

* Defined::

* Else::

* Elif::

Implementation Details

* Implementation-defined behavior::

* Implementation limits::

* Obsolete Features::

* Differences from previous versions::

Obsolete Features

* Assertions::

* Obsolete once-only headers::

@end detailmenu

@end menu

@insertcopying

@end ifnottex

@node Overview

@chapter Overview

@c man begin DESCRIPTION

The C preprocessor, often known as @dfn{cpp}, is a @dfn{macro processor}

that is used automatically by the C compiler to transform your program

before compilation.  It is called a macro processor because it allows

you to define @dfn{macros}, which are brief abbreviations for longer

constructs.

The C preprocessor is intended to be used only with C, C++, and

Objective-C source code.  In the past, it has been abused as a general

text processor.  It will choke on input which does not obey C's lexical

rules.  For example, apostrophes will be interpreted as the beginning of

character constants, and cause errors.  Also, you cannot rely on it

preserving characteristics of the input which are not significant to

C-family languages.  If a Makefile is preprocessed, all the hard tabs

will be removed, and the Makefile will not work.

Having said that, you can often get away with using cpp on things which

are not C@.  Other Algol-ish programming languages are often safe

(Pascal, Ada, etc.) So is assembly, with caution.  @option{-traditional-cpp}

mode preserves more white space, and is otherwise more permissive.  Many

of the problems can be avoided by writing C or C++ style comments

instead of native language comments, and keeping macros simple.

Wherever possible, you should use a preprocessor geared to the language

you are writing in.  Modern versions of the GNU assembler have macro

facilities.  Most high level programming languages have their own

conditional compilation and inclusion mechanism.  If all else fails,

try a true general text processor, such as GNU M4.

C preprocessors vary in some details.  This manual discusses the GNU C

preprocessor, which provides a small superset of the features of ISO

Standard C@.  In its default mode, the GNU C preprocessor does not do a

few things required by the standard.  These are features which are

rarely, if ever, used, and may cause surprising changes to the meaning

of a program which does not expect them.  To get strict ISO Standard C,

you should use the @option{-std=c89} or @option{-std=c99} options, depending

on which version of the standard you want.  To get all the mandatory

diagnostics, you must also use @option{-pedantic}.  @xref{Invocation}.

This manual describes the behavior of the ISO preprocessor.  To

minimize gratuitous differences, where the ISO preprocessor's

behavior does not conflict with traditional semantics, the

traditional preprocessor should behave the same way.  The various

differences that do exist are detailed in the section @ref{Traditional

Mode}.

For clarity, unless noted otherwise, references to @samp{CPP} in this

manual refer to GNU CPP@.

@c man end

@menu

* Character sets::

* Initial processing::

* Tokenization::

* The preprocessing language::

@end menu

@node Character sets

@section Character sets

Source code character set processing in C and related languages is

rather complicated.  The C standard discusses two character sets, but

there are really at least four.

The files input to CPP might be in any character set at all.  CPP's

very first action, before it even looks for line boundaries, is to

convert the file into the character set it uses for internal

processing.  That set is what the C standard calls the @dfn{source}

character set.  It must be isomorphic with ISO 10646, also known as

Unicode.  CPP uses the UTF-8 encoding of Unicode.

The character sets of the input files are specified using the

@option{-finput-charset=} option.

All preprocessing work (the subject of the rest of this manual) is

carried out in the source character set.  If you request textual

output from the preprocessor with the @option{-E} option, it will be

in UTF-8.

After preprocessing is complete, string and character constants are

converted again, into the @dfn{execution} character set.  This

character set is under control of the user; the default is UTF-8,

matching the source character set.  Wide string and character

constants have their own character set, which is not called out

specifically in the standard.  Again, it is under control of the user.

The default is UTF-16 or UTF-32, whichever fits in the target's

@code{wchar_t} type, in the target machine's byte

order.@footnote{UTF-16 does not meet the requirements of the C

standard for a wide character set, but the choice of 16-bit

@code{wchar_t} is enshrined in some system ABIs so we cannot fix

this.}  Octal and hexadecimal escape sequences do not undergo

conversion; @t{'\x12'} has the value 0x12 regardless of the currently

selected execution character set.  All other escapes are replaced by

the character in the source character set that they represent, then

converted to the execution character set, just like unescaped

characters.

Unless the experimental @option{-fextended-identifiers} option is used,

GCC does not permit the use of characters outside the ASCII range, nor

@samp{\u} and @samp{\U} escapes, in identifiers.  Even with that

option, characters outside the ASCII range can only be specified with

the @samp{\u} and @samp{\U} escapes, not used directly in identifiers.

@node Initial processing

@section Initial processing

The preprocessor performs a series of textual transformations on its

input.  These happen before all other processing.  Conceptually, they

happen in a rigid order, and the entire file is run through each

transformation before the next one begins.  CPP actually does them

all at once, for performance reasons.  These transformations correspond

roughly to the first three ``phases of translation'' described in the C

standard.

@enumerate

@item

@cindex line endings

The input file is read into memory and broken into lines.

Different systems use different conventions to indicate the end of a

line.  GCC accepts the ASCII control sequences @kbd{LF}, @kbd{@w{CR

LF}} and @kbd{CR} as end-of-line markers.  These are the canonical

sequences used by Unix, DOS and VMS, and the classic Mac OS (before

OSX) respectively.  You may therefore safely copy source code written

on any of those systems to a different one and use it without

conversion.  (GCC may lose track of the current line number if a file

doesn't consistently use one convention, as sometimes happens when it

is edited on computers with different conventions that share a network

file system.)

If the last line of any input file lacks an end-of-line marker, the end

of the file is considered to implicitly supply one.  The C standard says

that this condition provokes undefined behavior, so GCC will emit a

warning message.

@item

@cindex trigraphs

@anchor{trigraphs}If trigraphs are enabled, they are replaced by their

corresponding single characters.  By default GCC ignores trigraphs,

but if you request a strictly conforming mode with the @option{-std}

option, or you specify the @option{-trigraphs} option, then it

converts them.

These are nine three-character sequences, all starting with @samp{??},

that are defined by ISO C to stand for single characters.  They permit

obsolete systems that lack some of C's punctuation to use C@.  For

example, @samp{??/} stands for @samp{\}, so @t{'??/n'} is a character

constant for a newline.

Trigraphs are not popular and many compilers implement them

incorrectly.  Portable code should not rely on trigraphs being either

converted or ignored.  With @option{-Wtrigraphs} GCC will warn you

when a trigraph may change the meaning of your program if it were

converted.  @xref{Wtrigraphs}.

In a string constant, you can prevent a sequence of question marks

from being confused with a trigraph by inserting a backslash between

the question marks, or by separating the string literal at the

trigraph and making use of string literal concatenation.  @t{"(??\?)"}

is the string @samp{(???)}, not @samp{(?]}.  Traditional C compilers

do not recognize these idioms.

The nine trigraphs and their replacements are

@smallexample

Trigraph:       ??(  ??)  ??<  ??>  ??=  ??/  ??'  ??!  ??-

Replacement:      [    ]    @{    @}    #    \    ^    |    ~

@end smallexample

@item

@cindex continued lines

@cindex backslash-newline

Continued lines are merged into one long line.

A continued line is a line which ends with a backslash, @samp{\}.  The

backslash is removed and the following line is joined with the current

one.  No space is inserted, so you may split a line anywhere, even in

the middle of a word.  (It is generally more readable to split lines

only at white space.)

The trailing backslash on a continued line is commonly referred to as a

@dfn{backslash-newline}.

If there is white space between a backslash and the end of a line, that

is still a continued line.  However, as this is usually the result of an

editing mistake, and many compilers will not accept it as a continued

line, GCC will warn you about it.

@item

@cindex comments

@cindex line comments

@cindex block comments

All comments are replaced with single spaces.

There are two kinds of comments.  @dfn{Block comments} begin with

@samp{/*} and continue until the next @samp{*/}.  Block comments do not

nest:

@smallexample

/* @r{this is} /* @r{one comment} */ @r{text outside comment}

@end smallexample

@dfn{Line comments} begin with @samp{//} and continue to the end of the

current line.  Line comments do not nest either, but it does not matter,

because they would end in the same place anyway.

@smallexample

// @r{this is} // @r{one comment}

@r{text outside comment}

@end smallexample

@end enumerate

It is safe to put line comments inside block comments, or vice versa.

@smallexample

@group

/* @r{block comment}

   // @r{contains line comment}

   @r{yet more comment}

 */ @r{outside comment}

// @r{line comment} /* @r{contains block comment} */

@end group

@end smallexample

But beware of commenting out one end of a block comment with a line

comment.

@smallexample

@group

 // @r{l.c.}  /* @r{block comment begins}

    @r{oops! this isn't a comment anymore} */

@end group

@end smallexample

Comments are not recognized within string literals.

@t{@w{"/* blah */"}} is the string constant @samp{@w{/* blah */}}, not

an empty string.

Line comments are not in the 1989 edition of the C standard, but they

are recognized by GCC as an extension.  In C++ and in the 1999 edition

of the C standard, they are an official part of the language.

Since these transformations happen before all other processing, you can

split a line mechanically with backslash-newline anywhere.  You can

comment out the end of a line.  You can continue a line comment onto the

next line with backslash-newline.  You can even split @samp{/*},

@samp{*/}, and @samp{//} onto multiple lines with backslash-newline.

For example:

@smallexample

@group

/\

*

*/ # /*

*/ defi\

ne FO\

O 10\

20

@end group

@end smallexample

@noindent

is equivalent to @code{@w{#define FOO 1020}}.  All these tricks are

extremely confusing and should not be used in code intended to be

readable.

There is no way to prevent a backslash at the end of a line from being

interpreted as a backslash-newline.  This cannot affect any correct

program, however.

@node Tokenization

@section Tokenization

@cindex tokens

@cindex preprocessing tokens

After the textual transformations are finished, the input file is

converted into a sequence of @dfn{preprocessing tokens}.  These mostly

correspond to the syntactic tokens used by the C compiler, but there are

a few differences.  White space separates tokens; it is not itself a

token of any kind.  Tokens do not have to be separated by white space,

but it is often necessary to avoid ambiguities.

When faced with a sequence of characters that has more than one possible

tokenization, the preprocessor is greedy.  It always makes each token,

starting from the left, as big as possible before moving on to the next

token.  For instance, @code{a+++++b} is interpreted as

@code{@w{a ++ ++ + b}}, not as @code{@w{a ++ + ++ b}}, even though the

latter tokenization could be part of a valid C program and the former

could not.

Once the input file is broken into tokens, the token boundaries never

change, except when the @samp{##} preprocessing operator is used to paste

tokens together.  @xref{Concatenation}.  For example,

@smallexample

@group

#define foo() bar

foo()baz

     @expansion{} bar baz

@emph{not}

     @expansion{} barbaz

@end group

@end smallexample

The compiler does not re-tokenize the preprocessor's output.  Each

preprocessing token becomes one compiler token.

@cindex identifiers

Preprocessing tokens fall into five broad classes: identifiers,

preprocessing numbers, string literals, punctuators, and other.  An

@dfn{identifier} is the same as an identifier in C: any sequence of

letters, digits, or underscores, which begins with a letter or

underscore.  Keywords of C have no significance to the preprocessor;

they are ordinary identifiers.  You can define a macro whose name is a

keyword, for instance.  The only identifier which can be considered a

preprocessing keyword is @code{defined}.  @xref{Defined}.

This is mostly true of other languages which use the C preprocessor.

However, a few of the keywords of C++ are significant even in the

preprocessor.  @xref{C++ Named Operators}.

In the 1999 C standard, identifiers may contain letters which are not

part of the ``basic source character set'', at the implementation's

discretion (such as accented Latin letters, Greek letters, or Chinese

ideograms).  This may be done with an extended character set, or the

@samp{\u} and @samp{\U} escape sequences.  The implementation of this

feature in GCC is experimental; such characters are only accepted in

the @samp{\u} and @samp{\U} forms and only if

@option{-fextended-identifiers} is used.

As an extension, GCC treats @samp{$} as a letter.  This is for

compatibility with some systems, such as VMS, where @samp{$} is commonly

used in system-defined function and object names.  @samp{$} is not a

letter in strictly conforming mode, or if you specify the @option{-$}

option.  @xref{Invocation}.

@cindex numbers

@cindex preprocessing numbers

A @dfn{preprocessing number} has a rather bizarre definition.  The

category includes all the normal integer and floating point constants

one expects of C, but also a number of other things one might not

initially recognize as a number.  Formally, preprocessing numbers begin

with an optional period, a required decimal digit, and then continue

with any sequence of letters, digits, underscores, periods, and

exponents.  Exponents are the two-character sequences @samp{e+},

@samp{e-}, @samp{E+}, @samp{E-}, @samp{p+}, @samp{p-}, @samp{P+}, and

@samp{P-}.  (The exponents that begin with @samp{p} or @samp{P} are new

to C99.  They are used for hexadecimal floating-point constants.)

The purpose of this unusual definition is to isolate the preprocessor

from the full complexity of numeric constants.  It does not have to

distinguish between lexically valid and invalid floating-point numbers,

which is complicated.  The definition also permits you to split an

identifier at any position and get exactly two tokens, which can then be

pasted back together with the @samp{##} operator.

It's possible for preprocessing numbers to cause programs to be

misinterpreted.  For example, @code{0xE+12} is a preprocessing number

which does not translate to any valid numeric constant, therefore a

syntax error.  It does not mean @code{@w{0xE + 12}}, which is what you

might have intended.

@cindex string literals

@cindex string constants

@cindex character constants

@cindex header file names

@c the @: prevents makeinfo from turning '' into ".

@dfn{String literals} are string constants, character constants, and

header file names (the argument of @samp{#include}).@footnote{The C

standard uses the term @dfn{string literal} to refer only to what we are

calling @dfn{string constants}.}  String constants and character

constants are straightforward: @t{"@dots{}"} or @t{'@dots{}'}.  In

either case embedded quotes should be escaped with a backslash:

@t{'\'@:'} is the character constant for @samp{'}.  There is no limit on

the length of a character constant, but the value of a character

constant that contains more than one character is

implementation-defined.  @xref{Implementation Details}.

Header file names either look like string constants, @t{"@dots{}"}, or are

written with angle brackets instead, @t{<@dots{}>}.  In either case,

backslash is an ordinary character.  There is no way to escape the

closing quote or angle bracket.  The preprocessor looks for the header

file in different places depending on which form you use.  @xref{Include

Operation}.

No string literal may extend past the end of a line.  Older versions

of GCC accepted multi-line string constants.  You may use continued

lines instead, or string constant concatenation.  @xref{Differences

from previous versions}.

@cindex punctuators

@cindex digraphs

@cindex alternative tokens

@dfn{Punctuators} are all the usual bits of punctuation which are

meaningful to C and C++.  All but three of the punctuation characters in

ASCII are C punctuators.  The exceptions are @samp{@@}, @samp{$}, and

@samp{`}.  In addition, all the two- and three-character operators are

punctuators.  There are also six @dfn{digraphs}, which the C++ standard

calls @dfn{alternative tokens}, which are merely alternate ways to spell

other punctuators.  This is a second attempt to work around missing

punctuation in obsolete systems.  It has no negative side effects,

unlike trigraphs, but does not cover as much ground.  The digraphs and

their corresponding normal punctuators are:

@smallexample

Digraph:        <%  %>  <:  :>  %:  %:%:

Punctuator:      @{   @}   [   ]   #    ##

@end smallexample

@cindex other tokens

Any other single character is considered ``other''.  It is passed on to

the preprocessor's output unmolested.  The C compiler will almost

certainly reject source code containing ``other'' tokens.  In ASCII, the

only other characters are @samp{@@}, @samp{$}, @samp{`}, and control

characters other than NUL (all bits zero).  (Note that @samp{$} is

normally considered a letter.)  All characters with the high bit set

(numeric range 0x7F--0xFF) are also ``other'' in the present

implementation.  This will change when proper support for international

character sets is added to GCC@.

NUL is a special case because of the high probability that its

appearance is accidental, and because it may be invisible to the user

(many terminals do not display NUL at all).  Within comments, NULs are

silently ignored, just as any other character would be.  In running

text, NUL is considered white space.  For example, these two directives

have the same meaning.

@smallexample

#define X^@@1

#define X 1

@end smallexample

@noindent

(where @samp{^@@} is ASCII NUL)@.  Within string or character constants,

NULs are preserved.  In the latter two cases the preprocessor emits a

warning message.

@node The preprocessing language

@section The preprocessing language

@cindex directives

@cindex preprocessing directives

@cindex directive line

@cindex directive name

After tokenization, the stream of tokens may simply be passed straight

to the compiler's parser.  However, if it contains any operations in the

@dfn{preprocessing language}, it will be transformed first.  This stage

corresponds roughly to the standard's ``translation phase 4'' and is

what most people think of as the preprocessor's job.

The preprocessing language consists of @dfn{directives} to be executed

and @dfn{macros} to be expanded.  Its primary capabilities are:

@itemize @bullet

@item

Inclusion of header files.  These are files of declarations that can be

substituted into your program.

@item

Macro expansion.  You can define @dfn{macros}, which are abbreviations

for arbitrary fragments of C code.  The preprocessor will replace the

macros with their definitions throughout the program.  Some macros are

automatically defined for you.

@item

Conditional compilation.  You can include or exclude parts of the

program according to various conditions.

@item

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 where each source line originally came

from.

@item

Diagnostics.  You can detect problems at compile time and issue errors

or warnings.

@end itemize

There are a few more, less useful, features.

Except for expansion of predefined macros, all these operations are

triggered with @dfn{preprocessing directives}.  Preprocessing directives

are lines in your program that start with @samp{#}.  Whitespace is

allowed before and after the @samp{#}.  The @samp{#} is followed by an

identifier, the @dfn{directive name}.  It specifies the operation to

perform.  Directives are commonly referred to as @samp{#@var{name}}

where @var{name} is the directive name.  For example, @samp{#define} is

the directive that defines a macro.

The @samp{#} which begins a directive cannot come from a macro

expansion.  Also, the directive name is not macro expanded.  Thus, if

@code{foo} is defined as a macro expanding to @code{define}, that does

not make @samp{#foo} a valid preprocessing directive.

The set of valid directive names is fixed.  Programs cannot define new

preprocessing directives.

Some directives require arguments; these make up the rest of the

directive line and must be separated from the directive name by

whitespace.  For example, @samp{#define} must be followed by a macro

name and the intended expansion of the macro.

A preprocessing directive cannot cover more than one line.  The line

may, however, be continued with backslash-newline, or by a block comment

which extends past the end of the line.  In either case, when the

directive is processed, the continuations have already been merged with

the first line to make one long line.

@node Header Files

@chapter Header Files

@cindex header file

A header file is a file containing C declarations and macro definitions

(@pxref{Macros}) to be shared between several source files.  You request

the use of a header file in your program by @dfn{including} it, with the

C preprocessing directive @samp{#include}.

Header files serve two purposes.

@itemize @bullet

@item

@cindex system header files

System header files declare the interfaces to parts of the operating

system.  You include them in your program to supply the definitions and

declarations you need to invoke system calls and libraries.

@item

Your own header files contain declarations for interfaces between the

source files of your program.  Each time you have a group of related

declarations and macro definitions all or most of which are needed in

several different source files, it is a good idea to create a header

file for them.

@end itemize

Including a header file produces the same results as copying the header

file into each source file that needs it.  Such copying would be

time-consuming and error-prone.  With a header file, the related

declarations appear in only one place.  If they need to be changed, they

can be changed in one place, and programs that include the header file

will automatically use the new version when next recompiled.  The header

file eliminates the labor of finding and changing all the copies as well

as the risk that a failure to find one copy will result in

inconsistencies within a program.

In C, the usual convention is to give header files names that end with

@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 quote directories and then the same

directories used for @code{<@var{file}>}.  You can prepend directories

to the list of quote directories with the @option{-iquote} option.

@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,

@smallexample

char *test (void);

@end smallexample

@noindent

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

like this,

@smallexample

int x;

#include "header.h"

int

main (void)

@{

  puts (test ());

@}

@end smallexample

@noindent

the compiler will see the same token stream as it would if

@file{program.c} read

@smallexample

int x;

char *test (void);

int

main (void)

@{

  puts (test ());

@}

@end smallexample

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,

an included file must consist of complete tokens.  Comments and string

literals which have not been closed by the end of an included file are

invalid.  For error recovery, they are considered to end 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:

@smallexample

/usr/local/include

@var{libdir}/gcc/@var{target}/@var{version}/include

/usr/@var{target}/include

/usr/include

@end smallexample

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.  The only

exception is when @file{dir} is already searched by default.  In

this case, the option is ignored and the search order for system

directories remains unchanged.

Duplicate directories are removed from the quote and bracket search

chains before the two chains are merged to make the final search chain.

Thus, it is possible for a directory to occur twice in the final search

chain if it was specified in both the quote and bracket chains.

You can 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.

@option{-I} options are not ignored as described above when

@option{-nostdinc} is in effect.

GCC looks for headers requested with @code{@w{#include "@var{file}"}}

first in the directory containing the current file, then in the

directories as specified by @option{-iquote} options, 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-} is deprecated, @option{-iquote}

should be used instead.

@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

generally less 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:

@smallexample

@group

/* File foo.  */

#ifndef FILE_FOO_SEEN

#define FILE_FOO_SEEN

@var{the entire file}

#endif /* !FILE_FOO_SEEN */

@end group

@end smallexample

This construct is commonly known as a @dfn{wrapper #ifndef}.