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