m a system header. *Note System Headers::.  File: cpp.info, Node: Other Directives, Next: Preprocessor Output, Prev: Pragmas, Up: Top 8 Other Directives ****************** The `#ident' directive takes one argument, a string constant. On some systems, that string constant is copied into a special segment of the object file. On other systems, the directive is ignored. The `#sccs' directive is a synonym for `#ident'. These directives are not part of the C standard, but they are not official GNU extensions either. What historical information we have been able to find, suggests they originated with System V. The "null directive" consists of a `#' followed by a newline, with only whitespace (including comments) in between. A null directive is understood as a preprocessing directive but has no effect on the preprocessor output. The primary significance of the existence of the null directive is that an input line consisting of just a `#' will produce no output, rather than a line of output containing just a `#'. Supposedly some old C programs contain such lines.  File: cpp.info, Node: Preprocessor Output, Next: Traditional Mode, Prev: Other Directives, Up: Top 9 Preprocessor Output ********************* When the C preprocessor is used with the C, C++, or Objective-C compilers, it is integrated into the compiler and communicates a stream of binary tokens directly to the compiler's parser. However, it can also be used in the more conventional standalone mode, where it produces textual output. The output from the C preprocessor looks much like the input, except that all preprocessing directive lines have been replaced with blank lines and all comments with spaces. Long runs of blank lines are discarded. The ISO standard specifies that it is implementation defined whether a preprocessor preserves whitespace between tokens, or replaces it with e.g. a single space. In GNU CPP, whitespace between tokens is collapsed to become a single space, with the exception that the first token on a non-directive line is preceded with sufficient spaces that it appears in the same column in the preprocessed output that it appeared in the original source file. This is so the output is easy to read. *Note Differences from previous versions::. CPP does not insert any whitespace where there was none in the original source, except where necessary to prevent an accidental token paste. Source file name and line number information is conveyed by lines of the form # LINENUM FILENAME FLAGS These are called "linemarkers". They are inserted as needed into the output (but never within a string or character constant). They mean that the following line originated in file FILENAME at line LINENUM. FILENAME will never contain any non-printing characters; they are replaced with octal escape sequences. After the file name comes zero or more flags, which are `1', `2', `3', or `4'. If there are multiple flags, spaces separate them. Here is what the flags mean: `1' This indicates the start of a new file. `2' This indicates returning to a file (after having included another file). `3' This indicates that the following text comes from a system header file, so certain warnings should be suppressed. `4' This indicates that the following text should be treated as being wrapped in an implicit `extern "C"' block. As an extension, the preprocessor accepts linemarkers in non-assembler input files. They are treated like the corresponding `#line' directive, (*note Line Control::), except that trailing flags are permitted, and are interpreted with the meanings described above. If multiple flags are given, they must be in ascending order. Some directives may be duplicated in the output of the preprocessor. These are `#ident' (always), `#pragma' (only if the preprocessor does not handle the pragma itself), and `#define' and `#undef' (with certain debugging options). If this happens, the `#' of the directive will always be in the first column, and there will be no space between the `#' and the directive name. If macro expansion happens to generate tokens which might be mistaken for a duplicated directive, a space will be inserted between the `#' and the directive name.  File: cpp.info, Node: Traditional Mode, Next: Implementation Details, Prev: Preprocessor Output, Up: Top 10 Traditional Mode ******************* Traditional (pre-standard) C preprocessing is rather different from the preprocessing specified by the standard. When GCC is given the `-traditional-cpp' option, it attempts to emulate a traditional preprocessor. GCC versions 3.2 and later only support traditional mode semantics in the preprocessor, and not in the compiler front ends. This chapter outlines the traditional preprocessor semantics we implemented. The implementation does not correspond precisely to the behavior of earlier versions of GCC, nor to any true traditional preprocessor. After all, inconsistencies among traditional implementations were a major motivation for C standardization. However, we intend that it should be compatible with true traditional preprocessors in all ways that actually matter. * Menu: * Traditional lexical analysis:: * Traditional macros:: * Traditional miscellany:: * Traditional warnings::  File: cpp.info, Node: Traditional lexical analysis, Next: Traditional macros, Up: Traditional Mode 10.1 Traditional lexical analysis ================================= The traditional preprocessor does not decompose its input into tokens the same way a standards-conforming preprocessor does. The input is simply treated as a stream of text with minimal internal form. This implementation does not treat trigraphs (*note trigraphs::) specially since they were an invention of the standards committee. It handles arbitrarily-positioned escaped newlines properly and splices the lines as you would expect; many traditional preprocessors did not do this. The form of horizontal whitespace in the input file is preserved in the output. In particular, hard tabs remain hard tabs. This can be useful if, for example, you are preprocessing a Makefile. Traditional CPP only recognizes C-style block comments, and treats the `/*' sequence as introducing a comment only if it lies outside quoted text. Quoted text is introduced by the usual single and double quotes, and also by an initial `<' in a `#include' directive. Traditionally, comments are completely removed and are not replaced with a space. Since a traditional compiler does its own tokenization of the output of the preprocessor, this means that comments can effectively be used as token paste operators. However, comments behave like separators for text handled by the preprocessor itself, since it doesn't re-lex its input. For example, in #if foo/**/bar `foo' and `bar' are distinct identifiers and expanded separately if they happen to be macros. In other words, this directive is equivalent to #if foo bar rather than #if foobar Generally speaking, in traditional mode an opening quote need not have a matching closing quote. In particular, a macro may be defined with replacement text that contains an unmatched quote. Of course, if you attempt to compile preprocessed output containing an unmatched quote you will get a syntax error. However, all preprocessing directives other than `#define' require matching quotes. For example: #define m This macro's fine and has an unmatched quote "/* This is not a comment. */ /* This is a comment. The following #include directive is ill-formed. */ #include ++foo; Function-like macros are similar in form but quite different in behavior to their ISO counterparts. Their arguments are contained within parentheses, are comma-separated, and can cross physical lines. Commas within nested parentheses are not treated as argument separators. Similarly, a quote in an argument cannot be left unclosed; a following comma or parenthesis that comes before the closing quote is treated like any other character. There is no facility for handling variadic macros. This implementation removes all comments from macro arguments, unless the `-C' option is given. The form of all other horizontal whitespace in arguments is preserved, including leading and trailing whitespace. In particular f( ) is treated as an invocation of the macro `f' with a single argument consisting of a single space. If you want to invoke a function-like macro that takes no arguments, you must not leave any whitespace between the parentheses. If a macro argument crosses a new line, the new line is replaced with a space when forming the argument. If the previous line contained an unterminated quote, the following line inherits the quoted state. Traditional preprocessors replace parameters in the replacement text with their arguments regardless of whether the parameters are within quotes or not. This provides a way to stringize arguments. For example #define str(x) "x" str(/* A comment */some text ) ==> "some text " Note that the comment is removed, but that the trailing space is preserved. Here is an example of using a comment to effect token pasting. #define suffix(x) foo_/**/x suffix(bar) ==> foo_bar  File: cpp.info, Node: Traditional miscellany, Next: Traditional warnings, Prev: Traditional macros, Up: Traditional Mode 10.3 Traditional miscellany =========================== Here are some things to be aware of when using the traditional preprocessor. * Preprocessing directives are recognized only when their leading `#' appears in the first column. There can be no whitespace between the beginning of the line and the `#', but whitespace can follow the `#'. * A true traditional C preprocessor does not recognize `#error' or `#pragma', and may not recognize `#elif'. CPP supports all the directives in traditional mode that it supports in ISO mode, including extensions, with the exception that the effects of `#pragma GCC poison' are undefined. * __STDC__ is not defined. * If you use digraphs the behavior is undefined. * If a line that looks like a directive appears within macro arguments, the behavior is undefined.  File: cpp.info, Node: Traditional warnings, Prev: Traditional miscellany, Up: Traditional Mode 10.4 Traditional warnings ========================= You can request warnings about features that did not exist, or worked differently, in traditional C with the `-Wtraditional' option. GCC does not warn about features of ISO C which you must use when you are using a conforming compiler, such as the `#' and `##' operators. Presently `-Wtraditional' warns about: * Macro parameters that appear within string literals in the macro body. In traditional C macro replacement takes place within string literals, but does not in ISO C. * In traditional C, some preprocessor directives did not exist. Traditional preprocessors would only consider a line to be a directive if the `#' appeared in column 1 on the line. Therefore `-Wtraditional' warns about directives that traditional C understands but would ignore because the `#' does not appear as the first character on the line. It also suggests you hide directives like `#pragma' not understood by traditional C by indenting them. Some traditional implementations would not recognize `#elif', so it suggests avoiding it altogether. * A function-like macro that appears without an argument list. In some traditional preprocessors this was an error. In ISO C it merely means that the macro is not expanded. * The unary plus operator. This did not exist in traditional C. * The `U' and `LL' integer constant suffixes, which were not available in traditional C. (Traditional C does support the `L' suffix for simple long integer constants.) You are not warned about uses of these suffixes in macros defined in system headers. For instance, `UINT_MAX' may well be defined as `4294967295U', but you will not be warned if you use `UINT_MAX'. You can usually avoid the warning, and the related warning about constants which are so large that they are unsigned, by writing the integer constant in question in hexadecimal, with no U suffix. Take care, though, because this gives the wrong result in exotic cases.  File: cpp.info, Node: Implementation Details, Next: Invocation, Prev: Traditional Mode, Up: Top 11 Implementation Details ************************* Here we document details of how the preprocessor's implementation affects its user-visible behavior. You should try to avoid undue reliance on behavior described here, as it is possible that it will change subtly in future implementations. Also documented here are obsolete features and changes from previous versions of CPP. * Menu: * Implementation-defined behavior:: * Implementation limits:: * Obsolete Features:: * Differences from previous versions::  File: cpp.info, Node: Implementation-defined behavior, Next: Implementation limits, Up: Implementation Details 11.1 Implementation-defined behavior ==================================== This is how CPP behaves in all the cases which the C standard describes as "implementation-defined". This term means that the implementation is free to do what it likes, but must document its choice and stick to it. * The mapping of physical source file multi-byte characters to the execution character set. Currently, CPP requires its input to be ASCII or UTF-8. The execution character set may be controlled by the user, with the `-fexec-charset' and `-fwide-exec-charset' options. * Identifier characters. The C and C++ standards allow identifiers to be composed of `_' and the alphanumeric characters. C++ and C99 also allow universal character names, and C99 further permits implementation-defined characters. GCC currently only permits universal character names if `-fextended-identifiers' is used, because the implementation of universal character names in identifiers is experimental. GCC allows the `$' character in identifiers as an extension for most targets. This is true regardless of the `std=' switch, since this extension cannot conflict with standards-conforming programs. When preprocessing assembler, however, dollars are not identifier characters by default. Currently the targets that by default do not permit `$' are AVR, IP2K, MMIX, MIPS Irix 3, ARM aout, and PowerPC targets for the AIX and BeOS operating systems. You can override the default with `-fdollars-in-identifiers' or `fno-dollars-in-identifiers'. *Note fdollars-in-identifiers::. * Non-empty sequences of whitespace characters. In textual output, each whitespace sequence is collapsed to a single space. For aesthetic reasons, the first token on each non-directive line of output is preceded with sufficient spaces that it appears in the same column as it did in the original source file. * The numeric value of character constants in preprocessor expressions. The preprocessor and compiler interpret character constants in the same way; i.e. escape sequences such as `\a' are given the values they would have on the target machine. The compiler values a multi-character character constant a character at a time, shifting the previous value left by the number of bits per target character, and then or-ing in the bit-pattern of the new character truncated to the width of a target character. The final bit-pattern is given type `int', and is therefore signed, regardless of whether single characters are signed or not (a slight change from versions 3.1 and earlier of GCC). If there are more characters in the constant than would fit in the target `int' the compiler issues a warning, and the excess leading characters are ignored. For example, `'ab'' for a target with an 8-bit `char' would be interpreted as `(int) ((unsigned char) 'a' * 256 + (unsigned char) 'b')', and `'\234a'' as `(int) ((unsigned char) '\234' * 256 + (unsigned char) 'a')'. * Source file inclusion. For a discussion on how the preprocessor locates header files, *note Include Operation::. * Interpretation of the filename resulting from a macro-expanded `#include' directive. *Note Computed Includes::. * Treatment of a `#pragma' directive that after macro-expansion results in a standard pragma. No macro expansion occurs on any `#pragma' directive line, so the question does not arise. Note that GCC does not yet implement any of the standard pragmas.  File: cpp.info, Node: Implementation limits, Next: Obsolete Features, Prev: Implementation-defined behavior, Up: Implementation Details 11.2 Implementation limits ========================== CPP has a small number of internal limits. This section lists the limits which the C standard requires to be no lower than some minimum, and all the others known. It is intended that there should be as few limits as possible. If you encounter an undocumented or inconvenient limit, please report that as a bug. *Note Reporting Bugs: (gcc)Bugs. Where we say something is limited "only by available memory", that means that internal data structures impose no intrinsic limit, and space is allocated with `malloc' or equivalent. The actual limit will therefore depend on many things, such as the size of other things allocated by the compiler at the same time, the amount of memory consumed by other processes on the same computer, etc. * Nesting levels of `#include' files. We impose an arbitrary limit of 200 levels, to avoid runaway recursion. The standard requires at least 15 levels. * Nesting levels of conditional inclusion. The C standard mandates this be at least 63. CPP is limited only by available memory. * Levels of parenthesized expressions within a full expression. The C standard requires this to be at least 63. In preprocessor conditional expressions, it is limited only by available memory. * Significant initial characters in an identifier or macro name. The preprocessor treats all characters as significant. The C standard requires only that the first 63 be significant. * Number of macros simultaneously defined in a single translation unit. The standard requires at least 4095 be possible. CPP is limited only by available memory. * Number of parameters in a macro definition and arguments in a macro call. We allow `USHRT_MAX', which is no smaller than 65,535. The minimum required by the standard is 127. * Number of characters on a logical source line. The C standard requires a minimum of 4096 be permitted. CPP places no limits on this, but you may get incorrect column numbers reported in diagnostics for lines longer than 65,535 characters. * Maximum size of a source file. The standard does not specify any lower limit on the maximum size of a source file. GNU cpp maps files into memory, so it is limited by the available address space. This is generally at least two gigabytes. Depending on the operating system, the size of physical memory may or may not be a limitation.  File: cpp.info, Node: Obsolete Features, Next: Differences from previous versions, Prev: Implementation limits, Up: Implementation Details 11.3 Obsolete Features ====================== CPP has 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::  File: cpp.info, Node: Assertions, Next: Obsolete once-only headers, Up: Obsolete Features 11.3.1 Assertions ----------------- "Assertions" are a deprecated alternative to macros in writing conditionals to test what sort of computer or system the compiled program will run on. Assertions are usually predefined, but you can define them with preprocessing directives or command-line options. Assertions were intended to provide a more systematic way to describe the compiler's target system. However, in practice they are just as unpredictable as the system-specific predefined macros. In addition, they are not part of any standard, and only a few compilers support them. Therefore, the use of assertions is *less* portable than the use of system-specific predefined macros. We recommend you do not use them at all. An assertion looks like this: #PREDICATE (ANSWER) PREDICATE must be a single identifier. ANSWER can be any sequence of tokens; all characters are significant except for leading and trailing whitespace, and differences in internal whitespace sequences are ignored. (This is similar to the rules governing macro redefinition.) Thus, `(x + y)' is different from `(x+y)' but equivalent to `( x + y )'. Parentheses do not nest inside an answer. To test an assertion, you write it in an `#if'. For example, this conditional succeeds if either `vax' or `ns16000' has been asserted as an answer for `machine'. #if #machine (vax) || #machine (ns16000) You can test whether _any_ answer is asserted for a predicate by omitting the answer in the conditional: #if #machine Assertions are made with the `#assert' directive. Its sole argument is the assertion to make, without the leading `#' that identifies assertions in conditionals. #assert PREDICATE (ANSWER) You may make several assertions with the same predicate and different answers. Subsequent assertions do not override previous ones for the same predicate. All the answers for any given predicate are simultaneously true. Assertions can be canceled with the `#unassert' directive. It has the same syntax as `#assert'. In that form it cancels only the answer which was specified on the `#unassert' line; other answers for that predicate remain true. You can cancel an entire predicate by leaving out the answer: #unassert PREDICATE In either form, if no such assertion has been made, `#unassert' has no effect. You can also make or cancel assertions using command line options. *Note Invocation::.  File: cpp.info, Node: Obsolete once-only headers, Prev: Assertions, Up: Obsolete Features 11.3.2 Obsolete once-only headers --------------------------------- 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: Differences from previous versions, Prev: Obsolete Features, Up: Implementation Details 11.4 Differences from previous versions ======================================= This section details behavior which has changed from previous versions of CPP. We do not plan to change it again in the near future, but we do not promise not to, either. The "previous versions" discussed here are 2.95 and before. The behavior of GCC 3.0 is mostly the same as the behavior of the widely used 2.96 and 2.97 development snapshots. Where there are differences, they generally represent bugs in the snapshots. * -I- deprecated This option has been deprecated in 4.0. `-iquote' is meant to replace the need for this option. * Order of evaluation of `#' and `##' operators The standard does not specify the order of evaluation of a chain of `##' operators, nor whether `#' is evaluated before, after, or at the same time as `##'. You should therefore not write any code which depends on any specific ordering. It is possible to guarantee an ordering, if you need one, by suitable use of nested macros. An example of where this might matter is pasting the arguments `1', `e' and `-2'. This would be fine for left-to-right pasting, but right-to-left pasting would produce an invalid token `e-2'. GCC 3.0 evaluates `#' and `##' at the same time and strictly left to right. Older versions evaluated all `#' operators first, then all `##' operators, in an unreliable order. * The form of whitespace between tokens in preprocessor output *Note Preprocessor Output::, for the current textual format. This is also the format used by stringification. Normally, the preprocessor communicates tokens directly to the compiler's parser, and whitespace does not come up at all. Older versions of GCC preserved all whitespace provided by the user and inserted lots more whitespace of their own, because they could not accurately predict when extra spaces were needed to prevent accidental token pasting. * Optional argument when invoking rest argument macros As an extension, GCC permits you to omit the variable arguments entirely when you use a variable argument macro. This is forbidden by the 1999 C standard, and will provoke a pedantic warning with GCC 3.0. Previous versions accepted it silently. * `##' swallowing preceding text in rest argument macros Formerly, in a macro expansion, if `##' appeared before a variable arguments parameter, and the set of tokens specified for that argument in the macro invocation was empty, previous versions of CPP would back up and remove the preceding sequence of non-whitespace characters (*not* the preceding token). This extension is in direct conflict with the 1999 C standard and has been drastically pared back. In the current version of the preprocessor, if `##' appears between a comma and a variable arguments parameter, and the variable argument is omitted entirely, the comma will be removed from the expansion. If the variable argument is empty, or the token before `##' is not a comma, then `##' behaves as a normal token paste. * `#line' and `#include' The `#line' directive used to change GCC's notion of the "directory containing the current file", used by `#include' with a double-quoted header file name. In 3.0 and later, it does not. *Note Line Control::, for further explanation. * Syntax of `#line' In GCC 2.95 and previous, the string constant argument to `#line' was treated the same way as the argument to `#include': backslash escapes were not honored, and the string ended at the second `"'. This is not compliant with the C standard. In GCC 3.0, an attempt was made to correct the behavior, so that the string was treated as a real string constant, but it turned out to be buggy. In 3.1, the bugs have been fixed. (We are not fixing the bugs in 3.0 because they affect relatively few people and the fix is quite invasive.)  File: cpp.info, Node: Invocation, Next: Environment Variables, Prev: Implementation Details, Up: Top 12 Invocation ************* Most often when you use the C preprocessor you will not have to invoke it explicitly: the C compiler will do so automatically. However, the preprocessor is sometimes useful on its own. All the options listed here are also acceptable to the C compiler and have the same meaning, except that the C compiler has different rules for specifying the output file. _Note:_ Whether you use the preprocessor by way of `gcc' or `cpp', the "compiler driver" is run first. This program's purpose is to translate your command into invocations of the programs that do the actual work. Their command line interfaces are similar but not identical to the documented interface, and may change without notice. The C preprocessor expects two file names as arguments, INFILE and OUTFILE. The preprocessor reads INFILE together with any other files it specifies with `#include'. All the output generated by the combined input files is written in OUTFILE. Either INFILE or OUTFILE may be `-', which as INFILE means to read from standard input and as OUTFILE means to write to standard output. Also, if either file is omitted, it means the same as if `-' had been specified for that file. Unless otherwise noted, or the option ends in `=', all options which take an argument may have that argument appear either immediately after the option, or with a space between option and argument: `-Ifoo' and `-I foo' have the same effect. Many options have multi-letter names; therefore multiple single-letter options may _not_ be grouped: `-dM' is very different from `-d -M'. `-D NAME' Predefine NAME as a macro, with definition `1'. `-D NAME=DEFINITION' The contents of DEFINITION are tokenized and processed as if they appeared during translation phase three in a `#define' directive. In particular, the definition will be truncated by embedded newline characters. If you are invoking the preprocessor from a shell or shell-like program you may need to use the shell's quoting syntax to protect characters such as spaces that have a meaning in the shell syntax. If you wish to define a function-like macro on the command line, write its argument list with surrounding parentheses before the equals sign (if any). Parentheses are meaningful to most shells, so you will need to quote the option. With `sh' and `csh', `-D'NAME(ARGS...)=DEFINITION'' works. `-D' and `-U' options are processed in the order they are given on the command line. All `-imacros FILE' and `-include FILE' options are processed after all `-D' and `-U' options. `-U NAME' Cancel any previous definition of NAME, either built in or provided with a `-D' option. `-undef' Do not predefine any system-specific or GCC-specific macros. The standard predefined macros remain defined. *Note Standard Predefined Macros::. `-I DIR' Add the directory DIR to the list of directories to be searched for header files. *Note Search Path::. Directories named by `-I' are searched before the standard system include directories. If the directory DIR is a standard system include directory, the option is ignored to ensure that the default search order for system directories and the special treatment of system headers are not defeated (*note System Headers::) . If DIR begins with `=', then the `=' will be replaced by the sysroot prefix; see `--sysroot' and `-isysroot'. `-o FILE' Write output to FILE. This is the same as specifying FILE as the second non-option argument to `cpp'. `gcc' has a different interpretation of a second non-option argument, so you must use `-o' to specify the output file. `-Wall' Turns on all optional warnings which are desirable for normal code. At present this is `-Wcomment', `-Wtrigraphs', `-Wmultichar' and a warning about integer promotion causing a change of sign in `#if' expressions. Note that many of the preprocessor's warnings are on by default and have no options to control them. `-Wcomment' `-Wcomments' Warn whenever a comment-start sequence `/*' appears in a `/*' comment, or whenever a backslash-newline appears in a `//' comment. (Both forms have the same effect.) `-Wtrigraphs' Most trigraphs in comments cannot affect the meaning of the program. However, a trigraph that would form an escaped newline (`??/' at the end of a line) can, by changing where the comment begins or ends. Therefore, only trigraphs that would form escaped newlines produce warnings inside a comment. This option is implied by `-Wall'. If `-Wall' is not given, this option is still enabled unless trigraphs are enabled. To get trigraph conversion without warnings, but get the other `-Wall' warnings, use `-trigraphs -Wall -Wno-trigraphs'. `-Wtraditional' Warn about certain constructs that behave differently in traditional and ISO C. Also warn about ISO C constructs that have no traditional C equivalent, and problematic constructs which should be avoided. *Note Traditional Mode::. `-Wimport' Warn the first time `#import' is used. `-Wundef' Warn whenever an identifier which is not a macro is encountered in an `#if' directive, outside of `defined'. Such identifiers are replaced with zero. `-Wunused-macros' Warn about macros defined in the main file that are unused. A macro is "used" if it is expanded or tested for existence at least once. The preprocessor will also warn if the macro has not been used at the time it is redefined or undefined. Built-in macros, macros defined on the command line, and macros defined in include files are not warned about. _Note:_ If a macro is actually used, but only used in skipped conditional blocks, then CPP will report it as unused. To avoid the warning in such a case, you might improve the scope of the macro's definition by, for example, moving it into the first skipped block. Alternatively, you could provide a dummy use with something like: #if defined the_macro_causing_the_warning #endif `-Wendif-labels' Warn whenever an `#else' or an `#endif' are followed by text. This usually happens in code of the form #if FOO ... #else FOO ... #endif FOO The second and third `FOO' should be in comments, but often are not in older programs. This warning is on by default. `-Werror' Make all warnings into hard errors. Source code which triggers warnings will be rejected. `-Wsystem-headers' Issue warnings for code in system headers. These are normally unhelpful in finding bugs in your own code, therefore suppressed. If you are responsible for the system library, you may want to see them. `-w' Suppress all warnings, including those which GNU CPP issues by default. `-pedantic' Issue all the mandatory diagnostics listed in the C standard. Some of them are left out by default, since they trigger frequently on harmless code. `-pedantic-errors' Issue all the mandatory diagnostics, and make all mandatory diagnostics into errors. This includes mandatory diagnostics that GCC issues without `-pedantic' but treats as warnings. `-M' Instead of outputting the result of preprocessing, output a rule suitable for `make' describing the dependencies of the main source file. The preprocessor outputs one `make' rule containing the object file name for that source file, a colon, and the names of all the included files, including those coming from `-include' or `-imacros' command line options. Unless specified explicitly (with `-MT' or `-MQ'), the object file name consists of the name of the source file with any suffix replaced with object file suffix and with any leading directory parts removed. If there are many included files then the rule is split into several lines using `\'-newline. The rule has no commands. This option does not suppress the preprocessor's debug output, such as `-dM'. To avoid mixing such debug output with the dependency rules you should explicitly specify the dependency output file with `-MF', or use an environment variable like `DEPENDENCIES_OUTPUT' (*note Environment Variables::). Debug output will still be sent to the regular output stream as normal. Passing `-M' to the driver implies `-E', and suppresses warnings with an implicit `-w'. `-MM' Like `-M' but do not mention header files that are found in system header directories, nor header files that are included, directly or indirectly, from such a header. This implies that the choice of angle brackets or double quotes in an `#include' directive does not in itself determine whether that header will appear in `-MM' dependency output. This is a slight change in semantics from GCC versions 3.0 and earlier. `-MF FILE' When used with `-M' or `-MM', specifies a file to write the dependencies to. If no `-MF' switch is given the preprocessor sends the rules to the same place it would have sent preprocessed output. When used with the driver options `-MD' or `-MMD', `-MF' overrides the default dependency output file. `-MG' In conjunction with an option such as `-M' requesting dependency generation, `-MG' assumes missing header files are generated files and adds them to the dependency list without raising an error. The dependency filename is taken directly from the `#include' directive without prepending any path. `-MG' also suppresses preprocessed output, as a missing header file renders this useless. This feature is used in automatic updating of makefiles. `-MP' This option instructs CPP to add a phony target for each dependency other than the main file, causing each to depend on nothing. These dummy rules work around errors `make' gives if you remove header files without updating the `Makefile' to match. This is typical output: test.o: test.c test.h test.h: `-MT TARGET' Change the target of the rule emitted by dependency generation. By default CPP takes the name of the main input file, deletes any directory components and any file suffix such as `.c', and appends the platform's usual object suffix. The result is the target. An `-MT' option will set the target to be exactly the string you specify. If you want multiple targets, you can specify them as a single argument to `-MT', or use multiple `-MT' options. For example, `-MT '$(objpfx)foo.o'' might give $(objpfx)foo.o: foo.c `-MQ TARGET' Same as `-MT', but it quotes any characters which are special to Make. `-MQ '$(objpfx)foo.o'' gives $$(objpfx)foo.o: foo.c The default target is automatically quoted, as if it were given with `-MQ'. `-MD' `-MD' is equivalent to `-M -MF FILE', except that `-E' is not implied. The driver determines FILE based on whether an `-o' option is given. If it is, the driver uses its argument but with a suffix of `.d', otherwise it takes the name of the input file, removes any directory components and suffix, and applies a `.d' suffix. If `-MD' is used in conjunction with `-E', any `-o' switch is understood to specify the dependency output file (*note -MF: dashMF.), but if used without `-E', each `-o' is understood to specify a target object file. Since `-E' is not implied, `-MD' can be used to generate a dependency output file as a side-effect of the compilation process. `-MMD' Like `-MD' except mention only user header files, not system header files. `-x c' `-x c++' `-x objective-c' `-x assembler-with-cpp' Specify the source language: C, C++, Objective-C, or assembly. This has nothing to do with standards conformance or extensions; it merely selects which base syntax to expect. If you give none of these options, cpp will deduce the language from the extension of the source file: `.c', `.cc', `.m', or `.S'. Some other common extensions for C++ and assembly are also recognized. If cpp does not recognize the extension, it will treat the file as C; this is the most generic mode. _Note:_ Previous versions of cpp accepted a `-lang' option which selected both the language and the standards conformance level. This option has been removed, because it conflicts with the `-l' option. `-std=STANDARD' `-ansi' Specify the standard to which the code should conform. Currently CPP knows about C and C++ standards; others may be added in the future. STANDARD may be one of: `iso9899:1990' `c89' The ISO C standard from 1990. `c89' is the customary shorthand for this version of the standard. The `-ansi' option is equivalent to `-std=c89'. `iso9899:199409' The 1990 C standard, as amended in 1994. `iso9899:1999' `c99' `iso9899:199x' `c9x' The revised ISO C standard, published in December 1999. Before publication, this was known as C9X. `gnu89' The 1990 C standard plus GNU extensions. This is the default. `gnu99' `gnu9x' The 1999 C standard plus GNU extensions. `c++98' The 1998 ISO C++ standard plus amendments. `gnu++98' The same as `-std=c++98' plus GNU extensions. This is the default for C++ code. `-I-' Split the include path. Any directories specified with `-I' options before `-I-' are searched only for headers requested with `#include "FILE"'; they are not searched for `#include '. If additional directories are specified with `-I' options after the `-I-', those directories are searched for all `#include' directives. In addition, `-I-' inhibits the use of the directory of the current file directory as the first search directory for `#include "FILE"'. *Note Search Path::. This option has been deprecated. `-nostdinc' Do not search the standard system directories for header files. Only the directories you have specified with `-I' options (and the directory of the current file, if appropriate) are searched. `-nostdinc++' Do not search for header files in the C++-specific standard directories, but do still search the other standard directories. (This option is used when building the C++ library.) `-include FILE' Process FILE as if `#include "file"' appeared as the first line of the primary source file. However, the first directory searched for FILE is the preprocessor's working directory _instead of_ the directory containing the main source file. If not found there, it is searched for in the remainder of the `#include "..."' search chain as normal. If multiple `-include' options are given, the files are included in the order they appear on the command line. `-imacros FILE' Exactly like `-include', except that any output produced by scanning FILE is thrown away. Macros it defines remain defined. This allows you to acquire all the macros from a header without also processing its declarations. All files specified by `-imacros' are processed before all files specified by `-include'. `-idirafter DIR' Search DIR for header files, but do it _after_ all directories specified with `-I' and the standard system directories have been exhausted. DIR is treated as a system include directory. If DIR begins with `=', then the `=' will be replaced by the sysroot prefix; see `--sysroot' and `-isysroot'. `-iprefix PREFIX' Specify PREFIX as the prefix for subsequent `-iwithprefix' options. If the prefix represents a directory, you should include the final `/'. `-iwithprefix DIR' `-iwithprefixbefore DIR' Append DIR to the prefix specified previously with `-iprefix', and add the resulting directory to the include search path. `-iwithprefixbefore' puts it in the same place `-I' would; `-iwithprefix' puts it where `-idirafter' would. `-isysroot DIR' This option is like the `--sysroot' option, but applies only to header files. See the `--sysroot' option for more information. `-imultilib DIR' Use DIR as a subdirectory of the directory containing target-specific C++ headers. `-isystem DIR' Search DIR for header files, after all directories specified by `-I' but before the standard system directories. Mark it as a system directory, so that it gets the same special treatment as is applied to the standard system directories. *Note System Headers::. If DIR begins with `=', then the `=' will be replaced by the sysroot prefix; see `--sysroot' and `-isysroot'. `-iquote DIR' Search DIR only for header files requested with `#include "FILE"'; they are not searched for `#include ', before all directories specified by `-I' and before the standard system directories. *Note Search Path::. If DIR begins with `=', then the `=' will be replaced by the sysroot prefix; see `--sysroot' and `-isysroot'. `-fdirectives-only' When preprocessing, handle directives, but do not expand macros. The option's behavior depends on the `-E' and `-fpreprocessed' options. With `-E', preprocessing is limited to the handling of directives such as `#define', `#ifdef', and `#error'. Other preprocessor operations, such as macro expansion and trigraph conversion are not performed. In addition, the `-dD' option is implicitly enabled. With `-fpreprocessed', predefinition of command line and most builtin macros is disabled. Macros such as `__LINE__', which are contextually dependent, are handled normally. This enables compilation of files previously preprocessed with `-E -fdirectives-only'. With both `-E' and `-fpreprocessed', the rules for `-fpreprocessed' take precedence. This enables full preprocessing of files previously preprocessed with `-E -fdirectives-only'. `-fdollars-in-identifiers' Accept `$' in identifiers. *Note Identifier characters::. `-fextended-identifiers' Accept universal character names in identifiers. This option is experimental; in a future version of GCC, it will be enabled by default for C99 and C++. `-fpreprocessed' Indicate to the preprocessor that the input file has already been preprocessed. This suppresses things like macro expansion, trigraph conversion, escaped newline splicing, and processing of most directives. The preprocessor still recognizes and removes comments, so that you can pass a file preprocessed with `-C' to the compiler without problems. In this mode the integrated preprocessor is little more than a tokenizer for the front ends. `-fpreprocessed' is implicit if the input file has one of the extensions `.i', `.ii' or `.mi'. These are the extensions that GCC uses for preprocessed files created by `-save-temps'. `-ftabstop=WIDTH' Set the distance between tab stops. This helps the preprocessor report correct column numbers in warnings or errors, even if tabs appear on the line. If the value is less than 1 or greater than 100, the option is ignored. The default is 8. `-fexec-charset=CHARSET' Set the execution character set, used for string and character constants. The default is UTF-8. CHARSET can be any encoding supported by the system's `iconv' library routine. `-fwide-exec-charset=CHARSET' Set the wide execution character set, used for wide string and character constants. The default is UTF-32 or UTF-16, whichever corresponds to the width of `wchar_t'. As with `-fexec-charset', CHARSET can be any encoding supported by the system's `iconv' library routine; however, you will have problems with encodings that do not fit exactly in `wchar_t'. `-finput-charset=CHARSET' Set the input character set, used for translation from the character set of the input file to the source character set used by GCC. If the locale does not specify, or GCC cannot get this information from the locale, the default is UTF-8. This can be overridden by either the locale or this command line option. Currently the command line option takes precedence if there's a conflict. CHARSET can be any encoding supported by the system's `iconv' library routine. `-fworking-directory' Enable generation of linemarkers in the preprocessor output that will let the compiler know the current working directory at the time of preprocessing. When this option is enabled, the preprocessor will emit, after the initial linemarker, a second linemarker with the current working directory followed by two slashes. GCC will use this directory, when it's present in the preprocessed input, as the directory emitted as the current working directory in some debugging information formats. This option is implicitly enabled if debugging information is enabled, but this can be inhibited with the negated form `-fno-working-directory'. If the `-P' flag is present in the command line, this option has no effect, since no `#line' directives are emitted whatsoever. `-fno-show-column' Do not print column numbers in diagnostics. This may be necessary if diagnostics are being scanned by a program that does not understand the column numbers, such as `dejagnu'. `-A PREDICATE=ANSWER' Make an assertion with the predicate PREDICATE and answer ANSWER. This form is preferred to the older form `-A PREDICATE(ANSWER)', which is still supported, because it does not use shell special characters. *Note Assertions::. `-A -PREDICATE=ANSWER' Cancel an assertion with the predicate PREDICATE and answer ANSWER. `-dCHARS' CHARS is a sequence of one or more of the following characters, and must not be preceded by a space. Other characters are interpreted by the compiler proper, or reserved for future versions of GCC, and so are silently ignored. If you specify characters whose behavior conflicts, the result is undefined. `M' Instead of the normal output, generate a list of `#define' directives for all the macros defined during the execution of the preprocessor, including predefined macros. This gives you a way of finding out what is predefined in your version of the preprocessor. Assuming you have no file `foo.h', the command touch foo.h; cpp -dM foo.h will show all the predefined macros. If you use `-dM' without the `-E' option, `-dM' is interpreted as a synonym for `-fdump-rtl-mach'. *Note Debugging Options: (gcc)Debugging Options. `D' Like `M' except in two respects: it does _not_ include the predefined macros, and it outputs _both_ the `#define' directives and the result of preprocessing. Both kinds of output go to the standard output file. `N' Like `D', but emit only the macro names, not their expansions. `I' Output `#include' directives in addition to the result of preprocessing. `-P' Inhibit generation of linemarkers in the output from the preprocessor. This might be useful when running the preprocessor on something that is not C code, and will be sent to a program which might be confused by the linemarkers. *Note Preprocessor Output::. `-C' Do not discard comments. All comments are passed through to the output file, except for comments in processed directives, which are deleted along with the directive. You should be prepared for side effects when using `-C'; it causes the preprocessor to treat comments as tokens in their own right. For example, comments appearing at the start of what would be a directive line have the effect of turning that line into an ordinary source line, since the first token on the line is no longer a `#'. `-CC' Do not discard comments, including during macro expansion. This is like `-C', except that comments contained within macros are also passed through to the output file where the macro is expanded. In addition to the side-effects of the `-C' option, the `-CC' option causes all C++-style comments inside a macro to be converted to C-style comments. This is to prevent later use of that macro from inadvertently commenting out the remainder of the source line. The `-CC' option is generally used to support lint comments. `-traditional-cpp' Try to imitate the behavior of old-fashioned C preprocessors, as opposed to ISO C preprocessors. *Note Traditional Mode::. `-trigraphs' Process trigraph sequences. *Note Initial processing::. `-remap' Enable special code to work around file systems which only permit very short file names, such as MS-DOS. `--help' `--target-help' Print text describing all the command line options instead of preprocessing anything. `-v' Verbose mode. Print out GNU CPP's version number at the beginning of execution, and report the final form of the include path. `-H' Print the name of each header file used, in addition to other normal activities. Each name is indented to show how deep in the `#include' stack it is. Precompiled header files are also printed, even if they are found to be invalid; an invalid precompiled header file is printed with `...x' and a valid one with `...!' . `-version' `--version' Print out GNU CPP's version number. With one dash, proceed to preprocess as normal. With two dashes, exit immediately.  File: cpp.info, Node: Environment Variables, Next: GNU Free Documentation License, Prev: Invocation, Up: Top 13 Environment Variables ************************ This section describes the environment variables that affect how CPP operates. You can use them to specify directories or prefixes to use when searching for include files, or to control dependency output. Note that you can also specify places to search using options such as `-I', and control dependency output with options like `-M' (*note Invocation::). These take precedence over environment variables, which in turn take precedence over the configuration of GCC. `CPATH' `C_INCLUDE_PATH' `CPLUS_INCLUDE_PATH' `OBJC_INCLUDE_PATH' Each variable's value is a list of directories separated by a special character, much like `PATH', in which to look for header files. The special character, `PATH_SEPARATOR', is target-dependent and determined at GCC build time. For Microsoft Windows-based targets it is a semicolon, and for almost all other targets it is a colon. `CPATH' specifies a list of directories to be searched as if specified with `-I', but after any paths given with `-I' options on the command line. This environment variable is used regardless of which language is being preprocessed. The remaining environment variables apply only when preprocessing the particular language indicated. Each specifies a list of directories to be searched as if specified with `-isystem', but after any paths given with `-isystem' options on the command line. In all these variables, an empty element instructs the compiler to search its current working directory. Empty elements can appear at the beginning or end of a path. For instance, if the value of `CPATH' is `:/special/include', that has the same effect as `-I. -I/special/include'. See also *note Search Path::. `DEPENDENCIES_OUTPUT' If this variable is set, its value specifies how to output dependencies for Make based on the non-system header files processed by the compiler. System header files are ignored in the dependency output. The value of `DEPENDENCIES_OUTPUT' can be just a file name, in which case the Make rules are written to that file, guessing the target name from the source file name. Or the value can have the form `FILE TARGET', in which case the rules are written to file FILE using TARGET as the target name. In other words, this environment variable is equivalent to combining the options `-MM' and `-MF' (*note Invocation::), with an optional `-MT' switch too. `SUNPRO_DEPENDENCIES' This variable is the same as `DEPENDENCIES_OUTPUT' (see above), except that system header files are not ignored, so it implies `-M' rather than `-MM'. However, the dependence on the main input file is omitted. *Note Invocation::.  File: cpp.info, Node: GNU Free Documentation License, Next: Index of Directives, Prev: Environment Variables, Up: Top GNU Free Documentation License ****************************** Version 1.2, November 2002 Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. 0. PREAMBLE The purpose of this License is to make a manual, textbook, or other functional and useful document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. 1. APPLICABILITY AND DEFINITIONS This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law. A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none. The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words. A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque". Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML,