Lines Matching full:macro
38 The C preprocessor implements the macro language used to transform C,
85 * Macro Arguments::
91 * Directives Within Macro Arguments::
92 * Macro Pitfalls::
101 Macro Pitfalls
166 The C preprocessor, often known as "cpp", is a "macro processor" that
168 before compilation. It is called a macro processor because it allows
190 macro facilities. Most high level programming languages have their own
443 they are ordinary identifiers. You can define a macro whose name is a
571 * Macro expansion. You can define "macros", which are abbreviations
595 For example, `#define' is the directive that defines a macro.
597 The `#' which begins a directive cannot come from a macro expansion.
598 Also, the directive name is not macro expanded. Thus, if `foo' is
599 defined as a macro expanding to `define', that does not make `#foo' a
607 whitespace. For example, `#define' must be followed by a macro name
608 and the intended expansion of the macro.
622 A header file is a file containing C declarations and macro definitions
636 related declarations and macro definitions all or most of which
688 recognized, and macro names are not expanded. Thus, `#include <x/*y>'
742 Included files are not limited to declarations and macro definitions;
858 and the macro in the `#ifndef' is still defined, it does not bother to
864 The macro `FILE_FOO_SEEN' is called the "controlling macro" or
865 "guard macro". In a user header file, the macro name should not begin
867 conflicts with user programs. In any kind of header file, the macro
891 ability to use a macro for the header name. This is called a "computed
893 `#include', you simply put a macro name there instead:
903 You must be careful when you define the macro. `#define' saves
904 tokens, not text. The preprocessor has no way of knowing that the macro
912 not `"' or `<', then the entire line is macro-expanded like running
942 object-like macro which expands to a string constant. This will also
1044 A "macro" is a fragment of code which has been given a name. Whenever
1045 the name is used, it is replaced by the contents of the macro. There
1050 You may define any valid identifier as a macro, even if it is a C
1054 operator `defined' (*note Defined::) can never be defined as a macro,
1062 * Macro Arguments::
1068 * Directives Within Macro Arguments::
1069 * Macro Pitfalls::
1077 An "object-like macro" is a simple identifier which will be replaced by
1083 followed by the name of the macro and then the token sequence it should
1084 be an abbreviation for, which is variously referred to as the macro's
1089 defines a macro named `BUFFER_SIZE' as an abbreviation for the token
1095 then the C preprocessor will recognize and "expand" the macro
1101 By convention, macro names are written in uppercase. Programs are
1105 The macro's body ends at the end of the `#define' line. You may
1107 backslash-newline. When the macro is expanded, however, it will all
1119 There is no restriction on what can go in a macro body provided it
1122 you may get error messages from the C compiler when you use the macro.)
1124 The C preprocessor scans your program sequentially. Macro
1137 When the preprocessor expands a macro name, the macro's expansion
1138 replaces the macro invocation, then the expansion is examined for more
1147 `TABLESIZE' is expanded first to produce `BUFSIZE', then that macro is
1153 too contains macro names. Only when you _use_ `TABLESIZE' is the
1154 result of its expansion scanned for more macro names.
1168 If the expansion of a macro contains its own name, either directly or
1174 File: cpp.info, Node: Function-like Macros, Next: Macro Arguments, Prev: Object-like Macros, Up: Macros
1180 are called "function-like macros". To define a function-like macro,
1182 immediately after the macro name. For example,
1188 A function-like macro is only expanded if its name appears with a
1190 alone. This can be useful when you have a function and a macro of the
1199 Here the call to `foo()' will use the macro, but the function
1200 pointer will get the address of the real function. If the macro were to
1203 If you put spaces between the macro name and the parentheses in the
1204 macro definition, that does not define a function-like macro, it defines
1205 an object-like macro whose expansion happens to begin with a pair of
1213 macro. The third is the pair that was originally after the macro
1214 invocation. Since `lang_init' is an object-like macro, it does not
1218 File: cpp.info, Node: Macro Arguments, Next: Stringification, Prev: Function-like Macros, Up: Macros
1220 Macro Arguments
1224 To define a macro that uses arguments, you insert "parameters" between
1225 the pair of parentheses in the macro definition that make the macro
1229 To invoke a macro that takes arguments, you write the name of the
1230 macro followed by a list of "actual arguments" in parentheses, separated
1231 by commas. The invocation of the macro need not be restricted to a
1234 parameters in the macro definition. When the macro is expanded, each
1237 macro body.)
1239 As an example, here is a macro that computes the minimum of two
1248 macro arguments. *Note Macro Pitfalls::, for detailed explanations.)
1257 macro (array[x = y, x + 1])
1259 passes two arguments to `macro': `array[x = y' and `x + 1]'. If you
1263 All arguments to a macro are completely macro-expanded before they
1264 are substituted into the macro body. After substitution, the complete
1267 not worry about whether any function call is actually a macro
1283 You can leave macro arguments empty; this is not an error to the
1285 cannot leave out arguments entirely; if a macro takes two arguments,
1294 min() error--> macro "min" requires 2 arguments, but only 1 given
1295 min(,,) error--> macro "min" passed 3 arguments, but takes just 2
1297 Whitespace is not a preprocessing token, so if a macro `foo' takes
1300 incorrect on this point, insisting that a function-like macro that
1304 Macro parameters appearing inside string literals are not replaced by
1311 File: cpp.info, Node: Stringification, Next: Concatenation, Prev: Macro Arguments, Up: Macros
1316 Sometimes you may want to convert a macro argument into a string
1318 can use the `#' preprocessing operator instead. When a macro parameter
1321 Unlike normal parameter replacement, the argument is not macro-expanded
1331 Here is an example of a macro definition that uses stringification:
1343 `x' were a macro, it would be expanded in the `if' statement, but not
1366 There is no way to convert a macro argument into a character
1369 If you want to stringify the result of expansion of a macro argument,
1383 macro-expanded first. But `s' is an ordinary argument to `xstr', so it
1384 is completely macro-expanded before `xstr' itself is expanded (*note
1386 argument, it has already been macro-expanded.
1396 preprocessing operator performs token pasting. When a macro is
1399 original tokens in the macro expansion. Usually both will be
1414 Both the tokens combined by `##' could come from the macro body, but
1417 macro argument. If either of the tokens next to an `##' is a parameter
1419 with stringification, the actual argument is not macro-expanded first.
1427 is an error if `##' appears at either end of a macro body.
1447 once in the string constant and once in the function name. A macro
1468 A macro can be declared to accept a variable number of arguments much as
1469 a function can. The syntax for defining the macro is similar to that of
1474 This kind of macro is called "variadic". When the macro is invoked,
1476 macro has none), including any commas, become the "variable argument".
1478 macro body wherever it appears. Thus, we have this expansion:
1483 The variable argument is completely macro-expanded before it is
1484 inserted into the macro expansion, just like an ordinary argument. You
1489 If your macro is complicated, you may want a more descriptive name
1493 macro above could be written
1498 in the same macro.
1501 variadic macro. We could define `eprintf' like this, instead:
1526 and the variable argument is left out when the `eprintf' macro is used,
1534 The above explanation is ambiguous about the case where the only macro
1543 appear is in the replacement list of a variadic macro. It may not be
1544 used as a macro name, macro argument name, or within a different type
1545 of macro. It may also be forbidden in open text; the standard is
1599 This macro expands to the name of the current input file, in the
1604 macro.
1607 This macro expands to the current input line number, in the form
1609 macro, it's a pretty strange macro, since its "definition" changes
1636 manual). Neither of them is a macro; the preprocessor does not know the
1641 This macro expands to a string constant that describes the date on
1651 This macro expands to a string constant that describes the time at
1660 In normal operation, this macro expands to the constant 1, to
1666 This macro is not defined if the `-traditional-cpp' option is used.
1678 This macro expands to the C Standard's version number, a long
1690 This macro is not defined if the `-traditional-cpp' option is
1694 This macro is defined, with value 1, if the compiler's target is a
1699 This macro is defined when the C++ compiler is in use. You can use
1701 or a C++ compiler. This macro is similar to `__STDC_VERSION__', in
1703 implementation of the 1998 C++ standard will define this macro to
1709 This macro is defined, with value 1, when the Objective-C compiler
1714 This macro is defined with value 1 when preprocessing assembly
1730 This macro expands to sequential integral values starting from 0.
1789 GCC defines this macro if and only if the `-ansi' switch, or a
1792 This macro exists primarily to direct GNU libc's header files to
1797 This macro expands to the name of the main input file, in the form
1802 This macro expands to a decimal integer constant that represents
1803 the depth of nesting in include files. The value of this macro is
1809 This macro is defined if the target uses the ELF object format.
1812 This macro expands to a string constant which describes the
1834 GCC defines this macro if functions declared `inline' will be
1841 GCC defines this macro if functions declared `inline' will be
1847 If this macro is defined, GCC supports the `gnu_inline' function
1850 macro is defined, an older version of GCC is being used: `inline'
1855 GCC defines this macro if and only if the data type `char' is
1858 macro yourself; instead, refer to the standard macros defined in
1862 Like `__CHAR_UNSIGNED__', this macro is defined if and only if the
1866 This macro expands to a single token (not a string constant) which
1874 This macro expands to a single token which is the prefix applied to
1879 This macro will have the correct definition even if
1900 numerical limits work correctly. You should not use this macro
1934 This macro is defined, with value 1, when compiling a C++ source
1940 This macro is defined, with value 1, when compiling a C++ source
1942 compiling the file, then this macro is not defined.
1945 This macro is defined, with value 1, when compiling a C++ source
1947 used when compiling the file, then this macro is not defined.
1950 This macro is defined, with value 1, if the compiler uses the old
1954 This macro is defined when compiling a C++ source file with the
1961 This macro is defined when compiling a C++ source file. It has the
1965 will not collapse such symbols, this macro is defined with value
1967 macro; the purpose of this macro is to ease implementation of the
1971 This macro
1973 the GNU runtime is used, this macro is not defined, so that you
1974 can use this macro to determine which runtime (NeXT or GNU) is
1984 This macro is defined, with value 1, when `-fstack-protector' is in
1988 This macro is defined, with value 2, when `-fstack-protector-all'
1992 This macro expands to a string constant that describes the date
2033 provides a parallel macro with two underscores added at the beginning
2062 `iso646.h'. That header defines each one as a normal object-like macro
2081 File: cpp.info, Node: Undefining and Redefining Macros, Next: Directives Within Macro Arguments, Prev: Predefined Macros, Up: Macros
2086 If a macro ceases to be useful, it may be "undefined" with the `#undef'
2087 directive. `#undef' takes a single argument, the name of the macro to
2088 undefine. You use the bare macro name, even if the macro is
2090 the macro name. `#undef' has no effect if the name is not a macro.
2097 Once a macro has been undefined, that identifier may be "redefined"
2098 as a macro by a subsequent `#define' directive. The new definition
2101 However, if an identifier which is currently a macro is redefined,
2103 Two macro definitions are effectively the same if:
2104 * Both are the same type of macro (object- or function-like).
2124 If a macro is redefined with a definition that is not effectively the
2126 macro to use the new definition. If the new definition is effectively
2128 instance, two different headers to define a common macro. The
2132 File: cpp.info, Node: Directives Within Macro Arguments, Next: Macro Pitfalls, Prev: Undefining and Redefining Macros, Up: Macros
2134 3.9 Directives Within Macro Arguments
2138 arguments of a macro. The C and C++ standards declare that behavior in
2148 `printf' had changed to be a function-like macro, and their code would
2150 process arbitrary directives within macro arguments in exactly the same
2152 macro invocation not present.
2154 If, within a macro invocation, that macro is redefined, then the new
2172 File: cpp.info, Node: Macro Pitfalls, Prev: Directives Within Macro Arguments, Up: Macros
2174 3.10 Macro Pitfalls
2178 macro expansion, and point out certain cases in which the rules have
2192 File: cpp.info, Node: Misnesting, Next: Operator Precedence Problems, Up: Macro Pitfalls
2197 When a macro is called with arguments, the arguments are substituted
2198 into the macro body and the result is checked, together with the rest of
2199 the input file, for more macro calls. It is possible to piece together
2200 a macro call coming partially from the macro body and partially from the
2209 Macro definitions do not have to have balanced parentheses. By
2210 writing an unbalanced open parenthesis in a macro body, it is possible
2211 to create a macro call that begins inside the macro body but ends
2219 The ability to piece together a macro call can be useful, but the
2220 use of unbalanced open parentheses in a macro body is just confusing,
2224 File: cpp.info, Node: Operator Precedence Problems, Next: Swallowing the Semicolon, Prev: Misnesting, Up: Macro Pitfalls
2229 You may have noticed that in most of the macro definition examples shown
2230 above, each occurrence of a macro argument name had parentheses around
2232 entire macro definition. Here is why it is best to write macros that
2235 Suppose you define a macro as follows,
2255 Defining the macro as
2272 Parentheses around the entire macro definition prevent such problems.
2278 File: cpp.info, Node: Swallowing the Semicolon, Next: Duplication of Side Effects, Prev: Operator Precedence Problems, Up: Macro Pitfalls
2283 Often it is desirable to define a macro that expands into a compound
2284 statement. Consider, for example, the following macro, that advances a
2294 Here backslash-newline is used to split the macro definition, which must
2296 be laid out if not part of a macro definition.
2298 A call to this macro might be `SKIP_SPACES (p, lim)'. Strictly
2316 The definition of the macro `SKIP_SPACES' can be altered to solve
2334 File: cpp.info, Node: Duplication of Side Effects, Next: Self-Referential Macros, Prev: Swallowing the Semicolon, Up: Macro Pitfalls
2339 Many C programs define a macro `min', for "minimum", like this:
2343 When you use this macro with an argument containing a side effect,
2356 into the macro expansion. As a result, `foo' might be called two times
2359 say that `min' is an "unsafe" macro.
2379 be careful when _using_ the macro `min'. For example, you can
2393 File: cpp.info, Node: Self-Referential Macros, Next: Argument Prescan, Prev: Duplication of Side Effects, Up: Macro Pitfalls
2398 A "self-referential" macro is one whose name appears in its definition.
2399 Recall that all macro definitions are rescanned for more macros to
2400 replace. If the self-reference were considered a use of the macro, it
2402 self-reference is not considered a macro call. It is passed into the
2414 `(4 + foo)'. Therefore, this macro definition has the possibly useful
2420 expect that it is a macro as well. The reader will come across the
2424 One common, useful use of self-reference is to create a macro which
2429 then the macro `EPERM' expands to `EPERM'. Effectively, it is left
2431 tell that it's a macro with `#ifdef'. You might do this if you want to
2435 If a macro `x' expands to use a macro `y', and the expansion of `y'
2436 refers to the macro `x', that is an "indirect self-reference" of `x'.
2450 Each macro is expanded when it appears in the definition of the other
2451 macro, but not when it indirectly appears in its own definition.
2454 File: cpp.info, Node: Argument Prescan, Next: Newlines in Arguments, Prev: Self-Referential Macros, Up: Macro Pitfalls
2459 Macro arguments are completely macro-expanded before they are
2460 substituted into a macro body, unless they are stringified or pasted
2461 with other tokens. After substitution, the entire macro body, including
2463 The result is that the arguments are scanned _twice_ to expand macro
2467 macro calls, they are expanded during the first scan. The result
2468 therefore contains no macro calls, so the second scan does not change
2470 single remaining scan would find the same macro calls and produce the
2474 self-referential macro is used in an argument of another macro (*note
2475 Self-Referential Macros::): the self-referential macro would be
2486 * Nested calls to a macro.
2488 We say that "nested" calls to a macro occur when a macro's argument
2489 contains a call to that very macro. For example, if `f' is a macro
2501 occur. If you _want_ to expand a macro, then stringify or
2502 concatenate its expansion, you can do that by causing one macro to
2503 call another macro that does the stringification or concatenation.
2518 This can cause a macro expanded on the second scan to be called
2541 File: cpp.info, Node: Newlines in Arguments, Prev: Argument Prescan, Up: Macro Pitfalls
2546 The invocation of a function-like macro can extend over many logical
2575 arithmetic expressions, or whether a name is defined as a macro, or both
2663 #ifdef MACRO
2667 #endif /* MACRO */
2670 included in the output of the preprocessor if and only if MACRO is
2671 defined. We say that the conditional "succeeds" if MACRO is defined,
2690 sometimes put MACRO directly after the `#endif' without enclosing it in
2695 Sometimes you wish to use some code if a macro is _not_ defined.
2700 Macro definitions can vary between compilations for several reasons.
2715 choosing a macro name to specify which program you want, writing
2716 conditionals to test whether or how this macro is defined, and
2717 then controlling the state of the macro with command line options,
2734 expression, rather than the mere existence of one macro. Its syntax is
2762 number zero. This allows you to write `#if MACRO' instead of
2763 `#ifdef MACRO', if you know that MACRO, when defined, will always
2769 which is not a macro in an `#if'.
2792 to test whether a certain name is defined as a macro. `defined NAME'
2794 defined as a macro at the current point in the program, and 0
2795 otherwise. Thus, `#if defined MACRO' is precisely equivalent to
2796 `#ifdef MACRO'.
2798 `defined' is useful when you wish to test more than one macro for
2804 defined as a macro.
2814 If the `defined' operator appears as a result of a macro expansion,
2905 `notdef' might be accidentally defined as a macro, and then the
2948 Neither `#error' nor `#warning' macro-expands its argument.
2962 and line number. All the tokens resulting from macro expansion are
2964 outermost macro was used. We intend to be more accurate in the future.
2998 ANYTHING ELSE is checked for macro calls, which are expanded. The
3059 as the result of macro expansion. `_Pragma' is an operator, much like
3060 `sizeof' or `defined', and can be embedded in a macro.
3112 macro which was defined before the identifier was poisoned, it
3222 `#' and the directive name. If macro expansion happens to generate
3300 have a matching closing quote. In particular, a macro may be defined
3308 #define m This macro's fine and has an unmatched quote
3325 leading and trailing horizontal whitespace from a macro's replacement
3331 the macro call. Similarly, the text at the end of a macro's expansion
3332 can run together with the text after the macro invocation to produce a
3336 macro is expanded, but if the `-CC' option is passed on the command
3338 removes comments even before saving the macro replacement text, but it
3340 even in the function-like macro case.)
3344 these operators can be obtained in a different way. Macro names that
3345 are embedded in quotes, either from the main file or after macro
3348 CPP replaces an unquoted object-like macro name with its replacement
3350 standard macro expansion, traditional macro expansion has no provision
3351 to prevent recursion. If an object-like macro appears unquoted in its
3354 macros, emits an error message, and continues after the offending macro
3371 This implementation removes all comments from macro arguments, unless
3378 is treated as an invocation of the macro `f' with a single argument
3380 macro that takes no arguments, you must not leave any whitespace
3383 If a macro argument crosses a new line, the new line is replaced with
3427 * If a line that looks like a directive appears within macro
3444 * Macro parameters that appear within string literals in the macro
3445 body. In traditional C macro replacement takes place within
3458 * A function-like macro that appears without an argument list. In
3460 merely means that the macro is not expanded.
3575 * Interpretation of the filename resulting from a macro-expanded
3580 * Treatment of a `#pragma' directive that after macro-expansion
3583 No macro expansion occurs on any `#pragma' directive line, so the
3623 * Significant initial characters in an identifier or macro name.
3634 * Number of parameters in a macro definition and arguments in a
3635 macro call.
3696 ignored. (This is similar to the rules governing macro redefinition.)
3826 entirely when you use a variable argument macro. This is
3832 Formerly, in a macro expansion, if `##' appeared before a variable
3834 argument in the macro invocation was empty, previous versions of
3905 Predefine NAME as a macro, with definition `1'.
3917 If you wish to define a function-like macro on the command line,
3988 Warn whenever an identifier which is not a macro is encountered in
3994 macro is "used" if it is expanded or tested for existence at least
3995 once. The preprocessor will also warn if the macro has not been
4001 _Note:_ If a macro is actually used, but only used in skipped
4004 macro's definition by, for example, moving it into the first
4306 operations, such as macro expansion and trigraph conversion are
4330 preprocessed. This suppresses things like macro expansion,
4429 Like `D', but emit only the macro names, not their expansions.
4455 Do not discard comments, including during macro expansion. This is
4457 passed through to the output file where the macro is expanded.
4460 option causes all C++-style comments inside a macro to be
4462 that macro from inadvertently commenting out the remainder of the
5140 * arguments: Macro Arguments. (line 6)
5141 * arguments in macro definitions: Macro Arguments. (line 6)
5161 * controlling macro: Once-Only Headers. (line 35)
5176 * empty macro arguments: Macro Arguments. (line 66)
5185 * guard macro: Once-Only Headers. (line 35)
5200 * macro argument expansion: Argument Prescan. (line 6)
5201 * macro arguments and directives: Directives Within Macro Arguments.
5204 * macros with arguments: Macro Arguments. (line 6)
5209 * newlines in macro arguments: Newlines in Arguments.
5213 * object-like macro: Object-like Macros. (line 6)
5219 * parentheses in macro bodies: Operator Precedence Problems.
5221 * pitfalls of macros: Macro Pitfalls. (line 6)
5230 * prescan of macro arguments: Argument Prescan. (line 6)
5231 * problems with macros: Macro Pitfalls. (line 6)
5242 * semicolons (after macro calls): Swallowing the Semicolon.
5244 * side effects (in macro arguments): Duplication of Side Effects.
5293 Node: Macro Arguments49036
5303 Node: Directives Within Macro Arguments88582
5304 Node: Macro Pitfalls90130
