![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to cpp.info-3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [GCC 2.x] / gcc|
Return to cpp.info-3 CVS log | Up to [GCC 2.x] / gcc |
1.1.1.5 ! root 1: This is Info file cpp.info, produced by Makeinfo version 1.67 from the ! 2: input file cpp.texi. 1.1 root 3: 4: This file documents the GNU C Preprocessor. 5: 1.1.1.4 root 6: Copyright 1987, 1989, 1991, 1992, 1993, 1994, 1995 Free Software 1.1.1.3 root 7: Foundation, Inc. 1.1 root 8: 9: Permission is granted to make and distribute verbatim copies of this 10: manual provided the copyright notice and this permission notice are 11: preserved on all copies. 12: 13: Permission is granted to copy and distribute modified versions of 14: this manual under the conditions for verbatim copying, provided also 15: that the entire resulting derived work is distributed under the terms 16: of a permission notice identical to this one. 17: 18: Permission is granted to copy and distribute translations of this 19: manual into another language, under the above conditions for modified 20: versions. 21: 22: 1.1.1.3 root 23: File: cpp.info, Node: Invocation, Next: Concept Index, Prev: Output, Up: Top 24: 25: Invoking the C Preprocessor 26: =========================== 27: 28: Most often when you use the C preprocessor you will not have to 29: invoke it explicitly: the C compiler will do so automatically. 30: However, the preprocessor is sometimes useful on its own. 31: 32: The C preprocessor expects two file names as arguments, INFILE and 33: OUTFILE. The preprocessor reads INFILE together with any other files 34: it specifies with `#include'. All the output generated by the combined 35: input files is written in OUTFILE. 36: 37: Either INFILE or OUTFILE may be `-', which as INFILE means to read 38: from standard input and as OUTFILE means to write to standard output. 39: Also, if OUTFILE or both file names are omitted, the standard output 40: and standard input are used for the omitted file names. 41: 42: Here is a table of command options accepted by the C preprocessor. 43: These options can also be given when compiling a C program; they are 44: passed along automatically to the preprocessor when it is invoked by the 45: compiler. 46: 47: `-P' 48: Inhibit generation of `#'-lines with line-number information in 49: the output from the preprocessor (*note Output::.). This might be 50: useful when running the preprocessor on something that is not C 51: code and will be sent to a program which might be confused by the 52: `#'-lines. 53: 54: `-C' 55: Do not discard comments: pass them through to the output file. 56: Comments appearing in arguments of a macro call will be copied to 57: the output before the expansion of the macro call. 58: 59: `-traditional' 60: Try to imitate the behavior of old-fashioned C, as opposed to ANSI 61: C. 62: 63: * Traditional macro expansion pays no attention to singlequote 64: or doublequote characters; macro argument symbols are 65: replaced by the argument values even when they appear within 66: apparent string or character constants. 67: 68: * Traditionally, it is permissible for a macro expansion to end 69: in the middle of a string or character constant. The 70: constant continues into the text surrounding the macro call. 71: 72: * However, traditionally the end of the line terminates a 73: string or character constant, with no error. 74: 75: * In traditional C, a comment is equivalent to no text at all. 76: (In ANSI C, a comment counts as whitespace.) 77: 78: * Traditional C does not have the concept of a "preprocessing 79: number". It considers `1.0e+4' to be three tokens: `1.0e', 80: `+', and `4'. 81: 82: * A macro is not suppressed within its own definition, in 83: traditional C. Thus, any macro that is used recursively 84: inevitably causes an error. 85: 86: * The character `#' has no special meaning within a macro 87: definition in traditional C. 88: 89: * In traditional C, the text at the end of a macro expansion 90: can run together with the text after the macro call, to 91: produce a single token. (This is impossible in ANSI C.) 92: 93: * Traditionally, `\' inside a macro argument suppresses the 94: syntactic significance of the following character. 95: 96: `-trigraphs' 97: Process ANSI standard trigraph sequences. These are 98: three-character sequences, all starting with `??', that are 99: defined by ANSI C to stand for single characters. For example, 100: `??/' stands for `\', so `'??/n'' is a character constant for a 101: newline. Strictly speaking, the GNU C preprocessor does not 102: support all programs in ANSI Standard C unless `-trigraphs' is 103: used, but if you ever notice the difference it will be with relief. 104: 105: You don't want to know any more about trigraphs. 106: 107: `-pedantic' 108: Issue warnings required by the ANSI C standard in certain cases 109: such as when text other than a comment follows `#else' or `#endif'. 110: 111: `-pedantic-errors' 112: Like `-pedantic', except that errors are produced rather than 113: warnings. 114: 115: `-Wtrigraphs' 116: Warn if any trigraphs are encountered (assuming they are enabled). 117: 118: `-Wcomment' 119: Warn whenever a comment-start sequence `/*' appears in a comment. 120: 121: `-Wall' 122: Requests both `-Wtrigraphs' and `-Wcomment' (but not 123: `-Wtraditional'). 124: 125: `-Wtraditional' 126: Warn about certain constructs that behave differently in 127: traditional and ANSI C. 128: 129: `-I DIRECTORY' 1.1.1.4 root 130: Add the directory DIRECTORY to the head of the list of directories 1.1.1.3 root 131: to be searched for header files (*note Include Syntax::.). This 132: can be used to override a system header file, substituting your 133: own version, since these directories are searched before the system 134: header file directories. If you use more than one `-I' option, 135: the directories are scanned in left-to-right order; the standard 136: system directories come after. 137: 138: `-I-' 139: Any directories specified with `-I' options before the `-I-' 140: option are searched only for the case of `#include "FILE"'; they 141: are not searched for `#include <FILE>'. 142: 143: If additional directories are specified with `-I' options after 144: the `-I-', these directories are searched for all `#include' 1.1.1.4 root 145: directives. 1.1.1.3 root 146: 147: In addition, the `-I-' option inhibits the use of the current 148: directory as the first search directory for `#include "FILE"'. 149: Therefore, the current directory is searched only if it is 150: requested explicitly with `-I.'. Specifying both `-I-' and `-I.' 151: allows you to control precisely which directories are searched 152: before the current one and which are searched after. 153: 154: `-nostdinc' 155: Do not search the standard system directories for header files. 156: Only the directories you have specified with `-I' options (and the 157: current directory, if appropriate) are searched. 158: 159: `-nostdinc++' 160: Do not search for header files in the C++-specific standard 161: directories, but do still search the other standard directories. 162: (This option is used when building libg++.) 163: 164: `-D NAME' 165: Predefine NAME as a macro, with definition `1'. 166: 167: `-D NAME=DEFINITION' 168: Predefine NAME as a macro, with definition DEFINITION. There are 169: no restrictions on the contents of DEFINITION, but if you are 170: invoking the preprocessor from a shell or shell-like program you 171: may need to use the shell's quoting syntax to protect characters 172: such as spaces that have a meaning in the shell syntax. If you 173: use more than one `-D' for the same NAME, the rightmost definition 174: takes effect. 175: 176: `-U NAME' 177: Do not predefine NAME. If both `-U' and `-D' are specified for 178: one name, the `-U' beats the `-D' and the name is not predefined. 179: 180: `-undef' 181: Do not predefine any nonstandard macros. 182: 183: `-A PREDICATE(ANSWER)' 184: Make an assertion with the predicate PREDICATE and answer ANSWER. 185: *Note Assertions::. 186: 187: You can use `-A-' to disable all predefined assertions; it also 188: undefines all predefined macros that identify the type of target 189: system. 190: 191: `-dM' 192: Instead of outputting the result of preprocessing, output a list of 1.1.1.4 root 193: `#define' directives for all the macros defined during the 194: execution of the preprocessor, including predefined macros. This 195: gives you a way of finding out what is predefined in your version 196: of the preprocessor; assuming you have no file `foo.h', the command 1.1.1.3 root 197: 198: touch foo.h; cpp -dM foo.h 199: 200: will show the values of any predefined macros. 201: 202: `-dD' 203: Like `-dM' except in two respects: it does *not* include the 1.1.1.4 root 204: predefined macros, and it outputs *both* the `#define' directives 1.1.1.3 root 205: and the result of preprocessing. Both kinds of output go to the 206: standard output file. 207: 208: `-M [-MG]' 209: Instead of outputting the result of preprocessing, output a rule 210: suitable for `make' describing the dependencies of the main source 211: file. The preprocessor outputs one `make' rule containing the 212: object file name for that source file, a colon, and the names of 213: all the included files. If there are many included files then the 214: rule is split into several lines using `\'-newline. 215: 216: `-MG' says to treat missing header files as generated files and 217: assume they live in the same directory as the source file. It 218: must be specified in addition to `-M'. 219: 220: This feature is used in automatic updating of makefiles. 221: 222: `-MM [-MG]' 223: Like `-M' but mention only the files included with `#include 224: "FILE"'. System header files included with `#include <FILE>' are 225: omitted. 226: 227: `-MD FILE' 228: Like `-M' but the dependency information is written to FILE. This 229: is in addition to compiling the file as specified--`-MD' does not 230: inhibit ordinary compilation the way `-M' does. 231: 232: When invoking gcc, do not specify the FILE argument. Gcc will 233: create file names made by replacing ".c" with ".d" at the end of 234: the input file names. 235: 236: In Mach, you can use the utility `md' to merge multiple dependency 237: files into a single dependency file suitable for using with the 238: `make' command. 239: 240: `-MMD FILE' 241: Like `-MD' except mention only user header files, not system 242: header files. 243: 244: `-H' 245: Print the name of each header file used, in addition to other 246: normal activities. 247: 248: `-imacros FILE' 249: Process FILE as input, discarding the resulting output, before 250: processing the regular input file. Because the output generated 251: from FILE is discarded, the only effect of `-imacros FILE' is to 252: make the macros defined in FILE available for use in the main 253: input. 254: 255: `-include FILE' 256: Process FILE as input, and include all the resulting output, 257: before processing the regular input file. 258: 259: `-idirafter DIR' 260: Add the directory DIR to the second include path. The directories 261: on the second include path are searched when a header file is not 262: found in any of the directories in the main include path (the one 263: that `-I' adds to). 264: 265: `-iprefix PREFIX' 266: Specify PREFIX as the prefix for subsequent `-iwithprefix' options. 267: 268: `-iwithprefix DIR' 269: Add a directory to the second include path. The directory's name 270: is made by concatenating PREFIX and DIR, where PREFIX was 271: specified previously with `-iprefix'. 272: 273: `-isystem DIR' 274: Add a directory to the beginning of the second include path, 275: marking it as a system directory, so that it gets the same special 276: treatment as is applied to the standard system directories. 277: 278: `-lang-c' 1.1.1.4 root 279: `-lang-c89' 1.1.1.3 root 280: `-lang-c++' 281: `-lang-objc' 282: `-lang-objc++' 1.1.1.4 root 283: Specify the source language. `-lang-c' is the default; it allows 284: recognition of C++ comments (comments that begin with `//' and end 285: at end of line), since this is a common feature and it will most 286: likely be in the next C standard. `-lang-c89' disables 287: recognition of C++ comments. `-lang-c++' handles C++ comment 288: syntax and includes extra default include directories for C++. 289: `-lang-objc' enables the Objective C `#import' directive. 290: `-lang-objc++' enables both C++ and Objective C extensions. 1.1.1.3 root 291: 292: These options are generated by the compiler driver `gcc', but not 1.1.1.4 root 293: passed from the `gcc' command line unless you use the driver's 294: `-Wp' option. 1.1.1.3 root 295: 296: `-lint' 297: Look for commands to the program checker `lint' embedded in 298: comments, and emit them preceded by `#pragma lint'. For example, 299: the comment `/* NOTREACHED */' becomes `#pragma lint NOTREACHED'. 300: 301: This option is available only when you call `cpp' directly; `gcc' 302: will not pass it from its command line. 303: 304: `-$' 305: Forbid the use of `$' in identifiers. This is required for ANSI 306: conformance. `gcc' automatically supplies this option to the 307: preprocessor if you specify `-ansi', but `gcc' doesn't recognize 308: the `-$' option itself--to use it without the other effects of 309: `-ansi', you must call the preprocessor directly. 310: 311: 312: File: cpp.info, Node: Concept Index, Next: Index, Prev: Invocation, Up: Top 313: 314: Concept Index 315: ************* 316: 317: * Menu: 318: 1.1.1.5 ! root 319: * ##: Concatenation. ! 320: * arguments in macro definitions: Argument Macros. ! 321: * assertions: Assertions. ! 322: * assertions, undoing: Assertions. ! 323: * blank macro arguments: Argument Macros. ! 324: * cascaded macros: Cascaded Macros. ! 325: * commenting out code: Deleted Code. ! 326: * computed #include: Include Syntax. ! 327: * concatenation: Concatenation. ! 328: * conditionals: Conditionals. ! 329: * directives: Directives. ! 330: * expansion of arguments: Argument Prescan. ! 331: * function-like macro: Argument Macros. ! 332: * header file: Header Files. ! 333: * including just once: Once-Only. ! 334: * inheritance: Inheritance. ! 335: * invocation of the preprocessor: Invocation. ! 336: * line control: Combining Sources. ! 337: * macro argument expansion: Argument Prescan. ! 338: * macro body uses macro: Cascaded Macros. ! 339: * macros with argument: Argument Macros. ! 340: * manifest constant: Simple Macros. ! 341: * newlines in macro arguments: Newlines in Args. ! 342: * null directive: Other Directives. ! 343: * options: Invocation. ! 344: * output format: Output. ! 345: * overriding a header file: Inheritance. ! 346: * parentheses in macro bodies: Macro Parentheses. ! 347: * pitfalls of macros: Macro Pitfalls. ! 348: * predefined macros: Predefined. ! 349: * predicates: Assertions. ! 350: * preprocessing directives: Directives. ! 351: * prescan of macro arguments: Argument Prescan. ! 352: * problems with macros: Macro Pitfalls. ! 353: * redefining macros: Redefining. ! 354: * repeated inclusion: Once-Only. ! 355: * retracting assertions: Assertions. ! 356: * second include path: Invocation. ! 357: * self-reference: Self-Reference. ! 358: * semicolons (after macro calls): Swallow Semicolon. ! 359: * side effects (in macro arguments): Side Effects. ! 360: * simple macro: Simple Macros. ! 361: * space as macro argument: Argument Macros. ! 362: * standard predefined macros: Standard Predefined. ! 363: * stringification: Stringification. ! 364: * testing predicates: Assertions. ! 365: * unassert: Assertions. ! 366: * undefining macros: Undefining. ! 367: * unsafe macros: Side Effects. 1.1.1.3 root 368: 369: 1.1 root 370: File: cpp.info, Node: Index, Prev: Concept Index, Up: Top 371: 1.1.1.4 root 372: Index of Directives, Macros and Options 373: *************************************** 1.1 root 374: 375: * Menu: 376: 1.1.1.5 ! root 377: * #assert: Assertions. ! 378: * #cpu: Assertions. ! 379: * #define: Argument Macros. ! 380: * #elif: #elif Directive. ! 381: * #else: #else Directive. ! 382: * #error: #error Directive. ! 383: * #ident: Other Directives. ! 384: * #if: Conditional Syntax. ! 385: * #ifdef: Conditionals-Macros. ! 386: * #ifndef: Conditionals-Macros. ! 387: * #import: Once-Only. ! 388: * #include: Include Syntax. ! 389: * #include_next: Inheritance. ! 390: * #line: Combining Sources. ! 391: * #machine: Assertions. ! 392: * #pragma: Other Directives. ! 393: * #pragma once: Once-Only. ! 394: * #system: Assertions. ! 395: * #unassert: Assertions. ! 396: * #warning: #error Directive. ! 397: * -$: Invocation. ! 398: * -A: Invocation. ! 399: * -C: Invocation. ! 400: * -D: Invocation. ! 401: * -dD: Invocation. ! 402: * -dM: Invocation. ! 403: * -H: Invocation. ! 404: * -I: Invocation. ! 405: * -idirafter: Invocation. ! 406: * -imacros: Invocation. ! 407: * -include: Invocation. ! 408: * -iprefix: Invocation. ! 409: * -isystem: Invocation. ! 410: * -iwithprefix: Invocation. ! 411: * -lang-c: Invocation. ! 412: * -lang-c++: Invocation. ! 413: * -lang-c89: Invocation. ! 414: * -lang-objc: Invocation. ! 415: * -lang-objc++: Invocation. ! 416: * -M: Invocation. ! 417: * -MD: Invocation. ! 418: * -MM: Invocation. ! 419: * -MMD: Invocation. ! 420: * -nostdinc: Invocation. ! 421: * -nostdinc++: Invocation. ! 422: * -P: Invocation. ! 423: * -pedantic: Invocation. ! 424: * -pedantic-errors: Invocation. ! 425: * -traditional: Invocation. ! 426: * -trigraphs: Invocation. ! 427: * -U: Invocation. ! 428: * -undef: Invocation. ! 429: * -Wall: Invocation. ! 430: * -Wcomment: Invocation. ! 431: * -Wtraditional: Invocation. ! 432: * -Wtrigraphs: Invocation. ! 433: * __BASE_FILE__: Standard Predefined. ! 434: * __CHAR_UNSIGNED__: Standard Predefined. ! 435: * __cplusplus: Standard Predefined. ! 436: * __DATE__: Standard Predefined. ! 437: * __FILE__: Standard Predefined. ! 438: * __GNUC__: Standard Predefined. ! 439: * __GNUC_MINOR__: Standard Predefined. ! 440: * __GNUG__: Standard Predefined. ! 441: * __INCLUDE_LEVEL_: Standard Predefined. ! 442: * __LINE__: Standard Predefined. ! 443: * __OPTIMIZE__: Standard Predefined. ! 444: * __REGISTER_PREFIX__: Standard Predefined. ! 445: * __STDC__: Standard Predefined. ! 446: * __STDC_VERSION__: Standard Predefined. ! 447: * __STRICT_ANSI__: Standard Predefined. ! 448: * __TIME__: Standard Predefined. ! 449: * __USER_LABEL_PREFIX__: Standard Predefined. ! 450: * __VERSION__: Standard Predefined. ! 451: * _AM29000: Nonstandard Predefined. ! 452: * _AM29K: Nonstandard Predefined. ! 453: * BSD: Nonstandard Predefined. ! 454: * defined: Conditionals-Macros. ! 455: * M68020: Nonstandard Predefined. ! 456: * m68k: Nonstandard Predefined. ! 457: * mc68000: Nonstandard Predefined. ! 458: * ns32000: Nonstandard Predefined. ! 459: * pyr: Nonstandard Predefined. ! 460: * sequent: Nonstandard Predefined. ! 461: * sun: Nonstandard Predefined. ! 462: * system header files: Header Uses. ! 463: * unix: Nonstandard Predefined. ! 464: * vax: Nonstandard Predefined. 1.1 root 465: 466:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.