Subversion Repositories scarts

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

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

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

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

Foundation, Inc.

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

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

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

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

License".

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

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

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

   A GNU Manual

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

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

software.  Copies published by the Free Software Foundation raise

funds for GNU development.

INFO-DIR-SECTION Programming

START-INFO-DIR-ENTRY

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

END-INFO-DIR-ENTRY

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

The C Preprocessor

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

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

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

useful on its own.

* Menu:

* Overview::

* Header Files::

* Macros::

* Conditionals::

* Diagnostics::

* Line Control::

* Pragmas::

* Other Directives::

* Preprocessor Output::

* Traditional Mode::

* Implementation Details::

* Invocation::

* Environment Variables::

* GNU Free Documentation License::

* Index of Directives::

* Option Index::

* Concept Index::

 --- The Detailed Node Listing ---

Overview

* Character sets::

* Initial processing::

* Tokenization::

* The preprocessing language::

Header Files

* Include Syntax::

* Include Operation::

* Search Path::

* Once-Only Headers::

* Computed Includes::

* Wrapper Headers::

* System Headers::

Macros

* Object-like Macros::

* Function-like Macros::

* Macro Arguments::

* Stringification::

* Concatenation::

* Variadic Macros::

* Predefined Macros::

* Undefining and Redefining Macros::

* Directives Within Macro Arguments::

* Macro Pitfalls::

Predefined Macros

* Standard Predefined Macros::

* Common Predefined Macros::

* System-specific Predefined Macros::

* C++ Named Operators::

Macro Pitfalls

* Misnesting::

* Operator Precedence Problems::

* Swallowing the Semicolon::

* Duplication of Side Effects::

* Self-Referential Macros::

* Argument Prescan::

* Newlines in Arguments::

Conditionals

* Conditional Uses::

* Conditional Syntax::

* Deleted Code::

Conditional Syntax

* Ifdef::

* If::

* Defined::

* Else::

* Elif::

Implementation Details

* Implementation-defined behavior::

* Implementation limits::

* Obsolete Features::

* Differences from previous versions::

Obsolete Features

* Assertions::

* Obsolete once-only headers::

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

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

Foundation, Inc.

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

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

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

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

License".

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

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

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

   A GNU Manual

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

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

software.  Copies published by the Free Software Foundation raise

funds for GNU development.

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

1 Overview

**********

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

is used automatically by the C compiler to transform your program

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

you to define "macros", which are brief abbreviations for longer

constructs.

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

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

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

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

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

preserving characteristics of the input which are not significant to

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

will be removed, and the Makefile will not work.

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

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

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

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

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

instead of native language comments, and keeping macros simple.

   Wherever possible, you should use a preprocessor geared to the

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

macro facilities.  Most high level programming languages have their own

conditional compilation and inclusion mechanism.  If all else fails,

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

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

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

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

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

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

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

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

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

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

   This manual describes the behavior of the ISO preprocessor.  To

minimize gratuitous differences, where the ISO preprocessor's behavior

does not conflict with traditional semantics, the traditional

preprocessor should behave the same way.  The various differences that

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

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

manual refer to GNU CPP.

* Menu:

* Character sets::

* Initial processing::

* Tokenization::

* The preprocessing language::

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

1.1 Character sets

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

Source code character set processing in C and related languages is

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

there are really at least four.

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

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

convert the file into the character set it uses for internal

processing.  That set is what the C standard calls the "source"

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

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

   At present, GNU CPP does not implement conversion from arbitrary file

encodings to the source character set.  Use of any encoding other than

plain ASCII or UTF-8, except in comments, will cause errors.  Use of

encodings that are not strict supersets of ASCII, such as Shift JIS,

may cause errors even if non-ASCII characters appear only in comments.

We plan to fix this in the near future.

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

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

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

   After preprocessing is complete, string and character constants are

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

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

source character set.  Wide string and character constants have their

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

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

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

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

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

currently selected execution character set.  All other escapes are

replaced by the character in the source character set that they

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

unescaped characters.

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

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

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

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

