Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/342b.lha/cpp/cpp.man

Text File | 1990-01-26 | 11KB | 397 lines

     CPP(1)                Amiga Programmer's Manual                 CPP(1)



     ›1mNAME
      cpp ›0m- C Pre Processor. Macro-preprocess C programs.

     ›1mSYNOPSIS
      ›0mcpp [-options] [infile [outfile]]

     ›1mDESCRIPTION
      ›0mCPP reads a C source file, expands macros and include files,
      and writes  an  input  file  for the C compiler.  If no file
      arguments are given, CPP reads  from    stdin  and  writes  to
      stdout.   If    one file argument is given, it will define the
      input file, while two file arguments define both  input  and
      output files.    The file name "-" is a synonym for stdin or
      stdout as appropriate.

      The following options are supported.    Options may  be  given
      in either case.

      -C   If  set, source-file comments are written to the output
           file.  This allows the output of CPP to be used as  the
           input to a program, such as lint, that expects commands
           embedded in specially-formatted comments.

      -Dname=value
           Define the name as if the programmer wrote

           #define name value

           at the  start  of  the  first file.  If "=value" is not
           given, a value of "1" will be used.

           On non-unix and non-amiga systems, all alphabetic  text
           will be forced to upper-case.

      -E   Always  return  "success" to the operating system, even
           if errors were detected.  Note that some fatal  errors,
           such  as  a  missing #include file, will terminate CPP,
           returning "failure" even if the -E option is given.

      -Idirectory
           Add this directory to the list of directories  searched
           for #include "..."   and #include <...> commands.  Note
           that there  is  no  space  between  the    "-I"  and  the
           directory string.      More  than  one  -I  command  is
           permitted.  On non-Unix systems "directory"  is  forced
           to upper-case.

      -N   CPP  normally  predefines  some    symbols  defining  the
           target computer    and  operating    system.    If  -N   is
           specified, no  symbols will be predefined.  If -N -N is
           specified,  the    "always  present"  symbols,  __LINE__,
           __FILE__, __TIME__ and __DATE__ are not defined.

      -Stext
           CPP  normally  assumes  that  the  size    of  the target
           computer's basic variable types is the same as the size
           of these types of the host  computer.    (This  can  be


     1st PDC distribution          -1-


     CPP(1)                Amiga Programmer's Manual                 CPP(1)


           overridden  when  CPP  is  compiled,  however.)    The -S
           option allows dynamic respecification of these  values.
           "text"  is  a  string  of numbers, separated by commas,
           that specifies  correct    sizes.      The  sizes  must  be
           specified in the exact order:

           char short int long float double

           If  you    specify  the  option as "-S*text", pointers to
           these types  will  be  specified.     -S*   takes   one
           additional argument  for pointer to function (e.g.  int
           (*)())

           For example, to specify sizes appropriate for a PDP-11,
           you would write:

              c s i l f d func
            -S1,2,2,2,4,8,
           -S*2,2,2,2,2,2,2

           Note that all values must be specified.
           ›3mNote also that this is not  allowed  by  the    11-Jan-88
           Draft,  and  therefore  has  made  into    an option when
           compiling Cpp.

      ›0m-Uname
           Undefine the name as if

           #undef name

           were given.  On non-Unix systems, "name" will be forced
           to upper-case.

      -Xnumber
           Enable debugging code.  If no value is given,  a  value
           of 1 will be used.  (For maintenence of CPP only.)

     ›1mPre›0m-›1mDefined Variables
      ›0mWhen  CPP    begins    processing,  the following variables will
      have been defined (unless the -N option is specified):

      Target computer (as appropriate):

          pdp11, vax, M68000 m68000 m68k, amiga m68000

      Target operating system (as appropriate):

          rsx, rt11, vms, unix, amigados

      Target compiler (as appropriate):

          decus, vax11c, pdc __PDC__

      The implementor may add  definitions    to  this  list.    The
      default   definitions  match    the  definition  of  the  host
      computer, operating system, and C compiler.

      The following are always available unless undefined  (or  -N


     1st PDC distribution          -2-


     CPP(1)                Amiga Programmer's Manual                 CPP(1)


      was specified twice):

          __FILE__    The  input (or #include) file being compiled
              (as a quoted string).
          __LINE__    The line number being compiled.
          __DATE__    The date of compilation as a    quoted    string
              of the format "Mmm dd yyyy".
          __TIME__    The  time  of  the start of compilation as a
              quoted  string  of  the  format  "hh:mm:ss".
              Thus,
                  printf("Bug at line %s,", __LINE__);
                  printf(" source file %s", __FILE__);
                  printf(" compiled on %s %s",   __DATE__,
              __TIME__);

     ›1mSupported directives
          ›0m#assert <expression>
          #define <token> <replacement>
          #elif <expression>
          #else <expression>
          #endif
          #error
          #if <expression>
          #ifdef <token>
          #ifndef <token>
          #include <filename>
          #line <number> <filename>
          #pragma <anything>
          #undef <token>
          #debug
          #nodebug

      Unsupported # commands are copied verbatim into the  output,
      so that maybe the compiler knows what to do with them.

     ›1mDraft Proposed Ansi Standard Considerations
      ›0mThe   current   version   of  the    Draft  Proposed  Standard
      explicitly states that "readers are requested not to specify
      or claim conformance to this draft."  Readers and  users  of
      Decus  CPP  should not assume that Decus CPP conforms to the
      standard, or that it will conform to the actual  C  Language
      Standard.

      When    CPP  is  itself  compiled,  many features of the Draft
      Proposed  Standard  that  are  incompatible  with   existing
      preprocessors may  be  disabled.   See the comments in CPP's
      source for details.

      The latest  version  of  the    Draft  Proposed  Standard  (as
      reflected in Decus CPP) is dated November 12, 1984, and bits
      from K&R V2 are put in by Ois.

      Comments are    removed  from  the input text.    The comment is
      replaced by  a  single  space  character.    The  -C    option
      preserves comments, writing them to the output file.

      The '$'  character  is considered to be a letter.  This is a
      permitted extension.


     1st PDC distribution          -3-


     CPP(1)                Amiga Programmer's Manual                 CPP(1)



      The following new features of C are processed by CPP:

          #if, #elif
          #elif expression          (#else #if)
          '\xNNN'                 (Hexadecimal constant)
          '\a'                    (Ascii BELL)
          '\v'                    (Ascii Vertical Tab)
          #if defined NAME          1 if defined, 0 if not
          #if defined (NAME)      1 if defined, 0 if not
          #if sizeof (basic type)
          #error              Generates error message
          unary +
          123U, 123LU          Unsigned ints and longs.
          12.3L              Long double numbers
          token##token          Token concatenation in macros
          #macro-formal          String generation in macros
          #include token          Expands to filename

      The  Draft  Proposed    Standard  has  extended  C,  adding  a
      constant string concatenation operator, where

          "foo" "bar"

      is  regarded    as  the single string "foobar". (This does not
      affect CPP's processing but does permit a  limited  form  of
      macro   argument   substitution  into  strings  as  will  be
      discussed.)

      The Standard Committee plans to add token  concatenation  to
      #define command  lines.   One suggested implementation is as
      follows: the sequence "Token1 ## Token2" is  treated  as  if
      the programmer wrote "Token1Token2".

      This could be used as follows:

          #line 123
          #define ATLINE foo ## __LINE__

      ATLINE would be defined as foo123.

      Note    that  "Token1" and "Token2" both must be valid tokens,
      but the concatenation of their expanded forms may not  be  a
      _single_ valid  token.    In    that  case, K&R state that the
      behaviour is undefined.  So if you wish to make portable use
      of this facility, do not do the following:

          #define cat(x, y) x ## y
          cat(foo, 1.23)

      which will produce

          foo1.23

      and that is not a single token.

      If the tokens T1 and    T2  are  concatenated  into  T3,  this
      implementation operates as follows:


     1st PDC distribution          -4-


     CPP(1)                Amiga Programmer's Manual                 CPP(1)



        1. Expand T1 if it is a macro.
        2. Expand T2 if it is a macro.
        3. Join the tokens, forming T3.
        4. Rescan  T3,  looking  for  tokens, that may be expanded
      again.

        A macro formal parameter will be  substituted  into  a
      string  or character constant if it is the only component of
      that constant:

          #define VECSIZE 123
          #define vprint(name, size) \
        printf("name" "[" "size" "] = {\n")
        ... vprint(vector, VECSIZE);

      expands (effectively) to

        vprint("vector[123] = {\n");

      Note that this will be useful if your  C  compiler  supports
      the new  string  concatenation  operation  noted  above.  As
      implemented here, if you write

          #define string(arg) "arg"
        ... string("foo") ...

      This    implementation    generates  "foo",  rather   than   the
      strictly  correct  ""foo""  (which will probably generate an
      error message).  This is, strictly speaking, an error in CPP
      and may be removed from future  releases.    ›3mNote    that  the
      above  feature  of  replacing macro formals inside quotes is
      non-standard.  The Committee thought    the  following    to  be
      better:

      ›0mIf  a macro formal argument is immediately preceeded by a #,
      the argument supplied  when  expanding  the  macro  will  be
      surrounded  by  double  quotes,  and    each  double  quote or
      backslash will be preceeded by a backslash.  An  example  of
      this would be:

          #define string(arg) #arg
        ... string(foo) ...

      which  produces  "foo". Note that this feature is useless if
      you want your string to contain an odd number of quotes:

          string(Hello");

      will     produce   an    error    message,   complaining     about
      unterminated strings.


     ›1mError messages
      ›0mMany. CPP prints warning or error messages if you try to use
      multiple-byte character constants (non-transportable) if you
      #undef a symbol that was not defined, or if your program has
      potentially nested comments.


     1st PDC distribution          -5-


     CPP(1)                Amiga Programmer's Manual                 CPP(1)


     ›1mAuthor
      ›0mMartin Minow, minor changes by RMS, FNF, OIS.

     ›1mBugs
      ›0mThe  #if  expression  processor  uses  signed integers only.
      I.e, #if 0xFFFFu < 0 may be TRUE.






















































     1st PDC distribution          -6-