Subversion Repositories openrisc

This is doc/cpp.info, produced by makeinfo version 4.8 from

This is doc/cpp.info, produced by makeinfo version 4.8 from

/scratch/mitchell/gcc-releases/gcc-4.2.2/gcc-4.2.2/gcc/doc/cpp.texi.

/scratch/mitchell/gcc-releases/gcc-4.2.2/gcc-4.2.2/gcc/doc/cpp.texi.

   Copyright (C) 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, 1997,

   Copyright (C) 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, 1997,

1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005 Free Software

1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005 Free Software

Foundation, Inc.

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.1 or

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

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

the license is included in the section entitled "GNU Free Documentation

the license is included in the section entitled "GNU Free Documentation

License".

License".

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

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

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

are (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.

INFO-DIR-SECTION Software development

INFO-DIR-SECTION Software development

START-INFO-DIR-ENTRY

START-INFO-DIR-ENTRY

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

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

END-INFO-DIR-ENTRY

END-INFO-DIR-ENTRY

File: cpp.info,  Node: Top,  Next: Overview,  Up: (dir)

File: cpp.info,  Node: Top,  Next: Overview,  Up: (dir)

The C Preprocessor

The C Preprocessor

******************

******************

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

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

* 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

* Assertions::

* Assertions::

* Obsolete once-only headers::

* Obsolete once-only headers::

   Copyright (C) 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, 1997,

   Copyright (C) 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, 1997,

1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005 Free Software

1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005 Free Software

Foundation, Inc.

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.1 or

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

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

the license is included in the section entitled "GNU Free Documentation

the license is included in the section entitled "GNU Free Documentation

License".

License".

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

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

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

are (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.

File: cpp.info,  Node: Overview,  Next: Header Files,  Prev: Top,  Up: Top

File: cpp.info,  Node: Overview,  Next: Header Files,  Prev: Top,  Up: Top

1 Overview

1 Overview

**********

**********

The C preprocessor, often known as "cpp", is a "macro processor" that

The C preprocessor, often known as "cpp", is a "macro processor" that

is used automatically by the C compiler to transform your program

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 "macros", which are brief abbreviations for longer

you to define "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

   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

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

(Pascal, Ada, etc.) So is assembly, with caution.  `-traditional-cpp'

(Pascal, Ada, etc.) So is assembly, with caution.  `-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

   Wherever possible, you should use a preprocessor geared to the

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

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

macro facilities.  Most high level programming languages have their own

macro 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 preprocessors vary in some details.  This manual discusses the GNU

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

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

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 `-std=c89' or `-std=c99' options, depending on which

you should use the `-std=c89' or `-std=c99' options, depending on which

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

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

diagnostics, you must also use `-pedantic'.  *Note Invocation::.

diagnostics, you must also use `-pedantic'.  *Note 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 behavior

minimize gratuitous differences, where the ISO preprocessor's behavior

does not conflict with traditional semantics, the traditional

does not conflict with traditional semantics, the traditional

preprocessor should behave the same way.  The various differences that

preprocessor should behave the same way.  The various differences that

do exist are detailed in the section *Note Traditional Mode::.

do exist are detailed in the section *Note Traditional Mode::.

   For clarity, unless noted otherwise, references to `CPP' in this

   For clarity, unless noted otherwise, references to `CPP' in this

manual refer to GNU CPP.

manual refer to GNU CPP.

* Menu:

* Menu:

* Character sets::

* Character sets::

* Initial processing::

* Initial processing::

* Tokenization::

* Tokenization::

* The preprocessing language::

* The preprocessing language::

File: cpp.info,  Node: Character sets,  Next: Initial processing,  Up: Overview

File: cpp.info,  Node: Character sets,  Next: Initial processing,  Up: Overview

1.1 Character sets

1.1 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 "source"

processing.  That set is what the C standard calls the "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

`-finput-charset=' 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 output

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

from the preprocessor with the `-E' option, it will be in UTF-8.

from the preprocessor with the `-E' option, it will be 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 "execution" character set.  This character

converted again, into the "execution" character set.  This character

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

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

source character set.  Wide string and character constants have their

source character set.  Wide string and character constants have their

own character set, which is not called out specifically in the

own character set, which is not called out specifically in the

standard.  Again, it is under control of the user.  The default is

standard.  Again, it is under control of the user.  The default is

UTF-16 or UTF-32, whichever fits in the target's `wchar_t' type, in the

UTF-16 or UTF-32, whichever fits in the target's `wchar_t' type, in the

target machine's byte order.(1)  Octal and hexadecimal escape sequences

target machine's byte order.(1)  Octal and hexadecimal escape sequences

do not undergo conversion; '\x12' has the value 0x12 regardless of the

do not undergo conversion; '\x12' has the value 0x12 regardless of the

currently selected execution character set.  All other escapes are

currently selected execution character set.  All other escapes are

replaced by the character in the source character set that they

replaced by the character in the source character set that they

represent, then converted to the execution character set, just like

represent, then converted to the execution character set, just like

unescaped characters.

unescaped characters.

   Unless the experimental `-fextended-identifiers' option is used, GCC

   Unless the experimental `-fextended-identifiers' option is used, GCC

does not permit the use of characters outside the ASCII range, nor `\u'

does not permit the use of characters outside the ASCII range, nor `\u'

and `\U' escapes, in identifiers.  Even with that option, characters

and `\U' escapes, in identifiers.  Even with that option, characters

outside the ASCII range can only be specified with the `\u' and `\U'

outside the ASCII range can only be specified with the `\u' and `\U'

escapes, not used directly in identifiers.

escapes, not used directly in identifiers.

   ---------- Footnotes ----------

   ---------- Footnotes ----------

   (1) UTF-16 does not meet the requirements of the C standard for a

   (1) UTF-16 does not meet the requirements of the C standard for a

wide character set, but the choice of 16-bit `wchar_t' is enshrined in

wide character set, but the choice of 16-bit `wchar_t' is enshrined in

some system ABIs so we cannot fix this.

some system ABIs so we cannot fix this.

File: cpp.info,  Node: Initial processing,  Next: Tokenization,  Prev: Character sets,  Up: Overview

File: cpp.info,  Node: Initial processing,  Next: Tokenization,  Prev: Character sets,  Up: Overview

1.2 Initial processing

1.2 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 all

transformation before the next one begins.  CPP actually does them all

at once, for performance reasons.  These transformations correspond

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.

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

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

     Different systems use different conventions to indicate the end of

     Different systems use different conventions to indicate the end of

     a line.  GCC accepts the ASCII control sequences `LF', `CR LF' and

     a line.  GCC accepts the ASCII control sequences `LF', `CR LF' and

     `CR' as end-of-line markers.  These are the canonical sequences

     `CR' as end-of-line markers.  These are the canonical sequences

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

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

     respectively.  You may therefore safely copy source code written

     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

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

     file doesn't consistently use one convention, as sometimes happens

     file doesn't consistently use one convention, as sometimes happens

     when it is edited on computers with different conventions that

     when it is edited on computers with different conventions that

     share a network file system.)

     share a network file system.)

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

     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

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

     standard says that this condition provokes undefined behavior, so

     standard says that this condition provokes undefined behavior, so

     GCC will emit a warning message.

     GCC will emit a warning message.

  2. If trigraphs are enabled, they are replaced by their corresponding

  2. If trigraphs are enabled, they are replaced by their corresponding

     single characters.  By default GCC ignores trigraphs, but if you

     single characters.  By default GCC ignores trigraphs, but if you

     request a strictly conforming mode with the `-std' option, or you

     request a strictly conforming mode with the `-std' option, or you

     specify the `-trigraphs' option, then it converts them.

     specify the `-trigraphs' option, then it converts them.

     These are nine three-character sequences, all starting with `??',

     These are nine three-character sequences, all starting with `??',

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

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

     permit obsolete systems that lack some of C's punctuation to use

     permit obsolete systems that lack some of C's punctuation to use

     C.  For example, `??/' stands for `\', so '??/n' is a character

     C.  For example, `??/' stands for `\', so '??/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

     incorrectly.  Portable code should not rely on trigraphs being

     either converted or ignored.  With `-Wtrigraphs' GCC will warn you

     either converted or ignored.  With `-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.  *Note Wtrigraphs::.

     converted.  *Note 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

     from being confused with a trigraph by inserting a backslash

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

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

     the trigraph and making use of string literal concatenation.

     the trigraph and making use of string literal concatenation.

     "(??\?)"  is the string `(???)', not `(?]'.  Traditional C

     "(??\?)"  is the string `(???)', not `(?]'.  Traditional C

     compilers do not recognize these idioms.

     compilers do not recognize these idioms.

     The nine trigraphs and their replacements are

     The nine trigraphs and their replacements are

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

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

          Replacement:      [    ]    {    }    #    \    ^    |    ~

          Replacement:      [    ]    {    }    #    \    ^    |    ~

  3. Continued lines are merged into one long line.

  3. Continued lines are merged into one long line.

     A continued line is a line which ends with a backslash, `\'.  The

     A continued line is a line which ends with a backslash, `\'.  The

     backslash is removed and the following line is joined with the

     backslash is removed and the following line is joined with the

     current one.  No space is inserted, so you may split a line

     current one.  No space is inserted, so you may split a line

     anywhere, even in the middle of a word.  (It is generally more

     anywhere, even in the middle of a word.  (It is generally more

     readable to split lines only at white space.)

     readable to split lines only at white space.)

     The trailing backslash on a continued line is commonly referred to

     The trailing backslash on a continued line is commonly referred to

     as a "backslash-newline".

     as a "backslash-newline".

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

     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

     that is still a continued line.  However, as this is usually the

     result of an editing mistake, and many compilers will not accept

     result of an editing mistake, and many compilers will not accept

     it as a continued line, GCC will warn you about it.

     it as a continued line, GCC will warn you about it.

  4. All comments are replaced with single spaces.

  4. All comments are replaced with single spaces.

     There are two kinds of comments.  "Block comments" begin with `/*'

     There are two kinds of comments.  "Block comments" begin with `/*'

     and continue until the next `*/'.  Block comments do not nest:

     and continue until the next `*/'.  Block comments do not nest:

          /* this is /* one comment */ text outside comment

          /* this is /* one comment */ text outside comment

     "Line comments" begin with `//' and continue to the end of the

     "Line comments" begin with `//' and continue to the end of the

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

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

     matter, because they would end in the same place anyway.

     matter, because they would end in the same place anyway.

          // this is // one comment

          // this is // one comment

          text outside comment

          text outside comment

   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.

     /* block comment

     /* block comment

        // contains line comment

        // contains line comment

        yet more comment

        yet more comment

      */ outside comment

      */ outside comment

     // line comment /* contains block comment */

     // line comment /* contains block comment */

   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.

      // l.c.  /* block comment begins

      // l.c.  /* block comment begins

         oops! this isn't a comment anymore */

         oops! this isn't a comment anymore */

   Comments are not recognized within string literals.  "/* blah */" is

   Comments are not recognized within string literals.  "/* blah */" is

the string constant `/* blah */', not an empty string.

