| This is Info file cpp.info, produced by Makeinfo version 1.68 from the |
| input file cpp.texi. |
| |
| This file documents the GNU C Preprocessor. |
| |
| Copyright 1987, 1989, 1991, 1992, 1993, 1994, 1995 Free Software |
| Foundation, Inc. |
| |
| Permission is granted to make and distribute verbatim copies of this |
| manual provided the copyright notice and this permission notice are |
| preserved on all copies. |
| |
| Permission is granted to copy and distribute modified versions of |
| this manual under the conditions for verbatim copying, provided also |
| that the entire resulting derived work is distributed under the terms |
| of a permission notice identical to this one. |
| |
| Permission is granted to copy and distribute translations of this |
| manual into another language, under the above conditions for modified |
| versions. |
| |
| |
| File: cpp.info, Node: Invocation, Next: Concept Index, Prev: Output, Up: Top |
| |
| Invoking the C Preprocessor |
| =========================== |
| |
| 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. |
| |
| 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 OUTFILE or both file names are omitted, the standard output |
| and standard input are used for the omitted file names. |
| |
| Here is a table of command options accepted by the C preprocessor. |
| These options can also be given when compiling a C program; they are |
| passed along automatically to the preprocessor when it is invoked by the |
| compiler. |
| |
| `-P' |
| Inhibit generation of `#'-lines with line-number information in |
| the output from the preprocessor (*note Output::.). 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 |
| `#'-lines. |
| |
| `-C' |
| Do not discard comments: pass them through to the output file. |
| Comments appearing in arguments of a macro call will be copied to |
| the output before the expansion of the macro call. |
| |
| `-traditional' |
| Try to imitate the behavior of old-fashioned C, as opposed to ANSI |
| C. |
| |
| * Traditional macro expansion pays no attention to singlequote |
| or doublequote 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, traditionally the end of the line terminates a |
| string or character constant, with no error. |
| |
| * In traditional C, a comment is equivalent to no text at all. |
| (In ANSI C, a comment counts as whitespace.) |
| |
| * Traditional C does not have the concept of a "preprocessing |
| number". It considers `1.0e+4' to be three tokens: `1.0e', |
| `+', and `4'. |
| |
| * A macro is not suppressed within its own definition, in |
| traditional C. Thus, any macro that is used recursively |
| inevitably causes an error. |
| |
| * The character `#' has no special meaning within a macro |
| definition 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 ANSI C.) |
| |
| * Traditionally, `\' inside a macro argument suppresses the |
| syntactic significance of the following character. |
| |
| `-trigraphs' |
| Process ANSI standard trigraph sequences. These are |
| three-character sequences, all starting with `??', that are |
| defined by ANSI C to stand for single characters. For example, |
| `??/' stands for `\', so `'??/n'' is a character constant for a |
| newline. Strictly speaking, the GNU C preprocessor does not |
| support all programs in ANSI Standard C unless `-trigraphs' is |
| used, but if you ever notice the difference it will be with relief. |
| |
| You don't want to know any more about trigraphs. |
| |
| `-pedantic' |
| Issue warnings required by the ANSI C standard in certain cases |
| such as when text other than a comment follows `#else' or `#endif'. |
| |
| `-pedantic-errors' |
| Like `-pedantic', except that errors are produced rather than |
| warnings. |
| |
| `-Wtrigraphs' |
| Warn if any trigraphs are encountered (assuming they are enabled). |
| |
| `-Wcomment' |
| Warn whenever a comment-start sequence `/*' appears in a `/*' |
| comment, or whenever a Backslash-Newline appears in a `//' comment. |
| |
| `-Wall' |
| Requests both `-Wtrigraphs' and `-Wcomment' (but not |
| `-Wtraditional' or `-Wundef'). |
| |
| `-Wtraditional' |
| Warn about certain constructs that behave differently in |
| traditional and ANSI C. |
| |
| `-Wundef' |
| Warn if an undefined identifier is evaluated in an `#if' directive. |
| |
| `-I DIRECTORY' |
| Add the directory DIRECTORY to the head of the list of directories |
| to be searched for header files (*note Include Syntax::.). This |
| can be used to override a system header file, substituting your |
| own version, since these directories are searched before the system |
| header file directories. If you use more than one `-I' option, |
| the directories are scanned in left-to-right order; the standard |
| system directories come after. |
| |
| `-I-' |
| Any directories specified with `-I' options before the `-I-' |
| option are searched only for the case of `#include "FILE"'; they |
| are not searched for `#include <FILE>'. |
| |
| If additional directories are specified with `-I' options after |
| the `-I-', these directories are searched for all `#include' |
| directives. |
| |
| In addition, the `-I-' option inhibits the use of the current |
| directory as the first search directory for `#include "FILE"'. |
| Therefore, the current directory is searched only if it is |
| requested explicitly with `-I.'. Specifying both `-I-' and `-I.' |
| allows you to control precisely which directories are searched |
| before the current one and which are searched after. |
| |
| `-nostdinc' |
| Do not search the standard system directories for header files. |
| Only the directories you have specified with `-I' options (and the |
| current directory, 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 libg++.) |
| |
| `-remap' |
| When searching for a header file in a directory, remap file names |
| if a file named `header.gcc' exists in that directory. This can |
| be used to work around limitations of file systems with file name |
| restrictions. The `header.gcc' file should contain a series of |
| lines with two tokens on each line: the first token is the name to |
| map, and the second token is the actual name to use. |
| |
| `-D NAME' |
| Predefine NAME as a macro, with definition `1'. |
| |
| `-D NAME=DEFINITION' |
| Predefine NAME as a macro, with definition DEFINITION. There are |
| no restrictions on the contents of DEFINITION, but 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 |
| use more than one `-D' for the same NAME, the rightmost definition |
| takes effect. |
| |
| `-U NAME' |
| Do not predefine NAME. If both `-U' and `-D' are specified for |
| one name, the `-U' beats the `-D' and the name is not predefined. |
| |
| `-undef' |
| Do not predefine any nonstandard macros. |
| |
| `-A PREDICATE(ANSWER)' |
| Make an assertion with the predicate PREDICATE and answer ANSWER. |
| *Note Assertions::. |
| |
| You can use `-A-' to disable all predefined assertions; it also |
| undefines all predefined macros that identify the type of target |
| system. |
| |
| `-dM' |
| Instead of outputting the result of preprocessing, output 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 the values of any predefined macros. |
| |
| `-dD' |
| Like `-dM' 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. |
| |
| `-dI' |
| Output `#include' directives in addition to the result of |
| preprocessing. |
| |
| `-M [-MG]' |
| 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. If there are many included files then the |
| rule is split into several lines using `\'-newline. |
| |
| `-MG' says to treat missing header files as generated files and |
| assume they live in the same directory as the source file. It |
| must be specified in addition to `-M'. |
| |
| This feature is used in automatic updating of makefiles. |
| |
| `-MM [-MG]' |
| Like `-M' but mention only the files included with `#include |
| "FILE"'. System header files included with `#include <FILE>' are |
| omitted. |
| |
| `-MD FILE' |
| Like `-M' but the dependency information is written to FILE. This |
| is in addition to compiling the file as specified--`-MD' does not |
| inhibit ordinary compilation the way `-M' does. |
| |
| When invoking gcc, do not specify the FILE argument. Gcc will |
| create file names made by replacing ".c" with ".d" at the end of |
| the input file names. |
| |
| In Mach, you can use the utility `md' to merge multiple dependency |
| files into a single dependency file suitable for using with the |
| `make' command. |
| |
| `-MMD FILE' |
| Like `-MD' except mention only user header files, not system |
| header files. |
| |
| `-H' |
| Print the name of each header file used, in addition to other |
| normal activities. |
| |
| `-imacros FILE' |
| Process FILE as input, discarding the resulting output, before |
| processing the regular input file. Because the output generated |
| from FILE is discarded, the only effect of `-imacros FILE' is to |
| make the macros defined in FILE available for use in the main |
| input. |
| |
| `-include FILE' |
| Process FILE as input, and include all the resulting output, |
| before processing the regular input file. |
| |
| `-idirafter DIR' |
| Add the directory DIR to the second include path. The directories |
| on the second include path are searched when a header file is not |
| found in any of the directories in the main include path (the one |
| that `-I' adds to). |
| |
| `-iprefix PREFIX' |
| Specify PREFIX as the prefix for subsequent `-iwithprefix' options. |
| |
| `-iwithprefix DIR' |
| Add a directory to the second include path. The directory's name |
| is made by concatenating PREFIX and DIR, where PREFIX was |
| specified previously with `-iprefix'. |
| |
| `-isystem DIR' |
| Add a directory to the beginning of the second include path, |
| marking it as a system directory, so that it gets the same special |
| treatment as is applied to the standard system directories. |
| |
| `-lang-c' |
| `-lang-c89' |
| `-lang-c++' |
| `-lang-objc' |
| `-lang-objc++' |
| Specify the source language. `-lang-c' is the default; it allows |
| recognition of C++ comments (comments that begin with `//' and end |
| at end of line) and hexadecimal floating-point constants, since |
| these features will most likely appear in the next C standard. |
| `-lang-c89' disables recognition of C++ comments and hexadecimal |
| floating-point constants. `-lang-c++' handles C++ comment syntax |
| and includes extra default include directories for C++. |
| `-lang-objc' enables the Objective C `#import' directive. |
| `-lang-objc++' enables both C++ and Objective C extensions. |
| |
| These options are generated by the compiler driver `gcc', but not |
| passed from the `gcc' command line unless you use the driver's |
| `-Wp' option. |
| |
| `-lint' |
| Look for commands to the program checker `lint' embedded in |
| comments, and emit them preceded by `#pragma lint'. For example, |
| the comment `/* NOTREACHED */' becomes `#pragma lint NOTREACHED'. |
| |
| This option is available only when you call `cpp' directly; `gcc' |
| will not pass it from its command line. |
| |
| `-$' |
| Forbid the use of `$' in identifiers. This was formerly required |
| for strict conformance to the C Standard before the standard was |
| corrected. |
| |
| This option is available only when you call `cpp' directly; `gcc' |
| will not pass it from its command line. |
| |
| |
| File: cpp.info, Node: Concept Index, Next: Index, Prev: Invocation, Up: Top |
| |
| Concept Index |
| ************* |
| |
| * Menu: |
| |
| * ##: Concatenation. |
| * arguments in macro definitions: Argument Macros. |
| * assertions: Assertions. |
| * assertions, undoing: Assertions. |
| * blank macro arguments: Argument Macros. |
| * cascaded macros: Cascaded Macros. |
| * commenting out code: Deleted Code. |
| * computed #include: Include Syntax. |
| * concatenation: Concatenation. |
| * conditionals: Conditionals. |
| * directives: Directives. |
| * expansion of arguments: Argument Prescan. |
| * function-like macro: Argument Macros. |
| * header file: Header Files. |
| * including just once: Once-Only. |
| * inheritance: Inheritance. |
| * invocation of the preprocessor: Invocation. |
| * line control: Combining Sources. |
| * macro argument expansion: Argument Prescan. |
| * macro body uses macro: Cascaded Macros. |
| * macros with argument: Argument Macros. |
| * manifest constant: Simple Macros. |
| * newlines in macro arguments: Newlines in Args. |
| * null directive: Other Directives. |
| * options: Invocation. |
| * output format: Output. |
| * overriding a header file: Inheritance. |
| * parentheses in macro bodies: Macro Parentheses. |
| * pitfalls of macros: Macro Pitfalls. |
| * predefined macros: Predefined. |
| * predicates: Assertions. |
| * preprocessing directives: Directives. |
| * prescan of macro arguments: Argument Prescan. |
| * problems with macros: Macro Pitfalls. |
| * redefining macros: Redefining. |
| * repeated inclusion: Once-Only. |
| * retracting assertions: Assertions. |
| * second include path: Invocation. |
| * self-reference: Self-Reference. |
| * semicolons (after macro calls): Swallow Semicolon. |
| * side effects (in macro arguments): Side Effects. |
| * simple macro: Simple Macros. |
| * space as macro argument: Argument Macros. |
| * standard predefined macros: Standard Predefined. |
| * stringification: Stringification. |
| * testing predicates: Assertions. |
| * unassert: Assertions. |
| * undefining macros: Undefining. |
| * unsafe macros: Side Effects. |
| |
| |
| File: cpp.info, Node: Index, Prev: Concept Index, Up: Top |
| |
| Index of Directives, Macros and Options |
| *************************************** |
| |
| * Menu: |
| |
| * #assert: Assertions. |
| * #cpu: Assertions. |
| * #define: Argument Macros. |
| * #elif: #elif Directive. |
| * #else: #else Directive. |
| * #error: #error Directive. |
| * #ident: Other Directives. |
| * #if: Conditional Syntax. |
| * #ifdef: Conditionals-Macros. |
| * #ifndef: Conditionals-Macros. |
| * #import: Once-Only. |
| * #include: Include Syntax. |
| * #include_next: Inheritance. |
| * #line: Combining Sources. |
| * #machine: Assertions. |
| * #pragma: Other Directives. |
| * #pragma once: Once-Only. |
| * #system: Assertions. |
| * #unassert: Assertions. |
| * #warning: #error Directive. |
| * -$: Invocation. |
| * -A: Invocation. |
| * -C: Invocation. |
| * -D: Invocation. |
| * -dD: Invocation. |
| * -dI: Invocation. |
| * -dM: Invocation. |
| * -H: Invocation. |
| * -I: Invocation. |
| * -idirafter: Invocation. |
| * -imacros: Invocation. |
| * -include: Invocation. |
| * -iprefix: Invocation. |
| * -isystem: Invocation. |
| * -iwithprefix: Invocation. |
| * -lang-c: Invocation. |
| * -lang-c++: Invocation. |
| * -lang-c89: Invocation. |
| * -lang-objc: Invocation. |
| * -lang-objc++: Invocation. |
| * -M: Invocation. |
| * -MD: Invocation. |
| * -MM: Invocation. |
| * -MMD: Invocation. |
| * -nostdinc: Invocation. |
| * -nostdinc++: Invocation. |
| * -P: Invocation. |
| * -pedantic: Invocation. |
| * -pedantic-errors: Invocation. |
| * -remap: Invocation. |
| * -traditional: Invocation. |
| * -trigraphs: Invocation. |
| * -U: Invocation. |
| * -undef: Invocation. |
| * -Wall: Invocation. |
| * -Wcomment: Invocation. |
| * -Wtraditional: Invocation. |
| * -Wtrigraphs: Invocation. |
| * -Wundef: Invocation. |
| * __BASE_FILE__: Standard Predefined. |
| * __CHAR_UNSIGNED__: Standard Predefined. |
| * __cplusplus: Standard Predefined. |
| * __DATE__: Standard Predefined. |
| * __FILE__: Standard Predefined. |
| * __GNUC__: Standard Predefined. |
| * __GNUC_MINOR__: Standard Predefined. |
| * __GNUG__: Standard Predefined. |
| * __INCLUDE_LEVEL_: Standard Predefined. |
| * __LINE__: Standard Predefined. |
| * __OPTIMIZE__: Standard Predefined. |
| * __REGISTER_PREFIX__: Standard Predefined. |
| * __STDC__: Standard Predefined. |
| * __STDC_VERSION__: Standard Predefined. |
| * __STRICT_ANSI__: Standard Predefined. |
| * __TIME__: Standard Predefined. |
| * __USER_LABEL_PREFIX__: Standard Predefined. |
| * __VERSION__: Standard Predefined. |
| * _AM29000: Nonstandard Predefined. |
| * _AM29K: Nonstandard Predefined. |
| * BSD: Nonstandard Predefined. |
| * defined: Conditionals-Macros. |
| * M68020: Nonstandard Predefined. |
| * m68k: Nonstandard Predefined. |
| * mc68000: Nonstandard Predefined. |
| * ns32000: Nonstandard Predefined. |
| * pyr: Nonstandard Predefined. |
| * sequent: Nonstandard Predefined. |
| * sun: Nonstandard Predefined. |
| * system header files: Header Uses. |
| * unix: Nonstandard Predefined. |
| * vax: Nonstandard Predefined. |
| |
| |
