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.
1785 GCC defines this macro if and only if the `-ansi' switch, or a
1788 This macro exists primarily to direct GNU libc's header files to
1793 This macro expands to the name of the main input file, in the form
1798 This macro expands to a decimal integer constant that represents
1799 the depth of nesting in include files. The value of this macro is
1805 This macro is defined if the target uses the ELF object format.
1808 This macro expands to a string constant which describes the
1830 GCC defines this macro if functions declared `inline' will be
1837 GCC defines this macro if functions declared `inline' will be
1844 If this macro is defined, GCC supports the `gnu_inline' function
1847 macro is defined, an older version of GCC is being used: `inline'
1852 GCC defines this macro if and only if the data type `char' is
1855 macro yourself; instead, refer to the standard macros defined in
1859 Like `__CHAR_UNSIGNED__', this macro is defined if and only if the
1863 This macro expands to a single token (not a string constant) which
1871 This macro expands to a single token which is the prefix applied to
1876 This macro will have the correct definition even if
1897 numerical limits work correctly. You should not use this macro
1915 This macro is defined, with value 1, when compiling a C++ source
1921 This macro is defined, with value 1, when compiling a C++ source
1923 compiling the file, then this macro will not be defined.
1926 This macro is defined, with value 1, if the compiler uses the old
1930 This macro is defined when compiling a C++ source file. It has the
1934 will not collapse such symbols, this macro is defined with value
1936 macro; the purpose of this macro is to ease implementation of the
1940 This macro is defined, with value 1, if (and only if) the NeXT
1942 the GNU runtime is used, this macro is not defined, so that you
1943 can use this macro to determine which runtime (NeXT or GNU) is
1953 This macro is defined, with value 1, when `-fstack-protector' is in
1957 This macro is defined, with value 2, when `-fstack-protector-all'
1961 This macro expands to a string constant that describes the date
1993 provides a parallel macro with two underscores added at the beginning
2022 `iso646.h'. That header defines each one as a normal object-like macro
2041 File: cpp.info, Node: Undefining and Redefining Macros, Next: Directives Within Macro Arguments, Prev: Predefined Macros, Up: Macros
2046 If a macro ceases to be useful, it may be "undefined" with the `#undef'
2047 directive. `#undef' takes a single argument, the name of the macro to
2048 undefine. You use the bare macro name, even if the macro is
2050 the macro name. `#undef' has no effect if the name is not a macro.
2057 Once a macro has been undefined, that identifier may be "redefined"
2058 as a macro by a subsequent `#define' directive. The new definition
2061 However, if an identifier which is currently a macro is redefined,
2063 Two macro definitions are effectively the same if:
2064 * Both are the same type of macro (object- or function-like).
2084 If a macro is redefined with a definition that is not effectively the
2086 macro to use the new definition. If the new definition is effectively
2088 instance, two different headers to define a common macro. The
2092 File: cpp.info, Node: Directives Within Macro Arguments, Next: Macro Pitfalls, Prev: Undefining and Redefining Macros, Up: Macros
2094 3.9 Directives Within Macro Arguments
2098 arguments of a macro. The C and C++ standards declare that behavior in
2108 `printf' had changed to be a function-like macro, and their code would
2110 process arbitrary directives within macro arguments in exactly the same
2112 macro invocation not present.
2114 If, within a macro invocation, that macro is redefined, then the new
2132 File: cpp.info, Node: Macro Pitfalls, Prev: Directives Within Macro Arguments, Up: Macros
2134 3.10 Macro Pitfalls
2138 macro expansion, and point out certain cases in which the rules have
2152 File: cpp.info, Node: Misnesting, Next: Operator Precedence Problems, Up: Macro Pitfalls
2157 When a macro is called with arguments, the arguments are substituted
2158 into the macro body and the result is checked, together with the rest of
2159 the input file, for more macro calls. It is possible to piece together
2160 a macro call coming partially from the macro body and partially from the
2169 Macro definitions do not have to have balanced parentheses. By
2170 writing an unbalanced open parenthesis in a macro body, it is possible
2171 to create a macro call that begins inside the macro body but ends
2179 The ability to piece together a macro call can be useful, but the
2180 use of unbalanced open parentheses in a macro body is just confusing,
2184 File: cpp.info, Node: Operator Precedence Problems, Next: Swallowing the Semicolon, Prev: Misnesting, Up: Macro Pitfalls
2189 You may have noticed that in most of the macro definition examples shown
2190 above, each occurrence of a macro argument name had parentheses around
2192 entire macro definition. Here is why it is best to write macros that
2195 Suppose you define a macro as follows,
2215 Defining the macro as
2232 Parentheses around the entire macro definition prevent such problems.
2238 File: cpp.info, Node: Swallowing the Semicolon, Next: Duplication of Side Effects, Prev: Operator Precedence Problems, Up: Macro Pitfalls
2243 Often it is desirable to define a macro that expands into a compound
2244 statement. Consider, for example, the following macro, that advances a
2254 Here backslash-newline is used to split the macro definition, which must
2256 be laid out if not part of a macro definition.
2258 A call to this macro might be `SKIP_SPACES (p, lim)'. Strictly
2276 The definition of the macro `SKIP_SPACES' can be altered to solve
2294 File: cpp.info, Node: Duplication of Side Effects, Next: Self-Referential Macros, Prev: Swallowing the Semicolon, Up: Macro Pitfalls
2299 Many C programs define a macro `min', for "minimum", like this:
2303 When you use this macro with an argument containing a side effect,
2316 into the macro expansion. As a result, `foo' might be called two times
2319 say that `min' is an "unsafe" macro.
2339 be careful when _using_ the macro `min'. For example, you can
2353 File: cpp.info, Node: Self-Referential Macros, Next: Argument Prescan, Prev: Duplication of Side Effects, Up: Macro Pitfalls
2358 A "self-referential" macro is one whose name appears in its definition.
2359 Recall that all macro definitions are rescanned for more macros to
2360 replace. If the self-reference were considered a use of the macro, it
2362 self-reference is not considered a macro call. It is passed into the
2374 `(4 + foo)'. Therefore, this macro definition has the possibly useful
2380 expect that it is a macro as well. The reader will come across the
2384 One common, useful use of self-reference is to create a macro which
2389 then the macro `EPERM' expands to `EPERM'. Effectively, it is left
2391 tell that it's a macro with `#ifdef'. You might do this if you want to
2395 If a macro `x' expands to use a macro `y', and the expansion of `y'
2396 refers to the macro `x', that is an "indirect self-reference" of `x'.
2410 Each macro is expanded when it appears in the definition of the other
2411 macro, but not when it indirectly appears in its own definition.
2414 File: cpp.info, Node: Argument Prescan, Next: Newlines in Arguments, Prev: Self-Referential Macros, Up: Macro Pitfalls
2419 Macro arguments are completely macro-expanded before they are
2420 substituted into a macro body, unless they are stringified or pasted
2421 with other tokens. After substitution, the entire macro body, including
2423 The result is that the arguments are scanned _twice_ to expand macro
2427 macro calls, they are expanded during the first scan. The result
2428 therefore contains no macro calls, so the second scan does not change
2430 single remaining scan would find the same macro calls and produce the
2434 self-referential macro is used in an argument of another macro (*note
2435 Self-Referential Macros::): the self-referential macro would be
2446 * Nested calls to a macro.
2448 We say that "nested" calls to a macro occur when a macro's argument
2449 contains a call to that very macro. For example, if `f' is a macro
2461 occur. If you _want_ to expand a macro, then stringify or
2462 concatenate its expansion, you can do that by causing one macro to
2463 call another macro that does the stringification or concatenation.
2478 This can cause a macro expanded on the second scan to be called
2501 File: cpp.info, Node: Newlines in Arguments, Prev: Argument Prescan, Up: Macro Pitfalls
2506 The invocation of a function-like macro can extend over many logical
2535 arithmetic expressions, or whether a name is defined as a macro, or both
2623 #ifdef MACRO
2627 #endif /* MACRO */
2630 included in the output of the preprocessor if and only if MACRO is
2631 defined. We say that the conditional "succeeds" if MACRO is defined,
2650 sometimes put MACRO directly after the `#endif' without enclosing it in
2655 Sometimes you wish to use some code if a macro is _not_ defined.
2660 Macro definitions can vary between compilations for several reasons.
2675 choosing a macro name to specify which program you want, writing
2676 conditionals to test whether or how this macro is defined, and
2677 then controlling the state of the macro with command line options,
2694 expression, rather than the mere existence of one macro. Its syntax is
2722 number zero. This allows you to write `#if MACRO' instead of
2723 `#ifdef MACRO', if you know that MACRO, when defined, will always
2729 which is not a macro in an `#if'.
2752 to test whether a certain name is defined as a macro. `defined NAME'
2754 defined as a macro at the current point in the program, and 0
2755 otherwise. Thus, `#if defined MACRO' is precisely equivalent to
2756 `#ifdef MACRO'.
2758 `defined' is useful when you wish to test more than one macro for
2764 defined as a macro.
2774 If the `defined' operator appears as a result of a macro expansion,
2865 `notdef' might be accidentally defined as a macro, and then the
2908 Neither `#error' nor `#warning' macro-expands its argument.
2922 and line number. All the tokens resulting from macro expansion are
2924 outermost macro was used. We intend to be more accurate in the future.
2958 ANYTHING ELSE is checked for macro calls, which are expanded. The
3019 as the result of macro expansion. `_Pragma' is an operator, much like
3020 `sizeof' or `defined', and can be embedded in a macro.
3072 macro which was defined before the identifier was poisoned, it
3182 `#' and the directive name. If macro expansion happens to generate
3260 have a matching closing quote. In particular, a macro may be defined
3268 #define m This macro's fine and has an unmatched quote
3285 leading and trailing horizontal whitespace from a macro's replacement
3291 the macro call. Similarly, the text at the end of a macro's expansion
3292 can run together with the text after the macro invocation to produce a
3296 macro is expanded, but if the `-CC' option is passed on the command
3298 removes comments even before saving the macro replacement text, but it
3300 even in the function-like macro case.)
3304 these operators can be obtained in a different way. Macro names that
3305 are embedded in quotes, either from the main file or after macro
3308 CPP replaces an unquoted object-like macro name with its replacement
3310 standard macro expansion, traditional macro expansion has no provision
3311 to prevent recursion. If an object-like macro appears unquoted in its
3314 macros, emits an error message, and continues after the offending macro
3331 This implementation removes all comments from macro arguments, unless
3338 is treated as an invocation of the macro `f' with a single argument
3340 macro that takes no arguments, you must not leave any whitespace
3343 If a macro argument crosses a new line, the new line is replaced with
3387 * If a line that looks like a directive appears within macro
3404 * Macro parameters that appear within string literals in the macro
3405 body. In traditional C macro replacement takes place within
3418 * A function-like macro that appears without an argument list. In
3420 merely means that the macro is not expanded.
3535 * Interpretation of the filename resulting from a macro-expanded
3540 * Treatment of a `#pragma' directive that after macro-expansion
3543 No macro expansion occurs on any `#pragma' directive line, so the
3583 * Significant initial characters in an identifier or macro name.
3594 * Number of parameters in a macro definition and arguments in a
3595 macro call.
3656 ignored. (This is similar to the rules governing macro redefinition.)
3786 entirely when you use a variable argument macro. This is
3792 Formerly, in a macro expansion, if `##' appeared before a variable
3794 argument in the macro invocation was empty, previous versions of
3865 Predefine NAME as a macro, with definition `1'.
3877 If you wish to define a function-like macro on the command line,
3946 Warn whenever an identifier which is not a macro is encountered in
3952 macro is "used" if it is expanded or tested for existence at least
3953 once. The preprocessor will also warn if the macro has not been
3959 _Note:_ If a macro is actually used, but only used in skipped
3962 macro's definition by, for example, moving it into the first
4254 If the `-E' option is enabled, it suppresses things like macro
4257 except that macro definitions are output similar to the `-dD'
4275 preprocessed. This suppresses things like macro expansion,
4370 Like `D', but emit only the macro names, not their expansions.
4396 Do not discard comments, including during macro expansion. This is
4398 passed through to the output file where the macro is expanded.
4401 option causes all C++-style comments inside a macro to be
4403 that macro from inadvertently commenting out the remainder of the
5081 * arguments: Macro Arguments. (line 6)
5082 * arguments in macro definitions: Macro Arguments. (line 6)
5102 * controlling macro: Once-Only Headers. (line 35)
5117 * empty macro arguments: Macro Arguments. (line 66)
5126 * guard macro: Once-Only Headers. (line 35)
5141 * macro argument expansion: Argument Prescan. (line 6)
5142 * macro arguments and directives: Directives Within Macro Arguments.
5145 * macros with arguments: Macro Arguments. (line 6)
5150 * newlines in macro arguments: Newlines in Arguments.
5154 * object-like macro: Object-like Macros. (line 6)
5160 * parentheses in macro bodies: Operator Precedence Problems.
5162 * pitfalls of macros: Macro Pitfalls. (line 6)
5171 * prescan of macro arguments: Argument Prescan. (line 6)
5172 * problems with macros: Macro Pitfalls. (line 6)
5183 * semicolons (after macro calls): Swallowing the Semicolon.
5185 * side effects (in macro arguments): Duplication of Side Effects.
5234 Node: Macro Arguments49035
5244 Node: Directives Within Macro Arguments87175
5245 Node: Macro Pitfalls88723