the string constant `/* blah */', not 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

   Since these transformations happen before all other processing, you

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

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 `/*', `*/', and

next line with backslash-newline.  You can even split `/*', `*/', and

`//' onto multiple lines with backslash-newline.  For example:

`//' onto multiple lines with backslash-newline.  For example:

     /\

     /\

     *

     *

     */ # /*

     */ # /*

     */ defi\

     */ defi\

     ne FO\

     ne FO\

     O 10\

     O 10\

     20

     20

is equivalent to `#define FOO 1020'.  All these tricks are extremely

is equivalent to `#define FOO 1020'.  All these tricks are extremely

confusing and should not be used in code intended to be readable.

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

   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

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

correct program, however.

correct program, however.

File: cpp.info,  Node: Tokenization,  Next: The preprocessing language,  Prev: Initial processing,  Up: Overview

File: cpp.info,  Node: Tokenization,  Next: The preprocessing language,  Prev: Initial processing,  Up: Overview

1.3 Tokenization

1.3 Tokenization

================

================

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 "preprocessing tokens".  These mostly

converted into a sequence of "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

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

possible tokenization, the preprocessor is greedy.  It always makes

possible tokenization, the preprocessor is greedy.  It always makes

each token, starting from the left, as big as possible before moving on

each token, starting from the left, as big as possible before moving on

