


cpp(1)                      GNU Tools                      cpp(1)


NNAAMMEE
       cccp, cpp - The GNU C-Compatible Compiler Preprocessor.

SSYYNNOOPPSSIISS
       ccccccpp   [--$$] [--AA_p_r_e_d_i_c_a_t_e[((_v_a_l_u_e))]] [--CC]
              [--DD_n_a_m_e[==_d_e_f_i_n_i_t_i_o_n]] [--ddDD] [--ddMM] [--II _d_i_r_e_c_t_o_r_y]
              [--HH] [--II--] [--iimmaaccrrooss _f_i_l_e] [--iinncclluuddee _f_i_l_e]
              [--iiddiirraafftteerr _d_i_r] [--iipprreeffiixx _p_r_e_f_i_x]
              [--iiwwiitthhpprreeffiixx _d_i_r] [--llaanngg--cc] [--llaanngg--cc++++]
              [--llaanngg--oobbjjcc] [--llaanngg--oobbjjcc++++] [--lliinntt] [--MM] [--MMDD]
              [--MMMM] [--MMMMDD] [--nnoossttddiinncc] [--nnoossttddiinncc++++] [--PP]
              [--ppeeddaannttiicc] [--ppeeddaannttiicc--eerrrroorrss] [--ttrraaddiittiioonnaall]
              [--ttrriiggrraapphhss] [--UU_n_a_m_e] [--uunnddeeff] [--WWttrriiggrraapphhss]
              [--WWccoommmmeenntt] [--WWaallll] [--WWttrraaddiittiioonnaall]
              [_i_n_f_i_l_e|--] [_o_u_t_f_i_l_e|--]

DDEESSCCRRIIPPTTIIOONN
       The C preprocessor is a _m_a_c_r_o _p_r_o_c_e_s_s_o_r that is used auto-
       matically  by the C compiler to transform your program be-
       fore actual compilation.  It is called a  macro  processor
       because  it  allows  you to define _m_a_c_r_o_s, which are brief
       abbreviations for longer constructs.

       The C preprocessor provides four separate facilities  that
       you can use as you see fit:

       o      Inclusion of header files.  These are files of dec-
              larations that can be substituted  into  your  pro-
              gram.

       o      Macro  expansion.  You can define _m_a_c_r_o_s, which are
              abbreviations for arbitrary fragments  of  C  code,
              and then the C preprocessor will replace the macros
              with their definitions throughout the program.

       o      Conditional compilation.  Using special  preproces-
              sor  commands,  you can include or exclude parts of
              the program according to various conditions.

       o      Line control.  If you use a program to  combine  or
              rearrange  source  files  into an intermediate file
              which is then compiled, you can use line control to
              inform the compiler of where each source line orig-
              inally came from.

       C preprocessors vary in some details.  For a full explana-
       tion  of  the  GNU  C  preprocessor,  see  the  iinnffoo  file
       `ccpppp..iinnffoo', or the manual _T_h_e  _C  _P_r_e_p_r_o_c_e_s_s_o_r.   Both  of
       these  are  built from the same documentation source file,
       `ccpppp..tteexxiinnffoo'.  The GNU C preprocessor provides a superset
       of the features of ANSI Standard C.

       ANSI  Standard  C  requires the rejection of many harmless
       constructs commonly used by today's C programs.  Such  in-



GNU Tools                   30apr1993                           1





