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