cpp(1) — Commands
NAME
cpp − the C language preprocessor
SYNOPSIS
/usr/lib/cpp [flag ...] [ifile [ofile] ]
DESCRIPTION
The cpp C language preprocessor is invoked as the first pass of any C compilation using the cc(1) command. Thus the output of cpp is designed to be in a form acceptable as input to the next pass of the C compiler. The actions performed by cpp are actually performed by cfe running in cpp mode. 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 since the functionality of cpp may someday be moved elsewhere. See m4(1) for a general macro processor.
The cpp preprocessor optionally accepts two file names as arguments:
ifileInput to the preprocessor
ofileOutput from preprocessor
These files default to standard input and standard output if not supplied. Unless directed to do otherwise, cpp places the output file (ofile) in the same directory in which the input file (ifile) resides.
The cpp preprocessor accepts C++-style end of line comments (//). This means that everything following the two slashes (//) to the end of the line in which they appear is considered as a comment.
FLAGS
The cpp command recognizes the following flags:
−PPreprocess the input without producing the line control information used by the next pass of the C compiler.
−CBy default, cpp strips C-style comments. If the −C flag is specified, all comments (except those found on cpp directive lines) are passed along.
−wTells cpp to not issue warning messages.
−nestlevel=nSet the limit of nesting levels for #included files, default 50.
−oldcommentTreat comments in old way by preprocessor, replace with nothing. Default is to replace comments by a space.
−QBy default, cpp uses " (double quote) for the string literal in the __FILE__ expansions. Specifying −Q flag will cause cpp to use ’ (single quotes) for the string literal in the __FILE__ expansion.
−UnameRemove any initial definition of name, where name is a reserved symbol that is predefined by the particular preprocessor. If no name is specified, then the −U flag is ignored. To see a list of predefined symbols, enter the cc command with the −v flag.
−Dname
−Dname=defDefine name as if by a #define directive. If no =def is given, name is defined as 1. If no name is given the −D flag is ignored. The −D flag has lower precedence than the −U flag. That is, if the same name is used in both a −U flag and a −D flag, the name will be undefined regardless of the order of the flags.
−IdirChange 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 "" will be searched for first in the directory of the ifile argument, then in directories named in −I flags, and last in directories on a standard list. For #include files whose names are enclosed in <> , the directory of the ifile argument is not searched.
−IThis flag changes the algorithm for searching for #include files to never look in the standard list.
−nocurrent_include
Change the behavior of the #include "filename" directive to not search the source file’s directory for filename. This flag causes the #include "filename" directives to behave like #include <filename> directives. This flag allows makefiles to control the search order for header files by using −I flags.
−MPrint, one per line on standard output; the path names of included files. Each is prefixed with ifile’s last component name with the suffix changed to ‘.o’ followed by a ‘:’ and a space (for example “hello.o: /usr/include/stdio.h”).
−MDProduce a dependency file, which has the suffix .d appended to the object file name. This dependency file is created even if the object file is not. The information and the format in the dependency file is identical to that produced by the −M flag. This flag allows dependency information to be generated at the same time that a compilation is occurring.
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 file name (as a C string) as known by cpp. They can be used anywhere (including in macros) just as any other defined name. Furthermore cpp reserves the names __DATE__ and __TIME__ for future use.
All cpp directives start with lines begun by #. The directives are:
#define name token-string
Replace subsequent instances of name with token-string.
#define name(arg, ..., arg) token-string
Notice that there can be no space between name and the (. Replace subsequent instances of name followed by a , a list of comma separated tokens, and a ) by token-string where each occurrence of an arg in the token-string is replaced by the corresponding token 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 re-starts its scan for names to expand at the beginning of the newly created token-string.
#undef nameCause the definition of name (if any) to be forgotten from now on.
#ident ""string""
This directive is transformed by the preprocessor into the form __pragma(6, "string").
#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 flag above for more detail.
#line integer-constant filename
Causes cpp to generate line control information for the next pass of the C compiler. The integer-constant is the line number of the next line and filename is the file where it comes from. If "filename" is not given, the current file name is unchanged.
#endifEnds a section of lines begun by a test directive (#if, #ifdef, or #ifndef). Each test directive must have a matching #endif.
#ifdef nameThe lines following will appear in the output if and only if name has been the subject of a previous #define without being the subject of an intervening #undef.
#ifndef nameThe lines following will not appear 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
Lines following will appear in the output if and only if the constant-expression evaluates to non-zero. All binary non-assignment C operators, the ?: operator, the unary −, !, and ~ operators are all 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 these 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. In particular, the sizeof operator is not available. To test whether either of two symbols, foo and fum, are defined, use #if defined(foo) || defined(fum)
#elseReverses the notion of the test directive which matches this directive. So if lines previous to this directive are ignored, the lines following will appear in the output. And vice versa.
#elif constant-expression
Similar to #else followed by #if, except does not introduce another conditional level. The same restrictions to the constant-expression for #if applies. For example: #if foo==4
a="foo is four";
#elif foo==2
a="foo is two";
#else
a="foo is not four nor two";
#endif The test directives and the possible #else directives can be nested. Any number of #elif may occur between a test directive and the corresponding #else or #endif.
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.
ERRORS
The error messages produced by cpp are intended to be self-explanatory. The line number and filename where the error occurred are printed along with the diagnostic.
FILES
/usr/include standard directory for #include files