cpp(1)                      GNU Tools                      cpp(1)


       compatibility  would be inconvenient for users, so the GNU
       C preprocessor is configured to accept these constructs by
       default.   Strictly  speaking, to get ANSI Standard C, you
       must  use   the   options   `--ttrriiggrraapphhss',   `--uunnddeeff'   and
       `--ppeeddaannttiicc',  but  in  practice the consequences of having
       strict ANSI Standard C make it undesirable to do this.

       Most often when you use the C preprocessor  you  will  not
       have  to  invoke  it explicitly: the C compiler will do so
       automatically.  However,  the  preprocessor  is  sometimes
       useful individually.

       When  you  call the preprocessor individually, either name
       (ccpppp or ccccccpp) will do--they are completely synonymous.

       The C preprocessor expects two file  names  as  arguments,
       _i_n_f_i_l_e and _o_u_t_f_i_l_e.  The preprocessor reads _i_n_f_i_l_e togeth-
       er with any other files it specifies with `##iinncclluuddee'.  All
       the  output generated by the combined input files is writ-
       ten in _o_u_t_f_i_l_e.

       Either _i_n_f_i_l_e or _o_u_t_f_i_l_e may be `--', which as _i_n_f_i_l_e means
       to  read from standard input and as _o_u_t_f_i_l_e means to write
       to standard output.  Also, if _o_u_t_f_i_l_e or both  file  names
       are  omitted,  the  standard output and standard input are
       used for the omitted file names.

OOPPTTIIOONNSS
       Here is a table of command options accepted by the C  pre-
       processor.  These options can also be given when compiling
       a C program; they are passed along  automatically  to  the
       preprocessor when it is invoked by the compiler.

       --PP     Inhibit  generation  of  `##'-lines with line-number
              information in the output  from  the  preprocessor.
              This  might be useful when running the preprocessor
              on something that is not C code and will be sent to
              a program which might be confused by the `##'-lines.

       --CC     Do not discard comments: pass them through  to  the
              output  file.  Comments appearing in arguments of a
              macro call will be copied to the output before  the
              expansion of the macro call.

       --ttrraaddiittiioonnaall
              Try  to imitate the behavior of old-fashioned C, as
              opposed to ANSI C.

       --ttrriiggrraapphhss
              Process ANSI standard  trigraph  sequences.   These
              are  three-character  sequences,  all starting with
              `????', that are defined by ANSI C to stand for  sin-
              gle characters.  For example, `????//' stands for `\\',
              so `''????//nn''' is a character constant for a  newline.



GNU Tools                   30apr1993                           2





cpp(1)                      GNU Tools                      cpp(1)


              Strictly  speaking, the GNU C preprocessor does not
              support all programs  in  ANSI  Standard  C  unless
              `--ttrriiggrraapphhss'  is  used,  but if you ever notice the
              difference it will be with relief.

              You don't want to know any more about trigraphs.

       --ppeeddaannttiicc
              Issue warnings required by the ANSI C  standard  in
              certain  cases  such as when text other than a com-
              ment follows `##eellssee' or `##eennddiiff'.

       --ppeeddaannttiicc--eerrrroorrss
              Like `--ppeeddaannttiicc', except that errors  are  produced
              rather than warnings.

       --WWttrriiggrraapphhss
              Warn  if  any  trigraphs  are encountered (assuming
              they are enabled).

       --WWccoommmmeenntt

       --WWccoommmmeennttss
              Warn whenever a comment-start sequence `//**' appears
              in a comment.  (Both forms have the same effect).

       --WWaallll  Requests  both  `--WWttrriiggrraapphhss'  and `--WWccoommmmeenntt' (but
              not `--WWttrraaddiittiioonnaall').

       --WWttrraaddiittiioonnaall
              Warn about certain constructs that  behave  differ-
              ently in traditional and ANSI C.

       --II _d_i_r_e_c_t_o_r_y
               Add the directory _d_i_r_e_c_t_o_r_y to the end of the list
              of directories to be  searched  for  header  files.
              This  can be used to override a system header file,
              substituting your own version, since these directo-
              ries are searched before the system header file di-
              rectories.  If you use more than one  `--II'  option,
              the directories are scanned in left-to-right order;
              the standard system directories come after.

       --II--    Any directories specified with `--II' options  before
              the  `--II--' option are searched only for the case of
              `##iinncclluuddee _f_i_l_e"'; they are not searched  for  `##iinn--
              cclluuddee <<_f_i_l_e>'.

              If  additional  directories are specified with `--II'
              options after  the  `--II--',  these  directories  are
              searched for all `##iinncclluuddee' directives.

              In  addition,  the `--II--' option inhibits the use of
              the current directory as the first search directory



GNU Tools                   30apr1993                           3





