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