cpp -- Command

C preprocessor
/lib/cpp [option...] [file...]

The command  cpp calls the  C preprocessor to perform  C preprocessing.  It
performs  the operations  described in  section 3.8  of the  ANSI Standard;
these  include   file  inclusion,  conditional   code  selection,  constant
definition, and  macro definition.  See  the entry on C  preprocessor for a
full description of C's preprocessing language.

Normally, cpp  is used to  preprocess C programs,  but it can be  used as a
simple macro processor for other types  of files as well.  For example, the
X utility imake uses cpp to help build makefiles.

cpp reads each input file,  processes directives, and writes its product on
stdout.  If the  option -E  is not  used, cpp also  writes into  its output
statements of the form #linen filename, so the parser can connect its error
messages and debugger output with  the original line numbers in your source
files.

Options

cpp recognizes the following options:

-C   Do not  suppress comments.  Normally,  cpp strips all  comments from C
     code before it invokes the parsing phase, cc0.

-DVARIABLE[=value]
     Define VARIABLE for the preprocessor at compilation time.  If value is
     not defined, VARIABLE is set to one.  For example, the command

         cc -DLIMIT=20 foo.c

     tells the preprocessor  to define the variable LIMIT to  be 20.  The C
     preprocessor  acts  as  though the  directive  #define  LIMIT 20  were
     included in all source code.

-E   Strip all  line-number information from the  source code.  This option
     is used  to preprocess assembly-language  files or other  sources, and
     should not be used with the other compiler phases.

-Idirectory
     C  allows two  types  of #include  directives  in a  C program,  i.e.,
     #include "file.h" and #include <file.h>. The -I option tells cpp
     to search  a specific directory for  the files you have  named in your
     #include directives,  in addition to the  directories that it searches
     by default.  You can have more  than one -I option on your cpp command
     line.

-o file
     Write  output into  file. If  this option is  missing, cpp  writes its
     output onto stdout, which may be redirected.

-P   Strip all  file and line-number information from the  C code.  This is
     identical to the -E option, defined above.

-Q   Suppress all messages.

-UVARIABLE
     Undefine  VARIABLE, as  if an  #undef directive  were included  in the
     source  program.  This  is  used to  undefine the  variables that  cpp
     defines by default.

-V   Print verbose messages.

-VCPLUS
     Suppress C++-style online comments.

cpp reads the environmental variables CPPHEAD and CPPTAIL and appends their
contents to, respectively, the beginning and the end of the command cpp.

See Also

C preprocessor,
cc,
commands

Diagnostics

The following gives the error messages returned by cpp. The messages are in
alphabetical order.  Each is marked as  to whether it is a fatal, error, or
warning  condition.  A  fatal message  usually  indicates a  condition that
caused the  compiler to terminate  execution.  Fatal errors  from the later
phases of  compilation often cannot be fixed, and  may indicate problems in
the compiler or  assembler.  An error message points to  a condition in the
source code  that the compiler  cannot resolve.  This  almost always occurs
when the program does something illegal, e.g., has unbalanced braces.

string argument mismatch (error)
     The argument string does not match the type declared in the function's
     prototype.  Either  the function prototype  or the argument  should be
     changed.

#assert failure (error)
     The condition being tested in a #assert statement has failed.

## at beginning of macro (error)
     Macro replacement  lists may contain tokens that  are separated by ##,
     but ##  cannot appear at  the beginning or  the end of  the list.  The
     tokens on either side of the ## are pasted together into one token.

## at end of macro (error)
     Macro replacement  lists may contain tokens that  are separated by ##,
     but ##  cannot appear at  the beginning or  the end of  the list.  The
     tokens on either side of the ## are pasted together into one token.

string: cannot create (fatal)
     The preprocessor cpp cannot create  the output file string that it was
     asked  to create.   This often  is due  to a  problem with  the output
     device; check and make sure that it is not full and that it is working
     correctly.

string: cannot open (fatal)
     The compiler  cannot open the file  string of source code  that it was
     asked to  read.  cpp may not  have been told the  correct directory in
     which  this file  is  to be  found;  check that  the  file is  located
     correctly, and that the -I options, if any, are correct.

cannot open include file string (fatal)
     The program  asked for file  string, which was  not found in  the same
     directory as  the source  file, nor  in the default  include directory
     specified  by the  environmental variable  INCDIR, nor  in any  of the
     directories named in -I options given to the cc command.

conditional stack overflow (fatal)
     A series of #if expressions is nested so deeply that it overflowed the
     allotted stack space.  You should simplify this code.

#define argument mismatch (warning)
     The definition of an argument  in a #define instruction does not match
     its subsequent use.  One or the other should be changed.

#elif used without #if or #ifdef (error)
     An #elif  instruction must be  preceded by an #if,  #ifdef, or #ifndef
     control line.

#elif used after #else (error)
     An #elif instruction cannot be preceded by an #else instruction.

#else used without #if or #ifdef (error)
     An #else control  line must be preceded by an  #if, #ifdef, or #ifndef
     control line.

#endif used without #if or #ifdef (error)
     An #endif  instruction must be preceded by an  #if, #ifdef, or #ifndef
     instruction.

EOF in comment (fatal)
     Your source  file appears to  end in mid-comment.  The  file of source
     code may have  been truncated, or you failed to  close a comment; make
     sure  that each  open-comment symbol  `/*' is  balanced with  a close-
     comment symbol `*/'.

