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.)