to the next token.  For instance, `a+++++b' is interpreted as

to the next token.  For instance, `a+++++b' is interpreted as

`a ++ ++ + b', not as `a ++ + ++ b', even though the latter

`a ++ ++ + b', not as `a ++ + ++ b', even though the latter

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

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

not.

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 `##' preprocessing operator is used to paste

change, except when the `##' preprocessing operator is used to paste

tokens together.  *Note Concatenation::.  For example,

tokens together.  *Note Concatenation::.  For example,

     #define foo() bar

     #define foo() bar

     foo()baz

     foo()baz

          ==> bar baz

          ==> bar baz

     _not_

     _not_

          ==> barbaz

          ==> barbaz

   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.

   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

"identifier" is the same as an identifier in C: any sequence of

"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 `defined'.  *Note Defined::.

preprocessing keyword is `defined'.  *Note 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.  *Note C++ Named Operators::.

preprocessor.  *Note 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

`\u' and `\U' escape sequences.  The implementation of this feature in

`\u' and `\U' escape sequences.  The implementation of this feature in

GCC is experimental; such characters are only accepted in the `\u' and

GCC is experimental; such characters are only accepted in the `\u' and

`\U' forms and only if `-fextended-identifiers' is used.

`\U' forms and only if `-fextended-identifiers' is used.

   As an extension, GCC treats `$' as a letter.  This is for

   As an extension, GCC treats `$' as a letter.  This is for

