💾 Archived View for mirrors.apple2.org.za › active › ftp.apple.asimov.net › images › programming › c… captured on 2024-12-18 at 00:01:48.

View Raw

More Information

-=-=-=-=-=-=-

        1.0  C Pre-Processor



                                    *******
                                    * cpp *
                                    *******



        NAME:   cpp -- C Pre-Processor

        SYNOPSIS:

                cpp [-options] [infile [outfile]]

        DESCRIPTION:

                CPP 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 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.
                                                                          Page 2
        cpp     C Pre-Processor


                -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__,   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  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.

                -Uname          Undefine the name as if

                                    #undef name

                                were given.  On non-Unix systems, "name"
                                will be forced to upper-case.
                                                                          Page 3
        cpp     C Pre-Processor


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


        PRE-DEFINED VARIABLES:

                When 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

                Target operating system (as appropriate):

                    rsx, rt11, vms, unix

                Target compiler (as appropriate):

                    decus, vax11c

                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 was specified twice):

                    __FILE__    The  input  (or  #include)  file   being
                                compiled (as a quoted string).

                    __LINE__    The line number being compiled.

                    __DATE__    The date and time of  compilation  as  a
                                Unix  ctime  quoted string (the trailing
                                newline is removed).  Thus,

                                    printf("Bug at line %s,", __LINE__);
                                    printf(" source file %s", __FILE__);
                                    printf(" compiled on %s", __DATE__);


        DRAFT PROPOSED ANSI STANDARD CONSIDERATIONS:

                The 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
                                                                          Page 4
        cpp     C Pre-Processor


                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.

                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.

                The following new features of C are processed by CPP:

                    #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)
                    unary +
                    123U, 123LU Unsigned ints and longs.
                    12.3L Long double numbers
                    token#token Token concatenation
                    #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 "Token2" must either have  the  format  of  an
                identifier or be a string of digits.  Thus, the string

                    #define ATLINE foo#1x3
                                                                          Page 5
        cpp     C Pre-Processor


                generates two tokens:  "foo1" and "x3".

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

                  1. Expand T1 if it is a macro.
                  2. Expand T2 if it is a macro.
                  3. Join the tokens, forming T3.
                  4. Expand T3 if it is a macro.

                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.

        ERROR MESSAGES:

                Many.  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.

        AUTHOR:

                Martin Minow

        BUGS:

                The #if expression processor uses signed integers  only.
                I.e, #if 0xFFFFu < 0 may be TRUE.