home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 342b.lha / cpp / org / cpp.mem < prev    next >
Encoding:
Text File  |  1990-01-26  |  11.8 KB  |  287 lines
  1.  
  2.  
  3.  
  4.  
  5.         1.0  C Pre-Processor
  6.  
  7.  
  8.  
  9.                                     *******
  10.                                     * cpp *
  11.                                     *******
  12.  
  13.  
  14.  
  15.         NAME:   cpp -- C Pre-Processor
  16.  
  17.         SYNOPSIS:
  18.  
  19.                 cpp [-options] [infile [outfile]]
  20.  
  21.         DESCRIPTION:
  22.  
  23.                 CPP reads a C source file, expands  macros  and  include
  24.                 files,  and writes an input file for the C compiler.  If
  25.                 no file arguments are given, CPP reads  from  stdin  and
  26.                 writes  to  stdout.   If  one file argument is given, it
  27.                 will define the input file,  while  two  file  arguments
  28.                 define  both  input and output files.  The file name "-"
  29.                 is a synonym for stdin or stdout as appropriate.
  30.  
  31.                 The following options are  supported.   Options  may  be
  32.                 given in either case.
  33.  
  34.                 -C              If set, source-file comments are written
  35.                                 to  the  output  file.   This allows the
  36.                                 output of CPP to be used as the input to
  37.                                 a  program,  such  as lint, that expects
  38.                                 commands embedded in specially-formatted
  39.                                 comments.
  40.  
  41.                 -Dname=value    Define the name  as  if  the  programmer
  42.                                 wrote
  43.  
  44.                                     #define name value
  45.  
  46.                                 at the start  of  the  first  file.   If
  47.                                 "=value"  is  not  given, a value of "1"
  48.                                 will be used.
  49.  
  50.                                 On non-unix systems, all alphabetic text
  51.                                 will be forced to upper-case.
  52.  
  53.                 -E              Always return "success" to the operating
  54.                                 system,  even  if  errors were detected.
  55.                                 Note that some fatal errors, such  as  a
  56.                                 missing  #include  file,  will terminate
  57.                                 CPP, returning "failure" even if the  -E
  58.                                 option is given.
  59.                                                                           Page 2
  60.         cpp     C Pre-Processor
  61.  
  62.  
  63.                 -Idirectory     Add  this  directory  to  the  list   of
  64.                                 directories  searched for #include "..."
  65.                                 and #include <...> commands.  Note  that
  66.                                 there  is  no space between the "-I" and
  67.                                 the directory string.  More than one  -I
  68.                                 command   is   permitted.   On  non-Unix
  69.                                 systems   "directory"   is   forced   to
  70.                                 upper-case.
  71.  
  72.                 -N              CPP  normally  predefines  some  symbols
  73.                                 defining   the   target   computer   and
  74.                                 operating system.  If -N  is  specified,
  75.                                 no symbols will be predefined.  If -N -N
  76.                                 is  specified,  the   "always   present"
  77.                                 symbols,    __LINE__,    __FILE__,   and
  78.                                 __DATE__ are not defined.
  79.  
  80.                 -Stext          CPP normally assumes that  the  size  of
  81.                                 the  target  computer's  basic  variable
  82.                                 types is the same as the size  of  these
  83.                                 types  of  the host computer.  (This can
  84.                                 be  overridden  when  CPP  is  compiled,
  85.                                 however.)  The  -S option allows dynamic
  86.                                 respecification of these values.  "text"
  87.                                 is  a  string  of  numbers, separated by
  88.                                 commas, that  specifies  correct  sizes.
  89.                                 The sizes must be specified in the exact
  90.                                 order:
  91.  
  92.                                     char short int long float double
  93.  
  94.                                 If you specify the option as  "-S*text",
  95.                                 pointers   to   these   types   will  be
  96.                                 specified.   -S*  takes  one  additional
  97.                                 argument  for  pointer to function (e.g.
  98.                                 int (*)())
  99.  
  100.                                 For   example,    to    specify    sizes
  101.                                 appropriate  for  a  PDP-11,  you  would
  102.                                 write:
  103.  
  104.                                        c s i l f d func
  105.                                      -S1,2,2,2,4,8,
  106.                                     -S*2,2,2,2,2,2,2
  107.  
  108.                                 Note that all values must be specified.
  109.  
  110.                 -Uname          Undefine the name as if
  111.  
  112.                                     #undef name
  113.  
  114.                                 were given.  On non-Unix systems, "name"
  115.                                 will be forced to upper-case.
  116.                                                                           Page 3
  117.         cpp     C Pre-Processor
  118.  
  119.  
  120.                 -Xnumber        Enable debugging code.  If no  value  is
  121.                                 given,  a value of 1 will be used.  (For
  122.                                 maintenence of CPP only.)
  123.  
  124.  
  125.         PRE-DEFINED VARIABLES:
  126.  
  127.                 When CPP begins processing, the following variables will
  128.                 have been defined (unless the -N option is specified):
  129.  
  130.                 Target computer (as appropriate):
  131.  
  132.                     pdp11, vax, M68000 m68000 m68k
  133.  
  134.                 Target operating system (as appropriate):
  135.  
  136.                     rsx, rt11, vms, unix
  137.  
  138.                 Target compiler (as appropriate):
  139.  
  140.                     decus, vax11c
  141.  
  142.                 The implementor may add definitions to this  list.   The
  143.                 default  definitions  match  the  definition of the host
  144.                 computer, operating system, and C compiler.
  145.  
  146.                 The following are always available unless undefined  (or
  147.                 -N was specified twice):
  148.  
  149.                     __FILE__    The  input  (or  #include)  file   being
  150.                                 compiled (as a quoted string).
  151.  
  152.                     __LINE__    The line number being compiled.
  153.  
  154.                     __DATE__    The date and time of  compilation  as  a
  155.                                 Unix  ctime  quoted string (the trailing
  156.                                 newline is removed).  Thus,
  157.  
  158.                                     printf("Bug at line %s,", __LINE__);
  159.                                     printf(" source file %s", __FILE__);
  160.                                     printf(" compiled on %s", __DATE__);
  161.  
  162.  
  163.         DRAFT PROPOSED ANSI STANDARD CONSIDERATIONS:
  164.  
  165.                 The current  version  of  the  Draft  Proposed  Standard
  166.                 explicitly  states  that  "readers  are requested not to
  167.                 specify or claim conformance to this draft." Readers and
  168.                 users  of  Decus  CPP  should  not assume that Decus CPP
  169.                 conforms to the standard, or that it will conform to the
  170.                 actual C Language Standard.
  171.  
  172.                 When CPP is itself compiled, many features of the  Draft
  173.                 Proposed  Standard  that  are incompatible with existing
  174.                                                                           Page 4
  175.         cpp     C Pre-Processor
  176.  
  177.  
  178.                 preprocessors may be  disabled.   See  the  comments  in
  179.                 CPP's source for details.
  180.  
  181.                 The latest version of the Draft  Proposed  Standard  (as
  182.                 reflected in Decus CPP) is dated November 12, 1984.
  183.  
  184.                 Comments are removed from the input text.   The  comment
  185.                 is  replaced by a single space character.  The -C option
  186.                 preserves comments, writing them to the output file.
  187.  
  188.                 The '$' character is considered to be a letter.  This is
  189.                 a permitted extension.
  190.  
  191.                 The following new features of C are processed by CPP:
  192.  
  193.                     #elif expression (#else #if)
  194.                     '\xNNN' (Hexadecimal constant)
  195.                     '\a' (Ascii BELL)
  196.                     '\v' (Ascii Vertical Tab)
  197.                     #if defined NAME 1 if defined, 0 if not
  198.                     #if defined (NAME) 1 if defined, 0 if not
  199.                     #if sizeof (basic type)
  200.                     unary +
  201.                     123U, 123LU Unsigned ints and longs.
  202.                     12.3L Long double numbers
  203.                     token#token Token concatenation
  204.                     #include token Expands to filename
  205.  
  206.                 The Draft Proposed Standard has  extended  C,  adding  a
  207.                 constant string concatenation operator, where
  208.  
  209.                     "foo" "bar"
  210.  
  211.                 is regarded as the single string "foobar".   (This  does
  212.                 not  affect  CPP's  processing but does permit a limited
  213.                 form of macro argument substitution into strings as will
  214.                 be discussed.)
  215.  
  216.                 The Standard Committee plans to add token  concatenation
  217.                 to  #define command lines.  One suggested implementation
  218.                 is as follows:  the sequence "Token1#Token2" is  treated
  219.                 as  if  the programmer wrote "Token1Token2".  This could
  220.                 be used as follows:
  221.  
  222.                     #line 123
  223.                     #define ATLINE foo#__LINE__
  224.  
  225.                 ATLINE would be defined as foo123.
  226.  
  227.                 Note that "Token2" must either have  the  format  of  an
  228.                 identifier or be a string of digits.  Thus, the string
  229.  
  230.                     #define ATLINE foo#1x3
  231.                                                                           Page 5
  232.         cpp     C Pre-Processor
  233.  
  234.  
  235.                 generates two tokens:  "foo1" and "x3".
  236.  
  237.                 If the tokens T1 and T2 are concatenated into  T3,  this
  238.                 implementation operates as follows:
  239.  
  240.                   1. Expand T1 if it is a macro.
  241.                   2. Expand T2 if it is a macro.
  242.                   3. Join the tokens, forming T3.
  243.                   4. Expand T3 if it is a macro.
  244.  
  245.                 A macro formal parameter  will  be  substituted  into  a
  246.                 string or character constant if it is the only component
  247.                 of that constant:
  248.  
  249.                     #define VECSIZE 123
  250.                     #define vprint(name, size) \
  251.                       printf("name" "[" "size" "] = {\n")
  252.                       ... vprint(vector, VECSIZE);
  253.  
  254.                 expands (effectively) to
  255.  
  256.                       vprint("vector[123] = {\n");
  257.  
  258.                 Note that  this  will  be  useful  if  your  C  compiler
  259.                 supports  the  new  string concatenation operation noted
  260.                 above.  As implemented here, if you write
  261.  
  262.                     #define string(arg) "arg"
  263.                       ... string("foo") ...
  264.  
  265.                 This implementation generates  "foo",  rather  than  the
  266.                 strictly  correct  ""foo"" (which will probably generate
  267.                 an error message).  This is, strictly speaking, an error
  268.                 in CPP and may be removed from future releases.
  269.  
  270.         ERROR MESSAGES:
  271.  
  272.                 Many.  CPP prints warning or error messages if  you  try
  273.                 to     use     multiple-byte     character     constants
  274.                 (non-transportable) if you #undef a symbol that was  not
  275.                 defined,  or  if  your  program  has  potentially nested
  276.                 comments.
  277.  
  278.         AUTHOR:
  279.  
  280.                 Martin Minow
  281.  
  282.         BUGS:
  283.  
  284.                 The #if expression processor uses signed integers  only.
  285.                 I.e, #if 0xFFFFu < 0 may be TRUE.
  286.  
  287.