compatibility with some systems, such as VMS, where `$' is commonly

compatibility with some systems, such as VMS, where `$' is commonly

used in system-defined function and object names.  `$' is not a letter

used in system-defined function and object names.  `$' is not a letter

in strictly conforming mode, or if you specify the `-$' option.  *Note

in strictly conforming mode, or if you specify the `-$' option.  *Note

Invocation::.

Invocation::.

   A "preprocessing number" has a rather bizarre definition.  The

   A "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 `e+', `e-', `E+',

exponents.  Exponents are the two-character sequences `e+', `e-', `E+',

`E-', `p+', `p-', `P+', and `P-'.  (The exponents that begin with `p'

`E-', `p+', `p-', `P+', and `P-'.  (The exponents that begin with `p'

or `P' are new to C99.  They are used for hexadecimal floating-point

or `P' are new to C99.  They are used for hexadecimal floating-point

constants.)

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 `##' operator.

pasted back together with the `##' 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, `0xE+12' is a preprocessing number which

misinterpreted.  For example, `0xE+12' is a preprocessing number which

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

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

error.  It does not mean `0xE + 12', which is what you might have

error.  It does not mean `0xE + 12', which is what you might have

intended.

intended.

   "String literals" are string constants, character constants, and

   "String literals" are string constants, character constants, and

header file names (the argument of `#include').(1)  String constants

header file names (the argument of `#include').(1)  String constants

and character constants are straightforward: "..." or '...'.  In either

and character constants are straightforward: "..." or '...'.  In either

case embedded quotes should be escaped with a backslash: '\'' is the

case embedded quotes should be escaped with a backslash: '\'' is the

character constant for `''.  There is no limit on the length of a

character constant for `''.  There is no limit on the length of a

character constant, but the value of a character constant that contains

character constant, but the value of a character constant that contains

more than one character is implementation-defined.  *Note

more than one character is implementation-defined.  *Note

Implementation Details::.

Implementation Details::.

   Header file names either look like string constants, "...", or are

   Header file names either look like string constants, "...", or are

written with angle brackets instead, <...>.  In either case, backslash

written with angle brackets instead, <...>.  In either case, backslash

is an ordinary character.  There is no way to escape the closing quote

is an ordinary character.  There is no way to escape the closing quote

or angle bracket.  The preprocessor looks for the header file in

or angle bracket.  The preprocessor looks for the header file in

different places depending on which form you use.  *Note Include

different places depending on which form you use.  *Note 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.  *Note Differences

lines instead, or string constant concatenation.  *Note Differences

from previous versions::.

from previous versions::.

   "Punctuators" are all the usual bits of punctuation which are

   "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 `@', `$', and ``'.  In

ASCII are C punctuators.  The exceptions are `@', `$', and ``'.  In

addition, all the two- and three-character operators are punctuators.

addition, all the two- and three-character operators are punctuators.

There are also six "digraphs", which the C++ standard calls

There are also six "digraphs", which the C++ standard calls

"alternative tokens", which are merely alternate ways to spell other

"alternative tokens", which are merely alternate ways to spell other

punctuators.  This is a second attempt to work around missing

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:

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

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

     Punctuator:      {   }   [   ]   #    ##

     Punctuator:      {   }   [   ]   #    ##

   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 `@', `$', ``', and control characters other

only other characters are `@', `$', ``', and control characters other

than NUL (all bits zero).  (Note that `$' is normally considered a

than NUL (all bits zero).  (Note that `$' is normally considered a

letter.)  All characters with the high bit set (numeric range

letter.)  All characters with the high bit set (numeric range

0x7F-0xFF) are also "other" in the present implementation.  This will

0x7F-0xFF) are also "other" in the present implementation.  This will

change when proper support for international character sets is added to

change when proper support for international character sets is added to

GCC.

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.

     #define X^@1

     #define X^@1

     #define X 1

     #define X 1

