X-Git-Url: https://git.subgeniuskitty.com/unix-history/.git/blobdiff_plain/a68924a6e07d69bc4b8d6106b3af0ac5a7490905..e1140cde90a599542041b57a992f69d71652811d:/usr/src/cmd/cpp/README diff --git a/usr/src/cmd/cpp/README b/usr/src/cmd/cpp/README index 3d64dfaa8c..fcff9bbc93 100644 --- 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 -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: - : backup the existing version + : safety first: backup the existing version cp /lib/cpp /lib/ocpp : install the new version cp cpp /lib/cpp +Invocation + cpp [-CEPR] [-Dname] ... [-Dname=def] ... [-Idirectory] ... + [-Uname] ... [] [] + + 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". + 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. - 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' @@ -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". - 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) - 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 - 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 @@ -67,8 +102,24 @@ Bugs fixed: 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 @@ -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 - 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