cpp(1) cpp(1)NAME cpp - invokes the C language preprocessor SYNOPSIS cpp [-C] [-Dname[=def]] [-Idir] [-P] [-Uname] [-M[prefix]] [-Y] [ifile [ofile]] ARGUMENTS -C Passes along all comments except those found on cpp directive lines. By default, cpp strips C-style comments. -Dname[=def] Defines name as if by a #define directive. If no =def is given, name is defined as 1. -Idir Searches for #include files (whose names do not begin with /) in dir before looking in the directories on the standard list. When this option is used, #include files whose names are enclosed in "" (double quotes) are searched for first in the directory of the ifile argument, then in directories named in -I options, and last in directories on a standard list, which, at present, consists of /usr/include. If the -Y option (see below) is specified, the standard list is not searched. For #include files whose names are enclosed in <>, the directory of the ifile argument is not searched, unless -I. is specified. -P Turns off the default production of line control information. Line control information is used by the next pass of the C compiler to generate useful error messages about the line on which an error occurred. Line control lines have the form #lineno file where lineno is the line number within the file at which cpp found the line. Line control information is useful because, as cpp reads each #include file and writes its contents to ofile, synchronization between the text lines in ifile and the text lines in ofile is lost. For example, if the following ifile is compiled without line control information #include <stdio.h> main() { x =) 2; } January 1992 1
cpp(1) cpp(1)the C compiler will generate the following error message: "", line 157: x undefined "", line 157: syntax error To the C compiler, having included stdio.h in ofile, line 157 is the true line number at which the error occurred. With line control information enabled, which is the default, cc can display the correct line number as shown below: "", line 5: x undefined "", line 5: syntax error -Uname Removes any initial definition of name, where name is a reserved symbol that is predefined by the particular preprocessor. The list of reserved symbols is shown below: operating system: unix hardware: m68k UNIX(Reg.) System variant: _SYSV_SOURCE _BSD_SOURCE _AUX_SOURCE -M[prefix] Generates make dependency statements from the #include (see below) statements contained in ifile. The dependency statements can later be incorporated into a description file for use by make in determining the #include files on which ifile depends. The dependency statements are of the form: target: include1 [ include2 ...] where target is a name created by subsituting the suffix of ifile with `.o.' For example, if the name of ifile is main.c, target will be main.o. If prefix is present and the #include file in ifile is found in the standard list, prefix is applied as shown below: target: prefix/include1 [ prefix/include2 ...] For example, if the source file main.c includes 2 January 1992
cpp(1) cpp(1)<stdio.h> and the -M option is used, the following dependency statement is generated: main.o: /usr/include/stdio.h If -M'$(INC)' is specified, the following dependency statement is generated: main.o: $(INC)/stdio.h Only unique #include files are kept; duplicates are discarded. The resulting ofile will contain only dependency statements. Error messages are written on standard error. If cpp is invoked with the -M option and ifile does not have a suffix, cpp exits with an error message. -Y Prevents cpp from searching the standard list, which at present consists of /usr/include, when processing #include files. This option is useful when used in conjunction with the -I option. When cpp cannot find a #include file in the directories specified by one or more -I options, its normal behavior is to search the standard list. If the -Y option is used in addition to the -I option and cpp cannot find a #include file in the directory specified by one or more -I options, cpp writes an error message on standard error, does not search the standard list, and continues processing. Thus, use of the -Y option ensures that cpp does not silently include the wrong #include file in cases where the -I option is incorrectly specified or the desired #include file is erroneously missing from the specified directory. ifile [ofile] Specifies the input file to be compiled (ifile) and the output file (ofile) into which the results will be placed. DESCRIPTION cpp is the C language preprocessor that is invoked as the first pass of any C compilation using the cc(1) command. The output of cpp is acceptable as input to the next pass of the C compiler. As the C language evolves, cpp and the rest of the C compilation package will be modified to follow these changes. Therefore, the use of cpp other than in this framework is not suggested. The preferred way to invoke cpp is through the cc(1) command because the functionality of cpp may someday be moved elsewhere. See m4(1) for a general macro processor. January 1992 3
cpp(1) cpp(1)The cpp command optionally accepts two filenames as arguments. The input for the preprocessor is ifile, which is also known as the source file, and the output is ofile. If not supplied, ifile and ofile default to standard input and standard output, except in the case of the -M option, which requires ifile to be present and have a suffix. Two special names are understood by cpp. The name __LINE__ is defined as the current line number (as a decimal integer) as known by cpp, and __FILE__ is defined as the current filename (as a C string) as known by cpp. They can be used anywhere, including in macros, just as any other defined name. All cpp directives start with lines begun by #. The directives are: #define name token-string Replaces subsequent instances of name with token-string. #define name( arg, ..., arg ) token-string Replaces subsequent instances of name followed by a left parenthesis [(], a list of comma-separated tokens, and a right parenthesis [)] by token-string where each occurrence of arg in the token-string is replaced by the corresponding token in the comma-separated list. Notice that there can be no space between name and the left parenthesis [(]. #undef name Causes the definition of name, if any, to be undefined. #include "filename" #include <filename> Includes at this point the contents of filename, which will then be run through cpp. When the <filename> notation is used, filename is only searched for in the standard places. See the -I option above for more detail. #line integer-constant "filename" Causes cpp to generate line-control information for the next pass of the C compiler. The line number of the next line is integer-constant, and filename is the file where it comes from. If "filename" is not given, the current filename is unchanged. #endif Ends a section of lines begun by a test directive (#if, #ifdef, or #ifndef). Each test directive must have a matching #endif. 4 January 1992
cpp(1) cpp(1)#ifdef name Displays the lines following in the output if and only if name was the subject of a previous #define without being the subject of an intervening #undef. #ifndef name Does not display the lines following in the output if and only if name has been the subject of a previous #define without being the subject of an intervening #undef. #if constant-expression Displays the lines following in the output if and only if constant-expression evaluates to nonzero. All binary nonassignment C operators, the ?: operator, the unary -, !, and ~ operators are legal in constant-expression. The precedence of the operators is the same as defined by the C language. There is also a unary operator defined that can be used in constant-expression in these two forms: defined ( name ) or defined name. This allows the utility of #ifdef and #ifndef in an #if directive. Only these operators, integer constants, and names that are known by cpp should be used in constant-expression. In particular, the sizeof operator is not available. #elif constant-expression Displays the lines following the output if and only if constant-expression is true and the preceding #if constant-expression with which the subject #elif is paired is false. The formation of constant-expression is subject to the restrictions described for #if above. #else Reverses the notion of the test directive that matches this directive. If lines previous to this directive are ignored, the lines following appear in the output. If lines previous to this directive are not ignored, the lines following do not appear in the output. #ident ... This directive is maintained for historical reasons, but does not cause cpp to do any special processing nor to generate any output to ofile. #pragma ... Lines beginning with this directive are written to ofile without modification. The test directives and the possible #else directives can be nested. January 1992 5
cpp(1) cpp(1)STATUS MESSAGES AND VALUES The error and warning messages produced by cpp are self- explanatory and are written to standard output. The line number and filename where the error occurred are printed with the message. If ifile is a relative pathname, cpp also prints the absolute path of ifile in the form: ifile (absolute path) :message NOTES When newline characters were found in argument lists for macros to be expanded, previous versions of cpp put out the newlines as they were found and expanded. The current version of cpp replaces these newlines with blanks to alleviate problems that the previous versions had when this occurred. FILES /lib/cpp Executable file /usr/include Executable file SEE ALSO cc(1), m4(1), make(1) ``Other Programming Tools'' in A/UX Programming Languages and Tools, Volume 2 6 January 1992