Return to README CVS log

Up to [CSRG BSD Unix] / 3BSD / cmd / cpp

Annotation of 3BSD/cmd/cpp/README, revision 1.1

1.1     ! root        1: August 25, 1978
        !             2: 
        !             3: Files in this directory form the C preprocessor, which handles '#include'
        !             4: files and macro definition and expansion for the C compiler.
        !             5: This new version was written by John F. Reiser and is from 5 to 12
        !             6: times faster (on UNIX systems) than the old.
        !             7: 
        !             8: To create the executable file 'cpp' in the current directory:
        !             9:        make
        !            10: 
        !            11: To install the preprocessor 'cpp' so it will be used by the C compiler:
        !            12:        : safety first: backup the existing version
        !            13:        cp /lib/cpp /lib/ocpp
        !            14:        : install the new version
        !            15:        cp cpp /lib/cpp
        !            16: 
        !            17: Invocation
        !            18:        cpp [-CEPR] [-Dname] ... [-Dname=def] ... [-Idirectory] ...
        !            19:                [-Uname] ... [<infile>] [<outfile>]
        !            20: 
        !            21:        If there are two non-flag arguments then the first is the name of the
        !            22:        input file and the second is the name of the output file.  If there is
        !            23:        one non-flag argument then it is the name of the input file and the
        !            24:        output is written on the standard output.  If there are no non-flag
        !            25:        arguments then the input is taken from the standard input and the output
        !            26:        is written on the standard output.  Flag arguments are:
        !            27: 
        !            28:                -C      retain comments in output
        !            29:                -Dname  define name as "1"
        !            30:                -Dname=def      define name as def
        !            31:                -E      ignored
        !            32:                -Idirectory     add directory to search list for #include files
        !            33:                -P      don't insert lines "# 12 \"foo.c\"" into output
        !            34:                -R      allow recursive macros
        !            35:                -Uname  undefine name
        !            36:                
        !            37: Documentation clarifications:
        !            38:        Symbols defined on the command line by "-Dfoo" are defined as "1",
        !            39:                i.e., as if they had been defined by "#define foo 1" or "-Dfoo=1".
        !            40:        The directory search order for #include files is
        !            41:                1) the directory of the file which contains the #include request
        !            42:                   (e.g. #include is relative to the file being scanned when
        !            43:                   the request is made)
        !            44:                2) the directories specified by -I, in left-to-right order
        !            45:                3) the standard directory(s) (which for UNIX is /usr/include)
        !            46:        An unescaped linefeed (the single character "\n") terminates a
        !            47:                character constant or quoted string.
        !            48:        An escaped linefeed (the two-character sequence "\\\n") may be
        !            49:                used in the body of a '#define' statement to continue
        !            50:                the definition onto the next line.  The escaped linefeed is
        !            51:                not included in the macro body.
        !            52:        Comments are uniformly removed (except if the argument -C is specified).
        !            53:                They are also ignored, except that a comment terminates a token.
        !            54:                Thus "foo/* la di da */bar" may expand 'foo' and 'bar' but
        !            55:                will never expand 'foobar'.  If neither 'foo' nor 'bar' is a
        !            56:                macro then the output is "foobar", even if 'foobar'
        !            57:                is defined as something else.  The file
        !            58:                        #define foo(a,b)b/**/a
        !            59:                        foo(1,2)
        !            60:                produces "21" because the comment causes a break which enables
        !            61:                the recognition of 'b' and 'a' as formals in the string "b/**/a".
        !            62:        Macro formal parameters are recognized in '#define' bodies even inside
        !            63:                character constants and quoted strings.  The output from
        !            64:                        #define foo(a) '\a'
        !            65:                        foo(bar)
        !            66:                is the seven characters " '\\bar'".  Macro names are not recognized
        !            67:                inside character constants or quoted strings during the regular scan.
        !            68:                Thus
        !            69:                        #define foo bar
        !            70:                        printf("foo");
        !            71:                does not expand 'foo' in the second line, because it is inside
        !            72:                a quoted string which is not part of a '#define' macro definition.
        !            73:        Macros are not expanded while processing a '#define' or '#undef'.
        !            74:                Thus
        !            75:                        #define foo bletch
        !            76:                        #define bar foo
        !            77:                        #undef foo
        !            78:                        bar
        !            79:                produces "foo".  The token appearing immediately after a
        !            80:                '#ifdef' or '#ifndef' is not expanded (of course!).
        !            81:        Macros are not expanded during the scan which determines the actual
        !            82:                parameters to another macro call.  Thus
        !            83:                        #define foo(a,b)b a
        !            84:                        #define bar hi
        !            85:                        foo(bar,
        !            86:                        #define bar bye
        !            87:                        )
        !            88:                produces " bye" (and warns about the redefinition of 'bar').
        !            89: 
        !            90: There are some differences between the new and the old preprocessor.
        !            91: Bugs fixed:
        !            92:        "1.e4" is recognized as a floating-point number, rather than as an
        !            93:                opportunity to expand the possible macro name "e4".
        !            94:        Any kind and amount of white space (space, tab, linefeed, vertical tab,
        !            95:                formfeed, carriage return) is allowed between a macro name and
        !            96:                the left parenthesis which introduces its actual parameters.
        !            97:        The comma operator is legal in preprocessor '#if' statements.
        !            98:        Macros with parameters are legal in preprocessor '#if' statements.
        !            99:        Single-character character constants are legal in preprocessor '#if' statements.
        !           100:        Linefeeds are put out in the proper place when a multiline comment
        !           101:                is not passed through to the output.
        !           102:        The following example expands to "# # #" :
        !           103:                #define foo #
        !           104:                foo foo foo
        !           105:        If the -R flag is not specified then the invocation of some recursive
        !           106:                macros is trapped and the recursion forcibly terminated with an
        !           107:                error message.  The recursions that are trapped are the ones
        !           108:                in which the nesting level is non-decreasing from some point on.
        !           109:                In particular,
        !           110:                        #define a a
        !           111:                        a
        !           112:                will be detected.  (Use "#undef a" if that is what you want.)
        !           113:                The recursion
        !           114:                        #define a c b
        !           115:                        #define b c a
        !           116:                        #define c foo
        !           117:                        a
        !           118:                will not be detected because the nesting level decreases after
        !           119:                each expansion of "c".
        !           120:        The -R flag specifically allows recursive macros and recursion will
        !           121:                be strictly obeyed (to the extent that space is available).
        !           122:                Assuming that -R is specified:
        !           123:                        #define a a
        !           124:                        a
        !           125:                causes an infinite loop with very little output.  The tail recursion
        !           126:                        #define a <b
        !           127:                        #define b >a
        !           128:                        a
        !           129:                causes the string "<>" to be output infinitely many times.  The
        !           130:                non-tail recursion
        !           131:                        #define a b>
        !           132:                        #define b a<
        !           133:                        a
        !           134:                complains "too much pushback", dumps the pushback, and continues
        !           135:                (again, infinitely).
        !           136:        
        !           137: Stylistic choice:
        !           138:        Nothing (not even linefeeds) is output while a false '#if', '#ifdef',
        !           139:                or '#ifndef' is in effect.  Thus when all conditions become true
        !           140:                a line of the form "# 12345 \"foo.c\"" is output (unless -P).
        !           141:        Error and warning messages always appear on standard error (file
        !           142:                descriptor 2).
        !           143:        Mismatch between the number of formals and actuals in a macro call
        !           144:                produces only a warning, and not an error.  Excess actuals
        !           145:                are ignored; missing actuals are turned into null strings.
        !           146: 
        !           147: Incompatibility:
        !           148:        The virgule '/' in "a=/*b" is interpreted as the first character of
        !           149:                the pair "/*" which introduces a comment, rather than as the
        !           150:                second character of the divide-and-replace operator "=/".
        !           151:                This incompatibility reflects the recent change in the C language
        !           152:                which made "a/=*b" the legal way to write such a statement
        !           153:                if the meaning "a=a/ *b" is intended.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.