Subversion Repositories openrisc

\input texinfo

\input texinfo

@setfilename cpp.info

@setfilename cpp.info

@settitle The C Preprocessor

@settitle The C Preprocessor

@setchapternewpage off

@setchapternewpage off

@c @smallbook

@c @smallbook

@c @cropmarks

@c @cropmarks

@c @finalout

@c @finalout

@include gcc-common.texi

@include gcc-common.texi

@copying

@copying

@c man begin COPYRIGHT

@c man begin COPYRIGHT

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

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

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

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

2008, 2009, 2010

2008, 2009, 2010

Free Software Foundation, Inc.

Free Software Foundation, Inc.

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

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

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

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

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

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

the license is included in the

the license is included in the

@c man end

@c man end

section entitled ``GNU Free Documentation License''.

section entitled ``GNU Free Documentation License''.

@ignore

@ignore

@c man begin COPYRIGHT

@c man begin COPYRIGHT

man page gfdl(7).

man page gfdl(7).

@c man end

@c man end

@end ignore

@end ignore

@c man begin COPYRIGHT

@c man begin COPYRIGHT

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

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

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

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

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

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

     A GNU Manual

     A GNU Manual

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

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

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

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

     software.  Copies published by the Free Software Foundation raise

     software.  Copies published by the Free Software Foundation raise

     funds for GNU development.

     funds for GNU development.

@c man end

@c man end

@end copying

@end copying

@c Create a separate index for command line options.

@c Create a separate index for command line options.

@defcodeindex op

@defcodeindex op

@syncodeindex vr op

@syncodeindex vr op

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

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

@set cppmanual

@set cppmanual

@ifinfo

@ifinfo

@dircategory Software development

@dircategory Software development

@direntry

@direntry

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

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

@end direntry

@end direntry

@end ifinfo

@end ifinfo

@titlepage

@titlepage

@title The C Preprocessor

@title The C Preprocessor

@versionsubtitle

@versionsubtitle

@author Richard M. Stallman, Zachary Weinberg

@author Richard M. Stallman, Zachary Weinberg

@page

@page

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

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

@c override it.

@c override it.

@vskip 0pt plus 1filll

@vskip 0pt plus 1filll

@insertcopying

@insertcopying

@end titlepage

@end titlepage

@contents

@contents

@page

@page

@ifnottex

@ifnottex

@node Top

@node Top

@top

@top

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

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

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

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

useful on its own.

useful on its own.

@menu

@menu

* Overview::

* Overview::

* Header Files::

* Header Files::

* Macros::

* Macros::

* Conditionals::

* Conditionals::

* Diagnostics::

* Diagnostics::

* Line Control::

* Line Control::

* Pragmas::

* Pragmas::

* Other Directives::

* Other Directives::

* Preprocessor Output::

* Preprocessor Output::

* Traditional Mode::

* Traditional Mode::

* Implementation Details::

* Implementation Details::

* Invocation::

* Invocation::

* Environment Variables::

* Environment Variables::

* GNU Free Documentation License::

* GNU Free Documentation License::

* Index of Directives::

* Index of Directives::

* Option Index::

* Option Index::

* Concept Index::

* Concept Index::

@detailmenu

@detailmenu

 --- The Detailed Node Listing ---

 --- The Detailed Node Listing ---

Overview

Overview

* Character sets::

* Character sets::

* Initial processing::

* Initial processing::

* Tokenization::

* Tokenization::

* The preprocessing language::

* The preprocessing language::

Header Files

Header Files

* Include Syntax::

* Include Syntax::

* Include Operation::

* Include Operation::

* Search Path::

* Search Path::

* Once-Only Headers::

* Once-Only Headers::

* Alternatives to Wrapper #ifndef::

* Alternatives to Wrapper #ifndef::

* Computed Includes::

* Computed Includes::

* Wrapper Headers::

* Wrapper Headers::

* System Headers::

* System Headers::

Macros

Macros

* Object-like Macros::

* Object-like Macros::

* Function-like Macros::

* Function-like Macros::

* Macro Arguments::

* Macro Arguments::

* Stringification::

* Stringification::

* Concatenation::

* Concatenation::

* Variadic Macros::

* Variadic Macros::

