| .\" Copyright (c) 1991, 1992, 1993 Free Software Foundation \-*-Text-*- |
| .\" See section COPYING for conditions for redistribution |
| .TH cpp 1 "30apr1993" "GNU Tools" "GNU Tools" |
| .SH NAME |
| cccp, cpp \- The GNU C-Compatible Compiler Preprocessor. |
| .SH SYNOPSIS |
| .hy 0 |
| .na |
| .TP |
| .B cccp |
| .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 preprocessing directives, 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. |
| |
| When you call the preprocessor individually, either name |
| (\c |
| .B cpp\c |
| \& or \c |
| .B cccp\c |
| \&) will do\(em\&they are completely synonymous. |
| |
| 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 |
| \& directive) |
| 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 |
| \&\|' directives 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 |
| \&\|' |
| directives 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 was formerly required for strict conformance |
| to the C Standard before the standard was corrected. \c |
| |
| This option is available only when you call \c |
| .B cpp\c |
| \& directly; |
| .B gcc\c |
| \& will not pass it from its command line. |
| .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. |