escapes, not used directly in identifiers.

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

   (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

some system ABIs so we cannot fix this.

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

1.2 Initial processing

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

The preprocessor performs a series of textual transformations on its

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

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

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

at once, for performance reasons.  These transformations correspond

roughly to the first three "phases of translation" described in the C

standard.

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

     Different systems use different conventions to indicate the end of

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

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

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

     respectively.  You may therefore safely copy source code written

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

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

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

     when it is edited on computers with different conventions that

     share a network file system.)

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

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

     standard says that this condition provokes undefined behavior, so

     GCC will emit a warning message.

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

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

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

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

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

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

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

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

     constant for a newline.

     Trigraphs are not popular and many compilers implement them

     incorrectly.  Portable code should not rely on trigraphs being

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

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

     converted.  *Note Wtrigraphs::.

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

     from being confused with a trigraph by inserting a backslash

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

     the trigraph and making use of string literal concatenation.

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

     compilers do not recognize these idioms.

     The nine trigraphs and their replacements are

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

          Replacement:      [    ]    {    }    #    \    ^    |    ~

  3. Continued lines are merged into one long line.

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

     backslash is removed and the following line is joined with the

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

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

     readable to split lines only at white space.)

     The trailing backslash on a continued line is commonly referred to

     as a "backslash-newline".

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

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

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

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

  4. All comments are replaced with single spaces.

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

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

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

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

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

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

          // this is // one comment

          text outside comment

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

     /* block comment

        // contains line comment

        yet more comment

      */ outside comment

     // line comment /* contains block comment */

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

comment.

      // l.c.  /* block comment begins

         oops! this isn't a comment anymore */

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

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

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

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

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

   Since these transformations happen before all other processing, you

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

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

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

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

     /\

     *

     */ # /*

     */ defi\

     ne FO\

     O 10\

     20

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

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

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

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

correct program, however.

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

1.3 Tokenization

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

After the textual transformations are finished, the input file is

converted into a sequence of "preprocessing tokens".  These mostly

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

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

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

but it is often necessary to avoid ambiguities.

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

possible tokenization, the preprocessor is greedy.  It always makes

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

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

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

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

not.

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

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

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

     #define foo() bar

     foo()baz

          ==> bar baz

     _not_

          ==> barbaz

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

preprocessing token becomes one compiler token.

   Preprocessing tokens fall into five broad classes: identifiers,

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

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

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

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

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

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

preprocessing keyword is `defined'.  *Note Defined::.

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

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

preprocessor.  *Note C++ Named Operators::.

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

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

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

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

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

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

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

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

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

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

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

Invocation::.

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

category includes all the normal integer and floating point constants

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

initially recognize as a number.  Formally, preprocessing numbers begin

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

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

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

`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

constants.)

   The purpose of this unusual definition is to isolate the preprocessor

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

distinguish between lexically valid and invalid floating-point numbers,

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

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

pasted back together with the `##' operator.

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

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

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

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

intended.

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

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

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

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, but the value of a character constant that contains

more than one character is implementation-defined.  *Note

Implementation Details::.

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

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

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

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

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

Operation::.

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

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

lines instead, or string constant concatenation.  *Note Differences

from previous versions::.

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

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

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

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

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

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

punctuators.  This is a second attempt to work around missing

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

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

their corresponding normal punctuators are:

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

     Punctuator:      {   }   [   ]   #    ##

   Any other single character is considered "other".  It is passed on to

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

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

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

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

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

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

change when proper support for international character sets is added to

GCC.

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

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

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

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

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

have the same meaning.

     #define X^@1

     #define X 1

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

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

warning message.

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

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

what we are calling "string constants".

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

1.4 The preprocessing language

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

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

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

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

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

most people think of as the preprocessor's job.

   The preprocessing language consists of "directives" to be executed

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

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

     can be substituted into your program.

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

     for arbitrary fragments of C code.  The preprocessor will replace

     the macros with their definitions throughout the program.  Some

     macros are automatically defined for you.

   * Conditional compilation.  You can include or exclude parts of the

     program according to various conditions.

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

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

     use line control to inform the compiler where each source line

     originally came from.

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

     errors or warnings.

   There are a few more, less useful, features.

   Except for expansion of predefined macros, all these operations are

triggered with "preprocessing directives".  Preprocessing directives

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

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

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

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

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

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

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

valid preprocessing directive.

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

new preprocessing directives.

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

directive line and must be separated from the directive name by

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

and the intended expansion of the macro.

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

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

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

directive is processed, the continuations have already been merged with

the first line to make one long line.

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

2 Header Files

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

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

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

preprocessing directive `#include'.

   Header files serve two purposes.

   * System header files declare the interfaces to parts of the

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

     definitions and declarations you need to invoke system calls and

     libraries.

   * Your own header files contain declarations for interfaces between

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

     related declarations and macro definitions all or most of which

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

     create a header file for them.

   Including a header file produces the same results as copying the

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

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

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

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

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

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

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

