cpp(CP)

cpp -- K&R C language preprocessor

Syntax

$LIBDIR/cpp [ options ] [ ifile [ ofile ] ]

Description

cpp is the K&R (pre-ANSI) C preprocessor. It can be invoked as the first pass of the cc C compiler as an alternate C language preprocessor for older code that does not work with the standard ANSI preprocessor. See cc(CP) for information about the preprocessor that is called by default. cpp is not generally recommended for current code, but may be required by some utilities or for backwards compatibility.

cpp's output is a form acceptable as input to the next pass of the C compiler. It is not intended as a general purpose macro processor; use m4(CP) instead.

The cpp command optionally accepts two file names as arguments. ifile and ofile are, respectively, the input and output for the preprocessor. They default to standard input and standard output.

Options

-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.
-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 option and a -D option, the name will be undefined regardless of the order of the options.
-H: Print the path names of included files, one per line on standard error.
-Idir: Search in dir for #include files whose names do not begin with ``/'' before looking in the directories on the standard list. #include files whose names do not begin with a ``/'' will first be searched for in the current directory, then in directories named on -I options, and last in directories on the standard list.
-P: Preprocess the input without producing the line control information used by the next pass of the C compiler.
-Sn: This option allows you to set the size of the ``sbf'' buffer. n is the number of bytes that will be dynamically allocated to the ``sbf'' buffer. The ``sbf'' buffer is used, among other things, to store the values of #defines. If you run out of space because of a large number of #defines, you can use the -S option to increase the buffer size. If the -S option is not used, a default statically allocated buffer is set up. If you specify some illegal value for n then the minimum allowable value will be printed in a warning message.
-T: The -T option forces cpp to use only the first eight characters to distinguish preprocessor symbols and is included for backward compatibility.
-Uname: Remove any initial definition of name, where name is a reserved symbol that is predefined by the preprocessor, or a name defined on a -D option. The names predefined by cpp are unix and i386.
-Ydir: Use directory dir in place of the standard list of directories when searching for #include files.

Special names

Two special names are understood by cpp. The name __LINE__ is defined as the current source line number (as a decimal integer), and __FILE__ is defined as the current file name (as a C string). They can be used anywhere (including in macros) just like any other defined names. cpp's notion of the line number and filename may be changed using a #line directive (see below).

The __DATE__, __TIME__, and __STDC__ special names are part of the ANSI C standard and are not recognized by the K&R cpp preprocessor.

Directives

All cpp directive lines start with # in column 1. Any number of blanks and tabs is allowed between the # and the directive. The directives are:

#define name token-string

Defines a macro called name. The value of name is token-string. Subsequent instances of name are replaced with token-string.

#define name( arg, ..., arg ) token-string

This allows substitution of a macro with arguments. The token-string will be substituted for occurrences of name in the input file. If the occurrence of name is followed by an argument list (a comma-separated list of tokens, enclosed in parentheses), each token in the list replaces the corresponding arg in the macro definition. After the entire token-string has been expanded, cpp processes the text that was just substituted. Notice that there can be no space between name and the ``(''.

#undef name

Removes the definition of the macro name. No additional tokens are permitted on the directive line after name.

#ident "string"

Put string into the .comment section of an object file.

#include "filename",
#include <filename>

Include the contents of filename at this point in the program. The included text will then itself be processed by cpp. #include files whose names are enclosed in <> are searched for only in the standard list of directories. See the -I and -Y options 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. The compiler will behave as if integer-constant is the line number of the next line of source code and filename (if present) is the name of the input file. No additional tokens are permitted 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 and up to the matching #endif or next #else or #elif will appear in the output if name is currently defined. No additional tokens are permitted on the directive line after name.

#ifndef name

The lines following this directive and up to the matching #endif or next #else or #elif will appear in the output if name is not currently defined. No additional tokens are permitted on the directive line after name.

#if constant-expression

The lines following this directive and up to the matching #endif or next #else or #elif will appear in the output 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 use 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)

#elif constant-expression

An arbitrary number of #elif directives is allowed between a #if, #ifdef, or #ifndef directive and a #else or #endif directive. The lines following the #elif and up to the next #else, #elif, or #endif directive will appear in the output if the preceding test directive evaluates to zero, all intervening #elif directives evaluate to zero, and the constant-expression evaluates to non-zero. If constant-expression evaluates to non-zero, all succeeding #elif and #else directives will be ignored. Any constant-expression allowed in a #if directive is allowed in a #elif directive.

#else

The lines following this directive and up to the matching #endif will appear in the output if the preceding test directive evaluates to zero, and all intervening #elif directives evaluate to zero. No additional tokens are permitted on the directive line. The test directives and the possible #else directives can be nested.

Unsupported operators

The K&R cpp preprocessor does not recognize the following ANSI operators:

##

concatenation of tokens

#

creation of strings

??

introduce trigraph sequences that allow representation of characters that may be lacking in some character sets. The defined trigraph sequences are:

   ??=   #               ??(   [               ??<   {
   ??/   \               ??)   ]               ??>   }
   ??'   ^               ??!   |               ??-   ~

Unsupported ANSI operators can be approximated through postprocessing. For example, the following command approximates the ANSI C ## operator, although it is not identical:

   sed -e "s/[ \t]*##[ \t]*//"

Files

INCDIR: Standard directory list for #include files, usually /usr/include. This is searched after the current project tree and directories referenced with the -I option.
LIBDIR: Location of the cpp binary, usually /lib.

Diagnostics

The error messages produced by cpp are intended to be self-explanatory. The line number and file name where the error occurred are printed along with the diagnostic.

Notes

By default, the standard directory for included files is /usr/include, but the environment can use a different location. To accomodate this, header files in the standard directory should be referenced using <...>, for example:

   #include <file.h>

This is preferred over one with an absolute path, such as the following:

   #include "/usr/include/file.h"

Double quotes are used for included files in the current project tree. When the header file is referenced in double quotes, the search path includes ./ first. Files referenced in double quotes are referenced first, followed by files in directory paths identified with the -Idir option, and then the files in the standard directory.

The cpp command warns about the use of the absolute path name.