![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to cpp.info-1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [GCC 2.x] / gcc|
Return to cpp.info-1 CVS log | Up to [GCC 2.x] / gcc |
1.1 root 1: Info file cpp.info, produced by Makeinfo, -*- Text -*- from input file
2: cpp.texi.
3:
4: This file documents the GNU C Preprocessor.
5:
6: Copyright (C) 1987, 1989, 1991 Free Software Foundation, Inc.
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
13: this manual under the conditions for verbatim copying, provided also
14: that the entire resulting derived work is distributed under the terms
15: of a permission notice identical to this one.
16:
17: Permission is granted to copy and distribute translations of this
18: manual into another language, under the above conditions for modified
19: versions.
20:
21:
22: File: cpp.info, Node: Top, Next: Global Actions, Up: (DIR)
23:
24: The C Preprocessor
25: ******************
26:
27: The C preprocessor is a "macro processor" that is used
28: automatically by the C compiler to transform your program before
29: actual compilation. It is called a macro processor because it allows
30: you to define "macros", which are brief abbreviations for longer
31: constructs.
32:
33: The C preprocessor provides four separate facilities that you can
34: use as you see fit:
35:
36: * Inclusion of header files. These are files of declarations that
37: can be substituted into your program.
38:
39: * Macro expansion. You can define "macros", which are abbreviations
40: for arbitrary fragments of C code, and then the C preprocessor
41: will replace the macros with their definitions throughout the
42: program.
43:
44: * Conditional compilation. Using special preprocessor commands, you
45: can include or exclude parts of the program according to various
46: conditions.
47:
48: * Line control. If you use a program to combine or rearrange
49: source files into an intermediate file which is then compiled,
50: you can use line control to inform the compiler of where each
51: source line originally came from.
52:
53: C preprocessors vary in some details. This manual discusses the
54: GNU C preprocessor, the C Compatible Compiler Preprocessor. The GNU C
55: preprocessor provides a superset of the features of ANSI Standard C.
56:
57: ANSI Standard C requires the rejection of many harmless constructs
58: commonly used by today's C programs. Such incompatibility would be
59: inconvenient for users, so the GNU C preprocessor is configured to
60: accept these constructs by default. Strictly speaking, to get ANSI
61: Standard C, you must use the options `-trigraphs', `-undef' and
62: `-pedantic', but in practice the consequences of having strict ANSI
63: Standard C make it undesirable to do this. *Note Invocation::.
64:
65: * Menu:
66:
67: * Global Actions:: Actions made uniformly on all input files.
68: * Commands:: General syntax of preprocessor commands.
69: * Header Files:: How and why to use header files.
70: * Macros:: How and why to use macros.
71: * Conditionals:: How and why to use conditionals.
72: * Combining Sources:: Use of line control when you combine source files.
73: * Other Commands:: Miscellaneous preprocessor commands.
74: * Output:: Format of output from the C preprocessor.
75: * Invocation:: How to invoke the preprocessor; command options.
76: * Concept Index:: Index of concepts and terms.
77: * Index:: Index of commands, predefined macros and options.
78:
79:
80: File: cpp.info, Node: Global Actions, Next: Commands, Prev: Top, Up: Top
81:
82: Transformations Made Globally
83: =============================
84:
85: Most C preprocessor features are inactive unless you give specific
86: commands to request their use. (Preprocessor commands are lines
87: starting with `#'; *note Commands::.). But there are three
88: transformations that the preprocessor always makes on all the input it
89: receives, even in the absence of commands.
90:
91: * All C comments are replaced with single spaces.
92:
93: * Backslash-Newline sequences are deleted, no matter where. This
94: feature allows you to break long lines for cosmetic purposes
95: without changing their meaning.
96:
97: * Predefined macro names are replaced with their expansions (*note
98: Predefined::.).
99:
100: The first two transformations are done *before* nearly all other
101: parsing and before preprocessor commands are recognized. Thus, for
102: example, you can split a line cosmetically with Backslash-Newline
103: anywhere (except when trigraphs are in use; see below).
104:
105: /*
106: */ # /*
107: */ defi\
108: ne FO\
109: O 10\
110: 20
111:
112: is equivalent into `#define FOO 1020'. You can split even an escape
113: sequence with Backslash-Newline. For example, you can split
114: `"foo\bar"' between the `\' and the `b' to get
115:
116: "foo\\
117: bar"
118:
119: This behavior is unclean: in all other contexts, a Backslash can be
120: inserted in a string constant as an ordinary character by writing a
121: double Backslash, and this creates an exception. But the ANSI C
122: standard requires it. (Strict ANSI C does not allow Newlines in
123: string constants, so they do not consider this a problem.)
124:
125: But there are a few exceptions to all three transformations.
126:
127: * C comments and predefined macro names are not recognized inside a
128: `#include' command in which the file name is delimited with `<'
129: and `>'.
130:
131: * C comments and predefined macro names are never recognized within
132: a character or string constant. (Strictly speaking, this is the
133: rule, not an exception, but it is worth noting here anyway.)
134:
135: * Backslash-Newline may not safely be used within an ANSI
136: "trigraph". Trigraphs are converted before Backslash-Newline is
137: deleted. If you write what looks like a trigraph with a
138: Backslash-Newline inside, the Backslash-Newline is deleted as
139: usual, but it is then too late to recognize the trigraph.
140:
141: This exception is relevant only if you use the `-trigraphs'
142: option to enable trigraph processing. *Note Invocation::.
143:
144:
145: File: cpp.info, Node: Commands, Next: Header Files, Prev: Global Actions, Up: Top
146:
147: Preprocessor Commands
148: =====================
149:
150: Most preprocessor features are active only if you use preprocessor
151: commands to request their use.
152:
153: Preprocessor commands are lines in your program that start with `#'.
154: The `#' is followed by an identifier that is the "command name". For
155: example, `#define' is the command that defines a macro. Whitespace is
156: also allowed before and after the `#'.
157:
158: The set of valid command names is fixed. Programs cannot define new
159: preprocessor commands.
160:
161: Some command names require arguments; these make up the rest of the
162: command line and must be separated from the command name by
163: whitespace. For example, `#define' must be followed by a macro name
164: and the intended expansion of the macro.
165:
166: A preprocessor command cannot be more than one line in normal
167: circumstances. It may be split cosmetically with Backslash-Newline,
168: but that has no effect on its meaning. Comments containing Newlines
169: can also divide the command into multiple lines, but the comments are
170: changed to Spaces before the command is interpreted. The only way a
171: significant Newline can occur in a preprocessor command is within a
172: string constant or character constant. Note that most C compilers
173: that might be applied to the output from the preprocessor do not
174: accept string or character constants containing Newlines.
175:
176: The `#' and the command name cannot come from a macro expansion.
177: For example, if `foo' is defined as a macro expanding to `define',
178: that does not make `#foo' a valid preprocessor command.
179:
180:
181: File: cpp.info, Node: Header Files, Next: Macros, Prev: Commands, Up: Top
182:
183: Header Files
184: ============
185:
186: A header file is a file containing C declarations and macro
187: definitions (*note Macros::.) to be shared between several source
188: files. You request the use of a header file in your program with the
189: C preprocessor command `#include'.
190:
191: * Menu:
192:
193: * Header Uses:: What header files are used for.
194: * Include Syntax:: How to write `#include' commands.
195: * Include Operation:: What `#include' does.
196: * Once-Only:: Preventing multiple inclusion of one header file.
197: * Inheritance:: Including one header file in another header file.
198:
199:
200: File: cpp.info, Node: Header Uses, Next: Include Syntax, Prev: Header Files, Up: Header Files
201:
202: Uses of Header Files
203: --------------------
204:
205: Header files serve two kinds of purposes.
206:
207: * System header files declare the interfaces to parts of the
208: operating system. You include them in your program to supply the
209: definitions and declarations you need to invoke system calls and
210: libraries.
211:
212: * Your own header files contain declarations for interfaces between
213: the source files of your program. Each time you have a group of
214: related declarations and macro definitions all or most of which
215: are needed in several different source files, it is a good idea
216: to create a header file for them.
217:
218: Including a header file produces the same results in C compilation
219: as copying the header file into each source file that needs it. But
220: such copying would be time-consuming and error-prone. With a header
221: file, the related declarations appear in only one place. If they need
222: to be changed, they can be changed in one place, and programs that
223: include the header file will automatically use the new version when
224: next recompiled. The header file eliminates the labor of finding and
225: changing all the copies as well as the risk that a failure to find one
226: copy will result in inconsistencies within a program.
227:
228: The usual convention is to give header files names that end with
229: `.h'.
230:
231:
232: File: cpp.info, Node: Include Syntax, Next: Include Operation, Prev: Header Uses, Up: Header Files
233:
234: The `#include' Command
235: ----------------------
236:
237: Both user and system header files are included using the
238: preprocessor command `#include'. It has three variants:
239:
240: `#include <FILE>'
241: This variant is used for system header files. It searches for a
242: file named FILE in a list of directories specified by you, then
243: in a standard list of system directories. You specify
244: directories to search for header files with the command option
245: `-I' (*note Invocation::.). The option `-nostdinc' inhibits
246: searching the standard system directories; in this case only the
247: directories you specify are searched.
248:
249: The parsing of this form of `#include' is slightly special
250: because comments are not recognized within the `<...>'. Thus, in
251: `#include <x/*y>' the `/*' does not start a comment and the
252: command specifies inclusion of a system header file named `x/*y'.
253: Of course, a header file with such a name is unlikely to exist
254: on Unix, where shell wildcard features would make it hard to
255: manipulate.
256:
257: The argument FILE may not contain a `>' character. It may,
258: however, contain a `<' character.
259:
260: `#include "FILE"'
261: This variant is used for header files of your own program. It
262: searches for a file named FILE first in the current directory,
263: then in the same directories used for system header files. The
264: current directory is the directory of the current input file. It
265: is tried first because it is presumed to be the location of the
266: files that the current input file refers to. (If the `-I-'
267: option is used, the special treatment of the current directory is
268: inhibited.)
269:
270: The argument FILE may not contain `"' characters. If backslashes
271: occur within FILE, they are considered ordinary text characters,
272: not escape characters. None of the character escape sequences
273: appropriate to string constants in C are processed. Thus,
274: `#include "x\n\\y"' specifies a filename containing three
275: backslashes. It is not clear why this behavior is ever useful,
276: but the ANSI standard specifies it.
277:
278: `#include ANYTHING ELSE'
279: This variant is called a "computed #include". Any `#include'
280: command whose argument does not fit the above two forms is a
281: computed include. The text ANYTHING ELSE is checked for macro
282: calls, which are expanded (*note Macros::.). When this is done,
283: the result must fit one of the above two variants--in particular,
284: the expanded text must in the end be surrounded by either quotes
285: or angle braces.
286:
287: This feature allows you to define a macro which controls the file
288: name to be used at a later point in the program. One application
289: of this is to allow a site-configuration file for your program to
290: specify the names of the system include files to be used. This
291: can help in porting the program to various operating systems in
292: which the necessary system header files are found in different
293: places.
294:
295:
296: File: cpp.info, Node: Include Operation, Next: Once-Only, Prev: Include Syntax, Up: Header Files
297:
298: How `#include' Works
299: --------------------
300:
301: The `#include' command works by directing the C preprocessor to scan
302: the specified file as input before continuing with the rest of the
303: current file. The output from the preprocessor contains the output
304: already generated, followed by the output resulting from the included
305: file, followed by the output that comes from the text after the
306: `#include' command. For example, given two files as follows:
307:
308: /* File program.c */
309: int x;
310: #include "header.h"
311:
312: main ()
313: {
314: printf (test ());
315: }
316:
317:
318: /* File header.h */
319: char *test ();
320:
321: the output generated by the C preprocessor for `program.c' as input
322: would be
323:
324: int x;
325: char *test ();
326:
327: main ()
328: {
329: printf (test ());
330: }
331:
332: Included files are not limited to declarations and macro
333: definitions; those are merely the typical uses. Any fragment of a C
334: program can be included from another file. The include file could
335: even contain the beginning of a statement that is concluded in the
336: containing file, or the end of a statement that was started in the
337: including file. However, a comment or a string or character constant
338: may not start in the included file and finish in the including file.
339: An unterminated comment, string constant or character constant in an
340: included file is considered to end (with an error message) at the end
341: of the file.
342:
343: The line following the `#include' command is always treated as a
344: separate line by the C preprocessor even if the included file lacks a
345: final newline.
346:
347:
348: File: cpp.info, Node: Once-Only, Next: Inheritance, Prev: Include Operation, Up: Header Files
349:
350: Once-Only Include Files
351: -----------------------
352:
353: Very often, one header file includes another. It can easily result
354: that a certain header file is included more than once. This may lead
355: to errors, if the header file defines structure types or typedefs, and
356: is certainly wasteful. Therefore, we often wish to prevent multiple
357: inclusion of a header file.
358:
359: The standard way to do this is to enclose the entire real contents
360: of the file in a conditional, like this:
361:
362: #ifndef __FILE_FOO_SEEN__
363: #define __FILE_FOO_SEEN__
364:
365: THE ENTIRE FILE
366:
367: #endif /* __FILE_FOO_SEEN__ */
368:
369: The macro `__FILE_FOO_SEEN__' indicates that the file has been
370: included once already; its name should begin with `__' to avoid
371: conflicts with user programs, and it should contain the name of the
372: file and some additional text, to avoid conflicts with other header
373: files.
374:
375: The GNU C preprocessor is programmed to notice when a header file
376: uses this particular construct and handle it efficiently. If a header
377: file is contained entirely in a `#ifndef' conditional, then it records
378: that fact. If a subsequent `#include' specifies the same file, and
379: the macro in the `#ifndef' is already defined, then the file is
380: entirely skipped, without even reading it.
381:
382: There is also an explicit command to tell the preprocessor that it
383: need not include a file more than once. This is called `#pragma once',
384: and was used *in addition to* the `#ifndef' conditional around the
385: contents of the header file. `#pragma once' is now obsolete and
386: should not be used at all.
387:
388: In the Objective C language, there is a variant of `#include'
389: called `#import' which includes a file, but does so at most once. If
390: you use `#import' *instead of* `#include', then you don't need the
391: conditionals inside the header file to prevent multiple execution of
392: the contents.
393:
394: `#import' is obsolete because it is not a well-designed feature.
395: It requires the users of a header file--the applications
396: programmers--to know that a certain header file should only be included
397: once. It is much better for the header file's implementor to write the
398: file so that users don't need to know this. Using `#ifndef'
399: accomplishes this goal.
400:
401:
402: File: cpp.info, Node: Inheritance, Prev: Once-Only, Up: Header Files
403:
404: Inheritance and Header Files
405: ============================
406:
407: "Inheritance" is what happens when one object or file derives some
408: of its contents by virtual copying from another object or file. In
409: the case of C header files, inheritance means that one header file
410: includes another header file and then replaces or adds something.
411:
412: If the inheriting header file and the base header file have
413: different names, then inheritance is straightforward: simply write
414: `#include "BASE"' in the inheriting file.
415:
416: Sometimes it is necessary to give the inheriting file the same name
417: as the base file. This is less straightforward.
418:
419: For example, suppose an application program uses the system header
420: file `sys/signal.h', but the version of `/usr/include/sys/signal.h' on
421: a particular system doesn't do what the application program expects.
422: It might be convenient to define a "local" version, perhaps under the
423: name `/usr/local/include/sys/signal.h', to override or add to the one
424: supplied by the system.
425:
426: You can do this by using the option `-I.' for compilation, and
427: writing a file `sys/signal.h' that does what the application program
428: expects. But making this file include the standard `sys/signal.h' is
429: not so easy--writing `#include <sys/signal.h>' in that file doesn't
430: work, because it includes your own version of the file, not the
431: standard system version. Used in that file itself, this leads to an
432: infinite recursion and a fatal error in compilation.
433:
434: `#include </usr/include/sys/signal.h>' would find the proper file,
435: but that is not clean, since it makes an assumption about where the
436: system header file is found. This is bad for maintenance, since it
437: means that any change in where the system's header files are kept
438: requires a change somewhere else.
439:
440: The clean way to solve this problem is to use `#include_next',
441: which means, "Include the *next* file with this name." This command
442: works like `#include' except in searching for the specified file: it
443: starts searching the list of header file directories *after* the
444: directory in which the current file was found.
445:
446: Suppose you specify `-I /usr/local/include', and the list of
447: directories to search also includes `/usr/include'; and suppose that
448: both directories contain a file named `sys/signal.h'. Ordinary
449: `#include <sys/signal.h>' finds the file under `/usr/local/include'.
450: If that file contains `#include_next <sys/signal.h>', it starts
451: searching after that directory, and finds the file in `/usr/include'.
452:
453:
454: File: cpp.info, Node: Macros, Next: Conditionals, Prev: Header Files, Up: Top
455:
456: Macros
457: ======
458:
459: A macro is a sort of abbreviation which you can define once and then
460: use later. There are many complicated features associated with macros
461: in the C preprocessor.
462:
463: * Menu:
464:
465: * Simple Macros:: Macros that always expand the same way.
466: * Argument Macros:: Macros that accept arguments that are substituted
467: into the macro expansion.
468: * Predefined:: Predefined macros that are always available.
469: * Stringification:: Macro arguments converted into string constants.
470: * Concatenation:: Building tokens from parts taken from macro arguments.
471: * Undefining:: Cancelling a macro's definition.
472: * Redefining:: Changing a macro's definition.
473: * Macro Pitfalls:: Macros can confuse the unwary. Here we explain
474: several common problems and strange features.
475:
476:
477: File: cpp.info, Node: Simple Macros, Next: Argument Macros, Prev: Macros, Up: Macros
478:
479: Simple Macros
480: -------------
481:
482: A "simple macro" is a kind of abbreviation. It is a name which
483: stands for a fragment of code. Some people refer to these as
484: "manifest constants".
485:
486: Before you can use a macro, you must "define" it explicitly with the
487: `#define' command. `#define' is followed by the name of the macro and
488: then the code it should be an abbreviation for. For example,
489:
490: #define BUFFER_SIZE 1020
491:
492: defines a macro named `BUFFER_SIZE' as an abbreviation for the text
493: `1020'. Therefore, if somewhere after this `#define' command there
494: comes a C statement of the form
495:
496: foo = (char *) xmalloc (BUFFER_SIZE);
497:
498: then the C preprocessor will recognize and "expand" the macro
499: `BUFFER_SIZE', resulting in
500:
501: foo = (char *) xmalloc (1020);
502:
503: the definition must be a single line; however, it may not end in the
504: middle of a multi-line string constant or character constant.
505:
506: The use of all upper case for macro names is a standard convention.
507: Programs are easier to read when it is possible to tell at a glance
508: which names are macros.
509:
510: Normally, a macro definition must be a single line, like all C
511: preprocessor commands. (You can split a long macro definition
512: cosmetically with Backslash-Newline.) There is one exception:
513: Newlines can be included in the macro definition if within a string or
514: character constant. By the same token, it is not possible for a macro
515: definition to contain an unbalanced quote character; the definition
516: automatically extends to include the matching quote character that
517: ends the string or character constant. Comments within a macro
518: definition may contain Newlines, which make no difference since the
519: comments are entirely replaced with Spaces regardless of their
520: contents.
521:
522: Aside from the above, there is no restriction on what can go in a
523: macro body. Parentheses need not balance. The body need not resemble
524: valid C code. (Of course, you might get error messages from the C
525: compiler when you use the macro.)
526:
527: The C preprocessor scans your program sequentially, so macro
528: definitions take effect at the place you write them. Therefore, the
529: following input to the C preprocessor
530:
531: foo = X;
532: #define X 4
533: bar = X;
534:
535: produces as output
536:
537: foo = X;
538:
539: bar = 4;
540:
541: After the preprocessor expands a macro name, the macro's definition
542: body is appended to the front of the remaining input, and the check
543: for macro calls continues. Therefore, the macro body can contain
544: calls to other macros. For example, after
545:
546: #define BUFSIZE 1020
547: #define TABLESIZE BUFSIZE
548:
549: the name `TABLESIZE' when used in the program would go through two
550: stages of expansion, resulting ultimately in `1020'.
551:
552: This is not at all the same as defining `TABLESIZE' to be `1020'.
553: The `#define' for `TABLESIZE' uses exactly the body you specify--in
554: this case, `BUFSIZE'--and does not check to see whether it too is the
555: name of a macro. It's only when you *use* `TABLESIZE' that the result
556: of its expansion is checked for more macro names. *Note Cascaded
557: Macros::.
558:
559:
560: File: cpp.info, Node: Argument Macros, Next: Predefined, Prev: Simple Macros, Up: Macros
561:
562: Macros with Arguments
563: ---------------------
564:
565: A simple macro always stands for exactly the same text, each time
566: it is used. Macros can be more flexible when they accept "arguments".
567: Arguments are fragments of code that you supply each time the macro is
568: used. These fragments are included in the expansion of the macro
569: according to the directions in the macro definition.
570:
571: To define a macro that uses arguments, you write a `#define' command
572: with a list of "argument names" in parentheses after the name of the
573: macro. The argument names may be any valid C identifiers, separated by
574: commas and optionally whitespace. The open-parenthesis must follow the
575: macro name immediately, with no space in between.
576:
577: For example, here is a macro that computes the minimum of two
578: numeric values, as it is defined in many C programs:
579:
580: #define min(X, Y) ((X) < (Y) ? (X) : (Y))
581:
582: (This is not the best way to define a "minimum" macro in GNU C. *Note
583: Side Effects::, for more information.)
584:
585: To use a macro that expects arguments, you write the name of the
586: macro followed by a list of "actual arguments" in parentheses.
587: separated by commas. The number of actual arguments you give must
588: match the number of arguments the macro expects. Examples of use of
589: the macro `min' include `min (1, 2)' and `min (x + 28, *p)'.
590:
591: The expansion text of the macro depends on the arguments you use.
592: Each of the argument names of the macro is replaced, throughout the
593: macro definition, with the corresponding actual argument. Using the
594: same macro `min' defined above, `min (1, 2)' expands into
595:
596: ((1) < (2) ? (1) : (2))
597:
598: where `1' has been substituted for `X' and `2' for `Y'.
599:
600: Likewise, `min (x + 28, *p)' expands into
601:
602: ((x + 28) < (*p) ? (x + 28) : (*p))
603:
604: Parentheses in the actual arguments must balance; a comma within
605: parentheses does not end an argument. However, there is no requirement
606: for brackets or braces to balance, and they do not prevent a comma from
607: separating arguments. Thus,
608:
609: macro (array[x = y, x + 1])
610:
611: passes two arguments to `macro': `array[x = y' and `x + 1]'. If you
612: want to supply `array[x = y, x + 1]' as an argument, you must write it
613: as `array[(x = y, x + 1)]', which is equivalent C code.
614:
615: After the actual arguments are substituted into the macro body, the
616: entire result is appended to the front of the remaining input, and the
617: check for macro calls continues. Therefore, the actual arguments can
618: contain calls to other macros, either with or without arguments, or
619: even to the same macro. The macro body can also contain calls to
620: other macros. For example, `min (min (a, b), c)' expands into this
621: text:
622:
623: ((((a) < (b) ? (a) : (b))) < (c)
624: ? (((a) < (b) ? (a) : (b)))
625: : (c))
626:
627: (Line breaks shown here for clarity would not actually be generated.)
628:
629: If you use the macro name followed by something other than an
630: open-parenthesis (after ignoring any spaces, tabs and comments that
631: follow), it is not a call to the macro, and the preprocessor does not
632: change what you have written. Therefore, it is possible for the same
633: name to be a variable or function in your program as well as a macro,
634: and you can choose in each instance whether to refer to the macro (if
635: an actual argument list follows) or the variable or function (if an
636: argument list does not follow).
637:
638: Such dual use of one name could be confusing and should be avoided
639: except when the two meanings are effectively synonymous: that is, when
640: the name is both a macro and a function and the two have similar
641: effects. You can think of the name simply as a function; use of the
642: name for purposes other than calling it (such as, to take the address)
643: will refer to the function, while calls will expand the macro and
644: generate better but equivalent code. For example, you can use a
645: function named `min' in the same source file that defines the macro.
646: If you write `&min' with no argument list, you refer to the function.
647: If you write `min (x, bb)', with an argument list, the macro is
648: expanded. If you write `(min) (a, bb)', where the name `min' is not
649: followed by an open-parenthesis, the macro is not expanded, so you
650: wind up with a call to the function `min'.
651:
652: You may not define the same name as both a simple macro and a macro
653: with arguments.
654:
655: In the definition of a macro with arguments, the list of argument
656: names must follow the macro name immediately with no space in between.
657: If there is a space after the macro name, the macro is defined as
658: taking no arguments, and all the rest of the lineis taken to be the
659: expansion. The reason for this is that it is often useful to define a
660: macro that takes no arguments and whose definition begins with an
661: identifier in parentheses. This rule about spaces makes it possible
662: for you to do either this:
663:
664: #define FOO(x) - 1 / (x)
665:
666: (which defines `FOO' to take an argument and expand into minus the
667: reciprocal of that argument) or this:
668:
669: #define BAR (x) - 1 / (x)
670:
671: (which defines `BAR' to take no argument and always expand into `(x) -
672: 1 / (x)').
673:
674: Note that the *uses* of a macro with arguments can have spaces
675: before the left parenthesis; it's the *definition* where it matters
676: whether there is a space.
677:
678:
679: File: cpp.info, Node: Predefined, Next: Stringification, Prev: Argument Macros, Up: Macros
680:
681: Predefined Macros
682: -----------------
683:
684: Several simple macros are predefined. You can use them without
685: giving definitions for them. They fall into two classes: standard
686: macros and system-specific macros.
687:
688: * Menu:
689:
690: * Standard Predefined:: Standard predefined macros.
691: * Nonstandard Predefined:: Nonstandard predefined macros.
692:
693:
694: File: cpp.info, Node: Standard Predefined, Next: Nonstandard Predefined, Prev: Predefined, Up: Predefined
695:
696: Standard Predefined Macros
697: ..........................
698:
699: The standard predefined macros are available with the same meanings
700: regardless of the machine or operating system on which you are using
701: GNU C. Their names all start and end with double underscores. Those
702: preceding `__GNUC__' in this table are standardized by ANSI C; the
703: rest are GNU C extensions.
704:
705: `__FILE__'
706: This macro expands to the name of the current input file, in the
707: form of a C string constant. The precise name returned is the
708: one that was specified in `#include' or as the input file name
709: argument.
710:
711: `__LINE__'
712: This macro expands to the current input line number, in the form
713: of a decimal integer constant. While we call it a predefined
714: macro, it's a pretty strange macro, since its "definition"
715: changes with each new line of source code.
716:
717: This and `__FILE__' are useful in generating an error message to
718: report an inconsistency detected by the program; the message can
719: state the source line at which the inconsistency was detected.
720: For example,
721:
722: fprintf (stderr, "Internal error: "
723: "negative string length "
724: "%d at %s, line %d.",
725: length, __FILE__, __LINE__);
726:
727: A `#include' command changes the expansions of `__FILE__' and
728: `__LINE__' to correspond to the included file. At the end of
729: that file, when processing resumes on the input file that
730: contained the `#include' command, the expansions of `__FILE__' and
731: `__LINE__' revert to the values they had before the `#include'
732: (but `__LINE__' is then incremented by one as processing moves to
733: the line after the `#include').
734:
735: The expansions of both `__FILE__' and `__LINE__' are altered if a
736: `#line' command is used. *Note Combining Sources::.
737:
738: `__INCLUDE_LEVEL__'
739: This macro expands to a decimal integer constant that represents
740: the depth of nesting in include files. The value of this macro is
741: incremented on every `#include' command and decremented at every
742: end of file.
743:
744: `__DATE__'
745: This macro expands to a string constant that describes the date on
746: which the preprocessor is being run. The string constant contains
747: eleven characters and looks like `"Jan 29 1987"' or
748: `"Apr 1 1905"'.
749:
750: `__TIME__'
751: This macro expands to a string constant that describes the time at
752: which the preprocessor is being run. The string constant contains
753: eight characters and looks like `"23:59:01"'.
754:
755: `__STDC__'
756: This macro expands to the constant 1, to signify that this is ANSI
757: Standard C. (Whether that is actually true depends on what C
758: compiler will operate on the output from the preprocessor.)
759:
760: `__GNUC__'
761: This macro is defined if and only if this is GNU C. This macro is
762: defined only when the entire GNU C compiler is in use; if you
763: invoke the preprocessor directly, `__GNUC__' is undefined.
764:
765: `__STRICT_ANSI__'
766: This macro is defined if and only if the `-ansi' switch was
767: specified when GNU C was invoked. Its definition is the null
768: string. This macro exists primarily to direct certain GNU header
769: files not to define certain traditional Unix constructs which are
770: incompatible with ANSI C.
771:
772: `__BASE_FILE__'
773: This macro expands to the name of the main input file, in the form
774: of a C string constant. This is the source file that was
775: specified as an argument when the C compiler was invoked.
776:
777: `__VERSION__'
778: This macro expands to a string which describes the version number
779: of GNU C. The string is normally a sequence of decimal numbers
780: separated by periods, such as `"1.18"'. The only reasonable use
781: of this macro is to incorporate it into a string constant.
782:
783: `__OPTIMIZE__'
784: This macro is defined in optimizing compilations. It causes
785: certain GNU header files to define alternative macro definitions
786: for some system library functions. It is unwise to refer to or
787: test the definition of this macro unless you make very sure that
788: programs will execute with the same effect regardless.
789:
790: `__CHAR_UNSIGNED__'
791: This macro is defined if and only if the data type `char' is
792: unsigned on the target machine. It exists to cause the standard
793: header file `limit.h' to work correctly. It is bad practice to
794: refer to this macro yourself; instead, refer to the standard
795: macros defined in `limit.h'. The preprocessor uses this macro to
796: determine whether or not to sign-extend large character constants
797: written in octal; see *Note The `#if' Command: #if Command.
798:
799:
800: File: cpp.info, Node: Nonstandard Predefined, Prev: Standard Predefined, Up: Predefined
801:
802: Nonstandard Predefined Macros
803: .............................
804:
805: The C preprocessor normally has several predefined macros that vary
806: between machines because their purpose is to indicate what type of
807: system and machine is in use. This manual, being for all systems and
808: machines, cannot tell you exactly what their names are; instead, we
809: offer a list of some typical ones. You can use `cpp -dM' to see the
810: values of predefined macros; *note Invocation::..
811:
812: Some nonstandard predefined macros describe the operating system in
813: use, with more or less specificity. For example,
814:
815: `unix'
816: `unix' is normally predefined on all Unix systems.
817:
818: `BSD'
819: `BSD' is predefined on recent versions of Berkeley Unix (perhaps
820: only in version 4.3).
821:
822: Other nonstandard predefined macros describe the kind of CPU, with
823: more or less specificity. For example,
824:
825: `vax'
826: `vax' is predefined on Vax computers.
827:
828: `mc68000'
829: `mc68000' is predefined on most computers whose CPU is a Motorola
830: 68000, 68010 or 68020.
831:
832: `m68k'
833: `m68k' is also predefined on most computers whose CPU is a 68000,
834: 68010 or 68020; however, some makers use `mc68000' and some use
835: `m68k'. Some predefine both names. What happens in GNU C
836: depends on the system you are using it on.
837:
838: `M68020'
839: `M68020' has been observed to be predefined on some systems that
840: use 68020 CPUs--in addition to `mc68000' and `m68k', which are
841: less specific.
842:
843: `_AM29K'
844: `_AM29000'
845: Both `_AM29K' and `_AM29000' are predefined for the AMD 29000 CPU
846: family.
847:
848: `ns32000'
849: `ns32000' is predefined on computers which use the National
850: Semiconductor 32000 series CPU.
851:
852: Yet other nonstandard predefined macros describe the manufacturer of
853: the system. For example,
854:
855: `sun'
856: `sun' is predefined on all models of Sun computers.
857:
858: `pyr'
859: `pyr' is predefined on all models of Pyramid computers.
860:
861: `sequent'
862: `sequent' is predefined on all models of Sequent computers.
863:
864: These predefined symbols are not only nonstandard, they are
865: contrary to the ANSI standard because their names do not start with
866: underscores. Therefore, the option `-ansi' inhibits the definition of
867: these symbols.
868:
869: This tends to make `-ansi' useless, since many programs depend on
870: the customary nonstandard predefined symbols. Even system header
871: files check them and will generate incorrect declarations if they do
872: not find the names that are expected. You might think that the header
873: files supplied for the Uglix computer would not need to test what
874: machine they are running on, because they can simply assume it is the
875: Uglix; but often they do, and they do so using the customary names.
876: As a result, very few C programs will compile with `-ansi'. We intend
877: to avoid such problems on the GNU system.
878:
879: What, then, should you do in an ANSI C program to test the type of
880: machine it will run on?
881:
882: GNU C offers a parallel series of symbols for this purpose, whose
883: names are made from the customary ones by adding `__' at the beginning
884: and end. Thus, the symbol `__vax__' would be available on a Vax, and
885: so on.
886:
887: The set of nonstandard predefined names in the GNU C preprocessor is
888: controlled (when `cpp' is itself compiled) by the macro
889: `CPP_PREDEFINES', which should be a string containing `-D' options,
890: separated by spaces. For example, on the Sun 3, we use the following
891: definition:
892:
893: #define CPP_PREDEFINES "-Dmc68000 -Dsun -Dunix -Dm68k"
894:
895: This macro is usually specified in `tm.h'.
896:
897:
898: File: cpp.info, Node: Stringification, Next: Concatenation, Prev: Predefined, Up: Macros
899:
900: Stringification
901: ---------------
902:
903: "Stringification" means turning a code fragment into a string
904: constant whose contents are the text for the code fragment. For
905: example, stringifying `foo (z)' results in `"foo (z)"'.
906:
907: In the C preprocessor, stringification is an option available when
908: macro arguments are substituted into the macro definition. In the
909: body of the definition, when an argument name appears, the character
910: `#' before the name specifies stringification of the corresponding
911: actual argument when it is substituted at that point in the
912: definition. The same argument may be substituted in other places in
913: the definition without stringification if the argument name appears in
914: those places with no `#'.
915:
916: Here is an example of a macro definition that uses stringification:
917:
918: #define WARN_IF(EXP) \
919: do { if (EXP) \
920: fprintf (stderr, "Warning: " #EXP "\n"); } \
921: while (0)
922:
923: Here the actual argument for `EXP' is substituted once as given, into
924: the `if' statement, and once as stringified, into the argument to
925: `fprintf'. The `do' and `while (0)' are a kludge to make it possible
926: to write `WARN_IF (ARG);', which the resemblance of `WARN_IF' to a
927: function would make C programmers want to do; *note Swallow
928: Semicolon::.).
929:
930: The stringification feature is limited to transforming one macro
931: argument into one string constant: there is no way to combine the
932: argument with other text and then stringify it all together. But the
933: example above shows how an equivalent result can be obtained in ANSI
934: Standard C using the feature that adjacent string constants are
935: concatenated as one string constant. The preprocessor stringifies
936: `EXP''s actual argument into a separate string constant, resulting in
937: text like
938:
939: do { if (x == 0) \
940: fprintf (stderr, "Warning: " "x == 0" "\n"); } \
941: while (0)
942:
943: but the C compiler then sees three consecutive string constants and
944: concatenates them into one, producing effectively
945:
946: do { if (x == 0) \
947: fprintf (stderr, "Warning: x == 0\n"); } \
948: while (0)
949:
950: Stringification in C involves more than putting doublequote
951: characters around the fragment; it is necessary to put backslashes in
952: front of all doublequote characters, and all backslashes in string and
953: character constants, in order to get a valid C string constant with
954: the proper contents. Thus, stringifying `p = "foo\n";' results in `"p
955: = \"foo\\n\";"'. However, backslashes that are not inside of string or
956: character constants are not duplicated: `\n' by itself stringifies to
957: `"\n"'.
958:
959: Whitespace (including comments) in the text being stringified is
960: handled according to precise rules. All leading and trailing
961: whitespace is ignored. Any sequence of whitespace in the middle of
962: the text is converted to a single space in the stringified result.
963:
964:
965: File: cpp.info, Node: Concatenation, Next: Undefining, Prev: Stringification, Up: Macros
966:
967: Concatenation
968: -------------
969:
970: "Concatenation" means joining two strings into one. In the context
971: of macro expansion, concatenation refers to joining two lexical units
972: into one longer one. Specifically, an actual argument to the macro
973: can be concatenated with another actual argument or with fixed text to
974: produce a longer name. The longer name might be the name of a
975: function, variable or type, or a C keyword; it might even be the name
976: of another macro, in which case it will be expanded.
977:
978: When you define a macro, you request concatenation with the special
979: operator `##' in the macro body. When the macro is called, after
980: actual arguments are substituted, all `##' operators are deleted, and
981: so is any whitespace next to them (including whitespace that was part
982: of an actual argument). The result is to concatenate the syntactic
983: tokens on either side of the `##'.
984:
985: Consider a C program that interprets named commands. There
986: probably needs to be a table of commands, perhaps an array of
987: structures declared as follows:
988:
989: struct command
990: {
991: char *name;
992: void (*function) ();
993: };
994:
995: struct command commands[] =
996: {
997: { "quit", quit_command},
998: { "help", help_command},
999: ...
1000: };
1001:
1002: It would be cleaner not to have to give each command name twice,
1003: once in the string constant and once in the function name. A macro
1004: which takes the name of a command as an argument can make this
1005: unnecessary. The string constant can be created with stringification,
1006: and the function name by concatenating the argument with `_command'.
1007: Here is how it is done:
1008:
1009: #define COMMAND(NAME) { #NAME, NAME ## _command }
1010:
1011: struct command commands[] =
1012: {
1013: COMMAND (quit),
1014: COMMAND (help),
1015: ...
1016: };
1017:
1018: The usual case of concatenation is concatenating two names (or a
1019: name and a number) into a longer name. But this isn't the only valid
1020: case. It is also possible to concatenate two numbers (or a number and
1021: a name, such as `1.5' and `e3') into a number. Also, multi-character
1022: operators such as `+=' can be formed by concatenation. In some cases
1023: it is even possible to piece together a string constant. However, two
1024: pieces of text that don't together form a valid lexical unit cannot be
1025: concatenated. For example, concatenation with `x' on one side and `+'
1026: on the other is not meaningful because those two characters can't fit
1027: together in any lexical unit of C. The ANSI standard says that such
1028: attempts at concatenation are undefined, but in the GNU C preprocessor
1029: it is well defined: it puts the `x' and `+' side by side with no
1030: particular special results.
1031:
1032: Keep in mind that the C preprocessor converts comments to
1033: whitespace before macros are even considered. Therefore, you cannot
1034: create a comment by concatenating `/' and `*': the `/*' sequence that
1035: starts a comment is not a lexical unit, but rather the beginning of a
1036: "long" space character. Also, you can freely use comments next to a
1037: `##' in a macro definition, or in actual arguments that will be
1038: concatenated, because the comments will be converted to spaces at
1039: first sight, and concatenation will later discard the spaces.
1040:
1041:
1042: File: cpp.info, Node: Undefining, Next: Redefining, Prev: Concatenation, Up: Macros
1043:
1044: Undefining Macros
1045: -----------------
1046:
1047: To "undefine" a macro means to cancel its definition. This is done
1048: with the `#undef' command. `#undef' is followed by the macro name to
1049: be undefined.
1050:
1051: Like definition, undefinition occurs at a specific point in the
1052: source file, and it applies starting from that point. The name ceases
1053: to be a macro name, and from that point on it is treated by the
1054: preprocessor as if it had never been a macro name.
1055:
1056: For example,
1057:
1058: #define FOO 4
1059: x = FOO;
1060: #undef FOO
1061: x = FOO;
1062:
1063: expands into
1064:
1065: x = 4;
1066:
1067: x = FOO;
1068:
1069: In this example, `FOO' had better be a variable or function as well as
1070: (temporarily) a macro, in order for the result of the expansion to be
1071: valid C code.
1072:
1073: The same form of `#undef' command will cancel definitions with
1074: arguments or definitions that don't expect arguments. The `#undef'
1075: command has no effect when used on a name not currently defined as a
1076: macro.
1077:
1078:
1079: File: cpp.info, Node: Redefining, Next: Macro Pitfalls, Prev: Undefining, Up: Macros
1080:
1081: Redefining Macros
1082: -----------------
1083:
1084: "Redefining" a macro means defining (with `#define') a name that is
1085: already defined as a macro.
1086:
1087: A redefinition is trivial if the new definition is transparently
1088: identical to the old one. You probably wouldn't deliberately write a
1089: trivial redefinition, but they can happen automatically when a header
1090: file is included more than once (*note Header Files::.), so they are
1091: accepted silently and without effect.
1092:
1093: Nontrivial redefinition is considered likely to be an error, so it
1094: provokes a warning message from the preprocessor. However, sometimes
1095: it is useful to change the definition of a macro in mid-compilation.
1096: You can inhibit the warning by undefining the macro with `#undef'
1097: before the second definition.
1098:
1099: In order for a redefinition to be trivial, the new definition must
1100: exactly match the one already in effect, with two possible exceptions:
1101:
1102: * Whitespace may be added or deleted at the beginning or the end.
1103:
1104: * Whitespace may be changed in the middle (but not inside strings).
1105: However, it may not be eliminated entirely, and it may not be
1106: added where there was no whitespace at all.
1107:
1108: Recall that a comment counts as whitespace.
1109:
1110:
1111: File: cpp.info, Node: Macro Pitfalls, Prev: Redefining, Up: Macros
1112:
1113: Pitfalls and Subtleties of Macros
1114: ---------------------------------
1115:
1116: In this section we describe some special rules that apply to macros
1117: and macro expansion, and point out certain cases in which the rules
1118: have counterintuitive consequences that you must watch out for.
1119:
1120: * Menu:
1121:
1122: * Misnesting:: Macros can contain unmatched parentheses.
1123: * Macro Parentheses:: Why apparently superfluous parentheses
1124: may be necessary to avoid incorrect grouping.
1125: * Swallow Semicolon:: Macros that look like functions
1126: but expand into compound statements.
1127: * Side Effects:: Unsafe macros that cause trouble when
1128: arguments contain side effects.
1129: * Self-Reference:: Macros whose definitions use the macros' own names.
1130: * Argument Prescan:: Actual arguments are checked for macro calls
1131: before they are substituted.
1132: * Cascaded Macros:: Macros whose definitions use other macros.
1133:
1134:
1135: File: cpp.info, Node: Misnesting, Next: Macro Parentheses, Prev: Macro Pitfalls, Up: Macro Pitfalls
1136:
1137: Improperly Nested Constructs
1138: ............................
1139:
1140: Recall that when a macro is called with arguments, the arguments are
1141: substituted into the macro body and the result is checked, together
1142: with the rest of the input file, for more macro calls.
1143:
1144: It is possible to piece together a macro call coming partially from
1145: the macro body and partially from the actual arguments. For example,
1146:
1147: #define double(x) (2*(x))
1148: #define call_with_1(x) x(1)
1149:
1150: would expand `call_with_1 (double)' into `(2*(1))'.
1151:
1152: Macro definitions do not have to have balanced parentheses. By
1153: writing an unbalanced open parenthesis in a macro body, it is possible
1154: to create a macro call that begins inside the macro body but ends
1155: outside of it. For example,
1156:
1157: #define strange(file) fprintf (file, "%s %d",
1158: ...
1159: strange(stderr) p, 35)
1160:
1161: This bizarre example expands to `fprintf (stderr, "%s %d", p, 35)'!
1162:
1163:
1164: File: cpp.info, Node: Macro Parentheses, Next: Swallow Semicolon, Prev: Misnesting, Up: Macro Pitfalls
1165:
1166: Unintended Grouping of Arithmetic
1167: .................................
1168:
1169: You may have noticed that in most of the macro definition examples
1170: shown above, each occurrence of a macro argument name had parentheses
1171: around it. In addition, another pair of parentheses usually surround
1172: the entire macro definition. Here is why it is best to write macros
1173: that way.
1174:
1175: Suppose you define a macro as follows,
1176:
1177: #define ceil_div(x, y) (x + y - 1) / y
1178:
1179: whose purpose is to divide, rounding up. (One use for this operation
1180: is to compute how many `int''s are needed to hold a certain number of
1181: `char''s.) Then suppose it is used as follows:
1182:
1183: a = ceil_div (b & c, sizeof (int));
1184:
1185: This expands into
1186:
1187: a = (b & c + sizeof (int) - 1) / sizeof (int);
1188:
1189: which does not do what is intended. The operator-precedence rules of
1190: C make it equivalent to this:
1191:
1192: a = (b & (c + sizeof (int) - 1)) / sizeof (int);
1193:
1194: But what we want is this:
1195:
1196: a = ((b & c) + sizeof (int) - 1)) / sizeof (int);
1197:
1198: Defining the macro as
1199:
1200: #define ceil_div(x, y) ((x) + (y) - 1) / (y)
1201:
1202: provides the desired result.
1203:
1204: However, unintended grouping can result in another way. Consider
1205: `sizeof ceil_div(1, 2)'. That has the appearance of a C expression
1206: that would compute the size of the type of `ceil_div (1, 2)', but in
1207: fact it means something very different. Here is what it expands to:
1208:
1209: sizeof ((1) + (2) - 1) / (2)
1210:
1211: This would take the size of an integer and divide it by two. The
1212: precedence rules have put the division outside the `sizeof' when it
1213: was intended to be inside.
1214:
1215: Parentheses around the entire macro definition can prevent such
1216: problems. Here, then, is the recommended way to define `ceil_div':
1217:
1218: #define ceil_div(x, y) (((x) + (y) - 1) / (y))
1219:
1220:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.