+++ /dev/null
-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
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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'.
-
-\1f
-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 `/*'.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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::.
-
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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::
-
-\1f
-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.
-
-
-\1f
-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.
-
-
-\1f
-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::
-
-\1f
-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::.
-
-\1f
-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.
-
-\1f
-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.
-
-
-\1f
-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.)
-
-
projects / msp430-gcc.git / blobdiff