CPP - the C preprocessor.

Syntax:

c_g8_ns/8cv1.3/cpp infile outfile option option ...

D=name[=value]  I=path
M=file          S=path
-0 (zero)       +a   +A
+h   +H         +i   +I
+t   +T

Options:

infile: is a file containing C source code to be preprocessed. This argument may be omitted, in which case CPP will just process the configuration file (as specified by the M= option).
outfile: is the name of a file where CPP's output should be written. This argument may be omitted, in which case output is written to the standard output stream. If you specify an "outfile", you must also specify an "infile".
D=name: #defines the given name as a preprocessor manifest.
D=name=value: #defines the given name as a preprocessor manifest and gives it the specified value.
I=path: indicates that include files can be found under the given pathname.
M=file: names a CPP configuration file (as described later).
S=path: sets both path/site and path as include file pathnames.
-0 (zero): requests special syntax-checking on behalf of the next pass of the compiler (P0). Users seldom have a reason for specifying this option explicitly. It is used by the driver that runs the C compiler itself.
+a or +A: checks for strict ANSI Standard C. In particular, this option generates warning messages if the input code exceeds any of the translation limits guaranteed by the ANSI standard. For example, you will be warned if any strings are longer than 509 characters. This version of C actually supports longer strings, but other versions may not.
+h or +H: generates ASCII text output. This is the default.
+i or +I: generates a CPP token file as output. This can be used as input to CPP (see the description of configuration files below).
+t or +T: generates a CPP token file as output. This can be used as input to the Parser (see below).

Description:

CPP preprocesses C source code, handling preprocessor directives (e.g. #include, #define, etc.). The output from CPP may be normal ASCII text, or it may be a special partly parsed token file. Token files are generally smaller and faster to process than normal ASCII text. There are two types of token files:

Ones that will be used as input to CPP in later compilations. For example, you might tokenize standard #include files so that CPP handles them more quickly.
Ones that will be used as input to the Parser. Using token files usually makes the parser phase go faster.

The contents of CPP token files may be dumped with the TFD command. This command is executed with the command line

tfd file

where "file" is the name of a CPP token file. The dump is printed on the standard output, and may be redirected to a file.

Include Files:

When CPP finds a #include directive, it must search for the file. If the file's name is given in angle brackets, as in <file.h>, it searches the S=path directory first and then searches the I=path directory. If the file's name is given in double quotes, as in "file.h", CPP searches the I=path directory first and then searches the S=path directory. Whatever the form of the #include directive, if the desired file cannot be found under the I= or S= directories, CPP will strip off the angle brackets or enclosing quotes and make one last attempt to find the file.

Configuration Files:

A configuration file consists of a series of directives that control the behavior of CPP. The possible directives are explained below.

define name string

This has the same format and purpose as a #define directive in normal C code. It creates a manifest or macro with the given value.

inline includefile

This directive lets you simulate an include file. When CPP finds an "inline" directive, it begins to gather input lines up until the first line consisting of only a '#' character. For example, in

inline sim.h
extern int junk1;
extern int junk2;
#

CPP collects the two declarations and associates them with the name "sim.h". If a program contains the directive,

#include <sim.h>

CPP will take the gathered text and include it at that point in the program, as if it had come from an included file.

map includename1 includename2

This directive says that all references of the form

#include includename1

should be converted to

#include includename2

null includefile

This tells CPP to ignore all #include directives that attempt to include the specified file.

search pathname

This is equivalent to I=pathname on the command line that invokes CPP; see above for an explanation of the I= option.

system_search pathname

This is equivalent to S=pathname on the command line that invokes CPP; see above for an explanation of the S= option.

token includename1 filename

This is similar to the map directive, but indicates that filename is in tokenized format (created using the "+I" option). Also, the second include name must be a complete pathname.

For example, suppose that you have a token file version of <stdio.h> named mystdio.h. You might write

token <stdio.h> /dir1/dir2/mystdio.h

Putting this in an appropriate configuration file is the only way to #include a token file.

Notes:

Unlike most of the other software in the C package, the command line for CPP is case-sensitive. The letters in option keywords must be entered in the case shown.