BSD 4 development

[unix-history] / usr / src / cmd / cpp / README

diff --git a/usr/src/cmd/cpp/README b/usr/src/cmd/cpp/README
index 3d64dfa..fcff9bb 100644 (file)
--- a/usr/src/cmd/cpp/README
+++ b/usr/src/cmd/cpp/README
@@ -1,28 +1,56 @@
+August 25, 1978
+

 Files in this directory form the C preprocessor, which handles '#include'
 files and macro definition and expansion for the C compiler.
 This new version was written by John F. Reiser and is from 5 to 12
 Files in this directory form the C preprocessor, which handles '#include'
 files and macro definition and expansion for the C compiler.
 This new version was written by John F. Reiser and is from 5 to 12

-times faster than the old.
+times faster (on UNIX systems) than the old.

 
 To create the executable file 'cpp' in the current directory:
        make
 
 To install the preprocessor 'cpp' so it will be used by the C compiler:
 
 To create the executable file 'cpp' in the current directory:
        make
 
 To install the preprocessor 'cpp' so it will be used by the C compiler:

-       : backup the existing version
+       : safety first: backup the existing version

        cp /lib/cpp /lib/ocpp
        : install the new version
        cp cpp /lib/cpp
 
        cp /lib/cpp /lib/ocpp
        : install the new version
        cp cpp /lib/cpp
 

+Invocation
+       cpp [-CEPR] [-Dname] ... [-Dname=def] ... [-Idirectory] ...
+               [-Uname] ... [<infile>] [<outfile>]
+
+       If there are two non-flag arguments then the first is the name of the
+       input file and the second is the name of the output file.  If there is
+       one non-flag argument then it is the name of the input file and the
+       output is written on the standard output.  If there are no non-flag
+       arguments then the input is taken from the standard input and the output
+       is written on the standard output.  Flag arguments are:
+
+               -C      retain comments in output
+               -Dname  define name as "1"
+               -Dname=def      define name as def
+               -E      ignored
+               -Idirectory     add directory to search list for #include files
+               -P      don't insert lines "# 12 \"foo.c\"" into output
+               -R      allow recursive macros
+               -Uname  undefine name
+               

 Documentation clarifications:
        Symbols defined on the command line by "-Dfoo" are defined as "1",
                i.e., as if they had been defined by "#define foo 1" or "-Dfoo=1".
 Documentation clarifications:
        Symbols defined on the command line by "-Dfoo" are defined as "1",
                i.e., as if they had been defined by "#define foo 1" or "-Dfoo=1".

+       The directory search order for #include files is
+               1) the directory of the file which contains the #include request
+                  (e.g. #include is relative to the file being scanned when
+                  the request is made)
+               2) the directories specified by -I, in left-to-right order
+               3) the standard directory(s) (which for UNIX is /usr/include)

        An unescaped linefeed (the single character "\n") terminates a
                character constant or quoted string.
        An escaped linefeed (the two-character sequence "\\\n") may be
                used in the body of a '#define' statement to continue
                the definition onto the next line.  The escaped linefeed is
                not included in the macro body.
        An unescaped linefeed (the single character "\n") terminates a
                character constant or quoted string.
        An escaped linefeed (the two-character sequence "\\\n") may be
                used in the body of a '#define' statement to continue
                the definition onto the next line.  The escaped linefeed is
                not included in the macro body.

-       Comments are uniformly removed.  They are also ignored, except
-               that a comment terminates a token.
+       Comments are uniformly removed (except if the argument -C is specified).
+               They are also ignored, except that a comment terminates a token.

                Thus "foo/* la di da */bar" may expand 'foo' and 'bar' but
                will never expand 'foobar'.  If neither 'foo' nor 'bar' is a
                macro then the output is "foobar", even if 'foobar'
                Thus "foo/* la di da */bar" may expand 'foo' and 'bar' but
                will never expand 'foobar'.  If neither 'foo' nor 'bar' is a
                macro then the output is "foobar", even if 'foobar'


@@ -31,18 +59,25 @@ Documentation clarifications:
                        foo(1,2)
                produces "21" because the comment causes a break which enables
                the recognition of 'b' and 'a' as formals in the string "b/**/a".
                        foo(1,2)
                produces "21" because the comment causes a break which enables
                the recognition of 'b' and 'a' as formals in the string "b/**/a".

-       Macro formals are recognized even inside character constants
-               and quoted strings.  The output from
+       Macro formal parameters are recognized in '#define' bodies even inside
+               character constants and quoted strings.  The output from

                        #define foo(a) '\a'
                        foo(bar)
                        #define foo(a) '\a'
                        foo(bar)

-               is the seven characters " '\\bar'".
+               is the seven characters " '\\bar'".  Macro names are not recognized
+               inside character constants or quoted strings during the regular scan.
+               Thus
+                       #define foo bar
+                       printf("foo");
+               does not expand 'foo' in the second line, because it is inside
+               a quoted string which is not part of a '#define' macro definition.

        Macros are not expanded while processing a '#define' or '#undef'.
                Thus
                        #define foo bletch
                        #define bar foo
                        #undef foo
                        bar
        Macros are not expanded while processing a '#define' or '#undef'.
                Thus
                        #define foo bletch
                        #define bar foo
                        #undef foo
                        bar

-               produces "foo".
+               produces "foo".  The token appearing immediately after a
+               '#ifdef' or '#ifndef' is not expanded (of course!).

        Macros are not expanded during the scan which determines the actual
                parameters to another macro call.  Thus
                        #define foo(a,b)b a
        Macros are not expanded during the scan which determines the actual
                parameters to another macro call.  Thus
                        #define foo(a,b)b a


@@ -67,8 +102,24 @@ Bugs fixed:
        The following example expands to "# # #" :
                #define foo #
                foo foo foo
        The following example expands to "# # #" :
                #define foo #
                foo foo foo

-       Recursion in macro definitions is strictly obeyed (to the extent that
-               space is available).  In particular,
+       If the -R flag is not specified then the invocation of some recursive
+               macros is trapped and the recursion forcibly terminated with an
+               error message.  The recursions that are trapped are the ones
+               in which the nesting level is non-decreasing from some point on.
+               In particular,
+                       #define a a
+                       a
+               will be detected.  (Use "#undef a" if that is what you want.)
+               The recursion
+                       #define a c b
+                       #define b c a
+                       #define c foo
+                       a
+               will not be detected because the nesting level decreases after
+               each expansion of "c".
+       The -R flag specifically allows recursive macros and recursion will
+               be strictly obeyed (to the extent that space is available).
+               Assuming that -R is specified:

                        #define a a
                        a
                causes an infinite loop with very little output.  The tail recursion
                        #define a a
                        a
                causes an infinite loop with very little output.  The tail recursion


@@ -86,7 +137,7 @@ Bugs fixed:
 Stylistic choice:
        Nothing (not even linefeeds) is output while a false '#if', '#ifdef',
                or '#ifndef' is in effect.  Thus when all conditions become true
 Stylistic choice:
        Nothing (not even linefeeds) is output while a false '#if', '#ifdef',
                or '#ifndef' is in effect.  Thus when all conditions become true

-               a line of the form "# 12345 foo.c" is output.
+               a line of the form "# 12345 \"foo.c\"" is output (unless -P).

        Error and warning messages always appear on standard error (file
                descriptor 2).
        Mismatch between the number of formals and actuals in a macro call
        Error and warning messages always appear on standard error (file
                descriptor 2).
        Mismatch between the number of formals and actuals in a macro call