Return to README CVS log

Up to [CSRG BSD Unix] / 43BSD / lib / cpp

Annotation of 43BSD/lib/cpp/README, revision 1.1

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