Penguin
Recent Changes
Annotated edit history of cpp-2.95(1) version 1 showing authors affecting page license. View with all changes included.
Rev Author # Line
1 perry 1 cpp
2 !!!cpp
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 OPTIONS
7 SEE ALSO
8 COPYING
9 ----
10 !!NAME
11
12
13 cccp, cpp - The GNU C-Compatible Compiler Preprocessor.
14 !!SYNOPSIS
15
16
17 __cccp__
18
19
20 [[__-$__]
21 [[__-A__''predicate''[[__(__''value''__)__]]
22 [[__-C__]
23 [[__-D__''name''[[__=__''definition'']]
24 [[__-dD__] [[__-dM__] [[__-I__ ''directory'']
25 [[__-H__] [[__-I-__] [[__-imacros__ ''file'']
26 [[__-include__ ''file''] [[__-idirafter__ ''dir'']
27 [[__-iprefix__ ''prefix''] [[__-iwithprefix__
28 ''dir''] [[__-lang-c__] [[__-lang-c++__]
29 [[__-lang-objc__] [[__-lang-objc++__] [[__-lint__]
30 [[__-M__ [[__-MG__]] [[__-MM__ [[__-MG__]]
31 [[__-MD__ ''file'' ] [[__-MMD__ ''file'' ]
32 [[__-nostdinc__] [[__-nostdinc++__] [[__-P__]
33 [[__-pedantic__] [[__-pedantic-errors__]
34 [[__-traditional__] [[__-trigraphs__]
35 [[__-U__''name''] [[__-undef__] [[__-Wtrigraphs__]
36 [[__-Wcomment__] [[__-Wall__] [[__-Wtraditional__]
37 [[''infile''|__-__]
38 [[''outfile''|__-__]
39 !!DESCRIPTION
40
41
42 The C preprocessor is a ''macro processor'' that is used
43 auto- matically by the C compiler to transform your program
44 be- fore actual compilation. It is called a macro processor
45 because it allows you to define ''macros'', which are
46 brief abbreviations for longer constructs.
47
48
49 The C preprocessor provides four separate facilities that
50 you can use as you see fit:
51
52
53 Inclusion of header files. These are files of dec- larations
54 that can be substituted into your pro- gram.
55
56
57 Macro expansion. You can define ''macros'', which are
58 abbreviations for arbitrary fragments of C code, and then
59 the C preprocessor will replace the macros with their
60 definitions throughout the program.
61
62
63 Conditional compilation. Using special preprocess- ing
64 directives, you can include or exclude parts of the program
65 according to various conditions.
66
67
68 Line control. If you use a program to combine or rearrange
69 source files into an intermediate file which is then
70 compiled, you can use line control to inform the compiler of
71 where each source line orig- inally came from.
72
73
74 C preprocessors vary in some details. For a full explana-
75 tion of the GNU C preprocessor, see the __info__ file
76 `__cpp.in- fo__', or the manual ''The C
77 Preprocessor''. Both of these are built from the same
78 documentation source file, `__cpp.texin- fo__'. The GNU C
79 preprocessor provides a superset of the features of ANSI
80 Standard C.
81
82
83 ANSI Standard C requires the rejection of many harmless
84 constructs commonly used by today's C programs. Such in-
85 compatibility would be inconvenient for users, so the GNU C
86 preprocessor is configured to accept these constructs by
87 default. Strictly speaking, to get ANSI Standard C, you must
88 use the options `__-trigraphs__', `__-undef__' and
89 `__-pedan- tic__', but in practice the consequences of
90 having strict ANSI Standard C make it undesirable to do
91 this.
92
93
94 Most often when you use the C preprocessor you will not have
95 to invoke it explicitly: the C compiler will do so
96 automatically. However, the preprocessor is sometimes useful
97 individually.
98
99
100 When you call the preprocessor individually, either name
101 (__cpp__ or __cccp__) will do--they are completely
102 synonymous.
103
104
105 The C preprocessor expects two file names as arguments,
106 ''infile'' and ''outfile''. The preprocessor reads
107 ''infile'' togeth- er with any other files it specifies
108 with `__#include__'. All the output generated by the
109 combined input files is writ- ten in
110 ''outfile''.
111
112
113 Either ''infile'' or ''outfile'' may be `__-__',
114 which as ''infile'' means to read from standard input and
115 as ''outfile'' means to write to standard output. Also,
116 if ''outfile'' or both file names are omitted, the
117 standard output and standard input are used for the omitted
118 file names.
119 !!OPTIONS
120
121
122 Here is a table of command options accepted by the C pre-
123 processor. These options can also be given when compiling a
124 C program; they are passed along automatically to the
125 preprocessor when it is invoked by the
126 compiler.
127
128
129 __-P__
130
131
132 Inhibit generation of `__#__'-lines with line-number
133 information in the output from the preprocessor. This might
134 be useful when running the preprocessor on something that is
135 not C code and will be sent to a program which might be
136 confused by the `__#__'-lines.
137
138
139 __-C__
140
141
142 Do not discard comments: pass them through to the output
143 file. Comments appearing in arguments of a macro call will
144 be copied to the output before the expansion of the macro
145 call.
146
147
148 __-traditional__
149
150
151 Try to imitate the behavior of old-fashioned C, as opposed
152 to ANSI C.
153
154
155 __-trigraphs__
156
157
158 Process ANSI standard trigraph sequences. These are
159 three-character sequences, all starting with `__??__',
160 that are defined by ANSI C to stand for sin- gle characters.
161 For example, `__??/__' stands for `__\__', so
162 `__'??/n'__' is a character constant for a newline.
163 Strictly speaking, the GNU C preprocessor does not support
164 all programs in ANSI Standard C unless `__-trigraphs__'
165 is used, but if you ever notice the difference it will be
166 with relief.
167
168
169 You don't want to know any more about
170 trigraphs.
171
172
173 __-pedantic__
174
175
176 Issue warnings required by the ANSI C standard in certain
177 cases such as when text other than a com- ment follows
178 `__#else__' or `__#endif__'.
179
180
181 __-pedantic-errors__
182
183
184 Like `__-pedantic__', except that errors are produced
185 rather than warnings.
186
187
188 __-Wtrigraphs__
189
190
191 Warn if any trigraphs are encountered (assuming they are
192 enabled).
193
194
195 __-Wcomment__
196
197
198 __-Wcomments__
199
200
201 Warn whenever a comment-start sequence `__/*__' appears
202 in a comment. (Both forms have the same
203 effect).
204
205
206 __-Wall__
207
208
209 Requests both `__-Wtrigraphs__' and `__-Wcomment__'
210 (but not `__-Wtraditional__').
211
212
213 __-Wtraditional__
214
215
216 Warn about certain constructs that behave differ- ently in
217 traditional and ANSI C.
218
219
220 __-I__ ''directory''
221
222
223 Add the directory ''directory'' to the end of the list of
224 directories to be searched for header files. This can be
225 used to override a system header file, substituting your own
226 version, since these directo- ries are searched before the
227 system header file di- rectories. If you use more than one
228 `__-I__' option, the directories are scanned in
229 left-to-right order; the standard system directories come
230 after.
231
232
233 __-I-__
234
235
236 Any directories specified with `__-I__' options before
237 the `__-I-__' option are searched only for the case of
238 `__#include__ ''file''
239 ''#in- clude ''''file''''
240
241
242 If additional directories are specified with `__-I__'
243 options after the `__-I-__', these directories are
244 searched for all `__#include__' directives.
245
246
247 In addition, the `__-I-__' option inhibits the use of the
248 current directory as the first search directory for
249 `__#include__ ''file''
250 ''-I.__'. Specifying both `__-I-__' and
251 `__-I.__' allows you to control precisely which
252 directories are searched before the current one and which
253 are searched after.
254
255
256 __-nostdinc__
257
258
259 Do not search the standard system directories for header
260 files. Only the directories you have speci- fied with
261 `__-I__' options (and the current directory, if
262 appropriate) are searched.
263
264
265 __-nostdinc++__
266
267
268 Do not search for header files in the C++ specific standard
269 directories, but do still search the other standard
270 directories. (This option is used when building
271 libg++.)
272
273
274 __-D__ ''name''
275
276
277 Predefine ''name'' as a macro, with definition
278 `__1__'.
279
280
281 __-D__ ''name''__=__''definition''
282
283
284 Predefine ''name'' as a macro, with definition ''defini-
285 tion''. There are no restrictions on the contents of
286 ''definition'', but if you are invoking the preproces-
287 sor from a shell or shell-like program you may need to use
288 the shell's quoting syntax to protect char- acters such as
289 spaces that have a meaning in the shell syntax. If you use
290 more than one `__-D__' for the same ''name'', the
291 rightmost definition takes ef- fect.
292
293
294 __-U__ ''name''
295
296
297 Do not predefine ''name''. If both `__-U__' and
298 `__-D__' are specified for one name, the `__-U__'
299 beats the `__-D__' and the name is not
300 predefined.
301
302
303 __-undef__
304
305
306 Do not predefine any nonstandard macros.
307
308
309 __-A__ ''name(''__value__'')''
310
311
312 Assert (in the same way as the __#assert__ directive) the
313 predicate ''name'' with tokenlist ''value''. Remember
314 to escape or quote the parentheses on shell command
315 lines.
316
317
318 You can use `__-A-__' to disable all predefined asser-
319 tions; it also undefines all predefined macros.
320
321
322 __-dM__
323
324
325 Instead of outputting the result of preprocessing, output a
326 list of `__#define__' directives for all the macros
327 defined during the execution of the prepro- cessor,
328 including predefined macros. This gives you a way of finding
329 out what is predefined in your version of the preprocessor;
330 assuming you have no file `__foo.h__', the
331 command
332
333
334 touch foo.h; cpp -dM foo.h
335
336
337 will show the values of any predefined macros.
338
339
340 __-dD__
341
342
343 Like `__-dM__' except in two respects: it does ''not''
344 in- clude the predefined macros, and it outputs ''both''
345 the `__#define__' directives and the result of prepro-
346 cessing. Both kinds of output go to the standard output
347 file.
348
349
350 __-M__ [[__-MG__]
351
352
353 Instead of outputting the result of preprocessing, output a
354 rule suitable for __make__ describing the de- pendencies
355 of the main source file. The preproces- sor outputs one
356 __make__ rule containing the object file name for that
357 source file, a colon, and the names of all the included
358 files. If there are many included files then the rule is
359 split into several lines using
360 `__\__'-newline.
361
362
363 `__-MG__' says to treat missing header files as gener-
364 ated files and assume they live in the same direc- tory as
365 the source file. It must be specified in addition to
366 `__-M__'.
367
368
369 This feature is used in automatic updating of make-
370 files.
371
372
373 __-MM__ [[__-MG__]
374
375
376 Like `__-M__' but mention only the files included with
377 `__#include__ __file''
378 ''#include__ __file''
379 ''
380
381
382 __-MD__ ''file''
383
384
385 Like `__-M__' but the dependency information is written
386 to `''file'''. This is in addition to compiling the file
387 as specified--`__-MD__' does not inhibit ordinary
388 compilation the way `__-M__' does.
389
390
391 When invoking gcc, do not specify the `''file''' argu-
392 ment. Gcc will create file names made by replacing
393 `__.c__' with `__.d__' at the end of the input file
394 names.
395
396
397 In Mach, you can use the utility __md__ to merge multi-
398 ple files into a single dependency file suitable for using
399 with the `__make__' command.
400
401
402 __-MMD__ ''file''
403
404
405 Like `__-MD__' except mention only user header files, not
406 system header files.
407
408
409 __-H__
410
411
412 Print the name of each header file used, in addi- tion to
413 other normal activities.
414
415
416 __-imacros__ ''file''
417
418
419 Process ''file'' as input, discarding the resulting
420 output, before processing the regular input file. Because
421 the output generated from ''file'' is discard- ed, the
422 only effect of `__-imacros__ ''file''' is to make the
423 macros defined in ''file'' available for use in the main
424 input. The preprocessor evaluates any `__-D__' and
425 `__-U__' options on the command line before pro- cessing
426 `__-imacros__ ''file''' .
427
428
429 __-include__ ''file''
430
431
432 Process ''file'' as input, and include all the result-
433 ing output, before processing the regular input
434 file.
435
436
437 __-idirafter__ ''dir''
438
439
440 Add the directory ''dir'' to the second include path. The
441 directories on the second include path are searched when a
442 header file is not found in any of the directories in the
443 main include path (the one that `__-I__' adds
444 to).
445
446
447 __-iprefix__ ''prefix''
448
449
450 Specify ''prefix'' as the prefix for subsequent
451 `__-iwithprefix__' options.
452
453
454 __-iwithprefix__ ''dir''
455
456
457 Add a directory to the second include path. The directory's
458 name is made by concatenating ''prefix'' and ''dir'',
459 where ''prefix'' was specified previously with
460 `__-iprefix__'.
461
462
463 __-lang-c__
464
465
466 __-lang-c++__
467
468
469 __-lang-objc__
470
471
472 __-lang-objc++__
473
474
475 Specify the source language. `__-lang-c++__' makes the
476 preprocessor handle C++ comment syntax, and in- cludes extra
477 default include directories for C++, and `__-lang-objc__'
478 enables the Objective C `__#import__' directive.
479 `__-lang-c__' explicitly turns off both of these
480 extensions, and `__-lang-objc++__' enables
481 both.
482
483
484 These options are generated by the compiler driver
485 __gcc__, but not passed from the `__gcc__' command
486 line.
487
488
489 __-lint__
490
491
492 Look for commands to the program checker __lint__ em-
493 bedded in comments, and emit them preceded by `__#pragma
494 lint__'. For example, the comment `__/* NOTREACHED
495 */__' becomes `__#pragma lint__
496 NOTREACHED'.
497
498
499 This option is available only when you call __cpp__ di-
500 rectly; __gcc__ will not pass it from its command
501 line.
502
503
504 __-$__
505
506
507 Forbid the use of `__$__' in identifiers. This was
508 formerly required for strict conformance to the C Standard
509 before the standard was corrected. This option is available
510 only when you call __cpp__ direct- ly; __gcc__ will
511 not pass it from its command line.
512 !!SEE ALSO
513
514
515 `__Cpp__' entry in __info__; ''The C
516 Preprocessor'', Richard M. Stall- man.__
517 gcc__(__1__); `__Gcc__' entry in __info__;
518 ''Using and Porting GNU CC (for version 2.0)'', Richard
519 M. Stallman.
520 !!COPYING
521
522
523 Copyright (c) 1991, 1992, 1993 Free Software Foundation,
524 Inc.
525
526
527 Permission is granted to make and distribute verbatim copies
528 of this manual provided the copyright notice and this
529 permission notice are preserved on all copies.
530
531
532 Permission is granted to copy and distribute modified ver-
533 sions of this manual under the conditions for verbatim
534 copying, provided that the entire resulting derived work is
535 distributed under the terms of a permission notice identical
536 to this one.
537
538
539 Permission is granted to copy and distribute translations of
540 this manual into another language, under the above con-
541 ditions for modified versions, except that this permission
542 notice may be included in translations approved by the Free
543 Software Foundation instead of in the original En-
544 glish.
545 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.