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