![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to cccp.1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [GCC 2.x] / gcc|
Return to cccp.1 CVS log | Up to [GCC 2.x] / gcc |
1.1.1.2 ! root 1: .\" Copyright (c) 1991, 1992 Free Software Foundation \-*-Text-*- 1.1 root 2: .\" See section COPYING for conditions for redistribution 3: .TH cpp 1 "2Jan1992" "GNU Tools" "GNU Tools" 4: .SH NAME 1.1.1.2 ! root 5: cccp, cpp \- The GNU C-Compatible Compiler Preprocessor. 1.1 root 6: .SH SYNOPSIS 7: .hy 0 8: .na 9: .TP 10: .B cccp 11: .RB "[\|" \-$ "\|]" 12: .RB "[\|" \-C "\|]" 13: .RB "[\|" \-D \c 14: .I name\c 15: .RB [ =\c 16: .I definition\c 17: \&]\|] 18: .RB "[\|" \-dD "\|]" 19: .RB "[\|" \-dM "\|]" 20: .RB "[\|" "\-I\ "\c 21: .I directory\c 22: \&\|] 23: .RB "[\|" \-H "\|]" 24: .RB "[\|" \-I\- "\|]" 25: .RB "[\|" "\-imacros\ "\c 26: .I file\c 27: \&\|] 28: .RB "[\|" "\-include\ "\c 29: .I file\c 30: \&\|] 31: .RB "[\|" \-lang\-c "\|]" 32: .RB "[\|" \-lang\-c++ "\|]" 33: .RB "[\|" \-lang\-objc "\|]" 34: .RB "[\|" \-lang\-objc++ "\|]" 35: .RB "[\|" \-lint "\|]" 36: .RB "[\|" \-M "\|]" 37: .RB "[\|" \-MD "\|]" 38: .RB "[\|" \-MM "\|]" 39: .RB "[\|" \-MMD "\|]" 40: .RB "[\|" \-nostdinc "\|]" 41: .RB "[\|" \-P "\|]" 42: .RB "[\|" \-pedantic "\|]" 43: .RB "[\|" \-pedantic\-errors "\|]" 44: .RB "[\|" \-trigraphs "\|]" 45: .RB "[\|" \-U \c 46: .I name\c 47: \&\|] 48: .RB "[\|" \-undef "\|]" 49: .RB "[\|" \-Wtrigraphs "\|]" 50: .RB "[\|" \-Wcomment "\|]" 51: .RB "[\|" \-Wall "\|]" 52: .RB "[\|" \-Wtraditional "\|]" 53: .br 54: .RB "[\|" \c 55: .I infile\c 56: .RB | \- "\|]" 57: .RB "[\|" \c 58: .I outfile\c 59: .RB | \- "\|]" 60: .ad b 61: .hy 1 62: .SH DESCRIPTION 63: The C preprocessor is a \c 64: .I macro processor\c 65: \& that is used automatically by 66: the C compiler to transform your program before actual compilation. It is 67: called a macro processor because it allows you to define \c 68: .I macros\c 69: \&, 70: which are brief abbreviations for longer constructs. 71: 72: The C preprocessor provides four separate facilities that you can use as 73: you see fit: 74: .TP 75: \(bu 76: Inclusion of header files. These are files of declarations that can be 77: substituted into your program. 78: .TP 79: \(bu 80: Macro expansion. You can define \c 81: .I macros\c 82: \&, which are abbreviations 83: for arbitrary fragments of C code, and then the C preprocessor will 84: replace the macros with their definitions throughout the program. 85: .TP 86: \(bu 87: Conditional compilation. Using special preprocessor commands, you 88: can include or exclude parts of the program according to various 89: conditions. 90: .TP 91: \(bu 92: Line control. If you use a program to combine or rearrange source files into 93: an intermediate file which is then compiled, you can use line control 94: to inform the compiler of where each source line originally came from. 95: .PP 96: C preprocessors vary in some details. For a full explanation of the 97: GNU C preprocessor, see the 98: .B info 99: file `\|\c 100: .B cpp.info\c 101: \&\|', or the manual 102: .I The C Preprocessor\c 103: \&. Both of these are built from the same documentation source file, `\|\c 104: .B cpp.texinfo\c 105: \&\|'. The GNU C 106: preprocessor provides a superset of the features of ANSI Standard C. 107: 108: ANSI Standard C requires the rejection of many harmless constructs commonly 109: used by today's C programs. Such incompatibility would be inconvenient for 110: users, so the GNU C preprocessor is configured to accept these constructs 111: by default. Strictly speaking, to get ANSI Standard C, you must use the 112: options `\|\c 113: .B \-trigraphs\c 114: \&\|', `\|\c 115: .B \-undef\c 116: \&\|' and `\|\c 117: .B \-pedantic\c 118: \&\|', but in 119: practice the consequences of having strict ANSI Standard C make it 120: undesirable to do this. 121: 122: Most often when you use the C preprocessor you will not have to invoke it 123: explicitly: the C compiler will do so automatically. However, the 124: preprocessor is sometimes useful individually. 125: 126: When you call the preprocessor individually, either name 127: (\c 128: .B cpp\c 129: \& or \c 130: .B cccp\c 131: \&) will do\(em\&they are completely synonymous. 132: 133: The C preprocessor expects two file names as arguments, \c 134: .I infile\c 135: \& and 136: \c 137: .I outfile\c 138: \&. The preprocessor reads \c 139: .I infile\c 140: \& together with any other 141: files it specifies with `\|\c 142: .B #include\c 143: \&\|'. All the output generated by the 144: combined input files is written in \c 145: .I outfile\c 146: \&. 147: 148: Either \c 149: .I infile\c 150: \& or \c 151: .I outfile\c 152: \& may be `\|\c 153: .B \-\c 154: \&\|', which as \c 155: .I infile\c 156: \& 157: means to read from standard input and as \c 158: .I outfile\c 159: \& means to write to 160: standard output. Also, if \c 161: .I outfile\c 162: \& or both file names are omitted, 163: the standard output and standard input are used for the omitted file names. 164: .SH OPTIONS 165: Here is a table of command options accepted by the C preprocessor. 166: These options can also be given when compiling a C program; they are 167: passed along automatically to the preprocessor when it is invoked by 168: the compiler. 169: .TP 170: .B \-P 171: Inhibit generation of `\|\c 172: .B #\c 173: \&\|'-lines with line-number information in 174: the output from the preprocessor. This might be 175: useful when running the preprocessor on something that is not C code 176: and will be sent to a program which might be confused by the 177: `\|\c 178: .B #\c 179: \&\|'-lines. 180: .TP 181: .B \-C 182: Do not discard comments: pass them through to the output file. 183: Comments appearing in arguments of a macro call will be copied to the 184: output before the expansion of the macro call. 185: .TP 186: .B \-trigraphs 187: Process ANSI standard trigraph sequences. These are three-character 188: sequences, all starting with `\|\c 189: .B ??\c 190: \&\|', that are defined by ANSI C to 191: stand for single characters. For example, `\|\c 192: .B ??/\c 193: \&\|' stands for 194: `\|\c 195: .BR "\e" "\|'," 196: so `\|\c 197: .B '??/n'\c 198: \&\|' is a character constant for a newline. 199: Strictly speaking, the GNU C preprocessor does not support all 200: programs in ANSI Standard C unless `\|\c 201: .B \-trigraphs\c 202: \&\|' is used, but if 203: you ever notice the difference it will be with relief. 204: 205: You don't want to know any more about trigraphs. 206: .TP 207: .B \-pedantic 208: Issue warnings required by the ANSI C standard in certain cases such 209: as when text other than a comment follows `\|\c 210: .B #else\c 211: \&\|' or `\|\c 212: .B #endif\c 213: \&\|'. 214: .TP 215: .B \-pedantic\-errors 216: Like `\|\c 217: .B \-pedantic\c 218: \&\|', except that errors are produced rather than 219: warnings. 220: .TP 221: .B \-Wtrigraphs 222: Warn if any trigraphs are encountered (assuming they are enabled). 223: .TP 224: .B \-Wcomment 225: .TP 226: .B \-Wcomments 227: Warn whenever a comment-start sequence `\|\c 228: .B /*\c 229: \&\|' appears in a comment. 230: (Both forms have the same effect). 231: .TP 232: .B \-Wall 233: Requests both `\|\c 234: .B \-Wtrigraphs\c 235: \&\|' and `\|\c 236: .B \-Wcomment\c 237: \&\|' (but not 238: `\|\c 239: .B \-Wtraditional\c 240: \&\|'). 241: .TP 242: .B \-Wtraditional 243: Warn about certain constructs that behave differently in traditional and 244: ANSI C. 245: .TP 246: .BI "\-I " directory\c 247: \& 248: Add the directory \c 249: .I directory\c 250: \& to the end of the list of 251: directories to be searched for header files. 252: This can be used to override a system header file, substituting your 253: own version, since these directories are searched before the system 254: header file directories. If you use more than one `\|\c 255: .B \-I\c 256: \&\|' option, 257: the directories are scanned in left-to-right order; the standard 258: system directories come after. 259: .TP 260: .B \-I\- 261: Any directories specified with `\|\c 262: .B \-I\c 263: \&\|' options before the `\|\c 264: .B \-I\-\c 265: \&\|' 266: option are searched only for the case of `\|\c 267: .B #include "\c 268: .I file\c 269: \&"\c 270: \&\|'; 271: they are not searched for `\|\c 272: .B #include <\c 273: .I file\c 274: \&>\c 275: \&\|'. 276: 277: If additional directories are specified with `\|\c 278: .B \-I\c 279: \&\|' options after 280: the `\|\c 281: .B \-I\-\c 282: \&\|', these directories are searched for all `\|\c 283: .B #include\c 284: \&\|' 285: directives. 286: 287: In addition, the `\|\c 288: .B \-I\-\c 289: \&\|' option inhibits the use of the current 290: directory as the first search directory for `\|\c 291: .B #include "\c 292: .I file\c 293: \&"\c 294: \&\|'. 295: Therefore, the current directory is searched only if it is requested 296: explicitly with `\|\c 297: .B \-I.\c 298: \&\|'. Specifying both `\|\c 299: .B \-I\-\c 300: \&\|' and `\|\c 301: .B \-I.\c 302: \&\|' 303: allows you to control precisely which directories are searched before 304: the current one and which are searched after. 305: .TP 306: .B \-nostdinc 307: Do not search the standard system directories for header files. 308: Only the directories you have specified with `\|\c 309: .B \-I\c 310: \&\|' options 311: (and the current directory, if appropriate) are searched. 312: .TP 313: .BI "\-D " "name"\c 314: \& 315: Predefine \c 316: .I name\c 317: \& as a macro, with definition `\|\c 318: .B 1\c 319: \&\|'. 320: .TP 321: .BI "\-D " "name" = definition 322: \& 323: Predefine \c 324: .I name\c 325: \& as a macro, with definition \c 326: .I definition\c 327: \&. 328: There are no restrictions on the contents of \c 329: .I definition\c 330: \&, but if 331: you are invoking the preprocessor from a shell or shell-like program 332: you may need to use the shell's quoting syntax to protect characters 333: such as spaces that have a meaning in the shell syntax. If you use more than 334: one `\|\c 335: .B \-D\c 336: \&\|' for the same 337: .I name\c 338: \&, the rightmost definition takes effect. 339: .TP 340: .BI "\-U " "name"\c 341: \& 342: Do not predefine \c 343: .I name\c 344: \&. If both `\|\c 345: .B \-U\c 346: \&\|' and `\|\c 347: .B \-D\c 348: \&\|' are 349: specified for one name, the `\|\c 350: .B \-U\c 351: \&\|' beats the `\|\c 352: .B \-D\c 353: \&\|' and the name 354: is not predefined. 355: .TP 356: .B \-undef 357: Do not predefine any nonstandard macros. 358: .TP 359: .B \-dM 360: Instead of outputting the result of preprocessing, output a list of 361: `\|\c 362: .B #define\c 363: \&\|' commands for all the macros defined during the 364: execution of the preprocessor, including predefined macros. This gives 365: you a way of finding out what is predefined in your version of the 366: preprocessor; assuming you have no file `\|\c 367: .B foo.h\c 368: \&\|', the command 369: .sp 370: .br 371: touch\ foo.h;\ cpp\ \-dM\ foo.h 372: .br 373: .sp 374: will show the values of any predefined macros. 375: .TP 376: .B \-dD 377: Like `\|\c 378: .B \-dM\c 379: \&\|' except in two respects: it does \c 380: .I not\c 381: \& include the 382: predefined macros, and it outputs \c 383: .I both\c 384: \& the `\|\c 385: .B #define\c 386: \&\|' 387: commands and the result of preprocessing. Both kinds of output go to 388: the standard output file. 389: .PP 390: .TP 391: .B \-M 392: Instead of outputting the result of preprocessing, output a rule 393: suitable for \c 394: .B make\c 395: \& describing the dependencies of the main 396: source file. The preprocessor outputs one \c 397: .B make\c 398: \& rule containing 399: the object file name for that source file, a colon, and the names of 400: all the included files. If there are many included files then the 401: rule is split into several lines using `\|\c 402: .B \\c 403: \&\|'-newline. 404: 405: This feature is used in automatic updating of makefiles. 406: .TP 407: .B \-MM 408: Like `\|\c 409: .B \-M\c 410: \&\|' but mention only the files included with `\|\c 411: .B #include 412: "\c 413: .I file\c 414: \&"\c 415: \&\|'. System header files included with `\|\c 416: .B #include 417: <\c 418: .I file\c 419: \&>\c 420: \&\|' are omitted. 421: .TP 422: .B \-MD 423: Like `\|\c 424: .B \-M\c 425: \&\|' but the dependency information is written to files with 426: names made by replacing `\|\c 427: .B .c\c 428: \&\|' with `\|\c 429: .B .d\c 430: \&\|' at the end of the 431: input file names. This is in addition to compiling the file as 432: specified\(em\&`\|\c 433: .B \-MD\c 434: \&\|' does not inhibit ordinary compilation the way 435: `\|\c 436: .B \-M\c 437: \&\|' does. 438: 439: In Mach, you can use the utility \c 440: .B md\c 441: \& to merge the `\|\c 442: .B .d\c 443: \&\|' files 444: into a single dependency file suitable for using with the `\|\c 445: .B make\c 446: \&\|' 447: command. 448: .TP 449: .B \-MMD 450: Like `\|\c 451: .B \-MD\c 452: \&\|' except mention only user header files, not system 453: header files. 454: .TP 455: .B \-H 456: Print the name of each header file used, in addition to other normal 457: activities. 458: .TP 459: .BI "\-imacros " "file"\c 460: \& 461: Process \c 462: .I file\c 463: \& as input, discarding the resulting output, before 464: processing the regular input file. Because the output generated from 465: \c 466: .I file\c 467: \& is discarded, the only effect of `\|\c 468: .B \-imacros \c 469: .I file\c 470: \&\c 471: \&\|' is to 472: make the macros defined in \c 473: .I file\c 474: \& available for use in the main 475: input. The preprocessor evaluates any `\|\c 476: .B \-D\c 477: \&\|' and `\|\c 478: .B \-U\c 479: \&\|' options 480: on the command line before processing `\|\c 481: .B \-imacros \c 482: .I file\c 483: \&\|' \c 484: \&. 485: .TP 486: .BI "\-include " "file" 487: Process 488: .I file 489: as input, and include all the resulting output, 490: before processing the regular input file. 491: .TP 492: .B \-lang-c 493: .TP 494: .B \-lang-c++ 495: .TP 496: .B \-lang-objc 497: .TP 498: .B \-lang-objc++ 499: Specify the source language. `\|\c 500: .B \-lang-c++\c 501: \&\|' makes the preprocessor 502: handle C++ comment syntax, and includes extra default include 503: directories for C++, and `\|\c 504: .B \-lang-objc\c 505: \&\|' enables the Objective C 506: `\|\c 507: .B #import\c 508: \&\|' directive. `\|\c 509: .B \-lang-c\c 510: \&\|' explicitly turns off both of 511: these extensions, and `\|\c 512: .B \-lang-objc++\c 513: \&\|' enables both. 514: 515: These options are generated by the compiler driver \c 516: .B gcc\c 517: \&, but not 518: passed from the `\|\c 519: .B gcc\c 520: \&\|' command line. 521: .TP 522: .B \-lint 523: Look for commands to the program checker \c 524: .B lint\c 525: \& embedded in 526: comments, and emit them preceded by `\|\c 527: .B #pragma lint\c 528: \&\|'. For example, 529: the comment `\|\c 530: .B /* NOTREACHED */\c 531: \&\|' becomes `\|\c 532: .B #pragma lint 533: NOTREACHED\c 534: \&\|'. 535: 536: This option is available only when you call \c 537: .B cpp\c 538: \& directly; 539: \c 540: .B gcc\c 541: \& will not pass it from its command line. 542: .TP 543: .B \-$ 544: Forbid the use of `\|\c 545: .B $\c 546: \&\|' in identifiers. This is required for ANSI 547: conformance. \c 548: .B gcc\c 549: \& automatically supplies this option to the 550: preprocessor if you specify `\|\c 551: .B \-ansi\c 552: \&\|', but \c 553: .B gcc\c 554: \& doesn't 555: recognize the `\|\c 556: .B \-$\c 557: \&\|' option itself\(em\&to use it without the other 558: effects of `\|\c 559: .B \-ansi\c 560: \&\|', you must call the preprocessor directly. 561: .SH "SEE ALSO" 562: .RB "`\|" Cpp "\|'" 563: entry in 564: .B info\c 565: \&; 566: .I The C Preprocessor\c 1.1.1.2 ! root 567: , Richard M. Stallman. 1.1 root 568: .br 569: .BR gcc "(" 1 ");" 570: .RB "`\|" Gcc "\|'" 571: entry in 572: .B info\c 573: \&; 574: .I 575: Using and Porting GNU CC (for version 2.0)\c 1.1.1.2 ! root 576: , Richard M. Stallman. 1.1 root 577: .SH COPYING 1.1.1.2 ! root 578: Copyright (c) 1991, 1992 Free Software Foundation, Inc. 1.1 root 579: .PP 580: Permission is granted to make and distribute verbatim copies of 581: this manual provided the copyright notice and this permission notice 582: are preserved on all copies. 583: .PP 584: Permission is granted to copy and distribute modified versions of this 585: manual under the conditions for verbatim copying, provided that the 586: entire resulting derived work is distributed under the terms of a 587: permission notice identical to this one. 588: .PP 589: Permission is granted to copy and distribute translations of this 590: manual into another language, under the above conditions for modified 591: versions, except that this permission notice may be included in 592: translations approved by the Free Software Foundation instead of in 593: the original English.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.