cpp - the C language preprocessor


     /usr/lib/cpp [-BCHMpPRT] [-undef] [-Dname] [ -Dname  =  def]
     [-Idirectory]  [-Uname]  [-Ydirectory] [ input-file [output-


     cpp is the C language preprocessor. It  is  invoked  as  the
     first pass of any C compilation started with the cc(1B) com-
     mand. However, cpp can also be used as a first-pass  prepro-
     cessor for other Sun compilers.

     Although cpp can be used as a macro processor, this  is  not
     normally  recommended,  as  its output is geared toward that
     which would be acceptable as input to  a  compiler's  second
     pass.  Thus,  the preferred way to invoke cpp is through the
     cc(1B) command,  or  some  other  compilation  command.  For
     general-purpose macro-processing, see m4(1).

     cpp optionally accepts two filenames  as  arguments.  input-
     file and output-file are, respectively, the input and output
     files for the preprocessor. They  default  to  the  standard
     input and the standard output.


     The following options are supported:

     -B    Supports the C++ comment  indicator  `//'.  With  this
           indicator,  everything  on  the  line  after the // is
           treated as a comment.

     -C    Passes all comments (except those that appear on   cpp
           directive lines) through the preprocessor. By default,
           cpp strips out C-style comments.

     -H    Prints the pathnames of included files, one  per  line
           on the standard error.

     -M    Generates a list of makefile  dependencies  and  write
           them  to the standard output. This list indicates that
           the object file which  would  be  generated  from  the
           input  file  depends  on the input file as well as the
           include files referenced.

     -p    Uses only the first eight  characters  to  distinguish
           preprocessor  symbols,  and  issue  a warning if extra
           tokens appear at the end of a line containing a direc-

     -P    Preprocesses the  input  without  producing  the  line
           control  information  used  by  the next pass of the C

     -R    Allows recursive macros.

     -T    Uses only the first eight characters for  distinguish-
           ing  different  preprocessor  names.  This  option  is
           included for backward compatibility with systems which
           always use only the first eight characters.

           Removes initial definitions for  all  predefined  sym-

           Defines name as 1 (one). This is  the  same  as  if  a
           -Dname=1  option appeared on the  cpp command line, or
           as if a

           #define name 1

           line appeared in the source file that cpp is  process-

           Defines name as if by a #define directive. This is the
           same as if a

           #define name def

           line appeared in the source file that  cpp is process-
           ing.  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.

           Inserts directory into the search  path  for  #include
           files  with names not beginning with `/'. directory is
           inserted ahead of the  standard  list  of  ``include''
           directories.  Thus, #include files with names enclosed
           in double-quotes (") are searched  for  first  in  the
           directory  of the file with the #include line, then in
           directories named with  -I  options,  and  lastly,  in
           directories from the standard list. For #include files
           with names  enclosed  in  angle-brackets  (<>  ),  the
           directory  of  the  file with the #include line is not
           searched. See Details below for exact details of  this
           search order.

           Removes any initial definition of name, where name  is
           a symbol that is predefined by a particular preproces-
           sor. Here is a partial list of  symbols  that  may  be
           predefined,  depending  upon   the architecture of the

     Operating System:
           ibm, gcos, os, tss and unix

           interdata,  pdp11,  u370,  u3b,  u3b2,  u3b5,   u3b15,
           u3b20d, vax, ns32000, iAPX286, i386, sparc, and sun

     UNIX system variant:
           RES, and RT

     The lint command:

     The symbols  sun, sparc and unix are  defined  for  all  Sun

           Uses directory in place of the standard list of direc-
           tories when searching for #include files.


     All cpp directives start with a hash symbol (#) as the first
     character  on  a line. White space (SPACE or TAB characters)
     can appear after the initial # for proper indentation.

     #define name token-string
           Replace  subsequent  instances  of  name  with  token-

     #define name(argument [, argument] ... ) token-string
           There can be no  space  between  name  and  the   `('.
           Replace  subsequent  instances  of name, followed by a
           parenthesized list of  arguments,  with  token-string,
           where  each  occurrence  of  an argument 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-

     #undef name
           Remove any definition for the symbol  name.  No  addi-
           tional  tokens  are  permitted  on  the directive line
           after name.

     #include "filename"

     #include <filename>
           Read in the contents of  filename  at  this  location.
           This  data  is  processed by cpp as if it were part of
           the current file.  When  the  <filename>  notation  is
           used,  filename  is  only searched for in the standard
           ``include'' directories. See the  -I  and  -Y  options
           above  for  more detail. No additional tokens are per-
           mitted on the directive line after the  final  `"'  or

     #line integer-constant "filename"
           Generate line control information for the next pass of
           the C compiler. integer-constant is interpreted as the
           line number of the next line and  filename  is  inter-
           preted  as the file from where it comes. If "filename"
           is not given, the current filename  is  unchanged.  No
           additional  tokens are permitted on the directive line
           after the optional filename.

     #if constant-expression
           Subsequent lines up to the matching #else,  #elif,  or
           #endif   directive,  appear  in  the  output  only  if
           constant-expression yields a nonzero value. All binary
           non-assignment C operators, including  `&&', `||', and
           `,', are legal in constant-expression. The `?:' opera-
           tor,  and  the  unary `-', `!', and `~' operators, are
           also legal in constant-expression.

           The precedence of these operators is the same as  that
           for C. In addition, the unary operator defined, can be
           used  in  constant-expression  in  these  two   forms:
           `defined  ( name )' or `defined name'. This allows the
           effect of #ifdef  and  #ifndef  directives  (described
           below)  in  the  #if directive.  Only these operators,
           integer constants, and names that  are  known  by  cpp
           should be used within constant-expression. In particu-
           lar, the size of operator is not available.

     #ifdef name
           Subsequent lines up to the matching #else,  #elif,  or
           #endif  appear  in  the  output  only if name has been
           defined, either with  a  #define  directive  or  a  -D
           option,  and  in  the absence of an intervening #undef
           directive. Additional tokens after name on the  direc-
           tive line will be silently ignored.

     #ifndef name
           Subsequent lines up to the matching #else,  #elif,  or
           #endif  appear in the output only if name has not been
           defined, or if its definition has been removed with an
           #undef  directive.  No additional tokens are permitted
           on the directive line after name.

     #elif constant-expression
           Any number of #elif directives may appear  between  an
           #if, #ifdef, or #ifndef directive and a matching #else
           or #endif directive. The  lines  following  the  #elif
           directive appear in the output only if all of the fol-
           lowing conditions hold:

              o  The constant-expression  in  the  preceding  #if
                 directive  evaluated  to  zero,  the name in the
                 preceding #ifdef is not defined, or the name  in
                 the preceding #ifndef directive was defined.

              o  The constant-expression in all intervening #elif
                 directives evaluated to zero.

              o  The  current  constant-expression  evaluates  to

           If the constant-expression evaluates to non-zero, sub-
           sequent  #elif  and #else directives are ignored up to
           the matching #endif. Any  constant-expression  allowed
           in an #if directive is allowed in an #elif directive.

     #else This inverts the sense of  the  conditional  directive
           otherwise  in  effect.   If  the preceding conditional
           would indicate that lines are  to  be  included,  then
           lines  between  the  #else and the matching #endif are
           ignored.  If the preceding conditional indicates  that
           lines  would be ignored, subsequent lines are included
           in the output. Conditional directives and  correspond-
           ing #else directives can be nested.

           End a section of lines begun by one of the conditional
           directives  #if,  #ifdef, or #ifndef. Each such direc-
           tive must have a matching #endif.

     Formal parameters for  macros  are  recognized  in   #define
     directive bodies, even when they occur inside character con-
     stants and quoted strings. For instance, the output from:

     #define abc(a)|`|a|


     # 1 ""

     The second line is a  NEWLINE. The last seven characters are
     ``|`|xyz|'' (vertical-bar, backquote, vertical-bar, x, y, z,
     vertical-bar). Macro names are not recognized within charac-
     ter  constants  or  quoted  strings during the regular scan.

     #define abc xyz

     does not expand abc in the second line, since it is inside a
     quoted  string  that is not part of a  #define macro defini-

     Macros are not  expanded  while  processing  a   #define  or
     #undef. Thus:

     #define abc zingo
     #define xyz abc
     #undef abc

     produces abc.  The  token  appearing  immediately  after  an
     #ifdef or #ifndef is not expanded.

     Macros are not expanded during the scan which determines the
     actual parameters to another macro call. Thus:

     #define reverse(first,second)second first
     #define greeting hello
     #define greeting goodbye

     produces  `` #define hello goodbye  hello''.

     Output consists of a copy of the input file, with  modifica-
     tions, plus lines of the form:

     #lineno " filename" "level"

     indicating the original source line number and  filename  of
     the following output line and whether this is the first such
     line after an include file has been entered  (level=1),  the
     first  such  line  after  an  include  file  has been exited
     (level=2), or any other such line (level is empty).

     This section contains usage details.

  Directory Search Order
     #include files are searched for in the following order:

     1. The directory of the file  that  contains  the   #include
        request (that is,  #include is relative to the file being
        scanned when the request is made).

     2. The directories specified by -I options, in left-to-right

     3. The standard directory(s) (/usr/include on UNIX systems).

  Special Names
     Two special names are understood by cpp. The name _ _LINE_ _
     is defined as the current line number (a decimal integer) as
     known by cpp, and _ _FILE_  _  is  defined  as  the  current
     filename (a C string) as known by cpp. They can be used any-
     where (including in macros) just as any other defined name.

  Newline Characters
     A  NEWLINE character  terminates  a  character  constant  or
     quoted  string.  An  escaped  NEWLINE  (that is, a backslash
     immediately followed by a  NEWLINE) may be used in the  body
     of  a  #define statement to continue the definition onto the
     next line. The escaped NEWLINE is not included in the  macro

     Comments are removed (unless the -C option is  used  on  the
     command line). Comments are also ignored, except that a com-
     ment terminates a token.


     The following exit values are returned:

     0     Successful completion.

           An error occurred.


     See attributes(5) for descriptions of the  following  attri-

    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    | Availability                | SUNWsprot                   |


     cc(1B), m4(1), attributes(5)


     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.


     When NEWLINE characters were found  in  argument  lists  for
     macros to be expanded, some previous versions of cpp put out
     the NEWLINE characters as they were found and expanded.  The
     current  version  of cpp replaces them with  <SPACE> charac-

     Because the standard directory for  included  files  may  be
     different  in  different environments, this form of #include

     #include <file.h>

     should be used, rather than one with an absolute path, like:

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

     cpp warns about the use of the absolute pathname.

     While the compiler allows 8-bit strings and comments, 8-bits
     are not allowed anywhere else.

Man(1) output converted with man2html