cpp(1)                      GNU Tools                      cpp(1)


              for  `##iinncclluuddee  _f_i_l_e"'.  Therefore, the current di-
              rectory is searched only if it is requested explic-
              itly  with  `--II..'.  Specifying both `--II--' and `--II..'
              allows you to control precisely  which  directories
              are  searched  before the current one and which are
              searched after.

       --nnoossttddiinncc
              Do not search the standard system  directories  for
              header files.  Only the directories you have speci-
              fied with `--II' options (and the current  directory,
              if appropriate) are searched.

       --nnoossttddiinncc++++
              Do  not search for header files in the C++ specific
              standard directories, but do still search the other
              standard  directories.   (This  option is used when
              building libg++.)

       --DD _n_a_m_e
               Predefine _n_a_m_e as a macro, with definition `11'.

       --DD _n_a_m_e==_d_e_f_i_n_i_t_i_o_n
               Predefine _n_a_m_e as a macro, with definition _d_e_f_i_n_i_-
              _t_i_o_n.  There are no restrictions on the contents of
              _d_e_f_i_n_i_t_i_o_n, but if you are invoking the  preproces-
              sor from a shell or shell-like program you may need
              to use the shell's quoting syntax to protect  char-
              acters  such  as  spaces that have a meaning in the
              shell syntax.  If you use more than  one  `--DD'  for
              the  same  _n_a_m_e, the rightmost definition takes ef-
              fect.

       --UU _n_a_m_e
               Do not predefine _n_a_m_e.  If both `--UU' and `--DD'  are
              specified for one name, the `--UU' beats the `--DD' and
              the name is not predefined.

       --uunnddeeff Do not predefine any nonstandard macros.

       --AA _n_a_m_e_(vvaalluuee_)
              Assert (in the same way as the ##aasssseerrtt command) the
              predicate  _n_a_m_e  with tokenlist _v_a_l_u_e.  Remember to
              escape or quote the parentheses  on  shell  command
              lines.

              You  can use `--AA--' to disable all predefined asser-
              tions; it also undefines all predefined macros.

       --ddMM    Instead of outputting the result of  preprocessing,
              output  a  list  of  `##ddeeffiinnee' commands for all the
              macros defined during the execution of the  prepro-
              cessor,  including  predefined  macros.  This gives
              you a way of finding out what is predefined in your



GNU Tools                   30apr1993                           4





cpp(1)                      GNU Tools                      cpp(1)


              version  of  the preprocessor; assuming you have no
              file `ffoooo..hh', the command

              touch foo.h; cpp -dM foo.h

              will show the values of any predefined macros.

       --ddDD    Like `--ddMM' except in two respects: it does _n_o_t  in-
              clude  the  predefined  macros, and it outputs _b_o_t_h
              the `##ddeeffiinnee' commands and the  result  of  prepro-
              cessing.   Both  kinds of output go to the standard
              output file.


       --MM     Instead of outputting the result of  preprocessing,
              output  a rule suitable for mmaakkee describing the de-
              pendencies of the main source file.  The preproces-
              sor  outputs  one  mmaakkee  rule containing the object
              file name for that source file, a  colon,  and  the
              names of all the included files.  If there are many
              included files then the rule is split into  several
              lines using `'-newline.

              This feature is used in automatic updating of make-
              files.

       --MMMM    Like `--MM' but mention only the files included  with
              `##iinncclluuddee  "_f_i_l_e"'.   System  header files included
              with `##iinncclluuddee <_f_i_l_e>' are omitted.

       --MMDD    Like `--MM' but the dependency information is written
              to  files  with  names  made by replacing `..cc' with
              `..dd' at the end of the input file names.   This  is
              in    addition    to    compiling   the   file   as
              specified--`--MMDD' does not inhibit ordinary compila-
              tion the way `--MM' does.

              In  Mach,  you  can use the utility mmdd to merge the
              `..dd' files into a single dependency  file  suitable
              for using with the `mmaakkee' command.

       --MMMMDD   Like  `--MMDD'  except mention only user header files,
              not system header files.

       --HH     Print the name of each header file used,  in  addi-
              tion to other normal activities.

       --iimmaaccrrooss _f_i_l_e
                Process  _f_i_l_e  as input, discarding the resulting
              output, before processing the regular  input  file.
              Because  the output generated from _f_i_l_e is discard-
              ed, the only effect of `--iimmaaccrrooss _f_i_l_e' is  to  make
              the macros defined in _f_i_l_e available for use in the
              main input.  The preprocessor  evaluates  any  `--DD'



GNU Tools                   30apr1993                           5





cpp(1)                      GNU Tools                      cpp(1)


              and  `--UU'  options  on the command line before pro-
              cessing `--iimmaaccrrooss _f_i_l_e' .

       --iinncclluuddee _f_i_l_e
              Process _f_i_l_e as input, and include all the  result-
              ing  output,  before  processing  the regular input
              file.

       --iiddiirraafftteerr _d_i_r
               Add the directory _d_i_r to the second include  path.
              The  directories  on  the  second  include path are
              searched when a header file is not found in any  of
              the  directories  in the main include path (the one
              that `--II' adds to).

       --iipprreeffiixx _p_r_e_f_i_x
                Specify  _p_r_e_f_i_x  as  the  prefix  for  subsequent
              `--iiwwiitthhpprreeffiixx' options.

       --iiwwiitthhpprreeffiixx _d_i_r
                Add  a directory to the second include path.  The
              directory's name is made  by  concatenating  _p_r_e_f_i_x
              and _d_i_r, where _p_r_e_f_i_x was specified previously with
              `--iipprreeffiixx'.

       --llaanngg--cc

       --llaanngg--cc++++

       --llaanngg--oobbjjcc

       --llaanngg--oobbjjcc++++
              Specify the source language.  `--llaanngg--cc++++' makes the
              preprocessor  handle  C++  comment  syntax, and in-
              cludes extra default include directories  for  C++,
              and  `--llaanngg--oobbjjcc' enables the Objective C `##iimmppoorrtt'
              directive.  `--llaanngg--cc' explicitly turns off both  of
              these  extensions, and `--llaanngg--oobbjjcc++++' enables both.

              These options are generated by the compiler  driver
              ggcccc, but not passed from the `ggcccc' command line.

       --lliinntt  Look  for  commands to the program checker lliinntt em-
              bedded in  comments,  and  emit  them  preceded  by
              `##pprraaggmmaa  lliinntt'.   For  example,  the  comment  `//**
              NNOOTTRREEAACCHHEEDD **//' becomes `##pprraaggmmaa lliinntt NOTREACHED'.

              This option is available only when you call ccpppp di-
              rectly; ggcccc will not pass it from its command line.

       --$$     Forbid the use of `$$' in identifiers.  This is  re-
              quired  for  ANSI  conformance.   ggcccc automatically
              supplies this option to  the  preprocessor  if  you
              specify `--aannssii', but ggcccc doesn't recognize the `--$$'



GNU Tools                   30apr1993                           6





cpp(1)                      GNU Tools                      cpp(1)


              option itself--to use it without the other  effects
              of  `--aannssii', you must call the preprocessor direct-
              ly.

SSEEEE AALLSSOO
       `CCpppp' entry in iinnffoo; _T_h_e _C _P_r_e_p_r_o_c_e_s_s_o_r, Richard M. Stall-
       man.
       ggcccc(11); `GGcccc' entry in iinnffoo; _U_s_i_n_g _a_n_d _P_o_r_t_i_n_g _G_N_U _C_C _(_f_o_r
       _v_e_r_s_i_o_n _2_._0_), Richard M. Stallman.

CCOOPPYYIINNGG
       Copyright (c) 1991, 1992, 1993 Free  Software  Foundation,
       Inc.

       Permission  is  granted  to  make  and distribute verbatim
       copies of this manual provided the  copyright  notice  and
       this permission notice are preserved on all copies.

       Permission is granted to copy and distribute modified ver-
       sions of this manual under  the  conditions  for  verbatim
       copying,  provided  that the entire resulting derived work
       is distributed under the  terms  of  a  permission  notice
       identical to this one.

       Permission  is granted to copy and distribute translations
       of this manual into another language, under the above con-
       ditions for modified versions, except that this permission
       notice may be included in  translations  approved  by  the
       Free  Software  Foundation  instead of in the original En-
       glish.



























GNU Tools                   30apr1993                           7


