Commit | Line | Data |
---|---|---|
c0d3cd70 BJ |
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. |