home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 4 / FreshFish_May-June1994.bin / bbs / gnu / gcc-2.5.8-bin.lha / man / cat1 / cpp.0 < prev    next >
Encoding:
Text File  |  1993-12-07  |  17.1 KB  |  397 lines
  1.  
  2.  
  3.  
  4. cpp(1)                      GNU Tools                      cpp(1)
  5.  
  6.  
  7. NNAAMMEE
  8.        cccp, cpp - The GNU C-Compatible Compiler Preprocessor.
  9.  
  10. SSYYNNOOPPSSIISS
  11.        ccccccpp   [--$$] [--CC] [--DD_n_a_m_e[==_d_e_f_i_n_i_t_i_o_n]] [--ddDD] [--ddMM]
  12.               [--II _d_i_r_e_c_t_o_r_y] [--HH] [--II--] [--iimmaaccrrooss _f_i_l_e]
  13.               [--iinncclluuddee _f_i_l_e] [--llaanngg--cc] [--llaanngg--cc++++] [--llaanngg--oobbjjcc]
  14.               [--llaanngg--oobbjjcc++++] [--lliinntt] [--MM] [--MMDD] [--MMMM] [--MMMMDD]
  15.               [--nnoossttddiinncc] [--PP] [--ppeeddaannttiicc] [--ppeeddaannttiicc--eerrrroorrss]
  16.               [--ttrriiggrraapphhss] [--UU_n_a_m_e] [--uunnddeeff] [--WWttrriiggrraapphhss]
  17.               [--WWccoommmmeenntt] [--WWaallll] [--WWttrraaddiittiioonnaall]
  18.               [_i_n_f_i_l_e|--] [_o_u_t_f_i_l_e|--]
  19.  
  20. DDEESSCCRRIIPPTTIIOONN
  21.        The C preprocessor is a _m_a_c_r_o _p_r_o_c_e_s_s_o_r that is used auto-
  22.        matically by the C compiler to transform your program  be-
  23.        fore  actual  compilation.  It is called a macro processor
  24.        because it allows you to define _m_a_c_r_o_s,  which  are  brief
  25.        abbreviations for longer constructs.
  26.  
  27.        The  C preprocessor provides four separate facilities that
  28.        you can use as you see fit:
  29.  
  30.        o      Inclusion of header files.  These are files of dec-
  31.               larations  that  can  be substituted into your pro-
  32.               gram.
  33.  
  34.        o      Macro expansion.  You can define _m_a_c_r_o_s, which  are
  35.               abbreviations  for  arbitrary  fragments of C code,
  36.               and then the C preprocessor will replace the macros
  37.               with their definitions throughout the program.
  38.  
  39.        o      Conditional  compilation.  Using special preproces-
  40.               sor commands, you can include or exclude  parts  of
  41.               the program according to various conditions.
  42.  
  43.        o      Line  control.   If you use a program to combine or
  44.               rearrange source files into  an  intermediate  file
  45.               which is then compiled, you can use line control to
  46.               inform the compiler of where each source line orig-
  47.               inally came from.
  48.  
  49.        C preprocessors vary in some details.  For a full explana-
  50.        tion  of  the  GNU  C  preprocessor,  see  the  iinnffoo  file
  51.        `ccpppp..iinnffoo',  or  the  manual  _T_h_e _C _P_r_e_p_r_o_c_e_s_s_o_r.  Both of
  52.        these are built from the same documentation  source  file,
  53.        `ccpppp..tteexxiinnffoo'.  The GNU C preprocessor provides a superset
  54.        of the features of ANSI Standard C.
  55.  
  56.        ANSI Standard C requires the rejection  of  many  harmless
  57.        constructs  commonly used by today's C programs.  Such in-
  58.        compatibility would be inconvenient for users, so the  GNU
  59.        C preprocessor is configured to accept these constructs by
  60.        default.  Strictly speaking, to get ANSI Standard  C,  you
  61.  
  62.  
  63.  
  64. GNU Tools                    2Jan1992                           1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. cpp(1)                      GNU Tools                      cpp(1)
  71.  
  72.  
  73.        must   use   the   options   `--ttrriiggrraapphhss',   `--uunnddeeff'  and
  74.        `--ppeeddaannttiicc', but in practice the  consequences  of  having
  75.        strict ANSI Standard C make it undesirable to do this.
  76.  
  77.        Most  often  when  you use the C preprocessor you will not
  78.        have to invoke it explicitly: the C compiler  will  do  so
  79.        automatically.   However,  the  preprocessor  is sometimes
  80.        useful individually.
  81.  
  82.        When you call the preprocessor individually,  either  name
  83.        (ccpppp or ccccccpp) will do--they are completely synonymous.
  84.  
  85.        The  C  preprocessor  expects two file names as arguments,
  86.        _i_n_f_i_l_e and _o_u_t_f_i_l_e.  The preprocessor reads _i_n_f_i_l_e togeth-
  87.        er with any other files it specifies with `##iinncclluuddee'.  All
  88.        the output generated by the combined input files is  writ-
  89.        ten in _o_u_t_f_i_l_e.
  90.  
  91.        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
  92.        to read from standard input and as _o_u_t_f_i_l_e means to  write
  93.        to  standard  output.  Also, if _o_u_t_f_i_l_e or both file names
  94.        are omitted, the standard output and  standard  input  are
  95.        used for the omitted file names.
  96.  
  97. OOPPTTIIOONNSS
  98.        Here  is a table of command options accepted by the C pre-
  99.        processor.  These options can also be given when compiling
  100.        a  C  program;  they are passed along automatically to the
  101.        preprocessor when it is invoked by the compiler.
  102.  
  103.        --PP     Inhibit generation of  `##'-lines  with  line-number
  104.               information  in  the  output from the preprocessor.
  105.               This might be useful when running the  preprocessor
  106.               on something that is not C code and will be sent to
  107.               a program which might be confused by the `##'-lines.
  108.  
  109.        --CC     Do  not  discard comments: pass them through to the
  110.               output file.  Comments appearing in arguments of  a
  111.               macro  call will be copied to the output before the
  112.               expansion of the macro call.
  113.  
  114.        --ttrriiggrraapphhss
  115.               Process ANSI standard  trigraph  sequences.   These
  116.               are  three-character  sequences,  all starting with
  117.               `????', that are defined by ANSI C to stand for  sin-
  118.               gle characters.  For example, `????//' stands for `\\',
  119.               so `''????//nn''' is a character constant for a  newline.
  120.               Strictly  speaking, the GNU C preprocessor does not
  121.               support all programs  in  ANSI  Standard  C  unless
  122.               `--ttrriiggrraapphhss'  is  used,  but if you ever notice the
  123.               difference it will be with relief.
  124.  
  125.               You don't want to know any more about trigraphs.
  126.  
  127.  
  128.  
  129.  
  130. GNU Tools                    2Jan1992                           2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. cpp(1)                      GNU Tools                      cpp(1)
  137.  
  138.  
  139.        --ppeeddaannttiicc
  140.               Issue warnings required by the ANSI C  standard  in
  141.               certain  cases  such as when text other than a com-
  142.               ment follows `##eellssee' or `##eennddiiff'.
  143.  
  144.        --ppeeddaannttiicc--eerrrroorrss
  145.               Like `--ppeeddaannttiicc', except that errors  are  produced
  146.               rather than warnings.
  147.  
  148.        --WWttrriiggrraapphhss
  149.               Warn  if  any  trigraphs  are encountered (assuming
  150.               they are enabled).
  151.  
  152.        --WWccoommmmeenntt
  153.  
  154.        --WWccoommmmeennttss
  155.               Warn whenever a comment-start sequence `//**' appears
  156.               in a comment.  (Both forms have the same effect).
  157.  
  158.        --WWaallll  Requests  both  `--WWttrriiggrraapphhss'  and `--WWccoommmmeenntt' (but
  159.               not `--WWttrraaddiittiioonnaall').
  160.  
  161.        --WWttrraaddiittiioonnaall
  162.               Warn about certain constructs that  behave  differ-
  163.               ently in traditional and ANSI C.
  164.  
  165.        --II _d_i_r_e_c_t_o_r_y
  166.                Add the directory _d_i_r_e_c_t_o_r_y to the end of the list
  167.               of directories to be  searched  for  header  files.
  168.               This  can be used to override a system header file,
  169.               substituting your own version, since these directo-
  170.               ries are searched before the system header file di-
  171.               rectories.  If you use more than one  `--II'  option,
  172.               the directories are scanned in left-to-right order;
  173.               the standard system directories come after.
  174.  
  175.        --II--    Any directories specified with `--II' options  before
  176.               the  `--II--' option are searched only for the case of
  177.               `##iinncclluuddee _f_i_l_e"'; they are not searched  for  `##iinn--
  178.               cclluuddee <<_f_i_l_e>'.
  179.  
  180.               If  additional  directories are specified with `--II'
  181.               options after  the  `--II--',  these  directories  are
  182.               searched for all `##iinncclluuddee' directives.
  183.  
  184.               In  addition,  the `--II--' option inhibits the use of
  185.               the current directory as the first search directory
  186.               for  `##iinncclluuddee  _f_i_l_e"'.  Therefore, the current di-
  187.               rectory is searched only if it is requested explic-
  188.               itly  with  `--II..'.  Specifying both `--II--' and `--II..'
  189.               allows you to control precisely  which  directories
  190.               are  searched  before the current one and which are
  191.               searched after.
  192.  
  193.  
  194.  
  195.  
  196. GNU Tools                    2Jan1992                           3
  197.  
  198.  
  199.  
  200.  
  201.  
  202. cpp(1)                      GNU Tools                      cpp(1)
  203.  
  204.  
  205.        --nnoossttddiinncc
  206.               Do not search the standard system  directories  for
  207.               header files.  Only the directories you have speci-
  208.               fied with `--II' options (and the current  directory,
  209.               if appropriate) are searched.
  210.  
  211.        --DD _n_a_m_e
  212.                Predefine _n_a_m_e as a macro, with definition `11'.
  213.  
  214.        --DD _n_a_m_e==_d_e_f_i_n_i_t_i_o_n
  215.                Predefine _n_a_m_e as a macro, with definition _d_e_f_i_n_i_-
  216.               _t_i_o_n.  There are no restrictions on the contents of
  217.               _d_e_f_i_n_i_t_i_o_n,  but if you are invoking the preproces-
  218.               sor from a shell or shell-like program you may need
  219.               to  use the shell's quoting syntax to protect char-
  220.               acters such as spaces that have a  meaning  in  the
  221.               shell  syntax.   If  you use more than one `--DD' for
  222.               the same _n_a_m_e, the rightmost definition  takes  ef-
  223.               fect.
  224.  
  225.        --UU _n_a_m_e
  226.                 Do not predefine _n_a_m_e.  If both `--UU' and `--DD' are
  227.               specified for one name, the `--UU' beats the `--DD' and
  228.               the name is not predefined.
  229.  
  230.        --uunnddeeff Do not predefine any nonstandard macros.
  231.  
  232.        --ddMM    Instead  of outputting the result of preprocessing,
  233.               output a list of `##ddeeffiinnee'  commands  for  all  the
  234.               macros  defined during the execution of the prepro-
  235.               cessor, including predefined  macros.   This  gives
  236.               you a way of finding out what is predefined in your
  237.               version of the preprocessor; assuming you  have  no
  238.               file `ffoooo..hh', the command
  239.  
  240.               touch foo.h; cpp -dM foo.h
  241.  
  242.               will show the values of any predefined macros.
  243.  
  244.        --ddDD    Like  `--ddMM' except in two respects: it does _n_o_t in-
  245.               clude the predefined macros, and  it  outputs  _b_o_t_h
  246.               the  `##ddeeffiinnee'  commands  and the result of prepro-
  247.               cessing.  Both kinds of output go to  the  standard
  248.               output file.
  249.  
  250.  
  251.        --MM     Instead  of outputting the result of preprocessing,
  252.               output a rule suitable for mmaakkee describing the  de-
  253.               pendencies of the main source file.  The preproces-
  254.               sor outputs one mmaakkee  rule  containing  the  object
  255.               file  name  for  that source file, a colon, and the
  256.               names of all the included files.  If there are many
  257.               included  files then the rule is split into several
  258.               lines using `'-newline.
  259.  
  260.  
  261.  
  262. GNU Tools                    2Jan1992                           4
  263.  
  264.  
  265.  
  266.  
  267.  
  268. cpp(1)                      GNU Tools                      cpp(1)
  269.  
  270.  
  271.               This feature is used in automatic updating of make-
  272.               files.
  273.  
  274.        --MMMM    Like  `--MM' but mention only the files included with
  275.               `##iinncclluuddee "_f_i_l_e"'.  System  header  files  included
  276.               with `##iinncclluuddee <_f_i_l_e>' are omitted.
  277.  
  278.        --MMDD    Like `--MM' but the dependency information is written
  279.               to files with names made  by  replacing  `..cc'  with
  280.               `..dd'  at  the end of the input file names.  This is
  281.               in   addition   to   compiling    the    file    as
  282.               specified--`--MMDD' does not inhibit ordinary compila-
  283.               tion the way `--MM' does.
  284.  
  285.               In Mach, you can use the utility mmdd  to  merge  the
  286.               `..dd'  files  into a single dependency file suitable
  287.               for using with the `mmaakkee' command.
  288.  
  289.        --MMMMDD   Like `--MMDD' except mention only user  header  files,
  290.               not system header files.
  291.  
  292.        --HH     Print  the  name of each header file used, in addi-
  293.               tion to other normal activities.
  294.  
  295.        --iimmaaccrrooss _f_i_l_e
  296.                Process _f_i_l_e as input,  discarding  the  resulting
  297.               output,  before  processing the regular input file.
  298.               Because the output generated from _f_i_l_e is  discard-
  299.               ed,  the  only effect of `--iimmaaccrrooss _f_i_l_e' is to make
  300.               the macros defined in _f_i_l_e available for use in the
  301.               main  input.   The  preprocessor evaluates any `--DD'
  302.               and `--UU' options on the command  line  before  pro-
  303.               cessing `--iimmaaccrrooss _f_i_l_e' .
  304.  
  305.        --iinncclluuddee _f_i_l_e
  306.               Process  _f_i_l_e as input, and include all the result-
  307.               ing output, before  processing  the  regular  input
  308.               file.
  309.  
  310.        --llaanngg--cc
  311.  
  312.        --llaanngg--cc++++
  313.  
  314.        --llaanngg--oobbjjcc
  315.  
  316.        --llaanngg--oobbjjcc++++
  317.               Specify the source language.  `--llaanngg--cc++++' makes the
  318.               preprocessor handle C++  comment  syntax,  and  in-
  319.               cludes  extra  default include directories for C++,
  320.               and `--llaanngg--oobbjjcc' enables the Objective C  `##iimmppoorrtt'
  321.               directive.   `--llaanngg--cc' explicitly turns off both of
  322.               these extensions, and `--llaanngg--oobbjjcc++++' enables  both.
  323.  
  324.               These  options are generated by the compiler driver
  325.  
  326.  
  327.  
  328. GNU Tools                    2Jan1992                           5
  329.  
  330.  
  331.  
  332.  
  333.  
  334. cpp(1)                      GNU Tools                      cpp(1)
  335.  
  336.  
  337.               ggcccc, but not passed from the `ggcccc' command line.
  338.  
  339.        --lliinntt  Look for commands to the program checker  lliinntt  em-
  340.               bedded  in  comments,  and  emit  them  preceded by
  341.               `##pprraaggmmaa  lliinntt'.   For  example,  the  comment  `//**
  342.               NNOOTTRREEAACCHHEEDD **//' becomes `##pprraaggmmaa lliinntt NOTREACHED'.
  343.  
  344.               This option is available only when you call ccpppp di-
  345.               rectly; ggcccc will not pass it from its command line.
  346.  
  347.        --$$     Forbid  the use of `$$' in identifiers.  This is re-
  348.               quired for  ANSI  conformance.   ggcccc  automatically
  349.               supplies  this  option  to  the preprocessor if you
  350.               specify `--aannssii', but ggcccc doesn't recognize the `--$$'
  351.               option  itself--to use it without the other effects
  352.               of `--aannssii', you must call the preprocessor  direct-
  353.               ly.
  354.  
  355. SSEEEE AALLSSOO
  356.        `CCpppp' entry in iinnffoo; _T_h_e _C _P_r_e_p_r_o_c_e_s_s_o_r, Richard M. Stall-
  357.        man.
  358.        ggcccc(11); `GGcccc' entry in iinnffoo; _U_s_i_n_g _a_n_d _P_o_r_t_i_n_g _G_N_U _C_C _(_f_o_r
  359.        _v_e_r_s_i_o_n _2_._0_), Richard M. Stallman.
  360.  
  361. CCOOPPYYIINNGG
  362.        Copyright (c) 1991, 1992 Free Software Foundation, Inc.
  363.  
  364.        Permission  is  granted  to  make  and distribute verbatim
  365.        copies of this manual provided the  copyright  notice  and
  366.        this permission notice are preserved on all copies.
  367.  
  368.        Permission is granted to copy and distribute modified ver-
  369.        sions of this manual under  the  conditions  for  verbatim
  370.        copying,  provided  that the entire resulting derived work
  371.        is distributed under the  terms  of  a  permission  notice
  372.        identical to this one.
  373.  
  374.        Permission  is granted to copy and distribute translations
  375.        of this manual into another language, under the above con-
  376.        ditions for modified versions, except that this permission
  377.        notice may be included in  translations  approved  by  the
  378.        Free  Software  Foundation  instead of in the original En-
  379.        glish.
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394. GNU Tools                    2Jan1992                           6
  395.  
  396.  
  397.