From 37aa8acf60b5c7701cab3d702d2900ca69af7853 Mon Sep 17 00:00:00 2001 From: "R. Steve McKown" Date: Thu, 20 May 2010 16:35:48 -0600 Subject: [PATCH] Remove build products in upstream tree. --- gcc/doc/cpp.info | 5350 ----- gcc/doc/cppinternals.info | 1036 - gcc/doc/gcc.info | 44028 ------------------------------------ gcc/doc/gccinstall.info | 4234 ---- gcc/doc/gccint.info | 43950 ----------------------------------- gcc/doc/gcj.info | 3632 --- gcc/po/be.gmo | Bin 10634 -> 0 bytes gcc/po/da.gmo | Bin 155096 -> 0 bytes gcc/po/de.gmo | Bin 774320 -> 0 bytes gcc/po/el.gmo | Bin 12274 -> 0 bytes gcc/po/es.gmo | Bin 894977 -> 0 bytes gcc/po/fi.gmo | Bin 122015 -> 0 bytes gcc/po/fr.gmo | Bin 214170 -> 0 bytes gcc/po/id.gmo | Bin 873872 -> 0 bytes gcc/po/ja.gmo | Bin 84528 -> 0 bytes gcc/po/nl.gmo | Bin 87281 -> 0 bytes gcc/po/ru.gmo | Bin 618971 -> 0 bytes gcc/po/sr.gmo | Bin 800175 -> 0 bytes gcc/po/sv.gmo | Bin 845967 -> 0 bytes gcc/po/tr.gmo | Bin 570652 -> 0 bytes gcc/po/zh_CN.gmo | Bin 671748 -> 0 bytes gcc/po/zh_TW.gmo | Bin 474790 -> 0 bytes gmp/doc/gmp.info | 177 - libcpp/po/be.gmo | Bin 1092 -> 0 bytes libcpp/po/ca.gmo | Bin 18557 -> 0 bytes libcpp/po/da.gmo | Bin 14744 -> 0 bytes libcpp/po/de.gmo | Bin 20829 -> 0 bytes libcpp/po/el.gmo | Bin 784 -> 0 bytes libcpp/po/es.gmo | Bin 21912 -> 0 bytes libcpp/po/fr.gmo | Bin 21824 -> 0 bytes libcpp/po/id.gmo | Bin 21442 -> 0 bytes libcpp/po/ja.gmo | Bin 9177 -> 0 bytes libcpp/po/nl.gmo | Bin 21608 -> 0 bytes libcpp/po/sv.gmo | Bin 20675 -> 0 bytes libcpp/po/tr.gmo | Bin 19818 -> 0 bytes libcpp/po/uk.gmo | Bin 25641 -> 0 bytes libcpp/po/vi.gmo | Bin 25033 -> 0 bytes libcpp/po/zh_CN.gmo | Bin 19800 -> 0 bytes libcpp/po/zh_TW.gmo | Bin 17828 -> 0 bytes libgomp/libgomp.info | 2455 -- mpfr/mpfr.info | 3570 --- 41 files changed, 108432 deletions(-) delete mode 100644 gcc/doc/cpp.info delete mode 100644 gcc/doc/cppinternals.info delete mode 100644 gcc/doc/gcc.info delete mode 100644 gcc/doc/gccinstall.info delete mode 100644 gcc/doc/gccint.info delete mode 100644 gcc/doc/gcj.info delete mode 100644 gcc/po/be.gmo delete mode 100644 gcc/po/da.gmo delete mode 100644 gcc/po/de.gmo delete mode 100644 gcc/po/el.gmo delete mode 100644 gcc/po/es.gmo delete mode 100644 gcc/po/fi.gmo delete mode 100644 gcc/po/fr.gmo delete mode 100644 gcc/po/id.gmo delete mode 100644 gcc/po/ja.gmo delete mode 100644 gcc/po/nl.gmo delete mode 100644 gcc/po/ru.gmo delete mode 100644 gcc/po/sr.gmo delete mode 100644 gcc/po/sv.gmo delete mode 100644 gcc/po/tr.gmo delete mode 100644 gcc/po/zh_CN.gmo delete mode 100644 gcc/po/zh_TW.gmo delete mode 100644 gmp/doc/gmp.info delete mode 100644 libcpp/po/be.gmo delete mode 100644 libcpp/po/ca.gmo delete mode 100644 libcpp/po/da.gmo delete mode 100644 libcpp/po/de.gmo delete mode 100644 libcpp/po/el.gmo delete mode 100644 libcpp/po/es.gmo delete mode 100644 libcpp/po/fr.gmo delete mode 100644 libcpp/po/id.gmo delete mode 100644 libcpp/po/ja.gmo delete mode 100644 libcpp/po/nl.gmo delete mode 100644 libcpp/po/sv.gmo delete mode 100644 libcpp/po/tr.gmo delete mode 100644 libcpp/po/uk.gmo delete mode 100644 libcpp/po/vi.gmo delete mode 100644 libcpp/po/zh_CN.gmo delete mode 100644 libcpp/po/zh_TW.gmo delete mode 100644 libgomp/libgomp.info delete mode 100644 mpfr/mpfr.info diff --git a/gcc/doc/cpp.info b/gcc/doc/cpp.info deleted file mode 100644 index 93798873..00000000 --- a/gcc/doc/cpp.info +++ /dev/null @@ -1,5350 +0,0 @@ -This is doc/cpp.info, produced by makeinfo version 4.13 from -/d/gcc-4.4.3/gcc-4.4.3/gcc/doc/cpp.texi. - -Copyright (C) 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, 1997, -1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 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.2 or -any later version published by the Free Software Foundation. A copy of -the license is included in the section entitled "GNU Free Documentation -License". - - This manual contains no Invariant Sections. The Front-Cover Texts -are (a) (see below), and the Back-Cover Texts are (b) (see below). - - (a) The FSF's Front-Cover Text is: - - A GNU Manual - - (b) The FSF's Back-Cover Text is: - - You have freedom to copy and modify this GNU Manual, like GNU -software. Copies published by the Free Software Foundation raise -funds for GNU development. - -INFO-DIR-SECTION Software development -START-INFO-DIR-ENTRY -* Cpp: (cpp). The GNU C preprocessor. -END-INFO-DIR-ENTRY - - -File: cpp.info, Node: Top, Next: Overview, Up: (dir) - -The C Preprocessor -****************** - -The C preprocessor implements the macro language used to transform C, -C++, and Objective-C programs before they are compiled. It can also be -useful on its own. - -* Menu: - -* Overview:: -* Header Files:: -* Macros:: -* Conditionals:: -* Diagnostics:: -* Line Control:: -* Pragmas:: -* Other Directives:: -* Preprocessor Output:: -* Traditional Mode:: -* Implementation Details:: -* Invocation:: -* Environment Variables:: -* GNU Free Documentation License:: -* Index of Directives:: -* Option Index:: -* Concept Index:: - - --- The Detailed Node Listing --- - -Overview - -* Character sets:: -* Initial processing:: -* Tokenization:: -* The preprocessing language:: - -Header Files - -* Include Syntax:: -* Include Operation:: -* Search Path:: -* Once-Only Headers:: -* Alternatives to Wrapper #ifndef:: -* 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 - -* Obsolete Features:: - - Copyright (C) 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, 1997, -1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 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.2 or -any later version published by the Free Software Foundation. A copy of -the license is included in the section entitled "GNU Free Documentation -License". - - This manual contains no Invariant Sections. The Front-Cover Texts -are (a) (see below), and the Back-Cover Texts are (b) (see below). - - (a) The FSF's Front-Cover Text is: - - A GNU Manual - - (b) The FSF's Back-Cover Text is: - - You have freedom to copy and modify this GNU Manual, like GNU -software. Copies published by the Free Software Foundation raise -funds for GNU development. - - -File: cpp.info, Node: Overview, Next: Header Files, Prev: Top, Up: Top - -1 Overview -********** - -The C preprocessor, often known as "cpp", is a "macro processor" that -is used automatically by the C compiler to transform your program -before compilation. It is called a macro processor because it allows -you to define "macros", which are brief abbreviations for longer -constructs. - - The C preprocessor is intended to be used only with C, C++, and -Objective-C source code. In the past, it has been abused as a general -text processor. It will choke on input which does not obey C's lexical -rules. For example, apostrophes will be interpreted as the beginning of -character constants, and cause errors. Also, you cannot rely on it -preserving characteristics of the input which are not significant to -C-family languages. If a Makefile is preprocessed, all the hard tabs -will be removed, and the Makefile will not work. - - Having said that, you can often get away with using cpp on things -which are not C. Other Algol-ish programming languages are often safe -(Pascal, Ada, etc.) So is assembly, with caution. `-traditional-cpp' -mode preserves more white space, and is otherwise more permissive. Many -of the problems can be avoided by writing C or C++ style comments -instead of native language comments, and keeping macros simple. - - Wherever possible, you should use a preprocessor geared to the -language you are writing in. Modern versions of the GNU assembler have -macro facilities. Most high level programming languages have their own -conditional compilation and inclusion mechanism. If all else fails, -try a true general text processor, such as GNU M4. - - C preprocessors vary in some details. This manual discusses the GNU -C preprocessor, which provides a small superset of the features of ISO -Standard C. In its default mode, the GNU C preprocessor does not do a -few things required by the standard. These are features which are -rarely, if ever, used, and may cause surprising changes to the meaning -of a program which does not expect them. To get strict ISO Standard C, -you should use the `-std=c89' or `-std=c99' options, depending on which -version of the standard you want. To get all the mandatory -diagnostics, you must also use `-pedantic'. *Note Invocation::. - - This manual describes the behavior of the ISO preprocessor. To -minimize gratuitous differences, where the ISO preprocessor's behavior -does not conflict with traditional semantics, the traditional -preprocessor should behave the same way. The various differences that -do exist are detailed in the section *note Traditional Mode::. - - For clarity, unless noted otherwise, references to `CPP' in this -manual refer to GNU CPP. - -* Menu: - -* Character sets:: -* Initial processing:: -* Tokenization:: -* The preprocessing language:: - - -File: cpp.info, Node: Character sets, Next: Initial processing, Up: Overview - -1.1 Character sets -================== - -Source code character set processing in C and related languages is -rather complicated. The C standard discusses two character sets, but -there are really at least four. - - The files input to CPP might be in any character set at all. CPP's -very first action, before it even looks for line boundaries, is to -convert the file into the character set it uses for internal -processing. That set is what the C standard calls the "source" -character set. It must be isomorphic with ISO 10646, also known as -Unicode. CPP uses the UTF-8 encoding of Unicode. - - The character sets of the input files are specified using the -`-finput-charset=' option. - - All preprocessing work (the subject of the rest of this manual) is -carried out in the source character set. If you request textual output -from the preprocessor with the `-E' option, it will be in UTF-8. - - After preprocessing is complete, string and character constants are -converted again, into the "execution" character set. This character -set is under control of the user; the default is UTF-8, matching the -source character set. Wide string and character constants have their -own character set, which is not called out specifically in the -standard. Again, it is under control of the user. The default is -UTF-16 or UTF-32, whichever fits in the target's `wchar_t' type, in the -target machine's byte order.(1) Octal and hexadecimal escape sequences -do not undergo conversion; '\x12' has the value 0x12 regardless of the -currently selected execution character set. All other escapes are -replaced by the character in the source character set that they -represent, then converted to the execution character set, just like -unescaped characters. - - Unless the experimental `-fextended-identifiers' option is used, GCC -does not permit the use of characters outside the ASCII range, nor `\u' -and `\U' escapes, in identifiers. Even with that option, characters -outside the ASCII range can only be specified with the `\u' and `\U' -escapes, not used directly in identifiers. - - ---------- Footnotes ---------- - - (1) UTF-16 does not meet the requirements of the C standard for a -wide character set, but the choice of 16-bit `wchar_t' is enshrined in -some system ABIs so we cannot fix this. - - -File: cpp.info, Node: Initial processing, Next: Tokenization, Prev: Character sets, Up: Overview - -1.2 Initial processing -====================== - -The preprocessor performs a series of textual transformations on its -input. These happen before all other processing. Conceptually, they -happen in a rigid order, and the entire file is run through each -transformation before the next one begins. CPP actually does them all -at once, for performance reasons. These transformations correspond -roughly to the first three "phases of translation" described in the C -standard. - - 1. The input file is read into memory and broken into lines. - - Different systems use different conventions to indicate the end of - a line. GCC accepts the ASCII control sequences `LF', `CR LF' and - `CR' as end-of-line markers. These are the canonical sequences - used by Unix, DOS and VMS, and the classic Mac OS (before OSX) - respectively. You may therefore safely copy source code written - on any of those systems to a different one and use it without - conversion. (GCC may lose track of the current line number if a - file doesn't consistently use one convention, as sometimes happens - when it is edited on computers with different conventions that - share a network file system.) - - If the last line of any input file lacks an end-of-line marker, - the end of the file is considered to implicitly supply one. The C - standard says that this condition provokes undefined behavior, so - GCC will emit a warning message. - - 2. If trigraphs are enabled, they are replaced by their corresponding - single characters. By default GCC ignores trigraphs, but if you - request a strictly conforming mode with the `-std' option, or you - specify the `-trigraphs' option, then it converts them. - - These are nine three-character sequences, all starting with `??', - that are defined by ISO C to stand for single characters. They - permit obsolete systems that lack some of C's punctuation to use - C. For example, `??/' stands for `\', so '??/n' is a character - constant for a newline. - - Trigraphs are not popular and many compilers implement them - incorrectly. Portable code should not rely on trigraphs being - either converted or ignored. With `-Wtrigraphs' GCC will warn you - when a trigraph may change the meaning of your program if it were - converted. *Note Wtrigraphs::. - - In a string constant, you can prevent a sequence of question marks - from being confused with a trigraph by inserting a backslash - between the question marks, or by separating the string literal at - the trigraph and making use of string literal concatenation. - "(??\?)" is the string `(???)', not `(?]'. Traditional C - compilers do not recognize these idioms. - - The nine trigraphs and their replacements are - - Trigraph: ??( ??) ??< ??> ??= ??/ ??' ??! ??- - Replacement: [ ] { } # \ ^ | ~ - - 3. Continued lines are merged into one long line. - - A continued line is a line which ends with a backslash, `\'. The - backslash is removed and the following line is joined with the - current one. No space is inserted, so you may split a line - anywhere, even in the middle of a word. (It is generally more - readable to split lines only at white space.) - - The trailing backslash on a continued line is commonly referred to - as a "backslash-newline". - - If there is white space between a backslash and the end of a line, - that is still a continued line. However, as this is usually the - result of an editing mistake, and many compilers will not accept - it as a continued line, GCC will warn you about it. - - 4. All comments are replaced with single spaces. - - There are two kinds of comments. "Block comments" begin with `/*' - and continue until the next `*/'. Block comments do not nest: - - /* this is /* one comment */ text outside comment - - "Line comments" begin with `//' and continue to the end of the - current line. Line comments do not nest either, but it does not - matter, because they would end in the same place anyway. - - // this is // one comment - text outside comment - - It is safe to put line comments inside block comments, or vice versa. - - /* block comment - // contains line comment - yet more comment - */ outside comment - - // line comment /* contains block comment */ - - But beware of commenting out one end of a block comment with a line -comment. - - // l.c. /* block comment begins - oops! this isn't a comment anymore */ - - Comments are not recognized within string literals. "/* blah */" is -the string constant `/* blah */', not an empty string. - - Line comments are not in the 1989 edition of the C standard, but they -are recognized by GCC as an extension. In C++ and in the 1999 edition -of the C standard, they are an official part of the language. - - Since these transformations happen before all other processing, you -can split a line mechanically with backslash-newline anywhere. You can -comment out the end of a line. You can continue a line comment onto the -next line with backslash-newline. You can even split `/*', `*/', and -`//' onto multiple lines with backslash-newline. For example: - - /\ - * - */ # /* - */ defi\ - ne FO\ - O 10\ - 20 - -is equivalent to `#define FOO 1020'. All these tricks are extremely -confusing and should not be used in code intended to be readable. - - There is no way to prevent a backslash at the end of a line from -being interpreted as a backslash-newline. This cannot affect any -correct program, however. - - -File: cpp.info, Node: Tokenization, Next: The preprocessing language, Prev: Initial processing, Up: Overview - -1.3 Tokenization -================ - -After the textual transformations are finished, the input file is -converted into a sequence of "preprocessing tokens". These mostly -correspond to the syntactic tokens used by the C compiler, but there are -a few differences. White space separates tokens; it is not itself a -token of any kind. Tokens do not have to be separated by white space, -but it is often necessary to avoid ambiguities. - - When faced with a sequence of characters that has more than one -possible tokenization, the preprocessor is greedy. It always makes -each token, starting from the left, as big as possible before moving on -to the next token. For instance, `a+++++b' is interpreted as -`a ++ ++ + b', not as `a ++ + ++ b', even though the latter -tokenization could be part of a valid C program and the former could -not. - - Once the input file is broken into tokens, the token boundaries never -change, except when the `##' preprocessing operator is used to paste -tokens together. *Note Concatenation::. For example, - - #define foo() bar - foo()baz - ==> bar baz - _not_ - ==> barbaz - - The compiler does not re-tokenize the preprocessor's output. Each -preprocessing token becomes one compiler token. - - Preprocessing tokens fall into five broad classes: identifiers, -preprocessing numbers, string literals, punctuators, and other. An -"identifier" is the same as an identifier in C: any sequence of -letters, digits, or underscores, which begins with a letter or -underscore. Keywords of C have no significance to the preprocessor; -they are ordinary identifiers. You can define a macro whose name is a -keyword, for instance. The only identifier which can be considered a -preprocessing keyword is `defined'. *Note Defined::. - - This is mostly true of other languages which use the C preprocessor. -However, a few of the keywords of C++ are significant even in the -preprocessor. *Note C++ Named Operators::. - - In the 1999 C standard, identifiers may contain letters which are not -part of the "basic source character set", at the implementation's -discretion (such as accented Latin letters, Greek letters, or Chinese -ideograms). This may be done with an extended character set, or the -`\u' and `\U' escape sequences. The implementation of this feature in -GCC is experimental; such characters are only accepted in the `\u' and -`\U' forms and only if `-fextended-identifiers' is used. - - As an extension, GCC treats `$' as a letter. This is for -compatibility with some systems, such as VMS, where `$' is commonly -used in system-defined function and object names. `$' is not a letter -in strictly conforming mode, or if you specify the `-$' option. *Note -Invocation::. - - A "preprocessing number" has a rather bizarre definition. The -category includes all the normal integer and floating point constants -one expects of C, but also a number of other things one might not -initially recognize as a number. Formally, preprocessing numbers begin -with an optional period, a required decimal digit, and then continue -with any sequence of letters, digits, underscores, periods, and -exponents. Exponents are the two-character sequences `e+', `e-', `E+', -`E-', `p+', `p-', `P+', and `P-'. (The exponents that begin with `p' -or `P' are new to C99. They are used for hexadecimal floating-point -constants.) - - The purpose of this unusual definition is to isolate the preprocessor -from the full complexity of numeric constants. It does not have to -distinguish between lexically valid and invalid floating-point numbers, -which is complicated. The definition also permits you to split an -identifier at any position and get exactly two tokens, which can then be -pasted back together with the `##' operator. - - It's possible for preprocessing numbers to cause programs to be -misinterpreted. For example, `0xE+12' is a preprocessing number which -does not translate to any valid numeric constant, therefore a syntax -error. It does not mean `0xE + 12', which is what you might have -intended. - - "String literals" are string constants, character constants, and -header file names (the argument of `#include').(1) String constants -and character constants are straightforward: "..." or '...'. In either -case embedded quotes should be escaped with a backslash: '\'' is the -character constant for `''. There is no limit on the length of a -character constant, but the value of a character constant that contains -more than one character is implementation-defined. *Note -Implementation Details::. - - Header file names either look like string constants, "...", or are -written with angle brackets instead, <...>. In either case, backslash -is an ordinary character. There is no way to escape the closing quote -or angle bracket. The preprocessor looks for the header file in -different places depending on which form you use. *Note Include -Operation::. - - No string literal may extend past the end of a line. Older versions -of GCC accepted multi-line string constants. You may use continued -lines instead, or string constant concatenation. *Note Differences -from previous versions::. - - "Punctuators" are all the usual bits of punctuation which are -meaningful to C and C++. All but three of the punctuation characters in -ASCII are C punctuators. The exceptions are `@', `$', and ``'. In -addition, all the two- and three-character operators are punctuators. -There are also six "digraphs", which the C++ standard calls -"alternative tokens", which are merely alternate ways to spell other -punctuators. This is a second attempt to work around missing -punctuation in obsolete systems. It has no negative side effects, -unlike trigraphs, but does not cover as much ground. The digraphs and -their corresponding normal punctuators are: - - Digraph: <% %> <: :> %: %:%: - Punctuator: { } [ ] # ## - - Any other single character is considered "other". It is passed on to -the preprocessor's output unmolested. The C compiler will almost -certainly reject source code containing "other" tokens. In ASCII, the -only other characters are `@', `$', ``', and control characters other -than NUL (all bits zero). (Note that `$' is normally considered a -letter.) All characters with the high bit set (numeric range -0x7F-0xFF) are also "other" in the present implementation. This will -change when proper support for international character sets is added to -GCC. - - NUL is a special case because of the high probability that its -appearance is accidental, and because it may be invisible to the user -(many terminals do not display NUL at all). Within comments, NULs are -silently ignored, just as any other character would be. In running -text, NUL is considered white space. For example, these two directives -have the same meaning. - - #define X^@1 - #define X 1 - -(where `^@' is ASCII NUL). Within string or character constants, NULs -are preserved. In the latter two cases the preprocessor emits a -warning message. - - ---------- Footnotes ---------- - - (1) The C standard uses the term "string literal" to refer only to -what we are calling "string constants". - - -File: cpp.info, Node: The preprocessing language, Prev: Tokenization, Up: Overview - -1.4 The preprocessing language -============================== - -After tokenization, the stream of tokens may simply be passed straight -to the compiler's parser. However, if it contains any operations in the -"preprocessing language", it will be transformed first. This stage -corresponds roughly to the standard's "translation phase 4" and is what -most people think of as the preprocessor's job. - - The preprocessing language consists of "directives" to be executed -and "macros" to be expanded. Its primary capabilities are: - - * Inclusion of header files. These are files of declarations that - can be substituted into your program. - - * Macro expansion. You can define "macros", which are abbreviations - for arbitrary fragments of C code. The preprocessor will replace - the macros with their definitions throughout the program. Some - macros are automatically defined for you. - - * Conditional compilation. You can include or exclude parts of the - program according to various conditions. - - * Line control. If you use a program to combine or rearrange source - files into an intermediate file which is then compiled, you can - use line control to inform the compiler where each source line - originally came from. - - * Diagnostics. You can detect problems at compile time and issue - errors or warnings. - - There are a few more, less useful, features. - - Except for expansion of predefined macros, all these operations are -triggered with "preprocessing directives". Preprocessing directives -are lines in your program that start with `#'. Whitespace is allowed -before and after the `#'. The `#' is followed by an identifier, the -"directive name". It specifies the operation to perform. Directives -are commonly referred to as `#NAME' where NAME is the directive name. -For example, `#define' is the directive that defines a macro. - - The `#' which begins a directive cannot come from a macro expansion. -Also, the directive name is not macro expanded. Thus, if `foo' is -defined as a macro expanding to `define', that does not make `#foo' a -valid preprocessing directive. - - The set of valid directive names is fixed. Programs cannot define -new preprocessing directives. - - Some directives require arguments; these make up the rest of the -directive line and must be separated from the directive name by -whitespace. For example, `#define' must be followed by a macro name -and the intended expansion of the macro. - - A preprocessing directive cannot cover more than one line. The line -may, however, be continued with backslash-newline, or by a block comment -which extends past the end of the line. In either case, when the -directive is processed, the continuations have already been merged with -the first line to make one long line. - - -File: cpp.info, Node: Header Files, Next: Macros, Prev: Overview, Up: Top - -2 Header Files -************** - -A header file is a file containing C declarations and macro definitions -(*note Macros::) to be shared between several source files. You request -the use of a header file in your program by "including" it, with the C -preprocessing directive `#include'. - - Header files serve two purposes. - - * System header files declare the interfaces to parts of the - operating system. You include them in your program to supply the - definitions and declarations you need to invoke system calls and - libraries. - - * Your own header files contain declarations for interfaces between - the source files of your program. Each time you have a group of - related declarations and macro definitions all or most of which - are needed in several different source files, it is a good idea to - create a header file for them. - - Including a header file produces the same results as copying the -header file into each source file that needs it. Such copying would be -time-consuming and error-prone. With a header file, the related -declarations appear in only one place. If they need to be changed, they -can be changed in one place, and programs that include the header file -will automatically use the new version when next recompiled. The header -file eliminates the labor of finding and changing all the copies as well -as the risk that a failure to find one copy will result in -inconsistencies within a program. - - In C, the usual convention is to give header files names that end -with `.h'. It is most portable to use only letters, digits, dashes, and -underscores in header file names, and at most one dot. - -* Menu: - -* Include Syntax:: -* Include Operation:: -* Search Path:: -* Once-Only Headers:: -* Alternatives to Wrapper #ifndef:: -* Computed Includes:: -* Wrapper Headers:: -* System Headers:: - - -File: cpp.info, Node: Include Syntax, Next: Include Operation, Up: Header Files - -2.1 Include Syntax -================== - -Both user and system header files are included using the preprocessing -directive `#include'. It has two variants: - -`#include ' - This variant is used for system header files. It searches for a - file named FILE in a standard list of system directories. You can - prepend directories to this list with the `-I' option (*note - Invocation::). - -`#include "FILE"' - This variant is used for header files of your own program. It - searches for a file named FILE first in the directory containing - the current file, then in the quote directories and then the same - directories used for `'. You can prepend directories to the - list of quote directories with the `-iquote' option. - - The argument of `#include', whether delimited with quote marks or -angle brackets, behaves like a string constant in that comments are not -recognized, and macro names are not expanded. Thus, `#include ' -specifies inclusion of a system header file named `x/*y'. - - However, if backslashes occur within FILE, they are considered -ordinary text characters, not escape characters. None of the character -escape sequences appropriate to string constants in C are processed. -Thus, `#include "x\n\\y"' specifies a filename containing three -backslashes. (Some systems interpret `\' as a pathname separator. All -of these also interpret `/' the same way. It is most portable to use -only `/'.) - - It is an error if there is anything (other than comments) on the line -after the file name. - - -File: cpp.info, Node: Include Operation, Next: Search Path, Prev: Include Syntax, Up: Header Files - -2.2 Include Operation -===================== - -The `#include' directive works by directing the C preprocessor to scan -the specified file as input before continuing with the rest of the -current file. The output from the preprocessor contains the output -already generated, followed by the output resulting from the included -file, followed by the output that comes from the text after the -`#include' directive. For example, if you have a header file -`header.h' as follows, - - char *test (void); - -and a main program called `program.c' that uses the header file, like -this, - - int x; - #include "header.h" - - int - main (void) - { - puts (test ()); - } - -the compiler will see the same token stream as it would if `program.c' -read - - int x; - char *test (void); - - int - main (void) - { - puts (test ()); - } - - Included files are not limited to declarations and macro definitions; -those are merely the typical uses. Any fragment of a C program can be -included from another file. The include file could even contain the -beginning of a statement that is concluded in the containing file, or -the end of a statement that was started in the including file. However, -an included file must consist of complete tokens. Comments and string -literals which have not been closed by the end of an included file are -invalid. For error recovery, they are considered to end at the end of -the file. - - To avoid confusion, it is best if header files contain only complete -syntactic units--function declarations or definitions, type -declarations, etc. - - The line following the `#include' directive is always treated as a -separate line by the C preprocessor, even if the included file lacks a -final newline. - - -File: cpp.info, Node: Search Path, Next: Once-Only Headers, Prev: Include Operation, Up: Header Files - -2.3 Search Path -=============== - -GCC looks in several different places for headers. On a normal Unix -system, if you do not instruct it otherwise, it will look for headers -requested with `#include ' in: - - /usr/local/include - LIBDIR/gcc/TARGET/VERSION/include - /usr/TARGET/include - /usr/include - - For C++ programs, it will also look in `/usr/include/g++-v3', first. -In the above, TARGET is the canonical name of the system GCC was -configured to compile code for; often but not always the same as the -canonical name of the system it runs on. VERSION is the version of GCC -in use. - - You can add to this list with the `-IDIR' command line option. All -the directories named by `-I' are searched, in left-to-right order, -_before_ the default directories. The only exception is when `dir' is -already searched by default. In this case, the option is ignored and -the search order for system directories remains unchanged. - - Duplicate directories are removed from the quote and bracket search -chains before the two chains are merged to make the final search chain. -Thus, it is possible for a directory to occur twice in the final search -chain if it was specified in both the quote and bracket chains. - - You can prevent GCC from searching any of the default directories -with the `-nostdinc' option. This is useful when you are compiling an -operating system kernel or some other program that does not use the -standard C library facilities, or the standard C library itself. `-I' -options are not ignored as described above when `-nostdinc' is in -effect. - - GCC looks for headers requested with `#include "FILE"' first in the -directory containing the current file, then in the directories as -specified by `-iquote' options, then in the same places it would have -looked for a header requested with angle brackets. For example, if -`/usr/include/sys/stat.h' contains `#include "types.h"', GCC looks for -`types.h' first in `/usr/include/sys', then in its usual search path. - - `#line' (*note Line Control::) does not change GCC's idea of the -directory containing the current file. - - You may put `-I-' at any point in your list of `-I' options. This -has two effects. First, directories appearing before the `-I-' in the -list are searched only for headers requested with quote marks. -Directories after `-I-' are searched for all headers. Second, the -directory containing the current file is not searched for anything, -unless it happens to be one of the directories named by an `-I' switch. -`-I-' is deprecated, `-iquote' should be used instead. - - `-I. -I-' is not the same as no `-I' options at all, and does not -cause the same behavior for `<>' includes that `""' includes get with -no special options. `-I.' searches the compiler's current working -directory for header files. That may or may not be the same as the -directory containing the current file. - - If you need to look for headers in a directory named `-', write -`-I./-'. - - There are several more ways to adjust the header search path. They -are generally less useful. *Note Invocation::. - - -File: cpp.info, Node: Once-Only Headers, Next: Alternatives to Wrapper #ifndef, Prev: Search Path, Up: Header Files - -2.4 Once-Only Headers -===================== - -If a header file happens to be included twice, the compiler will process -its contents twice. This is very likely to cause an error, e.g. when -the compiler sees the same structure definition twice. Even if it does -not, it will certainly waste time. - - The standard way to prevent this is to enclose the entire real -contents of the file in a conditional, like this: - - /* File foo. */ - #ifndef FILE_FOO_SEEN - #define FILE_FOO_SEEN - - THE ENTIRE FILE - - #endif /* !FILE_FOO_SEEN */ - - This construct is commonly known as a "wrapper #ifndef". When the -header is included again, the conditional will be false, because -`FILE_FOO_SEEN' is defined. The preprocessor will skip over the entire -contents of the file, and the compiler will not see it twice. - - CPP optimizes even further. It remembers when a header file has a -wrapper `#ifndef'. If a subsequent `#include' specifies that header, -and the macro in the `#ifndef' is still defined, it does not bother to -rescan the file at all. - - You can put comments outside the wrapper. They will not interfere -with this optimization. - - The macro `FILE_FOO_SEEN' is called the "controlling macro" or -"guard macro". In a user header file, the macro name should not begin -with `_'. In a system header file, it should begin with `__' to avoid -conflicts with user programs. In any kind of header file, the macro -name should contain the name of the file and some additional text, to -avoid conflicts with other header files. - - -File: cpp.info, Node: Alternatives to Wrapper #ifndef, Next: Computed Includes, Prev: Once-Only Headers, Up: Header Files - -2.5 Alternatives to Wrapper #ifndef -=================================== - -CPP supports two more ways of indicating that a header file should be -read only once. Neither one is as portable as a wrapper `#ifndef' and -we recommend you do not use them in new programs, with the caveat that -`#import' is standard practice in Objective-C. - - CPP supports a variant of `#include' called `#import' which includes -a file, but does so at most once. If you use `#import' instead of -`#include', then you don't need the conditionals inside the header file -to prevent multiple inclusion of the contents. `#import' is standard -in Objective-C, but is considered a deprecated extension in C and C++. - - `#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 `#ifndef' accomplishes this -goal. - - In the present implementation, a single use of `#import' will -prevent the file from ever being read again, by either `#import' or -`#include'. You should not rely on this; do not use both `#import' and -`#include' to refer to the same header file. - - Another way to prevent a header file from being included more than -once is with the `#pragma once' directive. If `#pragma once' is seen -when scanning a header file, that file will never be read again, no -matter what. - - `#pragma once' does not have the problems that `#import' does, but -it is not recognized by all preprocessors, so you cannot rely on it in -a portable program. - - -File: cpp.info, Node: Computed Includes, Next: Wrapper Headers, Prev: Alternatives to Wrapper #ifndef, Up: Header Files - -2.6 Computed Includes -===================== - -Sometimes it is necessary to select one of several different header -files to be included into your program. They might specify -configuration parameters to be used on different sorts of operating -systems, for instance. You could do this with a series of conditionals, - - #if SYSTEM_1 - # include "system_1.h" - #elif SYSTEM_2 - # include "system_2.h" - #elif SYSTEM_3 - ... - #endif - - That rapidly becomes tedious. Instead, the preprocessor offers the -ability to use a macro for the header name. This is called a "computed -include". Instead of writing a header name as the direct argument of -`#include', you simply put a macro name there instead: - - #define SYSTEM_H "system_1.h" - ... - #include SYSTEM_H - -`SYSTEM_H' will be expanded, and the preprocessor will look for -`system_1.h' as if the `#include' had been written that way originally. -`SYSTEM_H' could be defined by your Makefile with a `-D' option. - - You must be careful when you define the macro. `#define' saves -tokens, not text. The preprocessor has no way of knowing that the macro -will be used as the argument of `#include', so it generates ordinary -tokens, not a header name. This is unlikely to cause problems if you -use double-quote includes, which are close enough to string constants. -If you use angle brackets, however, you may have trouble. - - The syntax of a computed include is actually a bit more general than -the above. If the first non-whitespace character after `#include' is -not `"' or `<', then the entire line is macro-expanded like running -text would be. - - If the line expands to a single string constant, the contents of that -string constant are the file to be included. CPP does not re-examine -the string for embedded quotes, but neither does it process backslash -escapes in the string. Therefore - - #define HEADER "a\"b" - #include HEADER - -looks for a file named `a\"b'. CPP searches for the file according to -the rules for double-quoted includes. - - If the line expands to a token stream beginning with a `<' token and -including a `>' token, then the tokens between the `<' and the first -`>' are combined to form the filename to be included. Any whitespace -between tokens is reduced to a single space; then any space after the -initial `<' is retained, but a trailing space before the closing `>' is -ignored. CPP searches for the file according to the rules for -angle-bracket includes. - - In either case, if there are any tokens on the line after the file -name, an error occurs and the directive is not processed. It is also -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. - - -File: cpp.info, Node: Wrapper Headers, Next: System Headers, Prev: Computed Includes, Up: Header Files - -2.7 Wrapper Headers -=================== - -Sometimes it is necessary to adjust the contents of a system-provided -header file without editing it directly. GCC's `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 `#include'. That will -start from the beginning, and find your new header again. If your -header is not protected from multiple inclusion (*note Once-Only -Headers::), it will recurse infinitely and cause a fatal error. - - You could include the old header with an absolute pathname: - #include "/usr/include/old-header.h" - 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 `#include_next'. It means, "Include the -_next_ file with this name". This directive works like `#include' -except in searching for the specified file: it starts searching the -list of header file directories _after_ the directory in which the -current file was found. - - Suppose you specify `-I /usr/local/include', and the list of -directories to search also includes `/usr/include'; and suppose both -directories contain `signal.h'. Ordinary `#include ' finds -the file under `/usr/local/include'. If that file contains -`#include_next ', it starts searching after that directory, -and finds the file in `/usr/include'. - - `#include_next' does not distinguish between `' and `"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 `#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 `fixincludes'. - - -File: cpp.info, Node: System Headers, Prev: Wrapper Headers, Up: Header Files - -2.8 System Headers -================== - -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 "system headers" special treatment. -All warnings, other than those generated by `#warning' (*note -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 `-isystem' command line option adds its argument to the list of -directories to search for headers, just like `-I'. Any headers found -in that directory will be considered system headers. - - All directories named by `-isystem' are searched _after_ all -directories named by `-I', no matter what their order was on the -command line. If the same directory is named by both `-I' and -`-isystem', the `-I' option is ignored. GCC provides an informative -message when this occurs if `-v' is used. - - There is also a directive, `#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 `#pragma' in -the file will not be affected. `#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 `extern "C"' -block. There is no way to request this behavior with a `#pragma', or -from the command line. - - -File: cpp.info, Node: Macros, Next: Conditionals, Prev: Header Files, Up: Top - -3 Macros -******** - -A "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. "Object-like" macros resemble data objects when -used, "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 `const' from an -older compiler that does not understand it. However, the preprocessor -operator `defined' (*note Defined::) can never be defined as a macro, -and C++'s named operators (*note 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:: - - -File: cpp.info, Node: Object-like Macros, Next: Function-like Macros, Up: Macros - -3.1 Object-like Macros -====================== - -An "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. - - You create macros with the `#define' directive. `#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 -"body", "expansion" or "replacement list". For example, - - #define BUFFER_SIZE 1024 - -defines a macro named `BUFFER_SIZE' as an abbreviation for the token -`1024'. If somewhere after this `#define' directive there comes a C -statement of the form - - foo = (char *) malloc (BUFFER_SIZE); - -then the C preprocessor will recognize and "expand" the macro -`BUFFER_SIZE'. The C compiler will see the same tokens as it would if -you had written - - foo = (char *) malloc (1024); - - By convention, macro names are written in uppercase. 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 `#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, - - #define NUMBERS 1, \ - 2, \ - 3 - int x[] = { NUMBERS }; - ==> int x[] = { 1, 2, 3 }; - -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 - - foo = X; - #define X 4 - bar = X; - -produces - - foo = X; - bar = 4; - - 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, - - #define TABLESIZE BUFSIZE - #define BUFSIZE 1024 - TABLESIZE - ==> BUFSIZE - ==> 1024 - -`TABLESIZE' is expanded first to produce `BUFSIZE', then that macro is -expanded to produce the final result, `1024'. - - Notice that `BUFSIZE' was not defined when `TABLESIZE' was defined. -The `#define' for `TABLESIZE' uses exactly the expansion you -specify--in this case, `BUFSIZE'--and does not check to see whether it -too contains macro names. Only when you _use_ `TABLESIZE' is the -result of its expansion scanned for more macro names. - - This makes a difference if you change the definition of `BUFSIZE' at -some point in the source file. `TABLESIZE', defined as shown, will -always expand using the definition of `BUFSIZE' that is currently in -effect: - - #define BUFSIZE 1020 - #define TABLESIZE BUFSIZE - #undef BUFSIZE - #define BUFSIZE 37 - -Now `TABLESIZE' expands (in two stages) to `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. *Note -Self-Referential Macros::, for the precise details. - - -File: cpp.info, Node: Function-like Macros, Next: Macro Arguments, Prev: Object-like Macros, Up: Macros - -3.2 Function-like Macros -======================== - -You can also define macros whose use looks like a function call. These -are called "function-like macros". To define a function-like macro, -you use the same `#define' directive, but you put a pair of parentheses -immediately after the macro name. For example, - - #define lang_init() c_init() - lang_init() - ==> c_init() - - 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. - - extern void foo(void); - #define foo() /* optimized inline version */ - ... - foo(); - funcptr = foo; - - Here the call to `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. - - #define lang_init () c_init() - lang_init() - ==> () c_init()() - - 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 `lang_init' is an object-like macro, it does not -consume those parentheses. - - -File: cpp.info, Node: Macro Arguments, Next: Stringification, Prev: Function-like Macros, Up: Macros - -3.3 Macro Arguments -=================== - -Function-like macros can take "arguments", just like true functions. -To define a macro that uses arguments, you insert "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 "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. - - #define min(X, Y) ((X) < (Y) ? (X) : (Y)) - x = min(a, b); ==> x = ((a) < (b) ? (a) : (b)); - y = min(1, 2); ==> y = ((1) < (2) ? (1) : (2)); - z = min(a + 28, *p); ==> z = ((a + 28) < (*p) ? (a + 28) : (*p)); - -(In this small example you can already see several of the dangers of -macro arguments. *Note 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, - - macro (array[x = y, x + 1]) - -passes two arguments to `macro': `array[x = y' and `x + 1]'. If you -want to supply `array[x = y, x + 1]' as an argument, you can write it -as `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. *Note Argument Prescan::, for detailed discussion. - - For example, `min (min (a, b), c)' is first expanded to - - min (((a) < (b) ? (a) : (b)), (c)) - -and then to - - ((((a) < (b) ? (a) : (b))) < (c) - ? (((a) < (b) ? (a) : (b))) - : (c)) - -(Line breaks shown here for clarity would not actually be generated.) - - 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 `min': - - min(, b) ==> (( ) < (b) ? ( ) : (b)) - min(a, ) ==> ((a ) < ( ) ? (a ) : ( )) - min(,) ==> (( ) < ( ) ? ( ) : ( )) - min((,),) ==> (((,)) < ( ) ? ((,)) : ( )) - - min() error--> macro "min" requires 2 arguments, but only 1 given - min(,,) error--> macro "min" passed 3 arguments, but takes just 2 - - Whitespace is not a preprocessing token, so if a macro `foo' takes -one argument, `foo ()' and `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. - - #define foo(x) x, "x" - foo(bar) ==> bar, "x" - - -File: cpp.info, Node: Stringification, Next: Concatenation, Prev: Macro Arguments, Up: Macros - -3.4 Stringification -=================== - -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 `#' preprocessing operator instead. When a macro parameter -is used with a leading `#', 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 "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: - - #define WARN_IF(EXP) \ - do { if (EXP) \ - fprintf (stderr, "Warning: " #EXP "\n"); } \ - while (0) - WARN_IF (x == 0); - ==> do { if (x == 0) - fprintf (stderr, "Warning: " "x == 0" "\n"); } while (0); - -The argument for `EXP' is substituted once, as-is, into the `if' -statement, and once, stringified, into the argument to `fprintf'. If -`x' were a macro, it would be expanded in the `if' statement, but not -in the string. - - The `do' and `while (0)' are a kludge to make it possible to write -`WARN_IF (ARG);', which the resemblance of `WARN_IF' to a function -would make C programmers want to do; see *note 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 `p = "foo\n";' -results in "p = \"foo\\n\";". However, backslashes that are not inside -string or character constants are not duplicated: `\n' by itself -stringifies to "\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. - - #define xstr(s) str(s) - #define str(s) #s - #define foo 4 - str (foo) - ==> "foo" - xstr (foo) - ==> xstr (4) - ==> str (4) - ==> "4" - - `s' is stringified when it is used in `str', so it is not -macro-expanded first. But `s' is an ordinary argument to `xstr', so it -is completely macro-expanded before `xstr' itself is expanded (*note -Argument Prescan::). Therefore, by the time `str' gets to its -argument, it has already been macro-expanded. - - -File: cpp.info, Node: Concatenation, Next: Variadic Macros, Prev: Stringification, Up: Macros - -3.5 Concatenation -================= - -It is often useful to merge two tokens into one while expanding macros. -This is called "token pasting" or "token concatenation". The `##' -preprocessing operator performs token pasting. When a macro is -expanded, the two tokens on either side of each `##' operator are -combined into a single token, which then replaces the `##' 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 `1.5' and `e3') into a number. Also, -multi-character operators such as `+=' 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 `x' with `+' 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 `##' in complex -macros. If you get this warning, it is likely that you can simply -remove the `##'. - - Both the tokens combined by `##' 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 `##' is a parameter -name, it is replaced by its actual argument before `##' executes. As -with stringification, the actual argument is not macro-expanded first. -If the argument is empty, that `##' 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 `/' and `*'. You can put as much whitespace -between `##' 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 `##' 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: - - struct command - { - char *name; - void (*function) (void); - }; - - struct command commands[] = - { - { "quit", quit_command }, - { "help", help_command }, - ... - }; - - 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 `_command'. -Here is how it is done: - - #define COMMAND(NAME) { #NAME, NAME ## _command } - - struct command commands[] = - { - COMMAND (quit), - COMMAND (help), - ... - }; - - -File: cpp.info, Node: Variadic Macros, Next: Predefined Macros, Prev: Concatenation, Up: Macros - -3.6 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: - - #define eprintf(...) fprintf (stderr, __VA_ARGS__) - - This kind of macro is called "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 "variable argument". -This sequence of tokens replaces the identifier `__VA_ARGS__' in the -macro body wherever it appears. Thus, we have this expansion: - - eprintf ("%s:%d: ", input_file, lineno) - ==> fprintf (stderr, "%s:%d: ", input_file, lineno) - - The variable argument is completely macro-expanded before it is -inserted into the macro expansion, just like an ordinary argument. You -may use the `#' and `##' 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 `##'.) - - If your macro is complicated, you may want a more descriptive name -for the variable argument than `__VA_ARGS__'. CPP permits this, as an -extension. You may write an argument name immediately before the -`...'; that name is used for the variable argument. The `eprintf' -macro above could be written - - #define eprintf(args...) fprintf (stderr, args) - -using this extension. You cannot use `__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 `eprintf' like this, instead: - - #define eprintf(format, ...) fprintf (stderr, format, __VA_ARGS__) - -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. - - eprintf("success!\n", ); - ==> fprintf(stderr, "success!\n", ); - - GNU CPP has a pair of extensions which deal with this problem. -First, you are allowed to leave the variable argument out entirely: - - eprintf ("success!\n") - ==> fprintf(stderr, "success!\n", ); - -Second, the `##' token paste operator has a special meaning when placed -between a comma and a variable argument. If you write - - #define eprintf(format, ...) fprintf (stderr, format, ##__VA_ARGS__) - -and the variable argument is left out when the `eprintf' macro is used, -then the comma before the `##' will be deleted. This does _not_ happen -if you pass an empty argument, nor does it happen if the token -preceding `##' is anything other than a comma. - - eprintf ("success!\n") - ==> fprintf(stderr, "success!\n"); - -The above explanation is ambiguous about the case where the only macro -parameter is a variable arguments parameter, as it is meaningless to -try to distinguish whether no argument at all is an empty argument or a -missing argument. In this case the C99 standard is clear that the -comma must remain, however the existing GCC extension used to swallow -the comma. So CPP retains the comma when conforming to a specific C -standard, and drops it otherwise. - - C99 mandates that the only place the identifier `__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 (`args...', -not `...' and `__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 `__VA_ARGS__'. - - Previous versions of 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 `##' must be -a comma, and there must be white space between that comma and whatever -comes immediately before it: - - #define eprintf(format, args...) fprintf (stderr, format , ##args) - -*Note Differences from previous versions::, for the gory details. - - -File: cpp.info, Node: Predefined Macros, Next: Undefining and Redefining Macros, Prev: Variadic Macros, Up: Macros - -3.7 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:: - - -File: cpp.info, Node: Standard Predefined Macros, Next: Common Predefined Macros, Up: Predefined Macros - -3.7.1 Standard Predefined Macros --------------------------------- - -The standard predefined macros are specified by the relevant 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. - -`__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 - `#include' or as the input file name argument. For example, - `"/usr/local/include/myheader.h"' is a possible expansion of this - macro. - -`__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. - - `__FILE__' and `__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, - - fprintf (stderr, "Internal error: " - "negative string length " - "%d at %s, line %d.", - length, __FILE__, __LINE__); - - An `#include' directive changes the expansions of `__FILE__' and -`__LINE__' to correspond to the included file. At the end of that -file, when processing resumes on the input file that contained the -`#include' directive, the expansions of `__FILE__' and `__LINE__' -revert to the values they had before the `#include' (but `__LINE__' is -then incremented by one as processing moves to the line after the -`#include'). - - A `#line' directive changes `__LINE__', and may change `__FILE__' as -well. *Note Line Control::. - - C99 introduces `__func__', and GCC has provided `__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 `__FILE__' and `__LINE__', though. - -`__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 `"Feb 12 1996"'. If the day of - the month is less than 10, it is padded with a space on the left. - - If GCC cannot determine the current date, it will emit a warning - message (once per compilation) and `__DATE__' will expand to - `"??? ?? ????"'. - -`__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 `"23:59:01"'. - - If GCC cannot determine the current time, it will emit a warning - message (once per compilation) and `__TIME__' will expand to - `"??:??:??"'. - -`__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 `-traditional-cpp' option is used. - - This macro is not defined if the `-traditional-cpp' option is used. - - On some hosts, the system compiler uses a different convention, - where `__STDC__' is normally 0, but is 1 if the user specifies - strict conformance to the C Standard. CPP follows the host - convention when processing system header files, but when - processing user files `__STDC__' is always 1. This has been - reported to cause problems; for instance, some versions of Solaris - provide X Windows headers that expect `__STDC__' to be either - undefined or 1. *Note Invocation::. - -`__STDC_VERSION__' - This macro expands to the C Standard's version number, a long - integer constant of the form `YYYYMML' where YYYY and MM are the - year and month of the Standard version. This signifies which - version of the C Standard the compiler conforms to. Like - `__STDC__', this is not necessarily accurate for the entire - implementation, unless GNU CPP is being used with GCC. - - The value `199409L' signifies the 1989 C standard as amended in - 1994, which is the current default; the value `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 `-traditional-cpp' option is - used, nor when compiling C++ or Objective-C. - -`__STDC_HOSTED__' - This macro is defined, with value 1, if the compiler's target is a - "hosted environment". A hosted environment has the complete - facilities of the standard C library available. - -`__cplusplus' - This macro is defined when the C++ compiler is in use. You can use - `__cplusplus' to test whether a header is compiled by a C compiler - or a C++ compiler. This macro is similar to `__STDC_VERSION__', in - that it expands to a version number. A fully conforming - implementation of the 1998 C++ standard will define this macro to - `199711L'. The GNU C++ compiler is not yet fully conforming, so - it uses `1' instead. It is hoped to complete the implementation - of standard C++ in the near future. - -`__OBJC__' - This macro is defined, with value 1, when the Objective-C compiler - is in use. You can use `__OBJC__' to test whether a header is - compiled by a C compiler or a Objective-C compiler. - -`__ASSEMBLER__' - This macro is defined with value 1 when preprocessing assembly - language. - - - -File: cpp.info, Node: Common Predefined Macros, Next: System-specific Predefined Macros, Prev: Standard Predefined Macros, Up: Predefined Macros - -3.7.2 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 or GNU Fortran. Their names all start with -double underscores. - -`__COUNTER__' - This macro expands to sequential integral values starting from 0. - In conjunction with the `##' operator, this provides a convenient - means to generate unique identifiers. Care must be taken to - ensure that `__COUNTER__' is not expanded prior to inclusion of - precompiled headers which use it. Otherwise, the precompiled - headers will not be used. - -`__GFORTRAN__' - The GNU Fortran compiler defines this. - -`__GNUC__' -`__GNUC_MINOR__' -`__GNUC_PATCHLEVEL__' - These macros are defined by all GNU compilers that use the C - preprocessor: C, C++, Objective-C and Fortran. 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 - `__GNUC__' to 3, `__GNUC_MINOR__' to 2, and `__GNUC_PATCHLEVEL__' - to 1. These macros are also defined if you invoke the - preprocessor directly. - - `__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, or a non-GCC compiler that claims to accept the - GNU C dialects, you can simply test `__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: - - /* Test for GCC > 3.2.0 */ - #if __GNUC__ > 3 || \ - (__GNUC__ == 3 && (__GNUC_MINOR__ > 2 || \ - (__GNUC_MINOR__ == 2 && \ - __GNUC_PATCHLEVEL__ > 0)) - - Another approach is to use the predefined macros to calculate a - single number, then compare that against a threshold: - - #define GCC_VERSION (__GNUC__ * 10000 \ - + __GNUC_MINOR__ * 100 \ - + __GNUC_PATCHLEVEL__) - ... - /* Test for GCC > 3.2.0 */ - #if GCC_VERSION > 30200 - - Many people find this form easier to understand. - -`__GNUG__' - The GNU C++ compiler defines this. Testing it is equivalent to - testing `(__GNUC__ && __cplusplus)'. - -`__STRICT_ANSI__' - GCC defines this macro if and only if the `-ansi' switch, or a - `-std' switch specifying strict conformance to some version of ISO - C, was specified when GCC was invoked. It is defined to `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. - -`__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. - -`__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 `#include' directive and decremented at the - end of every included file. It starts out at 0, its value within - the base file specified on the command line. - -`__ELF__' - This macro is defined if the target uses the ELF object format. - -`__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. - -`__OPTIMIZE__' -`__OPTIMIZE_SIZE__' -`__NO_INLINE__' - These macros describe the compilation mode. `__OPTIMIZE__' is - defined in all optimizing compilations. `__OPTIMIZE_SIZE__' is - defined if the compiler is optimizing for size, not speed. - `__NO_INLINE__' is defined if no functions will be inlined into - their callers (when not optimizing, or when inlining has been - specifically disabled by `-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. - -`__GNUC_GNU_INLINE__' - GCC defines this macro if functions declared `inline' will be - handled in GCC's traditional gnu89 mode. Object files will contain - externally visible definitions of all functions declared `inline' - without `extern' or `static'. They will not contain any - definitions of any functions declared `extern inline'. - -`__GNUC_STDC_INLINE__' - GCC defines this macro if functions declared `inline' will be - handled according to the ISO C99 standard. Object files will - contain externally visible definitions of all functions declared - `extern inline'. They will not contain definitions of any - functions declared `inline' without `extern'. - - If this macro is defined, GCC supports the `gnu_inline' function - attribute as a way to always get the gnu89 behavior. Support for - this and `__GNUC_GNU_INLINE__' was added in GCC 4.1.3. If neither - macro is defined, an older version of GCC is being used: `inline' - functions will be compiled in gnu89 mode, and the `gnu_inline' - function attribute will not be recognized. - -`__CHAR_UNSIGNED__' - GCC defines this macro if and only if the data type `char' is - unsigned on the target machine. It exists to cause the standard - header file `limits.h' to work correctly. You should not use this - macro yourself; instead, refer to the standard macros defined in - `limits.h'. - -`__WCHAR_UNSIGNED__' - Like `__CHAR_UNSIGNED__', this macro is defined if and only if the - data type `wchar_t' is unsigned and the front-end is in C++ mode. - -`__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 `m68k-aout' - environment it expands to nothing, but in the `m68k-coff' - environment it expands to a single `%'. - -`__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 `m68k-aout' environment it expands to an `_', but in the - `m68k-coff' environment it expands to nothing. - - This macro will have the correct definition even if - `-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 `-mno-underscores' option). - -`__SIZE_TYPE__' -`__PTRDIFF_TYPE__' -`__WCHAR_TYPE__' -`__WINT_TYPE__' -`__INTMAX_TYPE__' -`__UINTMAX_TYPE__' - These macros are defined to the correct underlying types for the - `size_t', `ptrdiff_t', `wchar_t', `wint_t', `intmax_t', and - `uintmax_t' typedefs, respectively. They exist to make the - standard header files `stddef.h' and `wchar.h' work correctly. - You should not use these macros directly; instead, include the - appropriate headers and use the typedefs. - -`__CHAR_BIT__' - Defined to the number of bits used in the representation of the - `char' data type. It exists to make the standard header given - numerical limits work correctly. You should not use this macro - directly; instead, include the appropriate headers. - -`__SCHAR_MAX__' -`__WCHAR_MAX__' -`__SHRT_MAX__' -`__INT_MAX__' -`__LONG_MAX__' -`__LONG_LONG_MAX__' -`__INTMAX_MAX__' - Defined to the maximum value of the `signed char', `wchar_t', - `signed short', `signed int', `signed long', `signed long long', - and `intmax_t' types respectively. They exist to make the - standard header given numerical limits work correctly. You should - not use these macros directly; instead, include the appropriate - headers. - -`__SIZEOF_INT__' -`__SIZEOF_LONG__' -`__SIZEOF_LONG_LONG__' -`__SIZEOF_SHORT__' -`__SIZEOF_POINTER__' -`__SIZEOF_FLOAT__' -`__SIZEOF_DOUBLE__' -`__SIZEOF_LONG_DOUBLE__' -`__SIZEOF_SIZE_T__' -`__SIZEOF_WCHAR_T__' -`__SIZEOF_WINT_T__' -`__SIZEOF_PTRDIFF_T__' - Defined to the number of bytes of the C standard data types: `int', - `long', `long long', `short', `void *', `float', `double', `long - double', `size_t', `wchar_t', `wint_t' and `ptrdiff_t'. - -`__DEPRECATED' - This macro is defined, with value 1, when compiling a C++ source - file with warnings about deprecated constructs enabled. These - warnings are enabled by default, but can be disabled with - `-Wno-deprecated'. - -`__EXCEPTIONS' - This macro is defined, with value 1, when compiling a C++ source - file with exceptions enabled. If `-fno-exceptions' is used when - compiling the file, then this macro is not defined. - -`__GXX_RTTI' - This macro is defined, with value 1, when compiling a C++ source - file with runtime type identification enabled. If `-fno-rtti' is - used when compiling the file, then this macro is not defined. - -`__USING_SJLJ_EXCEPTIONS__' - This macro is defined, with value 1, if the compiler uses the old - mechanism based on `setjmp' and `longjmp' for exception handling. - -`__GXX_EXPERIMENTAL_CXX0X__' - This macro is defined when compiling a C++ source file with the - option `-std=c++0x' or `-std=gnu++0x'. It indicates that some - features likely to be included in C++0x are available. Note that - these features are experimental, and may change or be removed in - future versions of GCC. - -`__GXX_WEAK__' - This macro is defined when compiling a C++ source file. It has the - value 1 if the compiler will use weak symbols, COMDAT sections, or - other similar techniques to collapse symbols with "vague linkage" - that are defined in multiple translation units. If the compiler - will not collapse such symbols, this macro is defined with value - 0. In general, user code should not need to make use of this - macro; the purpose of this macro is to ease implementation of the - C++ runtime library provided with G++. - -`__NEXT_RUNTIME__' - This macro is defined, with value 1, if (and only if) the NeXT - runtime (as in `-fnext-runtime') is in use for Objective-C. If - the GNU runtime is used, this macro is not defined, so that you - can use this macro to determine which runtime (NeXT or GNU) is - being used. - -`__LP64__' -`_LP64' - These macros are defined, with value 1, if (and only if) the - compilation is for a target where `long int' and pointer both use - 64-bits and `int' uses 32-bit. - -`__SSP__' - This macro is defined, with value 1, when `-fstack-protector' is in - use. - -`__SSP_ALL__' - This macro is defined, with value 2, when `-fstack-protector-all' - is in use. - -`__TIMESTAMP__' - This macro expands to a string constant that describes the date - and time of the last modification of the current source file. The - string constant contains abbreviated day of the week, month, day - of the month, time in hh:mm:ss form, year and looks like - `"Sun Sep 16 01:03:52 1973"'. If the day of the month is less - than 10, it is padded with a space on the left. - - If GCC cannot determine the current date, it will emit a warning - message (once per compilation) and `__TIMESTAMP__' will expand to - `"??? ??? ?? ??:??:?? ????"'. - -`__GCC_HAVE_SYNC_COMPARE_AND_SWAP_1' -`__GCC_HAVE_SYNC_COMPARE_AND_SWAP_2' -`__GCC_HAVE_SYNC_COMPARE_AND_SWAP_4' -`__GCC_HAVE_SYNC_COMPARE_AND_SWAP_8' -`__GCC_HAVE_SYNC_COMPARE_AND_SWAP_16' - These macros are defined when the target processor supports atomic - compare and swap operations on operands 1, 2, 4, 8 or 16 bytes in - length, respectively. - -`__GCC_HAVE_DWARF2_CFI_ASM' - This macro is defined when the compiler is emitting Dwarf2 CFI - directives to the assembler. When this is defined, it is possible - to emit those same directives in inline assembly. - - -File: cpp.info, Node: System-specific Predefined Macros, Next: C++ Named Operators, Prev: Common Predefined Macros, Up: Predefined Macros - -3.7.3 System-specific Predefined Macros ---------------------------------------- - -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 `cpp --dM' to see them all. *Note Invocation::. All system-specific -predefined macros expand to the constant 1, so you can test them with -either `#ifdef' or `#if'. - - The C standard requires that all system-specific macros be part of -the "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 `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 `unix' is defined, `__unix__' will be defined too. -There will never be more than two underscores; the parallel of `_mips' -is `__mips__'. - - When the `-ansi' option, or any `-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 -`autoconf'. - - -File: cpp.info, Node: C++ Named Operators, Prev: System-specific Predefined Macros, Up: Predefined Macros - -3.7.4 C++ Named Operators -------------------------- - -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 -`#if', and they cannot be defined as macros or poisoned. In C, you can -request that those keywords take their C++ meaning by including -`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: - -Named Operator Punctuator -`and' `&&' -`and_eq' `&=' -`bitand' `&' -`bitor' `|' -`compl' `~' -`not' `!' -`not_eq' `!=' -`or' `||' -`or_eq' `|=' -`xor' `^' -`xor_eq' `^=' - - -File: cpp.info, Node: Undefining and Redefining Macros, Next: Directives Within Macro Arguments, Prev: Predefined Macros, Up: Macros - -3.8 Undefining and Redefining Macros -==================================== - -If a macro ceases to be useful, it may be "undefined" with the `#undef' -directive. `#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. `#undef' has no effect if the name is not a macro. - - #define FOO 4 - x = FOO; ==> x = 4; - #undef FOO - x = FOO; ==> x = FOO; - - Once a macro has been undefined, that identifier may be "redefined" -as a macro by a subsequent `#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 "effectively the same" as the old one. -Two macro definitions are effectively the same if: - * Both are the same type of macro (object- or function-like). - - * All the tokens of the replacement list are the same. - - * If there are any parameters, they are the same. - - * 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. - -These definitions are effectively the same: - #define FOUR (2 + 2) - #define FOUR (2 + 2) - #define FOUR (2 /* two */ + 2) - but these are not: - #define FOUR (2 + 2) - #define FOUR ( 2+2 ) - #define FOUR (2 * 2) - #define FOUR(score,and,seven,years,ago) (2 + 2) - - 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. - - -File: cpp.info, Node: Directives Within Macro Arguments, Next: Macro Pitfalls, Prev: Undefining and Redefining Macros, Up: Macros - -3.9 Directives Within Macro Arguments -===================================== - -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 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 `printf', only to find that after a library upgrade -`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: - - #define f(x) x x - f (1 - #undef f - #define f 2 - f) - -which expands to - - 1 2 1 2 - -with the semantics described above. - - -File: cpp.info, Node: Macro Pitfalls, Prev: Directives Within Macro Arguments, Up: Macros - -3.10 Macro Pitfalls -=================== - -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:: - - -File: cpp.info, Node: Misnesting, Next: Operator Precedence Problems, Up: Macro Pitfalls - -3.10.1 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, - - #define twice(x) (2*(x)) - #define call_with_1(x) x(1) - call_with_1 (twice) - ==> twice(1) - ==> (2*(1)) - - 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, - - #define strange(file) fprintf (file, "%s %d", - ... - strange(stderr) p, 35) - ==> fprintf (stderr, "%s %d", p, 35) - - 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. - - -File: cpp.info, Node: Operator Precedence Problems, Next: Swallowing the Semicolon, Prev: Misnesting, Up: Macro Pitfalls - -3.10.2 Operator Precedence Problems ------------------------------------ - -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, - - #define ceil_div(x, y) (x + y - 1) / y - -whose purpose is to divide, rounding up. (One use for this operation is -to compute how many `int' objects are needed to hold a certain number -of `char' objects.) Then suppose it is used as follows: - - a = ceil_div (b & c, sizeof (int)); - ==> a = (b & c + sizeof (int) - 1) / sizeof (int); - -This does not do what is intended. The operator-precedence rules of C -make it equivalent to this: - - a = (b & (c + sizeof (int) - 1)) / sizeof (int); - -What we want is this: - - a = ((b & c) + sizeof (int) - 1)) / sizeof (int); - -Defining the macro as - - #define ceil_div(x, y) ((x) + (y) - 1) / (y) - -provides the desired result. - - Unintended grouping can result in another way. Consider `sizeof -ceil_div(1, 2)'. That has the appearance of a C expression that would -compute the size of the type of `ceil_div (1, 2)', but in fact it means -something very different. Here is what it expands to: - - sizeof ((1) + (2) - 1) / (2) - -This would take the size of an integer and divide it by two. The -precedence rules have put the division outside the `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 `ceil_div': - - #define ceil_div(x, y) (((x) + (y) - 1) / (y)) - - -File: cpp.info, Node: Swallowing the Semicolon, Next: Duplication of Side Effects, Prev: Operator Precedence Problems, Up: Macro Pitfalls - -3.10.3 Swallowing the Semicolon -------------------------------- - -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 `p' says where to find it) across whitespace -characters: - - #define SKIP_SPACES(p, limit) \ - { char *lim = (limit); \ - while (p < lim) { \ - if (*p++ != ' ') { \ - p--; break; }}} - -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 `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 `SKIP_SPACES -(p, lim);' - - This can cause trouble before `else' statements, because the -semicolon is actually a null statement. Suppose you write - - if (*p != 0) - SKIP_SPACES (p, lim); - else ... - -The presence of two statements--the compound statement and a null -statement--in between the `if' condition and the `else' makes invalid C -code. - - The definition of the macro `SKIP_SPACES' can be altered to solve -this problem, using a `do ... while' statement. Here is how: - - #define SKIP_SPACES(p, limit) \ - do { char *lim = (limit); \ - while (p < lim) { \ - if (*p++ != ' ') { \ - p--; break; }}} \ - while (0) - - Now `SKIP_SPACES (p, lim);' expands into - - do {...} while (0); - -which is one statement. The loop executes exactly once; most compilers -generate no extra code for it. - - -File: cpp.info, Node: Duplication of Side Effects, Next: Self-Referential Macros, Prev: Swallowing the Semicolon, Up: Macro Pitfalls - -3.10.4 Duplication of Side Effects ----------------------------------- - -Many C programs define a macro `min', for "minimum", like this: - - #define min(X, Y) ((X) < (Y) ? (X) : (Y)) - - When you use this macro with an argument containing a side effect, -as shown here, - - next = min (x + y, foo (z)); - -it expands as follows: - - next = ((x + y) < (foo (z)) ? (x + y) : (foo (z))); - -where `x + y' has been substituted for `X' and `foo (z)' for `Y'. - - The function `foo' is used only once in the statement as it appears -in the program, but the expression `foo (z)' has been substituted twice -into the macro expansion. As a result, `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 `min' is an "unsafe" macro. - - The best solution to this problem is to define `min' in a way that -computes the value of `foo (z)' only once. The C language offers no -standard way to do this, but it can be done with GNU extensions as -follows: - - #define min(X, Y) \ - ({ typeof (X) x_ = (X); \ - typeof (Y) y_ = (Y); \ - (x_ < y_) ? x_ : y_; }) - - The `({ ... })' 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 _using_ the macro `min'. For example, you can -calculate the value of `foo (z)', save it in a variable, and use that -variable in `min': - - #define min(X, Y) ((X) < (Y) ? (X) : (Y)) - ... - { - int tem = foo (z); - next = min (x + y, tem); - } - -(where we assume that `foo' returns type `int'). - - -File: cpp.info, Node: Self-Referential Macros, Next: Argument Prescan, Prev: Duplication of Side Effects, Up: Macro Pitfalls - -3.10.5 Self-Referential Macros ------------------------------- - -A "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. Consider an example: - - #define foo (4 + foo) - -where `foo' is also a variable in your program. - - Following the ordinary rules, each reference to `foo' will expand -into `(4 + foo)'; then this will be rescanned and will expand into `(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 -`(4 + foo)'. Therefore, this macro definition has the possibly useful -effect of causing the program to add 4 to the value of `foo' wherever -`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 `foo' is a variable will not -expect that it is a macro as well. The reader will come across the -identifier `foo' in the program and think its value should be that of -the variable `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 - - #define EPERM EPERM - -then the macro `EPERM' expands to `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 `#ifdef'. You might do this if you want to -define numeric constants with an `enum', but have `#ifdef' be true for -each constant. - - If a macro `x' expands to use a macro `y', and the expansion of `y' -refers to the macro `x', that is an "indirect self-reference" of `x'. -`x' is not expanded in this case either. Thus, if we have - - #define x (4 + y) - #define y (2 * x) - -then `x' and `y' expand as follows: - - x ==> (4 + y) - ==> (4 + (2 * x)) - - y ==> (2 * x) - ==> (2 * (4 + y)) - -Each macro is expanded when it appears in the definition of the other -macro, but not when it indirectly appears in its own definition. - - -File: cpp.info, Node: Argument Prescan, Next: Newlines in Arguments, Prev: Self-Referential Macros, Up: Macro Pitfalls - -3.10.6 Argument Prescan ------------------------ - -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 _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 (*note -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: - - * Nested calls to a macro. - - We say that "nested" calls to a macro occur when a macro's argument - contains a call to that very macro. For example, if `f' is a macro - that expects one argument, `f (f (1))' is a nested pair of calls to - `f'. The desired expansion is made by expanding `f (1)' and - substituting that into the definition of `f'. The prescan causes - the expected result to happen. Without the prescan, `f (1)' itself - would be substituted as an argument, and the inner use of `f' would - appear during the main scan as an indirect self-reference and - would not be expanded. - - * Macros that call other macros that stringify or concatenate. - - If an argument is stringified or concatenated, the prescan does not - occur. If you _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 - - #define AFTERX(x) X_ ## x - #define XAFTERX(x) AFTERX(x) - #define TABLESIZE 1024 - #define BUFSIZE TABLESIZE - - then `AFTERX(BUFSIZE)' expands to `X_BUFSIZE', and - `XAFTERX(BUFSIZE)' expands to `X_1024'. (Not to `X_TABLESIZE'. - Prescan always does a complete expansion.) - - * 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: - - #define foo a,b - #define bar(x) lose(x) - #define lose(x) (1 + (x)) - - We would like `bar(foo)' to turn into `(1 + (foo))', which would - then turn into `(1 + (a,b))'. Instead, `bar(foo)' expands into - `lose(a,b)', and you get an error because `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: - - #define foo (a,b) - or - #define bar(x) lose((x)) - - The extra pair of parentheses prevents the comma in `foo''s - definition from being interpreted as an argument separator. - - - -File: cpp.info, Node: Newlines in Arguments, Prev: Argument Prescan, Up: Macro Pitfalls - -3.10.7 Newlines in 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: - - #define ignore_second_arg(a,b,c) a; c - - ignore_second_arg (foo (), - ignored (), - syntax error); - -The syntax error triggered by the tokens `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. - - -File: cpp.info, Node: Conditionals, Next: Diagnostics, Prev: Macros, Up: Top - -4 Conditionals -************** - -A "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 `defined' operator. - - A conditional in the C preprocessor resembles in some ways an `if' -statement in C, but it is important to understand the difference between -them. The condition in an `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 `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 `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:: - - -File: cpp.info, Node: Conditional Uses, Next: Conditional Syntax, Up: Conditionals - -4.1 Conditional Uses -==================== - -There are three general reasons to use a conditional. - - * 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. - - * 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. - - * 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. - - Simple programs that do not need system-specific logic or complex -debugging hooks generally will not need to use preprocessing -conditionals. - - -File: cpp.info, Node: Conditional Syntax, Next: Deleted Code, Prev: Conditional Uses, Up: Conditionals - -4.2 Conditional Syntax -====================== - -A conditional in the C preprocessor begins with a "conditional -directive": `#if', `#ifdef' or `#ifndef'. - -* Menu: - -* Ifdef:: -* If:: -* Defined:: -* Else:: -* Elif:: - - -File: cpp.info, Node: Ifdef, Next: If, Up: Conditional Syntax - -4.2.1 Ifdef ------------ - -The simplest sort of conditional is - - #ifdef MACRO - - CONTROLLED TEXT - - #endif /* MACRO */ - - This block is called a "conditional group". CONTROLLED TEXT will be -included in the output of the preprocessor if and only if MACRO is -defined. We say that the conditional "succeeds" if MACRO is defined, -"fails" if it is not. - - The 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, `#endif' -always matches the nearest `#ifdef' (or `#ifndef', or `#if'). Also, -you cannot start a conditional group in one file and end it in another. - - Even if a conditional fails, the 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 `#endif' is not required, but it is a good -practice if there is a lot of CONTROLLED TEXT, because it helps people -match the `#endif' to the corresponding `#ifdef'. Older programs -sometimes put MACRO directly after the `#endif' without enclosing it in -a comment. This is invalid code according to the C standard. CPP -accepts it with a warning. It never affects which `#ifndef' the -`#endif' matches. - - Sometimes you wish to use some code if a macro is _not_ defined. -You can do this by writing `#ifndef' instead of `#ifdef'. One common -use of `#ifndef' is to include code only the first time a header file -is included. *Note Once-Only Headers::. - - Macro definitions can vary between compilations for several reasons. -Here are some samples. - - * Some macros are predefined on each kind of machine (*note - System-specific Predefined Macros::). This allows you to provide - code specially tuned for a particular machine. - - * 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. - - * Macros can be defined or undefined with the `-D' and `-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. *Note Invocation::. - - * Your program might have a special header file (often called - `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 `autoconf', or done - by hand. - - -File: cpp.info, Node: If, Next: Defined, Prev: Ifdef, Up: Conditional Syntax - -4.2.2 If --------- - -The `#if' directive allows you to test the value of an arithmetic -expression, rather than the mere existence of one macro. Its syntax is - - #if EXPRESSION - - CONTROLLED TEXT - - #endif /* EXPRESSION */ - - EXPRESSION is a C expression of integer type, subject to stringent -restrictions. It may contain - - * Integer constants. - - * Character constants, which are interpreted as they would be in - normal code. - - * Arithmetic operators for addition, subtraction, multiplication, - division, bitwise operations, shifts, comparisons, and logical - operations (`&&' and `||'). The latter two obey the usual - short-circuiting rules of standard C. - - * Macros. All macros in the expression are expanded before actual - computation of the expression's value begins. - - * Uses of the `defined' operator, which lets you check whether macros - are defined in the middle of an `#if'. - - * Identifiers that are not macros, which are all considered to be the - number zero. This allows you to write `#if MACRO' instead of - `#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 `-Wundef' - option causes GCC to warn whenever it encounters an identifier - which is not a macro in an `#if'. - - The preprocessor does not know anything about types in the language. -Therefore, `sizeof' operators are not recognized in `#if', and neither -are `enum' constants. They will be taken as identifiers which are not -macros, and replaced by zero. In the case of `sizeof', this is likely -to cause the expression to be invalid. - - The preprocessor calculates the value of 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 `#if' succeeds and the CONTROLLED TEXT is -included; otherwise it is skipped. - - -File: cpp.info, Node: Defined, Next: Else, Prev: If, Up: Conditional Syntax - -4.2.3 Defined -------------- - -The special operator `defined' is used in `#if' and `#elif' expressions -to test whether a certain name is defined as a macro. `defined NAME' -and `defined (NAME)' are both expressions whose value is 1 if NAME is -defined as a macro at the current point in the program, and 0 -otherwise. Thus, `#if defined MACRO' is precisely equivalent to -`#ifdef MACRO'. - - `defined' is useful when you wish to test more than one macro for -existence at once. For example, - - #if defined (__vax__) || defined (__ns16000__) - -would succeed if either of the names `__vax__' or `__ns16000__' is -defined as a macro. - - Conditionals written like this: - - #if defined BUFSIZE && BUFSIZE >= 1024 - -can generally be simplified to just `#if BUFSIZE >= 1024', since if -`BUFSIZE' is not defined, it will be interpreted as having the value -zero. - - If the `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 `defined' operator and evaluates it normally. It will warn -wherever your code uses this feature if you use the command-line option -`-pedantic', since other compilers may handle it differently. - - -File: cpp.info, Node: Else, Next: Elif, Prev: Defined, Up: Conditional Syntax - -4.2.4 Else ----------- - -The `#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: - - #if EXPRESSION - TEXT-IF-TRUE - #else /* Not EXPRESSION */ - TEXT-IF-FALSE - #endif /* Not EXPRESSION */ - -If EXPRESSION is nonzero, the TEXT-IF-TRUE is included and the -TEXT-IF-FALSE is skipped. If EXPRESSION is zero, the opposite happens. - - You can use `#else' with `#ifdef' and `#ifndef', too. - - -File: cpp.info, Node: Elif, Prev: Else, Up: Conditional Syntax - -4.2.5 Elif ----------- - -One common case of nested conditionals is used to check for more than -two possible alternatives. For example, you might have - - #if X == 1 - ... - #else /* X != 1 */ - #if X == 2 - ... - #else /* X != 2 */ - ... - #endif /* X != 2 */ - #endif /* X != 1 */ - - Another conditional directive, `#elif', allows this to be -abbreviated as follows: - - #if X == 1 - ... - #elif X == 2 - ... - #else /* X != 2 and X != 1*/ - ... - #endif /* X != 2 and X != 1*/ - - `#elif' stands for "else if". Like `#else', it goes in the middle -of a conditional group and subdivides it; it does not require a -matching `#endif' of its own. Like `#if', the `#elif' directive -includes an expression to be tested. The text following the `#elif' is -processed only if the original `#if'-condition failed and the `#elif' -condition succeeds. - - More than one `#elif' can go in the same conditional group. Then -the text after each `#elif' is processed only if the `#elif' condition -succeeds after the original `#if' and all previous `#elif' directives -within it have failed. - - `#else' is allowed after any number of `#elif' directives, but -`#elif' may not follow `#else'. - - -File: cpp.info, Node: Deleted Code, Prev: Conditional Syntax, Up: Conditionals - -4.3 Deleted 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 `#if 0' before the deleted code and -`#endif' after it. This works even if the code being turned off -contains conditionals, but they must be entire conditionals (balanced -`#if' and `#endif'). - - Some people use `#ifdef notdef' instead. This is risky, because -`notdef' might be accidentally defined as a macro, and then the -conditional would succeed. `#if 0' can be counted on to fail. - - Do not use `#if 0' for comments which are not C code. Use a real -comment, instead. The interior of `#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 `#if 0'. They don't confuse `/*'. - - -File: cpp.info, Node: Diagnostics, Next: Line Control, Prev: Conditionals, Up: Top - -5 Diagnostics -************* - -The directive `#error' causes the preprocessor to report a fatal error. -The tokens forming the rest of the line following `#error' are used as -the error message. - - You would use `#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 - - #ifdef __vax__ - #error "Won't work on VAXen. See comments at get_last_object." - #endif - - 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 `#error'. For example, - - #if !defined(UNALIGNED_INT_ASM_OP) && defined(DWARF2_DEBUGGING_INFO) - #error "DWARF2_DEBUGGING_INFO requires UNALIGNED_INT_ASM_OP." - #endif - - The directive `#warning' is like `#error', but causes the -preprocessor to issue a warning and continue preprocessing. The tokens -following `#warning' are used as the warning message. - - You might use `#warning' in obsolete header files, with a message -directing the user to the header file which should be used instead. - - Neither `#error' nor `#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. - - -File: cpp.info, Node: Line Control, Next: Pragmas, Prev: Diagnostics, Up: Top - -6 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 -`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 `bison' are generated from scratch, other parts come from a -standard parser file. The rest are copied verbatim from `bison''s -input. You would like compiler error messages and symbolic debuggers -to be able to refer to `bison''s input file. - - `bison' or any such program can arrange this by writing `#line' -directives into the output file. `#line' is a directive that specifies -the original line number and source file name for subsequent input in -the current preprocessor input file. `#line' has three variants: - -`#line LINENUM' - 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 LINENUM. - -`#line LINENUM FILENAME' - LINENUM is the same as for the first form, and has the same - effect. In addition, 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. - FILENAME is interpreted according to the normal rules for a string - constant: backslash escapes are interpreted. This is different - from `#include'. - - Previous versions of CPP did not interpret escapes in `#line'; we - have changed it because the standard requires they be interpreted, - and most other compilers do. - -`#line ANYTHING ELSE' - ANYTHING ELSE is checked for macro calls, which are expanded. The - result should match one of the above two forms. - - `#line' directives alter the results of the `__FILE__' and -`__LINE__' predefined macros from that point on. *Note Standard -Predefined Macros::. They do not have any effect on `#include''s idea -of the directory containing the current file. This is a change from -GCC 2.95. Previously, a file reading - - #line 1 "../src/gram.y" - #include "gram.h" - - would search for `gram.h' in `../src', then the `-I' chain; the -directory containing the physical source file would not be searched. -In GCC 3.0 and later, the `#include' is not affected by the presence of -a `#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 `#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 -`-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. - - -File: cpp.info, Node: Pragmas, Next: Other Directives, Prev: Line Control, Up: Top - -7 Pragmas -********* - -The `#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 "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 `__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 `GCC' prefix. This is in line with the `STDC' prefix on all pragmas -defined by C99. For backward compatibility, pragmas which were -recognized by previous versions are still recognized without the `GCC' -prefix, but that usage is deprecated. Some older pragmas are -deprecated in their entirety. They are not recognized with the `GCC' -prefix. *Note Obsolete Features::. - - C99 introduces the `_Pragma' operator. This feature addresses a -major problem with `#pragma': being a directive, it cannot be produced -as the result of macro expansion. `_Pragma' is an operator, much like -`sizeof' or `defined', and can be embedded in a macro. - - Its syntax is `_Pragma (STRING-LITERAL)', where STRING-LITERAL can -be either a normal or wide-character string literal. It is -destringized, by replacing all `\\' with a single `\' and all `\"' with -a `"'. The result is then processed as if it had appeared as the right -hand side of a `#pragma' directive. For example, - - _Pragma ("GCC dependency \"parse.y\"") - -has the same effect as `#pragma GCC dependency "parse.y"'. The same -effect could be achieved using macros, for example - - #define DO_PRAGMA(x) _Pragma (#x) - DO_PRAGMA (GCC dependency "parse.y") - - The standard is unclear on where a `_Pragma' operator can appear. -The preprocessor does not accept it within a preprocessing conditional -directive like `#if'. To be safe, you are probably best keeping it out -of directives other than `#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. - -`#pragma GCC dependency' - `#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. - - #pragma GCC dependency "parse.y" - #pragma GCC dependency "/usr/include/time.h" rerun fixincludes - -`#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 "poison" the identifier with - this pragma. `#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, - - #pragma GCC poison printf sprintf fprintf - sprintf(some_string, "hello"); - - 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 _not_ cause an error. This lets you poison an identifier - without worrying about system headers defining macros that use it. - - For example, - - #define strrchr rindex - #pragma GCC poison rindex - strrchr(some_string, 'h'); - - will not produce an error. - -`#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. - *Note System Headers::. - - - -File: cpp.info, Node: Other Directives, Next: Preprocessor Output, Prev: Pragmas, Up: Top - -8 Other Directives -****************** - -The `#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. The `#sccs' -directive is a synonym for `#ident'. - - These directives are not part of the C standard, but they are not -official GNU extensions either. What historical information we have -been able to find, suggests they originated with System V. - - Both `#ident' and `#sccs' are deprecated extensions. - - The "null directive" consists of a `#' 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 `#' will -produce no output, rather than a line of output containing just a `#'. -Supposedly some old C programs contain such lines. - - -File: cpp.info, Node: Preprocessor Output, Next: Traditional Mode, Prev: Other Directives, Up: Top - -9 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. - - 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. *Note -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. - - Source file name and line number information is conveyed by lines of -the form - - # LINENUM FILENAME FLAGS - -These are called "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 FILENAME at line LINENUM. -FILENAME will never contain any non-printing characters; they are -replaced with octal escape sequences. - - After the file name comes zero or more flags, which are `1', `2', -`3', or `4'. If there are multiple flags, spaces separate them. Here -is what the flags mean: - -`1' - This indicates the start of a new file. - -`2' - This indicates returning to a file (after having included another - file). - -`3' - This indicates that the following text comes from a system header - file, so certain warnings should be suppressed. - -`4' - This indicates that the following text should be treated as being - wrapped in an implicit `extern "C"' block. - - As an extension, the preprocessor accepts linemarkers in -non-assembler input files. They are treated like the corresponding -`#line' directive, (*note 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 `#ident' (always), `#pragma' (only if the preprocessor does -not handle the pragma itself), and `#define' and `#undef' (with certain -debugging options). If this happens, the `#' of the directive will -always be in the first column, and there will be no space between the -`#' 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 `#' and the directive name. - - -File: cpp.info, Node: Traditional Mode, Next: Implementation Details, Prev: Preprocessor Output, Up: Top - -10 Traditional Mode -******************* - -Traditional (pre-standard) C preprocessing is rather different from the -preprocessing specified by the standard. When GCC is given the -`-traditional-cpp' option, it attempts to emulate a traditional -preprocessor. - - GCC versions 3.2 and later only support traditional mode semantics in -the preprocessor, and not in the compiler front ends. This chapter -outlines the traditional preprocessor semantics we implemented. - - The implementation does not correspond precisely to the behavior of -earlier versions of GCC, nor to any true traditional preprocessor. -After all, inconsistencies among traditional implementations were a -major motivation for C standardization. However, we intend that it -should be compatible with true traditional preprocessors in all ways -that actually matter. - -* Menu: - -* Traditional lexical analysis:: -* Traditional macros:: -* Traditional miscellany:: -* Traditional warnings:: - - -File: cpp.info, Node: Traditional lexical analysis, Next: Traditional macros, Up: Traditional Mode - -10.1 Traditional lexical analysis -================================= - -The traditional preprocessor does not decompose its input into tokens -the same way a standards-conforming preprocessor does. The input is -simply treated as a stream of text with minimal internal form. - - This implementation does not treat trigraphs (*note trigraphs::) -specially since they were an invention of the standards committee. It -handles arbitrarily-positioned escaped newlines properly and splices -the lines as you would expect; many traditional preprocessors did not -do this. - - The form of horizontal whitespace in the input file is preserved in -the output. In particular, hard tabs remain hard tabs. This can be -useful if, for example, you are preprocessing a Makefile. - - Traditional CPP only recognizes C-style block comments, and treats -the `/*' sequence as introducing a comment only if it lies outside -quoted text. Quoted text is introduced by the usual single and double -quotes, and also by an initial `<' in a `#include' directive. - - Traditionally, comments are completely removed and are not replaced -with a space. Since a traditional compiler does its own tokenization -of the output of the preprocessor, this means that comments can -effectively be used as token paste operators. However, comments behave -like separators for text handled by the preprocessor itself, since it -doesn't re-lex its input. For example, in - - #if foo/**/bar - -`foo' and `bar' are distinct identifiers and expanded separately if -they happen to be macros. In other words, this directive is equivalent -to - - #if foo bar - -rather than - - #if foobar - - Generally speaking, in traditional mode an opening quote need not -have a matching closing quote. In particular, a macro may be defined -with replacement text that contains an unmatched quote. Of course, if -you attempt to compile preprocessed output containing an unmatched quote -you will get a syntax error. - - However, all preprocessing directives other than `#define' require -matching quotes. For example: - - #define m This macro's fine and has an unmatched quote - "/* This is not a comment. */ - /* This is a comment. The following #include directive - is ill-formed. */ - #include ++foo; - - Function-like macros are similar in form but quite different in -behavior to their ISO counterparts. Their arguments are contained -within parentheses, are comma-separated, and can cross physical lines. -Commas within nested parentheses are not treated as argument -separators. Similarly, a quote in an argument cannot be left unclosed; -a following comma or parenthesis that comes before the closing quote is -treated like any other character. There is no facility for handling -variadic macros. - - This implementation removes all comments from macro arguments, unless -the `-C' option is given. The form of all other horizontal whitespace -in arguments is preserved, including leading and trailing whitespace. -In particular - - f( ) - -is treated as an invocation of the macro `f' with a single argument -consisting of a single space. If you want to invoke a function-like -macro that takes no arguments, you must not leave any whitespace -between the parentheses. - - If a macro argument crosses a new line, the new line is replaced with -a space when forming the argument. If the previous line contained an -unterminated quote, the following line inherits the quoted state. - - Traditional preprocessors replace parameters in the replacement text -with their arguments regardless of whether the parameters are within -quotes or not. This provides a way to stringize arguments. For example - - #define str(x) "x" - str(/* A comment */some text ) - ==> "some text " - -Note that the comment is removed, but that the trailing space is -preserved. Here is an example of using a comment to effect token -pasting. - - #define suffix(x) foo_/**/x - suffix(bar) - ==> foo_bar - - -File: cpp.info, Node: Traditional miscellany, Next: Traditional warnings, Prev: Traditional macros, Up: Traditional Mode - -10.3 Traditional miscellany -=========================== - -Here are some things to be aware of when using the traditional -preprocessor. - - * Preprocessing directives are recognized only when their leading - `#' appears in the first column. There can be no whitespace - between the beginning of the line and the `#', but whitespace can - follow the `#'. - - * A true traditional C preprocessor does not recognize `#error' or - `#pragma', and may not recognize `#elif'. CPP supports all the - directives in traditional mode that it supports in ISO mode, - including extensions, with the exception that the effects of - `#pragma GCC poison' are undefined. - - * __STDC__ is not defined. - - * If you use digraphs the behavior is undefined. - - * If a line that looks like a directive appears within macro - arguments, the behavior is undefined. - - - -File: cpp.info, Node: Traditional warnings, Prev: Traditional miscellany, Up: Traditional Mode - -10.4 Traditional warnings -========================= - -You can request warnings about features that did not exist, or worked -differently, in traditional C with the `-Wtraditional' option. GCC -does not warn about features of ISO C which you must use when you are -using a conforming compiler, such as the `#' and `##' operators. - - Presently `-Wtraditional' warns about: - - * 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. - - * In traditional C, some preprocessor directives did not exist. - Traditional preprocessors would only consider a line to be a - directive if the `#' appeared in column 1 on the line. Therefore - `-Wtraditional' warns about directives that traditional C - understands but would ignore because the `#' does not appear as the - first character on the line. It also suggests you hide directives - like `#pragma' not understood by traditional C by indenting them. - Some traditional implementations would not recognize `#elif', so it - suggests avoiding it altogether. - - * A function-like macro that appears without an argument list. In - some traditional preprocessors this was an error. In ISO C it - merely means that the macro is not expanded. - - * The unary plus operator. This did not exist in traditional C. - - * The `U' and `LL' integer constant suffixes, which were not - available in traditional C. (Traditional C does support the `L' - suffix for simple long integer constants.) You are not warned - about uses of these suffixes in macros defined in system headers. - For instance, `UINT_MAX' may well be defined as `4294967295U', but - you will not be warned if you use `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. - - -File: cpp.info, Node: Implementation Details, Next: Invocation, Prev: Traditional Mode, Up: Top - -11 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 CPP. - -* Menu: - -* Implementation-defined behavior:: -* Implementation limits:: -* Obsolete Features:: -* Differences from previous versions:: - - -File: cpp.info, Node: Implementation-defined behavior, Next: Implementation limits, Up: Implementation Details - -11.1 Implementation-defined behavior -==================================== - -This is how CPP behaves in all the cases which the C standard describes -as "implementation-defined". This term means that the implementation -is free to do what it likes, but must document its choice and stick to -it. - - * The mapping of physical source file multi-byte characters to the - execution character set. - - The input character set can be specified using the - `-finput-charset' option, while the execution character set may be - controlled using the `-fexec-charset' and `-fwide-exec-charset' - options. - - * Identifier characters. The C and C++ standards allow identifiers - to be composed of `_' and the alphanumeric characters. C++ and - C99 also allow universal character names, and C99 further permits - implementation-defined characters. GCC currently only permits - universal character names if `-fextended-identifiers' is used, - because the implementation of universal character names in - identifiers is experimental. - - GCC allows the `$' character in identifiers as an extension for - most targets. This is true regardless of the `std=' switch, since - this extension cannot conflict with standards-conforming programs. - When preprocessing assembler, however, dollars are not identifier - characters by default. - - Currently the targets that by default do not permit `$' are AVR, - IP2K, MMIX, MIPS Irix 3, ARM aout, and PowerPC targets for the AIX - operating system. - - You can override the default with `-fdollars-in-identifiers' or - `fno-dollars-in-identifiers'. *Note fdollars-in-identifiers::. - - * 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. - - * The numeric value of character constants in preprocessor - expressions. - - The preprocessor and compiler interpret character constants in the - same way; i.e. escape sequences such as `\a' are given the values - they would have on the target machine. - - The compiler values a multi-character character constant a - character at a time, shifting the previous value left by the - number of bits per target character, and then or-ing in the - bit-pattern of the new character truncated to the width of a - target character. The final bit-pattern is given type `int', and - is therefore signed, regardless of whether single characters are - signed or not (a slight change from versions 3.1 and earlier of - GCC). If there are more characters in the constant than would fit - in the target `int' the compiler issues a warning, and the excess - leading characters are ignored. - - For example, `'ab'' for a target with an 8-bit `char' would be - interpreted as - `(int) ((unsigned char) 'a' * 256 + (unsigned char) 'b')', and - `'\234a'' as - `(int) ((unsigned char) '\234' * 256 + (unsigned char) 'a')'. - - * Source file inclusion. - - For a discussion on how the preprocessor locates header files, - *note Include Operation::. - - * Interpretation of the filename resulting from a macro-expanded - `#include' directive. - - *Note Computed Includes::. - - * Treatment of a `#pragma' directive that after macro-expansion - results in a standard pragma. - - No macro expansion occurs on any `#pragma' directive line, so the - question does not arise. - - Note that GCC does not yet implement any of the standard pragmas. - - - -File: cpp.info, Node: Implementation limits, Next: Obsolete Features, Prev: Implementation-defined behavior, Up: Implementation Details - -11.2 Implementation limits -========================== - -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 known. It is intended that there should be as few -limits as possible. If you encounter an undocumented or inconvenient -limit, please report that as a bug. *Note Reporting Bugs: (gcc)Bugs. - - Where we say something is limited "only by available memory", that -means that internal data structures impose no intrinsic limit, and space -is allocated with `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. - - * Nesting levels of `#include' files. - - We impose an arbitrary limit of 200 levels, to avoid runaway - recursion. The standard requires at least 15 levels. - - * Nesting levels of conditional inclusion. - - The C standard mandates this be at least 63. CPP is limited only - by available memory. - - * Levels of parenthesized 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. - - * 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. - - * Number of macros simultaneously defined in a single translation - unit. - - The standard requires at least 4095 be possible. CPP is limited - only by available memory. - - * Number of parameters in a macro definition and arguments in a - macro call. - - We allow `USHRT_MAX', which is no smaller than 65,535. The minimum - required by the standard is 127. - - * Number of characters on a logical source line. - - The C standard requires a minimum of 4096 be permitted. CPP places - no limits on this, but you may get incorrect column numbers - reported in diagnostics for lines longer than 65,535 characters. - - * 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. - - - -File: cpp.info, Node: Obsolete Features, Next: Differences from previous versions, Prev: Implementation limits, Up: Implementation Details - -11.3 Obsolete Features -====================== - -CPP has some 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. - -11.3.1 Assertions ------------------ - -"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 *less* portable than the use -of system-specific predefined macros. We recommend you do not use them -at all. - - An assertion looks like this: - - #PREDICATE (ANSWER) - -PREDICATE must be a single identifier. 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, `(x + y)' is different from `(x+y)' but equivalent to -`( x + y )'. Parentheses do not nest inside an answer. - - To test an assertion, you write it in an `#if'. For example, this -conditional succeeds if either `vax' or `ns16000' has been asserted as -an answer for `machine'. - - #if #machine (vax) || #machine (ns16000) - -You can test whether _any_ answer is asserted for a predicate by -omitting the answer in the conditional: - - #if #machine - - Assertions are made with the `#assert' directive. Its sole argument -is the assertion to make, without the leading `#' that identifies -assertions in conditionals. - - #assert PREDICATE (ANSWER) - -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. - - Assertions can be canceled with the `#unassert' directive. It has -the same syntax as `#assert'. In that form it cancels only the answer -which was specified on the `#unassert' line; other answers for that -predicate remain true. You can cancel an entire predicate by leaving -out the answer: - - #unassert PREDICATE - -In either form, if no such assertion has been made, `#unassert' has no -effect. - - You can also make or cancel assertions using command line options. -*Note Invocation::. - - -File: cpp.info, Node: Differences from previous versions, Prev: Obsolete Features, Up: Implementation Details - -11.4 Differences from previous versions -======================================= - -This section details behavior which has changed from previous versions -of 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. - - * -I- deprecated - - This option has been deprecated in 4.0. `-iquote' is meant to - replace the need for this option. - - * Order of evaluation of `#' and `##' operators - - The standard does not specify the order of evaluation of a chain of - `##' operators, nor whether `#' is evaluated before, after, or at - the same time as `##'. 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 `1', - `e' and `-2'. This would be fine for left-to-right pasting, but - right-to-left pasting would produce an invalid token `e-2'. - - GCC 3.0 evaluates `#' and `##' at the same time and strictly left - to right. Older versions evaluated all `#' operators first, then - all `##' operators, in an unreliable order. - - * The form of whitespace between tokens in preprocessor output - - *Note 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. - - * 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. - - * `##' swallowing preceding text in rest argument macros - - Formerly, in a macro expansion, if `##' appeared before a variable - arguments parameter, and the set of tokens specified for that - argument in the macro invocation was empty, previous versions of - CPP would back up and remove the preceding sequence of - non-whitespace characters (*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 `##' 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 - `##' is not a comma, then `##' behaves as a normal token paste. - - * `#line' and `#include' - - The `#line' directive used to change GCC's notion of the - "directory containing the current file", used by `#include' with a - double-quoted header file name. In 3.0 and later, it does not. - *Note Line Control::, for further explanation. - - * Syntax of `#line' - - In GCC 2.95 and previous, the string constant argument to `#line' - was treated the same way as the argument to `#include': backslash - escapes were not honored, and the string ended at the second `"'. - This is not compliant with the C standard. In GCC 3.0, an attempt - was made to correct the behavior, so that the string was treated - as a real string constant, but it turned out to be buggy. In 3.1, - the bugs have been fixed. (We are not fixing the bugs in 3.0 - because they affect relatively few people and the fix is quite - invasive.) - - - -File: cpp.info, Node: Invocation, Next: Environment Variables, Prev: Implementation Details, Up: Top - -12 Invocation -************* - -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. - - _Note:_ Whether you use the preprocessor by way of `gcc' or `cpp', -the "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. - - The C preprocessor expects two file names as arguments, INFILE and -OUTFILE. The preprocessor reads INFILE together with any other files -it specifies with `#include'. All the output generated by the combined -input files is written in OUTFILE. - - Either INFILE or OUTFILE may be `-', which as INFILE means to read -from standard input and as OUTFILE means to write to standard output. -Also, if either file is omitted, it means the same as if `-' had been -specified for that file. - - Unless otherwise noted, or the option ends in `=', all options which -take an argument may have that argument appear either immediately after -the option, or with a space between option and argument: `-Ifoo' and -`-I foo' have the same effect. - - Many options have multi-letter names; therefore multiple -single-letter options may _not_ be grouped: `-dM' is very different from -`-d -M'. - -`-D NAME' - Predefine NAME as a macro, with definition `1'. - -`-D NAME=DEFINITION' - The contents of DEFINITION are tokenized and processed as if they - appeared during translation phase three in a `#define' directive. - In particular, the definition will be truncated by embedded - newline characters. - - 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 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 `sh' and `csh', - `-D'NAME(ARGS...)=DEFINITION'' works. - - `-D' and `-U' options are processed in the order they are given on - the command line. All `-imacros FILE' and `-include FILE' options - are processed after all `-D' and `-U' options. - -`-U NAME' - Cancel any previous definition of NAME, either built in or - provided with a `-D' option. - -`-undef' - Do not predefine any system-specific or GCC-specific macros. The - standard predefined macros remain defined. *Note Standard - Predefined Macros::. - -`-I DIR' - Add the directory DIR to the list of directories to be searched - for header files. *Note Search Path::. Directories named by `-I' - are searched before the standard system include directories. If - the directory DIR is a standard system include directory, the - option is ignored to ensure that the default search order for - system directories and the special treatment of system headers are - not defeated (*note System Headers::) . If DIR begins with `=', - then the `=' will be replaced by the sysroot prefix; see - `--sysroot' and `-isysroot'. - -`-o FILE' - Write output to FILE. This is the same as specifying FILE as the - second non-option argument to `cpp'. `gcc' has a different - interpretation of a second non-option argument, so you must use - `-o' to specify the output file. - -`-Wall' - Turns on all optional warnings which are desirable for normal code. - At present this is `-Wcomment', `-Wtrigraphs', `-Wmultichar' and a - warning about integer promotion causing a change of sign in `#if' - expressions. Note that many of the preprocessor's warnings are on - by default and have no options to control them. - -`-Wcomment' -`-Wcomments' - Warn whenever a comment-start sequence `/*' appears in a `/*' - comment, or whenever a backslash-newline appears in a `//' comment. - (Both forms have the same effect.) - -`-Wtrigraphs' - Most trigraphs in comments cannot affect the meaning of the - program. However, a trigraph that would form an escaped newline - (`??/' at the end of a line) can, by changing where the comment - begins or ends. Therefore, only trigraphs that would form escaped - newlines produce warnings inside a comment. - - This option is implied by `-Wall'. If `-Wall' is not given, this - option is still enabled unless trigraphs are enabled. To get - trigraph conversion without warnings, but get the other `-Wall' - warnings, use `-trigraphs -Wall -Wno-trigraphs'. - -`-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. *Note Traditional Mode::. - -`-Wundef' - Warn whenever an identifier which is not a macro is encountered in - an `#if' directive, outside of `defined'. Such identifiers are - replaced with zero. - -`-Wunused-macros' - Warn about macros defined in the main file that are unused. A - macro is "used" if it is expanded or tested for existence at least - once. The preprocessor will also warn if the macro has not been - used at the time it is redefined or undefined. - - Built-in macros, macros defined on the command line, and macros - defined in include files are not warned about. - - _Note:_ If a macro is actually used, but only used in skipped - conditional blocks, then CPP will report it as unused. To avoid - the warning in such a case, you might improve the scope of the - macro's definition by, for example, moving it into the first - skipped block. Alternatively, you could provide a dummy use with - something like: - - #if defined the_macro_causing_the_warning - #endif - -`-Wendif-labels' - Warn whenever an `#else' or an `#endif' are followed by text. - This usually happens in code of the form - - #if FOO - ... - #else FOO - ... - #endif FOO - - The second and third `FOO' should be in comments, but often are not - in older programs. This warning is on by default. - -`-Werror' - Make all warnings into hard errors. Source code which triggers - warnings will be rejected. - -`-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. - -`-w' - Suppress all warnings, including those which GNU CPP issues by - default. - -`-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. - -`-pedantic-errors' - Issue all the mandatory diagnostics, and make all mandatory - diagnostics into errors. This includes mandatory diagnostics that - GCC issues without `-pedantic' but treats as warnings. - -`-M' - Instead of outputting the result of preprocessing, output a rule - suitable for `make' describing the dependencies of the main source - file. The preprocessor outputs one `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 `-include' or - `-imacros' command line options. - - Unless specified explicitly (with `-MT' or `-MQ'), the object file - name consists of the name of the source file with any suffix - replaced with object file suffix and with any leading directory - parts removed. If there are many included files then the rule is - split into several lines using `\'-newline. The rule has no - commands. - - This option does not suppress the preprocessor's debug output, - such as `-dM'. To avoid mixing such debug output with the - dependency rules you should explicitly specify the dependency - output file with `-MF', or use an environment variable like - `DEPENDENCIES_OUTPUT' (*note Environment Variables::). Debug - output will still be sent to the regular output stream as normal. - - Passing `-M' to the driver implies `-E', and suppresses warnings - with an implicit `-w'. - -`-MM' - Like `-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 `#include' directive does not in itself determine whether that - header will appear in `-MM' dependency output. This is a slight - change in semantics from GCC versions 3.0 and earlier. - -`-MF FILE' - When used with `-M' or `-MM', specifies a file to write the - dependencies to. If no `-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 `-MD' or `-MMD', `-MF' overrides - the default dependency output file. - -`-MG' - In conjunction with an option such as `-M' requesting dependency - generation, `-MG' assumes missing header files are generated files - and adds them to the dependency list without raising an error. - The dependency filename is taken directly from the `#include' - directive without prepending any path. `-MG' also suppresses - preprocessed output, as a missing header file renders this useless. - - This feature is used in automatic updating of makefiles. - -`-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 `make' gives if you remove header - files without updating the `Makefile' to match. - - This is typical output: - - test.o: test.c test.h - - test.h: - -`-MT TARGET' - Change the target of the rule emitted by dependency generation. By - default CPP takes the name of the main input file, deletes any - directory components and any file suffix such as `.c', and appends - the platform's usual object suffix. The result is the target. - - An `-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 `-MT', or use multiple `-MT' options. - - For example, `-MT '$(objpfx)foo.o'' might give - - $(objpfx)foo.o: foo.c - -`-MQ TARGET' - Same as `-MT', but it quotes any characters which are special to - Make. `-MQ '$(objpfx)foo.o'' gives - - $$(objpfx)foo.o: foo.c - - The default target is automatically quoted, as if it were given - with `-MQ'. - -`-MD' - `-MD' is equivalent to `-M -MF FILE', except that `-E' is not - implied. The driver determines FILE based on whether an `-o' - option is given. If it is, the driver uses its argument but with - a suffix of `.d', otherwise it takes the name of the input file, - removes any directory components and suffix, and applies a `.d' - suffix. - - If `-MD' is used in conjunction with `-E', any `-o' switch is - understood to specify the dependency output file (*note -MF: - dashMF.), but if used without `-E', each `-o' is understood to - specify a target object file. - - Since `-E' is not implied, `-MD' can be used to generate a - dependency output file as a side-effect of the compilation process. - -`-MMD' - Like `-MD' except mention only user header files, not system - header files. - -`-x c' -`-x c++' -`-x objective-c' -`-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: `.c', `.cc', `.m', or `.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. - - _Note:_ Previous versions of cpp accepted a `-lang' option which - selected both the language and the standards conformance level. - This option has been removed, because it conflicts with the `-l' - option. - -`-std=STANDARD' -`-ansi' - Specify the standard to which the code should conform. Currently - CPP knows about C and C++ standards; others may be added in the - future. - - STANDARD may be one of: - `iso9899:1990' - `c89' - The ISO C standard from 1990. `c89' is the customary - shorthand for this version of the standard. - - The `-ansi' option is equivalent to `-std=c89'. - - `iso9899:199409' - The 1990 C standard, as amended in 1994. - - `iso9899:1999' - `c99' - `iso9899:199x' - `c9x' - The revised ISO C standard, published in December 1999. - Before publication, this was known as C9X. - - `gnu89' - The 1990 C standard plus GNU extensions. This is the default. - - `gnu99' - `gnu9x' - The 1999 C standard plus GNU extensions. - - `c++98' - The 1998 ISO C++ standard plus amendments. - - `gnu++98' - The same as `-std=c++98' plus GNU extensions. This is the - default for C++ code. - -`-I-' - Split the include path. Any directories specified with `-I' - options before `-I-' are searched only for headers requested with - `#include "FILE"'; they are not searched for `#include '. - If additional directories are specified with `-I' options after - the `-I-', those directories are searched for all `#include' - directives. - - In addition, `-I-' inhibits the use of the directory of the current - file directory as the first search directory for `#include "FILE"'. - *Note Search Path::. This option has been deprecated. - -`-nostdinc' - Do not search the standard system directories for header files. - Only the directories you have specified with `-I' options (and the - directory of the current file, if appropriate) are searched. - -`-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.) - -`-include FILE' - Process FILE as if `#include "file"' appeared as the first line of - the primary source file. However, the first directory searched - for FILE is the preprocessor's working directory _instead of_ the - directory containing the main source file. If not found there, it - is searched for in the remainder of the `#include "..."' search - chain as normal. - - If multiple `-include' options are given, the files are included - in the order they appear on the command line. - -`-imacros FILE' - Exactly like `-include', except that any output produced by - scanning 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 `-imacros' are processed before all files - specified by `-include'. - -`-idirafter DIR' - Search DIR for header files, but do it _after_ all directories - specified with `-I' and the standard system directories have been - exhausted. DIR is treated as a system include directory. If DIR - begins with `=', then the `=' will be replaced by the sysroot - prefix; see `--sysroot' and `-isysroot'. - -`-iprefix PREFIX' - Specify PREFIX as the prefix for subsequent `-iwithprefix' - options. If the prefix represents a directory, you should include - the final `/'. - -`-iwithprefix DIR' -`-iwithprefixbefore DIR' - Append DIR to the prefix specified previously with `-iprefix', and - add the resulting directory to the include search path. - `-iwithprefixbefore' puts it in the same place `-I' would; - `-iwithprefix' puts it where `-idirafter' would. - -`-isysroot DIR' - This option is like the `--sysroot' option, but applies only to - header files. See the `--sysroot' option for more information. - -`-imultilib DIR' - Use DIR as a subdirectory of the directory containing - target-specific C++ headers. - -`-isystem DIR' - Search DIR for header files, after all directories specified by - `-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. *Note System - Headers::. If DIR begins with `=', then the `=' will be replaced - by the sysroot prefix; see `--sysroot' and `-isysroot'. - -`-iquote DIR' - Search DIR only for header files requested with `#include "FILE"'; - they are not searched for `#include ', before all - directories specified by `-I' and before the standard system - directories. *Note Search Path::. If DIR begins with `=', then - the `=' will be replaced by the sysroot prefix; see `--sysroot' - and `-isysroot'. - -`-fdirectives-only' - When preprocessing, handle directives, but do not expand macros. - - The option's behavior depends on the `-E' and `-fpreprocessed' - options. - - With `-E', preprocessing is limited to the handling of directives - such as `#define', `#ifdef', and `#error'. Other preprocessor - operations, such as macro expansion and trigraph conversion are - not performed. In addition, the `-dD' option is implicitly - enabled. - - With `-fpreprocessed', predefinition of command line and most - builtin macros is disabled. Macros such as `__LINE__', which are - contextually dependent, are handled normally. This enables - compilation of files previously preprocessed with `-E - -fdirectives-only'. - - With both `-E' and `-fpreprocessed', the rules for - `-fpreprocessed' take precedence. This enables full preprocessing - of files previously preprocessed with `-E -fdirectives-only'. - -`-fdollars-in-identifiers' - Accept `$' in identifiers. *Note Identifier characters::. - -`-fextended-identifiers' - Accept universal character names in identifiers. This option is - experimental; in a future version of GCC, it will be enabled by - default for C99 and C++. - -`-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 `-C' to - the compiler without problems. In this mode the integrated - preprocessor is little more than a tokenizer for the front ends. - - `-fpreprocessed' is implicit if the input file has one of the - extensions `.i', `.ii' or `.mi'. These are the extensions that - GCC uses for preprocessed files created by `-save-temps'. - -`-ftabstop=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. - -`-fexec-charset=CHARSET' - Set the execution character set, used for string and character - constants. The default is UTF-8. CHARSET can be any encoding - supported by the system's `iconv' library routine. - -`-fwide-exec-charset=CHARSET' - Set the wide execution character set, used for wide string and - character constants. The default is UTF-32 or UTF-16, whichever - corresponds to the width of `wchar_t'. As with `-fexec-charset', - CHARSET can be any encoding supported by the system's `iconv' - library routine; however, you will have problems with encodings - that do not fit exactly in `wchar_t'. - -`-finput-charset=CHARSET' - Set the input character set, used for translation from the - character set of the input file to the source character set used - by GCC. If the locale does not specify, or GCC cannot get this - information from the locale, the default is UTF-8. This can be - overridden by either the locale or this command line option. - Currently the command line option takes precedence if there's a - conflict. CHARSET can be any encoding supported by the system's - `iconv' library routine. - -`-fworking-directory' - Enable generation of linemarkers in the preprocessor output that - will let the compiler know the current working directory at the - time of preprocessing. When this option is enabled, the - preprocessor will emit, after the initial linemarker, a second - linemarker with the current working directory followed by two - slashes. GCC will use this directory, when it's present in the - preprocessed input, as the directory emitted as the current - working directory in some debugging information formats. This - option is implicitly enabled if debugging information is enabled, - but this can be inhibited with the negated form - `-fno-working-directory'. If the `-P' flag is present in the - command line, this option has no effect, since no `#line' - directives are emitted whatsoever. - -`-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 `dejagnu'. - -`-A PREDICATE=ANSWER' - Make an assertion with the predicate PREDICATE and answer ANSWER. - This form is preferred to the older form `-A PREDICATE(ANSWER)', - which is still supported, because it does not use shell special - characters. *Note Obsolete Features::. - -`-A -PREDICATE=ANSWER' - Cancel an assertion with the predicate PREDICATE and answer ANSWER. - -`-dCHARS' - 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. - - `M' - Instead of the normal output, generate a list of `#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 `foo.h', the - command - - touch foo.h; cpp -dM foo.h - - will show all the predefined macros. - - If you use `-dM' without the `-E' option, `-dM' is - interpreted as a synonym for `-fdump-rtl-mach'. *Note - Debugging Options: (gcc)Debugging Options. - - `D' - Like `M' except in two respects: it does _not_ include the - predefined macros, and it outputs _both_ the `#define' - directives and the result of preprocessing. Both kinds of - output go to the standard output file. - - `N' - Like `D', but emit only the macro names, not their expansions. - - `I' - Output `#include' directives in addition to the result of - preprocessing. - - `U' - Like `D' except that only macros that are expanded, or whose - definedness is tested in preprocessor directives, are output; - the output is delayed until the use or test of the macro; and - `#undef' directives are also output for macros tested but - undefined at the time. - -`-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. *Note Preprocessor - Output::. - -`-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 `-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 `#'. - -`-CC' - Do not discard comments, including during macro expansion. This is - like `-C', except that comments contained within macros are also - passed through to the output file where the macro is expanded. - - In addition to the side-effects of the `-C' option, the `-CC' - option causes all C++-style comments inside a macro to be - converted to C-style comments. This is to prevent later use of - that macro from inadvertently commenting out the remainder of the - source line. - - The `-CC' option is generally used to support lint comments. - -`-traditional-cpp' - Try to imitate the behavior of old-fashioned C preprocessors, as - opposed to ISO C preprocessors. *Note Traditional Mode::. - -`-trigraphs' - Process trigraph sequences. *Note Initial processing::. - -`-remap' - Enable special code to work around file systems which only permit - very short file names, such as MS-DOS. - -`--help' -`--target-help' - Print text describing all the command line options instead of - preprocessing anything. - -`-v' - Verbose mode. Print out GNU CPP's version number at the beginning - of execution, and report the final form of the include path. - -`-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 - `#include' stack it is. Precompiled header files are also - printed, even if they are found to be invalid; an invalid - precompiled header file is printed with `...x' and a valid one - with `...!' . - -`-version' -`--version' - Print out GNU CPP's version number. With one dash, proceed to - preprocess as normal. With two dashes, exit immediately. - - -File: cpp.info, Node: Environment Variables, Next: GNU Free Documentation License, Prev: Invocation, Up: Top - -13 Environment Variables -************************ - -This section describes the environment variables that affect how CPP -operates. You can use them to specify directories or prefixes to use -when searching for include files, or to control dependency output. - - Note that you can also specify places to search using options such as -`-I', and control dependency output with options like `-M' (*note -Invocation::). These take precedence over environment variables, which -in turn take precedence over the configuration of GCC. - -`CPATH' -`C_INCLUDE_PATH' -`CPLUS_INCLUDE_PATH' -`OBJC_INCLUDE_PATH' - Each variable's value is a list of directories separated by a - special character, much like `PATH', in which to look for header - files. The special character, `PATH_SEPARATOR', is - target-dependent and determined at GCC build time. For Microsoft - Windows-based targets it is a semicolon, and for almost all other - targets it is a colon. - - `CPATH' specifies a list of directories to be searched as if - specified with `-I', but after any paths given with `-I' options - on the command line. This environment variable is used regardless - of which language is being preprocessed. - - The remaining environment variables apply only when preprocessing - the particular language indicated. Each specifies a list of - directories to be searched as if specified with `-isystem', but - after any paths given with `-isystem' options on the command line. - - In all these variables, an empty element instructs the compiler to - search its current working directory. Empty elements can appear - at the beginning or end of a path. For instance, if the value of - `CPATH' is `:/special/include', that has the same effect as - `-I. -I/special/include'. - - See also *note Search Path::. - -`DEPENDENCIES_OUTPUT' - If this variable is set, its value specifies how to output - dependencies for Make based on the non-system header files - processed by the compiler. System header files are ignored in the - dependency output. - - The value of `DEPENDENCIES_OUTPUT' can be just a file name, in - which case the Make rules are written to that file, guessing the - target name from the source file name. Or the value can have the - form `FILE TARGET', in which case the rules are written to file - FILE using TARGET as the target name. - - In other words, this environment variable is equivalent to - combining the options `-MM' and `-MF' (*note Invocation::), with - an optional `-MT' switch too. - -`SUNPRO_DEPENDENCIES' - This variable is the same as `DEPENDENCIES_OUTPUT' (see above), - except that system header files are not ignored, so it implies - `-M' rather than `-MM'. However, the dependence on the main input - file is omitted. *Note Invocation::. - - -File: cpp.info, Node: GNU Free Documentation License, Next: Index of Directives, Prev: Environment Variables, Up: Top - -GNU Free Documentation License -****************************** - - Version 1.2, November 2002 - - Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. - 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA - - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - 0. PREAMBLE - - The purpose of this License is to make a manual, textbook, or other - functional and useful document "free" in the sense of freedom: to - assure everyone the effective freedom to copy and redistribute it, - with or without modifying it, either commercially or - noncommercially. Secondarily, this License preserves for the - author and publisher a way to get credit for their work, while not - being considered responsible for modifications made by others. - - This License is a kind of "copyleft", which means that derivative - works of the document must themselves be free in the same sense. - It complements the GNU General Public License, which is a copyleft - license designed for free software. - - We have designed this License in order to use it for manuals for - free software, because free software needs free documentation: a - free program should come with manuals providing the same freedoms - that the software does. But this License is not limited to - software manuals; it can be used for any textual work, regardless - of subject matter or whether it is published as a printed book. - We recommend this License principally for works whose purpose is - instruction or reference. - - 1. APPLICABILITY AND DEFINITIONS - - This License applies to any manual or other work, in any medium, - that contains a notice placed by the copyright holder saying it - can be distributed under the terms of this License. Such a notice - grants a world-wide, royalty-free license, unlimited in duration, - to use that work under the conditions stated herein. The - "Document", below, refers to any such manual or work. Any member - of the public is a licensee, and is addressed as "you". You - accept the license if you copy, modify or distribute the work in a - way requiring permission under copyright law. - - A "Modified Version" of the Document means any work containing the - Document or a portion of it, either copied verbatim, or with - modifications and/or translated into another language. - - A "Secondary Section" is a named appendix or a front-matter section - of the Document that deals exclusively with the relationship of the - publishers or authors of the Document to the Document's overall - subject (or to related matters) and contains nothing that could - fall directly within that overall subject. (Thus, if the Document - is in part a textbook of mathematics, a Secondary Section may not - explain any mathematics.) The relationship could be a matter of - historical connection with the subject or with related matters, or - of legal, commercial, philosophical, ethical or political position - regarding them. - - The "Invariant Sections" are certain Secondary Sections whose - titles are designated, as being those of Invariant Sections, in - the notice that says that the Document is released under this - License. If a section does not fit the above definition of - Secondary then it is not allowed to be designated as Invariant. - The Document may contain zero Invariant Sections. If the Document - does not identify any Invariant Sections then there are none. - - The "Cover Texts" are certain short passages of text that are - listed, as Front-Cover Texts or Back-Cover Texts, in the notice - that says that the Document is released under this License. A - Front-Cover Text may be at most 5 words, and a Back-Cover Text may - be at most 25 words. - - A "Transparent" copy of the Document means a machine-readable copy, - represented in a format whose specification is available to the - general public, that is suitable for revising the document - straightforwardly with generic text editors or (for images - composed of pixels) generic paint programs or (for drawings) some - widely available drawing editor, and that is suitable for input to - text formatters or for automatic translation to a variety of - formats suitable for input to text formatters. A copy made in an - otherwise Transparent file format whose markup, or absence of - markup, has been arranged to thwart or discourage subsequent - modification by readers is not Transparent. An image format is - not Transparent if used for any substantial amount of text. A - copy that is not "Transparent" is called "Opaque". - - Examples of suitable formats for Transparent copies include plain - ASCII without markup, Texinfo input format, LaTeX input format, - SGML or XML using a publicly available DTD, and - standard-conforming simple HTML, PostScript or PDF designed for - human modification. Examples of transparent image formats include - PNG, XCF and JPG. Opaque formats include proprietary formats that - can be read and edited only by proprietary word processors, SGML or - XML for which the DTD and/or processing tools are not generally - available, and the machine-generated HTML, PostScript or PDF - produced by some word processors for output purposes only. - - The "Title Page" means, for a printed book, the title page itself, - plus such following pages as are needed to hold, legibly, the - material this License requires to appear in the title page. For - works in formats which do not have any title page as such, "Title - Page" means the text near the most prominent appearance of the - work's title, preceding the beginning of the body of the text. - - A section "Entitled XYZ" means a named subunit of the Document - whose title either is precisely XYZ or contains XYZ in parentheses - following text that translates XYZ in another language. (Here XYZ - stands for a specific section name mentioned below, such as - "Acknowledgements", "Dedications", "Endorsements", or "History".) - To "Preserve the Title" of such a section when you modify the - Document means that it remains a section "Entitled XYZ" according - to this definition. - - The Document may include Warranty Disclaimers next to the notice - which states that this License applies to the Document. These - Warranty Disclaimers are considered to be included by reference in - this License, but only as regards disclaiming warranties: any other - implication that these Warranty Disclaimers may have is void and - has no effect on the meaning of this License. - - 2. VERBATIM COPYING - - You may copy and distribute the Document in any medium, either - commercially or noncommercially, provided that this License, the - copyright notices, and the license notice saying this License - applies to the Document are reproduced in all copies, and that you - add no other conditions whatsoever to those of this License. You - may not use technical measures to obstruct or control the reading - or further copying of the copies you make or distribute. However, - you may accept compensation in exchange for copies. If you - distribute a large enough number of copies you must also follow - the conditions in section 3. - - You may also lend copies, under the same conditions stated above, - and you may publicly display copies. - - 3. COPYING IN QUANTITY - - If you publish printed copies (or copies in media that commonly - have printed covers) of the Document, numbering more than 100, and - the Document's license notice requires Cover Texts, you must - enclose the copies in covers that carry, clearly and legibly, all - these Cover Texts: Front-Cover Texts on the front cover, and - Back-Cover Texts on the back cover. Both covers must also clearly - and legibly identify you as the publisher of these copies. The - front cover must present the full title with all words of the - title equally prominent and visible. You may add other material - on the covers in addition. Copying with changes limited to the - covers, as long as they preserve the title of the Document and - satisfy these conditions, can be treated as verbatim copying in - other respects. - - If the required texts for either cover are too voluminous to fit - legibly, you should put the first ones listed (as many as fit - reasonably) on the actual cover, and continue the rest onto - adjacent pages. - - If you publish or distribute Opaque copies of the Document - numbering more than 100, you must either include a - machine-readable Transparent copy along with each Opaque copy, or - state in or with each Opaque copy a computer-network location from - which the general network-using public has access to download - using public-standard network protocols a complete Transparent - copy of the Document, free of added material. If you use the - latter option, you must take reasonably prudent steps, when you - begin distribution of Opaque copies in quantity, to ensure that - this Transparent copy will remain thus accessible at the stated - location until at least one year after the last time you - distribute an Opaque copy (directly or through your agents or - retailers) of that edition to the public. - - It is requested, but not required, that you contact the authors of - the Document well before redistributing any large number of - copies, to give them a chance to provide you with an updated - version of the Document. - - 4. MODIFICATIONS - - You may copy and distribute a Modified Version of the Document - under the conditions of sections 2 and 3 above, provided that you - release the Modified Version under precisely this License, with - the Modified Version filling the role of the Document, thus - licensing distribution and modification of the Modified Version to - whoever possesses a copy of it. In addition, you must do these - things in the Modified Version: - - A. Use in the Title Page (and on the covers, if any) a title - distinct from that of the Document, and from those of - previous versions (which should, if there were any, be listed - in the History section of the Document). You may use the - same title as a previous version if the original publisher of - that version gives permission. - - B. List on the Title Page, as authors, one or more persons or - entities responsible for authorship of the modifications in - the Modified Version, together with at least five of the - principal authors of the Document (all of its principal - authors, if it has fewer than five), unless they release you - from this requirement. - - C. State on the Title page the name of the publisher of the - Modified Version, as the publisher. - - D. Preserve all the copyright notices of the Document. - - E. Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices. - - F. Include, immediately after the copyright notices, a license - notice giving the public permission to use the Modified - Version under the terms of this License, in the form shown in - the Addendum below. - - G. Preserve in that license notice the full lists of Invariant - Sections and required Cover Texts given in the Document's - license notice. - - H. Include an unaltered copy of this License. - - I. Preserve the section Entitled "History", Preserve its Title, - and add to it an item stating at least the title, year, new - authors, and publisher of the Modified Version as given on - the Title Page. If there is no section Entitled "History" in - the Document, create one stating the title, year, authors, - and publisher of the Document as given on its Title Page, - then add an item describing the Modified Version as stated in - the previous sentence. - - J. Preserve the network location, if any, given in the Document - for public access to a Transparent copy of the Document, and - likewise the network locations given in the Document for - previous versions it was based on. These may be placed in - the "History" section. You may omit a network location for a - work that was published at least four years before the - Document itself, or if the original publisher of the version - it refers to gives permission. - - K. For any section Entitled "Acknowledgements" or "Dedications", - Preserve the Title of the section, and preserve in the - section all the substance and tone of each of the contributor - acknowledgements and/or dedications given therein. - - L. Preserve all the Invariant Sections of the Document, - unaltered in their text and in their titles. Section numbers - or the equivalent are not considered part of the section - titles. - - M. Delete any section Entitled "Endorsements". Such a section - may not be included in the Modified Version. - - N. Do not retitle any existing section to be Entitled - "Endorsements" or to conflict in title with any Invariant - Section. - - O. Preserve any Warranty Disclaimers. - - If the Modified Version includes new front-matter sections or - appendices that qualify as Secondary Sections and contain no - material copied from the Document, you may at your option - designate some or all of these sections as invariant. To do this, - add their titles to the list of Invariant Sections in the Modified - Version's license notice. These titles must be distinct from any - other section titles. - - You may add a section Entitled "Endorsements", provided it contains - nothing but endorsements of your Modified Version by various - parties--for example, statements of peer review or that the text - has been approved by an organization as the authoritative - definition of a standard. - - You may add a passage of up to five words as a Front-Cover Text, - and a passage of up to 25 words as a Back-Cover Text, to the end - of the list of Cover Texts in the Modified Version. Only one - passage of Front-Cover Text and one of Back-Cover Text may be - added by (or through arrangements made by) any one entity. If the - Document already includes a cover text for the same cover, - previously added by you or by arrangement made by the same entity - you are acting on behalf of, you may not add another; but you may - replace the old one, on explicit permission from the previous - publisher that added the old one. - - The author(s) and publisher(s) of the Document do not by this - License give permission to use their names for publicity for or to - assert or imply endorsement of any Modified Version. - - 5. COMBINING DOCUMENTS - - You may combine the Document with other documents released under - this License, under the terms defined in section 4 above for - modified versions, provided that you include in the combination - all of the Invariant Sections of all of the original documents, - unmodified, and list them all as Invariant Sections of your - combined work in its license notice, and that you preserve all - their Warranty Disclaimers. - - The combined work need only contain one copy of this License, and - multiple identical Invariant Sections may be replaced with a single - copy. If there are multiple Invariant Sections with the same name - but different contents, make the title of each such section unique - by adding at the end of it, in parentheses, the name of the - original author or publisher of that section if known, or else a - unique number. Make the same adjustment to the section titles in - the list of Invariant Sections in the license notice of the - combined work. - - In the combination, you must combine any sections Entitled - "History" in the various original documents, forming one section - Entitled "History"; likewise combine any sections Entitled - "Acknowledgements", and any sections Entitled "Dedications". You - must delete all sections Entitled "Endorsements." - - 6. COLLECTIONS OF DOCUMENTS - - You may make a collection consisting of the Document and other - documents released under this License, and replace the individual - copies of this License in the various documents with a single copy - that is included in the collection, provided that you follow the - rules of this License for verbatim copying of each of the - documents in all other respects. - - You may extract a single document from such a collection, and - distribute it individually under this License, provided you insert - a copy of this License into the extracted document, and follow - this License in all other respects regarding verbatim copying of - that document. - - 7. AGGREGATION WITH INDEPENDENT WORKS - - A compilation of the Document or its derivatives with other - separate and independent documents or works, in or on a volume of - a storage or distribution medium, is called an "aggregate" if the - copyright resulting from the compilation is not used to limit the - legal rights of the compilation's users beyond what the individual - works permit. When the Document is included in an aggregate, this - License does not apply to the other works in the aggregate which - are not themselves derivative works of the Document. - - If the Cover Text requirement of section 3 is applicable to these - copies of the Document, then if the Document is less than one half - of the entire aggregate, the Document's Cover Texts may be placed - on covers that bracket the Document within the aggregate, or the - electronic equivalent of covers if the Document is in electronic - form. Otherwise they must appear on printed covers that bracket - the whole aggregate. - - 8. TRANSLATION - - Translation is considered a kind of modification, so you may - distribute translations of the Document under the terms of section - 4. Replacing Invariant Sections with translations requires special - permission from their copyright holders, but you may include - translations of some or all Invariant Sections in addition to the - original versions of these Invariant Sections. You may include a - translation of this License, and all the license notices in the - Document, and any Warranty Disclaimers, provided that you also - include the original English version of this License and the - original versions of those notices and disclaimers. In case of a - disagreement between the translation and the original version of - this License or a notice or disclaimer, the original version will - prevail. - - If a section in the Document is Entitled "Acknowledgements", - "Dedications", or "History", the requirement (section 4) to - Preserve its Title (section 1) will typically require changing the - actual title. - - 9. TERMINATION - - You may not copy, modify, sublicense, or distribute the Document - except as expressly provided for under this License. Any other - attempt to copy, modify, sublicense or distribute the Document is - void, and will automatically terminate your rights under this - License. However, parties who have received copies, or rights, - from you under this License will not have their licenses - terminated so long as such parties remain in full compliance. - - 10. FUTURE REVISIONS OF THIS LICENSE - - The Free Software Foundation may publish new, revised versions of - the GNU Free Documentation License from time to time. Such new - versions will be similar in spirit to the present version, but may - differ in detail to address new problems or concerns. See - `http://www.gnu.org/copyleft/'. - - Each version of the License is given a distinguishing version - number. If the Document specifies that a particular numbered - version of this License "or any later version" applies to it, you - have the option of following the terms and conditions either of - that specified version or of any later version that has been - published (not as a draft) by the Free Software Foundation. If - the Document does not specify a version number of this License, - you may choose any version ever published (not as a draft) by the - Free Software Foundation. - -ADDENDUM: How to use this License for your documents -==================================================== - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and license -notices just after the title page: - - Copyright (C) YEAR YOUR NAME. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.2 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover - Texts. A copy of the license is included in the section entitled ``GNU - Free Documentation License''. - - If you have Invariant Sections, Front-Cover Texts and Back-Cover -Texts, replace the "with...Texts." line with this: - - with the Invariant Sections being LIST THEIR TITLES, with - the Front-Cover Texts being LIST, and with the Back-Cover Texts - being LIST. - - If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - - If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, to -permit their use in free software. - - -File: cpp.info, Node: Index of Directives, Next: Option Index, Prev: GNU Free Documentation License, Up: Top - -Index of Directives -******************* - -[index] -* Menu: - -* #assert: Obsolete Features. (line 48) -* #define: Object-like Macros. (line 11) -* #elif: Elif. (line 6) -* #else: Else. (line 6) -* #endif: Ifdef. (line 6) -* #error: Diagnostics. (line 6) -* #ident: Other Directives. (line 6) -* #if: Conditional Syntax. (line 6) -* #ifdef: Ifdef. (line 6) -* #ifndef: Ifdef. (line 40) -* #import: Alternatives to Wrapper #ifndef. - (line 11) -* #include: Include Syntax. (line 6) -* #include_next: Wrapper Headers. (line 6) -* #line: Line Control. (line 20) -* #pragma GCC dependency: Pragmas. (line 53) -* #pragma GCC poison: Pragmas. (line 65) -* #pragma GCC system_header <1>: Pragmas. (line 92) -* #pragma GCC system_header: System Headers. (line 31) -* #sccs: Other Directives. (line 6) -* #unassert: Obsolete Features. (line 59) -* #undef: Undefining and Redefining Macros. - (line 6) -* #warning: Diagnostics. (line 27) - - -File: cpp.info, Node: Option Index, Next: Concept Index, Prev: Index of Directives, Up: Top - -Option Index -************ - -CPP's command line options and environment variables are indexed here -without any initial `-' or `--'. - -[index] -* Menu: - -* A: Invocation. (line 522) -* ansi: Invocation. (line 308) -* C: Invocation. (line 581) -* C_INCLUDE_PATH: Environment Variables. - (line 16) -* CPATH: Environment Variables. - (line 15) -* CPLUS_INCLUDE_PATH: Environment Variables. - (line 17) -* D: Invocation. (line 39) -* dD: Invocation. (line 554) -* DEPENDENCIES_OUTPUT: Environment Variables. - (line 44) -* dI: Invocation. (line 563) -* dM: Invocation. (line 538) -* dN: Invocation. (line 560) -* dU: Invocation. (line 567) -* fdirectives-only: Invocation. (line 430) -* fdollars-in-identifiers: Invocation. (line 452) -* fexec-charset: Invocation. (line 479) -* fextended-identifiers: Invocation. (line 455) -* finput-charset: Invocation. (line 492) -* fno-show-column: Invocation. (line 517) -* fno-working-directory: Invocation. (line 502) -* fpreprocessed: Invocation. (line 460) -* ftabstop: Invocation. (line 473) -* fwide-exec-charset: Invocation. (line 484) -* fworking-directory: Invocation. (line 502) -* H: Invocation. (line 626) -* help: Invocation. (line 618) -* I: Invocation. (line 71) -* I-: Invocation. (line 345) -* idirafter: Invocation. (line 387) -* imacros: Invocation. (line 378) -* imultilib: Invocation. (line 410) -* include: Invocation. (line 367) -* iprefix: Invocation. (line 394) -* iquote: Invocation. (line 422) -* isysroot: Invocation. (line 406) -* isystem: Invocation. (line 414) -* iwithprefix: Invocation. (line 400) -* iwithprefixbefore: Invocation. (line 400) -* M: Invocation. (line 180) -* MD: Invocation. (line 269) -* MF: Invocation. (line 215) -* MG: Invocation. (line 224) -* MM: Invocation. (line 205) -* MMD: Invocation. (line 285) -* MP: Invocation. (line 234) -* MQ: Invocation. (line 260) -* MT: Invocation. (line 246) -* nostdinc: Invocation. (line 357) -* nostdinc++: Invocation. (line 362) -* o: Invocation. (line 82) -* OBJC_INCLUDE_PATH: Environment Variables. - (line 18) -* P: Invocation. (line 574) -* pedantic: Invocation. (line 170) -* pedantic-errors: Invocation. (line 175) -* remap: Invocation. (line 613) -* std=: Invocation. (line 308) -* SUNPRO_DEPENDENCIES: Environment Variables. - (line 60) -* target-help: Invocation. (line 618) -* traditional-cpp: Invocation. (line 606) -* trigraphs: Invocation. (line 610) -* U: Invocation. (line 62) -* undef: Invocation. (line 66) -* v: Invocation. (line 622) -* version: Invocation. (line 635) -* w: Invocation. (line 166) -* Wall: Invocation. (line 88) -* Wcomment: Invocation. (line 96) -* Wcomments: Invocation. (line 96) -* Wendif-labels: Invocation. (line 143) -* Werror: Invocation. (line 156) -* Wsystem-headers: Invocation. (line 160) -* Wtraditional: Invocation. (line 113) -* Wtrigraphs: Invocation. (line 101) -* Wundef: Invocation. (line 119) -* Wunused-macros: Invocation. (line 124) -* x: Invocation. (line 292) - - -File: cpp.info, Node: Concept Index, Prev: Option Index, Up: Top - -Concept Index -************* - -[index] -* Menu: - -* # operator: Stringification. (line 6) -* ## operator: Concatenation. (line 6) -* _Pragma: Pragmas. (line 25) -* alternative tokens: Tokenization. (line 106) -* arguments: Macro Arguments. (line 6) -* arguments in macro definitions: Macro Arguments. (line 6) -* assertions: Obsolete Features. (line 13) -* assertions, canceling: Obsolete Features. (line 59) -* backslash-newline: Initial processing. (line 61) -* block comments: Initial processing. (line 77) -* C++ named operators: C++ Named Operators. (line 6) -* character constants: Tokenization. (line 85) -* character set, execution: Invocation. (line 479) -* character set, input: Invocation. (line 492) -* character set, wide execution: Invocation. (line 484) -* command line: Invocation. (line 6) -* commenting out code: Deleted Code. (line 6) -* comments: Initial processing. (line 77) -* common predefined macros: Common Predefined Macros. - (line 6) -* computed includes: Computed Includes. (line 6) -* concatenation: Concatenation. (line 6) -* conditional group: Ifdef. (line 14) -* conditionals: Conditionals. (line 6) -* continued lines: Initial processing. (line 61) -* controlling macro: Once-Only Headers. (line 35) -* defined: Defined. (line 6) -* dependencies for make as output: Environment Variables. - (line 45) -* dependencies, make: Invocation. (line 180) -* diagnostic: Diagnostics. (line 6) -* differences from previous versions: Differences from previous versions. - (line 6) -* digraphs: Tokenization. (line 106) -* directive line: The preprocessing language. - (line 6) -* directive name: The preprocessing language. - (line 6) -* directives: The preprocessing language. - (line 6) -* empty macro arguments: Macro Arguments. (line 66) -* environment variables: Environment Variables. - (line 6) -* expansion of arguments: Argument Prescan. (line 6) -* FDL, GNU Free Documentation License: GNU Free Documentation License. - (line 6) -* function-like macros: Function-like Macros. - (line 6) -* grouping options: Invocation. (line 34) -* guard macro: Once-Only Headers. (line 35) -* header file: Header Files. (line 6) -* header file names: Tokenization. (line 85) -* identifiers: Tokenization. (line 34) -* implementation limits: Implementation limits. - (line 6) -* implementation-defined behavior: Implementation-defined behavior. - (line 6) -* including just once: Once-Only Headers. (line 6) -* invocation: Invocation. (line 6) -* iso646.h: C++ Named Operators. (line 6) -* line comments: Initial processing. (line 77) -* line control: Line Control. (line 6) -* line endings: Initial processing. (line 14) -* linemarkers: Preprocessor Output. (line 28) -* macro argument expansion: Argument Prescan. (line 6) -* macro arguments and directives: Directives Within Macro Arguments. - (line 6) -* macros in include: Computed Includes. (line 6) -* macros with arguments: Macro Arguments. (line 6) -* macros with variable arguments: Variadic Macros. (line 6) -* make: Invocation. (line 180) -* manifest constants: Object-like Macros. (line 6) -* named operators: C++ Named Operators. (line 6) -* newlines in macro arguments: Newlines in Arguments. - (line 6) -* null directive: Other Directives. (line 17) -* numbers: Tokenization. (line 61) -* object-like macro: Object-like Macros. (line 6) -* options: Invocation. (line 38) -* options, grouping: Invocation. (line 34) -* other tokens: Tokenization. (line 120) -* output format: Preprocessor Output. (line 12) -* overriding a header file: Wrapper Headers. (line 6) -* parentheses in macro bodies: Operator Precedence Problems. - (line 6) -* pitfalls of macros: Macro Pitfalls. (line 6) -* predefined macros: Predefined Macros. (line 6) -* predefined macros, system-specific: System-specific Predefined Macros. - (line 6) -* predicates: Obsolete Features. (line 26) -* preprocessing directives: The preprocessing language. - (line 6) -* preprocessing numbers: Tokenization. (line 61) -* preprocessing tokens: Tokenization. (line 6) -* prescan of macro arguments: Argument Prescan. (line 6) -* problems with macros: Macro Pitfalls. (line 6) -* punctuators: Tokenization. (line 106) -* redefining macros: Undefining and Redefining Macros. - (line 6) -* repeated inclusion: Once-Only Headers. (line 6) -* reporting errors: Diagnostics. (line 6) -* reporting warnings: Diagnostics. (line 6) -* reserved namespace: System-specific Predefined Macros. - (line 6) -* self-reference: Self-Referential Macros. - (line 6) -* semicolons (after macro calls): Swallowing the Semicolon. - (line 6) -* side effects (in macro arguments): Duplication of Side Effects. - (line 6) -* standard predefined macros.: Standard Predefined Macros. - (line 6) -* string constants: Tokenization. (line 85) -* string literals: Tokenization. (line 85) -* stringification: Stringification. (line 6) -* symbolic constants: Object-like Macros. (line 6) -* system header files <1>: System Headers. (line 6) -* system header files: Header Files. (line 13) -* system-specific predefined macros: System-specific Predefined Macros. - (line 6) -* testing predicates: Obsolete Features. (line 37) -* token concatenation: Concatenation. (line 6) -* token pasting: Concatenation. (line 6) -* tokens: Tokenization. (line 6) -* trigraphs: Initial processing. (line 32) -* undefining macros: Undefining and Redefining Macros. - (line 6) -* unsafe macros: Duplication of Side Effects. - (line 6) -* variable number of arguments: Variadic Macros. (line 6) -* variadic macros: Variadic Macros. (line 6) -* wrapper #ifndef: Once-Only Headers. (line 6) -* wrapper headers: Wrapper Headers. (line 6) - - - -Tag Table: -Node: Top1091 -Node: Overview3805 -Node: Character sets6626 -Ref: Character sets-Footnote-18809 -Node: Initial processing8990 -Ref: trigraphs10549 -Node: Tokenization14751 -Ref: Tokenization-Footnote-121887 -Node: The preprocessing language21998 -Node: Header Files24876 -Node: Include Syntax26792 -Node: Include Operation28429 -Node: Search Path30277 -Node: Once-Only Headers33467 -Node: Alternatives to Wrapper #ifndef35126 -Node: Computed Includes36869 -Node: Wrapper Headers40027 -Node: System Headers42453 -Node: Macros44503 -Node: Object-like Macros45644 -Node: Function-like Macros49234 -Node: Macro Arguments50850 -Node: Stringification54995 -Node: Concatenation58201 -Node: Variadic Macros61309 -Node: Predefined Macros66096 -Node: Standard Predefined Macros66684 -Node: Common Predefined Macros72620 -Node: System-specific Predefined Macros85530 -Node: C++ Named Operators87551 -Node: Undefining and Redefining Macros88515 -Node: Directives Within Macro Arguments90619 -Node: Macro Pitfalls92167 -Node: Misnesting92700 -Node: Operator Precedence Problems93812 -Node: Swallowing the Semicolon95678 -Node: Duplication of Side Effects97701 -Node: Self-Referential Macros99884 -Node: Argument Prescan102293 -Node: Newlines in Arguments106047 -Node: Conditionals106998 -Node: Conditional Uses108828 -Node: Conditional Syntax110186 -Node: Ifdef110506 -Node: If113667 -Node: Defined115971 -Node: Else117254 -Node: Elif117824 -Node: Deleted Code119113 -Node: Diagnostics120360 -Node: Line Control121977 -Node: Pragmas125781 -Node: Other Directives130051 -Node: Preprocessor Output131158 -Node: Traditional Mode134359 -Node: Traditional lexical analysis135417 -Node: Traditional macros137920 -Node: Traditional miscellany141722 -Node: Traditional warnings142719 -Node: Implementation Details144916 -Node: Implementation-defined behavior145537 -Ref: Identifier characters146289 -Node: Implementation limits149364 -Node: Obsolete Features152038 -Node: Differences from previous versions154875 -Node: Invocation159083 -Ref: Wtrigraphs163535 -Ref: dashMF168310 -Ref: fdollars-in-identifiers177693 -Node: Environment Variables185856 -Node: GNU Free Documentation License188822 -Node: Index of Directives211255 -Node: Option Index213189 -Node: Concept Index219373 - -End Tag Table diff --git a/gcc/doc/cppinternals.info b/gcc/doc/cppinternals.info deleted file mode 100644 index 38e4979f..00000000 --- a/gcc/doc/cppinternals.info +++ /dev/null @@ -1,1036 +0,0 @@ -This is doc/cppinternals.info, produced by makeinfo version 4.13 from -/d/gcc-4.4.3/gcc-4.4.3/gcc/doc/cppinternals.texi. - -INFO-DIR-SECTION Software development -START-INFO-DIR-ENTRY -* Cpplib: (cppinternals). Cpplib internals. -END-INFO-DIR-ENTRY - - This file documents the internals of the GNU C Preprocessor. - - Copyright 2000, 2001, 2002, 2004, 2005, 2006, 2007 Free Software -Foundation, Inc. - - Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - - Permission is granted to copy and distribute modified versions of -this manual under the conditions for verbatim copying, provided also -that the entire resulting derived work is distributed under the terms -of a permission notice identical to this one. - - Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions. - - -File: cppinternals.info, Node: Top, Next: Conventions, Up: (dir) - -The GNU C Preprocessor Internals -******************************** - -1 Cpplib--the GNU C Preprocessor -******************************** - -The GNU C preprocessor is implemented as a library, "cpplib", so it can -be easily shared between a stand-alone preprocessor, and a preprocessor -integrated with the C, C++ and Objective-C front ends. It is also -available for use by other programs, though this is not recommended as -its exposed interface has not yet reached a point of reasonable -stability. - - The library has been written to be re-entrant, so that it can be used -to preprocess many files simultaneously if necessary. It has also been -written with the preprocessing token as the fundamental unit; the -preprocessor in previous versions of GCC would operate on text strings -as the fundamental unit. - - This brief manual documents the internals of cpplib, and explains -some of the tricky issues. It is intended that, along with the -comments in the source code, a reasonably competent C programmer should -be able to figure out what the code is doing, and why things have been -implemented the way they have. - -* Menu: - -* Conventions:: Conventions used in the code. -* Lexer:: The combined C, C++ and Objective-C Lexer. -* Hash Nodes:: All identifiers are entered into a hash table. -* Macro Expansion:: Macro expansion algorithm. -* Token Spacing:: Spacing and paste avoidance issues. -* Line Numbering:: Tracking location within files. -* Guard Macros:: Optimizing header files with guard macros. -* Files:: File handling. -* Concept Index:: Index. - - -File: cppinternals.info, Node: Conventions, Next: Lexer, Prev: Top, Up: Top - -Conventions -*********** - -cpplib has two interfaces--one is exposed internally only, and the -other is for both internal and external use. - - The convention is that functions and types that are exposed to -multiple files internally are prefixed with `_cpp_', and are to be -found in the file `internal.h'. Functions and types exposed to external -clients are in `cpplib.h', and prefixed with `cpp_'. For historical -reasons this is no longer quite true, but we should strive to stick to -it. - - We are striving to reduce the information exposed in `cpplib.h' to -the bare minimum necessary, and then to keep it there. This makes clear -exactly what external clients are entitled to assume, and allows us to -change internals in the future without worrying whether library clients -are perhaps relying on some kind of undocumented implementation-specific -behavior. - - -File: cppinternals.info, Node: Lexer, Next: Hash Nodes, Prev: Conventions, Up: Top - -The Lexer -********* - -Overview -======== - -The lexer is contained in the file `lex.c'. It is a hand-coded lexer, -and not implemented as a state machine. It can understand C, C++ and -Objective-C source code, and has been extended to allow reasonably -successful preprocessing of assembly language. The lexer does not make -an initial pass to strip out trigraphs and escaped newlines, but handles -them as they are encountered in a single pass of the input file. It -returns preprocessing tokens individually, not a line at a time. - - It is mostly transparent to users of the library, since the library's -interface for obtaining the next token, `cpp_get_token', takes care of -lexing new tokens, handling directives, and expanding macros as -necessary. However, the lexer does expose some functionality so that -clients of the library can easily spell a given token, such as -`cpp_spell_token' and `cpp_token_len'. These functions are useful when -generating diagnostics, and for emitting the preprocessed output. - -Lexing a token -============== - -Lexing of an individual token is handled by `_cpp_lex_direct' and its -subroutines. In its current form the code is quite complicated, with -read ahead characters and such-like, since it strives to not step back -in the character stream in preparation for handling non-ASCII file -encodings. The current plan is to convert any such files to UTF-8 -before processing them. This complexity is therefore unnecessary and -will be removed, so I'll not discuss it further here. - - The job of `_cpp_lex_direct' is simply to lex a token. It is not -responsible for issues like directive handling, returning lookahead -tokens directly, multiple-include optimization, or conditional block -skipping. It necessarily has a minor ro^le to play in memory -management of lexed lines. I discuss these issues in a separate section -(*note Lexing a line::). - - The lexer places the token it lexes into storage pointed to by the -variable `cur_token', and then increments it. This variable is -important for correct diagnostic positioning. Unless a specific line -and column are passed to the diagnostic routines, they will examine the -`line' and `col' values of the token just before the location that -`cur_token' points to, and use that location to report the diagnostic. - - The lexer does not consider whitespace to be a token in its own -right. If whitespace (other than a new line) precedes a token, it sets -the `PREV_WHITE' bit in the token's flags. Each token has its `line' -and `col' variables set to the line and column of the first character -of the token. This line number is the line number in the translation -unit, and can be converted to a source (file, line) pair using the line -map code. - - The first token on a logical, i.e. unescaped, line has the flag -`BOL' set for beginning-of-line. This flag is intended for internal -use, both to distinguish a `#' that begins a directive from one that -doesn't, and to generate a call-back to clients that want to be -notified about the start of every non-directive line with tokens on it. -Clients cannot reliably determine this for themselves: the first token -might be a macro, and the tokens of a macro expansion do not have the -`BOL' flag set. The macro expansion may even be empty, and the next -token on the line certainly won't have the `BOL' flag set. - - New lines are treated specially; exactly how the lexer handles them -is context-dependent. The C standard mandates that directives are -terminated by the first unescaped newline character, even if it appears -in the middle of a macro expansion. Therefore, if the state variable -`in_directive' is set, the lexer returns a `CPP_EOF' token, which is -normally used to indicate end-of-file, to indicate end-of-directive. -In a directive a `CPP_EOF' token never means end-of-file. -Conveniently, if the caller was `collect_args', it already handles -`CPP_EOF' as if it were end-of-file, and reports an error about an -unterminated macro argument list. - - The C standard also specifies that a new line in the middle of the -arguments to a macro is treated as whitespace. This white space is -important in case the macro argument is stringified. The state variable -`parsing_args' is nonzero when the preprocessor is collecting the -arguments to a macro call. It is set to 1 when looking for the opening -parenthesis to a function-like macro, and 2 when collecting the actual -arguments up to the closing parenthesis, since these two cases need to -be distinguished sometimes. One such time is here: the lexer sets the -`PREV_WHITE' flag of a token if it meets a new line when `parsing_args' -is set to 2. It doesn't set it if it meets a new line when -`parsing_args' is 1, since then code like - - #define foo() bar - foo - baz - -would be output with an erroneous space before `baz': - - foo - baz - - This is a good example of the subtlety of getting token spacing -correct in the preprocessor; there are plenty of tests in the testsuite -for corner cases like this. - - The lexer is written to treat each of `\r', `\n', `\r\n' and `\n\r' -as a single new line indicator. This allows it to transparently -preprocess MS-DOS, Macintosh and Unix files without their needing to -pass through a special filter beforehand. - - We also decided to treat a backslash, either `\' or the trigraph -`??/', separated from one of the above newline indicators by -non-comment whitespace only, as intending to escape the newline. It -tends to be a typing mistake, and cannot reasonably be mistaken for -anything else in any of the C-family grammars. Since handling it this -way is not strictly conforming to the ISO standard, the library issues a -warning wherever it encounters it. - - Handling newlines like this is made simpler by doing it in one place -only. The function `handle_newline' takes care of all newline -characters, and `skip_escaped_newlines' takes care of arbitrarily long -sequences of escaped newlines, deferring to `handle_newline' to handle -the newlines themselves. - - The most painful aspect of lexing ISO-standard C and C++ is handling -trigraphs and backlash-escaped newlines. Trigraphs are processed before -any interpretation of the meaning of a character is made, and -unfortunately there is a trigraph representation for a backslash, so it -is possible for the trigraph `??/' to introduce an escaped newline. - - Escaped newlines are tedious because theoretically they can occur -anywhere--between the `+' and `=' of the `+=' token, within the -characters of an identifier, and even between the `*' and `/' that -terminates a comment. Moreover, you cannot be sure there is just -one--there might be an arbitrarily long sequence of them. - - So, for example, the routine that lexes a number, `parse_number', -cannot assume that it can scan forwards until the first non-number -character and be done with it, because this could be the `\' -introducing an escaped newline, or the `?' introducing the trigraph -sequence that represents the `\' of an escaped newline. If it -encounters a `?' or `\', it calls `skip_escaped_newlines' to skip over -any potential escaped newlines before checking whether the number has -been finished. - - Similarly code in the main body of `_cpp_lex_direct' cannot simply -check for a `=' after a `+' character to determine whether it has a -`+=' token; it needs to be prepared for an escaped newline of some -sort. Such cases use the function `get_effective_char', which returns -the first character after any intervening escaped newlines. - - The lexer needs to keep track of the correct column position, -including counting tabs as specified by the `-ftabstop=' option. This -should be done even within C-style comments; they can appear in the -middle of a line, and we want to report diagnostics in the correct -position for text appearing after the end of the comment. - - Some identifiers, such as `__VA_ARGS__' and poisoned identifiers, -may be invalid and require a diagnostic. However, if they appear in a -macro expansion we don't want to complain with each use of the macro. -It is therefore best to catch them during the lexing stage, in -`parse_identifier'. In both cases, whether a diagnostic is needed or -not is dependent upon the lexer's state. For example, we don't want to -issue a diagnostic for re-poisoning a poisoned identifier, or for using -`__VA_ARGS__' in the expansion of a variable-argument macro. Therefore -`parse_identifier' makes use of state flags to determine whether a -diagnostic is appropriate. Since we change state on a per-token basis, -and don't lex whole lines at a time, this is not a problem. - - Another place where state flags are used to change behavior is whilst -lexing header names. Normally, a `<' would be lexed as a single token. -After a `#include' directive, though, it should be lexed as a single -token as far as the nearest `>' character. Note that we don't allow -the terminators of header names to be escaped; the first `"' or `>' -terminates the header name. - - Interpretation of some character sequences depends upon whether we -are lexing C, C++ or Objective-C, and on the revision of the standard in -force. For example, `::' is a single token in C++, but in C it is two -separate `:' tokens and almost certainly a syntax error. Such cases -are handled by `_cpp_lex_direct' based upon command-line flags stored -in the `cpp_options' structure. - - Once a token has been lexed, it leads an independent existence. The -spelling of numbers, identifiers and strings is copied to permanent -storage from the original input buffer, so a token remains valid and -correct even if its source buffer is freed with `_cpp_pop_buffer'. The -storage holding the spellings of such tokens remains until the client -program calls cpp_destroy, probably at the end of the translation unit. - -Lexing a line -============= - -When the preprocessor was changed to return pointers to tokens, one -feature I wanted was some sort of guarantee regarding how long a -returned pointer remains valid. This is important to the stand-alone -preprocessor, the future direction of the C family front ends, and even -to cpplib itself internally. - - Occasionally the preprocessor wants to be able to peek ahead in the -token stream. For example, after the name of a function-like macro, it -wants to check the next token to see if it is an opening parenthesis. -Another example is that, after reading the first few tokens of a -`#pragma' directive and not recognizing it as a registered pragma, it -wants to backtrack and allow the user-defined handler for unknown -pragmas to access the full `#pragma' token stream. The stand-alone -preprocessor wants to be able to test the current token with the -previous one to see if a space needs to be inserted to preserve their -separate tokenization upon re-lexing (paste avoidance), so it needs to -be sure the pointer to the previous token is still valid. The -recursive-descent C++ parser wants to be able to perform tentative -parsing arbitrarily far ahead in the token stream, and then to be able -to jump back to a prior position in that stream if necessary. - - The rule I chose, which is fairly natural, is to arrange that the -preprocessor lex all tokens on a line consecutively into a token buffer, -which I call a "token run", and when meeting an unescaped new line -(newlines within comments do not count either), to start lexing back at -the beginning of the run. Note that we do _not_ lex a line of tokens -at once; if we did that `parse_identifier' would not have state flags -available to warn about invalid identifiers (*note Invalid -identifiers::). - - In other words, accessing tokens that appeared earlier in the current -line is valid, but since each logical line overwrites the tokens of the -previous line, tokens from prior lines are unavailable. In particular, -since a directive only occupies a single logical line, this means that -the directive handlers like the `#pragma' handler can jump around in -the directive's tokens if necessary. - - Two issues remain: what about tokens that arise from macro -expansions, and what happens when we have a long line that overflows -the token run? - - Since we promise clients that we preserve the validity of pointers -that we have already returned for tokens that appeared earlier in the -line, we cannot reallocate the run. Instead, on overflow it is -expanded by chaining a new token run on to the end of the existing one. - - The tokens forming a macro's replacement list are collected by the -`#define' handler, and placed in storage that is only freed by -`cpp_destroy'. So if a macro is expanded in the line of tokens, the -pointers to the tokens of its expansion that are returned will always -remain valid. However, macros are a little trickier than that, since -they give rise to three sources of fresh tokens. They are the built-in -macros like `__LINE__', and the `#' and `##' operators for -stringification and token pasting. I handled this by allocating space -for these tokens from the lexer's token run chain. This means they -automatically receive the same lifetime guarantees as lexed tokens, and -we don't need to concern ourselves with freeing them. - - Lexing into a line of tokens solves some of the token memory -management issues, but not all. The opening parenthesis after a -function-like macro name might lie on a different line, and the front -ends definitely want the ability to look ahead past the end of the -current line. So cpplib only moves back to the start of the token run -at the end of a line if the variable `keep_tokens' is zero. -Line-buffering is quite natural for the preprocessor, and as a result -the only time cpplib needs to increment this variable is whilst looking -for the opening parenthesis to, and reading the arguments of, a -function-like macro. In the near future cpplib will export an -interface to increment and decrement this variable, so that clients can -share full control over the lifetime of token pointers too. - - The routine `_cpp_lex_token' handles moving to new token runs, -calling `_cpp_lex_direct' to lex new tokens, or returning -previously-lexed tokens if we stepped back in the token stream. It also -checks each token for the `BOL' flag, which might indicate a directive -that needs to be handled, or require a start-of-line call-back to be -made. `_cpp_lex_token' also handles skipping over tokens in failed -conditional blocks, and invalidates the control macro of the -multiple-include optimization if a token was successfully lexed outside -a directive. In other words, its callers do not need to concern -themselves with such issues. - - -File: cppinternals.info, Node: Hash Nodes, Next: Macro Expansion, Prev: Lexer, Up: Top - -Hash Nodes -********** - -When cpplib encounters an "identifier", it generates a hash code for it -and stores it in the hash table. By "identifier" we mean tokens with -type `CPP_NAME'; this includes identifiers in the usual C sense, as -well as keywords, directive names, macro names and so on. For example, -all of `pragma', `int', `foo' and `__GNUC__' are identifiers and hashed -when lexed. - - Each node in the hash table contain various information about the -identifier it represents. For example, its length and type. At any one -time, each identifier falls into exactly one of three categories: - - * Macros - - These have been declared to be macros, either on the command line - or with `#define'. A few, such as `__TIME__' are built-ins - entered in the hash table during initialization. The hash node - for a normal macro points to a structure with more information - about the macro, such as whether it is function-like, how many - arguments it takes, and its expansion. Built-in macros are - flagged as special, and instead contain an enum indicating which - of the various built-in macros it is. - - * Assertions - - Assertions are in a separate namespace to macros. To enforce - this, cpp actually prepends a `#' character before hashing and - entering it in the hash table. An assertion's node points to a - chain of answers to that assertion. - - * Void - - Everything else falls into this category--an identifier that is not - currently a macro, or a macro that has since been undefined with - `#undef'. - - When preprocessing C++, this category also includes the named - operators, such as `xor'. In expressions these behave like the - operators they represent, but in contexts where the spelling of a - token matters they are spelt differently. This spelling - distinction is relevant when they are operands of the stringizing - and pasting macro operators `#' and `##'. Named operator hash - nodes are flagged, both to catch the spelling distinction and to - prevent them from being defined as macros. - - The same identifiers share the same hash node. Since each identifier -token, after lexing, contains a pointer to its hash node, this is used -to provide rapid lookup of various information. For example, when -parsing a `#define' statement, CPP flags each argument's identifier -hash node with the index of that argument. This makes duplicated -argument checking an O(1) operation for each argument. Similarly, for -each identifier in the macro's expansion, lookup to see if it is an -argument, and which argument it is, is also an O(1) operation. Further, -each directive name, such as `endif', has an associated directive enum -stored in its hash node, so that directive lookup is also O(1). - - -File: cppinternals.info, Node: Macro Expansion, Next: Token Spacing, Prev: Hash Nodes, Up: Top - -Macro Expansion Algorithm -************************* - -Macro expansion is a tricky operation, fraught with nasty corner cases -and situations that render what you thought was a nifty way to optimize -the preprocessor's expansion algorithm wrong in quite subtle ways. - - I strongly recommend you have a good grasp of how the C and C++ -standards require macros to be expanded before diving into this -section, let alone the code!. If you don't have a clear mental picture -of how things like nested macro expansion, stringification and token -pasting are supposed to work, damage to your sanity can quickly result. - -Internal representation of macros -================================= - -The preprocessor stores macro expansions in tokenized form. This saves -repeated lexing passes during expansion, at the cost of a small -increase in memory consumption on average. The tokens are stored -contiguously in memory, so a pointer to the first one and a token count -is all you need to get the replacement list of a macro. - - If the macro is a function-like macro the preprocessor also stores -its parameters, in the form of an ordered list of pointers to the hash -table entry of each parameter's identifier. Further, in the macro's -stored expansion each occurrence of a parameter is replaced with a -special token of type `CPP_MACRO_ARG'. Each such token holds the index -of the parameter it represents in the parameter list, which allows -rapid replacement of parameters with their arguments during expansion. -Despite this optimization it is still necessary to store the original -parameters to the macro, both for dumping with e.g., `-dD', and to warn -about non-trivial macro redefinitions when the parameter names have -changed. - -Macro expansion overview -======================== - -The preprocessor maintains a "context stack", implemented as a linked -list of `cpp_context' structures, which together represent the macro -expansion state at any one time. The `struct cpp_reader' member -variable `context' points to the current top of this stack. The top -normally holds the unexpanded replacement list of the innermost macro -under expansion, except when cpplib is about to pre-expand an argument, -in which case it holds that argument's unexpanded tokens. - - When there are no macros under expansion, cpplib is in "base -context". All contexts other than the base context contain a -contiguous list of tokens delimited by a starting and ending token. -When not in base context, cpplib obtains the next token from the list -of the top context. If there are no tokens left in the list, it pops -that context off the stack, and subsequent ones if necessary, until an -unexhausted context is found or it returns to base context. In base -context, cpplib reads tokens directly from the lexer. - - If it encounters an identifier that is both a macro and enabled for -expansion, cpplib prepares to push a new context for that macro on the -stack by calling the routine `enter_macro_context'. When this routine -returns, the new context will contain the unexpanded tokens of the -replacement list of that macro. In the case of function-like macros, -`enter_macro_context' also replaces any parameters in the replacement -list, stored as `CPP_MACRO_ARG' tokens, with the appropriate macro -argument. If the standard requires that the parameter be replaced with -its expanded argument, the argument will have been fully macro expanded -first. - - `enter_macro_context' also handles special macros like `__LINE__'. -Although these macros expand to a single token which cannot contain any -further macros, for reasons of token spacing (*note Token Spacing::) -and simplicity of implementation, cpplib handles these special macros -by pushing a context containing just that one token. - - The final thing that `enter_macro_context' does before returning is -to mark the macro disabled for expansion (except for special macros -like `__TIME__'). The macro is re-enabled when its context is later -popped from the context stack, as described above. This strict -ordering ensures that a macro is disabled whilst its expansion is being -scanned, but that it is _not_ disabled whilst any arguments to it are -being expanded. - -Scanning the replacement list for macros to expand -================================================== - -The C standard states that, after any parameters have been replaced -with their possibly-expanded arguments, the replacement list is scanned -for nested macros. Further, any identifiers in the replacement list -that are not expanded during this scan are never again eligible for -expansion in the future, if the reason they were not expanded is that -the macro in question was disabled. - - Clearly this latter condition can only apply to tokens resulting from -argument pre-expansion. Other tokens never have an opportunity to be -re-tested for expansion. It is possible for identifiers that are -function-like macros to not expand initially but to expand during a -later scan. This occurs when the identifier is the last token of an -argument (and therefore originally followed by a comma or a closing -parenthesis in its macro's argument list), and when it replaces its -parameter in the macro's replacement list, the subsequent token happens -to be an opening parenthesis (itself possibly the first token of an -argument). - - It is important to note that when cpplib reads the last token of a -given context, that context still remains on the stack. Only when -looking for the _next_ token do we pop it off the stack and drop to a -lower context. This makes backing up by one token easy, but more -importantly ensures that the macro corresponding to the current context -is still disabled when we are considering the last token of its -replacement list for expansion (or indeed expanding it). As an -example, which illustrates many of the points above, consider - - #define foo(x) bar x - foo(foo) (2) - -which fully expands to `bar foo (2)'. During pre-expansion of the -argument, `foo' does not expand even though the macro is enabled, since -it has no following parenthesis [pre-expansion of an argument only uses -tokens from that argument; it cannot take tokens from whatever follows -the macro invocation]. This still leaves the argument token `foo' -eligible for future expansion. Then, when re-scanning after argument -replacement, the token `foo' is rejected for expansion, and marked -ineligible for future expansion, since the macro is now disabled. It -is disabled because the replacement list `bar foo' of the macro is -still on the context stack. - - If instead the algorithm looked for an opening parenthesis first and -then tested whether the macro were disabled it would be subtly wrong. -In the example above, the replacement list of `foo' would be popped in -the process of finding the parenthesis, re-enabling `foo' and expanding -it a second time. - -Looking for a function-like macro's opening parenthesis -======================================================= - -Function-like macros only expand when immediately followed by a -parenthesis. To do this cpplib needs to temporarily disable macros and -read the next token. Unfortunately, because of spacing issues (*note -Token Spacing::), there can be fake padding tokens in-between, and if -the next real token is not a parenthesis cpplib needs to be able to -back up that one token as well as retain the information in any -intervening padding tokens. - - Backing up more than one token when macros are involved is not -permitted by cpplib, because in general it might involve issues like -restoring popped contexts onto the context stack, which are too hard. -Instead, searching for the parenthesis is handled by a special -function, `funlike_invocation_p', which remembers padding information -as it reads tokens. If the next real token is not an opening -parenthesis, it backs up that one token, and then pushes an extra -context just containing the padding information if necessary. - -Marking tokens ineligible for future expansion -============================================== - -As discussed above, cpplib needs a way of marking tokens as -unexpandable. Since the tokens cpplib handles are read-only once they -have been lexed, it instead makes a copy of the token and adds the flag -`NO_EXPAND' to the copy. - - For efficiency and to simplify memory management by avoiding having -to remember to free these tokens, they are allocated as temporary tokens -from the lexer's current token run (*note Lexing a line::) using the -function `_cpp_temp_token'. The tokens are then re-used once the -current line of tokens has been read in. - - This might sound unsafe. However, tokens runs are not re-used at the -end of a line if it happens to be in the middle of a macro argument -list, and cpplib only wants to back-up more than one lexer token in -situations where no macro expansion is involved, so the optimization is -safe. - - -File: cppinternals.info, Node: Token Spacing, Next: Line Numbering, Prev: Macro Expansion, Up: Top - -Token Spacing -************* - -First, consider an issue that only concerns the stand-alone -preprocessor: there needs to be a guarantee that re-reading its -preprocessed output results in an identical token stream. Without -taking special measures, this might not be the case because of macro -substitution. For example: - - #define PLUS + - #define EMPTY - #define f(x) =x= - +PLUS -EMPTY- PLUS+ f(=) - ==> + + - - + + = = = - _not_ - ==> ++ -- ++ === - - One solution would be to simply insert a space between all adjacent -tokens. However, we would like to keep space insertion to a minimum, -both for aesthetic reasons and because it causes problems for people who -still try to abuse the preprocessor for things like Fortran source and -Makefiles. - - For now, just notice that when tokens are added (or removed, as -shown by the `EMPTY' example) from the original lexed token stream, we -need to check for accidental token pasting. We call this "paste -avoidance". Token addition and removal can only occur because of macro -expansion, but accidental pasting can occur in many places: both before -and after each macro replacement, each argument replacement, and -additionally each token created by the `#' and `##' operators. - - Look at how the preprocessor gets whitespace output correct -normally. The `cpp_token' structure contains a flags byte, and one of -those flags is `PREV_WHITE'. This is flagged by the lexer, and -indicates that the token was preceded by whitespace of some form other -than a new line. The stand-alone preprocessor can use this flag to -decide whether to insert a space between tokens in the output. - - Now consider the result of the following macro expansion: - - #define add(x, y, z) x + y +z; - sum = add (1,2, 3); - ==> sum = 1 + 2 +3; - - The interesting thing here is that the tokens `1' and `2' are output -with a preceding space, and `3' is output without a preceding space, -but when lexed none of these tokens had that property. Careful -consideration reveals that `1' gets its preceding whitespace from the -space preceding `add' in the macro invocation, _not_ replacement list. -`2' gets its whitespace from the space preceding the parameter `y' in -the macro replacement list, and `3' has no preceding space because -parameter `z' has none in the replacement list. - - Once lexed, tokens are effectively fixed and cannot be altered, since -pointers to them might be held in many places, in particular by -in-progress macro expansions. So instead of modifying the two tokens -above, the preprocessor inserts a special token, which I call a -"padding token", into the token stream to indicate that spacing of the -subsequent token is special. The preprocessor inserts padding tokens -in front of every macro expansion and expanded macro argument. These -point to a "source token" from which the subsequent real token should -inherit its spacing. In the above example, the source tokens are `add' -in the macro invocation, and `y' and `z' in the macro replacement list, -respectively. - - It is quite easy to get multiple padding tokens in a row, for -example if a macro's first replacement token expands straight into -another macro. - - #define foo bar - #define bar baz - [foo] - ==> [baz] - - Here, two padding tokens are generated with sources the `foo' token -between the brackets, and the `bar' token from foo's replacement list, -respectively. Clearly the first padding token is the one to use, so -the output code should contain a rule that the first padding token in a -sequence is the one that matters. - - But what if a macro expansion is left? Adjusting the above example -slightly: - - #define foo bar - #define bar EMPTY baz - #define EMPTY - [foo] EMPTY; - ==> [ baz] ; - - As shown, now there should be a space before `baz' and the semicolon -in the output. - - The rules we decided above fail for `baz': we generate three padding -tokens, one per macro invocation, before the token `baz'. We would -then have it take its spacing from the first of these, which carries -source token `foo' with no leading space. - - It is vital that cpplib get spacing correct in these examples since -any of these macro expansions could be stringified, where spacing -matters. - - So, this demonstrates that not just entering macro and argument -expansions, but leaving them requires special handling too. I made -cpplib insert a padding token with a `NULL' source token when leaving -macro expansions, as well as after each replaced argument in a macro's -replacement list. It also inserts appropriate padding tokens on either -side of tokens created by the `#' and `##' operators. I expanded the -rule so that, if we see a padding token with a `NULL' source token, -_and_ that source token has no leading space, then we behave as if we -have seen no padding tokens at all. A quick check shows this rule will -then get the above example correct as well. - - Now a relationship with paste avoidance is apparent: we have to be -careful about paste avoidance in exactly the same locations we have -padding tokens in order to get white space correct. This makes -implementation of paste avoidance easy: wherever the stand-alone -preprocessor is fixing up spacing because of padding tokens, and it -turns out that no space is needed, it has to take the extra step to -check that a space is not needed after all to avoid an accidental paste. -The function `cpp_avoid_paste' advises whether a space is required -between two consecutive tokens. To avoid excessive spacing, it tries -hard to only require a space if one is likely to be necessary, but for -reasons of efficiency it is slightly conservative and might recommend a -space where one is not strictly needed. - - -File: cppinternals.info, Node: Line Numbering, Next: Guard Macros, Prev: Token Spacing, Up: Top - -Line numbering -************** - -Just which line number anyway? -============================== - -There are three reasonable requirements a cpplib client might have for -the line number of a token passed to it: - - * The source line it was lexed on. - - * The line it is output on. This can be different to the line it was - lexed on if, for example, there are intervening escaped newlines or - C-style comments. For example: - - foo /* A long - comment */ bar \ - baz - => - foo bar baz - - * If the token results from a macro expansion, the line of the macro - name, or possibly the line of the closing parenthesis in the case - of function-like macro expansion. - - The `cpp_token' structure contains `line' and `col' members. The -lexer fills these in with the line and column of the first character of -the token. Consequently, but maybe unexpectedly, a token from the -replacement list of a macro expansion carries the location of the token -within the `#define' directive, because cpplib expands a macro by -returning pointers to the tokens in its replacement list. The current -implementation of cpplib assigns tokens created from built-in macros -and the `#' and `##' operators the location of the most recently lexed -token. This is a because they are allocated from the lexer's token -runs, and because of the way the diagnostic routines infer the -appropriate location to report. - - The diagnostic routines in cpplib display the location of the most -recently _lexed_ token, unless they are passed a specific line and -column to report. For diagnostics regarding tokens that arise from -macro expansions, it might also be helpful for the user to see the -original location in the macro definition that the token came from. -Since that is exactly the information each token carries, such an -enhancement could be made relatively easily in future. - - The stand-alone preprocessor faces a similar problem when determining -the correct line to output the token on: the position attached to a -token is fairly useless if the token came from a macro expansion. All -tokens on a logical line should be output on its first physical line, so -the token's reported location is also wrong if it is part of a physical -line other than the first. - - To solve these issues, cpplib provides a callback that is generated -whenever it lexes a preprocessing token that starts a new logical line -other than a directive. It passes this token (which may be a `CPP_EOF' -token indicating the end of the translation unit) to the callback -routine, which can then use the line and column of this token to -produce correct output. - -Representation of line numbers -============================== - -As mentioned above, cpplib stores with each token the line number that -it was lexed on. In fact, this number is not the number of the line in -the source file, but instead bears more resemblance to the number of the -line in the translation unit. - - The preprocessor maintains a monotonic increasing line count, which -is incremented at every new line character (and also at the end of any -buffer that does not end in a new line). Since a line number of zero is -useful to indicate certain special states and conditions, this variable -starts counting from one. - - This variable therefore uniquely enumerates each line in the -translation unit. With some simple infrastructure, it is straight -forward to map from this to the original source file and line number -pair, saving space whenever line number information needs to be saved. -The code the implements this mapping lies in the files `line-map.c' and -`line-map.h'. - - Command-line macros and assertions are implemented by pushing a -buffer containing the right hand side of an equivalent `#define' or -`#assert' directive. Some built-in macros are handled similarly. -Since these are all processed before the first line of the main input -file, it will typically have an assigned line closer to twenty than to -one. - - -File: cppinternals.info, Node: Guard Macros, Next: Files, Prev: Line Numbering, Up: Top - -The Multiple-Include Optimization -********************************* - -Header files are often of the form - - #ifndef FOO - #define FOO - ... - #endif - -to prevent the compiler from processing them more than once. The -preprocessor notices such header files, so that if the header file -appears in a subsequent `#include' directive and `FOO' is defined, then -it is ignored and it doesn't preprocess or even re-open the file a -second time. This is referred to as the "multiple include -optimization". - - Under what circumstances is such an optimization valid? If the file -were included a second time, it can only be optimized away if that -inclusion would result in no tokens to return, and no relevant -directives to process. Therefore the current implementation imposes -requirements and makes some allowances as follows: - - 1. There must be no tokens outside the controlling `#if'-`#endif' - pair, but whitespace and comments are permitted. - - 2. There must be no directives outside the controlling directive - pair, but the "null directive" (a line containing nothing other - than a single `#' and possibly whitespace) is permitted. - - 3. The opening directive must be of the form - - #ifndef FOO - - or - - #if !defined FOO [equivalently, #if !defined(FOO)] - - 4. In the second form above, the tokens forming the `#if' expression - must have come directly from the source file--no macro expansion - must have been involved. This is because macro definitions can - change, and tracking whether or not a relevant change has been - made is not worth the implementation cost. - - 5. There can be no `#else' or `#elif' directives at the outer - conditional block level, because they would probably contain - something of interest to a subsequent pass. - - First, when pushing a new file on the buffer stack, -`_stack_include_file' sets the controlling macro `mi_cmacro' to `NULL', -and sets `mi_valid' to `true'. This indicates that the preprocessor -has not yet encountered anything that would invalidate the -multiple-include optimization. As described in the next few -paragraphs, these two variables having these values effectively -indicates top-of-file. - - When about to return a token that is not part of a directive, -`_cpp_lex_token' sets `mi_valid' to `false'. This enforces the -constraint that tokens outside the controlling conditional block -invalidate the optimization. - - The `do_if', when appropriate, and `do_ifndef' directive handlers -pass the controlling macro to the function `push_conditional'. cpplib -maintains a stack of nested conditional blocks, and after processing -every opening conditional this function pushes an `if_stack' structure -onto the stack. In this structure it records the controlling macro for -the block, provided there is one and we're at top-of-file (as described -above). If an `#elif' or `#else' directive is encountered, the -controlling macro for that block is cleared to `NULL'. Otherwise, it -survives until the `#endif' closing the block, upon which `do_endif' -sets `mi_valid' to true and stores the controlling macro in `mi_cmacro'. - - `_cpp_handle_directive' clears `mi_valid' when processing any -directive other than an opening conditional and the null directive. -With this, and requiring top-of-file to record a controlling macro, and -no `#else' or `#elif' for it to survive and be copied to `mi_cmacro' by -`do_endif', we have enforced the absence of directives outside the main -conditional block for the optimization to be on. - - Note that whilst we are inside the conditional block, `mi_valid' is -likely to be reset to `false', but this does not matter since the -closing `#endif' restores it to `true' if appropriate. - - Finally, since `_cpp_lex_direct' pops the file off the buffer stack -at `EOF' without returning a token, if the `#endif' directive was not -followed by any tokens, `mi_valid' is `true' and `_cpp_pop_file_buffer' -remembers the controlling macro associated with the file. Subsequent -calls to `stack_include_file' result in no buffer being pushed if the -controlling macro is defined, effecting the optimization. - - A quick word on how we handle the - - #if !defined FOO - -case. `_cpp_parse_expr' and `parse_defined' take steps to see whether -the three stages `!', `defined-expression' and `end-of-directive' occur -in order in a `#if' expression. If so, they return the guard macro to -`do_if' in the variable `mi_ind_cmacro', and otherwise set it to `NULL'. -`enter_macro_context' sets `mi_valid' to false, so if a macro was -expanded whilst parsing any part of the expression, then the -top-of-file test in `push_conditional' fails and the optimization is -turned off. - - -File: cppinternals.info, Node: Files, Next: Concept Index, Prev: Guard Macros, Up: Top - -File Handling -************* - -Fairly obviously, the file handling code of cpplib resides in the file -`files.c'. It takes care of the details of file searching, opening, -reading and caching, for both the main source file and all the headers -it recursively includes. - - The basic strategy is to minimize the number of system calls. On -many systems, the basic `open ()' and `fstat ()' system calls can be -quite expensive. For every `#include'-d file, we need to try all the -directories in the search path until we find a match. Some projects, -such as glibc, pass twenty or thirty include paths on the command line, -so this can rapidly become time consuming. - - For a header file we have not encountered before we have little -choice but to do this. However, it is often the case that the same -headers are repeatedly included, and in these cases we try to avoid -repeating the filesystem queries whilst searching for the correct file. - - For each file we try to open, we store the constructed path in a -splay tree. This path first undergoes simplification by the function -`_cpp_simplify_pathname'. For example, `/usr/include/bits/../foo.h' is -simplified to `/usr/include/foo.h' before we enter it in the splay tree -and try to `open ()' the file. CPP will then find subsequent uses of -`foo.h', even as `/usr/include/foo.h', in the splay tree and save -system calls. - - Further, it is likely the file contents have also been cached, -saving a `read ()' system call. We don't bother caching the contents of -header files that are re-inclusion protected, and whose re-inclusion -macro is defined when we leave the header file for the first time. If -the host supports it, we try to map suitably large files into memory, -rather than reading them in directly. - - The include paths are internally stored on a null-terminated -singly-linked list, starting with the `"header.h"' directory search -chain, which then links into the `' directory chain. - - Files included with the `' syntax start the lookup directly -in the second half of this chain. However, files included with the -`"foo.h"' syntax start at the beginning of the chain, but with one -extra directory prepended. This is the directory of the current file; -the one containing the `#include' directive. Prepending this directory -on a per-file basis is handled by the function `search_from'. - - Note that a header included with a directory component, such as -`#include "mydir/foo.h"' and opened as -`/usr/local/include/mydir/foo.h', will have the complete path minus the -basename `foo.h' as the current directory. - - Enough information is stored in the splay tree that CPP can -immediately tell whether it can skip the header file because of the -multiple include optimization, whether the file didn't exist or -couldn't be opened for some reason, or whether the header was flagged -not to be re-used, as it is with the obsolete `#import' directive. - - For the benefit of MS-DOS filesystems with an 8.3 filename -limitation, CPP offers the ability to treat various include file names -as aliases for the real header files with shorter names. The map from -one to the other is found in a special file called `header.gcc', stored -in the command line (or system) include directories to which the mapping -applies. This may be higher up the directory tree than the full path to -the file minus the base name. - - -File: cppinternals.info, Node: Concept Index, Prev: Files, Up: Top - -Concept Index -************* - -[index] -* Menu: - -* assertions: Hash Nodes. (line 6) -* controlling macros: Guard Macros. (line 6) -* escaped newlines: Lexer. (line 6) -* files: Files. (line 6) -* guard macros: Guard Macros. (line 6) -* hash table: Hash Nodes. (line 6) -* header files: Conventions. (line 6) -* identifiers: Hash Nodes. (line 6) -* interface: Conventions. (line 6) -* lexer: Lexer. (line 6) -* line numbers: Line Numbering. (line 6) -* macro expansion: Macro Expansion. (line 6) -* macro representation (internal): Macro Expansion. (line 19) -* macros: Hash Nodes. (line 6) -* multiple-include optimization: Guard Macros. (line 6) -* named operators: Hash Nodes. (line 6) -* newlines: Lexer. (line 6) -* paste avoidance: Token Spacing. (line 6) -* spacing: Token Spacing. (line 6) -* token run: Lexer. (line 192) -* token spacing: Token Spacing. (line 6) - - - -Tag Table: -Node: Top971 -Node: Conventions2656 -Node: Lexer3598 -Ref: Invalid identifiers11511 -Ref: Lexing a line13460 -Node: Hash Nodes18233 -Node: Macro Expansion21112 -Node: Token Spacing30059 -Node: Line Numbering35919 -Node: Guard Macros40004 -Node: Files44795 -Node: Concept Index48261 - -End Tag Table diff --git a/gcc/doc/gcc.info b/gcc/doc/gcc.info deleted file mode 100644 index 4db3e172..00000000 --- a/gcc/doc/gcc.info +++ /dev/null @@ -1,44028 +0,0 @@ -This is doc/gcc.info, produced by makeinfo version 4.13 from -/d/gcc-4.4.3/gcc-4.4.3/gcc/doc/gcc.texi. - -Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, -1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 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.2 or -any later version published by the Free Software Foundation; with the -Invariant Sections being "Funding Free Software", the Front-Cover Texts -being (a) (see below), and with the Back-Cover Texts being (b) (see -below). A copy of the license is included in the section entitled "GNU -Free Documentation License". - - (a) The FSF's Front-Cover Text is: - - A GNU Manual - - (b) The FSF's Back-Cover Text is: - - You have freedom to copy and modify this GNU Manual, like GNU -software. Copies published by the Free Software Foundation raise -funds for GNU development. - -INFO-DIR-SECTION Software development -START-INFO-DIR-ENTRY -* gcc: (gcc). The GNU Compiler Collection. -* g++: (gcc). The GNU C++ compiler. -END-INFO-DIR-ENTRY - This file documents the use of the GNU compilers. - - Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, -1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 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.2 or -any later version published by the Free Software Foundation; with the -Invariant Sections being "Funding Free Software", the Front-Cover Texts -being (a) (see below), and with the Back-Cover Texts being (b) (see -below). A copy of the license is included in the section entitled "GNU -Free Documentation License". - - (a) The FSF's Front-Cover Text is: - - A GNU Manual - - (b) The FSF's Back-Cover Text is: - - You have freedom to copy and modify this GNU Manual, like GNU -software. Copies published by the Free Software Foundation raise -funds for GNU development. - - - -File: gcc.info, Node: Top, Next: G++ and GCC, Up: (DIR) - -Introduction -************ - -This manual documents how to use the GNU compilers, as well as their -features and incompatibilities, and how to report bugs. It corresponds -to the compilers (GCC) version 4.4.3. The internals of the GNU -compilers, including how to port them to new targets and some -information about how to write front ends for new languages, are -documented in a separate manual. *Note Introduction: (gccint)Top. - -* Menu: - -* G++ and GCC:: You can compile C or C++ programs. -* Standards:: Language standards supported by GCC. -* Invoking GCC:: Command options supported by `gcc'. -* C Implementation:: How GCC implements the ISO C specification. -* C Extensions:: GNU extensions to the C language family. -* C++ Extensions:: GNU extensions to the C++ language. -* Objective-C:: GNU Objective-C runtime features. -* Compatibility:: Binary Compatibility -* Gcov:: `gcov'---a test coverage program. -* Trouble:: If you have trouble using GCC. -* Bugs:: How, why and where to report bugs. -* Service:: How to find suppliers of support for GCC. -* Contributing:: How to contribute to testing and developing GCC. - -* Funding:: How to help assure funding for free software. -* GNU Project:: The GNU Project and GNU/Linux. - -* Copying:: GNU General Public License says - how you can copy and share GCC. -* GNU Free Documentation License:: How you can copy and share this manual. -* Contributors:: People who have contributed to GCC. - -* Option Index:: Index to command line options. -* Keyword Index:: Index of concepts and symbol names. - - -File: gcc.info, Node: G++ and GCC, Next: Standards, Prev: Top, Up: Top - -1 Programming Languages Supported by GCC -**************************************** - -GCC stands for "GNU Compiler Collection". GCC is an integrated -distribution of compilers for several major programming languages. -These languages currently include C, C++, Objective-C, Objective-C++, -Java, Fortran, and Ada. - - The abbreviation "GCC" has multiple meanings in common use. The -current official meaning is "GNU Compiler Collection", which refers -generically to the complete suite of tools. The name historically stood -for "GNU C Compiler", and this usage is still common when the emphasis -is on compiling C programs. Finally, the name is also used when -speaking of the "language-independent" component of GCC: code shared -among the compilers for all supported languages. - - The language-independent component of GCC includes the majority of the -optimizers, as well as the "back ends" that generate machine code for -various processors. - - The part of a compiler that is specific to a particular language is -called the "front end". In addition to the front ends that are -integrated components of GCC, there are several other front ends that -are maintained separately. These support languages such as Pascal, -Mercury, and COBOL. To use these, they must be built together with GCC -proper. - - Most of the compilers for languages other than C have their own names. -The C++ compiler is G++, the Ada compiler is GNAT, and so on. When we -talk about compiling one of those languages, we might refer to that -compiler by its own name, or as GCC. Either is correct. - - Historically, compilers for many languages, including C++ and Fortran, -have been implemented as "preprocessors" which emit another high level -language such as C. None of the compilers included in GCC are -implemented this way; they all generate machine code directly. This -sort of preprocessor should not be confused with the "C preprocessor", -which is an integral feature of the C, C++, Objective-C and -Objective-C++ languages. - - -File: gcc.info, Node: Standards, Next: Invoking GCC, Prev: G++ and GCC, Up: Top - -2 Language Standards Supported by GCC -************************************* - -For each language compiled by GCC for which there is a standard, GCC -attempts to follow one or more versions of that standard, possibly with -some exceptions, and possibly with some extensions. - -2.1 C language -============== - -GCC supports three versions of the C standard, although support for the -most recent version is not yet complete. - - The original ANSI C standard (X3.159-1989) was ratified in 1989 and -published in 1990. This standard was ratified as an ISO standard -(ISO/IEC 9899:1990) later in 1990. There were no technical differences -between these publications, although the sections of the ANSI standard -were renumbered and became clauses in the ISO standard. This standard, -in both its forms, is commonly known as "C89", or occasionally as -"C90", from the dates of ratification. The ANSI standard, but not the -ISO standard, also came with a Rationale document. To select this -standard in GCC, use one of the options `-ansi', `-std=c89' or -`-std=iso9899:1990'; to obtain all the diagnostics required by the -standard, you should also specify `-pedantic' (or `-pedantic-errors' if -you want them to be errors rather than warnings). *Note Options -Controlling C Dialect: C Dialect Options. - - Errors in the 1990 ISO C standard were corrected in two Technical -Corrigenda published in 1994 and 1996. GCC does not support the -uncorrected version. - - An amendment to the 1990 standard was published in 1995. This -amendment added digraphs and `__STDC_VERSION__' to the language, but -otherwise concerned the library. This amendment is commonly known as -"AMD1"; the amended standard is sometimes known as "C94" or "C95". To -select this standard in GCC, use the option `-std=iso9899:199409' -(with, as for other standard versions, `-pedantic' to receive all -required diagnostics). - - A new edition of the ISO C standard was published in 1999 as ISO/IEC -9899:1999, and is commonly known as "C99". GCC has incomplete support -for this standard version; see -`http://gcc.gnu.org/gcc-4.4/c99status.html' for details. To select this -standard, use `-std=c99' or `-std=iso9899:1999'. (While in -development, drafts of this standard version were referred to as "C9X".) - - Errors in the 1999 ISO C standard were corrected in three Technical -Corrigenda published in 2001, 2004 and 2007. GCC does not support the -uncorrected version. - - By default, GCC provides some extensions to the C language that on -rare occasions conflict with the C standard. *Note Extensions to the C -Language Family: C Extensions. Use of the `-std' options listed above -will disable these extensions where they conflict with the C standard -version selected. You may also select an extended version of the C -language explicitly with `-std=gnu89' (for C89 with GNU extensions) or -`-std=gnu99' (for C99 with GNU extensions). The default, if no C -language dialect options are given, is `-std=gnu89'; this will change to -`-std=gnu99' in some future release when the C99 support is complete. -Some features that are part of the C99 standard are accepted as -extensions in C89 mode. - - The ISO C standard defines (in clause 4) two classes of conforming -implementation. A "conforming hosted implementation" supports the -whole standard including all the library facilities; a "conforming -freestanding implementation" is only required to provide certain -library facilities: those in `', `', `', -and `'; since AMD1, also those in `'; and in C99, -also those in `' and `'. In addition, complex -types, added in C99, are not required for freestanding implementations. -The standard also defines two environments for programs, a -"freestanding environment", required of all implementations and which -may not have library facilities beyond those required of freestanding -implementations, where the handling of program startup and termination -are implementation-defined, and a "hosted environment", which is not -required, in which all the library facilities are provided and startup -is through a function `int main (void)' or `int main (int, char *[])'. -An OS kernel would be a freestanding environment; a program using the -facilities of an operating system would normally be in a hosted -implementation. - - GCC aims towards being usable as a conforming freestanding -implementation, or as the compiler for a conforming hosted -implementation. By default, it will act as the compiler for a hosted -implementation, defining `__STDC_HOSTED__' as `1' and presuming that -when the names of ISO C functions are used, they have the semantics -defined in the standard. To make it act as a conforming freestanding -implementation for a freestanding environment, use the option -`-ffreestanding'; it will then define `__STDC_HOSTED__' to `0' and not -make assumptions about the meanings of function names from the standard -library, with exceptions noted below. To build an OS kernel, you may -well still need to make your own arrangements for linking and startup. -*Note Options Controlling C Dialect: C Dialect Options. - - GCC does not provide the library facilities required only of hosted -implementations, nor yet all the facilities required by C99 of -freestanding implementations; to use the facilities of a hosted -environment, you will need to find them elsewhere (for example, in the -GNU C library). *Note Standard Libraries: Standard Libraries. - - Most of the compiler support routines used by GCC are present in -`libgcc', but there are a few exceptions. GCC requires the -freestanding environment provide `memcpy', `memmove', `memset' and -`memcmp'. Finally, if `__builtin_trap' is used, and the target does -not implement the `trap' pattern, then GCC will emit a call to `abort'. - - For references to Technical Corrigenda, Rationale documents and -information concerning the history of C that is available online, see -`http://gcc.gnu.org/readings.html' - -2.2 C++ language -================ - -GCC supports the ISO C++ standard (1998) and contains experimental -support for the upcoming ISO C++ standard (200x). - - The original ISO C++ standard was published as the ISO standard -(ISO/IEC 14882:1998) and amended by a Technical Corrigenda published in -2003 (ISO/IEC 14882:2003). These standards are referred to as C++98 and -C++03, respectively. GCC implements the majority of C++98 (`export' is -a notable exception) and most of the changes in C++03. To select this -standard in GCC, use one of the options `-ansi' or `-std=c++98'; to -obtain all the diagnostics required by the standard, you should also -specify `-pedantic' (or `-pedantic-errors' if you want them to be -errors rather than warnings). - - The ISO C++ committee is working on a new ISO C++ standard, dubbed -C++0x, that is intended to be published by 2009. C++0x contains several -changes to the C++ language, some of which have been implemented in an -experimental C++0x mode in GCC. The C++0x mode in GCC tracks the draft -working paper for the C++0x standard; the latest working paper is -available on the ISO C++ committee's web site at -`http://www.open-std.org/jtc1/sc22/wg21/'. For information regarding -the C++0x features available in the experimental C++0x mode, see -`http://gcc.gnu.org/gcc-4.3/cxx0x_status.html'. To select this standard -in GCC, use the option `-std=c++0x'; to obtain all the diagnostics -required by the standard, you should also specify `-pedantic' (or -`-pedantic-errors' if you want them to be errors rather than warnings). - - By default, GCC provides some extensions to the C++ language; *Note -Options Controlling C++ Dialect: C++ Dialect Options. Use of the -`-std' option listed above will disable these extensions. You may also -select an extended version of the C++ language explicitly with -`-std=gnu++98' (for C++98 with GNU extensions) or `-std=gnu++0x' (for -C++0x with GNU extensions). The default, if no C++ language dialect -options are given, is `-std=gnu++98'. - -2.3 Objective-C and Objective-C++ languages -=========================================== - -There is no formal written standard for Objective-C or Objective-C++. -The most authoritative manual is "Object-Oriented Programming and the -Objective-C Language", available at a number of web sites: - - * - `http://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/' - is a recent (and periodically updated) version; - - * `http://www.toodarkpark.org/computers/objc/' is an older example; - - * `http://www.gnustep.org' and `http://gcc.gnu.org/readings.html' - have additional useful information. - - *Note GNAT Reference Manual: (gnat_rm)Top, for information on standard -conformance and compatibility of the Ada compiler. - - *Note Standards: (gfortran)Standards, for details of standards -supported by GNU Fortran. - - *Note Compatibility with the Java Platform: (gcj)Compatibility, for -details of compatibility between `gcj' and the Java Platform. - - -File: gcc.info, Node: Invoking GCC, Next: C Implementation, Prev: Standards, Up: Top - -3 GCC Command Options -********************* - -When you invoke GCC, it normally does preprocessing, compilation, -assembly and linking. The "overall options" allow you to stop this -process at an intermediate stage. For example, the `-c' option says -not to run the linker. Then the output consists of object files output -by the assembler. - - Other options are passed on to one stage of processing. Some options -control the preprocessor and others the compiler itself. Yet other -options control the assembler and linker; most of these are not -documented here, since you rarely need to use any of them. - - Most of the command line options that you can use with GCC are useful -for C programs; when an option is only useful with another language -(usually C++), the explanation says so explicitly. If the description -for a particular option does not mention a source language, you can use -that option with all supported languages. - - *Note Compiling C++ Programs: Invoking G++, for a summary of special -options for compiling C++ programs. - - The `gcc' program accepts options and file names as operands. Many -options have multi-letter names; therefore multiple single-letter -options may _not_ be grouped: `-dv' is very different from `-d -v'. - - You can mix options and other arguments. For the most part, the order -you use doesn't matter. Order does matter when you use several options -of the same kind; for example, if you specify `-L' more than once, the -directories are searched in the order specified. Also, the placement -of the `-l' option is significant. - - Many options have long names starting with `-f' or with `-W'--for -example, `-fmove-loop-invariants', `-Wformat' and so on. Most of these -have both positive and negative forms; the negative form of `-ffoo' -would be `-fno-foo'. This manual documents only one of these two -forms, whichever one is not the default. - - *Note Option Index::, for an index to GCC's options. - -* Menu: - -* Option Summary:: Brief list of all options, without explanations. -* Overall Options:: Controlling the kind of output: - an executable, object files, assembler files, - or preprocessed source. -* Invoking G++:: Compiling C++ programs. -* C Dialect Options:: Controlling the variant of C language compiled. -* C++ Dialect Options:: Variations on C++. -* Objective-C and Objective-C++ Dialect Options:: Variations on Objective-C - and Objective-C++. -* Language Independent Options:: Controlling how diagnostics should be - formatted. -* Warning Options:: How picky should the compiler be? -* Debugging Options:: Symbol tables, measurements, and debugging dumps. -* Optimize Options:: How much optimization? -* Preprocessor Options:: Controlling header files and macro definitions. - Also, getting dependency information for Make. -* Assembler Options:: Passing options to the assembler. -* Link Options:: Specifying libraries and so on. -* Directory Options:: Where to find header files and libraries. - Where to find the compiler executable files. -* Spec Files:: How to pass switches to sub-processes. -* Target Options:: Running a cross-compiler, or an old version of GCC. -* Submodel Options:: Specifying minor hardware or convention variations, - such as 68010 vs 68020. -* Code Gen Options:: Specifying conventions for function calls, data layout - and register usage. -* Environment Variables:: Env vars that affect GCC. -* Precompiled Headers:: Compiling a header once, and using it many times. -* Running Protoize:: Automatically adding or removing function prototypes. - - -File: gcc.info, Node: Option Summary, Next: Overall Options, Up: Invoking GCC - -3.1 Option Summary -================== - -Here is a summary of all the options, grouped by type. Explanations are -in the following sections. - -_Overall Options_ - *Note Options Controlling the Kind of Output: Overall Options. - -c -S -E -o FILE -combine -pipe -pass-exit-codes - -x LANGUAGE -v -### --help[=CLASS[,...]] --target-help - --version -wrapper@FILE - -_C Language Options_ - *Note Options Controlling C Dialect: C Dialect Options. - -ansi -std=STANDARD -fgnu89-inline - -aux-info FILENAME - -fno-asm -fno-builtin -fno-builtin-FUNCTION - -fhosted -ffreestanding -fopenmp -fms-extensions - -trigraphs -no-integrated-cpp -traditional -traditional-cpp - -fallow-single-precision -fcond-mismatch -flax-vector-conversions - -fsigned-bitfields -fsigned-char - -funsigned-bitfields -funsigned-char - -_C++ Language Options_ - *Note Options Controlling C++ Dialect: C++ Dialect Options. - -fabi-version=N -fno-access-control -fcheck-new - -fconserve-space -ffriend-injection - -fno-elide-constructors - -fno-enforce-eh-specs - -ffor-scope -fno-for-scope -fno-gnu-keywords - -fno-implicit-templates - -fno-implicit-inline-templates - -fno-implement-inlines -fms-extensions - -fno-nonansi-builtins -fno-operator-names - -fno-optional-diags -fpermissive - -frepo -fno-rtti -fstats -ftemplate-depth-N - -fno-threadsafe-statics -fuse-cxa-atexit -fno-weak -nostdinc++ - -fno-default-inline -fvisibility-inlines-hidden - -fvisibility-ms-compat - -Wabi -Wctor-dtor-privacy - -Wnon-virtual-dtor -Wreorder - -Weffc++ -Wstrict-null-sentinel - -Wno-non-template-friend -Wold-style-cast - -Woverloaded-virtual -Wno-pmf-conversions - -Wsign-promo - -_Objective-C and Objective-C++ Language Options_ - *Note Options Controlling Objective-C and Objective-C++ Dialects: - Objective-C and Objective-C++ Dialect Options. - -fconstant-string-class=CLASS-NAME - -fgnu-runtime -fnext-runtime - -fno-nil-receivers - -fobjc-call-cxx-cdtors - -fobjc-direct-dispatch - -fobjc-exceptions - -fobjc-gc - -freplace-objc-classes - -fzero-link - -gen-decls - -Wassign-intercept - -Wno-protocol -Wselector - -Wstrict-selector-match - -Wundeclared-selector - -_Language Independent Options_ - *Note Options to Control Diagnostic Messages Formatting: Language - Independent Options. - -fmessage-length=N - -fdiagnostics-show-location=[once|every-line] - -fdiagnostics-show-option - -_Warning Options_ - *Note Options to Request or Suppress Warnings: Warning Options. - -fsyntax-only -pedantic -pedantic-errors - -w -Wextra -Wall -Waddress -Waggregate-return -Warray-bounds - -Wno-attributes -Wno-builtin-macro-redefined - -Wc++-compat -Wc++0x-compat -Wcast-align -Wcast-qual - -Wchar-subscripts -Wclobbered -Wcomment - -Wconversion -Wcoverage-mismatch -Wno-deprecated - -Wno-deprecated-declarations -Wdisabled-optimization - -Wno-div-by-zero -Wempty-body -Wenum-compare -Wno-endif-labels - -Werror -Werror=* - -Wfatal-errors -Wfloat-equal -Wformat -Wformat=2 - -Wno-format-contains-nul -Wno-format-extra-args -Wformat-nonliteral - -Wformat-security -Wformat-y2k - -Wframe-larger-than=LEN -Wignored-qualifiers - -Wimplicit -Wimplicit-function-declaration -Wimplicit-int - -Winit-self -Winline - -Wno-int-to-pointer-cast -Wno-invalid-offsetof - -Winvalid-pch -Wlarger-than=LEN -Wunsafe-loop-optimizations - -Wlogical-op -Wlong-long - -Wmain -Wmissing-braces -Wmissing-field-initializers - -Wmissing-format-attribute -Wmissing-include-dirs - -Wmissing-noreturn -Wno-mudflap - -Wno-multichar -Wnonnull -Wno-overflow - -Woverlength-strings -Wpacked -Wpacked-bitfield-compat -Wpadded - -Wparentheses -Wpedantic-ms-format -Wno-pedantic-ms-format - -Wpointer-arith -Wno-pointer-to-int-cast - -Wredundant-decls - -Wreturn-type -Wsequence-point -Wshadow - -Wsign-compare -Wsign-conversion -Wstack-protector - -Wstrict-aliasing -Wstrict-aliasing=n - -Wstrict-overflow -Wstrict-overflow=N - -Wswitch -Wswitch-default -Wswitch-enum -Wsync-nand - -Wsystem-headers -Wtrigraphs -Wtype-limits -Wundef -Wuninitialized - -Wunknown-pragmas -Wno-pragmas -Wunreachable-code - -Wunused -Wunused-function -Wunused-label -Wunused-parameter - -Wunused-value -Wunused-variable - -Wvariadic-macros -Wvla - -Wvolatile-register-var -Wwrite-strings - -_C and Objective-C-only Warning Options_ - -Wbad-function-cast -Wmissing-declarations - -Wmissing-parameter-type -Wmissing-prototypes -Wnested-externs - -Wold-style-declaration -Wold-style-definition - -Wstrict-prototypes -Wtraditional -Wtraditional-conversion - -Wdeclaration-after-statement -Wpointer-sign - -_Debugging Options_ - *Note Options for Debugging Your Program or GCC: Debugging Options. - -dLETTERS -dumpspecs -dumpmachine -dumpversion - -fdbg-cnt-list -fdbg-cnt=COUNTER-VALUE-LIST - -fdump-noaddr -fdump-unnumbered - -fdump-translation-unit[-N] - -fdump-class-hierarchy[-N] - -fdump-ipa-all -fdump-ipa-cgraph -fdump-ipa-inline - -fdump-statistics - -fdump-tree-all - -fdump-tree-original[-N] - -fdump-tree-optimized[-N] - -fdump-tree-cfg -fdump-tree-vcg -fdump-tree-alias - -fdump-tree-ch - -fdump-tree-ssa[-N] -fdump-tree-pre[-N] - -fdump-tree-ccp[-N] -fdump-tree-dce[-N] - -fdump-tree-gimple[-raw] -fdump-tree-mudflap[-N] - -fdump-tree-dom[-N] - -fdump-tree-dse[-N] - -fdump-tree-phiopt[-N] - -fdump-tree-forwprop[-N] - -fdump-tree-copyrename[-N] - -fdump-tree-nrv -fdump-tree-vect - -fdump-tree-sink - -fdump-tree-sra[-N] - -fdump-tree-fre[-N] - -fdump-tree-vrp[-N] - -ftree-vectorizer-verbose=N - -fdump-tree-storeccp[-N] - -feliminate-dwarf2-dups -feliminate-unused-debug-types - -feliminate-unused-debug-symbols -femit-class-debug-always - -fmem-report -fpre-ipa-mem-report -fpost-ipa-mem-report -fprofile-arcs - -frandom-seed=STRING -fsched-verbose=N - -fsel-sched-verbose -fsel-sched-dump-cfg -fsel-sched-pipelining-verbose - -ftest-coverage -ftime-report -fvar-tracking - -g -gLEVEL -gcoff -gdwarf-2 - -ggdb -gstabs -gstabs+ -gvms -gxcoff -gxcoff+ - -fno-merge-debug-strings -fno-dwarf2-cfi-asm - -fdebug-prefix-map=OLD=NEW - -femit-struct-debug-baseonly -femit-struct-debug-reduced - -femit-struct-debug-detailed[=SPEC-LIST] - -p -pg -print-file-name=LIBRARY -print-libgcc-file-name - -print-multi-directory -print-multi-lib - -print-prog-name=PROGRAM -print-search-dirs -Q - -print-sysroot -print-sysroot-headers-suffix - -save-temps -time - -_Optimization Options_ - *Note Options that Control Optimization: Optimize Options. - -falign-functions[=N] -falign-jumps[=N] - -falign-labels[=N] -falign-loops[=N] -fassociative-math - -fauto-inc-dec -fbranch-probabilities -fbranch-target-load-optimize - -fbranch-target-load-optimize2 -fbtr-bb-exclusive -fcaller-saves - -fcheck-data-deps -fconserve-stack -fcprop-registers -fcrossjumping - -fcse-follow-jumps -fcse-skip-blocks -fcx-fortran-rules -fcx-limited-range - -fdata-sections -fdce -fdce - -fdelayed-branch -fdelete-null-pointer-checks -fdse -fdse - -fearly-inlining -fexpensive-optimizations -ffast-math - -ffinite-math-only -ffloat-store -fforward-propagate - -ffunction-sections -fgcse -fgcse-after-reload -fgcse-las -fgcse-lm - -fgcse-sm -fif-conversion -fif-conversion2 -findirect-inlining - -finline-functions -finline-functions-called-once -finline-limit=N - -finline-small-functions -fipa-cp -fipa-cp-clone -fipa-matrix-reorg -fipa-pta - -fipa-pure-const -fipa-reference -fipa-struct-reorg - -fipa-type-escape -fira-algorithm=ALGORITHM - -fira-region=REGION -fira-coalesce -fno-ira-share-save-slots - -fno-ira-share-spill-slots -fira-verbose=N - -fivopts -fkeep-inline-functions -fkeep-static-consts - -floop-block -floop-interchange -floop-strip-mine - -fmerge-all-constants -fmerge-constants -fmodulo-sched - -fmodulo-sched-allow-regmoves -fmove-loop-invariants -fmudflap - -fmudflapir -fmudflapth -fno-branch-count-reg -fno-default-inline - -fno-defer-pop -fno-function-cse -fno-guess-branch-probability - -fno-inline -fno-math-errno -fno-peephole -fno-peephole2 - -fno-sched-interblock -fno-sched-spec -fno-signed-zeros - -fno-toplevel-reorder -fno-trapping-math -fno-zero-initialized-in-bss - -fomit-frame-pointer -foptimize-register-move -foptimize-sibling-calls - -fpeel-loops -fpredictive-commoning -fprefetch-loop-arrays - -fprofile-correction -fprofile-dir=PATH -fprofile-generate - -fprofile-generate=PATH - -fprofile-use -fprofile-use=PATH -fprofile-values - -freciprocal-math -fregmove -frename-registers -freorder-blocks - -freorder-blocks-and-partition -freorder-functions - -frerun-cse-after-loop -freschedule-modulo-scheduled-loops - -frounding-math -frtl-abstract-sequences -fsched2-use-superblocks - -fsched2-use-traces -fsched-spec-load -fsched-spec-load-dangerous - -fsched-stalled-insns-dep[=N] -fsched-stalled-insns[=N] - -fschedule-insns -fschedule-insns2 -fsection-anchors -fsee - -fselective-scheduling -fselective-scheduling2 - -fsel-sched-pipelining -fsel-sched-pipelining-outer-loops - -fsignaling-nans -fsingle-precision-constant -fsplit-ivs-in-unroller - -fsplit-wide-types -fstack-protector -fstack-protector-all - -fstrict-aliasing -fstrict-overflow -fthread-jumps -ftracer - -ftree-builtin-call-dce -ftree-ccp -ftree-ch -ftree-copy-prop - -ftree-copyrename -ftree-dce - -ftree-dominator-opts -ftree-dse -ftree-fre -ftree-loop-im - -ftree-loop-distribution - -ftree-loop-ivcanon -ftree-loop-linear -ftree-loop-optimize - -ftree-parallelize-loops=N -ftree-pre -ftree-reassoc - -ftree-sink -ftree-sra -ftree-switch-conversion - -ftree-ter -ftree-vect-loop-version -ftree-vectorize -ftree-vrp - -funit-at-a-time -funroll-all-loops -funroll-loops - -funsafe-loop-optimizations -funsafe-math-optimizations -funswitch-loops - -fvariable-expansion-in-unroller -fvect-cost-model -fvpt -fweb - -fwhole-program - --param NAME=VALUE - -O -O0 -O1 -O2 -O3 -Os - -_Preprocessor Options_ - *Note Options Controlling the Preprocessor: Preprocessor Options. - -AQUESTION=ANSWER - -A-QUESTION[=ANSWER] - -C -dD -dI -dM -dN - -DMACRO[=DEFN] -E -H - -idirafter DIR - -include FILE -imacros FILE - -iprefix FILE -iwithprefix DIR - -iwithprefixbefore DIR -isystem DIR - -imultilib DIR -isysroot DIR - -M -MM -MF -MG -MP -MQ -MT -nostdinc - -P -fworking-directory -remap - -trigraphs -undef -UMACRO -Wp,OPTION - -Xpreprocessor OPTION - -_Assembler Option_ - *Note Passing Options to the Assembler: Assembler Options. - -Wa,OPTION -Xassembler OPTION - -_Linker Options_ - *Note Options for Linking: Link Options. - OBJECT-FILE-NAME -lLIBRARY - -nostartfiles -nodefaultlibs -nostdlib -pie -rdynamic - -s -static -static-libgcc -shared -shared-libgcc -symbolic - -T SCRIPT -Wl,OPTION -Xlinker OPTION - -u SYMBOL - -_Directory Options_ - *Note Options for Directory Search: Directory Options. - -BPREFIX -IDIR -iquoteDIR -LDIR - -specs=FILE -I- --sysroot=DIR - -_Target Options_ - *Note Target Options::. - -V VERSION -b MACHINE - -_Machine Dependent Options_ - *Note Hardware Models and Configurations: Submodel Options. - - _ARC Options_ - -EB -EL - -mmangle-cpu -mcpu=CPU -mtext=TEXT-SECTION - -mdata=DATA-SECTION -mrodata=READONLY-DATA-SECTION - - _ARM Options_ - -mapcs-frame -mno-apcs-frame - -mabi=NAME - -mapcs-stack-check -mno-apcs-stack-check - -mapcs-float -mno-apcs-float - -mapcs-reentrant -mno-apcs-reentrant - -msched-prolog -mno-sched-prolog - -mlittle-endian -mbig-endian -mwords-little-endian - -mfloat-abi=NAME -msoft-float -mhard-float -mfpe - -mthumb-interwork -mno-thumb-interwork - -mcpu=NAME -march=NAME -mfpu=NAME - -mstructure-size-boundary=N - -mabort-on-noreturn - -mlong-calls -mno-long-calls - -msingle-pic-base -mno-single-pic-base - -mpic-register=REG - -mnop-fun-dllimport - -mcirrus-fix-invalid-insns -mno-cirrus-fix-invalid-insns - -mpoke-function-name - -mthumb -marm - -mtpcs-frame -mtpcs-leaf-frame - -mcaller-super-interworking -mcallee-super-interworking - -mtp=NAME - -mword-relocations - -mfix-cortex-m3-ldrd - - _AVR Options_ - -mmcu=MCU -msize -mno-interrupts - -mcall-prologues -mno-tablejump -mtiny-stack -mint8 - - _Blackfin Options_ - -mcpu=CPU[-SIREVISION] - -msim -momit-leaf-frame-pointer -mno-omit-leaf-frame-pointer - -mspecld-anomaly -mno-specld-anomaly -mcsync-anomaly -mno-csync-anomaly - -mlow-64k -mno-low64k -mstack-check-l1 -mid-shared-library - -mno-id-shared-library -mshared-library-id=N - -mleaf-id-shared-library -mno-leaf-id-shared-library - -msep-data -mno-sep-data -mlong-calls -mno-long-calls - -mfast-fp -minline-plt -mmulticore -mcorea -mcoreb -msdram - -micplb - - _CRIS Options_ - -mcpu=CPU -march=CPU -mtune=CPU - -mmax-stack-frame=N -melinux-stacksize=N - -metrax4 -metrax100 -mpdebug -mcc-init -mno-side-effects - -mstack-align -mdata-align -mconst-align - -m32-bit -m16-bit -m8-bit -mno-prologue-epilogue -mno-gotplt - -melf -maout -melinux -mlinux -sim -sim2 - -mmul-bug-workaround -mno-mul-bug-workaround - - _CRX Options_ - -mmac -mpush-args - - _Darwin Options_ - -all_load -allowable_client -arch -arch_errors_fatal - -arch_only -bind_at_load -bundle -bundle_loader - -client_name -compatibility_version -current_version - -dead_strip - -dependency-file -dylib_file -dylinker_install_name - -dynamic -dynamiclib -exported_symbols_list - -filelist -flat_namespace -force_cpusubtype_ALL - -force_flat_namespace -headerpad_max_install_names - -iframework - -image_base -init -install_name -keep_private_externs - -multi_module -multiply_defined -multiply_defined_unused - -noall_load -no_dead_strip_inits_and_terms - -nofixprebinding -nomultidefs -noprebind -noseglinkedit - -pagezero_size -prebind -prebind_all_twolevel_modules - -private_bundle -read_only_relocs -sectalign - -sectobjectsymbols -whyload -seg1addr - -sectcreate -sectobjectsymbols -sectorder - -segaddr -segs_read_only_addr -segs_read_write_addr - -seg_addr_table -seg_addr_table_filename -seglinkedit - -segprot -segs_read_only_addr -segs_read_write_addr - -single_module -static -sub_library -sub_umbrella - -twolevel_namespace -umbrella -undefined - -unexported_symbols_list -weak_reference_mismatches - -whatsloaded -F -gused -gfull -mmacosx-version-min=VERSION - -mkernel -mone-byte-bool - - _DEC Alpha Options_ - -mno-fp-regs -msoft-float -malpha-as -mgas - -mieee -mieee-with-inexact -mieee-conformant - -mfp-trap-mode=MODE -mfp-rounding-mode=MODE - -mtrap-precision=MODE -mbuild-constants - -mcpu=CPU-TYPE -mtune=CPU-TYPE - -mbwx -mmax -mfix -mcix - -mfloat-vax -mfloat-ieee - -mexplicit-relocs -msmall-data -mlarge-data - -msmall-text -mlarge-text - -mmemory-latency=TIME - - _DEC Alpha/VMS Options_ - -mvms-return-codes - - _FR30 Options_ - -msmall-model -mno-lsim - - _FRV Options_ - -mgpr-32 -mgpr-64 -mfpr-32 -mfpr-64 - -mhard-float -msoft-float - -malloc-cc -mfixed-cc -mdword -mno-dword - -mdouble -mno-double - -mmedia -mno-media -mmuladd -mno-muladd - -mfdpic -minline-plt -mgprel-ro -multilib-library-pic - -mlinked-fp -mlong-calls -malign-labels - -mlibrary-pic -macc-4 -macc-8 - -mpack -mno-pack -mno-eflags -mcond-move -mno-cond-move - -moptimize-membar -mno-optimize-membar - -mscc -mno-scc -mcond-exec -mno-cond-exec - -mvliw-branch -mno-vliw-branch - -mmulti-cond-exec -mno-multi-cond-exec -mnested-cond-exec - -mno-nested-cond-exec -mtomcat-stats - -mTLS -mtls - -mcpu=CPU - - _GNU/Linux Options_ - -muclibc - - _H8/300 Options_ - -mrelax -mh -ms -mn -mint32 -malign-300 - - _HPPA Options_ - -march=ARCHITECTURE-TYPE - -mbig-switch -mdisable-fpregs -mdisable-indexing - -mfast-indirect-calls -mgas -mgnu-ld -mhp-ld - -mfixed-range=REGISTER-RANGE - -mjump-in-delay -mlinker-opt -mlong-calls - -mlong-load-store -mno-big-switch -mno-disable-fpregs - -mno-disable-indexing -mno-fast-indirect-calls -mno-gas - -mno-jump-in-delay -mno-long-load-store - -mno-portable-runtime -mno-soft-float - -mno-space-regs -msoft-float -mpa-risc-1-0 - -mpa-risc-1-1 -mpa-risc-2-0 -mportable-runtime - -mschedule=CPU-TYPE -mspace-regs -msio -mwsio - -munix=UNIX-STD -nolibdld -static -threads - - _i386 and x86-64 Options_ - -mtune=CPU-TYPE -march=CPU-TYPE - -mfpmath=UNIT - -masm=DIALECT -mno-fancy-math-387 - -mno-fp-ret-in-387 -msoft-float - -mno-wide-multiply -mrtd -malign-double - -mpreferred-stack-boundary=NUM - -mincoming-stack-boundary=NUM - -mcld -mcx16 -msahf -mrecip - -mmmx -msse -msse2 -msse3 -mssse3 -msse4.1 -msse4.2 -msse4 -mavx - -maes -mpclmul - -msse4a -m3dnow -mpopcnt -mabm -msse5 - -mthreads -mno-align-stringops -minline-all-stringops - -minline-stringops-dynamically -mstringop-strategy=ALG - -mpush-args -maccumulate-outgoing-args -m128bit-long-double - -m96bit-long-double -mregparm=NUM -msseregparm - -mveclibabi=TYPE -mpc32 -mpc64 -mpc80 -mstackrealign - -momit-leaf-frame-pointer -mno-red-zone -mno-tls-direct-seg-refs - -mcmodel=CODE-MODEL - -m32 -m64 -mlarge-data-threshold=NUM - -mfused-madd -mno-fused-madd -msse2avx - - _IA-64 Options_ - -mbig-endian -mlittle-endian -mgnu-as -mgnu-ld -mno-pic - -mvolatile-asm-stop -mregister-names -mno-sdata - -mconstant-gp -mauto-pic -minline-float-divide-min-latency - -minline-float-divide-max-throughput - -minline-int-divide-min-latency - -minline-int-divide-max-throughput - -minline-sqrt-min-latency -minline-sqrt-max-throughput - -mno-dwarf2-asm -mearly-stop-bits - -mfixed-range=REGISTER-RANGE -mtls-size=TLS-SIZE - -mtune=CPU-TYPE -mt -pthread -milp32 -mlp64 - -mno-sched-br-data-spec -msched-ar-data-spec -mno-sched-control-spec - -msched-br-in-data-spec -msched-ar-in-data-spec -msched-in-control-spec - -msched-ldc -mno-sched-control-ldc -mno-sched-spec-verbose - -mno-sched-prefer-non-data-spec-insns - -mno-sched-prefer-non-control-spec-insns - -mno-sched-count-spec-in-critical-path - - _M32R/D Options_ - -m32r2 -m32rx -m32r - -mdebug - -malign-loops -mno-align-loops - -missue-rate=NUMBER - -mbranch-cost=NUMBER - -mmodel=CODE-SIZE-MODEL-TYPE - -msdata=SDATA-TYPE - -mno-flush-func -mflush-func=NAME - -mno-flush-trap -mflush-trap=NUMBER - -G NUM - - _M32C Options_ - -mcpu=CPU -msim -memregs=NUMBER - - _M680x0 Options_ - -march=ARCH -mcpu=CPU -mtune=TUNE - -m68000 -m68020 -m68020-40 -m68020-60 -m68030 -m68040 - -m68060 -mcpu32 -m5200 -m5206e -m528x -m5307 -m5407 - -mcfv4e -mbitfield -mno-bitfield -mc68000 -mc68020 - -mnobitfield -mrtd -mno-rtd -mdiv -mno-div -mshort - -mno-short -mhard-float -m68881 -msoft-float -mpcrel - -malign-int -mstrict-align -msep-data -mno-sep-data - -mshared-library-id=n -mid-shared-library -mno-id-shared-library - -mxgot -mno-xgot - - _M68hc1x Options_ - -m6811 -m6812 -m68hc11 -m68hc12 -m68hcs12 - -mauto-incdec -minmax -mlong-calls -mshort - -msoft-reg-count=COUNT - - _MCore Options_ - -mhardlit -mno-hardlit -mdiv -mno-div -mrelax-immediates - -mno-relax-immediates -mwide-bitfields -mno-wide-bitfields - -m4byte-functions -mno-4byte-functions -mcallgraph-data - -mno-callgraph-data -mslow-bytes -mno-slow-bytes -mno-lsim - -mlittle-endian -mbig-endian -m210 -m340 -mstack-increment - - _MIPS Options_ - -EL -EB -march=ARCH -mtune=ARCH - -mips1 -mips2 -mips3 -mips4 -mips32 -mips32r2 - -mips64 -mips64r2 - -mips16 -mno-mips16 -mflip-mips16 - -minterlink-mips16 -mno-interlink-mips16 - -mabi=ABI -mabicalls -mno-abicalls - -mshared -mno-shared -mplt -mno-plt -mxgot -mno-xgot - -mgp32 -mgp64 -mfp32 -mfp64 -mhard-float -msoft-float - -msingle-float -mdouble-float -mdsp -mno-dsp -mdspr2 -mno-dspr2 - -mfpu=FPU-TYPE - -msmartmips -mno-smartmips - -mpaired-single -mno-paired-single -mdmx -mno-mdmx - -mips3d -mno-mips3d -mmt -mno-mt -mllsc -mno-llsc - -mlong64 -mlong32 -msym32 -mno-sym32 - -GNUM -mlocal-sdata -mno-local-sdata - -mextern-sdata -mno-extern-sdata -mgpopt -mno-gopt - -membedded-data -mno-embedded-data - -muninit-const-in-rodata -mno-uninit-const-in-rodata - -mcode-readable=SETTING - -msplit-addresses -mno-split-addresses - -mexplicit-relocs -mno-explicit-relocs - -mcheck-zero-division -mno-check-zero-division - -mdivide-traps -mdivide-breaks - -mmemcpy -mno-memcpy -mlong-calls -mno-long-calls - -mmad -mno-mad -mfused-madd -mno-fused-madd -nocpp - -mfix-r4000 -mno-fix-r4000 -mfix-r4400 -mno-fix-r4400 - -mfix-r10000 -mno-fix-r10000 -mfix-vr4120 -mno-fix-vr4120 - -mfix-vr4130 -mno-fix-vr4130 -mfix-sb1 -mno-fix-sb1 - -mflush-func=FUNC -mno-flush-func - -mbranch-cost=NUM -mbranch-likely -mno-branch-likely - -mfp-exceptions -mno-fp-exceptions - -mvr4130-align -mno-vr4130-align - - _MMIX Options_ - -mlibfuncs -mno-libfuncs -mepsilon -mno-epsilon -mabi=gnu - -mabi=mmixware -mzero-extend -mknuthdiv -mtoplevel-symbols - -melf -mbranch-predict -mno-branch-predict -mbase-addresses - -mno-base-addresses -msingle-exit -mno-single-exit - - _MN10300 Options_ - -mmult-bug -mno-mult-bug - -mam33 -mno-am33 - -mam33-2 -mno-am33-2 - -mreturn-pointer-on-d0 - -mno-crt0 -mrelax - - _PDP-11 Options_ - -mfpu -msoft-float -mac0 -mno-ac0 -m40 -m45 -m10 - -mbcopy -mbcopy-builtin -mint32 -mno-int16 - -mint16 -mno-int32 -mfloat32 -mno-float64 - -mfloat64 -mno-float32 -mabshi -mno-abshi - -mbranch-expensive -mbranch-cheap - -msplit -mno-split -munix-asm -mdec-asm - - _picoChip Options_ - -mae=AE_TYPE -mvliw-lookahead=N - -msymbol-as-address -mno-inefficient-warnings - - _PowerPC Options_ See RS/6000 and PowerPC Options. - - _RS/6000 and PowerPC Options_ - -mcpu=CPU-TYPE - -mtune=CPU-TYPE - -mpower -mno-power -mpower2 -mno-power2 - -mpowerpc -mpowerpc64 -mno-powerpc - -maltivec -mno-altivec - -mpowerpc-gpopt -mno-powerpc-gpopt - -mpowerpc-gfxopt -mno-powerpc-gfxopt - -mmfcrf -mno-mfcrf -mpopcntb -mno-popcntb -mfprnd -mno-fprnd - -mcmpb -mno-cmpb -mmfpgpr -mno-mfpgpr -mhard-dfp -mno-hard-dfp - -mnew-mnemonics -mold-mnemonics - -mfull-toc -mminimal-toc -mno-fp-in-toc -mno-sum-in-toc - -m64 -m32 -mxl-compat -mno-xl-compat -mpe - -malign-power -malign-natural - -msoft-float -mhard-float -mmultiple -mno-multiple - -msingle-float -mdouble-float -msimple-fpu - -mstring -mno-string -mupdate -mno-update - -mavoid-indexed-addresses -mno-avoid-indexed-addresses - -mfused-madd -mno-fused-madd -mbit-align -mno-bit-align - -mstrict-align -mno-strict-align -mrelocatable - -mno-relocatable -mrelocatable-lib -mno-relocatable-lib - -mtoc -mno-toc -mlittle -mlittle-endian -mbig -mbig-endian - -mdynamic-no-pic -maltivec -mswdiv - -mprioritize-restricted-insns=PRIORITY - -msched-costly-dep=DEPENDENCE_TYPE - -minsert-sched-nops=SCHEME - -mcall-sysv -mcall-netbsd - -maix-struct-return -msvr4-struct-return - -mabi=ABI-TYPE -msecure-plt -mbss-plt - -misel -mno-isel - -misel=yes -misel=no - -mspe -mno-spe - -mspe=yes -mspe=no - -mpaired - -mgen-cell-microcode -mwarn-cell-microcode - -mvrsave -mno-vrsave - -mmulhw -mno-mulhw - -mdlmzb -mno-dlmzb - -mfloat-gprs=yes -mfloat-gprs=no -mfloat-gprs=single -mfloat-gprs=double - -mprototype -mno-prototype - -msim -mmvme -mads -myellowknife -memb -msdata - -msdata=OPT -mvxworks -G NUM -pthread - - _S/390 and zSeries Options_ - -mtune=CPU-TYPE -march=CPU-TYPE - -mhard-float -msoft-float -mhard-dfp -mno-hard-dfp - -mlong-double-64 -mlong-double-128 - -mbackchain -mno-backchain -mpacked-stack -mno-packed-stack - -msmall-exec -mno-small-exec -mmvcle -mno-mvcle - -m64 -m31 -mdebug -mno-debug -mesa -mzarch - -mtpf-trace -mno-tpf-trace -mfused-madd -mno-fused-madd - -mwarn-framesize -mwarn-dynamicstack -mstack-size -mstack-guard - - _Score Options_ - -meb -mel - -mnhwloop - -muls - -mmac - -mscore5 -mscore5u -mscore7 -mscore7d - - _SH Options_ - -m1 -m2 -m2e -m3 -m3e - -m4-nofpu -m4-single-only -m4-single -m4 - -m4a-nofpu -m4a-single-only -m4a-single -m4a -m4al - -m5-64media -m5-64media-nofpu - -m5-32media -m5-32media-nofpu - -m5-compact -m5-compact-nofpu - -mb -ml -mdalign -mrelax - -mbigtable -mfmovd -mhitachi -mrenesas -mno-renesas -mnomacsave - -mieee -mbitops -misize -minline-ic_invalidate -mpadstruct -mspace - -mprefergot -musermode -multcost=NUMBER -mdiv=STRATEGY - -mdivsi3_libfunc=NAME -mfixed-range=REGISTER-RANGE - -madjust-unroll -mindexed-addressing -mgettrcost=NUMBER -mpt-fixed - -minvalid-symbols - - _SPARC Options_ - -mcpu=CPU-TYPE - -mtune=CPU-TYPE - -mcmodel=CODE-MODEL - -m32 -m64 -mapp-regs -mno-app-regs - -mfaster-structs -mno-faster-structs - -mfpu -mno-fpu -mhard-float -msoft-float - -mhard-quad-float -msoft-quad-float - -mimpure-text -mno-impure-text -mlittle-endian - -mstack-bias -mno-stack-bias - -munaligned-doubles -mno-unaligned-doubles - -mv8plus -mno-v8plus -mvis -mno-vis - -threads -pthreads -pthread - - _SPU Options_ - -mwarn-reloc -merror-reloc - -msafe-dma -munsafe-dma - -mbranch-hints - -msmall-mem -mlarge-mem -mstdmain - -mfixed-range=REGISTER-RANGE - - _System V Options_ - -Qy -Qn -YP,PATHS -Ym,DIR - - _V850 Options_ - -mlong-calls -mno-long-calls -mep -mno-ep - -mprolog-function -mno-prolog-function -mspace - -mtda=N -msda=N -mzda=N - -mapp-regs -mno-app-regs - -mdisable-callt -mno-disable-callt - -mv850e1 - -mv850e - -mv850 -mbig-switch - - _VAX Options_ - -mg -mgnu -munix - - _VxWorks Options_ - -mrtp -non-static -Bstatic -Bdynamic - -Xbind-lazy -Xbind-now - - _x86-64 Options_ See i386 and x86-64 Options. - - _i386 and x86-64 Windows Options_ - -mconsole -mcygwin -mno-cygwin -mdll - -mnop-fun-dllimport -mthread -mwin32 -mwindows - - _Xstormy16 Options_ - -msim - - _Xtensa Options_ - -mconst16 -mno-const16 - -mfused-madd -mno-fused-madd - -mserialize-volatile -mno-serialize-volatile - -mtext-section-literals -mno-text-section-literals - -mtarget-align -mno-target-align - -mlongcalls -mno-longcalls - - _zSeries Options_ See S/390 and zSeries Options. - -_Code Generation Options_ - *Note Options for Code Generation Conventions: Code Gen Options. - -fcall-saved-REG -fcall-used-REG - -ffixed-REG -fexceptions - -fnon-call-exceptions -funwind-tables - -fasynchronous-unwind-tables - -finhibit-size-directive -finstrument-functions - -finstrument-functions-exclude-function-list=SYM,SYM,... - -finstrument-functions-exclude-file-list=FILE,FILE,... - -fno-common -fno-ident - -fpcc-struct-return -fpic -fPIC -fpie -fPIE - -fno-jump-tables - -frecord-gcc-switches - -freg-struct-return -fshort-enums - -fshort-double -fshort-wchar - -fverbose-asm -fpack-struct[=N] -fstack-check - -fstack-limit-register=REG -fstack-limit-symbol=SYM - -fno-stack-limit -fargument-alias -fargument-noalias - -fargument-noalias-global -fargument-noalias-anything - -fleading-underscore -ftls-model=MODEL - -ftrapv -fwrapv -fbounds-check - -fvisibility - - -* Menu: - -* Overall Options:: Controlling the kind of output: - an executable, object files, assembler files, - or preprocessed source. -* C Dialect Options:: Controlling the variant of C language compiled. -* C++ Dialect Options:: Variations on C++. -* Objective-C and Objective-C++ Dialect Options:: Variations on Objective-C - and Objective-C++. -* Language Independent Options:: Controlling how diagnostics should be - formatted. -* Warning Options:: How picky should the compiler be? -* Debugging Options:: Symbol tables, measurements, and debugging dumps. -* Optimize Options:: How much optimization? -* Preprocessor Options:: Controlling header files and macro definitions. - Also, getting dependency information for Make. -* Assembler Options:: Passing options to the assembler. -* Link Options:: Specifying libraries and so on. -* Directory Options:: Where to find header files and libraries. - Where to find the compiler executable files. -* Spec Files:: How to pass switches to sub-processes. -* Target Options:: Running a cross-compiler, or an old version of GCC. - - -File: gcc.info, Node: Overall Options, Next: Invoking G++, Prev: Option Summary, Up: Invoking GCC - -3.2 Options Controlling the Kind of Output -========================================== - -Compilation can involve up to four stages: preprocessing, compilation -proper, assembly and linking, always in that order. GCC is capable of -preprocessing and compiling several files either into several assembler -input files, or into one assembler input file; then each assembler -input file produces an object file, and linking combines all the object -files (those newly compiled, and those specified as input) into an -executable file. - - For any given input file, the file name suffix determines what kind of -compilation is done: - -`FILE.c' - C source code which must be preprocessed. - -`FILE.i' - C source code which should not be preprocessed. - -`FILE.ii' - C++ source code which should not be preprocessed. - -`FILE.m' - Objective-C source code. Note that you must link with the - `libobjc' library to make an Objective-C program work. - -`FILE.mi' - Objective-C source code which should not be preprocessed. - -`FILE.mm' -`FILE.M' - Objective-C++ source code. Note that you must link with the - `libobjc' library to make an Objective-C++ program work. Note - that `.M' refers to a literal capital M. - -`FILE.mii' - Objective-C++ source code which should not be preprocessed. - -`FILE.h' - C, C++, Objective-C or Objective-C++ header file to be turned into - a precompiled header. - -`FILE.cc' -`FILE.cp' -`FILE.cxx' -`FILE.cpp' -`FILE.CPP' -`FILE.c++' -`FILE.C' - C++ source code which must be preprocessed. Note that in `.cxx', - the last two letters must both be literally `x'. Likewise, `.C' - refers to a literal capital C. - -`FILE.mm' -`FILE.M' - Objective-C++ source code which must be preprocessed. - -`FILE.mii' - Objective-C++ source code which should not be preprocessed. - -`FILE.hh' -`FILE.H' -`FILE.hp' -`FILE.hxx' -`FILE.hpp' -`FILE.HPP' -`FILE.h++' -`FILE.tcc' - C++ header file to be turned into a precompiled header. - -`FILE.f' -`FILE.for' -`FILE.ftn' - Fixed form Fortran source code which should not be preprocessed. - -`FILE.F' -`FILE.FOR' -`FILE.fpp' -`FILE.FPP' -`FILE.FTN' - Fixed form Fortran source code which must be preprocessed (with - the traditional preprocessor). - -`FILE.f90' -`FILE.f95' -`FILE.f03' -`FILE.f08' - Free form Fortran source code which should not be preprocessed. - -`FILE.F90' -`FILE.F95' -`FILE.F03' -`FILE.F08' - Free form Fortran source code which must be preprocessed (with the - traditional preprocessor). - -`FILE.ads' - Ada source code file which contains a library unit declaration (a - declaration of a package, subprogram, or generic, or a generic - instantiation), or a library unit renaming declaration (a package, - generic, or subprogram renaming declaration). Such files are also - called "specs". - -`FILE.adb' - Ada source code file containing a library unit body (a subprogram - or package body). Such files are also called "bodies". - -`FILE.s' - Assembler code. - -`FILE.S' -`FILE.sx' - Assembler code which must be preprocessed. - -`OTHER' - An object file to be fed straight into linking. Any file name - with no recognized suffix is treated this way. - - You can specify the input language explicitly with the `-x' option: - -`-x LANGUAGE' - Specify explicitly the LANGUAGE for the following input files - (rather than letting the compiler choose a default based on the - file name suffix). This option applies to all following input - files until the next `-x' option. Possible values for LANGUAGE - are: - c c-header c-cpp-output - c++ c++-header c++-cpp-output - objective-c objective-c-header objective-c-cpp-output - objective-c++ objective-c++-header objective-c++-cpp-output - assembler assembler-with-cpp - ada - f77 f77-cpp-input f95 f95-cpp-input - java - -`-x none' - Turn off any specification of a language, so that subsequent files - are handled according to their file name suffixes (as they are if - `-x' has not been used at all). - -`-pass-exit-codes' - Normally the `gcc' program will exit with the code of 1 if any - phase of the compiler returns a non-success return code. If you - specify `-pass-exit-codes', the `gcc' program will instead return - with numerically highest error produced by any phase that returned - an error indication. The C, C++, and Fortran frontends return 4, - if an internal compiler error is encountered. - - If you only want some of the stages of compilation, you can use `-x' -(or filename suffixes) to tell `gcc' where to start, and one of the -options `-c', `-S', or `-E' to say where `gcc' is to stop. Note that -some combinations (for example, `-x cpp-output -E') instruct `gcc' to -do nothing at all. - -`-c' - Compile or assemble the source files, but do not link. The linking - stage simply is not done. The ultimate output is in the form of an - object file for each source file. - - By default, the object file name for a source file is made by - replacing the suffix `.c', `.i', `.s', etc., with `.o'. - - Unrecognized input files, not requiring compilation or assembly, - are ignored. - -`-S' - Stop after the stage of compilation proper; do not assemble. The - output is in the form of an assembler code file for each - non-assembler input file specified. - - By default, the assembler file name for a source file is made by - replacing the suffix `.c', `.i', etc., with `.s'. - - Input files that don't require compilation are ignored. - -`-E' - Stop after the preprocessing stage; do not run the compiler - proper. The output is in the form of preprocessed source code, - which is sent to the standard output. - - Input files which don't require preprocessing are ignored. - -`-o FILE' - Place output in file FILE. This applies regardless to whatever - sort of output is being produced, whether it be an executable file, - an object file, an assembler file or preprocessed C code. - - If `-o' is not specified, the default is to put an executable file - in `a.out', the object file for `SOURCE.SUFFIX' in `SOURCE.o', its - assembler file in `SOURCE.s', a precompiled header file in - `SOURCE.SUFFIX.gch', and all preprocessed C source on standard - output. - -`-v' - Print (on standard error output) the commands executed to run the - stages of compilation. Also print the version number of the - compiler driver program and of the preprocessor and the compiler - proper. - -`-###' - Like `-v' except the commands are not executed and all command - arguments are quoted. This is useful for shell scripts to capture - the driver-generated command lines. - -`-pipe' - Use pipes rather than temporary files for communication between the - various stages of compilation. This fails to work on some systems - where the assembler is unable to read from a pipe; but the GNU - assembler has no trouble. - -`-combine' - If you are compiling multiple source files, this option tells the - driver to pass all the source files to the compiler at once (for - those languages for which the compiler can handle this). This - will allow intermodule analysis (IMA) to be performed by the - compiler. Currently the only language for which this is supported - is C. If you pass source files for multiple languages to the - driver, using this option, the driver will invoke the compiler(s) - that support IMA once each, passing each compiler all the source - files appropriate for it. For those languages that do not support - IMA this option will be ignored, and the compiler will be invoked - once for each source file in that language. If you use this - option in conjunction with `-save-temps', the compiler will - generate multiple pre-processed files (one for each source file), - but only one (combined) `.o' or `.s' file. - -`--help' - Print (on the standard output) a description of the command line - options understood by `gcc'. If the `-v' option is also specified - then `--help' will also be passed on to the various processes - invoked by `gcc', so that they can display the command line options - they accept. If the `-Wextra' option has also been specified - (prior to the `--help' option), then command line options which - have no documentation associated with them will also be displayed. - -`--target-help' - Print (on the standard output) a description of target-specific - command line options for each tool. For some targets extra - target-specific information may also be printed. - -`--help={CLASS|[^]QUALIFIER}[,...]' - Print (on the standard output) a description of the command line - options understood by the compiler that fit into all specified - classes and qualifiers. These are the supported classes: - - `optimizers' - This will display all of the optimization options supported - by the compiler. - - `warnings' - This will display all of the options controlling warning - messages produced by the compiler. - - `target' - This will display target-specific options. Unlike the - `--target-help' option however, target-specific options of the - linker and assembler will not be displayed. This is because - those tools do not currently support the extended `--help=' - syntax. - - `params' - This will display the values recognized by the `--param' - option. - - LANGUAGE - This will display the options supported for LANGUAGE, where - LANGUAGE is the name of one of the languages supported in this - version of GCC. - - `common' - This will display the options that are common to all - languages. - - These are the supported qualifiers: - - `undocumented' - Display only those options which are undocumented. - - `joined' - Display options which take an argument that appears after an - equal sign in the same continuous piece of text, such as: - `--help=target'. - - `separate' - Display options which take an argument that appears as a - separate word following the original option, such as: `-o - output-file'. - - Thus for example to display all the undocumented target-specific - switches supported by the compiler the following can be used: - - --help=target,undocumented - - The sense of a qualifier can be inverted by prefixing it with the - `^' character, so for example to display all binary warning - options (i.e., ones that are either on or off and that do not take - an argument), which have a description the following can be used: - - --help=warnings,^joined,^undocumented - - The argument to `--help=' should not consist solely of inverted - qualifiers. - - Combining several classes is possible, although this usually - restricts the output by so much that there is nothing to display. - One case where it does work however is when one of the classes is - TARGET. So for example to display all the target-specific - optimization options the following can be used: - - --help=target,optimizers - - The `--help=' option can be repeated on the command line. Each - successive use will display its requested class of options, - skipping those that have already been displayed. - - If the `-Q' option appears on the command line before the - `--help=' option, then the descriptive text displayed by `--help=' - is changed. Instead of describing the displayed options, an - indication is given as to whether the option is enabled, disabled - or set to a specific value (assuming that the compiler knows this - at the point where the `--help=' option is used). - - Here is a truncated example from the ARM port of `gcc': - - % gcc -Q -mabi=2 --help=target -c - The following options are target specific: - -mabi= 2 - -mabort-on-noreturn [disabled] - -mapcs [disabled] - - The output is sensitive to the effects of previous command line - options, so for example it is possible to find out which - optimizations are enabled at `-O2' by using: - - -Q -O2 --help=optimizers - - Alternatively you can discover which binary optimizations are - enabled by `-O3' by using: - - gcc -c -Q -O3 --help=optimizers > /tmp/O3-opts - gcc -c -Q -O2 --help=optimizers > /tmp/O2-opts - diff /tmp/O2-opts /tmp/O3-opts | grep enabled - -`--version' - Display the version number and copyrights of the invoked GCC. - -`-wrapper' - Invoke all subcommands under a wrapper program. It takes a single - comma separated list as an argument, which will be used to invoke - the wrapper: - - gcc -c t.c -wrapper gdb,--args - - This will invoke all subprograms of gcc under "gdb -args", thus - cc1 invocation will be "gdb -args cc1 ...". - -`@FILE' - Read command-line options from FILE. The options read are - inserted in place of the original @FILE option. If FILE does not - exist, or cannot be read, then the option will be treated - literally, and not removed. - - Options in FILE are separated by whitespace. A whitespace - character may be included in an option by surrounding the entire - option in either single or double quotes. Any character - (including a backslash) may be included by prefixing the character - to be included with a backslash. The FILE may itself contain - additional @FILE options; any such options will be processed - recursively. - - -File: gcc.info, Node: Invoking G++, Next: C Dialect Options, Prev: Overall Options, Up: Invoking GCC - -3.3 Compiling C++ Programs -========================== - -C++ source files conventionally use one of the suffixes `.C', `.cc', -`.cpp', `.CPP', `.c++', `.cp', or `.cxx'; C++ header files often use -`.hh', `.hpp', `.H', or (for shared template code) `.tcc'; and -preprocessed C++ files use the suffix `.ii'. GCC recognizes files with -these names and compiles them as C++ programs even if you call the -compiler the same way as for compiling C programs (usually with the -name `gcc'). - - However, the use of `gcc' does not add the C++ library. `g++' is a -program that calls GCC and treats `.c', `.h' and `.i' files as C++ -source files instead of C source files unless `-x' is used, and -automatically specifies linking against the C++ library. This program -is also useful when precompiling a C header file with a `.h' extension -for use in C++ compilations. On many systems, `g++' is also installed -with the name `c++'. - - When you compile C++ programs, you may specify many of the same -command-line options that you use for compiling programs in any -language; or command-line options meaningful for C and related -languages; or options that are meaningful only for C++ programs. *Note -Options Controlling C Dialect: C Dialect Options, for explanations of -options for languages related to C. *Note Options Controlling C++ -Dialect: C++ Dialect Options, for explanations of options that are -meaningful only for C++ programs. - - -File: gcc.info, Node: C Dialect Options, Next: C++ Dialect Options, Prev: Invoking G++, Up: Invoking GCC - -3.4 Options Controlling C Dialect -================================= - -The following options control the dialect of C (or languages derived -from C, such as C++, Objective-C and Objective-C++) that the compiler -accepts: - -`-ansi' - In C mode, this is equivalent to `-std=c89'. In C++ mode, it is - equivalent to `-std=c++98'. - - This turns off certain features of GCC that are incompatible with - ISO C90 (when compiling C code), or of standard C++ (when - compiling C++ code), such as the `asm' and `typeof' keywords, and - predefined macros such as `unix' and `vax' that identify the type - of system you are using. It also enables the undesirable and - rarely used ISO trigraph feature. For the C compiler, it disables - recognition of C++ style `//' comments as well as the `inline' - keyword. - - The alternate keywords `__asm__', `__extension__', `__inline__' - and `__typeof__' continue to work despite `-ansi'. You would not - want to use them in an ISO C program, of course, but it is useful - to put them in header files that might be included in compilations - done with `-ansi'. Alternate predefined macros such as `__unix__' - and `__vax__' are also available, with or without `-ansi'. - - The `-ansi' option does not cause non-ISO programs to be rejected - gratuitously. For that, `-pedantic' is required in addition to - `-ansi'. *Note Warning Options::. - - The macro `__STRICT_ANSI__' is predefined when the `-ansi' option - is used. Some header files may notice this macro and refrain from - declaring certain functions or defining certain macros that the - ISO standard doesn't call for; this is to avoid interfering with - any programs that might use these names for other things. - - Functions that would normally be built in but do not have semantics - defined by ISO C (such as `alloca' and `ffs') are not built-in - functions when `-ansi' is used. *Note Other built-in functions - provided by GCC: Other Builtins, for details of the functions - affected. - -`-std=' - Determine the language standard. *Note Language Standards - Supported by GCC: Standards, for details of these standard - versions. This option is currently only supported when compiling - C or C++. - - The compiler can accept several base standards, such as `c89' or - `c++98', and GNU dialects of those standards, such as `gnu89' or - `gnu++98'. By specifying a base standard, the compiler will - accept all programs following that standard and those using GNU - extensions that do not contradict it. For example, `-std=c89' - turns off certain features of GCC that are incompatible with ISO - C90, such as the `asm' and `typeof' keywords, but not other GNU - extensions that do not have a meaning in ISO C90, such as omitting - the middle term of a `?:' expression. On the other hand, by - specifying a GNU dialect of a standard, all features the compiler - support are enabled, even when those features change the meaning - of the base standard and some strict-conforming programs may be - rejected. The particular standard is used by `-pedantic' to - identify which features are GNU extensions given that version of - the standard. For example `-std=gnu89 -pedantic' would warn about - C++ style `//' comments, while `-std=gnu99 -pedantic' would not. - - A value for this option must be provided; possible values are - - `c89' - `iso9899:1990' - Support all ISO C90 programs (certain GNU extensions that - conflict with ISO C90 are disabled). Same as `-ansi' for C - code. - - `iso9899:199409' - ISO C90 as modified in amendment 1. - - `c99' - `c9x' - `iso9899:1999' - `iso9899:199x' - ISO C99. Note that this standard is not yet fully supported; - see `http://gcc.gnu.org/gcc-4.4/c99status.html' for more - information. The names `c9x' and `iso9899:199x' are - deprecated. - - `gnu89' - GNU dialect of ISO C90 (including some C99 features). This is - the default for C code. - - `gnu99' - `gnu9x' - GNU dialect of ISO C99. When ISO C99 is fully implemented in - GCC, this will become the default. The name `gnu9x' is - deprecated. - - `c++98' - The 1998 ISO C++ standard plus amendments. Same as `-ansi' for - C++ code. - - `gnu++98' - GNU dialect of `-std=c++98'. This is the default for C++ - code. - - `c++0x' - The working draft of the upcoming ISO C++0x standard. This - option enables experimental features that are likely to be - included in C++0x. The working draft is constantly changing, - and any feature that is enabled by this flag may be removed - from future versions of GCC if it is not part of the C++0x - standard. - - `gnu++0x' - GNU dialect of `-std=c++0x'. This option enables experimental - features that may be removed in future versions of GCC. - -`-fgnu89-inline' - The option `-fgnu89-inline' tells GCC to use the traditional GNU - semantics for `inline' functions when in C99 mode. *Note An - Inline Function is As Fast As a Macro: Inline. This option is - accepted and ignored by GCC versions 4.1.3 up to but not including - 4.3. In GCC versions 4.3 and later it changes the behavior of GCC - in C99 mode. Using this option is roughly equivalent to adding the - `gnu_inline' function attribute to all inline functions (*note - Function Attributes::). - - The option `-fno-gnu89-inline' explicitly tells GCC to use the C99 - semantics for `inline' when in C99 or gnu99 mode (i.e., it - specifies the default behavior). This option was first supported - in GCC 4.3. This option is not supported in C89 or gnu89 mode. - - The preprocessor macros `__GNUC_GNU_INLINE__' and - `__GNUC_STDC_INLINE__' may be used to check which semantics are in - effect for `inline' functions. *Note Common Predefined Macros: - (cpp)Common Predefined Macros. - -`-aux-info FILENAME' - Output to the given filename prototyped declarations for all - functions declared and/or defined in a translation unit, including - those in header files. This option is silently ignored in any - language other than C. - - Besides declarations, the file indicates, in comments, the origin - of each declaration (source file and line), whether the - declaration was implicit, prototyped or unprototyped (`I', `N' for - new or `O' for old, respectively, in the first character after the - line number and the colon), and whether it came from a declaration - or a definition (`C' or `F', respectively, in the following - character). In the case of function definitions, a K&R-style list - of arguments followed by their declarations is also provided, - inside comments, after the declaration. - -`-fno-asm' - Do not recognize `asm', `inline' or `typeof' as a keyword, so that - code can use these words as identifiers. You can use the keywords - `__asm__', `__inline__' and `__typeof__' instead. `-ansi' implies - `-fno-asm'. - - In C++, this switch only affects the `typeof' keyword, since `asm' - and `inline' are standard keywords. You may want to use the - `-fno-gnu-keywords' flag instead, which has the same effect. In - C99 mode (`-std=c99' or `-std=gnu99'), this switch only affects - the `asm' and `typeof' keywords, since `inline' is a standard - keyword in ISO C99. - -`-fno-builtin' -`-fno-builtin-FUNCTION' - Don't recognize built-in functions that do not begin with - `__builtin_' as prefix. *Note Other built-in functions provided - by GCC: Other Builtins, for details of the functions affected, - including those which are not built-in functions when `-ansi' or - `-std' options for strict ISO C conformance are used because they - do not have an ISO standard meaning. - - GCC normally generates special code to handle certain built-in - functions more efficiently; for instance, calls to `alloca' may - become single instructions that adjust the stack directly, and - calls to `memcpy' may become inline copy loops. The resulting - code is often both smaller and faster, but since the function - calls no longer appear as such, you cannot set a breakpoint on - those calls, nor can you change the behavior of the functions by - linking with a different library. In addition, when a function is - recognized as a built-in function, GCC may use information about - that function to warn about problems with calls to that function, - or to generate more efficient code, even if the resulting code - still contains calls to that function. For example, warnings are - given with `-Wformat' for bad calls to `printf', when `printf' is - built in, and `strlen' is known not to modify global memory. - - With the `-fno-builtin-FUNCTION' option only the built-in function - FUNCTION is disabled. FUNCTION must not begin with `__builtin_'. - If a function is named that is not built-in in this version of - GCC, this option is ignored. There is no corresponding - `-fbuiltin-FUNCTION' option; if you wish to enable built-in - functions selectively when using `-fno-builtin' or - `-ffreestanding', you may define macros such as: - - #define abs(n) __builtin_abs ((n)) - #define strcpy(d, s) __builtin_strcpy ((d), (s)) - -`-fhosted' - Assert that compilation takes place in a hosted environment. This - implies `-fbuiltin'. A hosted environment is one in which the - entire standard library is available, and in which `main' has a - return type of `int'. Examples are nearly everything except a - kernel. This is equivalent to `-fno-freestanding'. - -`-ffreestanding' - Assert that compilation takes place in a freestanding environment. - This implies `-fno-builtin'. A freestanding environment is one in - which the standard library may not exist, and program startup may - not necessarily be at `main'. The most obvious example is an OS - kernel. This is equivalent to `-fno-hosted'. - - *Note Language Standards Supported by GCC: Standards, for details - of freestanding and hosted environments. - -`-fopenmp' - Enable handling of OpenMP directives `#pragma omp' in C/C++ and - `!$omp' in Fortran. When `-fopenmp' is specified, the compiler - generates parallel code according to the OpenMP Application - Program Interface v2.5 `http://www.openmp.org/'. This option - implies `-pthread', and thus is only supported on targets that - have support for `-pthread'. - -`-fms-extensions' - Accept some non-standard constructs used in Microsoft header files. - - Some cases of unnamed fields in structures and unions are only - accepted with this option. *Note Unnamed struct/union fields - within structs/unions: Unnamed Fields, for details. - -`-trigraphs' - Support ISO C trigraphs. The `-ansi' option (and `-std' options - for strict ISO C conformance) implies `-trigraphs'. - -`-no-integrated-cpp' - Performs a compilation in two passes: preprocessing and compiling. - This option allows a user supplied "cc1", "cc1plus", or "cc1obj" - via the `-B' option. The user supplied compilation step can then - add in an additional preprocessing step after normal preprocessing - but before compiling. The default is to use the integrated cpp - (internal cpp) - - The semantics of this option will change if "cc1", "cc1plus", and - "cc1obj" are merged. - -`-traditional' -`-traditional-cpp' - Formerly, these options caused GCC to attempt to emulate a - pre-standard C compiler. They are now only supported with the - `-E' switch. The preprocessor continues to support a pre-standard - mode. See the GNU CPP manual for details. - -`-fcond-mismatch' - Allow conditional expressions with mismatched types in the second - and third arguments. The value of such an expression is void. - This option is not supported for C++. - -`-flax-vector-conversions' - Allow implicit conversions between vectors with differing numbers - of elements and/or incompatible element types. This option should - not be used for new code. - -`-funsigned-char' - Let the type `char' be unsigned, like `unsigned char'. - - Each kind of machine has a default for what `char' should be. It - is either like `unsigned char' by default or like `signed char' by - default. - - Ideally, a portable program should always use `signed char' or - `unsigned char' when it depends on the signedness of an object. - But many programs have been written to use plain `char' and expect - it to be signed, or expect it to be unsigned, depending on the - machines they were written for. This option, and its inverse, let - you make such a program work with the opposite default. - - The type `char' is always a distinct type from each of `signed - char' or `unsigned char', even though its behavior is always just - like one of those two. - -`-fsigned-char' - Let the type `char' be signed, like `signed char'. - - Note that this is equivalent to `-fno-unsigned-char', which is the - negative form of `-funsigned-char'. Likewise, the option - `-fno-signed-char' is equivalent to `-funsigned-char'. - -`-fsigned-bitfields' -`-funsigned-bitfields' -`-fno-signed-bitfields' -`-fno-unsigned-bitfields' - These options control whether a bit-field is signed or unsigned, - when the declaration does not use either `signed' or `unsigned'. - By default, such a bit-field is signed, because this is - consistent: the basic integer types such as `int' are signed types. - - -File: gcc.info, Node: C++ Dialect Options, Next: Objective-C and Objective-C++ Dialect Options, Prev: C Dialect Options, Up: Invoking GCC - -3.5 Options Controlling C++ Dialect -=================================== - -This section describes the command-line options that are only meaningful -for C++ programs; but you can also use most of the GNU compiler options -regardless of what language your program is in. For example, you might -compile a file `firstClass.C' like this: - - g++ -g -frepo -O -c firstClass.C - -In this example, only `-frepo' is an option meant only for C++ -programs; you can use the other options with any language supported by -GCC. - - Here is a list of options that are _only_ for compiling C++ programs: - -`-fabi-version=N' - Use version N of the C++ ABI. Version 2 is the version of the C++ - ABI that first appeared in G++ 3.4. Version 1 is the version of - the C++ ABI that first appeared in G++ 3.2. Version 0 will always - be the version that conforms most closely to the C++ ABI - specification. Therefore, the ABI obtained using version 0 will - change as ABI bugs are fixed. - - The default is version 2. - -`-fno-access-control' - Turn off all access checking. This switch is mainly useful for - working around bugs in the access control code. - -`-fcheck-new' - Check that the pointer returned by `operator new' is non-null - before attempting to modify the storage allocated. This check is - normally unnecessary because the C++ standard specifies that - `operator new' will only return `0' if it is declared `throw()', - in which case the compiler will always check the return value even - without this option. In all other cases, when `operator new' has - a non-empty exception specification, memory exhaustion is - signalled by throwing `std::bad_alloc'. See also `new (nothrow)'. - -`-fconserve-space' - Put uninitialized or runtime-initialized global variables into the - common segment, as C does. This saves space in the executable at - the cost of not diagnosing duplicate definitions. If you compile - with this flag and your program mysteriously crashes after - `main()' has completed, you may have an object that is being - destroyed twice because two definitions were merged. - - This option is no longer useful on most targets, now that support - has been added for putting variables into BSS without making them - common. - -`-fno-deduce-init-list' - Disable deduction of a template type parameter as - std::initializer_list from a brace-enclosed initializer list, i.e. - - template auto forward(T t) -> decltype (realfn (t)) - { - return realfn (t); - } - - void f() - { - forward({1,2}); // call forward> - } - - This option is present because this deduction is an extension to - the current specification in the C++0x working draft, and there was - some concern about potential overload resolution problems. - -`-ffriend-injection' - Inject friend functions into the enclosing namespace, so that they - are visible outside the scope of the class in which they are - declared. Friend functions were documented to work this way in - the old Annotated C++ Reference Manual, and versions of G++ before - 4.1 always worked that way. However, in ISO C++ a friend function - which is not declared in an enclosing scope can only be found - using argument dependent lookup. This option causes friends to be - injected as they were in earlier releases. - - This option is for compatibility, and may be removed in a future - release of G++. - -`-fno-elide-constructors' - The C++ standard allows an implementation to omit creating a - temporary which is only used to initialize another object of the - same type. Specifying this option disables that optimization, and - forces G++ to call the copy constructor in all cases. - -`-fno-enforce-eh-specs' - Don't generate code to check for violation of exception - specifications at runtime. This option violates the C++ standard, - but may be useful for reducing code size in production builds, - much like defining `NDEBUG'. This does not give user code - permission to throw exceptions in violation of the exception - specifications; the compiler will still optimize based on the - specifications, so throwing an unexpected exception will result in - undefined behavior. - -`-ffor-scope' -`-fno-for-scope' - If `-ffor-scope' is specified, the scope of variables declared in - a for-init-statement is limited to the `for' loop itself, as - specified by the C++ standard. If `-fno-for-scope' is specified, - the scope of variables declared in a for-init-statement extends to - the end of the enclosing scope, as was the case in old versions of - G++, and other (traditional) implementations of C++. - - The default if neither flag is given to follow the standard, but - to allow and give a warning for old-style code that would - otherwise be invalid, or have different behavior. - -`-fno-gnu-keywords' - Do not recognize `typeof' as a keyword, so that code can use this - word as an identifier. You can use the keyword `__typeof__' - instead. `-ansi' implies `-fno-gnu-keywords'. - -`-fno-implicit-templates' - Never emit code for non-inline templates which are instantiated - implicitly (i.e. by use); only emit code for explicit - instantiations. *Note Template Instantiation::, for more - information. - -`-fno-implicit-inline-templates' - Don't emit code for implicit instantiations of inline templates, - either. The default is to handle inlines differently so that - compiles with and without optimization will need the same set of - explicit instantiations. - -`-fno-implement-inlines' - To save space, do not emit out-of-line copies of inline functions - controlled by `#pragma implementation'. This will cause linker - errors if these functions are not inlined everywhere they are - called. - -`-fms-extensions' - Disable pedantic warnings about constructs used in MFC, such as - implicit int and getting a pointer to member function via - non-standard syntax. - -`-fno-nonansi-builtins' - Disable built-in declarations of functions that are not mandated by - ANSI/ISO C. These include `ffs', `alloca', `_exit', `index', - `bzero', `conjf', and other related functions. - -`-fno-operator-names' - Do not treat the operator name keywords `and', `bitand', `bitor', - `compl', `not', `or' and `xor' as synonyms as keywords. - -`-fno-optional-diags' - Disable diagnostics that the standard says a compiler does not - need to issue. Currently, the only such diagnostic issued by G++ - is the one for a name having multiple meanings within a class. - -`-fpermissive' - Downgrade some diagnostics about nonconformant code from errors to - warnings. Thus, using `-fpermissive' will allow some - nonconforming code to compile. - -`-frepo' - Enable automatic template instantiation at link time. This option - also implies `-fno-implicit-templates'. *Note Template - Instantiation::, for more information. - -`-fno-rtti' - Disable generation of information about every class with virtual - functions for use by the C++ runtime type identification features - (`dynamic_cast' and `typeid'). If you don't use those parts of - the language, you can save some space by using this flag. Note - that exception handling uses the same information, but it will - generate it as needed. The `dynamic_cast' operator can still be - used for casts that do not require runtime type information, i.e. - casts to `void *' or to unambiguous base classes. - -`-fstats' - Emit statistics about front-end processing at the end of the - compilation. This information is generally only useful to the G++ - development team. - -`-ftemplate-depth-N' - Set the maximum instantiation depth for template classes to N. A - limit on the template instantiation depth is needed to detect - endless recursions during template class instantiation. ANSI/ISO - C++ conforming programs must not rely on a maximum depth greater - than 17. - -`-fno-threadsafe-statics' - Do not emit the extra code to use the routines specified in the C++ - ABI for thread-safe initialization of local statics. You can use - this option to reduce code size slightly in code that doesn't need - to be thread-safe. - -`-fuse-cxa-atexit' - Register destructors for objects with static storage duration with - the `__cxa_atexit' function rather than the `atexit' function. - This option is required for fully standards-compliant handling of - static destructors, but will only work if your C library supports - `__cxa_atexit'. - -`-fno-use-cxa-get-exception-ptr' - Don't use the `__cxa_get_exception_ptr' runtime routine. This - will cause `std::uncaught_exception' to be incorrect, but is - necessary if the runtime routine is not available. - -`-fvisibility-inlines-hidden' - This switch declares that the user does not attempt to compare - pointers to inline methods where the addresses of the two functions - were taken in different shared objects. - - The effect of this is that GCC may, effectively, mark inline - methods with `__attribute__ ((visibility ("hidden")))' so that - they do not appear in the export table of a DSO and do not require - a PLT indirection when used within the DSO. Enabling this option - can have a dramatic effect on load and link times of a DSO as it - massively reduces the size of the dynamic export table when the - library makes heavy use of templates. - - The behavior of this switch is not quite the same as marking the - methods as hidden directly, because it does not affect static - variables local to the function or cause the compiler to deduce - that the function is defined in only one shared object. - - You may mark a method as having a visibility explicitly to negate - the effect of the switch for that method. For example, if you do - want to compare pointers to a particular inline method, you might - mark it as having default visibility. Marking the enclosing class - with explicit visibility will have no effect. - - Explicitly instantiated inline methods are unaffected by this - option as their linkage might otherwise cross a shared library - boundary. *Note Template Instantiation::. - -`-fvisibility-ms-compat' - This flag attempts to use visibility settings to make GCC's C++ - linkage model compatible with that of Microsoft Visual Studio. - - The flag makes these changes to GCC's linkage model: - - 1. It sets the default visibility to `hidden', like - `-fvisibility=hidden'. - - 2. Types, but not their members, are not hidden by default. - - 3. The One Definition Rule is relaxed for types without explicit - visibility specifications which are defined in more than one - different shared object: those declarations are permitted if - they would have been permitted when this option was not used. - - In new code it is better to use `-fvisibility=hidden' and export - those classes which are intended to be externally visible. - Unfortunately it is possible for code to rely, perhaps - accidentally, on the Visual Studio behavior. - - Among the consequences of these changes are that static data - members of the same type with the same name but defined in - different shared objects will be different, so changing one will - not change the other; and that pointers to function members - defined in different shared objects may not compare equal. When - this flag is given, it is a violation of the ODR to define types - with the same name differently. - -`-fno-weak' - Do not use weak symbol support, even if it is provided by the - linker. By default, G++ will use weak symbols if they are - available. This option exists only for testing, and should not be - used by end-users; it will result in inferior code and has no - benefits. This option may be removed in a future release of G++. - -`-nostdinc++' - Do not search for header files in the standard directories - specific to C++, but do still search the other standard - directories. (This option is used when building the C++ library.) - - In addition, these optimization, warning, and code generation options -have meanings only for C++ programs: - -`-fno-default-inline' - Do not assume `inline' for functions defined inside a class scope. - *Note Options That Control Optimization: Optimize Options. Note - that these functions will have linkage like inline functions; they - just won't be inlined by default. - -`-Wabi (C, Objective-C, C++ and Objective-C++ only)' - Warn when G++ generates code that is probably not compatible with - the vendor-neutral C++ ABI. Although an effort has been made to - warn about all such cases, there are probably some cases that are - not warned about, even though G++ is generating incompatible code. - There may also be cases where warnings are emitted even though the - code that is generated will be compatible. - - You should rewrite your code to avoid these warnings if you are - concerned about the fact that code generated by G++ may not be - binary compatible with code generated by other compilers. - - The known incompatibilities at this point include: - - * Incorrect handling of tail-padding for bit-fields. G++ may - attempt to pack data into the same byte as a base class. For - example: - - struct A { virtual void f(); int f1 : 1; }; - struct B : public A { int f2 : 1; }; - - In this case, G++ will place `B::f2' into the same byte - as`A::f1'; other compilers will not. You can avoid this - problem by explicitly padding `A' so that its size is a - multiple of the byte size on your platform; that will cause - G++ and other compilers to layout `B' identically. - - * Incorrect handling of tail-padding for virtual bases. G++ - does not use tail padding when laying out virtual bases. For - example: - - struct A { virtual void f(); char c1; }; - struct B { B(); char c2; }; - struct C : public A, public virtual B {}; - - In this case, G++ will not place `B' into the tail-padding for - `A'; other compilers will. You can avoid this problem by - explicitly padding `A' so that its size is a multiple of its - alignment (ignoring virtual base classes); that will cause - G++ and other compilers to layout `C' identically. - - * Incorrect handling of bit-fields with declared widths greater - than that of their underlying types, when the bit-fields - appear in a union. For example: - - union U { int i : 4096; }; - - Assuming that an `int' does not have 4096 bits, G++ will make - the union too small by the number of bits in an `int'. - - * Empty classes can be placed at incorrect offsets. For - example: - - struct A {}; - - struct B { - A a; - virtual void f (); - }; - - struct C : public B, public A {}; - - G++ will place the `A' base class of `C' at a nonzero offset; - it should be placed at offset zero. G++ mistakenly believes - that the `A' data member of `B' is already at offset zero. - - * Names of template functions whose types involve `typename' or - template template parameters can be mangled incorrectly. - - template - void f(typename Q::X) {} - - template