inconsistencies within a program.

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

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

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

* Menu:

* Include Syntax::

* Include Operation::

* Search Path::

* Once-Only Headers::

* Computed Includes::

* Wrapper Headers::

* System Headers::

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

2.1 Include Syntax

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

Both user and system header files are included using the preprocessing

directive `#include'.  It has two variants:

`#include '

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

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

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

     Invocation::).

`#include "FILE"'

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

     searches for a file named FILE first in the directory containing

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

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

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

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

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

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

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

   However, if backslashes occur within FILE, they are considered

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

escape sequences appropriate to string constants in C are processed.

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

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

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

only `/'.)

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

after the file name.

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

2.2 Include Operation

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

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

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

current file.  The output from the preprocessor contains the output

already generated, followed by the output resulting from the included

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

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

`header.h' as follows,

     char *test (void);

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

this,

     int x;

     #include "header.h"

     int

     main (void)

     {

       puts (test ());

     }

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

read

     int x;

     char *test (void);

     int

     main (void)

     {

       puts (test ());

     }

   Included files are not limited to declarations and macro definitions;

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

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

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

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

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

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

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

the file.

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

syntactic units--function declarations or definitions, type

declarations, etc.

   The line following the `#include' directive is always treated as a

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

final newline.

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

2.3 Search Path

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

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

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

requested with `#include ' in:

     /usr/local/include

     LIBDIR/gcc/TARGET/VERSION/include

     /usr/TARGET/include

     /usr/include

   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

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

in use.

   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,

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

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

the search order for system directories remains unchanged.

   Duplicate directories are removed from the quote and bracket search

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

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

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

   You can prevent GCC from searching any of the default directories

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

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

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

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

effect.

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

directory containing the current file, then in the directories as

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

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

`/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.

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

directory containing the current file.

   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

list are searched only for headers requested with quote marks.

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

directory containing the current file is not searched for anything,

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

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

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

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 containing the current file.

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

`-I./-'.

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

are generally less useful.  *Note Invocation::.

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

2.4 Once-Only Headers

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

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

its contents twice.  This is very likely to cause an error, e.g. when

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

not, it will certainly waste time.

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

contents of the file in a conditional, like this:

     /* File foo.  */

     #ifndef FILE_FOO_SEEN

     #define FILE_FOO_SEEN

     THE ENTIRE FILE

     #endif /* !FILE_FOO_SEEN */

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

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

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

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

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

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

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

rescan the file at all.

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

with this optimization.

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

"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

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

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

avoid conflicts with other header files.

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

2.5 Computed Includes

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

Sometimes it is necessary to select one of several different header

files to be included into your program.  They might specify

configuration parameters to be used on different sorts of operating

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

     #if SYSTEM_1

     # include "system_1.h"

     #elif SYSTEM_2

     # include "system_2.h"

     #elif SYSTEM_3

     ...

     #endif

   That rapidly becomes tedious.  Instead, the preprocessor offers the

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', you simply put a macro name there instead:

     #define SYSTEM_H "system_1.h"

     ...

     #include SYSTEM_H

`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_H' could be defined by your Makefile with a `-D' option.

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

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

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

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

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

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

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

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

text would be.

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

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

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

escapes in the string.  Therefore

     #define HEADER "a\"b"

     #include HEADER

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

the rules for double-quoted includes.

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

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

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

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

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

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

angle-bracket includes.

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

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