(where `^@' is ASCII NUL).  Within string or character constants, NULs

(where `^@' is ASCII NUL).  Within string or character constants, NULs

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

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

warning message.

warning message.

   ---------- Footnotes ----------

   ---------- Footnotes ----------

   (1) The C standard uses the term "string literal" to refer only to

   (1) The C standard uses the term "string literal" to refer only to

what we are calling "string constants".

what we are calling "string constants".

File: cpp.info,  Node: The preprocessing language,  Prev: Tokenization,  Up: Overview

File: cpp.info,  Node: The preprocessing language,  Prev: Tokenization,  Up: Overview

1.4 The preprocessing language

1.4 The preprocessing language

==============================

==============================

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

"preprocessing language", it will be transformed first.  This stage

"preprocessing language", it will be transformed first.  This stage

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

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

most people think of as the preprocessor's job.

most people think of as the preprocessor's job.

   The preprocessing language consists of "directives" to be executed

   The preprocessing language consists of "directives" to be executed

and "macros" to be expanded.  Its primary capabilities are:

and "macros" to be expanded.  Its primary capabilities are:

   * Inclusion of header files.  These are files of declarations that

   * Inclusion of header files.  These are files of declarations that

     can be substituted into your program.

     can be substituted into your program.

   * Macro expansion.  You can define "macros", which are abbreviations

   * Macro expansion.  You can define "macros", which are abbreviations

     for arbitrary fragments of C code.  The preprocessor will replace

     for arbitrary fragments of C code.  The preprocessor will replace

     the macros with their definitions throughout the program.  Some

     the macros with their definitions throughout the program.  Some

     macros are automatically defined for you.

     macros are automatically defined for you.

   * 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.

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

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

     files into an intermediate file which is then compiled, you can

     files into an intermediate file which is then compiled, you can

     use line control to inform the compiler where each source line

     use line control to inform the compiler where each source line

     originally came from.

     originally came from.

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

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

     errors or warnings.

     errors or warnings.

   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 "preprocessing directives".  Preprocessing directives

triggered with "preprocessing directives".  Preprocessing directives

are lines in your program that start with `#'.  Whitespace is allowed

are lines in your program that start with `#'.  Whitespace is allowed

before and after the `#'.  The `#' is followed by an identifier, the

before and after the `#'.  The `#' is followed by an identifier, the

"directive name".  It specifies the operation to perform.  Directives

"directive name".  It specifies the operation to perform.  Directives

are commonly referred to as `#NAME' where NAME is the directive name.

are commonly referred to as `#NAME' where NAME is the directive name.

For example, `#define' is the directive that defines a macro.

For example, `#define' is the directive that defines a macro.

   The `#' which begins a directive cannot come from a macro expansion.

   The `#' which begins a directive cannot come from a macro expansion.

Also, the directive name is not macro expanded.  Thus, if `foo' is

Also, the directive name is not macro expanded.  Thus, if `foo' is

defined as a macro expanding to `define', that does not make `#foo' a

defined as a macro expanding to `define', that does not make `#foo' a

valid preprocessing directive.

valid preprocessing directive.

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

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

new preprocessing directives.

new 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, `#define' must be followed by a macro name

whitespace.  For example, `#define' must be followed by a macro name

and the intended expansion of the macro.

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.

File: cpp.info,  Node: Header Files,  Next: Macros,  Prev: Overview,  Up: Top

File: cpp.info,  Node: Header Files,  Next: Macros,  Prev: Overview,  Up: Top

2 Header Files

2 Header Files

**************

**************

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

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

(*note Macros::) to be shared between several source files.  You request

(*note Macros::) to be shared between several source files.  You request

the use of a header file in your program by "including" it, with the C

the use of a header file in your program by "including" it, with the C

preprocessing directive `#include'.

preprocessing directive `#include'.

   Header files serve two purposes.

   Header files serve two purposes.

   * System header files declare the interfaces to parts of the

   * System header files declare the interfaces to parts of the

     operating system.  You include them in your program to supply the

     operating system.  You include them in your program to supply the

     definitions and declarations you need to invoke system calls and

     definitions and declarations you need to invoke system calls and

     libraries.

     libraries.

   * Your own header files contain declarations for interfaces between

   * Your own header files contain declarations for interfaces between

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

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

     related declarations and macro definitions all or most of which

     related declarations and macro definitions all or most of which

     are needed in several different source files, it is a good idea to

     are needed in several different source files, it is a good idea to

     create a header file for them.

     create a header file for them.

   Including a header file produces the same results as copying the

   Including a header file produces the same results as copying the

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

header 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

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

with `.h'.  It is most portable to use only letters, digits, dashes, and

with `.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::

* Computed Includes::

* Computed Includes::

* Wrapper Headers::

* Wrapper Headers::

* System Headers::

* System Headers::

File: cpp.info,  Node: Include Syntax,  Next: Include Operation,  Up: Header Files

File: cpp.info,  Node: Include Syntax,  Next: Include Operation,  Up: Header Files

2.1 Include Syntax

2.1 Include Syntax

==================

==================

Both user and system header files are included using the preprocessing

Both user and system header files are included using the preprocessing

directive `#include'.  It has two variants:

directive `#include'.  It has two variants:

`#include '

`#include '

     This variant is used for system header files.  It searches for a

     This variant is used for system header files.  It searches for a

     file named FILE in a standard list of system directories.  You can

     file named FILE in a standard list of system directories.  You can

     prepend directories to this list with the `-I' option (*note

     prepend directories to this list with the `-I' option (*note

     Invocation::).

     Invocation::).