* Predefined Macros::

* Predefined Macros::

* Undefining and Redefining Macros::

* Undefining and Redefining Macros::

* Directives Within Macro Arguments::

* Directives Within Macro Arguments::

* Macro Pitfalls::

* Macro Pitfalls::

Predefined Macros

Predefined Macros

* Standard Predefined Macros::

* Standard Predefined Macros::

* Common Predefined Macros::

* Common Predefined Macros::

* System-specific Predefined Macros::

* System-specific Predefined Macros::

* C++ Named Operators::

* C++ Named Operators::

Macro Pitfalls

Macro Pitfalls

* Misnesting::

* Misnesting::

* Operator Precedence Problems::

* Operator Precedence Problems::

* Swallowing the Semicolon::

* Swallowing the Semicolon::

* Duplication of Side Effects::

* Duplication of Side Effects::

* Self-Referential Macros::

* Self-Referential Macros::

* Argument Prescan::

* Argument Prescan::

* Newlines in Arguments::

* Newlines in Arguments::

Conditionals

Conditionals

* Conditional Uses::

* Conditional Uses::

* Conditional Syntax::

* Conditional Syntax::

* Deleted Code::

* Deleted Code::

Conditional Syntax

Conditional Syntax

* Ifdef::

* Ifdef::

* If::

* If::

* Defined::

* Defined::

* Else::

* Else::

* Elif::

* Elif::

Implementation Details

Implementation Details

* Implementation-defined behavior::

* Implementation-defined behavior::

* Implementation limits::

* Implementation limits::

* Obsolete Features::

* Obsolete Features::

* Differences from previous versions::

* Differences from previous versions::

Obsolete Features

Obsolete Features

* Obsolete Features::

* Obsolete Features::

@end detailmenu

@end detailmenu

@end menu

@end menu

@insertcopying

@insertcopying

@end ifnottex

@end ifnottex

@node Overview

@node Overview

@chapter Overview

@chapter Overview

@c man begin DESCRIPTION

@c man begin DESCRIPTION

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

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

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

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

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

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

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

constructs.

constructs.

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

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

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

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

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

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

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

preserving characteristics of the input which are not significant to

preserving characteristics of the input which are not significant to

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

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

will be removed, and the Makefile will not work.

will be removed, and the Makefile will not work.

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

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

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

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

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

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

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

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

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

instead of native language comments, and keeping macros simple.

instead of native language comments, and keeping macros simple.

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

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

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

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

facilities.  Most high level programming languages have their own

facilities.  Most high level programming languages have their own

conditional compilation and inclusion mechanism.  If all else fails,

conditional compilation and inclusion mechanism.  If all else fails,

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

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

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

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

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

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

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

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

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

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,

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

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

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

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

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

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

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

This manual describes the behavior of the ISO preprocessor.  To

This manual describes the behavior of the ISO preprocessor.  To

minimize gratuitous differences, where the ISO preprocessor's

minimize gratuitous differences, where the ISO preprocessor's

behavior does not conflict with traditional semantics, the

behavior does not conflict with traditional semantics, the

traditional preprocessor should behave the same way.  The various

traditional preprocessor should behave the same way.  The various

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

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

Mode}.

Mode}.

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

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

manual refer to GNU CPP@.

manual refer to GNU CPP@.

@c man end

@c man end

@menu

@menu

* Character sets::

* Character sets::

* Initial processing::

* Initial processing::

* Tokenization::

* Tokenization::

* The preprocessing language::

* The preprocessing language::

@end menu

@end menu

@node Character sets

@node Character sets

@section Character sets

@section Character sets

Source code character set processing in C and related languages is

Source code character set processing in C and related languages is

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

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

there are really at least four.

there are really at least four.

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

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

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

convert the file into the character set it uses for internal

convert the file into the character set it uses for internal

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

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

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

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

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

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

The character sets of the input files are specified using the

The character sets of the input files are specified using the

@option{-finput-charset=} option.

@option{-finput-charset=} option.

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

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

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

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

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

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

in UTF-8.

in UTF-8.

After preprocessing is complete, string and character constants are

After preprocessing is complete, string and character constants are

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

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

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

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

matching the source character set.  Wide string and character

