![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to cpp.info CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [GCC 1.x] / gcc|
Return to cpp.info CVS log | Up to [GCC 1.x] / gcc |
1.1 root 1: Info file cpp, produced by texinfo-format-buffer -*-Text-*-
2: from file cpp.texinfo
3:
4: This file documents the GNU C Preprocessor.
5:
6: Copyright (C) 1987 Richard M. Stallman.
7:
8: Permission is granted to make and distribute verbatim copies of
9: this manual provided the copyright notice and this permission notice
10: are preserved on all copies.
11:
12: Permission is granted to copy and distribute modified versions of this
13: manual under the conditions for verbatim copying, provided also that
14: the entire resulting derived work is distributed under the terms of a
15: permission notice identical to this one.
16:
17: Permission is granted to copy and distribute translations of this manual
18: into another language, under the above conditions for modified versions.
19:
20:
21:
22: File: cpp Node: Top, Up: (DIR), Next: Global Actions
23:
24: The C Preprocessor
25: ******************
26:
27: The C preprocessor is a "macro processor" that is used automatically by
28: the C compiler to transform your program before actual compilation. It is
29: called a macro processor because it allows you to define "macros",
30: which are brief abbreviations for longer constructs.
31:
32: The C preprocessor provides four separate facilities that you can use as
33: you see fit:
34:
35: * Inclusion of header files. These are files of declarations that can be
36: substituted into your program.
37:
38: * Macro expansion. You can define "macros", which are abbreviations
39: for arbitrary fragments of C code, and then the C preprocessor will
40: replace the macros with their definitions throughout the program.
41:
42: * Conditional compilation. Using special preprocessor commands, you
43: can include or exclude parts of the program according to various
44: conditions.
45:
46: * Line control. If you use a program to combine or rearrange source files into
47: an intermediate file which is then compiled, you can use line control
48: to inform the compiler of where each source line originally came from.
49:
50: C preprocessors vary in some details. This manual discusses the GNU C
51: preprocessor, the C Compatible Compiler Preprocessor. The GNU C
52: preprocessor provides a superset of the features of ANSI Standard C.
53:
54: ANSI Standard C requires the rejection of many harmless constructs commonly
55: used by today's C programs. Such incompatibility would be inconvenient for
56: users, so the GNU C preprocessor is configured to accept these constructs
57: by default. Strictly speaking, to get ANSI Standard C, you must use the
58: switches `-T', `-undef' and `-pedantic', but in practice the
59: consequences of having strict ANSI Standard C make it undesirable to do
60: this. *Note Invocation::.
61:
62: * Menu:
63:
64: * Global Actions:: Actions made uniformly on all input files.
65: * Commands:: General syntax of preprocessor commands.
66: * Header Files:: How and why to use header files.
67: * Macros:: How and why to use macros.
68: * Conditionals:: How and why to use conditionals.
69: * Combining Sources:: Use of line control when you combine source files.
70: * Other Commands:: Miscellaneous preprocessor commands.
71: * Output:: Format of output from the C preprocessor.
72: * Invocation:: How to invoke the preprocessor; command switches.
73: * Concept Index:: Index of concepts and terms.
74: * Index:: Index of commands, predefined macros and switches.
75:
76:
77: File: cpp Node: Global Actions, Prev: Top, Up: Top, Next: Commands
78:
79: Transformations Made Globally
80: =============================
81:
82: Most C preprocessor features are inactive unless you give specific commands
83: to request their use. (Preprocessor commands are lines starting with
84: `#'; *Note Commands::). But there are three transformations that the
85: preprocessor always makes on all the input it receives, even in the absence
86: of commands.
87:
88: * All C comments are replaced with single spaces.
89:
90: * Backslash-Newline sequences are deleted, no matter where. This
91: feature allows you to break long lines for cosmetic purposes without
92: changing their meaning.
93:
94: * Predefined macro names are replaced with their expansions
95: (*Note Predefined::).
96:
97: The first two transformations are done *before* nearly all other parsing
98: and before preprocessor commands are recognized. Thus, for example, you
99: can split a line cosmetically with Backslash-Newline just about anywhere.
100: Even
101:
102: #defi\
103: ne FO\
104: O 10\
105: 20
106:
107: is equivalent into `#define FOO 1020'.
108:
109: But there are a few exceptions to both transformations.
110:
111: * C comments and predefined macro names are not recognized inside a
112: `#include' command in which the file name is delimited with
113: `<' and `>'.
114:
115: * C comments and predefined macro names are never recognized within a
116: character or string constant. (Strictly speaking, this is the rule,
117: not an exception, but it is worth noting here anyway.)
118:
119: * Backslash-Newline is not discarded if preceded by an odd number of
120: additional Backslashes. This is because the Backslashes quote each
121: other, leaving the Newline as an ordinary Newline.
122:
123: x\\
124: y
125:
126: is an example of a Backslash-Newline that is preserved from deletion for
127: this reason.
128:
129:
130: File: cpp Node: Commands, Prev: Global Actions, Up: Top, Next: Header Files
131:
132: Preprocessor Commands
133: =====================
134:
135: Most preprocessor features are active only if you use preprocessor commands
136: to request their use.
137:
138: Preprocessor commands are lines in your program that start with `#'.
139: The `#' is followed by an identifier that is the "command name".
140: For example, `#define' is the command that defines a macro.
141: Whitespace is also allowed before and after the `#'.
142:
143: The set of valid command names is fixed. Programs cannot define new
144: preprocessor commands.
145:
146: Some command names require arguments; these make up the rest of the command
147: line and must be separated from the command name by whitespace. For example,
148: `#define' must be followed by a macro name and the intended expansion
149: of the macro.
150:
151: A preprocessor command cannot be more than one line in normal circumstances.
152: It may be split cosmetically with Backslash-Newline, but that has no effect
153: on its meaning. Comments containing Newlines can also divide the command into
154: multiple lines, but the comments are changed to Spaces before the command
155: is interpreted. The only way a significant Newline can occur in a preprocessor
156: command is within a string constant or character constant. Note that
157: most C compilers that might be applied to the output from the preprocessor
158: do not accept string or character constants containing Newlines.
159:
160: The `#' and the command name cannot come from a macro expansion. For
161: example, if `foo' is defined as a macro expanding to `define',
162: that does not make `#foo' a valid preprocessor command.
163:
164:
165: File: cpp Node: Header Files, Prev: Commands, Up: Top, Next: Macros
166:
167: Header Files
168: ============
169:
170: A header file is a file containing C declarations and macro definitions
171: (*Note Macros::) to be shared between several source files. You request
172: the use of a header file in your program with the C preprocessor command
173: `#include'.
174:
175:
176: File: cpp Node: Header Uses, Prev: Header Files, Up: Header Files, Next: Include Syntax
177:
178: Uses of Header Files
179: --------------------
180:
181: Header files serve two kinds of purposes.
182:
183: * System header files declare the interfaces to parts of the operating
184: system. You include them in your program to supply the definitions
185: you need to invoke system calls and libraries.
186:
187: * Your own header files contain declarations for interfaces between the
188: source files of your program. Each time you have a group of related
189: declarations and macro definitions all or most of which are needed in
190: several different source files, it is a good idea to create a header
191: file for them.
192:
193: Including a header file produces the same results in C compilation as
194: copying the header file into each source file that needs it. But such
195: copying would be time-consuming and error-prone. With a header file, the
196: related declarations appear in only one place. If they need to be changed,
197: they can be changed in one place, and programs that include the header file
198: will automatically use the new version when next recompiled. The header
199: file eliminates the labor of finding and changing all the copies as well as
200: the risk that a failure to find one copy will result in inconsistencies
201: within a program.
202:
203: The usual convention is to give header files names that end with `.h'.
204:
205:
206: File: cpp Node: Include Syntax, Prev: Header Uses, Up: Header Files, Next: Include Operation
207:
208: The `#include' Command
209: ----------------------
210:
211: Both user and system header files are included using the preprocessor
212: command `#include'. It has three variants:
213:
214: `#include <FILE>'
215: This variant is used for system header files. It searches for a file
216: named FILE in a standard list of system directories.
217:
218: {{how can the user find out about/control this list?}}
219:
220: The parsing of this form of `#include' is slightly special
221: because comments are not recognized within the `<...>'.
222: Thus, in `#include <x/*y>' the `/*' does not start a comment
223: and the command specifies inclusion of a system header file named
224: `x/*y'. Of course, a header file with such a name is unlikely to
225: exist on Unix, where shell wildcard features would make it hard to
226: manipulate.
227:
228: FILE may not contain a `>' character. It may, however,
229: contain a `<' character.
230:
231: `#include "FILE"'
232: This variant is used for header files of your own program. It
233: searches for a file named FILE first in the current working
234: directory, and then in a specified list of directories for user
235: header files, and finally in the same directories used for system header
236: files. The current working directory is tried first because it is
237: presumed to be the location of the files of the program being
238: compiled. The other directories for user header files are specified
239: with the command switch `-I' (*Note Invocation::).
240:
241: FILE may not contain `"' characters unless they are
242: preceded by Backslashes. Note, however, that such Backslashes are
243: *not* discarded when searching for the file. None of the character
244: escape sequences appropriate to string constants in C is processed;
245: all Backslashes are significant. Thus, `#include "x\n\"y"'
246: specifies a filename containing two Backslashes. It is not clear why
247: this behavior is ever useful, but the ANSI standard specifies it.
248:
249: `#include ANYTHING ELSE'
250: This variant is called a "computed #include". Any `#include'
251: command whose argument does not fit the above two forms is a computed
252: include. ANYTHING ELSE is checked for macro calls, which are
253: expanded (*Note Macros::). When this is done, the result must fit
254: one of the above two variants.
255:
256: This feature allows you to define a macro which controls the file name
257: to be used at a later point in the program. One application of this
258: is to allow a site-configuration file for your program to specify the
259: names of the system include files to be used. This can help in
260: porting the program to various operating systems in which the
261: necessary system header files are found in different places.
262:
263:
264: File: cpp Node: Include Operation, Prev: Include Syntax, Up: Header Files
265:
266: How `#include' Works
267: --------------------
268:
269: The `#include' command works by directing the C preprocessor to scan
270: the specified file as input before continuing with the rest of the current
271: file. The output from the preprocessor contains the output already
272: generated, followed by the output resulting from the included file,
273: followed by the output that comes from the text after the `#include'
274: command. For example, given two files as follows:
275:
276: /* File program.c */
277: int x;
278: #include "header.h"
279:
280: main ()
281: {
282: printf (test ());
283: }
284:
285:
286: /* File header.h */
287: char *test ();
288:
289: the output generated by the C preprocessor for `program.c' as input
290: would be
291:
292: int x;
293: char *test ();
294:
295: main ()
296: {
297: printf (test ());
298: }
299:
300: Included files are not limited to declarations and macro definitions; they
301: are merely the typical use. Any fragment of a C program can be included
302: from another file. The include file could even contain the beginning of a
303: statement that is concluded in the containing file, or the end of a
304: statement that was started in the including file. However, a comment or a
305: string or character constant may not start in the included file and finish
306: in the including file. An unterminated comment, string constant or
307: character constant in an included file is considered to end (with an error
308: message) at the end of the file.
309:
310: The line following the `#include' command is always treated as a
311: separate line by the C preprocessor even if the included file lacks a final
312: newline.
313:
314:
315: File: cpp Node: Macros, Prev: Header Files, Up: Top, Next: Conditionals
316:
317: Macros
318: ======
319:
320: A macro is a sort of abbreviation which you can define once and then
321: use later. There are many complicated features associated with macros
322: in the C preprocessor.
323:
324: * Menu:
325:
326: * Simple Macros:: Macros that always expand the same way.
327: * Argument Macros:: Macros that accept arguments that are substituted
328: into the macro expansion.
329: * Predefined:: Predefined macros that are always available.
330: * Stringification:: Macro arguments converted into string constants.
331: * Concatenation:: Building tokens from parts taken from macro arguments.
332: * Undefining:: Cancelling a macro's definition.
333: * Redefining:: Changing a macro's definition.
334: * Macro Pitfalls:: Macros can confuse the unwary. Here we explain
335: several common problems and strange features.
336:
337:
338: File: cpp Node: Simple Macros, Prev: Macros, Up: Macros, Next: Argument Macros
339:
340: Simple Macros
341: -------------
342:
343: A "simple macro" is a kind of abbreviation. It is a name which stands
344: for a fragment of code.
345:
346: Before you can use a macro, you must "define" it explicitly with the
347: `#define' command. `#define' is followed by the name of the
348: macro and then the code it should be an abbreviation for. For example,
349:
350: #define BUFFER_SIZE 1020
351:
352: defines a macro named `BUFFER_SIZE' as an abbreviation for the text
353: `1020'. Therefore, if somewhere after this `#define' command
354: there comes a C statement of the form
355:
356: foo = (char *) xmalloc (BUFFER_SIZE);
357:
358: then the C preprocessor will recognize and "expand" the macro
359: `BUFFER_SIZE', resulting in
360:
361: foo = (char *) xmalloc (1020);
362:
363: the definition must be a single line; however, it may not end in the
364: middle of a multi-line string constant or character constant.
365:
366: The use of all upper case for macro names is a standard convention.
367: Programs are easier to read when it is possible to tell at a glance which
368: names are macros.
369:
370: Normally, a macro definition must be a single line, like all C preprocessor
371: commands. (You can split a long macro definition cosmetically with
372: Backslash-Newline.) There is one exception: Newlines can be included in
373: the macro definition if within a string or character constant. By the same
374: token, it is not possible for a macro definition to contain an unbalanced
375: quote character; the definition automatically extends to include the
376: matching quote character that ends the string or character constant.
377: Comments within a macro definition may contain Newlines, which make no
378: difference since the comments are entirely replaced with Spaces regardless
379: of their contents.
380:
381: Aside from the above, there is no restriction on what can go in a macro
382: body. Parentheses need not balance. The body need not resemble valid C
383: code. (Of course, you might get error messages from the C compiler when
384: you use the macro.)
385:
386: The C preprocessor scans your program sequentially, so macro definitions
387: take effect at the place you write them. Therefore, the following input to
388: the C preprocessor
389:
390: foo = X;
391: #define X 4
392: bar = X;
393:
394: produces as output
395:
396: foo = X;
397:
398: bar = 4;
399:
400: After the preprocessor expands a macro name, the macro's definition body is
401: appended to the front of the remaining input, and the check for macro calls
402: continues. Therefore, the macro body can contain calls to other macros.
403: For example, after
404:
405: #define BUFSIZE 1020
406: #define TABLESIZE BUFSIZE
407:
408: the name `TABLESIZE' when used in the program would go through two
409: stages of expansion, resulting ultimately in `1020'.
410:
411: This is not at all the same as defining `TABLESIZE' to be `1020'.
412: The `#define' for `TABLESIZE' uses exactly the body you
413: specify---in this case, `BUFSIZE'---and does not check to see whether
414: it too is the name of a macro. It's only when you *use* `TABLESIZE'
415: that the result of its expansion is checked for more macro names.
416: *Note Cascaded Macros::.
417:
418:
419: File: cpp Node: Argument Macros, Prev: Simple Macros, Up: Macros, Next: Predefined
420:
421: Macros with Arguments
422: ---------------------
423:
424: A simple macro always stands for exactly the same text, each time it is
425: used. Macros can be more flexible when they accept "arguments".
426: Arguments are fragments of code that you supply each time the macro is
427: used. These fragments are included in the expansion of the macro according
428: to the directions in the macro definition.
429:
430: To define a macro that uses arguments, you write a `#define' command
431: with a list of "argument names" in parentheses after the name of the
432: macro. The argument names may be any valid C identifiers, separated by
433: commas and optionally whitespace. The open-parenthesis must follow the
434: macro name immediately, with no space in between.
435:
436: For example, here is a macro that computes the minimum of two numeric
437: values:
438:
439: #define min(X, Y) ((X) < (Y) ? (X) : (Y))
440:
441: To use a macro that expects arguments, you write the name of the macro
442: followed by a list of "actual arguments" in parentheses. separated by
443: commas. The number of actual arguments you give must match the number of
444: arguments the macro expects. Examples of use of the macro `min'
445: include `min (1, 2)' and `min (x + 28, *p)'.
446:
447: The expansion text of the macro depends on the arguments you use.
448: Each of the argument names of the macro is replaced, throughout the
449: macro definition, with the corresponding actual argument. Using the
450: same macro `min' defined above, `min (1, 2)' expands into
451:
452: ((1) < (2) ? (1) : (2))
453:
454: where `1' has been substituted for `X' and `2' for `Y'.
455:
456: Likewise, `min (x + 28, *p)' expands into
457:
458: ((x + 28) < (*p) ? (x + 28) : (*p))
459:
460: Parentheses in the actual arguments must balance; a comma within
461: parentheses does not end an argument. However, there is no requirement for
462: brackets or braces to balance; thus, if you want to supply `array[x =
463: y, x + 1]' as an argument, you must write it as `array[(x = y, x +
464: 1)]', which is equivalent C code.
465:
466: After the actual arguments are substituted into the macro body, the entire
467: result is appended to the front of the remaining input, and the check for
468: macro calls continues. Therefore, the actual arguments can contain calls
469: to other macros, either with or without arguments, or even to the same
470: macro. The macro body can also contain calls to other macros. For
471: example, `min (min (a, b), c)' expands into
472:
473: ((((a) < (b) ? (a) : (b))) < (c)
474: ? (((a) < (b) ? (a) : (b)))
475: : (c))
476:
477: (Line breaks shown here for clarity would not actually be generated.)
478:
479: If you use the macro name followed by something other than an
480: open-parenthesis, it is not a call to the macro, and the preprocessor does
481: not change what you have written. Therefore, it is possible for the same
482: name to be a variable or function in your program as well as a macro,
483: and you can choose in each instance whether to refer to the macro
484: (if an actual argument list follows) or the variable or function (if
485: an argument list does not follow).
486:
487: Such dual use of one name could be confusing and should be avoided
488: except when the two meanings are effectively synonymous: that is, when the
489: name is both a macro and a function and the two have similar effects. You
490: can think of the name simply as as a function; use of the name for purposes
491: other than calling it (such as, to take the address) will refer to the
492: function, while calls will expand the macro and generate better but
493: equivalent code. For example, you can use a function named `min' in
494: the same source file that defines the macro. If you write `&min' with
495: no argument list, you refer to the function. If you write `min (x,
496: bb)', with an argument list, the macro is expanded. If you write
497: `(min) (a, bb)', where the name `min' is not followed by an
498: open-parenthesis, the macro is not expanded, so you wind up with a call to
499: the function `min'.
500:
501: It is not allowed to define the same name as both a simple macro and
502: a macro with arguments.
503:
504: In the definition of a macro with arguments, the list of argument names
505: must follow the macro name immediately with no space in between. If there
506: is a space after the macro name, the macro is defined as taking no
507: arguments, and all the rest of the name is taken to be the expansion.
508: The reason for this is that it is often useful to define a macro that
509: takes no arguments and whose definition begins with an identifier in
510: parentheses. This rule about spaces makes it possible for you to do either
511:
512: #define FOO(x) - 1 / (x)
513:
514: which defines `FOO' to take an argument and expand into minus the
515: reciprocal of that argument, or
516:
517: #define BAR (x) - 1 / (x)
518:
519: which defines `BAR' to take no argument and always expand into
520: `(x) - 1 / (x)'.
521:
522:
523: File: cpp Node: Predefined, Prev: Argument Macros, Up: Macros, Next: Stringification
524:
525: Predefined Macros
526: -----------------
527:
528: Several simple macros are predefined. You can use them without giving
529: definitions for them. They fall into two classes: standard macros and
530: system-specific macros.
531:
532: * Menu:
533:
534: * Standard Predefined:: Standard predefined macros.
535: * Nonstandard Predefined:: Nonstandard predefined macros.
536:
537:
538: File: cpp Node: Standard Predefined, Prev: Predefined, Up: Predefined, Next: Nonstandard Predefined
539:
540: Standard Predefined Macros
541: ..........................
542:
543: The standard predefined macros are available with the same meanings on all
544: operating systems and all kinds of machines. Their names all start and end
545: with double underscores. Here is a table of them.
546:
547: `__FILE__'
548: This macro expands to the name of the current input file, in the form
549: of a C string constant.
550:
551: `__LINE__'
552: This macro expands to the current input line number, in the form of a
553: decimal integer constant. While we call it a predefined macro, it's
554: a pretty strange macro, since its "definition" changes with each
555: new line of source code.
556:
557: This and `__FILE__' are useful in generating an error message to
558: report an inconsistency detected by the program; the message can state
559: the source line at which the inconsistency was detected. For example,
560:
561: fprintf (stderr, "Internal error: negative string length "
562: "%d at %s, line %d.",
563: length, __FILE__, __LINE__);
564:
565: A `#include' command changes the expansions of `__FILE__'
566: and `__LINE__' to correspond to the included file. At the end of
567: that file, when processing resumes on the input file that contained
568: the `#include' command, the expansions of `__FILE__' and
569: `__LINE__' revert to the values they had before the
570: `#include' (but `__LINE__' is then incremented by one as
571: processing moves to the line after the `#include').
572:
573: The expansions of both `__FILE__' and `__LINE__' are altered
574: if a `#line' command is used. *Note Combining Sources::.
575:
576: `__DATE__'
577: This macro expands to a string constant that describes the date on
578: which the preprocessor is being run. The string constant contains
579: eleven characters and looks like `"Jan 29 1987"' or `"Apr
580: 1 1905"'.
581:
582: `__TIME__'
583: This macro expands to a string constant that describes the time at
584: which the preprocessor is being run. The string constant contains
585: eight characters and looks like `"23:59:01"'.
586:
587: `__STDC__'
588: This macro expands to the constant 1, to signify that this is ANSI
589: Standard C. (Whether that is actually true depends on what C compiler
590: will operate on the output from the preprocessor.)
591:
592:
593: File: cpp Node: Nonstandard Predefined, Prev: Standard Predefined, Up: Predefined
594:
595: Nonstandard Predefined Macros
596: .............................
597:
598: The C preprocessor normally has several predefined macros that vary between
599: machines because their purpose is to indicate what type of system and
600: machine is in use. This manual, being for all systems and machines, cannot
601: tell you exactly what their names are; instead, we offer a list of some
602: typical ones.
603:
604: Some nonstandard predefined macros describe the operating system in use,
605: with more or less specificity. For example,
606:
607: `unix'
608: `unix' is normally predefined on all Unix systems.
609:
610: `BSD'
611: `BSD' is predefined on recent versions of Berkeley Unix
612: (perhaps only in version 4.3).
613:
614: Other nonstandard predefined macros describe the kind of CPU, with more or
615: less specificity. For example,
616:
617: `vax'
618: `vax' is predefined on Vax computers.
619:
620: `mc68000'
621: `mc68000' is predefined on most computers whose CPU is a 68000,
622: 68010 or 68020.
623:
624: `m68k'
625: `m68k' is also predefined on most computers whose CPU is a 68000.
626: 68010 or 68020; however, some makers use `mc68000' and some use
627: `m68k'. Some predefine both names.
628:
629: `M68020'
630: `M68020' has been observed to be predefined on some systems that
631: use 68020 CPUs---in addition to `mc68000' and `m68k' that
632: are less specific.
633:
634: Yet other nonstandard predefined macros describe the manufacturer of
635: the system. For example,
636:
637: `sun'
638: `sun' is predefined on all models of Sun computers.
639:
640: `pyr'
641: `sun' is predefined on all models of Pyramid computers.
642:
643: These predefined symbols are not only nonstandard, they are contrary to the
644: ANSI standard because their names do not start with underscores. However,
645: the GNU C preprocessor would be useless if it did not predefine the same
646: names that are normally predefined on the system and machine you are using.
647: Even system header files check the predefined names and will generate
648: incorrect declarations if they do not find the names that are expected.
649:
650: The set of nonstandard predefined names in the GNU C preprocessor is controlled
651: by the macro `PREDEFS', which should be set with a `-D' switch
652: in the `Makefile' to a string constant containing names separated
653: by commas. The Doublequotes that delimit the string constant must be
654: escaped with Backslashes to get them through the shell. For example,
655: `\"unix,sun,m68k,mc68000\"' is used on Suns.
656:
657:
658: File: cpp Node: Stringification, Prev: Predefined, Up: Macros, Next: Concatenation
659:
660: Stringification
661: ---------------
662:
663: "Stringification" means turning an code fragment into a string constant
664: whose contents are the text for the code fragment. For example,
665: stringifying `foo (z)' results in `"foo (z)"'.
666:
667: In the C preprocessor, stringification is an option available when macro
668: arguments are substituted into the macro definition. In the body of the
669: definition, when an argument name appears, the character `#' before
670: the name specifies stringification of the corresponding actual argument
671: when it is substituted at that point in the definition. The same argument
672: may be substituted in other places in the definition without
673: stringification if the argument name appears in those places with no
674: `#'.
675:
676: Here is an example of a macro definition that uses stringification:
677:
678: #define WARN_IF(EXP) \
679: do { if (EXP) fprintf (stderr, "Warning: " #EXP "\n"); } while (0)
680:
681: Here the actual argument for `EXP' is substituted once as given,
682: into the `if' statement, and once as stringified, into the
683: argument to `fprintf'. The `do' and `while (0)' are
684: a kludge to make it possible to write `WARN_IF (ARG);',
685: which the resemblance of `WARN_IF' to a function would make
686: C programmers want to do; *Note Swallow Semicolon::).
687:
688: The stringification feature is limited to transforming one macro argument
689: into one string constant: there is no way to combine the argument with
690: other text and then stringify it all together. But the example above shows
691: how an equivalent result can be obtained in ANSI Standard C using the
692: feature that adjacent string constants are concatenated as one string
693: constant. The preprocessor stringifies `EXP''s actual argument
694: into a separate string constant, resulting in text like
695:
696: do { if (x == 0) fprintf (stderr, "Warning: " "x == 0" "\n"); } while (0)
697:
698: but the C compiler then sees three consecutive string constants and
699: concatenates them into one, producing effectively
700:
701: do { if (x == 0) fprintf (stderr, "Warning: x == 0\n"); } while (0)
702:
703: Stringification in C involves more than putting doublequote characters
704: around the fragment; it is necessary to put backslashes in front of all
705: doublequote characters, and all backslashes in string and character
706: constants, in order to get a valid C string constant with the proper
707: contents. Thus, stringifying `p = "foo\n";' results in `"p =
708: \"foo\\n\";"'. However, backslashes that are not inside of string or
709: character constants are not duplicated: `\n' by itself stringifies to
710: `"\n"'.
711:
712: Whitespace (including comments) in the text being stringified is handled
713: according to precise rules. All leading and trailing whitespace is ignored.
714: Any sequence of whitespace in the middle of the text is converted to
715: a single space in the stringified result.
716:
717:
718: File: cpp Node: Concatenation, Prev: Stringification, Up: Macros, Next: Undefining
719:
720: Concatenation
721: -------------
722:
723: "Concatenation" means joining two strings into one. In the context
724: of macro expansion, concatenation refers to joining two lexical units
725: into one longer one. Specifically, an actual argument to the macro can be
726: concatenated with another actual argument or with fixed text to produce
727: a longer name. The longer name might be the name of a function,
728: variable or type, or a C keyword; it might even be the name of another
729: macro, in which case it will be expanded.
730:
731: When you define a macro, you request concatenation with the special
732: operator `##' in the macro body. When the macro is called,
733: after actual arguments are substituted, all `##' operators are
734: deleted, and so is any whitespace next to them (including whitespace
735: that was part of an actual argument). The result is to concatenate
736: the syntactic tokens on either side of the `##'.
737:
738: Consider a C program that interprets named commands. There probably needs
739: to be a table of commands, perhaps an array of structures declared as
740: follows:
741:
742: struct command
743: {
744: char *name;
745: void (*function) ();
746: };
747:
748: struct command commands[] =
749: {
750: { "quit", quit_command},
751: { "help", help_command},
752: ...
753: };
754:
755: It would be cleaner not to have to give each command name twice, once in
756: the string constant and once in the function name. A macro which takes the
757: name of a command as an argument can make this unnecessary. The string
758: constant can be created with stringification, and the function name by
759: concatenating the argument with `_command'. Here is how it is done:
760:
761: #define COMMAND(NAME) { #NAME, NAME ## _command }
762:
763: struct command commands[] =
764: {
765: COMMAND (quit),
766: COMMAND (help),
767: ...
768: };
769:
770: The usual case of concatenation is concatenating two names (or a name and a
771: number) into a longer name. But this isn't the only valid case. It is
772: also possible to concatenate two numbers (or a number and a name, such as
773: `1.5' and `e3') into a number. Also, multi-character operators
774: such as `+=' can be formed by concatenation. In some cases it is even
775: possible to piece together a string constant. However, two pieces of text
776: that don't together form a valid lexical unit cannot be concatenated. For
777: example, concatenation with `x' on one side and `+' on the other
778: is not meaningful because those two characters can't fit together in any
779: lexical unit of C. The ANSI standard says that such attempts at
780: concatenation are undefined, but in the GNU C preprocessor it is well
781: defined: it puts the `x' and `+' side by side with no particular
782: special results.
783:
784: Keep in mind that the C preprocessor converts comments to whitespace before
785: macros are even considered. Therefore, you cannot create a comment by
786: concatenating `/' and `*': the `/*' sequence that starts a
787: comment is not a lexical unit, but rather the beginning of a "long" space
788: character. Also, you can freely use comments next to a `##' in a
789: macro definition, or in actual arguments that will be concatenated, because
790: the comments will be converted to spaces at first sight, and concatenation
791: will later discard the spaces.
792:
793:
794: File: cpp Node: Undefining, Prev: Concatenation, Up: Macros, Next: Redefining
795:
796: Undefining Macros
797: -----------------
798:
799: To "undefine" a macro means to cancel its definition. This is done
800: with the `#undef' command. `#undef' is followed by the macro
801: name to be undefined.
802:
803: Like definition, undefinition occurs at a specific point in the source
804: file, and it applies starting from that point. The name ceases to be a
805: macro name, and from that point on it is treated by the preprocessor as if
806: it had never been a macro name.
807:
808: For example,
809:
810: #define FOO 4
811: x = FOO;
812: #undef FOO
813: x = FOO;
814:
815: expands into
816:
817: x = 4;
818:
819: x = FOO;
820:
821: In this example, `FOO' had better be a variable or function as well
822: as (temporarily) a macro, in order for the result of the expansion to be
823: valid C code.
824:
825: The same form of `#undef' command will cancel definitions with
826: arguments or definitions that don't expect arguments. The `#undef'
827: command has no effect when used on a name not currently defined as a macro.
828:
829:
830: File: cpp Node: Redefining, Prev: Undefining, Up: Macros, Next: Macro Pitfalls
831:
832: Redefining Macros
833: -----------------
834:
835: "Redefining" a macro means defining (with `#define') a name that
836: is already defined as a macro.
837:
838: A redefinition is trivial if the new definition is transparently identical
839: to the old one. You probably wouldn't deliberately write a trivial
840: redefinition, but they can happen automatically when a header file is
841: included more than once (*Note Header Files::), so they are accepted
842: silently and without effect.
843:
844: Nontrivial redefinition is considered likely to be an error, so
845: it provokes a warning message from the preprocessor. However, sometimes it
846: is useful to change the definition of a macro in mid-compilation. You can
847: inhibit the warning by undefining the macro with `#undef' before the
848: second definition.
849:
850: In order for a reefinition to be trivial, the new definition must exactly match
851: the one already in effect, with two possible exceptions:
852:
853: * Whitespace may be added or deleted at the beginning or the end.
854:
855: * Whitespace may be changed in the middle (but not inside strings).
856: However, it may not be eliminated entirely, and it may not be added
857: where there was no whitespace at all.
858:
859: Recall that a comment counts as whitespace.
860:
861:
862: File: cpp Node: Macro Pitfalls, Prev: Redefining, Up: Macros
863:
864: Pitfalls and Subtleties of Macros
865: ---------------------------------
866:
867: In this section we describe some special rules that apply to macros and
868: macro expansion, and point out certain cases in which the rules have
869: counterintuitive consequences that you must watch out for.
870:
871: * Menu:
872:
873: * Misnesting:: Macros can contain unmatched parentheses.
874: * Macro Parentheses:: Why apparently superfluous parentheses
875: may be necessary to avoid incorrect grouping.
876: * Swallow Semicolon:: Macros that look like functions
877: but expand into compound statements.
878: * Side Effects:: Unsafe macros that cause trouble when
879: arguments contain side effects.
880: * Self-Reference:: Macros whose definitions use the macros' own names.
881: * Argument Prescan:: Actual arguments are checked for macro calls
882: before they are substituted.
883: * Cascaded Macros:: Macros whose definitions use other macros.
884:
885:
886: File: cpp Node: Misnesting, Prev: Macro Pitfalls, Up: Macro Pitfalls, Next: Macro Parentheses
887:
888: Improperly Nested Constructs
889: ............................
890:
891: Recall that when a macro is called with arguments, the arguments are
892: substituted into the macro body and the result is checked, together with
893: the rest of the input file, for more macro calls.
894:
895: It is possible to piece together a macro call coming partially from the
896: macro body and partially from the actual arguments. For example,
897:
898: #define double(x) (2*(x))
899: #define call_with_1(x) x(1)
900:
901: would expand `call_with_1 (double)' into `(2*(1))'.
902:
903: Macro definitions do not have to have balanced parentheses. By writing an
904: unbalanced open parenthesis in a macro body, it is possible to create a
905: macro call that begins inside the macro body but ends outside of it. For
906: example,
907:
908: #define strange(file) fprintf (file, "%s %d",
909: ...
910: strange(stderr) p, 35)
911:
912: This bizarre example expands to `fprintf (stderr, "%s %d", p, 35)'!
913:
914:
915: File: cpp Node: Macro Parentheses, Prev: Misnesting, Up: Macro Pitfalls, Next: Swallow Semicolon
916:
917: Unintended Grouping of Arithmetic
918: .................................
919:
920: You may have noticed that in most of the macro definition examples shown
921: above, each occurrence of a macro argument name had parentheses around it.
922: In addition, another pair of parentheses usually surround the entire macro
923: definition. Here is why it is best to write macros that way.
924:
925: Suppose you define a macro as follows
926:
927: #define ceil_div(x, y) (x + y - 1) / y
928:
929: whose purpose is to divide, rounding up. (One use for this
930: operation is to compute how many `int''s are needed to hold
931: a certain number of `char''s.) Then suppose it is used as follows:
932:
933: a = ceil_div (b & c, sizeof (int));
934:
935: This expands into
936:
937: a = (b & c + sizeof (int) - 1) / sizeof (int);
938:
939: which is does not do what is intended the operator-precedence rules of
940: C make it equivalent to
941:
942: a = (b & (c + sizeof (int) - 1)) / sizeof (int);
943:
944: What we want is
945:
946: a = ((b & c) + sizeof (int) - 1)) / sizeof (int);
947:
948: Defining the macro as
949:
950: #define ceil_div(x, y) ((x) + (y) - 1) / (y)
951:
952: provides the desired result.
953:
954: However, unintended grouping can result in another way. Consider
955: `sizeof ceil_div(1, 2)'. That has the appearance of a C expression
956: that would compute the size of the type of `ceil_div (1, 2)', but in
957: fact it means something very different. Here is what it expands to:
958:
959: sizeof ((1) + (2) - 1) / (2)
960:
961: This would take the size of an integer and divide it by two. The precedence
962: rules have put the division outside the `sizeof' when it was intended
963: to be inside.
964:
965: Parentheses around the entire macro definition can prevent such problems.
966: Here, then, is the recommended way to define `ceil_div':
967:
968: #define ceil_div(x, y) (((x) + (y) - 1) / (y))
969:
970:
971: File: cpp Node: Swallow Semicolon, Prev: Macro Parentheses, Up: Macro Pitfalls, Next: Side Effects
972:
973: Swallowing the Semicolon
974: ........................
975:
976: Often it is desirable to define a macro that expands into a compound
977: statement. Consider, for example, the following macro, that advances a
978: pointer (the argument `p' says where to find it) across whitespace
979: characters:
980:
981: #define SKIP_SPACES (p, limit) \
982: { register char *lim = (limit); \
983: while (p != lim) { \
984: if (*p++ != ' ') { \
985: p--; break; }}}
986:
987: Here Backslash-Newline is used to split the macro definition, which must
988: be a single line, so that it resembles the way such C code would be
989: layed out if not part of a macro definition.
990:
991: A call to this macro might be `SKIP_SPACES (p, lim)'. Strictly
992: speaking, the call expands to a compound statement, which is a complete
993: statement with no need for a semicolon to end it. But it looks like a
994: function call. So it minimizes confusion if you can use it like a function
995: call, writing a semicolon afterward, as in `SKIP_SPACES (p, lim);'
996:
997: But this can cause trouble before `else' statements, because the
998: semicolon is actually a null statement. Suppose you write
999:
1000: if (*p != 0)
1001: SKIP_SPACES (p, lim);
1002: else ...
1003:
1004: The presence of two statements---the compound statement and a null
1005: statement---in between the `if' condition and the `else'
1006: makes invalid C code.
1007:
1008: The definition of the macro `SKIP_SPACES' can be altered to solve
1009: this problem, using a `do ... while' statement. Here is how:
1010:
1011: #define SKIP_SPACES (p, limit) \
1012: do { register char *lim = (limit); \
1013: while (p != lim) { \
1014: if (*p++ != ' ') { \
1015: p--; break; }}} \
1016: while (0)
1017:
1018: Now `SKIP_SPACES (p, lim);' expands into
1019:
1020: do {...} while (0);
1021:
1022: which is one statement.
1023:
1024:
1025: File: cpp Node: Side Effects, Prev: Swallow Semicolon, Up: Macro Pitfalls, Next: Self-Reference
1026:
1027: Duplication of Side Effects
1028: ...........................
1029:
1030: Let's consider a call to the macro `min':
1031:
1032: #define min(X, Y) ((X) < (Y) ? (X) : (Y))
1033: ...
1034: next = min (x + y, foo (z));
1035:
1036: expands into
1037:
1038: next = ((x + y) < (foo (z)) ? (x + y) : (foo (z)));
1039:
1040: where `x + y' has been substituted for `X' and `foo (z)'
1041: for `Y'.
1042:
1043: The function `foo' is used only once in the statement as it appears
1044: in the program, but the expression `foo (z)' has been substituted
1045: twice into the macro expansion. As a result, `foo' might be called
1046: two times when the statement is executed. If it has side effects or
1047: if it takes a long time to compute, the results might not be what you
1048: intended. We say that `min' is an "unsafe" macro.
1049:
1050: Solving this problem cleanly would involve defining `min' in
1051: a way that would compute the value of `foo (z)' only once.
1052: Unfortunately, the C language offers no way to do this. So the only
1053: solution is to be careful when *using* the macro `min'.
1054: For example, you can calculate the value of `foo (z)', save it
1055: in a variable, and use that variable in `min':
1056:
1057: #define min(X, Y) ((X) < (Y) ? (X) : (Y))
1058: ...
1059: {
1060: int tem = foo (z);
1061: next = min (x + y, tem);
1062: }
1063:
1064: (where I assume that `foo' returns type `int').
1065:
1066:
1067: File: cpp Node: Self-Reference, Prev: Side Effects, Up: Macro Pitfalls, Next: Argument Prescan
1068:
1069: Self-Referential Macros
1070: .......................
1071:
1072: A "self-referential" macro is one whose name appears in its definition.
1073: A special feature of ANSI Standard C is that the self-reference is not
1074: considered a macro call. It is passed into the preprocessor output
1075: unchanged.
1076:
1077: Let's consider an example:
1078:
1079: #define foo (4 + foo)
1080:
1081: where `foo' is also a variable in your program.
1082:
1083: Following the ordinary rules, each reference to `foo' will expand into
1084: `(4 + foo)'; then this will be rescanned and will expand into `(4
1085: + (4 + foo))'; and so on until it causes a fatal error (memory full) in the
1086: preprocessor.
1087:
1088: However, the special rule about self-reference cuts this process short
1089: after one step, at `(4 + foo)'. Therefore, this macro definition
1090: has the possibly useful effect of causing the program to add 4 to
1091: the value of `foo' wherever `foo' is referred to.
1092:
1093: In most cases, it is a bad idea to take advantage of this feature.
1094: A person reading the program who sees that `foo' is a variable will
1095: not expect that it is a macro as well. The reader will come across a
1096: the identifier `foo' in the program and think its value should be
1097: that of the variable `foo', whereas in fact the value is four
1098: greater.
1099:
1100: The special rule for self-reference applies also to "indirect"
1101: self-reference. This is the case where a macro X expands to use a
1102: macro `y', and `y''s expansion refers to the macro `x'. The
1103: resulting reference to `x' comes indirectly from the expansion of
1104: `x', so it is a self-reference and is not further expanded. Thus,
1105: after
1106:
1107: #define x (4 + y)
1108: #define y (2 * x)
1109:
1110: `x' would expand into `(4 + (2 * x))'. Clear?
1111:
1112: But suppose `y' is used elsewhere, not from the definition of `x'.
1113: Then the use of `x' in the expansion of `y' is not a self-reference
1114: because `x' is not "in progress". So it does expand. However,
1115: the expansion of `x' contains a reference to `y', and that
1116: is an indirect self-reference now because `y' is "in progress".
1117: The result is that `y' expands to `(2 * (4 + y))'.
1118:
1119: It is not clear that this behavior would ever be useful, but it is specified
1120: by the ANSI C standard, so you need to understand it.
1121:
1122:
1123: File: cpp Node: Argument Prescan, Prev: Self-Reference, Up: Macro Pitfalls, Next: Cascaded Macros
1124:
1125: Separate Expansion of Macro Arguments
1126: .....................................
1127:
1128: We have explained that the expansion of a macro, including the substituted
1129: actual arguments, is scanned over again for macro calls to be expanded.
1130:
1131: What really happens is more subtle: first each actual argument text is scanned
1132: separately for macro calls. Then the results of this are substituted into
1133: the macro body to produce the macro expansion, and the macro expansion
1134: is scanned again for macros to expand.
1135:
1136: The result is that the actual arguments are scanned *twice* to expand
1137: macro calls in them.
1138:
1139: Most of the time, this has no effect. If the actual argument contained
1140: any macro calls, they are expanded during the first scan. The result
1141: therefore contains no macro calls, so the second scan does not change it.
1142: If the actual argument were substituted as given, with no prescan,
1143: the single remaining scan would find the same macro calls and produce
1144: the same results.
1145:
1146: You might expect the double scan to change the results when a
1147: self-referential macro is used in an actual argument of another macro
1148: (*Note Self-Reference::): the self-referential macro would be expanded once
1149: in the first scan, and a second time in the second scan. But this is not
1150: what happens. The self-references that do not expand in the first scan are
1151: marked so that they will not expand in the second scan either.
1152:
1153: The prescan is not done when an argument is stringified or concatenated.
1154: (More precisely, stringification and concatenation use the argument as
1155: written, in un-prescanned form. The same actual argument would be used in
1156: prescanned form if it is substituted elsewhere without stringification or
1157: concatenation.) Thus,
1158:
1159: #define str(s) #s
1160: #define foo 4
1161: str (foo)
1162:
1163: expands to `"foo"'. Once more, prescan has been prevented from
1164: having any noticeable effect.
1165:
1166: You might now ask, "Why mention the prescan, if it makes no difference?
1167: Why not skip it and make the preprocessor faster?" The answer is that the
1168: prescan does make a difference in two special cases:
1169:
1170: * Nested calls to a macro.
1171:
1172: * Macros that call other macros that stringify or concatenate.
1173:
1174: We say that "nested" calls to a macro occur when a macro's actual
1175: argument contains a call to that very macro. For example, if `f'
1176: is a macro that expects one argument, `f (f (1))' is a nested
1177: pair of calls to `f'. The desired expansion is made by
1178: expanding `f (1)' and substituting that into the definition of
1179: `f'. The prescan causes the expected result to happen.
1180: Without the prescan, `f (1)' itself would be substituted as
1181: an actual argument, and the inner use of `f' would appear
1182: during the main scan as an indirect self-reference and would not
1183: be expanded. Here, the prescan cancels an undesirable side effect
1184: (in the medical, not computational, sense of the term) of the special
1185: rule for self-referential macros.
1186:
1187: There is also one case where prescan is useful. It is possible
1188: to use prescan to expand an argument and then stringify it---if you use
1189: two levels of macros. Let's add a new macro `xstr' to the
1190: example shown above:
1191:
1192: #define xstr(s) str(s)
1193: #define str(s) #s
1194: #define foo 4
1195: xstr (foo)
1196:
1197: This expands into `"4"', not `"foo"'. The reason for the
1198: difference is that the argument of `xstr' is expanded at prescan
1199: (because `xstr' does not specify stringification or concatenation of
1200: the argument). The result of prescan then forms the actual argument for
1201: `str'. `str' uses its argument without prescan because it
1202: performs strigification; but it cannot prevent or undo the prescanning
1203: already done by `xstr'.
1204:
1205:
1206: File: cpp Node: Cascaded Macros, Prev: Argument Prescan, Up: Macro Pitfalls
1207:
1208: Cascaded Use of Macros
1209: ......................
1210:
1211: A "cascade" of macros is when one macro's body contains a reference
1212: to another macro. This is very common practice. For example,
1213:
1214: #define BUFSIZE 1020
1215: #define TABLESIZE BUFSIZE
1216:
1217: This is not at all the same as defining `TABLESIZE' to be `1020'.
1218: The `#define' for `TABLESIZE' uses exactly the body you
1219: specify---in this case, `BUFSIZE'---and does not check to see whether
1220: it too is the name of a macro.
1221:
1222: It's only when you *use* `TABLESIZE' that the result of its expansion
1223: is checked for more macro names.
1224:
1225: This makes a difference if you change the definition of `BUFSIZE'
1226: at some point in the source file. `TABLESIZE', defined as shown,
1227: will always expand using the definition of `BUFSIZE' that is
1228: currently in effect:
1229:
1230: #define BUFSIZE 1020
1231: #define TABLESIZE BUFSIZE
1232: #undef BUFSIZE
1233: #define BUFSIZE 37
1234:
1235: Now `TABLESIZE' expands (in two stages) to `37'.
1236:
1237:
1238: File: cpp Node: Conditionals, Prev: Macros, Up: Top, Next: Combining Sources
1239:
1240: Conditionals
1241: ============
1242:
1243: In a macro processor, a "conditional" is a command that allows a part
1244: of the program to be ignored during compilation, on some conditions.
1245: In the C preprocessor, a conditional can test either an arithmetic expression
1246: or whether a name is defined as a macro.
1247:
1248: A conditional in the C preprocessor resembles in some ways an `if'
1249: statement in C, but it is important to understand the difference between
1250: them. The condition in an `if' statement is tested during the execution
1251: of your program. Its purpose is to allow your program to behave differently
1252: from run to run, depending on the data it is operating on. The condition
1253: in a preprocessor conditional command is tested when your program is compiled.
1254: Its purpose is to allow different code to be included in the program depending
1255: on the situation at the time of compilation.
1256:
1257: * Menu:
1258:
1259: * Uses: Conditional Uses. What conditionals are for.
1260: * Syntax: Conditional Syntax. How conditionals are written.
1261: * Deletion: Deleted Code. Making code into a comment.
1262: * Macros: Conditionals-Macros. Why conditionals are used with macros.
1263: * Errors: #error Command. Detecting inconsistent compilation parameters.
1264:
1265:
1266: File: cpp Node: Conditional Uses, Prev: Conditionals, Up: Conditionals, Next: Conditional Syntax
1267: Generally there are three kinds of reason to use a conditional.
1268:
1269: * A program may need to use different code depending on the machine or
1270: operating system it is to run on. In some cases the code for one
1271: operating system may be erroneous on another operating system; for
1272: example, it might refer to library routines that do not exist on the
1273: other system. When this happens, it is not enough to avoid executing
1274: the invalid code: merely having it in the program makes it impossible
1275: to link the program and run it. With a preprocessor conditional, the
1276: offending code can be effectively excised from the program when it is
1277: not valid.
1278:
1279: * You may want to be able to compile the same source file into two
1280: different programs. Sometimes the difference between the programs is
1281: that one makes frequent time-consuming consistency checks on its
1282: intermediate data while the other does not.
1283:
1284: * A conditional whose condition is always false is a good way to exclude
1285: code from the program but keep it as a sort of comment for future
1286: reference.
1287:
1288: Most simple programs that are intended to run on only one machine will
1289: not need to use preprocessor conditionals.
1290:
1291:
1292: File: cpp Node: Conditional Syntax, Prev: Conditional Uses, Up: Conditionals, Next: Conditionals-Macros
1293:
1294: Syntax of Conditionals
1295: ----------------------
1296:
1297: A conditional in the C preprocessor begins with a "conditional
1298: command": `#if', `#ifdef' or `#ifndef'.*Note Conditionals::,
1299: for info on `#ifdef' and `#ifndef'; only `#if' is explained
1300: here.
1301:
1302: * Menu:
1303:
1304: * If: #if Command. Basic conditionals using `#if' and `#endif'.
1305: * Else: #else Command. Including some text if the condition fails.
1306: * Elif: #elif Command. Testing several alternative possibilities.
1307:
1308:
1309: File: cpp Node: #if Command, Prev: Conditional Syntax, Up: Conditional Syntax, Next: #else Command
1310:
1311: The `#if' Command
1312: .................
1313:
1314: The `#if' command in its simplest form consists of
1315:
1316: #if EXPRESSION
1317: CONTROLLED TEXT
1318: #endif /* EXPRESSION */
1319:
1320: The comment following the `#endif' is not required, but it is a good
1321: practice because it helps people match the `#endif' to the
1322: corresponding `#if'. Such comments should always be used, except in
1323: short conditionals that are not nested. In fact, you can put anything at
1324: all after the `#endif' and it will be ignored by the GNU C preprocessor,
1325: but only comments are acceptable in ANSI Standard C.
1326:
1327: EXPRESSION is a C expression of integer type, subject to stringent
1328: restrictions. It may contain
1329:
1330: * Integer constants, which are all regarded as `long' or
1331: `unsigned long'.
1332:
1333: * Character constants, which are interpreted according to the character
1334: set and conventions of the machine and operating system on which the
1335: preprocessor is running. The GNU C preprocessor uses the C data type
1336: `char' for these character constants; therefore, whether some
1337: character codes are negative is determined by the C compiler used to
1338: compile the preprocessor. If it treats `char' as signed, then
1339: character codes large enough to set the sign bit will be considered
1340: negative; otherwise, no character code is considered negative.
1341:
1342: * Arithmetic operators for addition, subtraction, multiplication,
1343: division, bitwise operations, shifts, comparisons, and `&&' and
1344: `||'.
1345:
1346: * Identifiers that are not macros, which are all treated as zero(!).
1347:
1348: * Macro calls. All macro calls in the expression are expanded before
1349: actual computation of the expression's value begins.
1350:
1351: Note that `sizeof' operators and `enum'-type values are not allowed.
1352: `enum'-type values, like all other identifiers that are not taken
1353: as macro calls and expanded, are treated as zero.
1354:
1355: The text inside of a conditional can include preprocessor commands. Then
1356: the commands inside the conditional are obeyed only if that branch of the
1357: conditional succeeds. The text can also contain other conditional groups.
1358: However, the `#if''s and `#endif''s must balance.
1359:
1360:
1361: File: cpp Node: #else Command, Prev: #if Command, Up: Conditional Syntax, Next: #elif Command
1362:
1363: The `#else' Command
1364: ...................
1365:
1366: The `#else' command can be added a conditional to provide alternative
1367: text to be used if the condition is false. This looks like
1368:
1369: #if EXPRESSION
1370: TEXT-IF-TRUE
1371: #else /* Not EXPRESSION */
1372: TEXT-IF-FALSE
1373: #endif /* Not EXPRESSION */
1374:
1375: If EXPRESSION is nonzero, and the TEXT-IF-TRUE is considered
1376: included, then `#else' acts like a failing conditional and the
1377: TEXT-IF-FALSE is ignored. Contrariwise, if the `#if'
1378: conditional fails, the TEXT-IF-FALSE is considered included.
1379:
1380:
1381: File: cpp Node: #elif Command, Prev: #else Command, Up: Conditional Syntax
1382:
1383: The `#elif' Command
1384: ...................
1385:
1386: One common case of nested conditionals is used to check for more than two
1387: possible alternatives. For example, you might have
1388:
1389: #if X == 1
1390: ...
1391: #else /* X != 1 */
1392: #if X == 2
1393: ...
1394: #else /* X != 2 */
1395: ...
1396: #endif /* X != 2 */
1397: #endif /* X != 1 */
1398:
1399: Another conditional command, `#elif', allows this to be abbreviated
1400: as follows:
1401:
1402: #if X == 1
1403: ...
1404: #elif X == 2
1405: ...
1406: #else /* X != 2 and X != 1*/
1407: ...
1408: #endif /* X != 2 and X != 1*/
1409:
1410: `#elif' stands for "else if". Like `#else', it goes in the
1411: middle of a `#if'-`#endif' pair and subdivides it; it does not
1412: require a matching `#endif' of its own. Like `#if', the
1413: `#elif' command includes an expression to be tested.
1414:
1415: The text following the `#elif' is processed only if the original
1416: `#if'-condition failed and the `#elif' condition succeeeds. More
1417: than one `#elif' can go in the same `#if'-`#endif' group.
1418: Then the text after each `#elif' is processed only if the `#elif'
1419: condition succeeds after the original `#if' and any previous
1420: `#elif''s within it have failed. `#else' is equivalent to
1421: `#elif 1', and `#else' is allowed after any number of
1422: `#elif''s, but `#elif' may not follow a `#else'.
1423:
1424:
1425: File: cpp Node: Deleted Code, Prev: Conditional Syntax, Up: Conditionals, Next: Conditionals-Macros
1426:
1427: Keeping Deleted Code for Future Reference
1428: -----------------------------------------
1429:
1430: If you replace or delete a part of the program but want to keep the old
1431: code around as a comment for future reference, the easy way to do this is
1432: to put `#if 0' before it and `#endif' after it.
1433:
1434: This works even if the code being turned off contains conditionals, but
1435: they must be entire conditionals (balanced `#if' and `#endif').
1436:
1437:
1438: File: cpp Node: Conditionals-Macros, Prev: Deleted Code, Up: Conditionals, Next: #error Command
1439:
1440: Conditionals and Macros
1441: -----------------------
1442:
1443: Conditionals are rarely useful except in connection with macros. A
1444: `#if' command whose expression uses no macros is equivalent to
1445: `#if 1' or `#if 0'; you might as well determine which one, by
1446: computing the value of the expression yourself, and then simplify the
1447: program. But when the expression uses macros, its value can vary from
1448: compilation to compilation.
1449:
1450: For example, here is a conditional that tests the expression
1451: `BUFSIZE == 1020', where `BUFSIZE' must be a macro.
1452:
1453: #if BUFSIZE == 1020
1454: printf ("Large buffers!\n");
1455: #endif /* BUFSIZE is large */
1456:
1457: The special operator `defined' may be used in `#if' expressions
1458: to test whether a certain name is defined as a macro. Either
1459: `defined NAME' or `defined (NAME)'.
1460:
1461: is an expression whose value is 1 if NAME is defined as macro at
1462: the current point in the program, and 0 otherwise. For the
1463: `defined' operator it makes no difference what the definition of
1464: the macro is; all that matters is whether there is a definition. Thus,
1465: for example,
1466:
1467: #if defined (vax) || defined (ns16000)
1468:
1469: would include the following code if either of the names `vax' and
1470: `ns16000' is defined as a macro.
1471:
1472: If a macro is defined and later undefined with `#undef',
1473: subsequent use of the `defined' operator will return 0, because
1474: the name is no longer defined. If the macro is defined again with
1475: another `#define', `defined' will recommence returning 1.
1476:
1477: Conditionals that test just the definedness of one name are very common, so
1478: there are two special short conditional commands for this case. They are
1479:
1480: `#ifdef NAME'
1481: is equivalent to `#if defined (NAME)'.
1482:
1483: `#ifndef NAME'
1484: is equivalent to `#if ! defined (NAME)'.
1485:
1486: Macro definitions can vary between compilations for several reasons.
1487:
1488: * Some macros are predefined on each kind of machine. For example, on a
1489: Vax, the name `vax' is a predefined macro. On other machines, it
1490: would not be defined.
1491:
1492: * Many more macros are defined by system header files. Different
1493: systems and machines define different macros, or give them different
1494: values. It is useful to test these macros with conditionals to avoid
1495: using a system feature on a machine where it is not implemented.
1496:
1497: * Macros are a common way of allowing users to customize a program for
1498: different machines or applications. For example, the macro
1499: `BUFSIZE' might be defined in a configuration file for your
1500: program that is included as a header file in each source file. You
1501: would use `BUFSIZE' in a preprocessor conditional in order to
1502: generate different code depending on the chosen configuration.
1503:
1504: * Macros can be defined or undefined with `-D' and `-U'
1505: command switches when you compile the program. You can arrange to
1506: compile the same source file into two different programs by choosing
1507: a macro name to specify which program you want, writing conditionals
1508: to test whether or how this macro is defined, and then controlling
1509: the state of the macro with compiler command switches.
1510: *Note Invocation::.
1511:
1512:
1513: File: cpp Node: #error Command, Prev: Conditionals-Macros, Up: Conditionals
1514:
1515: The `#error' Command
1516: --------------------
1517:
1518: The command `#error' causes the preprocessor to report a fatal
1519: error. The rest of the line that follows `#error' is used as the
1520: error message.
1521:
1522: You would use `#error' inside of a conditional that detects a
1523: combination of parameters which you know the program does not properly
1524: support. For example, if you know that the program will not run
1525: properly on a Vax, you might write
1526:
1527: #ifdef vax
1528: #error Won't work on Vaxen. See comments at get_last_object.
1529: #endif
1530:
1531: *Note Nonstandard Predefined::, for why this works.
1532:
1533: If you have several configuration parameters that must be set up by
1534: the installation in a consistent way, you can use conditionals to detect
1535: an inconsistency and report it with `#error'. For example,
1536:
1537: #if HASH_TABLE_SIZE % 2 == 0 || HASH_TABLE_SIZE % 3 == 0 \
1538: || HASH_TABLE_SIZE % 5 == 0
1539: #error HASH_TABLE_SIZE should not be divisible by a small prime
1540: #endif
1541:
1542:
1543: File: cpp Node: Combining Sources, Prev: Conditionals, Up: Top, Next: Other Commands
1544:
1545: Combining Source Files
1546: ======================
1547:
1548: One of the jobs of the C preprocessor is to inform the C compiler of where
1549: each line of C code came from: which source file and which line number.
1550:
1551: C code can come from multiple source files if you use `#include';
1552: both `#include' and the use of conditionals and macros can cause
1553: the line number of a line in the preprocessor output to be different
1554: from the line's number in the original source file. You will appreciate
1555: the value of making both the C compiler (in error messages) and symbolic
1556: debuggers such as GDB use the line numbers in your source file.
1557:
1558: The C preprocessor builds on this feature by offering a command by which
1559: you can control the feature explicitly. This is useful when a file for
1560: input to the C preprocessor is the output from another program such as the
1561: `bison' parser generator, which operates on another file that is the
1562: true source file. Parts of the output from `bison' are generated from
1563: scratch, other parts come from a standard parser file. The rest are copied
1564: nearly verbatim from the source file, but their line numbers in the
1565: `bison' output are not the same as their original line numbers.
1566: Naturally you would like compiler error messages and symbolic debuggers to
1567: know the original source file and line number of each line in the
1568: `bison' output.
1569:
1570: `bison' arranges this by writing `#line' commands into the output
1571: file. `#line' is a command that specifies the original line number
1572: and source file name for subsequent input in the current preprocessor input
1573: file. `#line' has three variants:
1574:
1575: `#line LINENUM'
1576: Here LINENUM is a decimal integer constant. This specifies that
1577: the line number of the following line of input, in its original source file,
1578: was LINENUM.
1579:
1580: `#line LINENUM FILENAME'
1581: Here LINENUM is a decimal integer constant and FILENAME
1582: is a string constant. This specifies that the following line of input
1583: came originally from source file FILENAME and its line number there
1584: was LINENUM. Keep in mind that FILENAME is not just a
1585: file name; it is surrounded by Doublequotes.
1586:
1587: `#line ANYTHING ELSE'
1588: ANYTHING ELSE is checked for macro calls, which are expanded.
1589: The result should be a decimal integer constant followed optionally
1590: by a string constant, as described above.
1591:
1592: `#line' commands alter the results of the `__FILE__' and
1593: `__LINE__' predefined macros from that point on. *Note Standard Predefined::.
1594:
1595:
1596: File: cpp Node: Other Commands, Prev: Combining Sources, Up: Top, Next: Output
1597:
1598: Miscellaneous Preprocessor Commands
1599: ===================================
1600:
1601: This section describes two additional preprocesor commands. They are
1602: not very useful, but are mentioned for completeness.
1603:
1604: The "null command" consists of a `#' followed by a Newline, with
1605: only whitespace (including comments) in between. A null command is
1606: understood as a preprocessor command but has no effect on the preprocessor
1607: output. The primary significance of the existence of the null command is
1608: that an input line consisting of just a `#' will produce no output,
1609: rather than a line of output containing just a `#'. Supposedly
1610: some old C programs contain such lines.
1611:
1612: The `#pragma' command is specified in the ANSI standard to have an
1613: arbitrary implementation-defined effect. In the GNU C preprocessor,
1614: `#pragma' first attempts to run the game `rogue'; if that fails,
1615: it tries to run the game `hack'; if that fails, it tries to run
1616: GNU Emacs displaying the Tower of Hanoi; if that fails, it reports a
1617: fatal error. In any case, preprocessing does not continue.
1618:
1619:
1620: File: cpp Node: Output, Prev: Other Commands, Up: Top, Next: Invocation
1621:
1622: C Preprocessor Output
1623: =====================
1624:
1625: The output from the C preprocessor looks much like the input, except
1626: that all preprocessor command lines have been replaced with blank lines
1627: and all comments with spaces. Whitespace within a line is not altered;
1628: however, a space is inserted after the expansions of most macro calls.
1629:
1630: Source file name and line number information is conveyed by lines of
1631: the form
1632:
1633: # LINENUM FILENAME
1634:
1635: which are inserted as needed into the middle of the input (but never within
1636: a string or character constant). Such a line means that the following line
1637: originated in file FILENAME at line LINENUM.
1638:
1639:
1640: File: cpp Node: Invocation, Prev: Output, Up: Top
1641:
1642: Invoking the C Preprocessor
1643: ===========================
1644:
1645: Most often when you use the C preprocessor you will not have to invoke it
1646: explicitly: the C compiler will do so automatically. However, the
1647: preprocessor is sometimes useful individually.
1648:
1649: The C preprocessor expects two file names as arguments, INFILE and
1650: OUTFILE. The preprocessor reads INFILE together with any other
1651: files it specifies with `#include'. All the output generated by the
1652: combined input files is written in OUTFILE.
1653:
1654: Either INFILE or OUTFILE may be `-', which as INFILE
1655: means to read from standard input and as OUTFILE means to write to
1656: standard output. Also, if OUTFILE or both file names are omitted,
1657: the standard output and standard input are used for the omitted file names.
1658:
1659: Here is a table of command switches accepted by the C preprocessor. Most
1660: of them can also be given when compiling a C program; they are passed along
1661: automatically to the preprocessor when it is invoked by the compiler.
1662:
1663: `-P'
1664: Inhibit generation of `#'-lines with line-number information in
1665: the output from the preprocessor (*Note Output::). This might be
1666: useful when running the preprocessor on something that is not C code
1667: and will be sent to a program which might be confused by the
1668: `#'-lines
1669:
1670: `-C'
1671: Do not discard comments: pass them through to the output file.
1672: Comments appearing in arguments of a macro call will be copied to the
1673: output before the expansion of the macro call.
1674:
1675: `-T'
1676: Process ANSI standard trigraph sequences. These are three-character
1677: sequences, all starting with `??', that are defined by ANSI C to
1678: stand for single characters. For example, `??/' stands for
1679: `\', so `'??/n'' is a character constant for Newline.
1680: Strictly speaking, the GNU C preprocessor does not support all
1681: programs in ANSI Standard C unless `-T' is used, but you if you
1682: ever notice the difference it will be with relief.
1683:
1684: You don't want to know any more about trigraphs.
1685:
1686: `-pedantic'
1687: Issue warnings required by the ANSI C standard in certain cases such
1688: as when text other than a comment follows `#else' or `#endif'.
1689:
1690: `-I DIRECTORY'
1691: Add the directory DIRECTORY to the end of the list of
1692: directories to be searched for user header files (*Note Include Syntax::).
1693:
1694: `-D NAME'
1695: Predefine NAME as a macro, with definition `1'.
1696:
1697: `-D NAME=DEFINITION'
1698: Predefine NAME as a macro, with definition DEFINITION.
1699: There are no restrictions on the contents of DEFINITION, but if
1700: you are invoking the preprocessor from a shell or shell-like program
1701: you may need to use the shell's quoting syntax to protect characters
1702: such as spaces that have a meaning in the shell syntax.
1703:
1704: `-U NAME'
1705: Do not predefine NAME. If both `-U' and `-D' are
1706: specified for one name, the `-U' beats the `-D' and the name
1707: is not predefined.
1708:
1709: `-undef'
1710: Do not predefine any nonstandard macros.
1711:
1712: `-d'
1713: Instead of outputting the result of preprocessing, output a list of
1714: `#define' commands for all the macros defined during the
1715: execution of the preprocessor.
1716:
1717: `-i FILE'
1718: Process FILE as input, discarding the resulting output, before
1719: processing the regular input file. Because the output generated from
1720: FILE is discarded, the only effect of `-i FILE' is to
1721: make the macros defined in FILE available for use in the main
1722: input.
1723:
1724:
1725: File: cpp Node: Concept Index, Prev: Invocation, Up: Top, Next: Index
1726:
1727: Concept Index
1728: *************
1729:
1730: * Menu:
1731:
1732: * cascaded macros: Cascaded Macros.
1733: * commands: Commands.
1734: * concatenation: Concatenation.
1735: * conditionals: Conditionals.
1736: * header file: Header Files.
1737: * line control: Combining Sources.
1738: * macro body uses macro: Cascaded Macros.
1739: * null command: Other Commands.
1740: * output format: Output.
1741: * predefined macros: Predefined.
1742: * preprocessor commands: Commands.
1743: * redefining macros: Redefining.
1744: * self-reference: Self-Reference.
1745: * semicolons (after macro calls): Swallow Semicolon.
1746: * side effects (in macro arguments): Side Effects.
1747: * stringification: Stringification.
1748: * switches: Invocation.
1749: * undefining macros: Undefining.
1750: * unsafe macros: Side Effects.
1751:
1752:
1753: File: cpp Node: Index, Prev: Concept Index, Up: Top
1754:
1755: Index of Commands, Macros and Switches
1756: **************************************
1757:
1758: * Menu:
1759:
1760: * #elif: #elif Command.
1761: * #else: #else Command.
1762: * #error: #error Command.
1763: * #if: Conditional Syntax.
1764: * #ifdef: Conditionals-Macros.
1765: * #ifndef: Conditionals-Macros.
1766: * #include: Include Syntax.
1767: * #line: Combining Sources.
1768: * #pragma: Other Commands.
1769: * -C: Invocation.
1770: * -D: Invocation.
1771: * -d: Invocation.
1772: * -I: Invocation.
1773: * -i: Invocation.
1774: * -P: Invocation.
1775: * -pedantic: Invocation.
1776: * -T: Invocation.
1777: * -U: Invocation.
1778: * -undef: Invocation.
1779: * BSD: Nonstandard Predefined.
1780: * defined: Conditionals-Macros.
1781: * M68020: Nonstandard Predefined.
1782: * m68k: Nonstandard Predefined.
1783: * mc68000: Nonstandard Predefined.
1784: * pyr: Nonstandard Predefined.
1785: * sun: Nonstandard Predefined.
1786: * system header files: Header Uses.
1787: * unix: Nonstandard Predefined.
1788: * vax: Nonstandard Predefined.
1789: * __DATE__: Standard Predefined.
1790: * __FILE__: Standard Predefined.
1791: * __LINE__: Standard Predefined.
1792: * __STDC__: Standard Predefined.
1793: * __TIME__: Standard Predefined.
1794:
1795:
1796: Tag table:
1797: Node: Top737
1798: Node: Global Actions3284
1799: Node: Commands5126
1800: Node: Header Files6717
1801: Node: Header Uses7047
1802: Node: Include Syntax8428
1803: Node: Include Operation11291
1804: Node: Macros12930
1805: Node: Simple Macros13832
1806: Node: Argument Macros16865
1807: Node: Predefined21575
1808: Node: Standard Predefined21993
1809: Node: Nonstandard Predefined24421
1810: Node: Stringification26910
1811: Node: Concatenation29738
1812: Node: Undefining32985
1813: Node: Redefining33997
1814: Node: Macro Pitfalls35276
1815: Node: Misnesting36311
1816: Node: Macro Parentheses37307
1817: Node: Swallow Semicolon39133
1818: Node: Side Effects41014
1819: Node: Self-Reference42373
1820: Node: Argument Prescan44606
1821: Node: Cascaded Macros48306
1822: Node: Conditionals49318
1823: Node: Conditional Uses50594
1824: Node: Conditional Syntax51921
1825: Node: #if Command52478
1826: Node: #else Command54730
1827: Node: #elif Command55363
1828: Node: Deleted Code56693
1829: Node: Conditionals-Macros57214
1830: Node: #error Command60454
1831: Node: Combining Sources61490
1832: Node: Other Commands64062
1833: Node: Output65192
1834: Node: Invocation65900
1835: Node: Concept Index69479
1836: Node: Index70238
1837:
1838: End tag table
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.