CPP(1)CPP(1) NAME cpp - C language preprocessor SYNOPSIS LIBDIR/cpp [ option | file ] ... DESCRIPTION cpp is a K&R C language preprocessor (not an ISO/ANSI C language preprocessor) designed for standalone use and to be invoked as the first pass of all Fortran compilations and any K&R mode C compilation with the -mp option. Thus, the output of cpp is designed to be in a form acceptable as input to the next pass of the C compiler. Standalone use of cpp on C code is not recommended, because the functionality of cpp has been incorporated into the C compiler. See the m4(1) man page for information on a more general macro processor. The cpp preprocessor does not recognize the # operator (sometimes called the stringize operator), the ## operator (sometimes called the pasting operator), and the #elif command. There are other differences between this and ISO/ANSI C preprocessors. cpp optionally accepts any sequence of flags and input file names. The input files are processed in order; if no input file names are given, the standard input is used. The results of preprocessing the input file(s) are sent to the standard output. The following options are accepted by cpp: -P Preprocess the input without producing the line control information used by the next pass of the C compiler. -C By default, cpp strips C-style comments. If the -C option is specified, all comments (except those found on cpp directive lines) are passed along. -M Run only the macro preprocessor on the named C programs, requesting it to generate Makefile dependencies, and send the results to the standard output. -MDupdate filename Similar to the -M option, but stores the resulting Makefile dependencies in filename rather than sending them to the standard output. cpp specified with the -MDupdate option updates only the lines in filename that end with a distinctive make comment and begin with the target name (as described under the -MDtarget option) followed by a colon. -MDtarget name When the -MDupdate option has been specified, this option causes name to be used as the target name for the first source file. By default, the target name for a source file is the same as the source file name with a .o suffix. -Uname Remove any initial definition of name, where name is a reserved symbol that is predefined by the particular preprocessor. Following is the current list of these possibly reserved symbols. cpp predefines the __EDG, sgi, unix, and mips symbols. The __EXTENSIONS__ symbol is predefined to indicate this is not an ANSI cpp and to allow extensions in ANSI C include files. The compiler drivers, as(1), cc(1), CC(1), pc(1), and f77(1) predefine many other symbols during preprocessing. See their respective man pages for complete lists of the symbols that they define. -Dname -Dname=def Define name with value def as if by a #define. If no =def is given, name is defined with value 1. The -D option has lower precedence than the -U option. That is, if the same name is used in both a -U options and a -D option, the name will be undefined regardless of the order of the options. -Idir Change the algorithm for searching for #include files whose names do not begin with / to look in dir before looking in the directories on the standard list. Thus, #include files whose names are enclosed in double quotation marks ("") will be searched for first in the directory of the file with the #include line, then in the directories named in -I options, and last in directories on a standard list. For #include files whose names are enclosed in <>, the directory of the file with the #include line is not searched. If -I is specified with no dir, cpp is instructed to suppress the search of the standard list of include directories. This standard list consists only of /usr/include. -max_rec_depth=num Set the maximum nesting depth of calls to a single macro to num. The default value is 300. Names Four special names are understood by cpp. The name __LINE__ is defined as the current line number (as a decimal integer) as known by cpp, __FILE__ is defined as the current file name (as a C string) as known by cpp, __DATE__ is defined as a C string containing the current date (printed in the form "Dec 31 1999"), and __TIME__ is defined as a C string containing the current time in hh:mm:ss format. They can be used anywhere (including in macros) just as any other defined name. Directives All cpp directive lines start with # in column 1. Any number of blanks and tabs are allowed between the # and the directive. The directives are: #define name token-string Replace subsequent instances of name with token-string. #define name( arg, ..., arg ) token-string Note that there can be no space between name and the (. Replace subsequent instances of name followed by a (, a list of comma- separated sets of tokens, and a ) followed by token-string, where each occurrence of an arg in the token-string is replaced by the corresponding set of tokens in the comma-separated list. When a macro with arguments is expanded, the arguments are placed into the expanded token-string unchanged. After the entire token- string has been expanded, cpp restarts its scan for names to expand at the beginning of the newly created token-string. #undef name Cause the definition of name (if any) to be forgotten from now on. No additional tokens are permitted on the directive line after name. #ident string The string and the directive are silently allowed. No output is produced for this directive. #pragma The directive and whatever follows it on the line is passed to the output in a slightly modified form which is not documented. The form may change in a future release. #pragma once If this directive appears in an included file, the file will never be included again, even if there is another #include of this file. No tokens or comments are permitted after the once keyword. Using #pragma once is more efficient than using macro wrappers, because the included file is not rescanned, however, it may not be portable to third-party preprocessors. #include "filename" #include <filename> Include, 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. No additional tokens are permitted on the directive line after the final " or >. #line integer-constant filename Causes cpp to generate line control information for the next pass of the C compiler. integer-constant is the line number of the next line and filename is the file from which it comes. If filename is not given, the current file name is unchanged. No additional tokens are allowed on the directive line after the optional filename. #endif Ends a section of lines begun by a test directive (#if, #ifdef, or #ifndef). Each test directive must have a matching #endif. No additional tokens are permitted on the directive line. #ifdef name The lines following this directive will appear in the output only if name has been the subject of a previous #define without being the subject of an intervening #undef. No additional tokens are permitted on the directive line following name. #ifndef name The lines following this directive will appear in the output only if name has not been the subject of a previous #define. No additional tokens are permitted on the directive line after name. #if constant-expression Lines following this directive will appear in the output only if the constant-expression evaluates to non-zero. All binary non- assignment 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, which can be used in constant- expression in the following two forms: defined ( name ) or defined name. This allows the utility of #ifdef and #ifndef in a #if directive. Only these operators, integer constants, and names which are known by cpp should be used in constant- expression. The sizeof operator is not available. To test whether either of two symbols, foo and fum, are defined, use the following: #if defined(foo) || defined(fum) #else The lines following this directive will appear in the output only if the preceding test directive evaluates to zero. No additional tokens are permitted on the directive line. The test directives and the possible #else directives can be nested. FILES INCDIR Standard directory list for #include files, /usr/include LIBDIR /usr/lib SEE ALSO cc(1), line(1), m4(1), unifdef(1)