`#include "FILE"'

`#include "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 FILE first in the directory containing

     searches for a file named 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 `'.  You can prepend directories to the

     directories used for `'.  You can prepend directories to the

     list of quote directories with the `-iquote' option.

     list of quote directories with the `-iquote' option.

   The argument of `#include', whether delimited with quote marks or

   The argument of `#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, `#include '

recognized, and macro names are not expanded.  Thus, `#include '

specifies inclusion of a system header file named `x/*y'.

specifies inclusion of a system header file named `x/*y'.

   However, if backslashes occur within FILE, they are considered

   However, if backslashes occur within 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, `#include "x\n\\y"' specifies a filename containing three

Thus, `#include "x\n\\y"' specifies a filename containing three

backslashes.  (Some systems interpret `\' as a pathname separator.  All

backslashes.  (Some systems interpret `\' as a pathname separator.  All

of these also interpret `/' the same way.  It is most portable to use

of these also interpret `/' the same way.  It is most portable to use

only `/'.)

only `/'.)

   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.

File: cpp.info,  Node: Include Operation,  Next: Search Path,  Prev: Include Syntax,  Up: Header Files

File: cpp.info,  Node: Include Operation,  Next: Search Path,  Prev: Include Syntax,  Up: Header Files

2.2 Include Operation

2.2 Include Operation

=====================

=====================

The `#include' directive works by directing the C preprocessor to scan

The `#include' directive works by directing the C preprocessor to scan

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

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

`#include' directive.  For example, if you have a header file

`#include' directive.  For example, if you have a header file

`header.h' as follows,

`header.h' as follows,

     char *test (void);

     char *test (void);

and a main program called `program.c' that uses the header file, like

and a main program called `program.c' that uses the header file, like

this,

this,

     int x;

     int x;

     #include "header.h"

     #include "header.h"

     int

     int

     main (void)

     main (void)

     {

     {

       puts (test ());

       puts (test ());

     }

     }

the compiler will see the same token stream as it would if `program.c'

the compiler will see the same token stream as it would if `program.c'

read

read

     int x;

     int x;

     char *test (void);

     char *test (void);

     int

     int

     main (void)

     main (void)

     {

     {

       puts (test ());

       puts (test ());

     }

     }

   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 `#include' directive is always treated as a

   The line following the `#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.

File: cpp.info,  Node: Search Path,  Next: Once-Only Headers,  Prev: Include Operation,  Up: Header Files

File: cpp.info,  Node: Search Path,  Next: Once-Only Headers,  Prev: Include Operation,  Up: Header Files

2.3 Search Path

2.3 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 `#include ' in:

requested with `#include ' in:

     /usr/local/include

     /usr/local/include

     LIBDIR/gcc/TARGET/VERSION/include

     LIBDIR/gcc/TARGET/VERSION/include

     /usr/TARGET/include

     /usr/TARGET/include

     /usr/include

     /usr/include

   For C++ programs, it will also look in `/usr/include/g++-v3', first.

   For C++ programs, it will also look in `/usr/include/g++-v3', first.

In the above, TARGET is the canonical name of the system GCC was

In the above, TARGET is the canonical name of the system GCC was

configured to compile code for; often but not always the same as the

configured to compile code for; often but not always the same as the

canonical name of the system it runs on.  VERSION is the version of GCC

canonical name of the system it runs on.  VERSION is the version of GCC

in use.

in use.

   You can add to this list with the `-IDIR' command line option.  All

   You can add to this list with the `-IDIR' command line option.  All

the directories named by `-I' are searched, in left-to-right order,

the directories named by `-I' are searched, in left-to-right order,

_before_ the default directories.  The only exception is when `dir' is

_before_ the default directories.  The only exception is when `dir' is

already searched by default.  In this case, the option is ignored and

already searched by default.  In this case, the option is ignored and

the search order for system directories remains unchanged.

the search order for system 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

   You can prevent GCC from searching any of the default directories

with the `-nostdinc' option.  This is useful when you are compiling an

with the `-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.  `-I'

standard C library facilities, or the standard C library itself.  `-I'

options are not ignored as described above when `-nostdinc' is in

options are not ignored as described above when `-nostdinc' is in

effect.

effect.

   GCC looks for headers requested with `#include "FILE"' first in the

   GCC looks for headers requested with `#include "FILE"' first in the

directory containing the current file, then in the directories as

directory containing the current file, then in the directories as

specified by `-iquote' options, then in the same places it would have

specified by `-iquote' options, then in the same places it would have

looked for a header requested with angle brackets.  For example, if

looked for a header requested with angle brackets.  For example, if

`/usr/include/sys/stat.h' contains `#include "types.h"', GCC looks for

`/usr/include/sys/stat.h' contains `#include "types.h"', GCC looks for

`types.h' first in `/usr/include/sys', then in its usual search path.

`types.h' first in `/usr/include/sys', then in its usual search path.

   `#line' (*note Line Control::) does not change GCC's idea of the

   `#line' (*note Line Control::) does not change GCC's idea of the

directory containing the current file.

directory containing the current file.

   You may put `-I-' at any point in your list of `-I' options.  This

   You may put `-I-' at any point in your list of `-I' options.  This

has two effects.  First, directories appearing before the `-I-' in the

has two effects.  First, directories appearing before the `-I-' in the

list are searched only for headers requested with quote marks.

list are searched only for headers requested with quote marks.

Directories after `-I-' are searched for all headers.  Second, the

Directories after `-I-' are searched for all headers.  Second, the

directory containing the current file is not searched for anything,

directory containing the current file is not searched for anything,

unless it happens to be one of the directories named by an `-I' switch.

unless it happens to be one of the directories named by an `-I' switch.

`-I-' is deprecated, `-iquote' should be used instead.

`-I-' is deprecated, `-iquote' should be used instead.

   `-I. -I-' is not the same as no `-I' options at all, and does not

   `-I. -I-' is not the same as no `-I' options at all, and does not

cause the same behavior for `<>' includes that `""' includes get with

cause the same behavior for `<>' includes that `""' includes get with

no special options.  `-I.' searches the compiler's current working

no special options.  `-I.' searches the compiler's current working

directory for header files.  That may or may not be the same as the

directory for header files.  That may or may not be the same as the

directory containing the current file.

directory containing the current file.

   If you need to look for headers in a directory named `-', write

   If you need to look for headers in a directory named `-', write

`-I./-'.

`-I./-'.

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

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

are generally less useful.  *Note Invocation::.

are generally less useful.  *Note Invocation::.

File: cpp.info,  Node: Once-Only Headers,  Next: Computed Includes,  Prev: Search Path,  Up: Header Files

File: cpp.info,  Node: Once-Only Headers,  Next: Computed Includes,  Prev: Search Path,  Up: Header Files

2.4 Once-Only Headers

2.4 Once-Only Headers

=====================

=====================

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

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

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

not, it will certainly waste time.

not, it will certainly waste time.

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

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

contents of the file in a conditional, like this:

contents of the file in a conditional, like this:

     /* File foo.  */

     /* File foo.  */

     #ifndef FILE_FOO_SEEN

     #ifndef FILE_FOO_SEEN

     #define FILE_FOO_SEEN

     #define FILE_FOO_SEEN

     THE ENTIRE FILE

     THE ENTIRE FILE

     #endif /* !FILE_FOO_SEEN */

     #endif /* !FILE_FOO_SEEN */

   This construct is commonly known as a "wrapper #ifndef".  When the

   This construct is commonly known as a "wrapper #ifndef".  When the