matching the source character set.  Wide string and character

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

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

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

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

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

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

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

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

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

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

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

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

this.}  Octal and hexadecimal escape sequences do not undergo

this.}  Octal and hexadecimal escape sequences do not undergo

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

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

selected execution character set.  All other escapes are replaced by

selected execution character set.  All other escapes are replaced by

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

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

converted to the execution character set, just like unescaped

converted to the execution character set, just like unescaped

characters.

characters.

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

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

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

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

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

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

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

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

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

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

@node Initial processing

@node Initial processing

@section Initial processing

@section Initial processing

The preprocessor performs a series of textual transformations on its

The preprocessor performs a series of textual transformations on its

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

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

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

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

transformation before the next one begins.  CPP actually does them

transformation before the next one begins.  CPP actually does them

all at once, for performance reasons.  These transformations correspond

all at once, for performance reasons.  These transformations correspond

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

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

standard.

standard.

@enumerate

@enumerate

@item

@item

@cindex line endings

@cindex line endings

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

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

Different systems use different conventions to indicate the end of a

Different systems use different conventions to indicate the end of a

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

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

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

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

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

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

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

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

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

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

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

is edited on computers with different conventions that share a network

is edited on computers with different conventions that share a network

file system.)

file system.)

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

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

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

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

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

warning message.

warning message.

@item

@item

@cindex trigraphs

@cindex trigraphs

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

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

corresponding single characters.  By default GCC ignores trigraphs,

corresponding single characters.  By default GCC ignores trigraphs,

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

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

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

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

converts them.

converts them.

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

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

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

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

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

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

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

constant for a newline.

constant for a newline.

Trigraphs are not popular and many compilers implement them

Trigraphs are not popular and many compilers implement them

incorrectly.  Portable code should not rely on trigraphs being either

incorrectly.  Portable code should not rely on trigraphs being either

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

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

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

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

converted.  @xref{Wtrigraphs}.

converted.  @xref{Wtrigraphs}.

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

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

from being confused with a trigraph by inserting a backslash between

from being confused with a trigraph by inserting a backslash between

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

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

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

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

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

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

do not recognize these idioms.

do not recognize these idioms.

The nine trigraphs and their replacements are

The nine trigraphs and their replacements are

@smallexample

@smallexample

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

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

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

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

@end smallexample

@end smallexample

@item

@item

@cindex continued lines

@cindex continued lines

@cindex backslash-newline

@cindex backslash-newline

Continued lines are merged into one long line.

Continued lines are merged into one long line.

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

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

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

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

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

only at white space.)

only at white space.)

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

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

@dfn{backslash-newline}.

@dfn{backslash-newline}.

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

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

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

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

line, GCC will warn you about it.

line, GCC will warn you about it.

@item

@item

@cindex comments

@cindex comments

@cindex line comments

@cindex line comments

@cindex block comments

@cindex block comments

All comments are replaced with single spaces.

All comments are replaced with single spaces.

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

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

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

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

nest:

nest:

@smallexample

@smallexample

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

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

@end smallexample

@end smallexample

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

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

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

because they would end in the same place anyway.

because they would end in the same place anyway.

@smallexample

@smallexample

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

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

@r{text outside comment}

@r{text outside comment}

@end smallexample

@end smallexample

@end enumerate

@end enumerate

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

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

@smallexample

@smallexample

@group

@group

/* @r{block comment}

/* @r{block comment}

   // @r{contains line comment}

   // @r{contains line comment}

   @r{yet more comment}

   @r{yet more comment}

 */ @r{outside comment}

 */ @r{outside comment}

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

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

@end group

@end group

@end smallexample

@end smallexample

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

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

comment.

comment.

@smallexample

@smallexample

@group

@group

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

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

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

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

@end group

@end group

@end smallexample

@end smallexample

Comments are not recognized within string literals.

Comments are not recognized within string literals.

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

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

an empty string.

an empty string.

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

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

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.

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

Since these transformations happen before all other processing, you can

Since these transformations happen before all other processing, you can

