Commit | Line | Data |
---|---|---|
f23cb965 | 1 | # |
9372792e | 2 | # @(#)README 1.2 %G% |
f23cb965 | 3 | # |
9372792e RH |
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 | ||
f23cb965 RH |
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. |