Return to cccp.1 CVS log

Up to [GCC 2.x] / gcc

Annotation of gcc/cccp.1, revision 1.1

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

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.