header is included again, the conditional will be false, because

header is included again, the conditional will be false, because

`FILE_FOO_SEEN' is defined.  The preprocessor will skip over the entire

`FILE_FOO_SEEN' is defined.  The preprocessor will skip over the entire

contents of the file, and the compiler will not see it twice.

contents of the file, and the compiler will not see it twice.

   CPP optimizes even further.  It remembers when a header file has a

   CPP optimizes even further.  It remembers when a header file has a

wrapper `#ifndef'.  If a subsequent `#include' specifies that header,

wrapper `#ifndef'.  If a subsequent `#include' specifies that header,

and the macro in the `#ifndef' is still defined, it does not bother to

and the macro in the `#ifndef' is still defined, it does not bother to

rescan the file at all.

rescan the file at all.

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

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

with this optimization.

with this optimization.

   The macro `FILE_FOO_SEEN' is called the "controlling macro" or

   The macro `FILE_FOO_SEEN' is called the "controlling macro" or

"guard macro".  In a user header file, the macro name should not begin

"guard macro".  In a user header file, the macro name should not begin

with `_'.  In a system header file, it should begin with `__' to avoid

with `_'.  In a system header file, it should begin with `__' to avoid

conflicts with user programs.  In any kind of header file, the macro

conflicts with user programs.  In any kind of header file, the macro

name should contain the name of the file and some additional text, to

name should contain the name of the file and some additional text, to

avoid conflicts with other header files.

avoid conflicts with other header files.

File: cpp.info,  Node: Computed Includes,  Next: Wrapper Headers,  Prev: Once-Only Headers,  Up: Header Files

