| \input texinfo |
| @setfilename cpp.info |
| @settitle The C Preprocessor |
| @setchapternewpage off |
| @c @smallbook |
| @c @cropmarks |
| @c @finalout |
| |
| @macro copyrightnotice |
| @c man begin COPYRIGHT |
| Copyright @copyright{} 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, |
| 1997, 1998, 1999, 2000, 2001 |
| Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.1 or |
| any later version published by the Free Software Foundation. A copy of |
| the license is included in the |
| @c man end |
| section entitled ``GNU Free Documentation License''. |
| @ignore |
| @c man begin COPYRIGHT |
| man page gfdl(7). |
| @c man end |
| @end ignore |
| @end macro |
| |
| @macro covertexts |
| @c man begin COPYRIGHT |
| This manual contains no Invariant Sections. The Front-Cover Texts are |
| (a) (see below), and the Back-Cover Texts are (b) (see below). |
| |
| (a) The FSF's Front-Cover Text is: |
| |
| A GNU Manual |
| |
| (b) The FSF's Back-Cover Text is: |
| |
| You have freedom to copy and modify this GNU Manual, like GNU |
| software. Copies published by the Free Software Foundation raise |
| funds for GNU development. |
| @c man end |
| @end macro |
| |
| @macro gcctabopt{body} |
| @code{\body\} |
| @end macro |
| |
| @ifinfo |
| @dircategory Programming |
| @direntry |
| * Cpp: (cpp). The GNU C preprocessor. |
| @end direntry |
| @end ifinfo |
| |
| @titlepage |
| @title The C Preprocessor |
| @subtitle Last revised April 2001 |
| @subtitle for GCC version 3 |
| @author Richard M. Stallman |
| @author Zachary Weinberg |
| @page |
| @c There is a fill at the bottom of the page, so we need a filll to |
| @c override it. |
| @vskip 0pt plus 1filll |
| @copyrightnotice{} |
| @covertexts{} |
| @end titlepage |
| @contents |
| @page |
| |
| @node Top |
| @top |
| The C preprocessor implements the macro language used to transform C, |
| C++, and Objective-C programs before they are compiled. It can also be |
| useful on its own. |
| |
| @menu |
| * Overview:: |
| * Header Files:: |
| * Macros:: |
| * Conditionals:: |
| * Diagnostics:: |
| * Line Control:: |
| * Pragmas:: |
| * Other Directives:: |
| * Preprocessor Output:: |
| * Traditional Mode:: |
| * Implementation Details:: |
| * Invocation:: |
| * GNU Free Documentation License:: |
| * Index of Directives:: |
| * Concept Index:: |
| |
| @detailmenu |
| --- The Detailed Node Listing --- |
| |
| Overview |
| |
| * 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:: |
| * Miscellaneous obsolete features:: |
| |
| @end detailmenu |
| @end menu |
| |
| @ifnottex |
| @copyrightnotice{} |
| @covertexts{} |
| @end ifnottex |
| |
| @node Overview |
| @chapter Overview |
| @c man begin DESCRIPTION |
| The C preprocessor, often known as @dfn{cpp}, is a @dfn{macro processor} |
| that is used automatically by the C compiler to transform your program |
| before compilation. It is called a macro processor because it allows |
| you to define @dfn{macros}, which are brief abbreviations for longer |
| constructs. |
| |
| The C preprocessor is intended to be used only with C, C++, and |
| Objective-C source code. In the past, it has been abused as a general |
| text processor. It will choke on input which does not obey C's lexical |
| rules. For example, apostrophes will be interpreted as the beginning of |
| character constants, and cause errors. Also, you cannot rely on it |
| preserving characteristics of the input which are not significant to |
| C-family languages. If a Makefile is preprocessed, all the hard tabs |
| will be removed, and the Makefile will not work. |
| |
| Having said that, you can often get away with using cpp on things which |
| are not C@. Other Algol-ish programming languages are often safe |
| (Pascal, Ada, etc.) So is assembly, with caution. @option{-traditional} |
| mode preserves more white space, and is otherwise more permissive. Many |
| of the problems can be avoided by writing C or C++ style comments |
| instead of native language comments, and keeping macros simple. |
| |
| Wherever possible, you should use a preprocessor geared to the language |
| you are writing in. Modern versions of the GNU assembler have macro |
| facilities. Most high level programming languages have their own |
| conditional compilation and inclusion mechanism. If all else fails, |
| try a true general text processor, such as GNU M4. |
| |
| C preprocessors vary in some details. This manual discusses the GNU C |
| preprocessor, which provides a small superset of the features of ISO |
| Standard C@. In its default mode, the GNU C preprocessor does not do a |
| few things required by the standard. These are features which are |
| rarely, if ever, used, and may cause surprising changes to the meaning |
| of a program which does not expect them. To get strict ISO Standard C, |
| you should use the @option{-std=c89} or @option{-std=c99} options, depending |
| on which version of the standard you want. To get all the mandatory |
| diagnostics, you must also use @option{-pedantic}. @xref{Invocation}. |
| @c man end |
| |
| @menu |
| * Initial processing:: |
| * Tokenization:: |
| * The preprocessing language:: |
| @end menu |
| |
| @node Initial processing |
| @section Initial processing |
| |
| The preprocessor performs a series of textual transformations on its |
| input. These happen before all other processing. Conceptually, they |
| happen in a rigid order, and the entire file is run through each |
| transformation before the next one begins. GNU CPP actually does them |
| all at once, for performance reasons. These transformations correspond |
| roughly to the first three ``phases of translation'' described in the C |
| standard. |
| |
| @enumerate |
| @item |
| @cindex character sets |
| @cindex line endings |
| The input file is read into memory and broken into lines. |
| |
| GNU CPP expects its input to be a text file, that is, an unstructured |
| stream of ASCII characters, with some characters indicating the end of a |
| line of text. Extended ASCII character sets, such as ISO Latin-1 or |
| Unicode encoded in UTF-8, are also acceptable. Character sets that are |
| not strict supersets of seven-bit ASCII will not work. We plan to add |
| complete support for international character sets in a future release. |
| |
| Different systems use different conventions to indicate the end of a |
| line. GCC accepts the ASCII control sequences @kbd{LF}, @kbd{@w{CR |
| LF}}, @kbd{CR}, and @kbd{@w{LF CR}} as end-of-line markers. The first |
| three 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.) @kbd{@w{LF CR}} is included because it has been |
| reported as an end-of-line marker under exotic conditions. |
| |
| If the last line of any input file lacks an end-of-line marker, the end |
| of the file is considered to implicitly supply one. The C standard says |
| that this condition provokes undefined behavior, so GCC will emit a |
| warning message. |
| |
| @item |
| @cindex trigraphs |
| If trigraphs are enabled, they are replaced by their corresponding |
| single characters. |
| |
| These are nine three-character sequences, all starting with @samp{??}, |
| that are defined by ISO C to stand for single characters. They permit |
| obsolete systems that lack some of C's punctuation to use C@. For |
| example, @samp{??/} stands for @samp{\}, so @t{'??/n'} is a character |
| constant for a newline. By default, GCC ignores trigraphs, but if you |
| request a strictly conforming mode with the @option{-std} option, then |
| it converts them. |
| |
| Trigraphs are not popular and many compilers implement them incorrectly. |
| Portable code should not rely on trigraphs being either converted or |
| ignored. If you use the @option{-Wall} or @option{-Wtrigraphs} options, |
| GCC will warn you when a trigraph would 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. @t{"(??\?)"} is the string @samp{(???)}, not |
| @samp{(?]}. Traditional C compilers do not recognize this idiom. |
| |
| The nine trigraphs and their replacements are |
| |
| @example |
| Trigraph: ??( ??) ??< ??> ??= ??/ ??' ??! ??- |
| Replacement: [ ] @{ @} # \ ^ | ~ |
| @end example |
| |
| @item |
| @cindex continued lines |
| @cindex backslash-newline |
| Continued lines are merged into one long line. |
| |
| A continued line is a line which ends with a backslash, @samp{\}. The |
| backslash is removed and the following line is joined with the current |
| one. No space is inserted, so you may split a line anywhere, even in |
| the middle of a word. (It is generally more readable to split lines |
| only at white space.) |
| |
| The trailing backslash on a continued line is commonly referred to as a |
| @dfn{backslash-newline}. |
| |
| If there is white space between a backslash and the end of a line, that |
| is still a continued line. However, as this is usually the result of an |
| editing mistake, and many compilers will not accept it as a continued |
| line, GCC will warn you about it. |
| |
| @item |
| @cindex comments |
| @cindex line comments |
| @cindex block comments |
| All comments are replaced with single spaces. |
| |
| There are two kinds of comments. @dfn{Block comments} begin with |
| @samp{/*} and continue until the next @samp{*/}. Block comments do not |
| nest: |
| |
| @example |
| /* @r{this is} /* @r{one comment} */ @r{text outside comment} |
| @end example |
| |
| @dfn{Line comments} begin with @samp{//} and continue to the end of the |
| current line. Line comments do not nest either, but it does not matter, |
| because they would end in the same place anyway. |
| |
| @example |
| // @r{this is} // @r{one comment} |
| @r{text outside comment} |
| @end example |
| @end enumerate |
| |
| It is safe to put line comments inside block comments, or vice versa. |
| |
| @example |
| @group |
| /* @r{block comment} |
| // @r{contains line comment} |
| @r{yet more comment} |
| */ @r{outside comment} |
| |
| // @r{line comment} /* @r{contains block comment} */ |
| @end group |
| @end example |
| |
| But beware of commenting out one end of a block comment with a line |
| comment. |
| |
| @example |
| @group |
| // @r{l.c.} /* @r{block comment begins} |
| @r{oops! this isn't a comment anymore} */ |
| @end group |
| @end example |
| |
| Comments are not recognized within string literals. @t{@w{"/* blah |
| */"}} is the string constant @samp{@w{/* blah */}}, not an empty string. |
| |
| Line comments are not in the 1989 edition of the C standard, but they |
| are recognized by GCC as an extension. In C++ and in the 1999 edition |
| of the C standard, they are an official part of the language. |
| |
| Since these transformations happen before all other processing, you can |
| split a line mechanically with backslash-newline anywhere. You can |
| comment out the end of a line. You can continue a line comment onto the |
| next line with backslash-newline. You can even split @samp{/*}, |
| @samp{*/}, and @samp{//} onto multiple lines with backslash-newline. |
| For example: |
| |
| @example |
| @group |
| /\ |
| * |
| */ # /* |
| */ defi\ |
| ne FO\ |
| O 10\ |
| 20 |
| @end group |
| @end example |
| |
| @noindent |
| is equivalent to @code{@w{#define FOO 1020}}. All these tricks are |
| extremely confusing and should not be used in code intended to be |
| readable. |
| |
| There is no way to prevent a backslash at the end of a line from being |
| interpreted as a backslash-newline. |
| |
| @example |
| "foo\\ |
| bar" |
| @end example |
| |
| @noindent |
| is equivalent to @code{"foo\bar"}, not to @code{"foo\\bar"}. To avoid |
| having to worry about this, do not use the deprecated GNU extension |
| which permits multi-line strings. Instead, use string literal |
| concatenation: |
| |
| @example |
| "foo\\" |
| "bar" |
| @end example |
| |
| @noindent |
| Your program will be more portable this way, too. |
| |
| @node Tokenization |
| @section Tokenization |
| |
| @cindex tokens |
| @cindex preprocessing tokens |
| After the textual transformations are finished, the input file is |
| converted into a sequence of @dfn{preprocessing tokens}. These mostly |
| correspond to the syntactic tokens used by the C compiler, but there are |
| a few differences. White space separates tokens; it is not itself a |
| token of any kind. Tokens do not have to be separated by white space, |
| but it is often necessary to avoid ambiguities. |
| |
| When faced with a sequence of characters that has more than one possible |
| tokenization, the preprocessor is greedy. It always makes each token, |
| starting from the left, as big as possible before moving on to the next |
| token. For instance, @code{a+++++b} is interpreted as |
| @code{@w{a ++ ++ + b}}, not as @code{@w{a ++ + ++ b}}, even though the |
| latter tokenization could be part of a valid C program and the former |
| could not. |
| |
| Once the input file is broken into tokens, the token boundaries never |
| change, except when the @samp{##} preprocessing operator is used to paste |
| tokens together. @xref{Concatenation}. For example, |
| |
| @example |
| @group |
| #define foo() bar |
| foo()baz |
| @expansion{} bar baz |
| @emph{not} |
| @expansion{} barbaz |
| @end group |
| @end example |
| |
| The compiler does not re-tokenize the preprocessor's output. Each |
| preprocessing token becomes one compiler token. |
| |
| @cindex identifiers |
| Preprocessing tokens fall into five broad classes: identifiers, |
| preprocessing numbers, string literals, punctuators, and other. An |
| @dfn{identifier} is the same as an identifier in C: any sequence of |
| letters, digits, or underscores, which begins with a letter or |
| underscore. Keywords of C have no significance to the preprocessor; |
| they are ordinary identifiers. You can define a macro whose name is a |
| keyword, for instance. The only identifier which can be considered a |
| preprocessing keyword is @code{defined}. @xref{Defined}. |
| |
| This is mostly true of other languages which use the C preprocessor. |
| However, a few of the keywords of C++ are significant even in the |
| preprocessor. @xref{C++ Named Operators}. |
| |
| In the 1999 C standard, identifiers may contain letters which are not |
| part of the ``basic source character set,'' at the implementation's |
| discretion (such as accented Latin letters, Greek letters, or Chinese |
| ideograms). This may be done with an extended character set, or the |
| @samp{\u} and @samp{\U} escape sequences. GCC does not presently |
| implement either feature in the preprocessor or the compiler. |
| |
| As an extension, GCC treats @samp{$} as a letter. This is for |
| compatibility with some systems, such as VMS, where @samp{$} is commonly |
| used in system-defined function and object names. @samp{$} is not a |
| letter in strictly conforming mode, or if you specify the @option{-$} |
| option. @xref{Invocation}. |
| |
| @cindex numbers |
| @cindex preprocessing numbers |
| A @dfn{preprocessing number} has a rather bizarre definition. The |
| category includes all the normal integer and floating point constants |
| one expects of C, but also a number of other things one might not |
| initially recognize as a number. Formally, preprocessing numbers begin |
| with an optional period, a required decimal digit, and then continue |
| with any sequence of letters, digits, underscores, periods, and |
| exponents. Exponents are the two-character sequences @samp{e+}, |
| @samp{e-}, @samp{E+}, @samp{E-}, @samp{p+}, @samp{p-}, @samp{P+}, and |
| @samp{P-}. (The exponents that begin with @samp{p} or @samp{P} are new |
| to C99. They are used for hexadecimal floating-point constants.) |
| |
| The purpose of this unusual definition is to isolate the preprocessor |
| from the full complexity of numeric constants. It does not have to |
| distinguish between lexically valid and invalid floating-point numbers, |
| which is complicated. The definition also permits you to split an |
| identifier at any position and get exactly two tokens, which can then be |
| pasted back together with the @samp{##} operator. |
| |
| It's possible for preprocessing numbers to cause programs to be |
| misinterpreted. For example, @code{0xE+12} is a preprocessing number |
| which does not translate to any valid numeric constant, therefore a |
| syntax error. It does not mean @code{@w{0xE + 12}}, which is what you |
| might have intended. |
| |
| @cindex string literals |
| @cindex string constants |
| @cindex character constants |
| @cindex header file names |
| @c the @: prevents makeinfo from turning '' into ". |
| @dfn{String literals} are string constants, character constants, and |
| header file names (the argument of @samp{#include}).@footnote{The C |
| standard uses the term @dfn{string literal} to refer only to what we are |
| calling @dfn{string constants}.} String constants and character |
| constants are straightforward: @t{"@dots{}"} or @t{'@dots{}'}. In |
| either case embedded quotes should be escaped with a backslash: |
| @t{'\'@:'} is the character constant for @samp{'}. There is no limit on |
| the length of a character constant, but the value of a character |
| constant that contains more than one character is |
| implementation-defined. @xref{Implementation Details}. |
| |
| Header file names either look like string constants, @t{"@dots{}"}, or are |
| written with angle brackets instead, @t{<@dots{}>}. In either case, |
| backslash is an ordinary character. There is no way to escape the |
| closing quote or angle bracket. The preprocessor looks for the header |
| file in different places depending on which form you use. @xref{Include |
| Operation}. |
| |
| In standard C, no string literal may extend past the end of a line. GNU |
| CPP accepts multi-line string constants, but not multi-line character |
| constants or header file names. This extension is deprecated and will |
| be removed in GCC 3.1. You may use continued lines instead, or string |
| constant concatenation. @xref{Differences from previous versions}. |
| |
| @cindex punctuators |
| @cindex digraphs |
| @cindex alternative tokens |
| @dfn{Punctuators} are all the usual bits of punctuation which are |
| meaningful to C and C++. All but three of the punctuation characters in |
| ASCII are C punctuators. The exceptions are @samp{@@}, @samp{$}, and |
| @samp{`}. In addition, all the two- and three-character operators are |
| punctuators. There are also six @dfn{digraphs}, which the C++ standard |
| calls @dfn{alternative tokens}, which are merely alternate ways to spell |
| other punctuators. This is a second attempt to work around missing |
| punctuation in obsolete systems. It has no negative side effects, |
| unlike trigraphs, but does not cover as much ground. The digraphs and |
| their corresponding normal punctuators are: |
| |
| @example |
| Digraph: <% %> <: :> %: %:%: |
| Punctuator: @{ @} [ ] # ## |
| @end example |
| |
| @cindex other tokens |
| Any other single character is considered ``other.'' It is passed on to |
| the preprocessor's output unmolested. The C compiler will almost |
| certainly reject source code containing ``other'' tokens. In ASCII, the |
| only other characters are @samp{@@}, @samp{$}, @samp{`}, and control |
| characters other than NUL (all bits zero). (Note that @samp{$} is |
| normally considered a letter.) All characters with the high bit set |
| (numeric range 0x7F--0xFF) are also ``other'' in the present |
| implementation. This will change when proper support for international |
| character sets is added to GCC@. |
| |
| NUL is a special case because of the high probability that its |
| appearance is accidental, and because it may be invisible to the user |
| (many terminals do not display NUL at all). Within comments, NULs are |
| silently ignored, just as any other character would be. In running |
| text, NUL is considered white space. For example, these two directives |
| have the same meaning. |
| |
| @example |
| #define X^@@1 |
| #define X 1 |
| @end example |
| |
| @noindent |
| (where @samp{^@@} is ASCII NUL)@. Within string or character constants, |
| NULs are preserved. In the latter two cases the preprocessor emits a |
| warning message. |
| |
| @node The preprocessing language |
| @section The preprocessing language |
| @cindex directives |
| @cindex preprocessing directives |
| @cindex directive line |
| @cindex directive name |
| |
| After tokenization, the stream of tokens may simply be passed straight |
| to the compiler's parser. However, if it contains any operations in the |
| @dfn{preprocessing language}, it will be transformed first. This stage |
| corresponds roughly to the standard's ``translation phase 4'' and is |
| what most people think of as the preprocessor's job. |
| |
| The preprocessing language consists of @dfn{directives} to be executed |
| and @dfn{macros} to be expanded. Its primary capabilities are: |
| |
| @itemize @bullet |
| @item |
| Inclusion of header files. These are files of declarations that can be |
| substituted into your program. |
| |
| @item |
| Macro expansion. You can define @dfn{macros}, which are abbreviations |
| for arbitrary fragments of C code. The preprocessor will replace the |
| macros with their definitions throughout the program. Some macros are |
| automatically defined for you. |
| |
| @item |
| Conditional compilation. You can include or exclude parts of the |
| program according to various conditions. |
| |
| @item |
| Line control. If you use a program to combine or rearrange source files |
| into an intermediate file which is then compiled, you can use line |
| control to inform the compiler where each source line originally came |
| from. |
| |
| @item |
| Diagnostics. You can detect problems at compile time and issue errors |
| or warnings. |
| @end itemize |
| |
| There are a few more, less useful, features. |
| |
| Except for expansion of predefined macros, all these operations are |
| triggered with @dfn{preprocessing directives}. Preprocessing directives |
| are lines in your program that start with @samp{#}. Whitespace is |
| allowed before and after the @samp{#}. The @samp{#} is followed by an |
| identifier, the @dfn{directive name}. It specifies the operation to |
| perform. Directives are commonly referred to as @samp{#@var{name}} |
| where @var{name} is the directive name. For example, @samp{#define} is |
| the directive that defines a macro. |
| |
| The @samp{#} which begins a directive cannot come from a macro |
| expansion. Also, the directive name is not macro expanded. Thus, if |
| @code{foo} is defined as a macro expanding to @code{define}, that does |
| not make @samp{#foo} a valid preprocessing directive. |
| |
| The set of valid directive names is fixed. Programs cannot define new |
| preprocessing directives. |
| |
| Some directives require arguments; these make up the rest of the |
| directive line and must be separated from the directive name by |
| whitespace. For example, @samp{#define} must be followed by a macro |
| name and the intended expansion of the macro. |
| |
| A preprocessing directive cannot cover more than one line. The line |
| may, however, be continued with backslash-newline, or by a block comment |
| which extends past the end of the line. In either case, when the |
| directive is processed, the continuations have already been merged with |
| the first line to make one long line. |
| |
| @node Header Files |
| @chapter Header Files |
| |
| @cindex header file |
| A header file is a file containing C declarations and macro definitions |
| (@pxref{Macros}) to be shared between several source files. You request |
| the use of a header file in your program by @dfn{including} it, with the |
| C preprocessing directive @samp{#include}. |
| |
| Header files serve two purposes. |
| |
| @itemize @bullet |
| @item |
| @cindex system header files |
| System header files declare the interfaces to parts of the operating |
| system. You include them in your program to supply the definitions and |
| declarations you need to invoke system calls and libraries. |
| |
| @item |
| Your own header files contain declarations for interfaces between the |
| source files of your program. Each time you have a group of related |
| declarations and macro definitions all or most of which are needed in |
| several different source files, it is a good idea to create a header |
| file for them. |
| @end itemize |
| |
| Including a header file produces the same results as copying the header |
| file into each source file that needs it. Such copying would be |
| time-consuming and error-prone. With a header file, the related |
| declarations appear in only one place. If they need to be changed, they |
| can be changed in one place, and programs that include the header file |
| will automatically use the new version when next recompiled. The header |
| file eliminates the labor of finding and changing all the copies as well |
| as the risk that a failure to find one copy will result in |
| inconsistencies within a program. |
| |
| In C, the usual convention is to give header files names that end with |
| @file{.h}. It is most portable to use only letters, digits, dashes, and |
| underscores in header file names, and at most one dot. |
| |
| @menu |
| * Include Syntax:: |
| * Include Operation:: |
| * Search Path:: |
| * Once-Only Headers:: |
| * Computed Includes:: |
| * Wrapper Headers:: |
| * System Headers:: |
| @end menu |
| |
| @node Include Syntax |
| @section Include Syntax |
| |
| @findex #include |
| Both user and system header files are included using the preprocessing |
| directive @samp{#include}. It has two variants: |
| |
| @table @code |
| @item #include <@var{file}> |
| This variant is used for system header files. It searches for a file |
| named @var{file} in a standard list of system directories. You can prepend |
| directories to this list with the @option{-I} option (@pxref{Invocation}). |
| |
| @item #include "@var{file}" |
| This variant is used for header files of your own program. It searches |
| for a file named @var{file} first in the directory containing the |
| current file, then in the same directories used for @code{<@var{file}>}. |
| @end table |
| |
| The argument of @samp{#include}, whether delimited with quote marks or |
| angle brackets, behaves like a string constant in that comments are not |
| recognized, and macro names are not expanded. Thus, @code{@w{#include |
| <x/*y>}} specifies inclusion of a system header file named @file{x/*y}. |
| |
| However, if backslashes occur within @var{file}, they are considered |
| ordinary text characters, not escape characters. None of the character |
| escape sequences appropriate to string constants in C are processed. |
| Thus, @code{@w{#include "x\n\\y"}} specifies a filename containing three |
| backslashes. (Some systems interpret @samp{\} as a pathname separator. |
| All of these also interpret @samp{/} the same way. It is most portable |
| to use only @samp{/}.) |
| |
| It is an error if there is anything (other than comments) on the line |
| after the file name. |
| |
| @node Include Operation |
| @section Include Operation |
| |
| The @samp{#include} directive works by directing the C preprocessor to |
| scan the specified file as input before continuing with the rest of the |
| current file. The output from the preprocessor contains the output |
| already generated, followed by the output resulting from the included |
| file, followed by the output that comes from the text after the |
| @samp{#include} directive. For example, if you have a header file |
| @file{header.h} as follows, |
| |
| @example |
| char *test (void); |
| @end example |
| |
| @noindent |
| and a main program called @file{program.c} that uses the header file, |
| like this, |
| |
| @example |
| int x; |
| #include "header.h" |
| |
| int |
| main (void) |
| @{ |
| puts (test ()); |
| @} |
| @end example |
| |
| @noindent |
| the compiler will see the same token stream as it would if |
| @file{program.c} read |
| |
| @example |
| int x; |
| char *test (void); |
| |
| int |
| main (void) |
| @{ |
| puts (test ()); |
| @} |
| @end example |
| |
| 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, |
| a comment or a string or character constant may not start in the |
| included file and finish in the including file. An unterminated |
| comment, string constant or character constant in an included file is |
| considered to end (with an error message) at the end of the file. |
| |
| To avoid confusion, it is best if header files contain only complete |
| syntactic units---function declarations or definitions, type |
| declarations, etc. |
| |
| The line following the @samp{#include} directive is always treated as a |
| separate line by the C preprocessor, even if the included file lacks a |
| final newline. |
| |
| @node Search Path |
| @section Search Path |
| |
| GCC looks in several different places for headers. On a normal Unix |
| system, if you do not instruct it otherwise, it will look for headers |
| requested with @code{@w{#include <@var{file}>}} in: |
| |
| @example |
| /usr/local/include |
| /usr/lib/gcc-lib/@var{target}/@var{version}/include |
| /usr/@var{target}/include |
| /usr/include |
| @end example |
| |
| For C++ programs, it will also look in @file{/usr/include/g++-v3}, |
| first. In the above, @var{target} is the canonical name of the system |
| GCC was configured to compile code for; often but not always the same as |
| the canonical name of the system it runs on. @var{version} is the |
| version of GCC in use. |
| |
| You can add to this list with the @option{-I@var{dir}} command line |
| option. All the directories named by @option{-I} are searched, in |
| left-to-right order, @emph{before} the default directories. You can |
| also prevent GCC from searching any of the default directories with the |
| @option{-nostdinc} option. This is useful when you are compiling an |
| operating system kernel or some other program that does not use the |
| standard C library facilities, or the standard C library itself. |
| |
| GCC looks for headers requested with @code{@w{#include "@var{file}"}} |
| first in the directory containing the current file, then in the same |
| places it would have looked for a header requested with angle brackets. |
| For example, if @file{/usr/include/sys/stat.h} contains |
| @code{@w{#include "types.h"}}, GCC looks for @file{types.h} first in |
| @file{/usr/include/sys}, then in its usual search path. |
| |
| If you name a search directory with @option{-I@var{dir}} that is also a |
| system include directory, the @option{-I} wins; the directory will be |
| searched according to the @option{-I} ordering, and it will not be |
| treated as a system include directory. GCC will warn you when a system |
| include directory is hidden in this way. |
| |
| @samp{#line} (@pxref{Line Control}) does not change GCC's idea of the |
| directory containing the current file. |
| |
| You may put @option{-I-} at any point in your list of @option{-I} options. |
| This has two effects. First, directories appearing before the |
| @option{-I-} in the list are searched only for headers requested with |
| quote marks. Directories after @option{-I-} are searched for all |
| headers. Second, the directory containing the current file is not |
| searched for anything, unless it happens to be one of the directories |
| named by an @option{-I} switch. |
| |
| @option{-I. -I-} is not the same as no @option{-I} options at all, and does |
| not cause the same behavior for @samp{<>} includes that @samp{""} |
| includes get with no special options. @option{-I.} searches the |
| compiler's current working directory for header files. That may or may |
| not be the same as the directory containing the current file. |
| |
| If you need to look for headers in a directory named @file{-}, write |
| @option{-I./-}. |
| |
| There are several more ways to adjust the header search path. They are |
| generally less useful. @xref{Invocation}. |
| |
| @node Once-Only Headers |
| @section Once-Only Headers |
| @cindex repeated inclusion |
| @cindex including just once |
| @cindex wrapper @code{#ifndef} |
| |
| If a header file happens to be included twice, the compiler will process |
| its contents twice. This is very likely to cause an error, e.g.@: when the |
| compiler sees the same structure definition twice. Even if it does not, |
| it will certainly waste time. |
| |
| The standard way to prevent this is to enclose the entire real contents |
| of the file in a conditional, like this: |
| |
| @example |
| @group |
| /* File foo. */ |
| #ifndef FILE_FOO_SEEN |
| #define FILE_FOO_SEEN |
| |
| @var{the entire file} |
| |
| #endif /* !FILE_FOO_SEEN */ |
| @end group |
| @end example |
| |
| This construct is commonly known as a @dfn{wrapper #ifndef}. |
| When the header is included again, the conditional will be false, |
| because @code{FILE_FOO_SEEN} is defined. The preprocessor will skip |
| over the entire contents of the file, and the compiler will not see it |
| twice. |
| |
| GNU CPP optimizes even further. It remembers when a header file has a |
| wrapper @samp{#ifndef}. If a subsequent @samp{#include} specifies that |
| header, and the macro in the @samp{#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. |
| |
| @cindex controlling macro |
| @cindex guard macro |
| The macro @code{FILE_FOO_SEEN} is called the @dfn{controlling macro} or |
| @dfn{guard macro}. In a user header file, the macro name should not |
| begin with @samp{_}. In a system header file, it should begin with |
| @samp{__} 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. |
| |
| @node Computed Includes |
| @section Computed Includes |
| @cindex computed includes |
| @cindex macros in include |
| |
| 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, |
| |
| @example |
| #if SYSTEM_1 |
| # include "system_1.h" |
| #elif SYSTEM_2 |
| # include "system_2.h" |
| #elif SYSTEM_3 |
| @dots{} |
| #endif |
| @end example |
| |
| That rapidly becomes tedious. Instead, the preprocessor offers the |
| ability to use a macro for the header name. This is called a |
| @dfn{computed include}. Instead of writing a header name as the direct |
| argument of @samp{#include}, you simply put a macro name there instead: |
| |
| @example |
| #define SYSTEM_H "system_1.h" |
| @dots{} |
| #include SYSTEM_H |
| @end example |
| |
| @noindent |
| @code{SYSTEM_H} will be expanded, and the preprocessor will look for |
| @file{system_1.h} as if the @samp{#include} had been written that way |
| originally. @code{SYSTEM_H} could be defined by your Makefile with a |
| @option{-D} option. |
| |
| You must be careful when you define the macro. @samp{#define} saves |
| tokens, not text. The preprocessor has no way of knowing that the macro |
| will be used as the argument of @samp{#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 @samp{#include} is |
| not @samp{"} or @samp{<}, 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 |
| |
| @example |
| #define HEADER "a\"b" |
| #include HEADER |
| @end example |
| |
| @noindent |
| looks for a file named @file{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 @samp{<} token |
| and including a @samp{>} token, then the tokens between the @samp{<} and |
| the first @samp{>} 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 @samp{<} is retained, but a trailing space |
| before the closing @samp{>} 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 an error |
| if the result of expansion does not match either of the two expected |
| forms. |
| |
| These rules are implementation-defined behavior according to the C |
| standard. To minimize the risk of different compilers interpreting your |
| computed includes differently, we recommend you use only a single |
| object-like macro which expands to a string constant. This will also |
| minimize confusion for people reading your program. |
| |
| @node Wrapper Headers |
| @section Wrapper Headers |
| @cindex wrapper headers |
| @cindex overriding a header file |
| @findex #include_next |
| |
| Sometimes it is necessary to adjust the contents of a system-provided |
| header file without editing it directly. GCC's @command{fixincludes} |
| operation does this, for example. One way to do that would be to create |
| a new header file with the same name and insert it in the search path |
| before the original header. That works fine as long as you're willing |
| to replace the old header entirely. But what if you want to refer to |
| the old header from the new one? |
| |
| You cannot simply include the old header with @samp{#include}. That |
| will start from the beginning, and find your new header again. If your |
| header is not protected from multiple inclusion (@pxref{Once-Only |
| Headers}), it will recurse infinitely and cause a fatal error. |
| |
| You could include the old header with an absolute pathname: |
| @example |
| #include "/usr/include/old-header.h" |
| @end example |
| @noindent |
| This works, but is not clean; should the system headers ever move, you |
| would have to edit the new headers to match. |
| |
| There is no way to solve this problem within the C standard, but you can |
| use the GNU extension @samp{#include_next}. It means, ``Include the |
| @emph{next} file with this name.'' This directive works like |
| @samp{#include} except in searching for the specified file: it starts |
| searching the list of header file directories @emph{after} the directory |
| in which the current file was found. |
| |
| Suppose you specify @option{-I /usr/local/include}, and the list of |
| directories to search also includes @file{/usr/include}; and suppose |
| both directories contain @file{signal.h}. Ordinary @code{@w{#include |
| <signal.h>}} finds the file under @file{/usr/local/include}. If that |
| file contains @code{@w{#include_next <signal.h>}}, it starts searching |
| after that directory, and finds the file in @file{/usr/include}. |
| |
| @samp{#include_next} does not distinguish between @code{<@var{file}>} |
| and @code{"@var{file}"} inclusion, nor does it check that the file you |
| specify has the same name as the current file. It simply looks for the |
| file named, starting with the directory in the search path after the one |
| where the current file was found. |
| |
| The use of @samp{#include_next} can lead to great confusion. We |
| recommend it be used only when there is no other alternative. In |
| particular, it should not be used in the headers belonging to a specific |
| program; it should be used only to make global corrections along the |
| lines of @command{fixincludes}. |
| |
| @node System Headers |
| @section System Headers |
| @cindex system header files |
| |
| The header files declaring interfaces to the operating system and |
| runtime libraries often cannot be written in strictly conforming C@. |
| Therefore, GCC gives code found in @dfn{system headers} special |
| treatment. All warnings, other than those generated by @samp{#warning} |
| (@pxref{Diagnostics}), are suppressed while GCC is processing a system |
| header. Macros defined in a system header are immune to a few warnings |
| wherever they are expanded. This immunity is granted on an ad-hoc |
| basis, when we find that a warning generates lots of false positives |
| because of code in macros defined in system headers. |
| |
| Normally, only the headers found in specific directories are considered |
| system headers. These directories are determined when GCC is compiled. |
| There are, however, two ways to make normal headers into system headers. |
| |
| The @option{-isystem} command line option adds its argument to the list of |
| directories to search for headers, just like @option{-I}. Any headers |
| found in that directory will be considered system headers. |
| |
| All directories named by @option{-isystem} are searched @emph{after} all |
| directories named by @option{-I}, no matter what their order was on the |
| command line. If the same directory is named by both @option{-I} and |
| @option{-isystem}, @option{-I} wins; it is as if the @option{-isystem} option |
| had never been specified at all. GCC warns you when this happens. |
| |
| @findex #pragma GCC system_header |
| There is also a directive, @code{@w{#pragma GCC system_header}}, which |
| tells GCC to consider the rest of the current include file a system |
| header, no matter where it was found. Code that comes before the |
| @samp{#pragma} in the file will not be affected. @code{@w{#pragma GCC |
| system_header}} has no effect in the primary source file. |
| |
| On very old systems, some of the pre-defined system header directories |
| get even more special treatment. GNU C++ considers code in headers |
| found in those directories to be surrounded by an @code{@w{extern "C"}} |
| block. There is no way to request this behavior with a @samp{#pragma}, |
| or from the command line. |
| |
| @node Macros |
| @chapter Macros |
| |
| A @dfn{macro} is a fragment of code which has been given a name. |
| Whenever the name is used, it is replaced by the contents of the macro. |
| There are two kinds of macros. They differ mostly in what they look |
| like when they are used. @dfn{Object-like} macros resemble data objects |
| when used, @dfn{function-like} macros resemble function calls. |
| |
| You may define any valid identifier as a macro, even if it is a C |
| keyword. The preprocessor does not know anything about keywords. This |
| can be useful if you wish to hide a keyword such as @code{const} from an |
| older compiler that does not understand it. However, the preprocessor |
| operator @code{defined} (@pxref{Defined}) can never be defined as a |
| macro, and C++'s named operators (@pxref{C++ Named Operators}) cannot be |
| macros when you are compiling C++. |
| |
| @menu |
| * Object-like Macros:: |
| * Function-like Macros:: |
| * Macro Arguments:: |
| * Stringification:: |
| * Concatenation:: |
| * Variadic Macros:: |
| * Predefined Macros:: |
| * Undefining and Redefining Macros:: |
| * Directives Within Macro Arguments:: |
| * Macro Pitfalls:: |
| @end menu |
| |
| @node Object-like Macros |
| @section Object-like Macros |
| @cindex object-like macro |
| @cindex symbolic constants |
| @cindex manifest constants |
| |
| An @dfn{object-like macro} is a simple identifier which will be replaced |
| by a code fragment. It is called object-like because it looks like a |
| data object in code that uses it. They are most commonly used to give |
| symbolic names to numeric constants. |
| |
| @findex #define |
| You create macros with the @samp{#define} directive. @samp{#define} is |
| followed by the name of the macro and then the token sequence it should |
| be an abbreviation for, which is variously referred to as the macro's |
| @dfn{body}, @dfn{expansion} or @dfn{replacement list}. For example, |
| |
| @example |
| #define BUFFER_SIZE 1024 |
| @end example |
| |
| @noindent |
| defines a macro named @code{BUFFER_SIZE} as an abbreviation for the |
| token @code{1024}. If somewhere after this @samp{#define} directive |
| there comes a C statement of the form |
| |
| @example |
| foo = (char *) malloc (BUFFER_SIZE); |
| @end example |
| |
| @noindent |
| then the C preprocessor will recognize and @dfn{expand} the macro |
| @code{BUFFER_SIZE}. The C compiler will see the same tokens as it would |
| if you had written |
| |
| @example |
| foo = (char *) malloc (1024); |
| @end example |
| |
| By convention, macro names are written in upper case. Programs are |
| easier to read when it is possible to tell at a glance which names are |
| macros. |
| |
| The macro's body ends at the end of the @samp{#define} line. You may |
| continue the definition onto multiple lines, if necessary, using |
| backslash-newline. When the macro is expanded, however, it will all |
| come out on one line. For example, |
| |
| @example |
| #define NUMBERS 1, \ |
| 2, \ |
| 3 |
| int x[] = @{ NUMBERS @}; |
| @expansion{} int x[] = @{ 1, 2, 3 @}; |
| @end example |
| |
| @noindent |
| The most common visible consequence of this is surprising line numbers |
| in error messages. |
| |
| There is no restriction on what can go in a macro body provided it |
| decomposes into valid preprocessing tokens. Parentheses need not |
| balance, and the body need not resemble valid C code. (If it does not, |
| you may get error messages from the C compiler when you use the macro.) |
| |
| The C preprocessor scans your program sequentially. Macro definitions |
| take effect at the place you write them. Therefore, the following input |
| to the C preprocessor |
| |
| @example |
| foo = X; |
| #define X 4 |
| bar = X; |
| @end example |
| |
| @noindent |
| produces |
| |
| @example |
| foo = X; |
| bar = 4; |
| @end example |
| |
| When the preprocessor expands a macro name, the macro's expansion |
| replaces the macro invocation, then the expansion is examined for more |
| macros to expand. For example, |
| |
| @example |
| @group |
| #define TABLESIZE BUFSIZE |
| #define BUFSIZE 1024 |
| TABLESIZE |
| @expansion{} BUFSIZE |
| @expansion{} 1024 |
| @end group |
| @end example |
| |
| @noindent |
| @code{TABLESIZE} is expanded first to produce @code{BUFSIZE}, then that |
| macro is expanded to produce the final result, @code{1024}. |
| |
| Notice that @code{BUFSIZE} was not defined when @code{TABLESIZE} was |
| defined. The @samp{#define} for @code{TABLESIZE} uses exactly the |
| expansion you specify---in this case, @code{BUFSIZE}---and does not |
| check to see whether it too contains macro names. Only when you |
| @emph{use} @code{TABLESIZE} is the result of its expansion scanned for |
| more macro names. |
| |
| This makes a difference if you change the definition of @code{BUFSIZE} |
| at some point in the source file. @code{TABLESIZE}, defined as shown, |
| will always expand using the definition of @code{BUFSIZE} that is |
| currently in effect: |
| |
| @example |
| #define BUFSIZE 1020 |
| #define TABLESIZE BUFSIZE |
| #undef BUFSIZE |
| #define BUFSIZE 37 |
| @end example |
| |
| @noindent |
| Now @code{TABLESIZE} expands (in two stages) to @code{37}. |
| |
| If the expansion of a macro contains its own name, either directly or |
| via intermediate macros, it is not expanded again when the expansion is |
| examined for more macros. This prevents infinite recursion. |
| @xref{Self-Referential Macros}, for the precise details. |
| |
| @node Function-like Macros |
| @section Function-like Macros |
| @cindex function-like macros |
| |
| You can also define macros whose use looks like a function call. These |
| are called @dfn{function-like macros}. To define a function-like macro, |
| you use the same @samp{#define} directive, but you put a pair of |
| parentheses immediately after the macro name. For example, |
| |
| @example |
| #define lang_init() c_init() |
| lang_init() |
| @expansion{} c_init() |
| @end example |
| |
| A function-like macro is only expanded if its name appears with a pair |
| of parentheses after it. If you write just the name, it is left alone. |
| This can be useful when you have a function and a macro of the same |
| name, and you wish to use the function sometimes. |
| |
| @example |
| extern void foo(void); |
| #define foo() /* optimized inline version */ |
| @dots{} |
| foo(); |
| funcptr = foo; |
| @end example |
| |
| Here the call to @code{foo()} will use the macro, but the function |
| pointer will get the address of the real function. If the macro were to |
| be expanded, it would cause a syntax error. |
| |
| If you put spaces between the macro name and the parentheses in the |
| macro definition, that does not define a function-like macro, it defines |
| an object-like macro whose expansion happens to begin with a pair of |
| parentheses. |
| |
| @example |
| #define lang_init () c_init() |
| lang_init() |
| @expansion{} () c_init()() |
| @end example |
| |
| The first two pairs of parentheses in this expansion come from the |
| macro. The third is the pair that was originally after the macro |
| invocation. Since @code{lang_init} is an object-like macro, it does not |
| consume those parentheses. |
| |
| @node Macro Arguments |
| @section Macro Arguments |
| @cindex arguments |
| @cindex macros with arguments |
| @cindex arguments in macro definitions |
| |
| Function-like macros can take @dfn{arguments}, just like true functions. |
| To define a macro that uses arguments, you insert @dfn{parameters} |
| between the pair of parentheses in the macro definition that make the |
| macro function-like. The parameters must be valid C identifiers, |
| separated by commas and optionally whitespace. |
| |
| To invoke a macro that takes arguments, you write the name of the macro |
| followed by a list of @dfn{actual arguments} in parentheses, separated |
| by commas. The invocation of the macro need not be restricted to a |
| single logical line---it can cross as many lines in the source file as |
| you wish. The number of arguments you give must match the number of |
| parameters in the macro definition. When the macro is expanded, each |
| use of a parameter in its body is replaced by the tokens of the |
| corresponding argument. (You need not use all of the parameters in the |
| macro body.) |
| |
| As an example, here is a macro that computes the minimum of two numeric |
| values, as it is defined in many C programs, and some uses. |
| |
| @example |
| #define min(X, Y) ((X) < (Y) ? (X) : (Y)) |
| x = min(a, b); @expansion{} x = ((a) < (b) ? (a) : (b)); |
| y = min(1, 2); @expansion{} y = ((1) < (2) ? (1) : (2)); |
| z = min(a + 28, *p); @expansion{} z = ((a + 28) < (*p) ? (a + 28) : (*p)); |
| @end example |
| |
| @noindent |
| (In this small example you can already see several of the dangers of |
| macro arguments. @xref{Macro Pitfalls}, for detailed explanations.) |
| |
| Leading and trailing whitespace in each argument is dropped, and all |
| whitespace between the tokens of an argument is reduced to a single |
| space. Parentheses within each argument must balance; a comma within |
| such parentheses does not end the argument. However, there is no |
| requirement for square brackets or braces to balance, and they do not |
| prevent a comma from separating arguments. Thus, |
| |
| @example |
| macro (array[x = y, x + 1]) |
| @end example |
| |
| @noindent |
| passes two arguments to @code{macro}: @code{array[x = y} and @code{x + |
| 1]}. If you want to supply @code{array[x = y, x + 1]} as an argument, |
| you can write it as @code{array[(x = y, x + 1)]}, which is equivalent C |
| code. |
| |
| All arguments to a macro are completely macro-expanded before they are |
| substituted into the macro body. After substitution, the complete text |
| is scanned again for macros to expand, including the arguments. This rule |
| may seem strange, but it is carefully designed so you need not worry |
| about whether any function call is actually a macro invocation. You can |
| run into trouble if you try to be too clever, though. @xref{Argument |
| Prescan}, for detailed discussion. |
| |
| For example, @code{min (min (a, b), c)} is first expanded to |
| |
| @example |
| min (((a) < (b) ? (a) : (b)), (c)) |
| @end example |
| |
| @noindent |
| and then to |
| |
| @example |
| @group |
| ((((a) < (b) ? (a) : (b))) < (c) |
| ? (((a) < (b) ? (a) : (b))) |
| : (c)) |
| @end group |
| @end example |
| |
| @noindent |
| (Line breaks shown here for clarity would not actually be generated.) |
| |
| @cindex empty macro arguments |
| You can leave macro arguments empty; this is not an error to the |
| preprocessor (but many macros will then expand to invalid code). |
| You cannot leave out arguments entirely; if a macro takes two arguments, |
| there must be exactly one comma at the top level of its argument list. |
| Here are some silly examples using @code{min}: |
| |
| @example |
| min(, b) @expansion{} (( ) < (b) ? ( ) : (b)) |
| min(a, ) @expansion{} ((a ) < ( ) ? (a ) : ( )) |
| min(,) @expansion{} (( ) < ( ) ? ( ) : ( )) |
| min((,),) @expansion{} (((,)) < ( ) ? ((,)) : ( )) |
| |
| min() @error{} macro "min" requires 2 arguments, but only 1 given |
| min(,,) @error{} macro "min" passed 3 arguments, but takes just 2 |
| @end example |
| |
| Whitespace is not a preprocessing token, so if a macro @code{foo} takes |
| one argument, @code{@w{foo ()}} and @code{@w{foo ( )}} both supply it an |
| empty argument. Previous GNU preprocessor implementations and |
| documentation were incorrect on this point, insisting that a |
| function-like macro that takes a single argument be passed a space if an |
| empty argument was required. |
| |
| Macro parameters appearing inside string literals are not replaced by |
| their corresponding actual arguments. |
| |
| @example |
| #define foo(x) x, "x" |
| foo(bar) @expansion{} bar, "x" |
| @end example |
| |
| @node Stringification |
| @section Stringification |
| @cindex stringification |
| @cindex @samp{#} operator |
| |
| Sometimes you may want to convert a macro argument into a string |
| constant. Parameters are not replaced inside string constants, but you |
| can use the @samp{#} preprocessing operator instead. When a macro |
| parameter is used with a leading @samp{#}, the preprocessor replaces it |
| with the literal text of the actual argument, converted to a string |
| constant. Unlike normal parameter replacement, the argument is not |
| macro-expanded first. This is called @dfn{stringification}. |
| |
| There is no way to combine an argument with surrounding text and |
| stringify it all together. Instead, you can write a series of adjacent |
| string constants and stringified arguments. The preprocessor will |
| replace the stringified arguments with string constants. The C |
| compiler will then combine all the adjacent string constants into one |
| long string. |
| |
| Here is an example of a macro definition that uses stringification: |
| |
| @example |
| @group |
| #define WARN_IF(EXP) \ |
| do @{ if (EXP) \ |
| fprintf (stderr, "Warning: " #EXP "\n"); @} \ |
| while (0) |
| WARN_IF (x == 0); |
| @expansion{} do @{ if (x == 0) |
| fprintf (stderr, "Warning: " "x == 0" "\n"); @} while (0); |
| @end group |
| @end example |
| |
| @noindent |
| The argument for @code{EXP} is substituted once, as-is, into the |
| @code{if} statement, and once, stringified, into the argument to |
| @code{fprintf}. If @code{x} were a macro, it would be expanded in the |
| @code{if} statement, but not in the string. |
| |
| The @code{do} and @code{while (0)} are a kludge to make it possible to |
| write @code{WARN_IF (@var{arg});}, which the resemblance of |
| @code{WARN_IF} to a function would make C programmers want to do; see |
| @ref{Swallowing the Semicolon}. |
| |
| Stringification in C involves more than putting double-quote characters |
| around the fragment. The preprocessor backslash-escapes the quotes |
| surrounding embedded string constants, and all backslashes within string and |
| character constants, in order to get a valid C string constant with the |
| proper contents. Thus, stringifying @code{@w{p = "foo\n";}} results in |
| @t{@w{"p = \"foo\\n\";"}}. However, backslashes that are not inside string |
| or character constants are not duplicated: @samp{\n} by itself |
| stringifies to @t{"\n"}. |
| |
| All leading and trailing whitespace in text being stringified is |
| ignored. Any sequence of whitespace in the middle of the text is |
| converted to a single space in the stringified result. Comments are |
| replaced by whitespace long before stringification happens, so they |
| never appear in stringified text. |
| |
| There is no way to convert a macro argument into a character constant. |
| |
| If you want to stringify the result of expansion of a macro argument, |
| you have to use two levels of macros. |
| |
| @example |
| #define xstr(s) str(s) |
| #define str(s) #s |
| #define foo 4 |
| str (foo) |
| @expansion{} "foo" |
| xstr (foo) |
| @expansion{} xstr (4) |
| @expansion{} str (4) |
| @expansion{} "4" |
| @end example |
| |
| @code{s} is stringified when it is used in @code{str}, so it is not |
| macro-expanded first. But @code{s} is an ordinary argument to |
| @code{xstr}, so it is completely macro-expanded before @code{xstr} |
| itself is expanded (@pxref{Argument Prescan}). Therefore, by the time |
| @code{str} gets to its argument, it has already been macro-expanded. |
| |
| @node Concatenation |
| @section Concatenation |
| @cindex concatenation |
| @cindex token pasting |
| @cindex token concatenation |
| @cindex @samp{##} operator |
| |
| It is often useful to merge two tokens into one while expanding macros. |
| This is called @dfn{token pasting} or @dfn{token concatenation}. The |
| @samp{##} preprocessing operator performs token pasting. When a macro |
| is expanded, the two tokens on either side of each @samp{##} operator |
| are combined into a single token, which then replaces the @samp{##} and |
| the two original tokens in the macro expansion. Usually both will be |
| identifiers, or one will be an identifier and the other a preprocessing |
| number. When pasted, they make a longer identifier. This isn't the |
| only valid case. It is also possible to concatenate two numbers (or a |
| number and a name, such as @code{1.5} and @code{e3}) into a number. |
| Also, multi-character operators such as @code{+=} can be formed by |
| token pasting. |
| |
| However, two tokens that don't together form a valid token cannot be |
| pasted together. For example, you cannot concatenate @code{x} with |
| @code{+} in either order. If you try, the preprocessor issues a warning |
| and emits the two tokens. Whether it puts white space between the |
| tokens is undefined. It is common to find unnecessary uses of @samp{##} |
| in complex macros. If you get this warning, it is likely that you can |
| simply remove the @samp{##}. |
| |
| Both the tokens combined by @samp{##} could come from the macro body, |
| but you could just as well write them as one token in the first place. |
| Token pasting is most useful when one or both of the tokens comes from a |
| macro argument. If either of the tokens next to an @samp{##} is a |
| parameter name, it is replaced by its actual argument before @samp{##} |
| executes. As with stringification, the actual argument is not |
| macro-expanded first. If the argument is empty, that @samp{##} has no |
| effect. |
| |
| Keep in mind that the C preprocessor converts comments to whitespace |
| before macros are even considered. Therefore, you cannot create a |
| comment by concatenating @samp{/} and @samp{*}. You can put as much |
| whitespace between @samp{##} and its operands as you like, including |
| comments, and you can put comments in arguments that will be |
| concatenated. However, it is an error if @samp{##} appears at either |
| end of a macro body. |
| |
| Consider a C program that interprets named commands. There probably |
| needs to be a table of commands, perhaps an array of structures declared |
| as follows: |
| |
| @example |
| @group |
| struct command |
| @{ |
| char *name; |
| void (*function) (void); |
| @}; |
| @end group |
| |
| @group |
| struct command commands[] = |
| @{ |
| @{ "quit", quit_command @}, |
| @{ "help", help_command @}, |
| @dots{} |
| @}; |
| @end group |
| @end example |
| |
| It would be cleaner not to have to give each command name twice, once in |
| the string constant and once in the function name. A macro which takes the |
| name of a command as an argument can make this unnecessary. The string |
| constant can be created with stringification, and the function name by |
| concatenating the argument with @samp{_command}. Here is how it is done: |
| |
| @example |
| #define COMMAND(NAME) @{ #NAME, NAME ## _command @} |
| |
| struct command commands[] = |
| @{ |
| COMMAND (quit), |
| COMMAND (help), |
| @dots{} |
| @}; |
| @end example |
| |
| @node Variadic Macros |
| @section Variadic Macros |
| @cindex variable number of arguments |
| @cindex macros with variable arguments |
| @cindex variadic macros |
| |
| A macro can be declared to accept a variable number of arguments much as |
| a function can. The syntax for defining the macro is similar to that of |
| a function. Here is an example: |
| |
| @example |
| #define eprintf(@dots{}) fprintf (stderr, __VA_ARGS__) |
| @end example |
| |
| This kind of macro is called @dfn{variadic}. When the macro is invoked, |
| all the tokens in its argument list after the last named argument (this |
| macro has none), including any commas, become the @dfn{variable |
| argument}. This sequence of tokens replaces the identifier |
| @code{@w{__VA_ARGS__}} in the macro body wherever it appears. Thus, we |
| have this expansion: |
| |
| @example |
| eprintf ("%s:%d: ", input_file, lineno) |
| @expansion{} fprintf (stderr, "%s:%d: ", input_file, lineno) |
| @end example |
| |
| The variable argument is completely macro-expanded before it is inserted |
| into the macro expansion, just like an ordinary argument. You may use |
| the @samp{#} and @samp{##} operators to stringify the variable argument |
| or to paste its leading or trailing token with another token. (But see |
| below for an important special case for @samp{##}.) |
| |
| If your macro is complicated, you may want a more descriptive name for |
| the variable argument than @code{@w{__VA_ARGS__}}. GNU CPP permits |
| this, as an extension. You may write an argument name immediately |
| before the @samp{@dots{}}; that name is used for the variable argument. |
| The @code{eprintf} macro above could be written |
| |
| @example |
| #define eprintf(args@dots{}) fprintf (stderr, args) |
| @end example |
| |
| @noindent |
| using this extension. You cannot use @code{__VA_ARGS__} and this |
| extension in the same macro. |
| |
| You can have named arguments as well as variable arguments in a variadic |
| macro. We could define @code{eprintf} like this, instead: |
| |
| @example |
| #define eprintf(format, @dots{}) fprintf (stderr, format, __VA_ARGS__) |
| @end example |
| |
| @noindent |
| This formulation looks more descriptive, but unfortunately it is less |
| flexible: you must now supply at least one argument after the format |
| string. In standard C, you cannot omit the comma separating the named |
| argument from the variable arguments. Furthermore, if you leave the |
| variable argument empty, you will get a syntax error, because |
| there will be an extra comma after the format string. |
| |
| @example |
| eprintf("success!\n", ); |
| @expansion{} fprintf(stderr, "success!\n", ); |
| @end example |
| |
| GNU CPP has a pair of extensions which deal with this problem. First, |
| you are allowed to leave the variable argument out entirely: |
| |
| @example |
| eprintf ("success!\n") |
| @expansion{} fprintf(stderr, "success!\n", ); |
| @end example |
| |
| @noindent |
| Second, the @samp{##} token paste operator has a special meaning when |
| placed between a comma and a variable argument. If you write |
| |
| @example |
| #define eprintf(format, @dots{}) fprintf (stderr, format, ##__VA_ARGS__) |
| @end example |
| |
| @noindent |
| and the variable argument is left out when the @code{eprintf} macro is |
| used, then the comma before the @samp{##} will be deleted. This does |
| @emph{not} happen if you pass an empty argument, nor does it happen if |
| the token preceding @samp{##} is anything other than a comma. |
| |
| @example |
| eprintf ("success!\n") |
| @expansion{} fprintf(stderr, "success!\n"); |
| @end example |
| |
| C99 mandates that the only place the identifier @code{@w{__VA_ARGS__}} |
| can appear is in the replacement list of a variadic macro. It may not |
| be used as a macro name, macro argument name, or within a different type |
| of macro. It may also be forbidden in open text; the standard is |
| ambiguous. We recommend you avoid using it except for its defined |
| purpose. |
| |
| Variadic macros are a new feature in C99. GNU CPP has supported them |
| for a long time, but only with a named variable argument |
| (@samp{args@dots{}}, not @samp{@dots{}} and @code{@w{__VA_ARGS__}}). If you are |
| concerned with portability to previous versions of GCC, you should use |
| only named variable arguments. On the other hand, if you are concerned |
| with portability to other conforming implementations of C99, you should |
| use only @code{@w{__VA_ARGS__}}. |
| |
| Previous versions of GNU CPP implemented the comma-deletion extension |
| much more generally. We have restricted it in this release to minimize |
| the differences from C99. To get the same effect with both this and |
| previous versions of GCC, the token preceding the special @samp{##} must |
| be a comma, and there must be white space between that comma and |
| whatever comes immediately before it: |
| |
| @example |
| #define eprintf(format, args@dots{}) fprintf (stderr, format , ##args) |
| @end example |
| |
| @noindent |
| @xref{Differences from previous versions}, for the gory details. |
| |
| @node Predefined Macros |
| @section Predefined Macros |
| |
| @cindex predefined macros |
| Several object-like macros are predefined; you use them without |
| supplying their definitions. They fall into three classes: standard, |
| common, and system-specific. |
| |
| In C++, there is a fourth category, the named operators. They act like |
| predefined macros, but you cannot undefine them. |
| |
| @menu |
| * Standard Predefined Macros:: |
| * Common Predefined Macros:: |
| * System-specific Predefined Macros:: |
| * C++ Named Operators:: |
| @end menu |
| |
| @node Standard Predefined Macros |
| @subsection Standard Predefined Macros |
| @cindex standard predefined macros. |
| |
| The standard predefined macros are specified by the C and/or C++ |
| language standards, so they are available with all compilers that |
| implement those standards. Older compilers may not provide all of |
| them. Their names all start with double underscores. |
| |
| @table @code |
| @item __FILE__ |
| This macro expands to the name of the current input file, in the form of |
| a C string constant. This is the path by which the preprocessor opened |
| the file, not the short name specified in @samp{#include} or as the |
| input file name argument. For example, |
| @code{"/usr/local/include/myheader.h"} is a possible expansion of this |
| macro. |
| |
| @item __LINE__ |
| This macro expands to the current input line number, in the form of a |
| decimal integer constant. While we call it a predefined macro, it's |
| a pretty strange macro, since its ``definition'' changes with each |
| new line of source code. |
| @end table |
| |
| @code{__FILE__} and @code{__LINE__} are useful in generating an error |
| message to report an inconsistency detected by the program; the message |
| can state the source line at which the inconsistency was detected. For |
| example, |
| |
| @example |
| fprintf (stderr, "Internal error: " |
| "negative string length " |
| "%d at %s, line %d.", |
| length, __FILE__, __LINE__); |
| @end example |
| |
| An @samp{#include} directive changes the expansions of @code{__FILE__} |
| and @code{__LINE__} to correspond to the included file. At the end of |
| that file, when processing resumes on the input file that contained |
| the @samp{#include} directive, the expansions of @code{__FILE__} and |
| @code{__LINE__} revert to the values they had before the |
| @samp{#include} (but @code{__LINE__} is then incremented by one as |
| processing moves to the line after the @samp{#include}). |
| |
| A @samp{#line} directive changes @code{__LINE__}, and may change |
| @code{__FILE__} as well. @xref{Line Control}. |
| |
| C99 introduces @code{__func__}, and GCC has provided @code{__FUNCTION__} |
| for a long time. Both of these are strings containing the name of the |
| current function (there are slight semantic differences; see the GCC |
| manual). Neither of them is a macro; the preprocessor does not know the |
| name of the current function. They tend to be useful in conjunction |
| with @code{__FILE__} and @code{__LINE__}, though. |
| |
| @table @code |
| |
| @item __DATE__ |
| This macro expands to a string constant that describes the date on which |
| the preprocessor is being run. The string constant contains eleven |
| characters and looks like @code{@w{"Feb 12 1996"}}. If the day of the |
| month is less than 10, it is padded with a space on the left. |
| |
| @item __TIME__ |
| This macro expands to a string constant that describes the time at |
| which the preprocessor is being run. The string constant contains |
| eight characters and looks like @code{"23:59:01"}. |
| |
| @item __STDC__ |
| In normal operation, this macro expands to the constant 1, to signify |
| that this compiler conforms to ISO Standard C@. If GNU CPP is used with |
| a compiler other than GCC, this is not necessarily true; however, the |
| preprocessor always conforms to the standard, unless the |
| @option{-traditional} option is used. |
| |
| This macro is not defined if the @option{-traditional} option is used. |
| |
| On some hosts, the system compiler uses a different convention, where |
| @code{__STDC__} is normally 0, but is 1 if the user specifies strict |
| conformance to the C Standard. GNU CPP follows the host convention when |
| processing system header files, but when processing user files |
| @code{__STDC__} is always 1. This has been reported to cause problems; |
| for instance, some versions of Solaris provide X Windows headers that |
| expect @code{__STDC__} to be either undefined or 1. You may be able to |
| work around this sort of problem by using an @option{-I} option to |
| cancel treatment of those headers as system headers. @xref{Invocation}. |
| |
| @item __STDC_VERSION__ |
| This macro expands to the C Standard's version number, a long integer |
| constant of the form @code{@var{yyyy}@var{mm}L} where @var{yyyy} and |
| @var{mm} are the year and month of the Standard version. This signifies |
| which version of the C Standard the compiler conforms to. Like |
| @code{__STDC__}, this is not necessarily accurate for the entire |
| implementation, unless GNU CPP is being used with GCC@. |
| |
| The value @code{199409L} signifies the 1989 C standard as amended in |
| 1994, which is the current default; the value @code{199901L} signifies |
| the 1999 revision of the C standard. Support for the 1999 revision is |
| not yet complete. |
| |
| This macro is not defined if the @option{-traditional} option is used, nor |
| when compiling C++ or Objective-C@. |
| |
| @item __STDC_HOSTED__ |
| This macro is defined, with value 1, if the compiler's target is a |
| @dfn{hosted environment}. A hosted environment has the complete |
| facilities of the standard C library available. |
| |
| @item __cplusplus |
| This macro is defined when the C++ compiler is in use. You can use |
| @code{__cplusplus} to test whether a header is compiled by a C compiler |
| or a C++ compiler. This macro is similar to @code{__STDC_VERSION__}, in |
| that it expands to a version number. A fully conforming implementation |
| of the 1998 C++ standard will define this macro to @code{199711L}. The |
| GNU C++ compiler is not yet fully conforming, so it uses @code{1} |
| instead. We hope to complete our implementation in the near future. |
| |
| @end table |
| |
| @node Common Predefined Macros |
| @subsection Common Predefined Macros |
| @cindex common predefined macros |
| |
| The common predefined macros are GNU C extensions. They are available |
| with the same meanings regardless of the machine or operating system on |
| which you are using GNU C@. Their names all start with double |
| underscores. |
| |
| @table @code |
| |
| @item __GNUC__ |
| @itemx __GNUC_MINOR__ |
| @itemx __GNUC_PATCHLEVEL__ |
| These macros are defined by all GNU compilers that use the C |
| preprocessor: C, C++, and Objective-C@. Their values are the major |
| version, minor version, and patch level of the compiler, as integer |
| constants. For example, GCC 3.2.1 will define @code{__GNUC__} to 3, |
| @code{__GNUC_MINOR__} to 2, and @code{__GNUC_PATCHLEVEL__} to 1. They |
| are defined only when the entire compiler is in use; if you invoke the |
| preprocessor directly, they are not defined. |
| |
| @code{__GNUC_PATCHLEVEL__} is new to GCC 3.0; it is also present in the |
| widely-used development snapshots leading up to 3.0 (which identify |
| themselves as GCC 2.96 or 2.97, depending on which snapshot you have). |
| |
| If all you need to know is whether or not your program is being compiled |
| by GCC, you can simply test @code{__GNUC__}. If you need to write code |
| which depends on a specific version, you must be more careful. Each |
| time the minor version is increased, the patch level is reset to zero; |
| each time the major version is increased (which happens rarely), the |
| minor version and patch level are reset. If you wish to use the |
| predefined macros directly in the conditional, you will need to write it |
| like this: |
| |
| @example |
| /* @r{Test for GCC > 3.2.0} */ |
| #if __GNUC__ > 3 || \ |
| (__GNUC__ == 3 && (__GNUC_MINOR__ > 2 || \ |
| (__GNUC_MINOR__ == 2 && \ |
| __GNUC_PATCHLEVEL__ > 0)) |
| @end example |
| |
| @noindent |
| Another approach is to use the predefined macros to |
| calculate a single number, then compare that against a threshold: |
| |
| @example |
| #define GCC_VERSION (__GNUC__ * 10000 \ |
| + __GNUC_MINOR__ * 100 \ |
| + __GNUC_PATCHLEVEL__) |
| @dots{} |
| /* @r{Test for GCC > 3.2.0} */ |
| #if GCC_VERSION > 30200 |
| @end example |
| |
| @noindent |
| Many people find this form easier to understand. |
| |
| @item __OBJC__ |
| This macro is defined, with value 1, when the Objective-C compiler is in |
| use. You can use @code{__OBJC__} to test whether a header is compiled |
| by a C compiler or a Objective-C compiler. |
| |
| @item __GNUG__ |
| The GNU C++ compiler defines this. Testing it is equivalent to |
| testing @code{@w{(__GNUC__ && __cplusplus)}}. |
| |
| @item __STRICT_ANSI__ |
| GCC defines this macro if and only if the @option{-ansi} switch, or a |
| @option{-std} switch specifying strict conformance to some version of ISO C, |
| was specified when GCC was invoked. It is defined to @samp{1}. |
| This macro exists primarily to direct GNU libc's header files to |
| restrict their definitions to the minimal set found in the 1989 C |
| standard. |
| |
| @item __BASE_FILE__ |
| This macro expands to the name of the main input file, in the form |
| of a C string constant. This is the source file that was specified |
| on the command line of the preprocessor or C compiler. |
| |
| @item __INCLUDE_LEVEL__ |
| This macro expands to a decimal integer constant that represents the |
| depth of nesting in include files. The value of this macro is |
| incremented on every @samp{#include} directive and decremented at the |
| end of every included file. It starts out at 0, it's value within the |
| base file specified on the command line. |
| |
| @item __VERSION__ |
| This macro expands to a string constant which describes the version of |
| the compiler in use. You should not rely on its contents having any |
| particular form, but it can be counted on to contain at least the |
| release number. |
| |
| @item __OPTIMIZE__ |
| @itemx __OPTIMIZE_SIZE__ |
| @itemx __NO_INLINE__ |
| These macros describe the compilation mode. @code{__OPTIMIZE__} is |
| defined in all optimizing compilations. @code{__OPTIMIZE_SIZE__} is |
| defined if the compiler is optimizing for size, not speed. |
| @code{__NO_INLINE__} is defined if no functions will be inlined into |
| their callers (when not optimizing, or when inlining has been |
| specifically disabled by @option{-fno-inline}). |
| |
| These macros cause certain GNU header files to provide optimized |
| definitions, using macros or inline functions, of system library |
| functions. You should not use these macros in any way unless you make |
| sure that programs will execute with the same effect whether or not they |
| are defined. If they are defined, their value is 1. |
| |
| @item __CHAR_UNSIGNED__ |
| GCC defines this macro if and only if the data type @code{char} is |
| unsigned on the target machine. It exists to cause the standard header |
| file @file{limits.h} to work correctly. You should not use this macro |
| yourself; instead, refer to the standard macros defined in @file{limits.h}. |
| |
| @item __REGISTER_PREFIX__ |
| This macro expands to a single token (not a string constant) which is |
| the prefix applied to CPU register names in assembly language for this |
| target. You can use it to write assembly that is usable in multiple |
| environments. For example, in the @code{m68k-aout} environment it |
| expands to nothing, but in the @code{m68k-coff} environment it expands |
| to a single @samp{%}. |
| |
| @item __USER_LABEL_PREFIX__ |
| This macro expands to a single token which is the prefix applied to |
| user labels (symbols visible to C code) in assembly. For example, in |
| the @code{m68k-aout} environment it expands to an @samp{_}, but in the |
| @code{m68k-coff} environment it expands to nothing. |
| |
| This macro will have the correct definition even if |
| @option{-f(no-)underscores} is in use, but it will not be correct if |
| target-specific options that adjust this prefix are used (e.g.@: the |
| OSF/rose @option{-mno-underscores} option). |
| |
| @item __SIZE_TYPE__ |
| @itemx __PTRDIFF_TYPE__ |
| @itemx __WCHAR_TYPE__ |
| @itemx __WINT_TYPE__ |
| These macros are defined to the correct underlying types for the |
| @code{size_t}, @code{ptrdiff_t}, @code{wchar_t}, and @code{wint_t} |
| typedefs, respectively. They exist to make the standard header files |
| @file{stddef.h} and @file{wchar.h} work correctly. You should not use |
| these macros directly; instead, include the appropriate headers and use |
| the typedefs. |
| |
| @item __USING_SJLJ_EXCEPTIONS__ |
| This macro is defined, with value 1, if the compiler uses the old |
| mechanism based on @code{setjmp} and @code{longjmp} for exception |
| handling. |
| @end table |
| |
| @node System-specific Predefined Macros |
| @subsection System-specific Predefined Macros |
| |
| @cindex system-specific predefined macros |
| @cindex predefined macros, system-specific |
| @cindex reserved namespace |
| |
| The C preprocessor normally predefines several macros that indicate what |
| type of system and machine is in use. They are obviously different on |
| each target supported by GCC@. This manual, being for all systems and |
| machines, cannot tell you what their names are, but you can use |
| @command{cpp -dM} to see them all. @xref{Invocation}. All system-specific |
| predefined macros expand to the constant 1, so you can test them with |
| either @samp{#ifdef} or @samp{#if}. |
| |
| The C standard requires that all system-specific macros be part of the |
| @dfn{reserved namespace}. All names which begin with two underscores, |
| or an underscore and a capital letter, are reserved for the compiler and |
| library to use as they wish. However, historically system-specific |
| macros have had names with no special prefix; for instance, it is common |
| to find @code{unix} defined on Unix systems. For all such macros, GCC |
| provides a parallel macro with two underscores added at the beginning |
| and the end. If @code{unix} is defined, @code{__unix__} will be defined |
| too. There will never be more than two underscores; the parallel of |
| @code{_mips} is @code{__mips__}. |
| |
| When the @option{-ansi} option, or any @option{-std} option that |
| requests strict conformance, is given to the compiler, all the |
| system-specific predefined macros outside the reserved namespace are |
| suppressed. The parallel macros, inside the reserved namespace, remain |
| defined. |
| |
| We are slowly phasing out all predefined macros which are outside the |
| reserved namespace. You should never use them in new programs, and we |
| encourage you to correct older code to use the parallel macros whenever |
| you find it. We don't recommend you use the system-specific macros that |
| are in the reserved namespace, either. It is better in the long run to |
| check specifically for features you need, using a tool such as |
| @command{autoconf}. |
| |
| @node C++ Named Operators |
| @subsection C++ Named Operators |
| @cindex named operators |
| @cindex C++ named operators |
| @cindex iso646.h |
| |
| In C++, there are eleven keywords which are simply alternate spellings |
| of operators normally written with punctuation. These keywords are |
| treated as such even in the preprocessor. They function as operators in |
| @samp{#if}, and they cannot be defined as macros or poisoned. In C, you |
| can request that those keywords take their C++ meaning by including |
| @file{iso646.h}. That header defines each one as a normal object-like |
| macro expanding to the appropriate punctuator. |
| |
| These are the named operators and their corresponding punctuators: |
| |
| @multitable {Named Operator} {Punctuator} |
| @item Named Operator @tab Punctuator |
| @item @code{and} @tab @code{&&} |
| @item @code{and_eq} @tab @code{&=} |
| @item @code{bitand} @tab @code{&} |
| @item @code{bitor} @tab @code{|} |
| @item @code{compl} @tab @code{~} |
| @item @code{not} @tab @code{!} |
| @item @code{not_eq} @tab @code{!=} |
| @item @code{or} @tab @code{||} |
| @item @code{or_eq} @tab @code{|=} |
| @item @code{xor} @tab @code{^} |
| @item @code{xor_eq} @tab @code{^=} |
| @end multitable |
| |
| @node Undefining and Redefining Macros |
| @section Undefining and Redefining Macros |
| @cindex undefining macros |
| @cindex redefining macros |
| @findex #undef |
| |
| If a macro ceases to be useful, it may be @dfn{undefined} with the |
| @samp{#undef} directive. @samp{#undef} takes a single argument, the |
| name of the macro to undefine. You use the bare macro name, even if the |
| macro is function-like. It is an error if anything appears on the line |
| after the macro name. @samp{#undef} has no effect if the name is not a |
| macro. |
| |
| @example |
| #define FOO 4 |
| x = FOO; @expansion{} x = 4; |
| #undef FOO |
| x = FOO; @expansion{} x = FOO; |
| @end example |
| |
| Once a macro has been undefined, that identifier may be @dfn{redefined} |
| as a macro by a subsequent @samp{#define} directive. The new definition |
| need not have any resemblance to the old definition. |
| |
| However, if an identifier which is currently a macro is redefined, then |
| the new definition must be @dfn{effectively the same} as the old one. |
| Two macro definitions are effectively the same if: |
| @itemize @bullet |
| @item Both are the same type of macro (object- or function-like). |
| @item All the tokens of the replacement list are the same. |
| @item If there are any parameters, they are the same. |
| @item Whitespace appears in the same places in both. It need not be |
| exactly the same amount of whitespace, though. Remember that comments |
| count as whitespace. |
| @end itemize |
| |
| @noindent |
| These definitions are effectively the same: |
| @example |
| #define FOUR (2 + 2) |
| #define FOUR (2 + 2) |
| #define FOUR (2 /* two */ + 2) |
| @end example |
| @noindent |
| but these are not: |
| @example |
| #define FOUR (2 + 2) |
| #define FOUR ( 2+2 ) |
| #define FOUR (2 * 2) |
| #define FOUR(score,and,seven,years,ago) (2 + 2) |
| @end example |
| |
| If a macro is redefined with a definition that is not effectively the |
| same as the old one, the preprocessor issues a warning and changes the |
| macro to use the new definition. If the new definition is effectively |
| the same, the redefinition is silently ignored. This allows, for |
| instance, two different headers to define a common macro. The |
| preprocessor will only complain if the definitions do not match. |
| |
| @node Directives Within Macro Arguments |
| @section Directives Within Macro Arguments |
| @cindex macro arguments and directives |
| |
| Occasionally it is convenient to use preprocessor directives within |
| the arguments of a macro. The C and C++ standards declare that |
| behavior in these cases is undefined. |
| |
| Versions of GNU CPP prior to 3.2 would reject such constructs with an |
| error message. This was the only syntactic difference between normal |
| functions and function-like macros, so it seemed attractive to remove |
| this limitation, and people would often be surprised that they could |
| not use macros in this way. Moreover, sometimes people would use |
| conditional compilation in the argument list to a normal library |
| function like @samp{printf}, only to find that after a library upgrade |
| @samp{printf} had changed to be a function-like macro, and their code |
| would no longer compile. So from version 3.2 we changed CPP to |
| successfully process arbitrary directives within macro arguments in |
| exactly the same way as it would have processed the directive were the |
| function-like macro invocation not present. |
| |
| If, within a macro invocation, that macro is redefined, then the new |
| definition takes effect in time for argument pre-expansion, but the |
| original definition is still used for argument replacement. Here is a |
| pathological example: |
| |
| @smallexample |
| #define f(x) x x |
| f (1 |
| #undef f |
| #define f 2 |
| f) |
| @end smallexample |
| |
| @noindent which expands to |
| |
| @smallexample |
| 1 2 1 2 |
| @end smallexample |
| |
| @noindent with the semantics described above. |
| |
| @node Macro Pitfalls |
| @section Macro Pitfalls |
| @cindex problems with macros |
| @cindex pitfalls of macros |
| |
| In this section we describe some special rules that apply to macros and |
| macro expansion, and point out certain cases in which the rules have |
| counter-intuitive consequences that you must watch out for. |
| |
| @menu |
| * Misnesting:: |
| * Operator Precedence Problems:: |
| * Swallowing the Semicolon:: |
| * Duplication of Side Effects:: |
| * Self-Referential Macros:: |
| * Argument Prescan:: |
| * Newlines in Arguments:: |
| @end menu |
| |
| @node Misnesting |
| @subsection Misnesting |
| |
| When a macro is called with arguments, the arguments are substituted |
| into the macro body and the result is checked, together with the rest of |
| the input file, for more macro calls. It is possible to piece together |
| a macro call coming partially from the macro body and partially from the |
| arguments. For example, |
| |
| @example |
| #define twice(x) (2*(x)) |
| #define call_with_1(x) x(1) |
| call_with_1 (twice) |
| @expansion{} twice(1) |
| @expansion{} (2*(1)) |
| @end example |
| |
| Macro definitions do not have to have balanced parentheses. By writing |
| an unbalanced open parenthesis in a macro body, it is possible to create |
| a macro call that begins inside the macro body but ends outside of it. |
| For example, |
| |
| @example |
| #define strange(file) fprintf (file, "%s %d", |
| @dots{} |
| strange(stderr) p, 35) |
| @expansion{} fprintf (stderr, "%s %d", p, 35) |
| @end example |
| |
| The ability to piece together a macro call can be useful, but the use of |
| unbalanced open parentheses in a macro body is just confusing, and |
| should be avoided. |
| |
| @node Operator Precedence Problems |
| @subsection Operator Precedence Problems |
| @cindex parentheses in macro bodies |
| |
| You may have noticed that in most of the macro definition examples shown |
| above, each occurrence of a macro argument name had parentheses around |
| it. In addition, another pair of parentheses usually surround the |
| entire macro definition. Here is why it is best to write macros that |
| way. |
| |
| Suppose you define a macro as follows, |
| |
| @example |
| #define ceil_div(x, y) (x + y - 1) / y |
| @end example |
| |
| @noindent |
| whose purpose is to divide, rounding up. (One use for this operation is |
| to compute how many @code{int} objects are needed to hold a certain |
| number of @code{char} objects.) Then suppose it is used as follows: |
| |
| @example |
| a = ceil_div (b & c, sizeof (int)); |
| @expansion{} a = (b & c + sizeof (int) - 1) / sizeof (int); |
| @end example |
| |
| @noindent |
| This does not do what is intended. The operator-precedence rules of |
| C make it equivalent to this: |
| |
| @example |
| a = (b & (c + sizeof (int) - 1)) / sizeof (int); |
| @end example |
| |
| @noindent |
| What we want is this: |
| |
| @example |
| a = ((b & c) + sizeof (int) - 1)) / sizeof (int); |
| @end example |
| |
| @noindent |
| Defining the macro as |
| |
| @example |
| #define ceil_div(x, y) ((x) + (y) - 1) / (y) |
| @end example |
| |
| @noindent |
| provides the desired result. |
| |
| Unintended grouping can result in another way. Consider @code{sizeof |
| ceil_div(1, 2)}. That has the appearance of a C expression that would |
| compute the size of the type of @code{ceil_div (1, 2)}, but in fact it |
| means something very different. Here is what it expands to: |
| |
| @example |
| sizeof ((1) + (2) - 1) / (2) |
| @end example |
| |
| @noindent |
| This would take the size of an integer and divide it by two. The |
| precedence rules have put the division outside the @code{sizeof} when it |
| was intended to be inside. |
| |
| Parentheses around the entire macro definition prevent such problems. |
| Here, then, is the recommended way to define @code{ceil_div}: |
| |
| @example |
| #define ceil_div(x, y) (((x) + (y) - 1) / (y)) |
| @end example |
| |
| @node Swallowing the Semicolon |
| @subsection Swallowing the Semicolon |
| @cindex semicolons (after macro calls) |
| |
| Often it is desirable to define a macro that expands into a compound |
| statement. Consider, for example, the following macro, that advances a |
| pointer (the argument @code{p} says where to find it) across whitespace |
| characters: |
| |
| @example |
| #define SKIP_SPACES(p, limit) \ |
| @{ char *lim = (limit); \ |
| while (p < lim) @{ \ |
| if (*p++ != ' ') @{ \ |
| p--; break; @}@}@} |
| @end example |
| |
| @noindent |
| Here backslash-newline is used to split the macro definition, which must |
| be a single logical line, so that it resembles the way such code would |
| be laid out if not part of a macro definition. |
| |
| A call to this macro might be @code{SKIP_SPACES (p, lim)}. Strictly |
| speaking, the call expands to a compound statement, which is a complete |
| statement with no need for a semicolon to end it. However, since it |
| looks like a function call, it minimizes confusion if you can use it |
| like a function call, writing a semicolon afterward, as in |
| @code{SKIP_SPACES (p, lim);} |
| |
| This can cause trouble before @code{else} statements, because the |
| semicolon is actually a null statement. Suppose you write |
| |
| @example |
| if (*p != 0) |
| SKIP_SPACES (p, lim); |
| else @dots{} |
| @end example |
| |
| @noindent |
| The presence of two statements---the compound statement and a null |
| statement---in between the @code{if} condition and the @code{else} |
| makes invalid C code. |
| |
| The definition of the macro @code{SKIP_SPACES} can be altered to solve |
| this problem, using a @code{do @dots{} while} statement. Here is how: |
| |
| @example |
| #define SKIP_SPACES(p, limit) \ |
| do @{ char *lim = (limit); \ |
| while (p < lim) @{ \ |
| if (*p++ != ' ') @{ \ |
| p--; break; @}@}@} \ |
| while (0) |
| @end example |
| |
| Now @code{SKIP_SPACES (p, lim);} expands into |
| |
| @example |
| do @{@dots{}@} while (0); |
| @end example |
| |
| @noindent |
| which is one statement. The loop executes exactly once; most compilers |
| generate no extra code for it. |
| |
| @node Duplication of Side Effects |
| @subsection Duplication of Side Effects |
| |
| @cindex side effects (in macro arguments) |
| @cindex unsafe macros |
| Many C programs define a macro @code{min}, for ``minimum'', like this: |
| |
| @example |
| #define min(X, Y) ((X) < (Y) ? (X) : (Y)) |
| @end example |
| |
| When you use this macro with an argument containing a side effect, |
| as shown here, |
| |
| @example |
| next = min (x + y, foo (z)); |
| @end example |
| |
| @noindent |
| it expands as follows: |
| |
| @example |
| next = ((x + y) < (foo (z)) ? (x + y) : (foo (z))); |
| @end example |
| |
| @noindent |
| where @code{x + y} has been substituted for @code{X} and @code{foo (z)} |
| for @code{Y}. |
| |
| The function @code{foo} is used only once in the statement as it appears |
| in the program, but the expression @code{foo (z)} has been substituted |
| twice into the macro expansion. As a result, @code{foo} might be called |
| two times when the statement is executed. If it has side effects or if |
| it takes a long time to compute, the results might not be what you |
| intended. We say that @code{min} is an @dfn{unsafe} macro. |
| |
| The best solution to this problem is to define @code{min} in a way that |
| computes the value of @code{foo (z)} only once. The C language offers |
| no standard way to do this, but it can be done with GNU extensions as |
| follows: |
| |
| @example |
| #define min(X, Y) \ |
| (@{ typeof (X) x_ = (X); \ |
| typeof (Y) y_ = (Y); \ |
| (x_ < y_) ? x_ : y_; @}) |
| @end example |
| |
| The @samp{(@{ @dots{} @})} notation produces a compound statement that |
| acts as an expression. Its value is the value of its last statement. |
| This permits us to define local variables and assign each argument to |
| one. The local variables have underscores after their names to reduce |
| the risk of conflict with an identifier of wider scope (it is impossible |
| to avoid this entirely). Now each argument is evaluated exactly once. |
| |
| If you do not wish to use GNU C extensions, the only solution is to be |
| careful when @emph{using} the macro @code{min}. For example, you can |
| calculate the value of @code{foo (z)}, save it in a variable, and use |
| that variable in @code{min}: |
| |
| @example |
| @group |
| #define min(X, Y) ((X) < (Y) ? (X) : (Y)) |
| @dots{} |
| @{ |
| int tem = foo (z); |
| next = min (x + y, tem); |
| @} |
| @end group |
| @end example |
| |
| @noindent |
| (where we assume that @code{foo} returns type @code{int}). |
| |
| @node Self-Referential Macros |
| @subsection Self-Referential Macros |
| @cindex self-reference |
| |
| A @dfn{self-referential} macro is one whose name appears in its |
| definition. Recall that all macro definitions are rescanned for more |
| macros to replace. If the self-reference were considered a use of the |
| macro, it would produce an infinitely large expansion. To prevent this, |
| the self-reference is not considered a macro call. It is passed into |
| the preprocessor output unchanged. Let's consider an example: |
| |
| @example |
| #define foo (4 + foo) |
| @end example |
| |
| @noindent |
| where @code{foo} is also a variable in your program. |
| |
| Following the ordinary rules, each reference to @code{foo} will expand |
| into @code{(4 + foo)}; then this will be rescanned and will expand into |
| @code{(4 + (4 + foo))}; and so on until the computer runs out of memory. |
| |
| The self-reference rule cuts this process short after one step, at |
| @code{(4 + foo)}. Therefore, this macro definition has the possibly |
| useful effect of causing the program to add 4 to the value of @code{foo} |
| wherever @code{foo} is referred to. |
| |
| In most cases, it is a bad idea to take advantage of this feature. A |
| person reading the program who sees that @code{foo} is a variable will |
| not expect that it is a macro as well. The reader will come across the |
| identifier @code{foo} in the program and think its value should be that |
| of the variable @code{foo}, whereas in fact the value is four greater. |
| |
| One common, useful use of self-reference is to create a macro which |
| expands to itself. If you write |
| |
| @example |
| #define EPERM EPERM |
| @end example |
| |
| @noindent |
| then the macro @code{EPERM} expands to @code{EPERM}. Effectively, it is |
| left alone by the preprocessor whenever it's used in running text. You |
| can tell that it's a macro with @samp{#ifdef}. You might do this if you |
| want to define numeric constants with an @code{enum}, but have |
| @samp{#ifdef} be true for each constant. |
| |
| If a macro @code{x} expands to use a macro @code{y}, and the expansion of |
| @code{y} refers to the macro @code{x}, that is an @dfn{indirect |
| self-reference} of @code{x}. @code{x} is not expanded in this case |
| either. Thus, if we have |
| |
| @example |
| #define x (4 + y) |
| #define y (2 * x) |
| @end example |
| |
| @noindent |
| then @code{x} and @code{y} expand as follows: |
| |
| @example |
| @group |
| x @expansion{} (4 + y) |
| @expansion{} (4 + (2 * x)) |
| |
| y @expansion{} (2 * x) |
| @expansion{} (2 * (4 + y)) |
| @end group |
| @end example |
| |
| @noindent |
| Each macro is expanded when it appears in the definition of the other |
| macro, but not when it indirectly appears in its own definition. |
| |
| @node Argument Prescan |
| @subsection Argument Prescan |
| @cindex expansion of arguments |
| @cindex macro argument expansion |
| @cindex prescan of macro arguments |
| |
| Macro arguments are completely macro-expanded before they are |
| substituted into a macro body, unless they are stringified or pasted |
| with other tokens. After substitution, the entire macro body, including |
| the substituted arguments, is scanned again for macros to be expanded. |
| The result is that the arguments are scanned @emph{twice} to expand |
| macro calls in them. |
| |
| Most of the time, this has no effect. If the argument contained any |
| macro calls, they are expanded during the first scan. The result |
| therefore contains no macro calls, so the second scan does not change |
| it. If the argument were substituted as given, with no prescan, the |
| single remaining scan would find the same macro calls and produce the |
| same results. |
| |
| You might expect the double scan to change the results when a |
| self-referential macro is used in an argument of another macro |
| (@pxref{Self-Referential Macros}): the self-referential macro would be |
| expanded once in the first scan, and a second time in the second scan. |
| However, this is not what happens. The self-references that do not |
| expand in the first scan are marked so that they will not expand in the |
| second scan either. |
| |
| You might wonder, ``Why mention the prescan, if it makes no difference? |
| And why not skip it and make the preprocessor faster?'' The answer is |
| that the prescan does make a difference in three special cases: |
| |
| @itemize @bullet |
| @item |
| Nested calls to a macro. |
| |
| We say that @dfn{nested} calls to a macro occur when a macro's argument |
| contains a call to that very macro. For example, if @code{f} is a macro |
| that expects one argument, @code{f (f (1))} is a nested pair of calls to |
| @code{f}. The desired expansion is made by expanding @code{f (1)} and |
| substituting that into the definition of @code{f}. The prescan causes |
| the expected result to happen. Without the prescan, @code{f (1)} itself |
| would be substituted as an argument, and the inner use of @code{f} would |
| appear during the main scan as an indirect self-reference and would not |
| be expanded. |
| |
| @item |
| Macros that call other macros that stringify or concatenate. |
| |
| If an argument is stringified or concatenated, the prescan does not |
| occur. If you @emph{want} to expand a macro, then stringify or |
| concatenate its expansion, you can do that by causing one macro to call |
| another macro that does the stringification or concatenation. For |
| instance, if you have |
| |
| @example |
| #define AFTERX(x) X_ ## x |
| #define XAFTERX(x) AFTERX(x) |
| #define TABLESIZE 1024 |
| #define BUFSIZE TABLESIZE |
| @end example |
| |
| then @code{AFTERX(BUFSIZE)} expands to @code{X_BUFSIZE}, and |
| @code{XAFTERX(BUFSIZE)} expands to @code{X_1024}. (Not to |
| @code{X_TABLESIZE}. Prescan always does a complete expansion.) |
| |
| @item |
| Macros used in arguments, whose expansions contain unshielded commas. |
| |
| This can cause a macro expanded on the second scan to be called with the |
| wrong number of arguments. Here is an example: |
| |
| @example |
| #define foo a,b |
| #define bar(x) lose(x) |
| #define lose(x) (1 + (x)) |
| @end example |
| |
| We would like @code{bar(foo)} to turn into @code{(1 + (foo))}, which |
| would then turn into @code{(1 + (a,b))}. Instead, @code{bar(foo)} |
| expands into @code{lose(a,b)}, and you get an error because @code{lose} |
| requires a single argument. In this case, the problem is easily solved |
| by the same parentheses that ought to be used to prevent misnesting of |
| arithmetic operations: |
| |
| @example |
| #define foo (a,b) |
| @exdent or |
| #define bar(x) lose((x)) |
| @end example |
| |
| The extra pair of parentheses prevents the comma in @code{foo}'s |
| definition from being interpreted as an argument separator. |
| |
| @end itemize |
| |
| @node Newlines in Arguments |
| @subsection Newlines in Arguments |
| @cindex newlines in macro arguments |
| |
| The invocation of a function-like macro can extend over many logical |
| lines. However, in the present implementation, the entire expansion |
| comes out on one line. Thus line numbers emitted by the compiler or |
| debugger refer to the line the invocation started on, which might be |
| different to the line containing the argument causing the problem. |
| |
| Here is an example illustrating this: |
| |
| @example |
| #define ignore_second_arg(a,b,c) a; c |
| |
| ignore_second_arg (foo (), |
| ignored (), |
| syntax error); |
| @end example |
| |
| @noindent |
| The syntax error triggered by the tokens @code{syntax error} results in |
| an error message citing line three---the line of ignore_second_arg--- |
| even though the problematic code comes from line five. |
| |
| We consider this a bug, and intend to fix it in the near future. |
| |
| @node Conditionals |
| @chapter Conditionals |
| @cindex conditionals |
| |
| A @dfn{conditional} is a directive that instructs the preprocessor to |
| select whether or not to include a chunk of code in the final token |
| stream passed to the compiler. Preprocessor conditionals can test |
| arithmetic expressions, or whether a name is defined as a macro, or both |
| simultaneously using the special @code{defined} operator. |
| |
| A conditional in the C preprocessor resembles in some ways an @code{if} |
| statement in C, but it is important to understand the difference between |
| them. The condition in an @code{if} statement is tested during the |
| execution of your program. Its purpose is to allow your program to |
| behave differently from run to run, depending on the data it is |
| operating on. The condition in a preprocessing conditional directive is |
| tested when your program is compiled. Its purpose is to allow different |
| code to be included in the program depending on the situation at the |
| time of compilation. |
| |
| However, the distinction is becoming less clear. Modern compilers often |
| do test @code{if} statements when a program is compiled, if their |
| conditions are known not to vary at run time, and eliminate code which |
| can never be executed. If you can count on your compiler to do this, |
| you may find that your program is more readable if you use @code{if} |
| statements with constant conditions (perhaps determined by macros). Of |
| course, you can only use this to exclude code, not type definitions or |
| other preprocessing directives, and you can only do it if the code |
| remains syntactically valid when it is not to be used. |
| |
| GCC version 3 eliminates this kind of never-executed code even when |
| not optimizing. Older versions did it only when optimizing. |
| |
| @menu |
| * Conditional Uses:: |
| * Conditional Syntax:: |
| * Deleted Code:: |
| @end menu |
| |
| @node Conditional Uses |
| @section Conditional Uses |
| |
| There are three general reasons to use a conditional. |
| |
| @itemize @bullet |
| @item |
| A program may need to use different code depending on the machine or |
| operating system it is to run on. In some cases the code for one |
| operating system may be erroneous on another operating system; for |
| example, it might refer to data types or constants that do not exist on |
| the other system. When this happens, it is not enough to avoid |
| executing the invalid code. Its mere presence will cause the compiler |
| to reject the program. With a preprocessing conditional, the offending |
| code can be effectively excised from the program when it is not valid. |
| |
| @item |
| You may want to be able to compile the same source file into two |
| different programs. One version might make frequent time-consuming |
| consistency checks on its intermediate data, or print the values of |
| those data for debugging, and the other not. |
| |
| @item |
| A conditional whose condition is always false is one way to exclude code |
| from the program but keep it as a sort of comment for future reference. |
| @end itemize |
| |
| Simple programs that do not need system-specific logic or complex |
| debugging hooks generally will not need to use preprocessing |
| conditionals. |
| |
| @node Conditional Syntax |
| @section Conditional Syntax |
| |
| @findex #if |
| A conditional in the C preprocessor begins with a @dfn{conditional |
| directive}: @samp{#if}, @samp{#ifdef} or @samp{#ifndef}. |
| |
| @menu |
| * Ifdef:: |
| * If:: |
| * Defined:: |
| * Else:: |
| * Elif:: |
| @end menu |
| |
| @node Ifdef |
| @subsection Ifdef |
| @findex #ifdef |
| @findex #endif |
| |
| The simplest sort of conditional is |
| |
| @example |
| @group |
| #ifdef @var{MACRO} |
| |
| @var{controlled text} |
| |
| #endif /* @var{MACRO} */ |
| @end group |
| @end example |
| |
| @cindex conditional group |
| This block is called a @dfn{conditional group}. @var{controlled text} |
| will be included in the output of the preprocessor if and only if |
| @var{MACRO} is defined. We say that the conditional @dfn{succeeds} if |
| @var{MACRO} is defined, @dfn{fails} if it is not. |
| |
| The @var{controlled text} inside of a conditional can include |
| preprocessing directives. They are executed only if the conditional |
| succeeds. You can nest conditional groups inside other conditional |
| groups, but they must be completely nested. In other words, |
| @samp{#endif} always matches the nearest @samp{#ifdef} (or |
| @samp{#ifndef}, or @samp{#if}). Also, you cannot start a conditional |
| group in one file and end it in another. |
| |
| Even if a conditional fails, the @var{controlled text} inside it is |
| still run through initial transformations and tokenization. Therefore, |
| it must all be lexically valid C@. Normally the only way this matters is |
| that all comments and string literals inside a failing conditional group |
| must still be properly ended. |
| |
| The comment following the @samp{#endif} is not required, but it is a |
| good practice if there is a lot of @var{controlled text}, because it |
| helps people match the @samp{#endif} to the corresponding @samp{#ifdef}. |
| Older programs sometimes put @var{MACRO} directly after the |
| @samp{#endif} without enclosing it in a comment. This is invalid code |
| according to the C standard. GNU CPP accepts it with a warning. It |
| never affects which @samp{#ifndef} the @samp{#endif} matches. |
| |
| @findex #ifndef |
| Sometimes you wish to use some code if a macro is @emph{not} defined. |
| You can do this by writing @samp{#ifndef} instead of @samp{#ifdef}. |
| One common use of @samp{#ifndef} is to include code only the first |
| time a header file is included. @xref{Once-Only Headers}. |
| |
| Macro definitions can vary between compilations for several reasons. |
| Here are some samples. |
| |
| @itemize @bullet |
| @item |
| Some macros are predefined on each kind of machine |
| (@pxref{System-specific Predefined Macros}). This allows you to provide |
| code specially tuned for a particular machine. |
| |
| @item |
| System header files define more macros, associated with the features |
| they implement. You can test these macros with conditionals to avoid |
| using a system feature on a machine where it is not implemented. |
| |
| @item |
| Macros can be defined or undefined with the @option{-D} and @option{-U} |
| command line options when you compile the program. You can arrange to |
| compile the same source file into two different programs by choosing a |
| macro name to specify which program you want, writing conditionals to |
| test whether or how this macro is defined, and then controlling the |
| state of the macro with command line options, perhaps set in the |
| Makefile. @xref{Invocation}. |
| |
| @item |
| Your program might have a special header file (often called |
| @file{config.h}) that is adjusted when the program is compiled. It can |
| define or not define macros depending on the features of the system and |
| the desired capabilities of the program. The adjustment can be |
| automated by a tool such as @command{autoconf}, or done by hand. |
| @end itemize |
| |
| @node If |
| @subsection If |
| |
| The @samp{#if} directive allows you to test the value of an arithmetic |
| expression, rather than the mere existence of one macro. Its syntax is |
| |
| @example |
| @group |
| #if @var{expression} |
| |
| @var{controlled text} |
| |
| #endif /* @var{expression} */ |
| @end group |
| @end example |
| |
| @var{expression} is a C expression of integer type, subject to stringent |
| restrictions. It may contain |
| |
| @itemize @bullet |
| @item |
| Integer constants. |
| |
| @item |
| Character constants, which are interpreted as they would be in normal |
| code. |
| |
| @item |
| Arithmetic operators for addition, subtraction, multiplication, |
| division, bitwise operations, shifts, comparisons, and logical |
| operations (@code{&&} and @code{||}). The latter two obey the usual |
| short-circuiting rules of standard C@. |
| |
| @item |
| Macros. All macros in the expression are expanded before actual |
| computation of the expression's value begins. |
| |
| @item |
| Uses of the @code{defined} operator, which lets you check whether macros |
| are defined in the middle of an @samp{#if}. |
| |
| @item |
| Identifiers that are not macros, which are all considered to be the |
| number zero. This allows you to write @code{@w{#if MACRO}} instead of |
| @code{@w{#ifdef MACRO}}, if you know that MACRO, when defined, will |
| always have a nonzero value. Function-like macros used without their |
| function call parentheses are also treated as zero. |
| |
| In some contexts this shortcut is undesirable. The @option{-Wundef} |
| option causes GCC to warn whenever it encounters an identifier which is |
| not a macro in an @samp{#if}. |
| @end itemize |
| |
| The preprocessor does not know anything about types in the language. |
| Therefore, @code{sizeof} operators are not recognized in @samp{#if}, and |
| neither are @code{enum} constants. They will be taken as identifiers |
| which are not macros, and replaced by zero. In the case of |
| @code{sizeof}, this is likely to cause the expression to be invalid. |
| |
| The preprocessor calculates the value of @var{expression}. It carries |
| out all calculations in the widest integer type known to the compiler; |
| on most machines supported by GCC this is 64 bits. This is not the same |
| rule as the compiler uses to calculate the value of a constant |
| expression, and may give different results in some cases. If the value |
| comes out to be nonzero, the @samp{#if} succeeds and the @var{controlled |
| text} is included; otherwise it is skipped. |
| |
| If @var{expression} is not correctly formed, GCC issues an error and |
| treats the conditional as having failed. |
| |
| @node Defined |
| @subsection Defined |
| |
| @cindex @code{defined} |
| The special operator @code{defined} is used in @samp{#if} and |
| @samp{#elif} expressions to test whether a certain name is defined as a |
| macro. @code{defined @var{name}} and @code{defined (@var{name})} are |
| both expressions whose value is 1 if @var{name} is defined as a macro at |
| the current point in the program, and 0 otherwise. Thus, @code{@w{#if |
| defined MACRO}} is precisely equivalent to @code{@w{#ifdef MACRO}}. |
| |
| @code{defined} is useful when you wish to test more than one macro for |
| existence at once. For example, |
| |
| @example |
| #if defined (__vax__) || defined (__ns16000__) |
| @end example |
| |
| @noindent |
| would succeed if either of the names @code{__vax__} or |
| @code{__ns16000__} is defined as a macro. |
| |
| Conditionals written like this: |
| |
| @example |
| #if defined BUFSIZE && BUFSIZE >= 1024 |
| @end example |
| |
| @noindent |
| can generally be simplified to just @code{@w{#if BUFSIZE >= 1024}}, |
| since if @code{BUFSIZE} is not defined, it will be interpreted as having |
| the value zero. |
| |
| If the @code{defined} operator appears as a result of a macro expansion, |
| the C standard says the behavior is undefined. GNU cpp treats it as a |
| genuine @code{defined} operator and evaluates it normally. It will warn |
| wherever your code uses this feature if you use the command-line option |
| @option{-pedantic}, since other compilers may handle it differently. |
| |
| @node Else |
| @subsection Else |
| |
| @findex #else |
| The @samp{#else} directive can be added to a conditional to provide |
| alternative text to be used if the condition fails. This is what it |
| looks like: |
| |
| @example |
| @group |
| #if @var{expression} |
| @var{text-if-true} |
| #else /* Not @var{expression} */ |
| @var{text-if-false} |
| #endif /* Not @var{expression} */ |
| @end group |
| @end example |
| |
| @noindent |
| If @var{expression} is nonzero, the @var{text-if-true} is included and |
| the @var{text-if-false} is skipped. If @var{expression} is zero, the |
| opposite happens. |
| |
| You can use @samp{#else} with @samp{#ifdef} and @samp{#ifndef}, too. |
| |
| @node Elif |
| @subsection Elif |
| |
| @findex #elif |
| One common case of nested conditionals is used to check for more than two |
| possible alternatives. For example, you might have |
| |
| @example |
| #if X == 1 |
| @dots{} |
| #else /* X != 1 */ |
| #if X == 2 |
| @dots{} |
| #else /* X != 2 */ |
| @dots{} |
| #endif /* X != 2 */ |
| #endif /* X != 1 */ |
| @end example |
| |
| Another conditional directive, @samp{#elif}, allows this to be |
| abbreviated as follows: |
| |
| @example |
| #if X == 1 |
| @dots{} |
| #elif X == 2 |
| @dots{} |
| #else /* X != 2 and X != 1*/ |
| @dots{} |
| #endif /* X != 2 and X != 1*/ |
| @end example |
| |
| @samp{#elif} stands for ``else if''. Like @samp{#else}, it goes in the |
| middle of a conditional group and subdivides it; it does not require a |
| matching @samp{#endif} of its own. Like @samp{#if}, the @samp{#elif} |
| directive includes an expression to be tested. The text following the |
| @samp{#elif} is processed only if the original @samp{#if}-condition |
| failed and the @samp{#elif} condition succeeds. |
| |
| More than one @samp{#elif} can go in the same conditional group. Then |
| the text after each @samp{#elif} is processed only if the @samp{#elif} |
| condition succeeds after the original @samp{#if} and all previous |
| @samp{#elif} directives within it have failed. |
| |
| @samp{#else} is allowed after any number of @samp{#elif} directives, but |
| @samp{#elif} may not follow @samp{#else}. |
| |
| @node Deleted Code |
| @section Deleted Code |
| @cindex commenting out code |
| |
| If you replace or delete a part of the program but want to keep the old |
| code around for future reference, you often cannot simply comment it |
| out. Block comments do not nest, so the first comment inside the old |
| code will end the commenting-out. The probable result is a flood of |
| syntax errors. |
| |
| One way to avoid this problem is to use an always-false conditional |
| instead. For instance, put @code{#if 0} before the deleted code and |
| @code{#endif} after it. This works even if the code being turned |
| off contains conditionals, but they must be entire conditionals |
| (balanced @samp{#if} and @samp{#endif}). |
| |
| Some people use @code{#ifdef notdef} instead. This is risky, because |
| @code{notdef} might be accidentally defined as a macro, and then the |
| conditional would succeed. @code{#if 0} can be counted on to fail. |
| |
| Do not use @code{#if 0} for comments which are not C code. Use a real |
| comment, instead. The interior of @code{#if 0} must consist of complete |
| tokens; in particular, single-quote characters must balance. Comments |
| often contain unbalanced single-quote characters (known in English as |
| apostrophes). These confuse @code{#if 0}. They don't confuse |
| @samp{/*}. |
| |
| @node Diagnostics |
| @chapter Diagnostics |
| @cindex diagnostic |
| @cindex reporting errors |
| @cindex reporting warnings |
| |
| @findex #error |
| The directive @samp{#error} causes the preprocessor to report a fatal |
| error. The tokens forming the rest of the line following @samp{#error} |
| are used as the error message. |
| |
| You would use @samp{#error} inside of a conditional that detects a |
| combination of parameters which you know the program does not properly |
| support. For example, if you know that the program will not run |
| properly on a VAX, you might write |
| |
| @example |
| @group |
| #ifdef __vax__ |
| #error "Won't work on VAXen. See comments at get_last_object." |
| #endif |
| @end group |
| @end example |
| |
| If you have several configuration parameters that must be set up by |
| the installation in a consistent way, you can use conditionals to detect |
| an inconsistency and report it with @samp{#error}. For example, |
| |
| @example |
| #if !defined(UNALIGNED_INT_ASM_OP) && defined(DWARF2_DEBUGGING_INFO) |
| #error "DWARF2_DEBUGGING_INFO requires UNALIGNED_INT_ASM_OP." |
| #endif |
| @end example |
| |
| @findex #warning |
| The directive @samp{#warning} is like @samp{#error}, but causes the |
| preprocessor to issue a warning and continue preprocessing. The tokens |
| following @samp{#warning} are used as the warning message. |
| |
| You might use @samp{#warning} in obsolete header files, with a message |
| directing the user to the header file which should be used instead. |
| |
| Neither @samp{#error} nor @samp{#warning} macro-expands its argument. |
| Internal whitespace sequences are each replaced with a single space. |
| The line must consist of complete tokens. It is wisest to make the |
| argument of these directives be a single string constant; this avoids |
| problems with apostrophes and the like. |
| |
| @node Line Control |
| @chapter Line Control |
| @cindex line control |
| |
| The C preprocessor informs the C compiler of the location in your source |
| code where each token came from. Presently, this is just the file name |
| and line number. All the tokens resulting from macro expansion are |
| reported as having appeared on the line of the source file where the |
| outermost macro was used. We intend to be more accurate in the future. |
| |
| If you write a program which generates source code, such as the |
| @command{bison} parser generator, you may want to adjust the preprocessor's |
| notion of the current file name and line number by hand. Parts of the |
| output from @command{bison} are generated from scratch, other parts come |
| from a standard parser file. The rest are copied verbatim from |
| @command{bison}'s input. You would like compiler error messages and |
| symbolic debuggers to be able to refer to @code{bison}'s input file. |
| |
| @findex #line |
| @command{bison} or any such program can arrange this by writing |
| @samp{#line} directives into the output file. @samp{#line} is a |
| directive that specifies the original line number and source file name |
| for subsequent input in the current preprocessor input file. |
| @samp{#line} has three variants: |
| |
| @table @code |
| @item #line @var{linenum} |
| @var{linenum} is a non-negative decimal integer constant. It specifies |
| the line number which should be reported for the following line of |
| input. Subsequent lines are counted from @var{linenum}. |
| |
| @item #line @var{linenum} @var{filename} |
| @var{linenum} is the same as for the first form, and has the same |
| effect. In addition, @var{filename} is a string constant. The |
| following line and all subsequent lines are reported to come from the |
| file it specifies, until something else happens to change that. |
| |
| @item #line @var{anything else} |
| @var{anything else} is checked for macro calls, which are expanded. |
| The result should match one of the above two forms. |
| @end table |
| |
| @samp{#line} directives alter the results of the @code{__FILE__} and |
| @code{__LINE__} predefined macros from that point on. @xref{Standard |
| Predefined Macros}. They do not have any effect on @samp{#include}'s |
| idea of the directory containing the current file. This is a change |
| from GCC 2.95. Previously, a file reading |
| |
| @smallexample |
| #line 1 "../src/gram.y" |
| #include "gram.h" |
| @end smallexample |
| |
| would search for @file{gram.h} in @file{../src}, then the @option{-I} |
| chain; the directory containing the physical source file would not be |
| searched. In GCC 3.0 and later, the @samp{#include} is not affected by |
| the presence of a @samp{#line} referring to a different directory. |
| |
| We made this change because the old behavior caused problems when |
| generated source files were transported between machines. For instance, |
| it is common practice to ship generated parsers with a source release, |
| so that people building the distribution do not need to have yacc or |
| Bison installed. These files frequently have @samp{#line} directives |
| referring to the directory tree of the system where the distribution was |
| created. If GCC tries to search for headers in those directories, the |
| build is likely to fail. |
| |
| The new behavior can cause failures too, if the generated file is not |
| in the same directory as its source and it attempts to include a header |
| which would be visible searching from the directory containing the |
| source file. However, this problem is easily solved with an additional |
| @option{-I} switch on the command line. The failures caused by the old |
| semantics could sometimes be corrected only by editing the generated |
| files, which is difficult and error-prone. |
| |
| @node Pragmas |
| @chapter Pragmas |
| |
| The @samp{#pragma} directive is the method specified by the C standard |
| for providing additional information to the compiler, beyond what is |
| conveyed in the language itself. Three forms of this directive |
| (commonly known as @dfn{pragmas}) are specified by the 1999 C standard. |
| A C compiler is free to attach any meaning it likes to other pragmas. |
| |
| GCC has historically preferred to use extensions to the syntax of the |
| language, such as @code{__attribute__}, for this purpose. However, GCC |
| does define a few pragmas of its own. These mostly have effects on the |
| entire translation unit or source file. |
| |
| In GCC version 3, all GNU-defined, supported pragmas have been given a |
| @code{GCC} prefix. This is in line with the @code{STDC} prefix on all |
| pragmas defined by C99. For backward compatibility, pragmas which were |
| recognized by previous versions are still recognized without the |
| @code{GCC} prefix, but that usage is deprecated. Some older pragmas are |
| deprecated in their entirety. They are not recognized with the |
| @code{GCC} prefix. @xref{Obsolete Features}. |
| |
| @cindex @code{_Pragma} |
| C99 introduces the @code{@w{_Pragma}} operator. This feature addresses a |
| major problem with @samp{#pragma}: being a directive, it cannot be |
| produced as the result of macro expansion. @code{@w{_Pragma}} is an |
| operator, much like @code{sizeof} or @code{defined}, and can be embedded |
| in a macro. |
| |
| Its syntax is @code{@w{_Pragma (@var{string-literal})}}, where |
| @var{string-literal} can be either a normal or wide-character string |
| literal. It is destringized, by replacing all @samp{\\} with a single |
| @samp{\} and all @samp{\"} with a @samp{"}. The result is then |
| processed as if it had appeared as the right hand side of a |
| @samp{#pragma} directive. For example, |
| |
| @example |
| _Pragma ("GCC dependency \"parse.y\"") |
| @end example |
| |
| @noindent |
| has the same effect as @code{#pragma GCC dependency "parse.y"}. The |
| same effect could be achieved using macros, for example |
| |
| @example |
| #define DO_PRAGMA(x) _Pragma (#x) |
| DO_PRAGMA (GCC dependency "parse.y") |
| @end example |
| |
| The standard is unclear on where a @code{_Pragma} operator can appear. |
| The preprocessor does not accept it within a preprocessing conditional |
| directive like @samp{#if}. To be safe, you are probably best keeping it |
| out of directives other than @samp{#define}, and putting it on a line of |
| its own. |
| |
| This manual documents the pragmas which are meaningful to the |
| preprocessor itself. Other pragmas are meaningful to the C or C++ |
| compilers. They are documented in the GCC manual. |
| |
| @ftable @code |
| @item #pragma GCC dependency |
| @code{#pragma GCC dependency} allows you to check the relative dates of |
| the current file and another file. If the other file is more recent than |
| the current file, a warning is issued. This is useful if the current |
| file is derived from the other file, and should be regenerated. The |
| other file is searched for using the normal include search path. |
| Optional trailing text can be used to give more information in the |
| warning message. |
| |
| @example |
| #pragma GCC dependency "parse.y" |
| #pragma GCC dependency "/usr/include/time.h" rerun fixincludes |
| @end example |
| |
| @item #pragma GCC poison |
| Sometimes, there is an identifier that you want to remove completely |
| from your program, and make sure that it never creeps back in. To |
| enforce this, you can @dfn{poison} the identifier with this pragma. |
| @code{#pragma GCC poison} is followed by a list of identifiers to |
| poison. If any of those identifiers appears anywhere in the source |
| after the directive, it is a hard error. For example, |
| |
| @example |
| #pragma GCC poison printf sprintf fprintf |
| sprintf(some_string, "hello"); |
| @end example |
| |
| @noindent |
| will produce an error. |
| |
| If a poisoned identifier appears as part of the expansion of a macro |
| which was defined before the identifier was poisoned, it will @emph{not} |
| cause an error. This lets you poison an identifier without worrying |
| about system headers defining macros that use it. |
| |
| For example, |
| |
| @example |
| #define strrchr rindex |
| #pragma GCC poison rindex |
| strrchr(some_string, 'h'); |
| @end example |
| |
| @noindent |
| will not produce an error. |
| |
| @item #pragma GCC system_header |
| This pragma takes no arguments. It causes the rest of the code in the |
| current file to be treated as if it came from a system header. |
| @xref{System Headers}. |
| |
| @end ftable |
| |
| @node Other Directives |
| @chapter Other Directives |
| |
| @findex #ident |
| The @samp{#ident} directive takes one argument, a string constant. On |
| some systems, that string constant is copied into a special segment of |
| the object file. On other systems, the directive is ignored. |
| |
| This directive is not part of the C standard, but it is not an official |
| GNU extension either. We believe it came from System V@. |
| |
| @findex #sccs |
| The @samp{#sccs} directive is recognized on some systems, because it |
| appears in their header files. It is a very old, obscure, extension |
| which we did not invent, and we have been unable to find any |
| documentation of what it should do, so GCC simply ignores it. |
| |
| @cindex null directive |
| The @dfn{null directive} consists of a @samp{#} followed by a newline, |
| with only whitespace (including comments) in between. A null directive |
| is understood as a preprocessing directive but has no effect on the |
| preprocessor output. The primary significance of the existence of the |
| null directive is that an input line consisting of just a @samp{#} will |
| produce no output, rather than a line of output containing just a |
| @samp{#}. Supposedly some old C programs contain such lines. |
| |
| @node Preprocessor Output |
| @chapter Preprocessor Output |
| |
| When the C preprocessor is used with the C, C++, or Objective-C |
| compilers, it is integrated into the compiler and communicates a stream |
| of binary tokens directly to the compiler's parser. However, it can |
| also be used in the more conventional standalone mode, where it produces |
| textual output. |
| @c FIXME: Document the library interface. |
| |
| @cindex output format |
| The output from the C preprocessor looks much like the input, except |
| that all preprocessing directive lines have been replaced with blank |
| lines and all comments with spaces. Long runs of blank lines are |
| discarded. |
| |
| The ISO standard specifies that it is implementation defined whether a |
| preprocessor preserves whitespace between tokens, or replaces it with |
| e.g.@: a single space. In GNU CPP, whitespace between tokens is collapsed |
| to become a single space, with the exception that the first token on a |
| non-directive line is preceded with sufficient spaces that it appears in |
| the same column in the preprocessed output that it appeared in the |
| original source file. This is so the output is easy to read. |
| @xref{Differences from previous versions}. CPP does not insert any |
| whitespace where there was none in the original source, except where |
| necessary to prevent an accidental token paste. |
| |
| @cindex linemarkers |
| Source file name and line number information is conveyed by lines |
| of the form |
| |
| @example |
| # @var{linenum} @var{filename} @var{flags} |
| @end example |
| |
| @noindent |
| These are called @dfn{linemarkers}. They are inserted as needed into |
| the output (but never within a string or character constant). They mean |
| that the following line originated in file @var{filename} at line |
| @var{linenum}. |
| |
| After the file name comes zero or more flags, which are @samp{1}, |
| @samp{2}, @samp{3}, or @samp{4}. If there are multiple flags, spaces |
| separate them. Here is what the flags mean: |
| |
| @table @samp |
| @item 1 |
| This indicates the start of a new file. |
| @item 2 |
| This indicates returning to a file (after having included another file). |
| @item 3 |
| This indicates that the following text comes from a system header file, |
| so certain warnings should be suppressed. |
| @item 4 |
| This indicates that the following text should be treated as being |
| wrapped in an implicit @code{extern "C"} block. |
| @c maybe cross reference NO_IMPLICIT_EXTERN_C |
| @end table |
| |
| As an extension, the preprocessor accepts linemarkers in non-assembler |
| input files. They are treated like the corresponding @samp{#line} |
| directive, (@pxref{Line Control}), except that trailing flags are |
| permitted, and are interpreted with the meanings described above. If |
| multiple flags are given, they must be in ascending order. |
| |
| Some directives may be duplicated in the output of the preprocessor. |
| These are @samp{#ident} (always), @samp{#pragma} (only if the |
| preprocessor does not handle the pragma itself), and @samp{#define} and |
| @samp{#undef} (with certain debugging options). If this happens, the |
| @samp{#} of the directive will always be in the first column, and there |
| will be no space between the @samp{#} and the directive name. If macro |
| expansion happens to generate tokens which might be mistaken for a |
| duplicated directive, a space will be inserted between the @samp{#} and |
| the directive name. |
| |
| @node Traditional Mode |
| @chapter Traditional Mode |
| |
| Traditional (pre-standard) C preprocessing is rather different from |
| the preprocessing specified by the standard. When GCC is given the |
| @option{-traditional} option, it attempts to emulate a traditional |
| preprocessor. We do not guarantee that GCC's behavior under |
| @option{-traditional} matches any pre-standard preprocessor exactly. |
| |
| Traditional mode exists only for backward compatibility. We have no |
| plans to augment it in any way nor will we change it except to fix |
| catastrophic bugs. As of GCC 3.2, traditional mode is not supported for |
| compilation, only preprocessing. |
| |
| This is a list of the differences. It may not be complete, and may not |
| correspond exactly to the behavior of either GCC or a true traditional |
| preprocessor. |
| |
| @itemize @bullet |
| @item |
| Traditional macro expansion pays no attention to single-quote or |
| double-quote characters; macro argument symbols are replaced by the |
| argument values even when they appear within apparent string or |
| character constants. |
| |
| @item |
| Traditionally, it is permissible for a macro expansion to end in the |
| middle of a string or character constant. The constant continues into |
| the text surrounding the macro call. |
| |
| @item |
| However, the end of the line terminates a string or character constant, |
| with no error. (This is a kluge. Traditional mode is commonly used to |
| preprocess things which are not C, and have a different comment syntax. |
| Single apostrophes often appear in comments. This kluge prevents the |
| traditional preprocessor from issuing errors on such comments.) |
| |
| @item |
| Preprocessing directives are recognized in traditional C only when their |
| leading @samp{#} appears in the first column. There can be no |
| whitespace between the beginning of the line and the @samp{#}. |
| |
| @item |
| In traditional C, a comment is equivalent to no text at all. (In ISO |
| C, a comment counts as whitespace.) It can be used sort of the same way |
| that @samp{##} is used in ISO C, to paste macro arguments together. |
| |
| @item |
| Traditional C does not have the concept of a preprocessing number. |
| |
| @item |
| A macro is not suppressed within its own definition, in traditional C@. |
| Thus, any macro that is used recursively inevitably causes an error. |
| |
| @item |
| The @samp{#} and @samp{##} operators are not available in traditional |
| C@. |
| |
| @item |
| In traditional C, the text at the end of a macro expansion can run |
| together with the text after the macro call, to produce a single token. |
| This is impossible in ISO C@. |
| |
| @item |
| None of the GNU extensions to the preprocessor are available in |
| traditional mode, with the exception of a partial implementation of |
| assertions, and those may be removed in the future. |
| |
| @item |
| A true traditional C preprocessor does not recognize @samp{#elif}, |
| @samp{#error}, or @samp{#pragma}. GCC supports @samp{#elif} and |
| @samp{#error} even in traditional mode, but not @samp{#pragma}. |
| |
| @item |
| Traditional mode is text-based, not token-based, and comments are |
| stripped after macro expansion. Therefore, @samp{/**/} can be used to |
| paste tokens together provided that there is no whitespace between it |
| and the tokens to be pasted. |
| |
| @item |
| Traditional mode preserves the amount and form of whitespace provided by |
| the user. Hard tabs remain hard tabs. This can be useful, e.g.@: if you |
| are preprocessing a Makefile (which we do not encourage). |
| @end itemize |
| |
| You can request warnings about features that did not exist, or worked |
| differently, in traditional C with the @option{-Wtraditional} option. |
| This works only if you do @emph{not} specify @option{-traditional}. GCC |
| does not warn about features of ISO C which you must use when you are |
| using a conforming compiler, such as the @samp{#} and @samp{##} |
| operators. |
| |
| Presently @option{-Wtraditional} warns about: |
| |
| @itemize @bullet |
| @item |
| Macro parameters that appear within string literals in the macro body. |
| In traditional C macro replacement takes place within string literals, |
| but does not in ISO C@. |
| |
| @item |
| In traditional C, some preprocessor directives did not exist. |
| Traditional preprocessors would only consider a line to be a directive |
| if the @samp{#} appeared in column 1 on the line. Therefore |
| @option{-Wtraditional} warns about directives that traditional C |
| understands but would ignore because the @samp{#} does not appear as the |
| first character on the line. It also suggests you hide directives like |
| @samp{#pragma} not understood by traditional C by indenting them. Some |
| traditional implementations would not recognize @samp{#elif}, so it |
| suggests avoiding it altogether. |
| |
| @item |
| A function-like macro that appears without an argument list. In |
| traditional C this was an error. In ISO C it merely means that the |
| macro is not expanded. |
| |
| @item |
| The unary plus operator. This did not exist in traditional C@. |
| |
| @item |
| The @samp{U} and @samp{LL} integer constant suffixes, which were not |
| available in traditional C@. (Traditional C does support the @samp{L} |
| suffix for simple long integer constants.) You are not warned about |
| uses of these suffixes in macros defined in system headers. For |
| instance, @code{UINT_MAX} may well be defined as @code{4294967295U}, but |
| you will not be warned if you use @code{UINT_MAX}. |
| |
| You can usually avoid the warning, and the related warning about |
| constants which are so large that they are unsigned, by writing the |
| integer constant in question in hexadecimal, with no U suffix. Take |
| care, though, because this gives the wrong result in exotic cases. |
| @end itemize |
| |
| @node Implementation Details |
| @chapter Implementation Details |
| |
| Here we document details of how the preprocessor's implementation |
| affects its user-visible behavior. You should try to avoid undue |
| reliance on behavior described here, as it is possible that it will |
| change subtly in future implementations. |
| |
| Also documented here are obsolete features and changes from previous |
| versions of GNU CPP@. |
| |
| @menu |
| * Implementation-defined behavior:: |
| * Implementation limits:: |
| * Obsolete Features:: |
| * Differences from previous versions:: |
| @end menu |
| |
| @node Implementation-defined behavior |
| @section Implementation-defined behavior |
| @cindex implementation-defined behavior |
| |
| This is how GNU CPP behaves in all the cases which the C standard |
| describes as @dfn{implementation-defined}. This term means that the |
| implementation is free to do what it likes, but must document its choice |
| and stick to it. |
| @c FIXME: Check the C++ standard for more implementation-defined stuff. |
| |
| @itemize @bullet |
| @need 1000 |
| @item The mapping of physical source file multi-byte characters to the |
| execution character set. |
| |
| Currently, GNU cpp only supports character sets that are strict supersets |
| of ASCII, and performs no translation of characters. |
| |
| @item Non-empty sequences of whitespace characters. |
| |
| In textual output, each whitespace sequence is collapsed to a single |
| space. For aesthetic reasons, the first token on each non-directive |
| line of output is preceded with sufficient spaces that it appears in the |
| same column as it did in the original source file. |
| |
| @item The numeric value of character constants in preprocessor expressions. |
| |
| The preprocessor and compiler interpret character constants in the same |
| way; escape sequences such as @samp{\a} are given the values they would |
| have on the target machine. |
| |
| Multi-character character constants are interpreted a character at a |
| time, shifting the previous result left by the number of bits per |
| character on the host, and adding the new character. For example, 'ab' |
| on an 8-bit host would be interpreted as @w{'a' * 256 + 'b'}. If there |
| are more characters in the constant than can fit in the widest native |
| integer type on the host, usually a @code{long}, the excess characters |
| are ignored and a diagnostic is given. |
| |
| @item Source file inclusion. |
| |
| For a discussion on how the preprocessor locates header files, |
| @ref{Include Operation}. |
| |
| @item Interpretation of the filename resulting from a macro-expanded |
| @samp{#include} directive. |
| |
| @xref{Computed Includes}. |
| |
| @item Treatment of a @samp{#pragma} directive that after macro-expansion |
| results in a standard pragma. |
| |
| No macro expansion occurs on any @samp{#pragma} directive line, so the |
| question does not arise. |
| |
| Note that GCC does not yet implement any of the standard |
| pragmas. |
| |
| @end itemize |
| |
| @node Implementation limits |
| @section Implementation limits |
| @cindex implementation limits |
| |
| GNU CPP has a small number of internal limits. This section lists the |
| limits which the C standard requires to be no lower than some minimum, |
| and all the others we are aware of. We intend there to be as few limits |
| as possible. If you encounter an undocumented or inconvenient limit, |
| please report that to us as a bug. (See the section on reporting bugs in |
| the GCC manual.) |
| |
| Where we say something is limited @dfn{only by available memory}, that |
| means that internal data structures impose no intrinsic limit, and space |
| is allocated with @code{malloc} or equivalent. The actual limit will |
| therefore depend on many things, such as the size of other things |
| allocated by the compiler at the same time, the amount of memory |
| consumed by other processes on the same computer, etc. |
| |
| @itemize @bullet |
| |
| @item Nesting levels of @samp{#include} files. |
| |
| We impose an arbitrary limit of 200 levels, to avoid runaway recursion. |
| The standard requires at least 15 levels. |
| |
| @item Nesting levels of conditional inclusion. |
| |
| The C standard mandates this be at least 63. GNU CPP is limited only by |
| available memory. |
| |
| @item Levels of parenthesised expressions within a full expression. |
| |
| The C standard requires this to be at least 63. In preprocessor |
| conditional expressions, it is limited only by available memory. |
| |
| @item Significant initial characters in an identifier or macro name. |
| |
| The preprocessor treats all characters as significant. The C standard |
| requires only that the first 63 be significant. |
| |
| @item Number of macros simultaneously defined in a single translation unit. |
| |
| The standard requires at least 4095 be possible. GNU CPP is limited only |
| by available memory. |
| |
| @item Number of parameters in a macro definition and arguments in a macro call. |
| |
| We allow @code{USHRT_MAX}, which is no smaller than 65,535. The minimum |
| required by the standard is 127. |
| |
| @item Number of characters on a logical source line. |
| |
| The C standard requires a minimum of 4096 be permitted. GNU CPP places |
| no limits on this, but you may get incorrect column numbers reported in |
| diagnostics for lines longer than 65,535 characters. |
| |
| @item Maximum size of a source file. |
| |
| The standard does not specify any lower limit on the maximum size of a |
| source file. GNU cpp maps files into memory, so it is limited by the |
| available address space. This is generally at least two gigabytes. |
| Depending on the operating system, the size of physical memory may or |
| may not be a limitation. |
| |
| @end itemize |
| |
| @node Obsolete Features |
| @section Obsolete Features |
| |
| GNU CPP has a number of features which are present mainly for |
| compatibility with older programs. We discourage their use in new code. |
| In some cases, we plan to remove the feature in a future version of GCC@. |
| |
| @menu |
| * Assertions:: |
| * Obsolete once-only headers:: |
| * Miscellaneous obsolete features:: |
| @end menu |
| |
| @node Assertions |
| @subsection Assertions |
| @cindex assertions |
| |
| @dfn{Assertions} are a deprecated alternative to macros in writing |
| conditionals to test what sort of computer or system the compiled |
| program will run on. Assertions are usually predefined, but you can |
| define them with preprocessing directives or command-line options. |
| |
| Assertions were intended to provide a more systematic way to describe |
| the compiler's target system. However, in practice they are just as |
| unpredictable as the system-specific predefined macros. In addition, they |
| are not part of any standard, and only a few compilers support them. |
| Therefore, the use of assertions is @strong{less} portable than the use |
| of system-specific predefined macros. We recommend you do not use them at |
| all. |
| |
| @cindex predicates |
| An assertion looks like this: |
| |
| @example |
| #@var{predicate} (@var{answer}) |
| @end example |
| |
| @noindent |
| @var{predicate} must be a single identifier. @var{answer} can be any |
| sequence of tokens; all characters are significant except for leading |
| and trailing whitespace, and differences in internal whitespace |
| sequences are ignored. (This is similar to the rules governing macro |
| redefinition.) Thus, @code{(x + y)} is different from @code{(x+y)} but |
| equivalent to @code{@w{( x + y )}}. Parentheses do not nest inside an |
| answer. |
| |
| @cindex testing predicates |
| To test an assertion, you write it in an @samp{#if}. For example, this |
| conditional succeeds if either @code{vax} or @code{ns16000} has been |
| asserted as an answer for @code{machine}. |
| |
| @example |
| #if #machine (vax) || #machine (ns16000) |
| @end example |
| |
| @noindent |
| You can test whether @emph{any} answer is asserted for a predicate by |
| omitting the answer in the conditional: |
| |
| @example |
| #if #machine |
| @end example |
| |
| @findex #assert |
| Assertions are made with the @samp{#assert} directive. Its sole |
| argument is the assertion to make, without the leading @samp{#} that |
| identifies assertions in conditionals. |
| |
| @example |
| #assert @var{predicate} (@var{answer}) |
| @end example |
| |
| @noindent |
| You may make several assertions with the same predicate and different |
| answers. Subsequent assertions do not override previous ones for the |
| same predicate. All the answers for any given predicate are |
| simultaneously true. |
| |
| @cindex assertions, cancelling |
| @findex #unassert |
| Assertions can be cancelled with the @samp{#unassert} directive. It |
| has the same syntax as @samp{#assert}. In that form it cancels only the |
| answer which was specified on the @samp{#unassert} line; other answers |
| for that predicate remain true. You can cancel an entire predicate by |
| leaving out the answer: |
| |
| @example |
| #unassert @var{predicate} |
| @end example |
| |
| @noindent |
| In either form, if no such assertion has been made, @samp{#unassert} has |
| no effect. |
| |
| You can also make or cancel assertions using command line options. |
| @xref{Invocation}. |
| |
| @node Obsolete once-only headers |
| @subsection Obsolete once-only headers |
| |
| GNU CPP supports two more ways of indicating that a header file should be |
| read only once. Neither one is as portable as a wrapper @samp{#ifndef}, |
| and we recommend you do not use them in new programs. |
| |
| @findex #import |
| In the Objective-C language, there is a variant of @samp{#include} |
| called @samp{#import} which includes a file, but does so at most once. |
| If you use @samp{#import} instead of @samp{#include}, then you don't |
| need the conditionals inside the header file to prevent multiple |
| inclusion of the contents. GCC permits the use of @samp{#import} in C |
| and C++ as well as Objective-C@. However, it is not in standard C or C++ |
| and should therefore not be used by portable programs. |
| |
| @samp{#import} is not a well designed feature. It requires the users of |
| a header file to know that it should only be included once. It is much |
| better for the header file's implementor to write the file so that users |
| don't need to know this. Using a wrapper @samp{#ifndef} accomplishes |
| this goal. |
| |
| In the present implementation, a single use of @samp{#import} will |
| prevent the file from ever being read again, by either @samp{#import} or |
| @samp{#include}. You should not rely on this; do not use both |
| @samp{#import} and @samp{#include} to refer to the same header file. |
| |
| Another way to prevent a header file from being included more than once |
| is with the @samp{#pragma once} directive. If @samp{#pragma once} is |
| seen when scanning a header file, that file will never be read again, no |
| matter what. |
| |
| @samp{#pragma once} does not have the problems that @samp{#import} does, |
| but it is not recognized by all preprocessors, so you cannot rely on it |
| in a portable program. |
| |
| @node Miscellaneous obsolete features |
| @subsection Miscellaneous obsolete features |
| |
| Here are a few more obsolete features. |
| |
| @itemize @bullet |
| @cindex invalid token paste |
| @item Attempting to paste two tokens which together do not form a valid |
| preprocessing token. |
| |
| The preprocessor currently warns about this and outputs the two tokens |
| adjacently, which is probably the behavior the programmer intends. It |
| may not work in future, though. |
| |
| Most of the time, when you get this warning, you will find that @samp{##} |
| is being used superstitiously, to guard against whitespace appearing |
| between two tokens. It is almost always safe to delete the @samp{##}. |
| |
| @cindex pragma poison |
| @item @code{#pragma poison} |
| |
| This is the same as @code{#pragma GCC poison}. The version without the |
| @code{GCC} prefix is deprecated. @xref{Pragmas}. |
| |
| @cindex multi-line string constants |
| @item Multi-line string constants |
| |
| GCC currently allows a string constant to extend across multiple logical |
| lines of the source file. This extension is deprecated and will be |
| removed in a future version of GCC@. Such string constants are already |
| rejected in all directives apart from @samp{#define}. |
| |
| Instead, make use of ISO C concatenation of adjacent string literals, or |
| use @samp{\n} followed by a backslash-newline. |
| |
| @end itemize |
| |
| @node Differences from previous versions |
| @section Differences from previous versions |
| @cindex differences from previous versions |
| |
| This section details behavior which has changed from previous versions |
| of GNU CPP@. We do not plan to change it again in the near future, but |
| we do not promise not to, either. |
| |
| The ``previous versions'' discussed here are 2.95 and before. The |
| behavior of GCC 3.0 is mostly the same as the behavior of the widely |
| used 2.96 and 2.97 development snapshots. Where there are differences, |
| they generally represent bugs in the snapshots. |
| |
| @itemize @bullet |
| |
| @item Order of evaluation of @samp{#} and @samp{##} operators |
| |
| The standard does not specify the order of evaluation of a chain of |
| @samp{##} operators, nor whether @samp{#} is evaluated before, after, or |
| at the same time as @samp{##}. You should therefore not write any code |
| which depends on any specific ordering. It is possible to guarantee an |
| ordering, if you need one, by suitable use of nested macros. |
| |
| An example of where this might matter is pasting the arguments @samp{1}, |
| @samp{e} and @samp{-2}. This would be fine for left-to-right pasting, |
| but right-to-left pasting would produce an invalid token @samp{e-2}. |
| |
| GCC 3.0 evaluates @samp{#} and @samp{##} at the same time and strictly |
| left to right. Older versions evaluated all @samp{#} operators first, |
| then all @samp{##} operators, in an unreliable order. |
| |
| @item The form of whitespace betwen tokens in preprocessor output |
| |
| @xref{Preprocessor Output}, for the current textual format. This is |
| also the format used by stringification. Normally, the preprocessor |
| communicates tokens directly to the compiler's parser, and whitespace |
| does not come up at all. |
| |
| Older versions of GCC preserved all whitespace provided by the user and |
| inserted lots more whitespace of their own, because they could not |
| accurately predict when extra spaces were needed to prevent accidental |
| token pasting. |
| |
| @item Optional argument when invoking rest argument macros |
| |
| As an extension, GCC permits you to omit the variable arguments entirely |
| when you use a variable argument macro. This is forbidden by the 1999 C |
| standard, and will provoke a pedantic warning with GCC 3.0. Previous |
| versions accepted it silently. |
| |
| @item @samp{##} swallowing preceding text in rest argument macros |
| |
| Formerly, in a macro expansion, if @samp{##} appeared before a variable |
| arguments parameter, and the set of tokens specified for that argument |
| in the macro invocation was empty, previous versions of GNU CPP would |
| back up and remove the preceding sequence of non-whitespace characters |
| (@strong{not} the preceding token). This extension is in direct |
| conflict with the 1999 C standard and has been drastically pared back. |
| |
| In the current version of the preprocessor, if @samp{##} appears between |
| a comma and a variable arguments parameter, and the variable argument is |
| omitted entirely, the comma will be removed from the expansion. If the |
| variable argument is empty, or the token before @samp{##} is not a |
| comma, then @samp{##} behaves as a normal token paste. |
| |
| @item Traditional mode and GNU extensions |
| |
| Traditional mode used to be implemented in the same program as normal |
| preprocessing. Therefore, all the GNU extensions to the preprocessor |
| were still available in traditional mode. It is now a separate program |
| and does not implement any of the GNU extensions, except for a partial |
| implementation of assertions. Even those may be removed in a future |
| release. |
| |
| @item @samp{#line} and @samp{#include} |
| |
| The @samp{#line} directive used to change GCC's notion of the |
| ``directory containing the current file,'' used by @samp{#include} with |
| a double-quoted header file name. In 3.0 and later, it does not. |
| @xref{Line Control}, for further explanation. |
| |
| @end itemize |
| |
| @node Invocation |
| @chapter Invocation |
| @cindex invocation |
| @cindex command line |
| |
| Most often when you use the C preprocessor you will not have to invoke it |
| explicitly: the C compiler will do so automatically. However, the |
| preprocessor is sometimes useful on its own. All the options listed |
| here are also acceptable to the C compiler and have the same meaning, |
| except that the C compiler has different rules for specifying the output |
| file. |
| |
| @strong{Note:} Whether you use the preprocessor by way of @command{gcc} |
| or @command{cpp}, the @dfn{compiler driver} is run first. This |
| program's purpose is to translate your command into invocations of the |
| programs that do the actual work. Their command line interfaces are |
| similar but not identical to the documented interface, and may change |
| without notice. |
| |
| @ignore |
| @c man begin SYNOPSIS |
| cpp [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}] |
| [@option{-I}@var{dir}@dots{}] [@option{-W}@var{warn}@dots{}] |
| [@option{-M}|@option{-MM}] [@option{-MG}] [@option{-MF} @var{filename}] |
| [@option{-MP}] [@option{-MQ} @var{target}@dots{}] [@option{-MT} @var{target}@dots{}] |
| [@option{-x} @var{language}] [@option{-std=}@var{standard}] |
| @var{infile} @var{outfile} |
| |
| Only the most useful options are listed here; see below for the remainder. |
| @c man end |
| @c man begin SEEALSO |
| gpl(7), gfdl(7), fsf-funding(7), |
| gcc(1), as(1), ld(1), and the Info entries for @file{cpp}, @file{gcc}, and |
| @file{binutils}. |
| @c man end |
| @end ignore |
| |
| @c man begin OPTIONS |
| The C preprocessor expects two file names as arguments, @var{infile} and |
| @var{outfile}. The preprocessor reads @var{infile} together with any |
| other files it specifies with @samp{#include}. All the output generated |
| by the combined input files is written in @var{outfile}. |
| |
| Either @var{infile} or @var{outfile} may be @option{-}, which as |
| @var{infile} means to read from standard input and as @var{outfile} |
| means to write to standard output. Also, if either file is omitted, it |
| means the same as if @option{-} had been specified for that file. |
| |
| Unless otherwise noted, or the option ends in @samp{=}, all options |
| which take an argument may have that argument appear either immediately |
| after the option, or with a space between option and argument: |
| @option{-Ifoo} and @option{-I foo} have the same effect. |
| |
| @cindex grouping options |
| @cindex options, grouping |
| Many options have multi-letter names; therefore multiple single-letter |
| options may @emph{not} be grouped: @option{-dM} is very different from |
| @w{@samp{-d -M}}. |
| |
| @cindex options |
| @table @gcctabopt |
| @item -D @var{name} |
| Predefine @var{name} as a macro, with definition @code{1}. |
| |
| @item -D @var{name}=@var{definition} |
| Predefine @var{name} as a macro, with definition @var{definition}. |
| There are no restrictions on the contents of @var{definition}, but if |
| you are invoking the preprocessor from a shell or shell-like program you |
| may need to use the shell's quoting syntax to protect characters such as |
| spaces that have a meaning in the shell syntax. If you use more than |
| one @option{-D} for the same @var{name}, the rightmost definition takes |
| effect. |
| |
| If you wish to define a function-like macro on the command line, write |
| its argument list with surrounding parentheses before the equals sign |
| (if any). Parentheses are meaningful to most shells, so you will need |
| to quote the option. With @command{sh} and @command{csh}, |
| @option{-D'@var{name}(@var{args@dots{}})=@var{definition}'} works. |
| |
| @item -U @var{name} |
| Cancel any previous definition of @var{name}, either built in or |
| provided with a @option{-D} option. |
| |
| All @option{-imacros @var{file}} and @option{-include @var{file}} options |
| are processed after all @option{-D} and @option{-U} options. |
| |
| @item -undef |
| Do not predefine any system-specific macros. The common predefined |
| macros remain defined. |
| |
| @item -I @var{dir} |
| Add the directory @var{dir} to the list of directories to be searched |
| for header files. @xref{Search Path}. Directories named by @option{-I} |
| are searched before the standard system include directories. |
| |
| It is dangerous to specify a standard system include directory in an |
| @option{-I} option. This defeats the special treatment of system |
| headers (@pxref{System Headers}). It can also defeat the repairs to |
| buggy system headers which GCC makes when it is installed. |
| |
| @item -o @var{file} |
| Write output to @var{file}. This is the same as specifying @var{file} |
| as the second non-option argument to @command{cpp}. @command{gcc} has a |
| different interpretation of a second non-option argument, so you must |
| use @option{-o} to specify the output file. |
| |
| @item -Wall |
| Turns on all optional warnings which are desirable for normal code. At |
| present this is @option{-Wcomment} and @option{-Wtrigraphs}. Note that |
| many of the preprocessor's warnings are on by default and have no |
| options to control them. |
| |
| @item -Wcomment |
| @itemx -Wcomments |
| Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*} |
| comment, or whenever a backslash-newline appears in a @samp{//} comment. |
| (Both forms have the same effect.) |
| |
| @item -Wtrigraphs |
| Warn if any trigraphs are encountered. This option used to take effect |
| only if @option{-trigraphs} was also specified, but now works |
| independently. Warnings are not given for trigraphs within comments, as |
| they do not affect the meaning of the program. |
| |
| @item -Wtraditional |
| Warn about certain constructs that behave differently in traditional and |
| ISO C@. Also warn about ISO C constructs that have no traditional C |
| equivalent, and problematic constructs which should be avoided. |
| @xref{Traditional Mode}. |
| |
| @item -Wimport |
| Warn the first time @samp{#import} is used. |
| |
| @item -Wundef |
| Warn whenever an identifier which is not a macro is encountered in an |
| @samp{#if} directive, outside of @samp{defined}. Such identifiers are |
| replaced with zero. |
| |
| @item -Werror |
| Make all warnings into hard errors. Source code which triggers warnings |
| will be rejected. |
| |
| @item -Wsystem-headers |
| Issue warnings for code in system headers. These are normally unhelpful |
| in finding bugs in your own code, therefore suppressed. If you are |
| responsible for the system library, you may want to see them. |
| |
| @item -w |
| Suppress all warnings, including those which GNU CPP issues by default. |
| |
| @item -pedantic |
| Issue all the mandatory diagnostics listed in the C standard. Some of |
| them are left out by default, since they trigger frequently on harmless |
| code. |
| |
| @item -pedantic-errors |
| Issue all the mandatory diagnostics, and make all mandatory diagnostics |
| into errors. This includes mandatory diagnostics that GCC issues |
| without @samp{-pedantic} but treats as warnings. |
| |
| @item -M |
| Instead of outputting the result of preprocessing, output a rule |
| suitable for @command{make} describing the dependencies of the main |
| source file. The preprocessor outputs one @command{make} rule containing |
| the object file name for that source file, a colon, and the names of all |
| the included files, including those coming from @option{-include} or |
| @option{-imacros} command line options. |
| |
| Unless specified explicitly (with @option{-MT} or @option{-MQ}), the |
| object file name consists of the basename of the source file with any |
| suffix replaced with object file suffix. If there are many included |
| files then the rule is split into several lines using @samp{\}-newline. |
| The rule has no commands. |
| |
| Passing @option{-M} to the driver implies @option{-E}. |
| |
| @item -MM |
| Like @option{-M} but do not mention header files that are found in |
| system header directories, nor header files that are included, |
| directly or indirectly, from such a header. |
| |
| This implies that the choice of angle brackets or double quotes in an |
| @samp{#include} directive does not in itself determine whether that |
| header will appear in @option{-MM} dependency output. This is a |
| slight change in semantics from GCC versions 3.0 and earlier. |
| |
| @item -MF @var{file} |
| @anchor{-MF} |
| When used with @option{-M} or @option{-MM}, specifies a |
| file to write the dependencies to. If no @option{-MF} switch is given |
| the preprocessor sends the rules to the same place it would have sent |
| preprocessed output. |
| |
| When used with the driver options @option{-MD} or @option{-MMD}, |
| @option{-MF} overrides the default dependency output file. |
| |
| @item -MG |
| When used with @option{-M} or @option{-MM}, @option{-MG} says to treat missing |
| header files as generated files and assume they live in the same |
| directory as the source file. It suppresses preprocessed output, as a |
| missing header file is ordinarily an error. |
| |
| This feature is used in automatic updating of makefiles. |
| |
| @item -MP |
| This option instructs CPP to add a phony target for each dependency |
| other than the main file, causing each to depend on nothing. These |
| dummy rules work around errors @command{make} gives if you remove header |
| files without updating the @file{Makefile} to match. |
| |
| This is typical output: |
| |
| @example |
| test.o: test.c test.h |
| |
| test.h: |
| @end example |
| |
| @item -MT @var{target} |
| |
| Change the target of the rule emitted by dependency generation. By |
| default CPP takes the name of the main input file, including any path, |
| deletes any file suffix such as @samp{.c}, and appends the platform's |
| usual object suffix. The result is the target. |
| |
| An @option{-MT} option will set the target to be exactly the string you |
| specify. If you want multiple targets, you can specify them as a single |
| argument to @option{-MT}, or use multiple @option{-MT} options. |
| |
| For example, @option{@w{-MT '$(objpfx)foo.o'}} might give |
| |
| @example |
| $(objpfx)foo.o: foo.c |
| @end example |
| |
| @item -MQ @var{target} |
| |
| Same as @option{-MT}, but it quotes any characters which are special to |
| Make. @option{@w{-MQ '$(objpfx)foo.o'}} gives |
| |
| @example |
| $$(objpfx)foo.o: foo.c |
| @end example |
| |
| The default target is automatically quoted, as if it were given with |
| @option{-MQ}. |
| |
| @item -MD |
| @option{-MD} is equivalent to @option{-M -MF @var{file}}, except that |
| @option{-E} is not implied. The driver determines @var{file} based on |
| whether an @option{-o} option is given. If it is, the driver uses its |
| argument but with a suffix of @file{.d}, otherwise it take the |
| basename of the input file and applies a @file{.d} suffix. |
| |
| If @option{-MD} is used in conjunction with @option{-E}, any |
| @option{-o} switch is understood to specify the dependency output file |
| (but @pxref{-MF}), but if used without @option{-E}, each @option{-o} |
| is understood to specify a target object file. |
| |
| Since @option{-E} is not implied, @option{-MD} can be used to generate |
| a dependency output file as a side-effect of the compilation process. |
| |
| @item -MMD |
| Like @option{-MD} except mention only user header files, not system |
| -header files. |
| |
| @item -x c |
| @itemx -x c++ |
| @itemx -x objective-c |
| @itemx -x assembler-with-cpp |
| Specify the source language: C, C++, Objective-C, or assembly. This has |
| nothing to do with standards conformance or extensions; it merely |
| selects which base syntax to expect. If you give none of these options, |
| cpp will deduce the language from the extension of the source file: |
| @samp{.c}, @samp{.cc}, @samp{.m}, or @samp{.S}. Some other common |
| extensions for C++ and assembly are also recognized. If cpp does not |
| recognize the extension, it will treat the file as C; this is the most |
| generic mode. |
| |
| @strong{Note:} Previous versions of cpp accepted a @option{-lang} option |
| which selected both the language and the standards conformance level. |
| This option has been removed, because it conflicts with the @option{-l} |
| option. |
| |
| @item -std=@var{standard} |
| @itemx -ansi |
| Specify the standard to which the code should conform. Currently cpp |
| only knows about the standards for C; other language standards will be |
| added in the future. |
| |
| @var{standard} |
| may be one of: |
| @table @code |
| @item iso9899:1990 |
| @itemx c89 |
| The ISO C standard from 1990. @samp{c89} is the customary shorthand for |
| this version of the standard. |
| |
| The @option{-ansi} option is equivalent to @option{-std=c89}. |
| |
| @item iso9899:199409 |
| The 1990 C standard, as amended in 1994. |
| |
| @item iso9899:1999 |
| @itemx c99 |
| @itemx iso9899:199x |
| @itemx c9x |
| The revised ISO C standard, published in December 1999. Before |
| publication, this was known as C9X@. |
| |
| @item gnu89 |
| The 1990 C standard plus GNU extensions. This is the default. |
| |
| @item gnu99 |
| @itemx gnu9x |
| The 1999 C standard plus GNU extensions. |
| @end table |
| |
| @item -I- |
| Split the include path. Any directories specified with @option{-I} |
| options before @option{-I-} are searched only for headers requested with |
| @code{@w{#include "@var{file}"}}; they are not searched for |
| @code{@w{#include <@var{file}>}}. If additional directories are |
| specified with @option{-I} options after the @option{-I-}, those |
| directories are searched for all @samp{#include} directives. |
| |
| In addition, @option{-I-} inhibits the use of the directory of the current |
| file directory as the first search directory for @code{@w{#include |
| "@var{file}"}}. @xref{Search Path}. |
| |
| @item -nostdinc |
| Do not search the standard system directories for header files. |
| Only the directories you have specified with @option{-I} options |
| (and the directory of the current file, if appropriate) are searched. |
| |
| @item -nostdinc++ |
| Do not search for header files in the C++-specific standard directories, |
| but do still search the other standard directories. (This option is |
| used when building the C++ library.) |
| |
| @item -include @var{file} |
| |
| Process @var{file} as if @code{#include "file"} appeared as the first |
| line of the primary source file. However, the first directory searched |
| for @var{file} is the preprocessor's working directory @emph{instead of} |
| the directory containing the main source file. If not found there, it |
| is searched for in the remainder of the @code{#include "@dots{}"} search |
| chain as normal. |
| |
| If multiple @option{-include} options are given, the files are included |
| in the order they appear on the command line. |
| |
| @item -imacros @var{file} |
| |
| Exactly like @option{-include}, except that any output produced by |
| scanning @var{file} is thrown away. Macros it defines remain defined. |
| This allows you to acquire all the macros from a header without also |
| processing its declarations. |
| |
| All files specified by @option{-imacros} are processed before all files |
| specified by @option{-include}. |
| |
| @item -idirafter @var{dir} |
| Search @var{dir} for header files, but do it @emph{after} all |
| directories specified with @option{-I} and the standard system directories |
| have been exhausted. @var{dir} is treated as a system include directory. |
| |
| @item -iprefix @var{prefix} |
| Specify @var{prefix} as the prefix for subsequent @option{-iwithprefix} |
| options. If the prefix represents a directory, you should include the |
| final @samp{/}. |
| |
| @item -iwithprefix @var{dir} |
| @itemx -iwithprefixbefore @var{dir} |
| |
| Append @var{dir} to the prefix specified previously with |
| @option{-iprefix}, and add the resulting directory to the include search |
| path. @option{-iwithprefixbefore} puts it in the same place @option{-I} |
| would; @option{-iwithprefix} puts it where @option{-idirafter} would. |
| |
| Use of these options is discouraged. |
| |
| @item -isystem @var{dir} |
| Search @var{dir} for header files, after all directories specified by |
| @option{-I} but before the standard system directories. Mark it |
| as a system directory, so that it gets the same special treatment as |
| is applied to the standard system directories. @xref{System Headers}. |
| |
| @item -fpreprocessed |
| Indicate to the preprocessor that the input file has already been |
| preprocessed. This suppresses things like macro expansion, trigraph |
| conversion, escaped newline splicing, and processing of most directives. |
| The preprocessor still recognizes and removes comments, so that you can |
| pass a file preprocessed with @option{-C} to the compiler without |
| problems. In this mode the integrated preprocessor is little more than |
| a tokenizer for the front ends. |
| |
| @option{-fpreprocessed} is implicit if the input file has one of the |
| extensions @samp{.i}, @samp{.ii} or @samp{.mi}. These are the |
| extensions that GCC uses for preprocessed files created by |
| @option{-save-temps}. |
| |
| @item -ftabstop=@var{width} |
| Set the distance between tab stops. This helps the preprocessor report |
| correct column numbers in warnings or errors, even if tabs appear on the |
| line. If the value is less than 1 or greater than 100, the option is |
| ignored. The default is 8. |
| |
| @item -fno-show-column |
| Do not print column numbers in diagnostics. This may be necessary if |
| diagnostics are being scanned by a program that does not understand the |
| column numbers, such as @command{dejagnu}. |
| |
| @item -A @var{predicate}=@var{answer} |
| Make an assertion with the predicate @var{predicate} and answer |
| @var{answer}. This form is preferred to the older form @option{-A |
| @var{predicate}(@var{answer})}, which is still supported, because |
| it does not use shell special characters. @xref{Assertions}. |
| |
| @item -A -@var{predicate}=@var{answer} |
| Cancel an assertion with the predicate @var{predicate} and answer |
| @var{answer}. |
| |
| @item -A- |
| Cancel all predefined assertions and all assertions preceding it on |
| the command line. Also, undefine all predefined macros and all |
| macros preceding it on the command line. (This is a historical wart and |
| may change in the future.) |
| |
| @item -dCHARS |
| @var{CHARS} is a sequence of one or more of the following characters, |
| and must not be preceded by a space. Other characters are interpreted |
| by the compiler proper, or reserved for future versions of GCC, and so |
| are silently ignored. If you specify characters whose behavior |
| conflicts, the result is undefined. |
| |
| @table @samp |
| @item M |
| Instead of the normal output, generate a list of @samp{#define} |
| directives for all the macros defined during the execution of the |
| preprocessor, including predefined macros. This gives you a way of |
| finding out what is predefined in your version of the preprocessor. |
| Assuming you have no file @file{foo.h}, the command |
| |
| @example |
| touch foo.h; cpp -dM foo.h |
| @end example |
| |
| @noindent |
| will show all the predefined macros. |
| |
| @item D |
| Like @samp{M} except in two respects: it does @emph{not} include the |
| predefined macros, and it outputs @emph{both} the @samp{#define} |
| directives and the result of preprocessing. Both kinds of output go to |
| the standard output file. |
| |
| @item N |
| Like @samp{D}, but emit only the macro names, not their expansions. |
| |
| @item I |
| Output @samp{#include} directives in addition to the result of |
| preprocessing. |
| @end table |
| |
| @item -P |
| Inhibit generation of linemarkers in the output from the preprocessor. |
| This might be useful when running the preprocessor on something that is |
| not C code, and will be sent to a program which might be confused by the |
| linemarkers. @xref{Preprocessor Output}. |
| |
| @item -C |
| Do not discard comments. All comments are passed through to the output |
| file, except for comments in processed directives, which are deleted |
| along with the directive. |
| |
| You should be prepared for side effects when using @option{-C}; it |
| causes the preprocessor to treat comments as tokens in their own right. |
| For example, comments appearing at the start of what would be a |
| directive line have the effect of turning that line into an ordinary |
| source line, since the first token on the line is no longer a @samp{#}. |
| |
| @item -gcc |
| Define the macros @sc{__gnuc__}, @sc{__gnuc_minor__} and |
| @sc{__gnuc_patchlevel__}. These are defined automatically when you use |
| @command{gcc -E}; you can turn them off in that case with |
| @option{-no-gcc}. |
| |
| @item -traditional |
| Try to imitate the behavior of the old-fashioned C preprocessor, as |
| opposed to the behavior specified by ISO C@. @xref{Traditional Mode}. |
| |
| @item -trigraphs |
| Process trigraph sequences. @xref{Initial processing}. |
| |
| @item -remap |
| Enable special code to work around file systems which only permit very |
| short file names, such as MS-DOS@. |
| |
| @item -$ |
| Forbid the use of @samp{$} in identifiers. The C standard allows |
| implementations to define extra characters that can appear in |
| identifiers. By default GNU CPP permits @samp{$}, a common extension. |
| |
| @item -h |
| @itemx --help |
| @itemx --target-help |
| Print text describing all the command line options instead of |
| preprocessing anything. |
| |
| @item -v |
| Verbose mode. Print out GNU CPP's version number at the beginning of |
| execution, and report the final form of the include path. |
| |
| @item -H |
| Print the name of each header file used, in addition to other normal |
| activities. Each name is indented to show how deep in the |
| @samp{#include} stack it is. |
| |
| @item -version |
| @itemx --version |
| Print out GNU CPP's version number. With one dash, proceed to |
| preprocess as normal. With two dashes, exit immediately. |
| @end table |
| @c man end |
| |
| @include fdl.texi |
| |
| @page |
| @node Index of Directives |
| @unnumbered Index of Directives |
| @printindex fn |
| |
| @node Concept Index |
| @unnumbered Concept Index |
| @printindex cp |
| |
| @bye |