contrib/gcc/cccp.1

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