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