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