split a line mechanically with backslash-newline anywhere.  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

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{/*},

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

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

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

For example:

For example:

@smallexample

@smallexample

@group

@group

/\

/\

*

*

*/ # /*

*/ # /*

*/ defi\

*/ defi\

ne FO\

ne FO\

O 10\

O 10\

20

20

@end group

@end group

@end smallexample

@end smallexample

@noindent

@noindent

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

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

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

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

readable.

readable.

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

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

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

program, however.

program, however.

@node Tokenization

@node Tokenization

@section Tokenization

@section Tokenization

@cindex tokens

@cindex tokens

@cindex preprocessing tokens

@cindex preprocessing tokens

After the textual transformations are finished, the input file is

After the textual transformations are finished, the input file is

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

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

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

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

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,

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

but it is often necessary to avoid ambiguities.

but it is often necessary to avoid ambiguities.

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

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

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

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

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

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

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

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

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

@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

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

could not.

could not.

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

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

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

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

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

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

@smallexample

@smallexample

@group

@group

#define foo() bar

#define foo() bar

foo()baz

foo()baz

     @expansion{} bar baz

     @expansion{} bar baz

@emph{not}

@emph{not}

     @expansion{} barbaz

     @expansion{} barbaz

@end group

@end group

@end smallexample

@end smallexample

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

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

preprocessing token becomes one compiler token.

preprocessing token becomes one compiler token.

@cindex identifiers

@cindex identifiers

Preprocessing tokens fall into five broad classes: identifiers,

Preprocessing tokens fall into five broad classes: identifiers,

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@option{-fextended-identifiers} is used.

@option{-fextended-identifiers} is used.

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

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

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

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

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

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

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

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

option.  @xref{Invocation}.

option.  @xref{Invocation}.

@cindex numbers

@cindex numbers

@cindex preprocessing numbers

@cindex preprocessing numbers

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

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

category includes all the normal integer and floating point constants

category includes all the normal integer and floating point constants

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

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

initially recognize as a number.  Formally, preprocessing numbers begin

initially recognize as a number.  Formally, preprocessing numbers begin

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

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

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

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

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

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

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

@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

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

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

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

The purpose of this unusual definition is to isolate the preprocessor

The purpose of this unusual definition is to isolate the preprocessor

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

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

distinguish between lexically valid and invalid floating-point numbers,

distinguish between lexically valid and invalid floating-point numbers,

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

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

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

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

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

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

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

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

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

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

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

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

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

might have intended.

might have intended.

@cindex string literals

@cindex string literals

@cindex string constants

@cindex string constants

@cindex character constants

@cindex character constants

@cindex header file names

@cindex header file names

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

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

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

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

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

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

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

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

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

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

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

either case embedded quotes should be escaped with a backslash:

either case embedded quotes should be escaped with a backslash:

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

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

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

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

constant that contains more than one character is

constant that contains more than one character is

implementation-defined.  @xref{Implementation Details}.

implementation-defined.  @xref{Implementation Details}.

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

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

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

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

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

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

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

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

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

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

Operation}.

Operation}.

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

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

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

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

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

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

from previous versions}.

from previous versions}.

@cindex punctuators

@cindex punctuators

@cindex digraphs

@cindex digraphs

@cindex alternative tokens

@cindex alternative tokens

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

their corresponding normal punctuators are:

their corresponding normal punctuators are:

@smallexample

@smallexample

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

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

Punctuator:      @{   @}   [   ]   #    ##

Punctuator:      @{   @}   [   ]   #    ##

@end smallexample

@end smallexample

@cindex other tokens

@cindex other tokens

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

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

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

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

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

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

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

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

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

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

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

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

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

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

implementation.  This will change when proper support for international

implementation.  This will change when proper support for international

character sets is added to GCC@.

character sets is added to GCC@.

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

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

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

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

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

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

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

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

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

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

have the same meaning.

have the same meaning.

@smallexample

@smallexample

#define X^@@1

#define X^@@1

#define X 1

#define X 1

@end smallexample

@end smallexample

@noindent

@noindent

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

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

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

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

warning message.

warning message.

@node The preprocessing language

@node The preprocessing language

@section The preprocessing language

@section The preprocessing language

@cindex directives

@cindex directives

@cindex preprocessing directives

@cindex preprocessing directives

@cindex directive line

@cindex directive line

@cindex directive name