EOF in macro string invocation (error)
     Your source file appears to end  in a macro call.  The source file may
     be been truncated.

EOF in midline (warning)
     Check  to   see  that  your   source  file  has   not  been  truncated
     accidentally.

EOF in string (error)
     Your file  appears to end  in the middle  of a quoted  string literal.
     Check  to   see  that  your   source  file  has   not  been  truncated
     accidentally.

#error: string (fatal)
     An  #error control  line  has been  expanded,  printing the  remaining
     tokens on the line and terminating the program.

error in #define syntax (error)
     The syntax of a #define statement is incorrect.  See the Lexicon entry
     for #define for more information.

error in #include syntax (error)
     An #include directive must be  followed by a string enclosed by either
     quotation marks (`` '') or  angle brackets (<>).   Anything else
     is illegal.

identifier string has too many arguments (error)
     Too many actual parameters have been provided.

illegal control line (error)
     A `#' is followed by a word that the compiler does not recognize.

illegal cpp character (n decimal) (error)
     The character  noted cannot be processed  by cpp. It may  be a control
     character or a non-ASCII character.

illegal use of defined (error)
     The construction defined(token) or defined token is legal only in #if,
     #elif, or #assert expressions.

string in #if (error)
     A syntax  error occurred in  a #if declaration.   string describes the
     error in detail.

include stack overflow (fatal)
     A set  of #include  statements is nested  so deeply that  the allotted
     stack space  cannot hold  them.  Examines the  files for a  loop.  You
     should  try to  fold some  of the  header files  into one,  instead of
     having them call each other.

macro body too long (fatal)
     The size of the macro in  question exceeds the limit designed into the
     preprocessor.  Try to shorten or split the macro.

macro expansion buffer overflow in string (fatal)
     The  COHERENT  C  compiler  uses  a  static  buffer  space  to  expand
     preprocessor macros.  In some extreme cases, a macro will exhaust this
     space, thus causing the C compiler  to exit with this message.  Try to
     shorten the macro, or break it  up.  See the Lexicon entry for cpp for
     suggestions on how to use an alternative C preprocessor to expand huge
     macros.

macro string redefined (error)
     The program redefined the macro string.

macro string requires arguments (error)
     The macro calls for arguments that the program has not supplied.

macros nested number deep, loop likely (error)
     Macros  call  each  other number  times;  you  may have  inadvertently
     created an infinite loop.  Try to simplify the program.

missing #endif (error)
     An #if,  #ifdef, or #ifndef instruction was not  closed with an #endif
     instruction.

missing output file (fatal)
     The preprocessor cpp found a -o option that was not followed by a file
     name for the output file.

multiple #else's (error)
     An #if, #ifdef, or #ifndef expression  can be followed by no more than
     one #else expression.

nested comment (warning)
     The  comment  introducer  sequence `/*'  has  been  detected within  a
     comment.  Comments do not nest.

new line in string literal (error)
     A newline character appears in the middle of a string.  If you wish to
     embed a newline within a  string, use the character constant `\n'.  If
     you wish to continue the string  on a new line, insert a backslash `\'
     before the new line.

newline in macro argument (warning)
     A  macro  argument  contains a  newline  character.   This may  create
     trouble when the program is run.

out of space (fatal)
     The compiler ran out of space while attempting to compile the program.
     To remove  this error, examine your source and  break up any functions
     that are extraordinarily large.

parameter must follow # (error)
     Macro replacement  lists may contain  # followed by  a macro parameter
     name.  The macro argument is converted to a string literal.

preprocessor assertion failure (warning)
     A #assert directive that was  tested by the preprocessor cpp was found
     to be false.

string redefined (error)
     cpp macros should not be redefined.   You should check to see that you
     are  not #includeing  two  different versions  of a  file somehow,  or
     attempting to use the same macro name for two different purposes.

too many arguments in a macro (fatal)
     The program uses more than the allowed ten arguments with a macro.

too many directories in include list (fatal)
     The program uses more than the allowed ten #include directories.

string: unknown option (fatal)
     The preprocessor  cpp does  not recognize  the option string.  Try re-
     typing the cc command line.

Notes

The COHERENT  C compiler uses a static buffer  space to expand preprocessor
macros.   Some  programs  that  make  especially  intensive use  of  the  C
processor's macro facility may die during compilation with the message

    macro expansion buffer overflow

This means that the program  has exhaused the compiler's ability to process
macros.  You may  wish to use an alternative preprocessor,  such as the one
that comes with gcc, as described below.

The COHERENT C compiler combines  the preprocessor cpp with the parser cc0.
The file /lib/cpp is simply a  link to the C compiler /lib/cc0. Thus, there
is no way to specify an alternative version of the preprocessor through the
cc command.   You can get around, this however,  by linking the alternative
preprocessor  to a  file named  cc0 in  a directory  other than  /lib, then
calling the alternative version via cc. For example, to have gcc preprocess
program hugemacro.c, do  the following.  First, type the following commands
to link the gcc preprocess to a file named cc0:

    su root
    cd /usr/local/lib/gcc-lib/i386-coh/2.3.2
    ln cpp cc0

Then, to preprocess and compile hugemacro.c, type the following:

    cc -t0 -B/usr/local/lib/gcc-lib/i386-coh/2.3.2 -E hugemacro.c > tmp.c
    cc tmp.c
    rm tmp.c

You may  wish to  embed the above  into your makefile,  or write it  into a
shell script.

© 2012 by Stephen A. Ness