X-Git-Url: https://oss.titaniummirror.com/gitweb/?a=blobdiff_plain;f=gcc%2Fdoc%2Fcpp.info-3;fp=gcc%2Fdoc%2Fcpp.info-3;h=0000000000000000000000000000000000000000;hb=6fed43773c9b0ce596dca5686f37ac3fc0fa11c0;hp=14ec610d2fae2179c0dcbb85d4f56f634601b7d4;hpb=27b11d56b743098deb193d510b337ba22dc52e5c;p=msp430-gcc.git diff --git a/gcc/doc/cpp.info-3 b/gcc/doc/cpp.info-3 deleted file mode 100644 index 14ec610d..00000000 --- a/gcc/doc/cpp.info-3 +++ /dev/null @@ -1,1103 +0,0 @@ -This is doc/cpp.info, produced by makeinfo version 4.5 from -doc/cpp.texi. - -INFO-DIR-SECTION Programming -START-INFO-DIR-ENTRY -* Cpp: (cpp). The GNU C preprocessor. -END-INFO-DIR-ENTRY - - -File: cpp.info, Node: Ifdef, Next: If, Up: Conditional Syntax - -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. GNU 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 - -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. - - If EXPRESSION is not correctly formed, GCC issues an error and -treats the conditional as having failed. - - -File: cpp.info, Node: Defined, Next: Else, Prev: If, Up: Conditional Syntax - -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 - -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 - -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 - -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 - -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 - -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 GNU 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 - -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 - -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. - - This directive is not part of the C standard, but it is not an -official GNU extension either. We believe it came from System V. - - The `#sccs' directive is recognized on some systems, because it -appears in their header files. It is a very old, obscure, extension -which we did not invent, and we have been unable to find any -documentation of what it should do, so GCC simply ignores it. - - 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 - -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 - -Traditional Mode -**************** - - Traditional (pre-standard) C preprocessing is rather different from -the preprocessing specified by the standard. When GCC is given the -`-traditional' option, it attempts to emulate a traditional -preprocessor. We do not guarantee that GCC's behavior under -`-traditional' matches any pre-standard preprocessor exactly. - - Traditional mode exists only for backward compatibility. We have no -plans to augment it in any way nor will we change it except to fix -catastrophic bugs. You should be aware that modern C libraries often -have header files which are incompatible with traditional mode. - - This is a list of the differences. It may not be complete, and may -not correspond exactly to the behavior of either GCC or a true -traditional preprocessor. - - * Traditional macro expansion pays no attention to single-quote or - double-quote characters; macro argument symbols are replaced by the - argument values even when they appear within apparent string or - character constants. - - * Traditionally, it is permissible for a macro expansion to end in - the middle of a string or character constant. The constant - continues into the text surrounding the macro call. - - * However, the end of the line terminates a string or character - constant, with no error. (This is a kluge. Traditional mode is - commonly used to preprocess things which are not C, and have a - different comment syntax. Single apostrophes often appear in - comments. This kluge prevents the traditional preprocessor from - issuing errors on such comments.) - - * Preprocessing directives are recognized in traditional C only when - their leading `#' appears in the first column. There can be no - whitespace between the beginning of the line and the `#'. - - * In traditional C, a comment is equivalent to no text at all. (In - ISO C, a comment counts as whitespace.) It can be used sort of - the same way that `##' is used in ISO C, to paste macro arguments - together. - - * Traditional C does not have the concept of a preprocessing number. - - * A macro is not suppressed within its own definition, in - traditional C. Thus, any macro that is used recursively - inevitably causes an error. - - * The `#' and `##' operators are not available in traditional C. - - * In traditional C, the text at the end of a macro expansion can run - together with the text after the macro call, to produce a single - token. This is impossible in ISO C. - - * None of the GNU extensions to the preprocessor are available in - traditional mode, with the exception of a partial implementation of - assertions, and those may be removed in the future. - - * A true traditional C preprocessor does not recognize `#elif', - `#error', or `#pragma'. GCC supports `#elif' and `#error' even in - traditional mode, but not `#pragma'. - - * Traditional mode is text-based, not token-based, and comments are - stripped after macro expansion. Therefore, `/**/' can be used to - paste tokens together provided that there is no whitespace between - it and the tokens to be pasted. - - * Traditional mode preserves the amount and form of whitespace - provided by the user. Hard tabs remain hard tabs. This can be - useful, e.g. if you are preprocessing a Makefile (which we do not - encourage). - - You can request warnings about features that did not exist, or worked -differently, in traditional C with the `-Wtraditional' option. This -works only if you do _not_ specify `-traditional'. 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 - traditional C 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 - -Implementation Details -********************** - - Here we document details of how the preprocessor's implementation -affects its user-visible behavior. You should try to avoid undue -reliance on behavior described here, as it is possible that it will -change subtly in future implementations. - - Also documented here are obsolete features and changes from previous -versions of GNU CPP. - -* Menu: - -* Implementation-defined behavior:: -* Implementation limits:: -* Obsolete Features:: -* Differences from previous versions:: - - -File: cpp.info, Node: Implementation-defined behavior, Next: Implementation limits, Up: Implementation Details - -Implementation-defined behavior -=============================== - - This is how GNU 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. - - Currently, GNU cpp only supports character sets that are strict - supersets of ASCII, and performs no translation of characters. - - * 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; escape sequences such as `\a' are given the values they - would have on the target machine. - - Multi-character character constants are interpreted a character at - a time, shifting the previous result left by the number of bits per - character on the host, and adding the new character. For example, - 'ab' on an 8-bit host would be interpreted as 'a' * 256 + 'b'. If - there are more characters in the constant than can fit in the - widest native integer type on the host, usually a `long', the - excess characters are ignored and a diagnostic is given. - - * 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 - -Implementation limits -===================== - - GNU CPP has a small number of internal limits. This section lists -the limits which the C standard requires to be no lower than some -minimum, and all the others we are aware of. We intend there to be as -few limits as possible. If you encounter an undocumented or -inconvenient limit, please report that to us as a bug. (See the -section on reporting bugs in the GCC manual.) - - Where we say something is limited "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. GNU CPP is limited - only by available memory. - - * Levels of parenthesised expressions within a full expression. - - The C standard requires this to be at least 63. In preprocessor - conditional expressions, it is limited only by available memory. - - * 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. GNU 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. GNU 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 - -Obsolete Features -================= - - GNU CPP has a number of features which are present mainly for -compatibility with older programs. We discourage their use in new code. -In some cases, we plan to remove the feature in a future version of GCC. - -* Menu: - -* Assertions:: -* Obsolete once-only headers:: -* Miscellaneous obsolete features:: - - -File: cpp.info, Node: Assertions, Next: Obsolete once-only headers, Up: Obsolete Features - -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 cancelled 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: Obsolete once-only headers, Next: Miscellaneous obsolete features, Prev: Assertions, Up: Obsolete Features - -Obsolete once-only headers --------------------------- - - GNU CPP supports two more ways of indicating that a header file -should be read only once. Neither one is as portable as a wrapper -`#ifndef', and we recommend you do not use them in new programs. - - In the Objective-C language, there is 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. -GCC permits the use of `#import' in C and C++ as well as Objective-C. -However, it is not in standard C or C++ and should therefore not be -used by portable programs. - - `#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: Miscellaneous obsolete features, Prev: Obsolete once-only headers, Up: Obsolete Features - -Miscellaneous obsolete features -------------------------------- - - Here are a few more obsolete features. - - * Attempting to paste two tokens which together do not form a valid - preprocessing token. - - The preprocessor currently warns about this, and the resulting - preprocessed output is undefined. The tokens remain distinct if - the preprocessor is being used directly by the compiler front end. - - Most of the time, when you get this warning, you will find that - `##' is being used superstitiously, to guard against whitespace - appearing between two tokens. It is almost always safe to delete - the `##'. - - * `#pragma poison' - - This is the same as `#pragma GCC poison'. The version without the - `GCC' prefix is deprecated. *Note Pragmas::. - - * Multi-line string constants - - GCC currently allows a string constant to extend across multiple - logical lines of the source file. This extension is deprecated - and will be removed in a future version of GCC. Such string - constants are already rejected in all directives apart from - `#define'. - - Instead, make use of ISO C concatenation of adjacent string - literals, or use `\n' followed by a backslash-newline. - - - -File: cpp.info, Node: Differences from previous versions, Prev: Obsolete Features, Up: Implementation Details - -Differences from previous versions -================================== - - This section details behavior which has changed from previous -versions of GNU CPP. We do not plan to change it again in the near -future, but we do not promise not to, either. - - The "previous versions" discussed here are 2.95 and before. The -behavior of GCC 3.0 is mostly the same as the behavior of the widely -used 2.96 and 2.97 development snapshots. Where there are differences, -they generally represent bugs in the snapshots. - - * 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 betwen 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 - GNU 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. - - * Traditional mode and GNU extensions - - Traditional mode used to be implemented in the same program as - normal preprocessing. Therefore, all the GNU extensions to the - preprocessor were still available in traditional mode. It is now - a separate program and does not implement any of the GNU - extensions, except for a partial implementation of assertions. - Even those may be removed in a future release. - - * `#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.) - -