contrib/gcc/cccp.1

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