diff options
author | pst <pst@FreeBSD.org> | 1994-11-02 08:18:25 +0000 |
---|---|---|
committer | pst <pst@FreeBSD.org> | 1994-11-02 08:18:25 +0000 |
commit | 304e7e53f19010b9fea089d376f17d341659121a (patch) | |
tree | 6d9d6a2f5c8be80403b58a444dc1a6624722a2af | |
parent | a1ca5f047f62bccffb3e873404fc3d9c5d3be1ba (diff) | |
download | FreeBSD-src-304e7e53f19010b9fea089d376f17d341659121a.zip FreeBSD-src-304e7e53f19010b9fea089d376f17d341659121a.tar.gz |
Put a real man page in for cpp(1)... it needs to be converted to the mandoc
macros, but it's good enough for now.
Obtained from: gcc 2.6.0 gnu distribution
-rw-r--r-- | gnu/usr.bin/cc/cpp/cpp.1 | 675 |
1 files changed, 674 insertions, 1 deletions
diff --git a/gnu/usr.bin/cc/cpp/cpp.1 b/gnu/usr.bin/cc/cpp/cpp.1 index 54c4dfb..a58fb20 100644 --- a/gnu/usr.bin/cc/cpp/cpp.1 +++ b/gnu/usr.bin/cc/cpp/cpp.1 @@ -1 +1,674 @@ -.so man1/cccp.1 +.\" Copyright (c) 1991, 1992, 1993 Free Software Foundation \-*-Text-*- +.\" See section COPYING for conditions for redistribution +.TH cpp 1 "30, April 1993" "FreeBSD" "GNU Tools" +.SH NAME +cpp \- Compiler Preprocessor. +.SH SYNOPSIS +.hy 0 +.na +.TP +.B cpp +.RB "[\|" \-$ "\|]" +.RB "[\|" \-A \c +.I predicate\c +.RB [ (\c +.I value\c +.BR ) ]\|] +.RB "[\|" \-C "\|]" +.RB "[\|" \-D \c +.I name\c +.RB [ =\c +.I definition\c +\&]\|] +.RB "[\|" \-dD "\|]" +.RB "[\|" \-dM "\|]" +.RB "[\|" "\-I\ "\c +.I directory\c +\&\|] +.RB "[\|" \-H "\|]" +.RB "[\|" \-I\- "\|]" +.RB "[\|" "\-imacros\ "\c +.I file\c +\&\|] +.RB "[\|" "\-include\ "\c +.I file\c +\&\|] +.RB "[\|" "\-idirafter\ "\c +.I dir\c +\&\|] +.RB "[\|" "\-iprefix\ "\c +.I prefix\c +\&\|] +.RB "[\|" "\-iwithprefix\ "\c +.I dir\c +\&\|] +.RB "[\|" \-lang\-c "\|]" +.RB "[\|" \-lang\-c++ "\|]" +.RB "[\|" \-lang\-objc "\|]" +.RB "[\|" \-lang\-objc++ "\|]" +.RB "[\|" \-lint "\|]" +.RB "[\|" \-M\ [ \-MG "\|]]" +.RB "[\|" \-MM\ [ \-MG "\|]]" +.RB "[\|" \-MD\ \c +.I file\ \c +\&\|] +.RB "[\|" \-MMD\ \c +.I file\ \c +\&\|] +.RB "[\|" \-nostdinc "\|]" +.RB "[\|" \-nostdinc++ "\|]" +.RB "[\|" \-P "\|]" +.RB "[\|" \-pedantic "\|]" +.RB "[\|" \-pedantic\-errors "\|]" +.RB "[\|" \-traditional "\|]" +.RB "[\|" \-trigraphs "\|]" +.RB "[\|" \-U \c +.I name\c +\&\|] +.RB "[\|" \-undef "\|]" +.RB "[\|" \-Wtrigraphs "\|]" +.RB "[\|" \-Wcomment "\|]" +.RB "[\|" \-Wall "\|]" +.RB "[\|" \-Wtraditional "\|]" +.br +.RB "[\|" \c +.I infile\c +.RB | \- "\|]" +.RB "[\|" \c +.I outfile\c +.RB | \- "\|]" +.ad b +.hy 1 +.SH DESCRIPTION +The C preprocessor is a \c +.I macro processor\c +\& that is used automatically by +the C compiler to transform your program before actual compilation. It is +called a macro processor because it allows you to define \c +.I macros\c +\&, +which are brief abbreviations for longer constructs. + +The C preprocessor provides four separate facilities that you can use as +you see fit: +.TP +\(bu +Inclusion of header files. These are files of declarations that can be +substituted into your program. +.TP +\(bu +Macro expansion. You can define \c +.I macros\c +\&, which are abbreviations +for arbitrary fragments of C code, and then the C preprocessor will +replace the macros with their definitions throughout the program. +.TP +\(bu +Conditional compilation. Using special preprocessor commands, you +can include or exclude parts of the program according to various +conditions. +.TP +\(bu +Line control. If you use a program to combine or rearrange source files into +an intermediate file which is then compiled, you can use line control +to inform the compiler of where each source line originally came from. +.PP +C preprocessors vary in some details. For a full explanation of the +GNU C preprocessor, see the +.B info +file `\|\c +.B cpp.info\c +\&\|', or the manual +.I The C Preprocessor\c +\&. Both of these are built from the same documentation source file, `\|\c +.B cpp.texinfo\c +\&\|'. The GNU C +preprocessor provides a superset of the features of ANSI Standard C. + +ANSI Standard C requires the rejection of many harmless constructs commonly +used by today's C programs. Such incompatibility would be inconvenient for +users, so the GNU C preprocessor is configured to accept these constructs +by default. Strictly speaking, to get ANSI Standard C, you must use the +options `\|\c +.B \-trigraphs\c +\&\|', `\|\c +.B \-undef\c +\&\|' and `\|\c +.B \-pedantic\c +\&\|', but in +practice the consequences of having strict ANSI Standard C make it +undesirable to do this. + +Most often when you use the C preprocessor you will not have to invoke it +explicitly: the C compiler will do so automatically. However, the +preprocessor is sometimes useful individually. + +The C preprocessor expects two file names as arguments, \c +.I infile\c +\& and +\c +.I outfile\c +\&. The preprocessor reads \c +.I infile\c +\& together with any other +files it specifies with `\|\c +.B #include\c +\&\|'. All the output generated by the +combined input files is written in \c +.I outfile\c +\&. + +Either \c +.I infile\c +\& or \c +.I outfile\c +\& may be `\|\c +.B \-\c +\&\|', which as \c +.I infile\c +\& +means to read from standard input and as \c +.I outfile\c +\& means to write to +standard output. Also, if \c +.I outfile\c +\& or both file names are omitted, +the standard output and standard input are used for the omitted file names. +.SH OPTIONS +Here is a table of command options accepted by the C preprocessor. +These options can also be given when compiling a C program; they are +passed along automatically to the preprocessor when it is invoked by +the compiler. +.TP +.B \-P +Inhibit generation of `\|\c +.B #\c +\&\|'-lines with line-number information in +the output from the preprocessor. This might be +useful when running the preprocessor on something that is not C code +and will be sent to a program which might be confused by the +`\|\c +.B #\c +\&\|'-lines. +.TP +.B \-C +Do not discard comments: pass them through to the output file. +Comments appearing in arguments of a macro call will be copied to the +output before the expansion of the macro call. +.TP +.B \-traditional +Try to imitate the behavior of old-fashioned C, as opposed to ANSI C. +.TP +.B \-trigraphs +Process ANSI standard trigraph sequences. These are three-character +sequences, all starting with `\|\c +.B ??\c +\&\|', that are defined by ANSI C to +stand for single characters. For example, `\|\c +.B ??/\c +\&\|' stands for +`\|\c +.BR "\e" "\|'," +so `\|\c +.B '??/n'\c +\&\|' is a character constant for a newline. +Strictly speaking, the GNU C preprocessor does not support all +programs in ANSI Standard C unless `\|\c +.B \-trigraphs\c +\&\|' is used, but if +you ever notice the difference it will be with relief. + +You don't want to know any more about trigraphs. +.TP +.B \-pedantic +Issue warnings required by the ANSI C standard in certain cases such +as when text other than a comment follows `\|\c +.B #else\c +\&\|' or `\|\c +.B #endif\c +\&\|'. +.TP +.B \-pedantic\-errors +Like `\|\c +.B \-pedantic\c +\&\|', except that errors are produced rather than +warnings. +.TP +.B \-Wtrigraphs +Warn if any trigraphs are encountered (assuming they are enabled). +.TP +.B \-Wcomment +.TP +.B \-Wcomments +Warn whenever a comment-start sequence `\|\c +.B /*\c +\&\|' appears in a comment. +(Both forms have the same effect). +.TP +.B \-Wall +Requests both `\|\c +.B \-Wtrigraphs\c +\&\|' and `\|\c +.B \-Wcomment\c +\&\|' (but not +`\|\c +.B \-Wtraditional\c +\&\|'). +.TP +.B \-Wtraditional +Warn about certain constructs that behave differently in traditional and +ANSI C. +.TP +.BI "\-I " directory\c +\& +Add the directory \c +.I directory\c +\& to the end of the list of +directories to be searched for header files. +This can be used to override a system header file, substituting your +own version, since these directories are searched before the system +header file directories. If you use more than one `\|\c +.B \-I\c +\&\|' option, +the directories are scanned in left-to-right order; the standard +system directories come after. +.TP +.B \-I\- +Any directories specified with `\|\c +.B \-I\c +\&\|' options before the `\|\c +.B \-I\-\c +\&\|' +option are searched only for the case of `\|\c +.B #include "\c +.I file\c +\&"\c +\&\|'; +they are not searched for `\|\c +.B #include <\c +.I file\c +\&>\c +\&\|'. + +If additional directories are specified with `\|\c +.B \-I\c +\&\|' options after +the `\|\c +.B \-I\-\c +\&\|', these directories are searched for all `\|\c +.B #include\c +\&\|' +directives. + +In addition, the `\|\c +.B \-I\-\c +\&\|' option inhibits the use of the current +directory as the first search directory for `\|\c +.B #include "\c +.I file\c +\&"\c +\&\|'. +Therefore, the current directory is searched only if it is requested +explicitly with `\|\c +.B \-I.\c +\&\|'. Specifying both `\|\c +.B \-I\-\c +\&\|' and `\|\c +.B \-I.\c +\&\|' +allows you to control precisely which directories are searched before +the current one and which are searched after. +.TP +.B \-nostdinc +Do not search the standard system directories for header files. +Only the directories you have specified with `\|\c +.B \-I\c +\&\|' options +(and the current directory, if appropriate) are searched. +.TP +.B \-nostdinc++ +Do not search for header files in the C++ specific standard +directories, but do still search the other standard directories. +(This option is used when building libg++.) +.TP +.BI "\-D " "name"\c +\& +Predefine \c +.I name\c +\& as a macro, with definition `\|\c +.B 1\c +\&\|'. +.TP +.BI "\-D " "name" = definition +\& +Predefine \c +.I name\c +\& as a macro, with definition \c +.I definition\c +\&. +There are no restrictions on the contents of \c +.I definition\c +\&, but if +you are invoking the preprocessor from a shell or shell-like program +you may need to use the shell's quoting syntax to protect characters +such as spaces that have a meaning in the shell syntax. If you use more than +one `\|\c +.B \-D\c +\&\|' for the same +.I name\c +\&, the rightmost definition takes effect. +.TP +.BI "\-U " "name"\c +\& +Do not predefine \c +.I name\c +\&. If both `\|\c +.B \-U\c +\&\|' and `\|\c +.B \-D\c +\&\|' are +specified for one name, the `\|\c +.B \-U\c +\&\|' beats the `\|\c +.B \-D\c +\&\|' and the name +is not predefined. +.TP +.B \-undef +Do not predefine any nonstandard macros. +.TP +.BI "\-A " "name(" value ) +Assert (in the same way as the \c +.B #assert\c +\& command) +the predicate \c +.I name\c +\& with tokenlist \c +.I value\c +\&. Remember to escape or quote the parentheses on +shell command lines. + +You can use `\|\c +.B \-A-\c +\&\|' to disable all predefined assertions; it also +undefines all predefined macros. +.TP +.B \-dM +Instead of outputting the result of preprocessing, output a list of +`\|\c +.B #define\c +\&\|' commands for all the macros defined during the +execution of the preprocessor, including predefined macros. This gives +you a way of finding out what is predefined in your version of the +preprocessor; assuming you have no file `\|\c +.B foo.h\c +\&\|', the command +.sp +.br +touch\ foo.h;\ cpp\ \-dM\ foo.h +.br +.sp +will show the values of any predefined macros. +.TP +.B \-dD +Like `\|\c +.B \-dM\c +\&\|' except in two respects: it does \c +.I not\c +\& include the +predefined macros, and it outputs \c +.I both\c +\& the `\|\c +.B #define\c +\&\|' +commands and the result of preprocessing. Both kinds of output go to +the standard output file. +.PP +.TP +.BR \-M\ [ \-MG ] +Instead of outputting the result of preprocessing, output a rule +suitable for \c +.B make\c +\& describing the dependencies of the main +source file. The preprocessor outputs one \c +.B make\c +\& rule containing +the object file name for that source file, a colon, and the names of +all the included files. If there are many included files then the +rule is split into several lines using `\|\c +.B \\\\\c +\&\|'-newline. + +`\|\c +.B \-MG\c +\&\|' says to treat missing header files as generated files and assume \c +they live in the same directory as the source file. It must be specified \c +in addition to `\|\c +.B \-M\c +\&\|'. + +This feature is used in automatic updating of makefiles. +.TP +.BR \-MM\ [ \-MG ] +Like `\|\c +.B \-M\c +\&\|' but mention only the files included with `\|\c +.B #include +"\c +.I file\c +\&"\c +\&\|'. System header files included with `\|\c +.B #include +<\c +.I file\c +\&>\c +\&\|' are omitted. +.TP +.BI \-MD\ file +Like `\|\c +.B \-M\c +\&\|' but the dependency information is written to `\|\c +.I file\c +\&\|'. This is in addition to compiling the file as +specified\(em\&`\|\c +.B \-MD\c +\&\|' does not inhibit ordinary compilation the way +`\|\c +.B \-M\c +\&\|' does. + +When invoking gcc, do not specify the `\|\c +.I file\c +\&\|' argument. Gcc will create file names made by replacing `\|\c +.B .c\c +\&\|' with `\|\c +.B .d\c +\&\|' at the end of the input file names. + +In Mach, you can use the utility \c +.B md\c +\& to merge multiple files +into a single dependency file suitable for using with the `\|\c +.B make\c +\&\|' +command. +.TP +.BI \-MMD\ file +Like `\|\c +.B \-MD\c +\&\|' except mention only user header files, not system +header files. +.TP +.B \-H +Print the name of each header file used, in addition to other normal +activities. +.TP +.BI "\-imacros " "file"\c +\& +Process \c +.I file\c +\& as input, discarding the resulting output, before +processing the regular input file. Because the output generated from +\c +.I file\c +\& is discarded, the only effect of `\|\c +.B \-imacros \c +.I file\c +\&\c +\&\|' is to +make the macros defined in \c +.I file\c +\& available for use in the main +input. The preprocessor evaluates any `\|\c +.B \-D\c +\&\|' and `\|\c +.B \-U\c +\&\|' options +on the command line before processing `\|\c +.B \-imacros \c +.I file\c +\&\|' \c +\&. +.TP +.BI "\-include " "file" +Process +.I file +as input, and include all the resulting output, +before processing the regular input file. +.TP +.BI "-idirafter " "dir"\c +\& +Add the directory \c +.I dir\c +\& to the second include path. The directories +on the second include path are searched when a header file is not found +in any of the directories in the main include path (the one that +`\|\c +.B \-I\c +\&\|' adds to). +.TP +.BI "-iprefix " "prefix"\c +\& +Specify \c +.I prefix\c +\& as the prefix for subsequent `\|\c +.B \-iwithprefix\c +\&\|' +options. +.TP +.BI "-iwithprefix " "dir"\c +\& +Add a directory to the second include path. The directory's name is +made by concatenating \c +.I prefix\c +\& and \c +.I dir\c +\&, where \c +.I prefix\c +\& +was specified previously with `\|\c +.B \-iprefix\c +\&\|'. +.TP +.B \-lang-c +.TP +.B \-lang-c++ +.TP +.B \-lang-objc +.TP +.B \-lang-objc++ +Specify the source language. `\|\c +.B \-lang-c++\c +\&\|' makes the preprocessor +handle C++ comment syntax, and includes extra default include +directories for C++, and `\|\c +.B \-lang-objc\c +\&\|' enables the Objective C +`\|\c +.B #import\c +\&\|' directive. `\|\c +.B \-lang-c\c +\&\|' explicitly turns off both of +these extensions, and `\|\c +.B \-lang-objc++\c +\&\|' enables both. + +These options are generated by the compiler driver \c +.B gcc\c +\&, but not +passed from the `\|\c +.B gcc\c +\&\|' command line. +.TP +.B \-lint +Look for commands to the program checker \c +.B lint\c +\& embedded in +comments, and emit them preceded by `\|\c +.B #pragma lint\c +\&\|'. For example, +the comment `\|\c +.B /* NOTREACHED */\c +\&\|' becomes `\|\c +.B #pragma lint +NOTREACHED\c +\&\|'. + +This option is available only when you call \c +.B cpp\c +\& directly; +\c +.B gcc\c +\& will not pass it from its command line. +.TP +.B \-$ +Forbid the use of `\|\c +.B $\c +\&\|' in identifiers. This is required for ANSI +conformance. \c +.B gcc\c +\& automatically supplies this option to the +preprocessor if you specify `\|\c +.B \-ansi\c +\&\|', but \c +.B gcc\c +\& doesn't +recognize the `\|\c +.B \-$\c +\&\|' option itself\(em\&to use it without the other +effects of `\|\c +.B \-ansi\c +\&\|', you must call the preprocessor directly. +.SH "SEE ALSO" +.RB "`\|" Cpp "\|'" +entry in +.B info\c +\&; +.I The C Preprocessor\c +, Richard M. Stallman. +.br +.BR gcc "(" 1 ");" +.RB "`\|" Gcc "\|'" +entry in +.B info\c +\&; +.I +Using and Porting GNU CC (for version 2.0)\c +, Richard M. Stallman. +.SH COPYING +Copyright (c) 1991, 1992, 1993 Free Software Foundation, Inc. +.PP +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. +.PP +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. +.PP +Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be included in +translations approved by the Free Software Foundation instead of in +the original English. |