File: cpp.info,  Node: Computed Includes,  Next: Wrapper Headers,  Prev: Once-Only Headers,  Up: Header Files

2.5 Computed Includes

2.5 Computed Includes

=====================

=====================

Sometimes it is necessary to select one of several different header

Sometimes it is necessary to select one of several different header

files to be included into your program.  They might specify

files to be included into your program.  They might specify

configuration parameters to be used on different sorts of operating

configuration parameters to be used on different sorts of operating

systems, for instance.  You could do this with a series of conditionals,

systems, for instance.  You could do this with a series of conditionals,

     #if SYSTEM_1

     #if SYSTEM_1

     # include "system_1.h"

     # include "system_1.h"

     #elif SYSTEM_2

     #elif SYSTEM_2

     # include "system_2.h"

     # include "system_2.h"

     #elif SYSTEM_3

     #elif SYSTEM_3

     ...

     ...

     #endif

     #endif

   That rapidly becomes tedious.  Instead, the preprocessor offers the

   That rapidly becomes tedious.  Instead, the preprocessor offers the

ability to use a macro for the header name.  This is called a "computed

ability to use a macro for the header name.  This is called a "computed

include".  Instead of writing a header name as the direct argument of

include".  Instead of writing a header name as the direct argument of

`#include', you simply put a macro name there instead:

`#include', you simply put a macro name there instead:

     #define SYSTEM_H "system_1.h"

     #define SYSTEM_H "system_1.h"

     ...

     ...

     #include SYSTEM_H

     #include SYSTEM_H

`SYSTEM_H' will be expanded, and the preprocessor will look for

`SYSTEM_H' will be expanded, and the preprocessor will look for

`system_1.h' as if the `#include' had been written that way originally.

`system_1.h' as if the `#include' had been written that way originally.

`SYSTEM_H' could be defined by your Makefile with a `-D' option.

`SYSTEM_H' could be defined by your Makefile with a `-D' option.

   You must be careful when you define the macro.  `#define' saves

   You must be careful when you define the macro.  `#define' saves

tokens, not text.  The preprocessor has no way of knowing that the macro

tokens, not text.  The preprocessor has no way of knowing that the macro

will be used as the argument of `#include', so it generates ordinary

will be used as the argument of `#include', so it generates ordinary

tokens, not a header name.  This is unlikely to cause problems if you

tokens, not a header name.  This is unlikely to cause problems if you

use double-quote includes, which are close enough to string constants.

use double-quote includes, which are close enough to string constants.

If you use angle brackets, however, you may have trouble.

If you use angle brackets, however, you may have trouble.

   The syntax of a computed include is actually a bit more general than

   The syntax of a computed include is actually a bit more general than

the above.  If the first non-whitespace character after `#include' is

the above.  If the first non-whitespace character after `#include' is

not `"' or `<', then the entire line is macro-expanded like running

not `"' or `<', then the entire line is macro-expanded like running

text would be.

text would be.

   If the line expands to a single string constant, the contents of that

   If the line expands to a single string constant, the contents of that

string constant are the file to be included.  CPP does not re-examine

string constant are the file to be included.  CPP does not re-examine

the string for embedded quotes, but neither does it process backslash

the string for embedded quotes, but neither does it process backslash

escapes in the string.  Therefore

escapes in the string.  Therefore

     #define HEADER "a\"b"

     #define HEADER "a\"b"

     #include HEADER

     #include HEADER

looks for a file named `a\"b'.  CPP searches for the file according to

looks for a file named `a\"b'.  CPP searches for the file according to

the rules for double-quoted includes.

the rules for double-quoted includes.

   If the line expands to a token stream beginning with a `<' token and

   If the line expands to a token stream beginning with a `<' token and

including a `>' token, then the tokens between the `<' and the first

including a `>' token, then the tokens between the `<' and the first

`>' are combined to form the filename to be included.  Any whitespace

`>' are combined to form the filename to be included.  Any whitespace

between tokens is reduced to a single space; then any space after the

between tokens is reduced to a single space; then any space after the

initial `<' is retained, but a trailing space before the closing `>' is

initial `<' is retained, but a trailing space before the closing `>' is

ignored.  CPP searches for the file according to the rules for

ignored.  CPP searches for the file according to the rules for

angle-bracket includes.

angle-bracket includes.

   In either case, if there are any tokens on the line after the file

   In either case, if there are any tokens on the line after the file

name, an error occurs and the directive is not processed.  It is also

name, an error occurs and the directive is not processed.  It is also

an error if the result of expansion does not match either of the two

an error if the result of expansion does not match either of the two

expected forms.

expected forms.

   These rules are implementation-defined behavior according to the C

   These rules are implementation-defined behavior according to the C