@cindex directive name

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@itemize @bullet

@itemize @bullet

@item

@item

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

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

substituted into your program.

substituted into your program.

@item

@item

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

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

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

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

macros with their definitions throughout the program.  Some macros are

macros with their definitions throughout the program.  Some macros are

automatically defined for you.

automatically defined for you.

@item

@item

Conditional compilation.  You can include or exclude parts of the

Conditional compilation.  You can include or exclude parts of the

program according to various conditions.

program according to various conditions.

@item

@item

Line control.  If you use a program to combine or rearrange source files

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

into an intermediate file which is then compiled, you can use line

control to inform the compiler where each source line originally came

control to inform the compiler where each source line originally came

from.

from.

@item

@item

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

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

or warnings.

or warnings.

@end itemize

@end itemize

There are a few more, less useful, features.

There are a few more, less useful, features.

Except for expansion of predefined macros, all these operations are

Except for expansion of predefined macros, all these operations are

triggered with @dfn{preprocessing directives}.  Preprocessing directives

triggered with @dfn{preprocessing directives}.  Preprocessing directives

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

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

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

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

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

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

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

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

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

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

the directive that defines a macro.

the directive that defines a macro.

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

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

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

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

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

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

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

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

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

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

preprocessing directives.

preprocessing directives.

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

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

directive line and must be separated from the directive name by

directive line and must be separated from the directive name by

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

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

name and the intended expansion of the macro.

name and the intended expansion of the macro.

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

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

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

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

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

directive is processed, the continuations have already been merged with

directive is processed, the continuations have already been merged with

the first line to make one long line.

the first line to make one long line.

@node Header Files

@node Header Files

@chapter Header Files

@chapter Header Files

@cindex header file

@cindex header file

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

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

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

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

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

