Red Hat ENTERPRISE LINUX 4 - USING BINUTILS Manual

Red Hat Enterprise Linux 4
Using cpp, the C Preprocessor

Red Hat Enterprise Linux 4: Using cpp, the C Preprocessor
Copyright © 1987, 1989, 1991-2004 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.
This version is by Red Hat, Inc.
Red Hat, Inc.
1801 Varsity Drive
Raleigh NC 27606-2072 USA
Phone: [phone]
Phone: [phone]
Fax: [phone]
PO Box 13588
Research Triangle Park NC 27709 USA
cpp(EN)-4-HTML-RHI (2005-02-01)
Red Hat and the Red Hat "Shadow Man" logo are registered trademarks of Red Hat, Inc. in the United States and other
countries.
All other trademarks referenced herein are the property of their respective owners.
The GPG fingerprint of the [email protected] key is:
CA 20 86 86 2B D6 9D FC 65 F6 EC C4 21 91 80 CD DB 42 A6 0E

Table of Contents
1. Overview .......................................................................................................................................... 1
1.1. Character sets ..................................................................................................................... 1
1.2. Initial processing................................................................................................................ 2
1.3. Tokenization....................................................................................................................... 4
1.4. The preprocessing language............................................................................................... 6
2. Header Files..................................................................................................................................... 9
2.1. Include Syntax ................................................................................................................... 9
2.2. Include Operation............................................................................................................... 9
2.3. Search Path....................................................................................................................... 10
2.4. Once-Only Headers.......................................................................................................... 11
2.5. Computed Includes .......................................................................................................... 12
2.6. Wrapper Headers ............................................................................................................. 13
2.7. System Headers................................................................................................................ 13
3. Macros............................................................................................................................................ 15
3.1. Object-like Macros........................................................................................................... 15
3.2. Function-like Macros ....................................................................................................... 16
3.3. Macro Arguments ............................................................................................................ 17
3.4. Stringification................................................................................................................... 19
3.5. Concatenation .................................................................................................................. 20
3.6. Variadic Macros ............................................................................................................... 21
3.7. Predefined Macros ........................................................................................................... 23
3.7.1. Standard Predefined Macros ............................................................................. 23
3.7.2. Common Predefined Macros............................................................................. 25
3.7.3. System-specific Predefined Macros .................................................................. 27
3.7.4. C++ Named Operators ...................................................................................... 28
3.8. Undefining and Redefining Macros ................................................................................. 28
3.9. Directives Within Macro Arguments ............................................................................... 29
3.10. Macro Pitfalls................................................................................................................. 30
3.10.1. Misnesting....................................................................................................... 30
3.10.2. Operator Precedence Problems ....................................................................... 30
3.10.3. Swallowing the Semicolon.............................................................................. 31
3.10.4. Duplication of Side Effects............................................................................. 32
3.10.5. Self-Referential Macros .................................................................................. 33
3.10.6. Argument Prescan ........................................................................................... 34
3.10.7. Newlines in Arguments................................................................................... 35
4. Conditionals................................................................................................................................... 37
4.1. Conditional Uses.............................................................................................................. 37
4.2. Conditional Syntax .......................................................................................................... 37
4.2.1. Ifdef................................................................................................................... 37
4.2.2. If........................................................................................................................ 38
4.2.3. Defined.............................................................................................................. 39
4.2.4. Else.................................................................................................................... 40
4.2.5. Elif..................................................................................................................... 40
4.3. Deleted Code.................................................................................................................... 41

5. Diagnostics..................................................................................................................................... 43
6. Line Control .................................................................................................................................. 45
7. Pragmas ......................................................................................................................................... 47
8. Other Directives ............................................................................................................................ 49
9. Preprocessor Output..................................................................................................................... 51
10. Traditional Mode ........................................................................................................................ 53
10.1. Traditional lexical analysis ............................................................................................ 53
10.2. Traditional macros ......................................................................................................... 54
10.3. Traditional miscellany.................................................................................................... 55
10.4. Traditional warnings ...................................................................................................... 55
11. Implementation Details .............................................................................................................. 57
11.1. Implementation-defined behavior .................................................................................. 57
11.2. Implementation limits .................................................................................................... 58
11.3. Obsolete Features........................................................................................................... 58
11.3.1. Assertions........................................................................................................ 59
11.3.2. Obsolete once-only headers ............................................................................ 60
11.4. Differences from previous versions ............................................................................... 60
12. Invocation .................................................................................................................................... 63
13. Environment Variables ............................................................................................................... 73
14. GNU Free Documentation License............................................................................................ 75
14.1. ADDENDUM: How to use this License for your documents ....................................... 79
Index of Directives ............................................................................................................................ 81
Option Index...................................................................................................................................... 83
Concept Index.................................................................................................................................... 85

The C Preprocessor

Chapter 1.
Overview
The C preprocessor implements the macro language used to transform C, C++, and Objective-C pro-
grams before they are compiled. It can also be useful on its own.
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. Chapter
12 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 Chapter 10 Traditional Mode.
For clarity, unless noted otherwise, references to CPP in this manual refer to GNU CPP.

2 Chapter 1. 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.1Octal 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.
GCC does not permit the use of characters outside the ASCII range, nor \u and \U escapes, in identi-
fiers. We hope this will change eventually, but there are problems with the standard semantics of such
"extended identifiers" which must be resolved through the ISO C and C++ committees first.
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 rea-
sons. 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 consis-
tently 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.
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.

Chapter 1. Overview 3
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.
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 */

4 Chapter 1. Overview
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.
1.3. Tokenization
After the textual transformations are finished, the input file is converted into a sequence of prepro-
cessing 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 prepro-
cessor 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. Section 3.5 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