C preprocessing directive @samp{#include}.

C preprocessing directive @samp{#include}.

Header files serve two purposes.

Header files serve two purposes.

@itemize @bullet

@itemize @bullet

@item

@item

@cindex system header files

@cindex system header files

System header files declare the interfaces to parts of the operating

System header files declare the interfaces to parts of the operating

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

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

declarations you need to invoke system calls and libraries.

declarations you need to invoke system calls and libraries.

@item

@item

Your own header files contain declarations for interfaces between the

Your own header files contain declarations for interfaces between the

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

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

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

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

file for them.

file for them.

@end itemize

@end itemize

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

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

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

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

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

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

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

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

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

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

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

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

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

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

inconsistencies within a program.

inconsistencies within a program.

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

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

@file{.h}.  It is most portable to use only letters, digits, dashes, and

underscores in header file names, and at most one dot.

underscores in header file names, and at most one dot.

@menu

@menu

* Include Syntax::

* Include Syntax::

* Include Operation::

* Include Operation::

* Search Path::

* Search Path::

* Once-Only Headers::

* Once-Only Headers::

* Alternatives to Wrapper #ifndef::

* Alternatives to Wrapper #ifndef::

* Computed Includes::

* Computed Includes::

* Wrapper Headers::

* Wrapper Headers::

* System Headers::

* System Headers::

@end menu

@end menu

@node Include Syntax

@node Include Syntax

@section Include Syntax

@section Include Syntax

@findex #include

@findex #include

Both user and system header files are included using the preprocessing

Both user and system header files are included using the preprocessing

directive @samp{#include}.  It has two variants:

directive @samp{#include}.  It has two variants:

@table @code

@table @code

@item #include <@var{file}>

@item #include <@var{file}>

This variant is used for system header files.  It searches for a 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

named @var{file} in a standard list of system directories.  You can prepend

directories to this list with the @option{-I} option (@pxref{Invocation}).

directories to this list with the @option{-I} option (@pxref{Invocation}).

@item #include "@var{file}"

@item #include "@var{file}"

This variant is used for header files of your own program.  It

This variant is used for header files of your own program.  It

searches for a file named @var{file} first in the directory containing

searches for a file named @var{file} first in the directory containing

the current file, then in the quote directories and then the same

the current file, then in the quote directories and then the same

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

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

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

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

@end table

@end table

The argument of @samp{#include}, whether delimited with quote marks or

The argument of @samp{#include}, whether delimited with quote marks or

angle brackets, behaves like a string constant in that comments are not

angle brackets, behaves like a string constant in that comments are not

recognized, and macro names are not expanded.  Thus, @code{@w{#include

recognized, and macro names are not expanded.  Thus, @code{@w{#include

<x/*y>}} specifies inclusion of a system header file named @file{x/*y}.

<x/*y>}} specifies inclusion of a system header file named @file{x/*y}.

However, if backslashes occur within @var{file}, they are considered

However, if backslashes occur within @var{file}, they are considered

ordinary text characters, not escape characters.  None of the character

ordinary text characters, not escape characters.  None of the character

escape sequences appropriate to string constants in C are processed.

escape sequences appropriate to string constants in C are processed.

Thus, @code{@w{#include "x\n\\y"}} specifies a filename containing three

Thus, @code{@w{#include "x\n\\y"}} specifies a filename containing three

backslashes.  (Some systems interpret @samp{\} as a pathname separator.

backslashes.  (Some systems interpret @samp{\} as a pathname separator.

All of these also interpret @samp{/} the same way.  It is most portable

All of these also interpret @samp{/} the same way.  It is most portable

to use only @samp{/}.)

to use only @samp{/}.)

It is an error if there is anything (other than comments) on the line

It is an error if there is anything (other than comments) on the line

after the file name.

after the file name.

@node Include Operation

@node Include Operation

@section Include Operation

@section Include Operation

The @samp{#include} directive works by directing the C preprocessor to

The @samp{#include} directive works by directing the C preprocessor to

scan the specified file as input before continuing with the rest of the

scan the specified file as input before continuing with the rest of the

current file.  The output from the preprocessor contains the output

current file.  The output from the preprocessor contains the output

already generated, followed by the output resulting from the included

already generated, followed by the output resulting from the included

file, followed by the output that comes from the text after the

file, followed by the output that comes from the text after the

@samp{#include} directive.  For example, if you have a header file

@samp{#include} directive.  For example, if you have a header file

@file{header.h} as follows,

@file{header.h} as follows,

@smallexample

@smallexample

char *test (void);

char *test (void);

@end smallexample

@end smallexample

@noindent

@noindent

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

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

like this,

like this,

@smallexample

@smallexample

int x;

int x;

#include "header.h"

#include "header.h"

int

int

main (void)

main (void)

@{

@{

  puts (test ());

  puts (test ());

@}

@}

@end smallexample

@end smallexample

@noindent

@noindent

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

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

@file{program.c} read

@file{program.c} read

@smallexample

@smallexample

int x;

int x;

char *test (void);

char *test (void);

int

int

main (void)

main (void)

@{

@{

  puts (test ());

  puts (test ());

@}

@}

@end smallexample

@end smallexample

Included files are not limited to declarations and macro definitions;

Included files are not limited to declarations and macro definitions;

those are merely the typical uses.  Any fragment of a C program can be

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

included from another file.  The include file could even contain the

beginning of a statement that is concluded in the containing file, or

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,

the end of a statement that was started in the including file.  However,

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

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

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

invalid.  For error recovery, they are considered to end at the end of

the file.

the file.

To avoid confusion, it is best if header files contain only complete

To avoid confusion, it is best if header files contain only complete

syntactic units---function declarations or definitions, type

syntactic units---function declarations or definitions, type

declarations, etc.

declarations, etc.

The line following the @samp{#include} directive is always treated as a

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

separate line by the C preprocessor, even if the included file lacks a

final newline.

final newline.

@node Search Path

@node Search Path

@section Search Path

@section Search Path

GCC looks in several different places for headers.  On a normal Unix

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

system, if you do not instruct it otherwise, it will look for headers

requested with @code{@w{#include <@var{file}>}} in:

requested with @code{@w{#include <@var{file}>}} in:

@smallexample

@smallexample

/usr/local/include

/usr/local/include

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

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

/usr/@var{target}/include

/usr/@var{target}/include

/usr/include

/usr/include

@end smallexample

@end smallexample

For C++ programs, it will also look in @file{/usr/include/g++-v3},

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

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

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

the canonical name of the system it runs on.  @var{version} is the

version of GCC in use.

version of GCC in use.

You can add to this list with the @option{-I@var{dir}} command line

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

option.  All the directories named by @option{-I} are searched, in

left-to-right order, @emph{before} the default directories.  The only

left-to-right order, @emph{before} the default directories.  The only

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

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

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

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

directories remains unchanged.

directories remains unchanged.

Duplicate directories are removed from the quote and bracket search

Duplicate directories are removed from the quote and bracket search

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

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

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.

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

You can prevent GCC from searching any of the default directories with

You can prevent GCC from searching any of the default directories with

the @option{-nostdinc} option.  This is useful when you are compiling an

the @option{-nostdinc} option.  This is useful when you are compiling an

operating system kernel or some other program that does not use the

operating system kernel or some other program that does not use the

standard C library facilities, or the standard C library itself.

standard C library facilities, or the standard C library itself.

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

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

@option{-nostdinc} is in effect.

@option{-nostdinc} is in effect.

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

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

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

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

directories as specified by @option{-iquote} options, then in the same

directories as specified by @option{-iquote} options, then in the same

places it would have looked for a header requested with angle

places it would have looked for a header requested with angle

brackets.  For example, if @file{/usr/include/sys/stat.h} contains

brackets.  For example, if @file{/usr/include/sys/stat.h} contains

@code{@w{#include "types.h"}}, GCC looks for @file{types.h} first in

@code{@w{#include "types.h"}}, GCC looks for @file{types.h} first in

@file{/usr/include/sys}, then in its usual search path.

@file{/usr/include/sys}, then in its usual search path.

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

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

directory containing the current file.

directory containing the current file.

You may put @option{-I-} at any point in your list of @option{-I} options.

You may put @option{-I-} at any point in your list of @option{-I} options.

This has two effects.  First, directories appearing before the

This has two effects.  First, directories appearing before the

@option{-I-} in the list are searched only for headers requested with

@option{-I-} in the list are searched only for headers requested with

quote marks.  Directories after @option{-I-} are searched for all

quote marks.  Directories after @option{-I-} are searched for all

headers.  Second, the directory containing the current file is not

headers.  Second, the directory containing the current file is not

searched for anything, unless it happens to be one of the directories

searched for anything, unless it happens to be one of the directories

named by an @option{-I} switch.  @option{-I-} is deprecated, @option{-iquote}

named by an @option{-I} switch.  @option{-I-} is deprecated, @option{-iquote}

should be used instead.

should be used instead.

@option{-I. -I-} is not the same as no @option{-I} options at all, and does

@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{""}

not cause the same behavior for @samp{<>} includes that @samp{""}

includes get with no special options.  @option{-I.} searches the

includes get with no special options.  @option{-I.} searches the

compiler's current working directory for header files.  That may or may

compiler's current working directory for header files.  That may or may

not be the same as the directory containing the current file.

not be the same as the directory containing the current file.

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

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

@option{-I./-}.

@option{-I./-}.

There are several more ways to adjust the header search path.  They are

There are several more ways to adjust the header search path.  They are

generally less useful.  @xref{Invocation}.

generally less useful.  @xref{Invocation}.

@node Once-Only Headers

@node Once-Only Headers

@section Once-Only Headers

@section Once-Only Headers

@cindex repeated inclusion

@cindex repeated inclusion

@cindex including just once

@cindex including just once

@cindex wrapper @code{#ifndef}

@cindex wrapper @code{#ifndef}

If a header file happens to be included twice, the compiler will process

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

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,

compiler sees the same structure definition twice.  Even if it does not,

it will certainly waste time.

it will certainly waste time.

The standard way to prevent this is to enclose the entire real contents

The standard way to prevent this is to enclose the entire real contents

of the file in a conditional, like this:

of the file in a conditional, like this:

@smallexample

@smallexample

@group

@group

/* File foo.  */

/* File foo.  */

#ifndef FILE_FOO_SEEN

#ifndef FILE_FOO_SEEN

#define FILE_FOO_SEEN

#define FILE_FOO_SEEN

@var{the entire file}

@var{the entire file}

#endif /* !FILE_FOO_SEEN */

#endif /* !FILE_FOO_SEEN */

@end group

@end group

@end smallexample

@end smallexample