+++ /dev/null
-This is doc/cpp.info, produced by makeinfo version 4.5 from
-doc/cpp.texi.
-
-INFO-DIR-SECTION Programming
-START-INFO-DIR-ENTRY
-* Cpp: (cpp). The GNU C preprocessor.
-END-INFO-DIR-ENTRY
-
-\1f
-File: cpp.info, Node: Stringification, Next: Concatenation, Prev: Macro Arguments, Up: Macros
-
-Stringification
-===============
-
- Sometimes you may want to convert a macro argument into a string
-constant. Parameters are not replaced inside string constants, but you
-can use the `#' preprocessing operator instead. When a macro parameter
-is used with a leading `#', the preprocessor replaces it with the
-literal text of the actual argument, converted to a string constant.
-Unlike normal parameter replacement, the argument is not macro-expanded
-first. This is called "stringification".
-
- There is no way to combine an argument with surrounding text and
-stringify it all together. Instead, you can write a series of adjacent
-string constants and stringified arguments. The preprocessor will
-replace the stringified arguments with string constants. The C
-compiler will then combine all the adjacent string constants into one
-long string.
-
- Here is an example of a macro definition that uses stringification:
-
- #define WARN_IF(EXP) \
- do { if (EXP) \
- fprintf (stderr, "Warning: " #EXP "\n"); } \
- while (0)
- WARN_IF (x == 0);
- ==> do { if (x == 0)
- fprintf (stderr, "Warning: " "x == 0" "\n"); } while (0);
-
-The argument for `EXP' is substituted once, as-is, into the `if'
-statement, and once, stringified, into the argument to `fprintf'. If
-`x' were a macro, it would be expanded in the `if' statement, but not
-in the string.
-
- The `do' and `while (0)' are a kludge to make it possible to write
-`WARN_IF (ARG);', which the resemblance of `WARN_IF' to a function
-would make C programmers want to do; see *Note Swallowing the
-Semicolon::.
-
- Stringification in C involves more than putting double-quote
-characters around the fragment. The preprocessor backslash-escapes the
-quotes surrounding embedded string constants, and all backslashes
-within string and character constants, in order to get a valid C string
-constant with the proper contents. Thus, stringifying `p = "foo\n";'
-results in "p = \"foo\\n\";". However, backslashes that are not inside
-string or character constants are not duplicated: `\n' by itself
-stringifies to "\n".
-
- All leading and trailing whitespace in text being stringified is
-ignored. Any sequence of whitespace in the middle of the text is
-converted to a single space in the stringified result. Comments are
-replaced by whitespace long before stringification happens, so they
-never appear in stringified text.
-
- There is no way to convert a macro argument into a character
-constant.
-
- If you want to stringify the result of expansion of a macro argument,
-you have to use two levels of macros.
-
- #define xstr(s) str(s)
- #define str(s) #s
- #define foo 4
- str (foo)
- ==> "foo"
- xstr (foo)
- ==> xstr (4)
- ==> str (4)
- ==> "4"
-
- `s' is stringified when it is used in `str', so it is not
-macro-expanded first. But `s' is an ordinary argument to `xstr', so it
-is completely macro-expanded before `xstr' itself is expanded (*note
-Argument Prescan::). Therefore, by the time `str' gets to its
-argument, it has already been macro-expanded.
-
-\1f
-File: cpp.info, Node: Concatenation, Next: Variadic Macros, Prev: Stringification, Up: Macros
-
-Concatenation
-=============
-
- It is often useful to merge two tokens into one while expanding
-macros. This is called "token pasting" or "token concatenation". The
-`##' preprocessing operator performs token pasting. When a macro is
-expanded, the two tokens on either side of each `##' operator are
-combined into a single token, which then replaces the `##' and the two
-original tokens in the macro expansion. Usually both will be
-identifiers, or one will be an identifier and the other a preprocessing
-number. When pasted, they make a longer identifier. This isn't the
-only valid case. It is also possible to concatenate two numbers (or a
-number and a name, such as `1.5' and `e3') into a number. Also,
-multi-character operators such as `+=' can be formed by token pasting.
-
- However, two tokens that don't together form a valid token cannot be
-pasted together. For example, you cannot concatenate `x' with `+' in
-either order. If you try, the preprocessor issues a warning and emits
-the two tokens. Whether it puts white space between the tokens is
-undefined. It is common to find unnecessary uses of `##' in complex
-macros. If you get this warning, it is likely that you can simply
-remove the `##'.
-
- Both the tokens combined by `##' could come from the macro body, but
-you could just as well write them as one token in the first place.
-Token pasting is most useful when one or both of the tokens comes from a
-macro argument. If either of the tokens next to an `##' is a parameter
-name, it is replaced by its actual argument before `##' executes. As
-with stringification, the actual argument is not macro-expanded first.
-If the argument is empty, that `##' has no effect.
-
- Keep in mind that the C preprocessor converts comments to whitespace
-before macros are even considered. Therefore, you cannot create a
-comment by concatenating `/' and `*'. You can put as much whitespace
-between `##' and its operands as you like, including comments, and you
-can put comments in arguments that will be concatenated. However, it
-is an error if `##' appears at either end of a macro body.
-
- Consider a C program that interprets named commands. There probably
-needs to be a table of commands, perhaps an array of structures declared
-as follows:
-
- struct command
- {
- char *name;
- void (*function) (void);
- };
-
- struct command commands[] =
- {
- { "quit", quit_command },
- { "help", help_command },
- ...
- };
-
- It would be cleaner not to have to give each command name twice,
-once in the string constant and once in the function name. A macro
-which takes the name of a command as an argument can make this
-unnecessary. The string constant can be created with stringification,
-and the function name by concatenating the argument with `_command'.
-Here is how it is done:
-
- #define COMMAND(NAME) { #NAME, NAME ## _command }
-
- struct command commands[] =
- {
- COMMAND (quit),
- COMMAND (help),
- ...
- };
-
-\1f
-File: cpp.info, Node: Variadic Macros, Next: Predefined Macros, Prev: Concatenation, Up: Macros
-
-Variadic Macros
-===============
-
- A macro can be declared to accept a variable number of arguments
-much as a function can. The syntax for defining the macro is similar
-to that of a function. Here is an example:
-
- #define eprintf(...) fprintf (stderr, __VA_ARGS__)
-
- This kind of macro is called "variadic". When the macro is invoked,
-all the tokens in its argument list after the last named argument (this
-macro has none), including any commas, become the "variable argument".
-This sequence of tokens replaces the identifier `__VA_ARGS__' in the
-macro body wherever it appears. Thus, we have this expansion:
-
- eprintf ("%s:%d: ", input_file, lineno)
- ==> fprintf (stderr, "%s:%d: ", input_file, lineno)
-
- The variable argument is completely macro-expanded before it is
-inserted into the macro expansion, just like an ordinary argument. You
-may use the `#' and `##' operators to stringify the variable argument
-or to paste its leading or trailing token with another token. (But see
-below for an important special case for `##'.)
-
- If your macro is complicated, you may want a more descriptive name
-for the variable argument than `__VA_ARGS__'. GNU CPP permits this, as
-an extension. You may write an argument name immediately before the
-`...'; that name is used for the variable argument. The `eprintf'
-macro above could be written
-
- #define eprintf(args...) fprintf (stderr, args)
-
-using this extension. You cannot use `__VA_ARGS__' and this extension
-in the same macro.
-
- You can have named arguments as well as variable arguments in a
-variadic macro. We could define `eprintf' like this, instead:
-
- #define eprintf(format, ...) fprintf (stderr, format, __VA_ARGS__)
-
-This formulation looks more descriptive, but unfortunately it is less
-flexible: you must now supply at least one argument after the format
-string. In standard C, you cannot omit the comma separating the named
-argument from the variable arguments. Furthermore, if you leave the
-variable argument empty, you will get a syntax error, because there
-will be an extra comma after the format string.
-
- eprintf("success!\n", );
- ==> fprintf(stderr, "success!\n", );
-
- GNU CPP has a pair of extensions which deal with this problem.
-First, you are allowed to leave the variable argument out entirely:
-
- eprintf ("success!\n")
- ==> fprintf(stderr, "success!\n", );
-
-Second, the `##' token paste operator has a special meaning when placed
-between a comma and a variable argument. If you write
-
- #define eprintf(format, ...) fprintf (stderr, format, ##__VA_ARGS__)
-
-and the variable argument is left out when the `eprintf' macro is used,
-then the comma before the `##' will be deleted. This does _not_ happen
-if you pass an empty argument, nor does it happen if the token
-preceding `##' is anything other than a comma.
-
- eprintf ("success!\n")
- ==> fprintf(stderr, "success!\n");
-
-The above explanation is ambiguous about the case where the only macro
-parameter is a variable arguments parameter, as it is meaningless to
-try to distinguish whether no argument at all is an empty argument or a
-missing argument. In this case the C99 standard is clear that the
-comma must remain, however the existing GCC extension used to swallow
-the comma. So CPP retains the comma when conforming to a specific C
-standard, and drops it otherwise.
-
- C99 mandates that the only place the identifier `__VA_ARGS__' can
-appear is in the replacement list of a variadic macro. It may not be
-used as a macro name, macro argument name, or within a different type
-of macro. It may also be forbidden in open text; the standard is
-ambiguous. We recommend you avoid using it except for its defined
-purpose.
-
- Variadic macros are a new feature in C99. GNU CPP has supported them
-for a long time, but only with a named variable argument (`args...',
-not `...' and `__VA_ARGS__'). If you are concerned with portability to
-previous versions of GCC, you should use only named variable arguments.
-On the other hand, if you are concerned with portability to other
-conforming implementations of C99, you should use only `__VA_ARGS__'.
-
- Previous versions of GNU CPP implemented the comma-deletion extension
-much more generally. We have restricted it in this release to minimize
-the differences from C99. To get the same effect with both this and
-previous versions of GCC, the token preceding the special `##' must be
-a comma, and there must be white space between that comma and whatever
-comes immediately before it:
-
- #define eprintf(format, args...) fprintf (stderr, format , ##args)
-
-*Note Differences from previous versions::, for the gory details.
-
-\1f
-File: cpp.info, Node: Predefined Macros, Next: Undefining and Redefining Macros, Prev: Variadic Macros, Up: Macros
-
-Predefined Macros
-=================
-
- Several object-like macros are predefined; you use them without
-supplying their definitions. They fall into three classes: standard,
-common, and system-specific.
-
- In C++, there is a fourth category, the named operators. They act
-like predefined macros, but you cannot undefine them.
-
-* Menu:
-
-* Standard Predefined Macros::
-* Common Predefined Macros::
-* System-specific Predefined Macros::
-* C++ Named Operators::
-
-\1f
-File: cpp.info, Node: Standard Predefined Macros, Next: Common Predefined Macros, Up: Predefined Macros
-
-Standard Predefined Macros
---------------------------
-
- The standard predefined macros are specified by the C and/or C++
-language standards, so they are available with all compilers that
-implement those standards. Older compilers may not provide all of
-them. Their names all start with double underscores.
-
-`__FILE__'
- This macro expands to the name of the current input file, in the
- form of a C string constant. This is the path by which the
- preprocessor opened the file, not the short name specified in
- `#include' or as the input file name argument. For example,
- `"/usr/local/include/myheader.h"' is a possible expansion of this
- macro.
-
-`__LINE__'
- This macro expands to the current input line number, in the form
- of a decimal integer constant. While we call it a predefined
- macro, it's a pretty strange macro, since its "definition" changes
- with each new line of source code.
-
- `__FILE__' and `__LINE__' are useful in generating an error message
-to report an inconsistency detected by the program; the message can
-state the source line at which the inconsistency was detected. For
-example,
-
- fprintf (stderr, "Internal error: "
- "negative string length "
- "%d at %s, line %d.",
- length, __FILE__, __LINE__);
-
- An `#include' directive changes the expansions of `__FILE__' and
-`__LINE__' to correspond to the included file. At the end of that
-file, when processing resumes on the input file that contained the
-`#include' directive, the expansions of `__FILE__' and `__LINE__'
-revert to the values they had before the `#include' (but `__LINE__' is
-then incremented by one as processing moves to the line after the
-`#include').
-
- A `#line' directive changes `__LINE__', and may change `__FILE__' as
-well. *Note Line Control::.
-
- C99 introduces `__func__', and GCC has provided `__FUNCTION__' for a
-long time. Both of these are strings containing the name of the
-current function (there are slight semantic differences; see the GCC
-manual). Neither of them is a macro; the preprocessor does not know the
-name of the current function. They tend to be useful in conjunction
-with `__FILE__' and `__LINE__', though.
-
-`__DATE__'
- This macro expands to a string constant that describes the date on
- which the preprocessor is being run. The string constant contains
- eleven characters and looks like `"Feb 12 1996"'. If the day of
- the month is less than 10, it is padded with a space on the left.
-
-`__TIME__'
- This macro expands to a string constant that describes the time at
- which the preprocessor is being run. The string constant contains
- eight characters and looks like `"23:59:01"'.
-
-`__STDC__'
- In normal operation, this macro expands to the constant 1, to
- signify that this compiler conforms to ISO Standard C. If GNU CPP
- is used with a compiler other than GCC, this is not necessarily
- true; however, the preprocessor always conforms to the standard,
- unless the `-traditional' option is used.
-
- This macro is not defined if the `-traditional' option is used.
-
- On some hosts, the system compiler uses a different convention,
- where `__STDC__' is normally 0, but is 1 if the user specifies
- strict conformance to the C Standard. GNU CPP follows the host
- convention when processing system header files, but when
- processing user files `__STDC__' is always 1. This has been
- reported to cause problems; for instance, some versions of Solaris
- provide X Windows headers that expect `__STDC__' to be either
- undefined or 1. *Note Invocation::.
-
-`__STDC_VERSION__'
- This macro expands to the C Standard's version number, a long
- integer constant of the form `YYYYMML' where YYYY and MM are the
- year and month of the Standard version. This signifies which
- version of the C Standard the compiler conforms to. Like
- `__STDC__', this is not necessarily accurate for the entire
- implementation, unless GNU CPP is being used with GCC.
-
- The value `199409L' signifies the 1989 C standard as amended in
- 1994, which is the current default; the value `199901L' signifies
- the 1999 revision of the C standard. Support for the 1999
- revision is not yet complete.
-
- This macro is not defined if the `-traditional' option is used, nor
- when compiling C++ or Objective-C.
-
-`__STDC_HOSTED__'
- This macro is defined, with value 1, if the compiler's target is a
- "hosted environment". A hosted environment has the complete
- facilities of the standard C library available.
-
-`__cplusplus'
- This macro is defined when the C++ compiler is in use. You can use
- `__cplusplus' to test whether a header is compiled by a C compiler
- or a C++ compiler. This macro is similar to `__STDC_VERSION__', in
- that it expands to a version number. A fully conforming
- implementation of the 1998 C++ standard will define this macro to
- `199711L'. The GNU C++ compiler is not yet fully conforming, so
- it uses `1' instead. We hope to complete our implementation in
- the near future.
-
-
-\1f
-File: cpp.info, Node: Common Predefined Macros, Next: System-specific Predefined Macros, Prev: Standard Predefined Macros, Up: Predefined Macros
-
-Common Predefined Macros
-------------------------
-
- The common predefined macros are GNU C extensions. They are
-available with the same meanings regardless of the machine or operating
-system on which you are using GNU C. Their names all start with double
-underscores.
-
-`__GNUC__'
-`__GNUC_MINOR__'
-`__GNUC_PATCHLEVEL__'
- These macros are defined by all GNU compilers that use the C
- preprocessor: C, C++, and Objective-C. Their values are the major
- version, minor version, and patch level of the compiler, as integer
- constants. For example, GCC 3.2.1 will define `__GNUC__' to 3,
- `__GNUC_MINOR__' to 2, and `__GNUC_PATCHLEVEL__' to 1. They are
- defined only when the entire compiler is in use; if you invoke the
- preprocessor directly, they are not defined.
-
- `__GNUC_PATCHLEVEL__' is new to GCC 3.0; it is also present in the
- widely-used development snapshots leading up to 3.0 (which identify
- themselves as GCC 2.96 or 2.97, depending on which snapshot you
- have).
-
- If all you need to know is whether or not your program is being
- compiled by GCC, you can simply test `__GNUC__'. If you need to
- write code which depends on a specific version, you must be more
- careful. Each time the minor version is increased, the patch
- level is reset to zero; each time the major version is increased
- (which happens rarely), the minor version and patch level are
- reset. If you wish to use the predefined macros directly in the
- conditional, you will need to write it like this:
-
- /* Test for GCC > 3.2.0 */
- #if __GNUC__ > 3 || \
- (__GNUC__ == 3 && (__GNUC_MINOR__ > 2 || \
- (__GNUC_MINOR__ == 2 && \
- __GNUC_PATCHLEVEL__ > 0))
-
- Another approach is to use the predefined macros to calculate a
- single number, then compare that against a threshold:
-
- #define GCC_VERSION (__GNUC__ * 10000 \
- + __GNUC_MINOR__ * 100 \
- + __GNUC_PATCHLEVEL__)
- ...
- /* Test for GCC > 3.2.0 */
- #if GCC_VERSION > 30200
-
- Many people find this form easier to understand.
-
-`__OBJC__'
- This macro is defined, with value 1, when the Objective-C compiler
- is in use. You can use `__OBJC__' to test whether a header is
- compiled by a C compiler or a Objective-C compiler.
-
-`__GNUG__'
- The GNU C++ compiler defines this. Testing it is equivalent to
- testing `(__GNUC__ && __cplusplus)'.
-
-`__STRICT_ANSI__'
- GCC defines this macro if and only if the `-ansi' switch, or a
- `-std' switch specifying strict conformance to some version of ISO
- C, was specified when GCC was invoked. It is defined to `1'.
- This macro exists primarily to direct GNU libc's header files to
- restrict their definitions to the minimal set found in the 1989 C
- standard.
-
-`__BASE_FILE__'
- This macro expands to the name of the main input file, in the form
- of a C string constant. This is the source file that was specified
- on the command line of the preprocessor or C compiler.
-
-`__INCLUDE_LEVEL__'
- This macro expands to a decimal integer constant that represents
- the depth of nesting in include files. The value of this macro is
- incremented on every `#include' directive and decremented at the
- end of every included file. It starts out at 0, it's value within
- the base file specified on the command line.
-
-`__VERSION__'
- This macro expands to a string constant which describes the
- version of the compiler in use. You should not rely on its
- contents having any particular form, but it can be counted on to
- contain at least the release number.
-
-`__OPTIMIZE__'
-`__OPTIMIZE_SIZE__'
-`__NO_INLINE__'
- These macros describe the compilation mode. `__OPTIMIZE__' is
- defined in all optimizing compilations. `__OPTIMIZE_SIZE__' is
- defined if the compiler is optimizing for size, not speed.
- `__NO_INLINE__' is defined if no functions will be inlined into
- their callers (when not optimizing, or when inlining has been
- specifically disabled by `-fno-inline').
-
- These macros cause certain GNU header files to provide optimized
- definitions, using macros or inline functions, of system library
- functions. You should not use these macros in any way unless you
- make sure that programs will execute with the same effect whether
- or not they are defined. If they are defined, their value is 1.
-
-`__CHAR_UNSIGNED__'
- GCC defines this macro if and only if the data type `char' is
- unsigned on the target machine. It exists to cause the standard
- header file `limits.h' to work correctly. You should not use this
- macro yourself; instead, refer to the standard macros defined in
- `limits.h'.
-
-`__REGISTER_PREFIX__'
- This macro expands to a single token (not a string constant) which
- is the prefix applied to CPU register names in assembly language
- for this target. You can use it to write assembly that is usable
- in multiple environments. For example, in the `m68k-aout'
- environment it expands to nothing, but in the `m68k-coff'
- environment it expands to a single `%'.
-
-`__USER_LABEL_PREFIX__'
- This macro expands to a single token which is the prefix applied to
- user labels (symbols visible to C code) in assembly. For example,
- in the `m68k-aout' environment it expands to an `_', but in the
- `m68k-coff' environment it expands to nothing.
-
- This macro will have the correct definition even if
- `-f(no-)underscores' is in use, but it will not be correct if
- target-specific options that adjust this prefix are used (e.g. the
- OSF/rose `-mno-underscores' option).
-
-`__SIZE_TYPE__'
-`__PTRDIFF_TYPE__'
-`__WCHAR_TYPE__'
-`__WINT_TYPE__'
- These macros are defined to the correct underlying types for the
- `size_t', `ptrdiff_t', `wchar_t', and `wint_t' typedefs,
- respectively. They exist to make the standard header files
- `stddef.h' and `wchar.h' work correctly. You should not use these
- macros directly; instead, include the appropriate headers and use
- the typedefs.
-
-`__USING_SJLJ_EXCEPTIONS__'
- This macro is defined, with value 1, if the compiler uses the old
- mechanism based on `setjmp' and `longjmp' for exception handling.
-
-\1f
-File: cpp.info, Node: System-specific Predefined Macros, Next: C++ Named Operators, Prev: Common Predefined Macros, Up: Predefined Macros
-
-System-specific Predefined Macros
----------------------------------
-
- The C preprocessor normally predefines several macros that indicate
-what type of system and machine is in use. They are obviously
-different on each target supported by GCC. This manual, being for all
-systems and machines, cannot tell you what their names are, but you can
-use `cpp -dM' to see them all. *Note Invocation::. All system-specific
-predefined macros expand to the constant 1, so you can test them with
-either `#ifdef' or `#if'.
-
- The C standard requires that all system-specific macros be part of
-the "reserved namespace". All names which begin with two underscores,
-or an underscore and a capital letter, are reserved for the compiler and
-library to use as they wish. However, historically system-specific
-macros have had names with no special prefix; for instance, it is common
-to find `unix' defined on Unix systems. For all such macros, GCC
-provides a parallel macro with two underscores added at the beginning
-and the end. If `unix' is defined, `__unix__' will be defined too.
-There will never be more than two underscores; the parallel of `_mips'
-is `__mips__'.
-
- When the `-ansi' option, or any `-std' option that requests strict
-conformance, is given to the compiler, all the system-specific
-predefined macros outside the reserved namespace are suppressed. The
-parallel macros, inside the reserved namespace, remain defined.
-
- We are slowly phasing out all predefined macros which are outside the
-reserved namespace. You should never use them in new programs, and we
-encourage you to correct older code to use the parallel macros whenever
-you find it. We don't recommend you use the system-specific macros that
-are in the reserved namespace, either. It is better in the long run to
-check specifically for features you need, using a tool such as
-`autoconf'.
-
-\1f
-File: cpp.info, Node: C++ Named Operators, Prev: System-specific Predefined Macros, Up: Predefined Macros
-
-C++ Named Operators
--------------------
-
- In C++, there are eleven keywords which are simply alternate
-spellings of operators normally written with punctuation. These
-keywords are treated as such even in the preprocessor. They function
-as operators in `#if', and they cannot be defined as macros or
-poisoned. In C, you can request that those keywords take their C++
-meaning by including `iso646.h'. That header defines each one as a
-normal object-like macro expanding to the appropriate punctuator.
-
- These are the named operators and their corresponding punctuators:
-
-Named Operator Punctuator
-`and' `&&'
-`and_eq' `&='
-`bitand' `&'
-`bitor' `|'
-`compl' `~'
-`not' `!'
-`not_eq' `!='
-`or' `||'
-`or_eq' `|='
-`xor' `^'
-`xor_eq' `^='
-
-\1f
-File: cpp.info, Node: Undefining and Redefining Macros, Next: Macro Pitfalls, Prev: Predefined Macros, Up: Macros
-
-Undefining and Redefining Macros
-================================
-
- If a macro ceases to be useful, it may be "undefined" with the
-`#undef' directive. `#undef' takes a single argument, the name of the
-macro to undefine. You use the bare macro name, even if the macro is
-function-like. It is an error if anything appears on the line after
-the macro name. `#undef' has no effect if the name is not a macro.
-
- #define FOO 4
- x = FOO; ==> x = 4;
- #undef FOO
- x = FOO; ==> x = FOO;
-
- Once a macro has been undefined, that identifier may be "redefined"
-as a macro by a subsequent `#define' directive. The new definition
-need not have any resemblance to the old definition.
-
- However, if an identifier which is currently a macro is redefined,
-then the new definition must be "effectively the same" as the old one.
-Two macro definitions are effectively the same if:
- * Both are the same type of macro (object- or function-like).
-
- * All the tokens of the replacement list are the same.
-
- * If there are any parameters, they are the same.
-
- * Whitespace appears in the same places in both. It need not be
- exactly the same amount of whitespace, though. Remember that
- comments count as whitespace.
-
-These definitions are effectively the same:
- #define FOUR (2 + 2)
- #define FOUR (2 + 2)
- #define FOUR (2 /* two */ + 2)
-
-but these are not:
- #define FOUR (2 + 2)
- #define FOUR ( 2+2 )
- #define FOUR (2 * 2)
- #define FOUR(score,and,seven,years,ago) (2 + 2)
-
- If a macro is redefined with a definition that is not effectively the
-same as the old one, the preprocessor issues a warning and changes the
-macro to use the new definition. If the new definition is effectively
-the same, the redefinition is silently ignored. This allows, for
-instance, two different headers to define a common macro. The
-preprocessor will only complain if the definitions do not match.
-
-\1f
-File: cpp.info, Node: Macro Pitfalls, Prev: Undefining and Redefining Macros, Up: Macros
-
-Macro Pitfalls
-==============
-
- In this section we describe some special rules that apply to macros
-and macro expansion, and point out certain cases in which the rules have
-counter-intuitive consequences that you must watch out for.
-
-* Menu:
-
-* Misnesting::
-* Operator Precedence Problems::
-* Swallowing the Semicolon::
-* Duplication of Side Effects::
-* Self-Referential Macros::
-* Argument Prescan::
-* Newlines in Arguments::
-
-\1f
-File: cpp.info, Node: Misnesting, Next: Operator Precedence Problems, Up: Macro Pitfalls
-
-Misnesting
-----------
-
- When a macro is called with arguments, the arguments are substituted
-into the macro body and the result is checked, together with the rest of
-the input file, for more macro calls. It is possible to piece together
-a macro call coming partially from the macro body and partially from the
-arguments. For example,
-
- #define twice(x) (2*(x))
- #define call_with_1(x) x(1)
- call_with_1 (twice)
- ==> twice(1)
- ==> (2*(1))
-
- Macro definitions do not have to have balanced parentheses. By
-writing an unbalanced open parenthesis in a macro body, it is possible
-to create a macro call that begins inside the macro body but ends
-outside of it. For example,
-
- #define strange(file) fprintf (file, "%s %d",
- ...
- strange(stderr) p, 35)
- ==> fprintf (stderr, "%s %d", p, 35)
-
- The ability to piece together a macro call can be useful, but the
-use of unbalanced open parentheses in a macro body is just confusing,
-and should be avoided.
-
-\1f
-File: cpp.info, Node: Operator Precedence Problems, Next: Swallowing the Semicolon, Prev: Misnesting, Up: Macro Pitfalls
-
-Operator Precedence Problems
-----------------------------
-
- You may have noticed that in most of the macro definition examples
-shown above, each occurrence of a macro argument name had parentheses
-around it. In addition, another pair of parentheses usually surround
-the entire macro definition. Here is why it is best to write macros
-that way.
-
- Suppose you define a macro as follows,
-
- #define ceil_div(x, y) (x + y - 1) / y
-
-whose purpose is to divide, rounding up. (One use for this operation is
-to compute how many `int' objects are needed to hold a certain number
-of `char' objects.) Then suppose it is used as follows:
-
- a = ceil_div (b & c, sizeof (int));
- ==> a = (b & c + sizeof (int) - 1) / sizeof (int);
-
-This does not do what is intended. The operator-precedence rules of C
-make it equivalent to this:
-
- a = (b & (c + sizeof (int) - 1)) / sizeof (int);
-
-What we want is this:
-
- a = ((b & c) + sizeof (int) - 1)) / sizeof (int);
-
-Defining the macro as
-
- #define ceil_div(x, y) ((x) + (y) - 1) / (y)
-
-provides the desired result.
-
- Unintended grouping can result in another way. Consider `sizeof
-ceil_div(1, 2)'. That has the appearance of a C expression that would
-compute the size of the type of `ceil_div (1, 2)', but in fact it means
-something very different. Here is what it expands to:
-
- sizeof ((1) + (2) - 1) / (2)
-
-This would take the size of an integer and divide it by two. The
-precedence rules have put the division outside the `sizeof' when it was
-intended to be inside.
-
- Parentheses around the entire macro definition prevent such problems.
-Here, then, is the recommended way to define `ceil_div':
-
- #define ceil_div(x, y) (((x) + (y) - 1) / (y))
-
-\1f
-File: cpp.info, Node: Swallowing the Semicolon, Next: Duplication of Side Effects, Prev: Operator Precedence Problems, Up: Macro Pitfalls
-
-Swallowing the Semicolon
-------------------------
-
- Often it is desirable to define a macro that expands into a compound
-statement. Consider, for example, the following macro, that advances a
-pointer (the argument `p' says where to find it) across whitespace
-characters:
-
- #define SKIP_SPACES(p, limit) \
- { char *lim = (limit); \
- while (p < lim) { \
- if (*p++ != ' ') { \
- p--; break; }}}
-
-Here backslash-newline is used to split the macro definition, which must
-be a single logical line, so that it resembles the way such code would
-be laid out if not part of a macro definition.
-
- A call to this macro might be `SKIP_SPACES (p, lim)'. Strictly
-speaking, the call expands to a compound statement, which is a complete
-statement with no need for a semicolon to end it. However, since it
-looks like a function call, it minimizes confusion if you can use it
-like a function call, writing a semicolon afterward, as in `SKIP_SPACES
-(p, lim);'
-
- This can cause trouble before `else' statements, because the
-semicolon is actually a null statement. Suppose you write
-
- if (*p != 0)
- SKIP_SPACES (p, lim);
- else ...
-
-The presence of two statements--the compound statement and a null
-statement--in between the `if' condition and the `else' makes invalid C
-code.
-
- The definition of the macro `SKIP_SPACES' can be altered to solve
-this problem, using a `do ... while' statement. Here is how:
-
- #define SKIP_SPACES(p, limit) \
- do { char *lim = (limit); \
- while (p < lim) { \
- if (*p++ != ' ') { \
- p--; break; }}} \
- while (0)
-
- Now `SKIP_SPACES (p, lim);' expands into
-
- do {...} while (0);
-
-which is one statement. The loop executes exactly once; most compilers
-generate no extra code for it.
-
-\1f
-File: cpp.info, Node: Duplication of Side Effects, Next: Self-Referential Macros, Prev: Swallowing the Semicolon, Up: Macro Pitfalls
-
-Duplication of Side Effects
----------------------------
-
- Many C programs define a macro `min', for "minimum", like this:
-
- #define min(X, Y) ((X) < (Y) ? (X) : (Y))
-
- When you use this macro with an argument containing a side effect,
-as shown here,
-
- next = min (x + y, foo (z));
-
-it expands as follows:
-
- next = ((x + y) < (foo (z)) ? (x + y) : (foo (z)));
-
-where `x + y' has been substituted for `X' and `foo (z)' for `Y'.
-
- The function `foo' is used only once in the statement as it appears
-in the program, but the expression `foo (z)' has been substituted twice
-into the macro expansion. As a result, `foo' might be called two times
-when the statement is executed. If it has side effects or if it takes
-a long time to compute, the results might not be what you intended. We
-say that `min' is an "unsafe" macro.
-
- The best solution to this problem is to define `min' in a way that
-computes the value of `foo (z)' only once. The C language offers no
-standard way to do this, but it can be done with GNU extensions as
-follows:
-
- #define min(X, Y) \
- ({ typeof (X) x_ = (X); \
- typeof (Y) y_ = (Y); \
- (x_ < y_) ? x_ : y_; })
-
- The `({ ... })' notation produces a compound statement that acts as
-an expression. Its value is the value of its last statement. This
-permits us to define local variables and assign each argument to one.
-The local variables have underscores after their names to reduce the
-risk of conflict with an identifier of wider scope (it is impossible to
-avoid this entirely). Now each argument is evaluated exactly once.
-
- If you do not wish to use GNU C extensions, the only solution is to
-be careful when _using_ the macro `min'. For example, you can
-calculate the value of `foo (z)', save it in a variable, and use that
-variable in `min':
-
- #define min(X, Y) ((X) < (Y) ? (X) : (Y))
- ...
- {
- int tem = foo (z);
- next = min (x + y, tem);
- }
-
-(where we assume that `foo' returns type `int').
-
-\1f
-File: cpp.info, Node: Self-Referential Macros, Next: Argument Prescan, Prev: Duplication of Side Effects, Up: Macro Pitfalls
-
-Self-Referential Macros
------------------------
-
- A "self-referential" macro is one whose name appears in its
-definition. Recall that all macro definitions are rescanned for more
-macros to replace. If the self-reference were considered a use of the
-macro, it would produce an infinitely large expansion. To prevent this,
-the self-reference is not considered a macro call. It is passed into
-the preprocessor output unchanged. Let's consider an example:
-
- #define foo (4 + foo)
-
-where `foo' is also a variable in your program.
-
- Following the ordinary rules, each reference to `foo' will expand
-into `(4 + foo)'; then this will be rescanned and will expand into `(4
-+ (4 + foo))'; and so on until the computer runs out of memory.
-
- The self-reference rule cuts this process short after one step, at
-`(4 + foo)'. Therefore, this macro definition has the possibly useful
-effect of causing the program to add 4 to the value of `foo' wherever
-`foo' is referred to.
-
- In most cases, it is a bad idea to take advantage of this feature. A
-person reading the program who sees that `foo' is a variable will not
-expect that it is a macro as well. The reader will come across the
-identifier `foo' in the program and think its value should be that of
-the variable `foo', whereas in fact the value is four greater.
-
- One common, useful use of self-reference is to create a macro which
-expands to itself. If you write
-
- #define EPERM EPERM
-
-then the macro `EPERM' expands to `EPERM'. Effectively, it is left
-alone by the preprocessor whenever it's used in running text. You can
-tell that it's a macro with `#ifdef'. You might do this if you want to
-define numeric constants with an `enum', but have `#ifdef' be true for
-each constant.
-
- If a macro `x' expands to use a macro `y', and the expansion of `y'
-refers to the macro `x', that is an "indirect self-reference" of `x'.
-`x' is not expanded in this case either. Thus, if we have
-
- #define x (4 + y)
- #define y (2 * x)
-
-then `x' and `y' expand as follows:
-
- x ==> (4 + y)
- ==> (4 + (2 * x))
-
- y ==> (2 * x)
- ==> (2 * (4 + y))
-
-Each macro is expanded when it appears in the definition of the other
-macro, but not when it indirectly appears in its own definition.
-
-\1f
-File: cpp.info, Node: Argument Prescan, Next: Newlines in Arguments, Prev: Self-Referential Macros, Up: Macro Pitfalls
-
-Argument Prescan
-----------------
-
- Macro arguments are completely macro-expanded before they are
-substituted into a macro body, unless they are stringified or pasted
-with other tokens. After substitution, the entire macro body, including
-the substituted arguments, is scanned again for macros to be expanded.
-The result is that the arguments are scanned _twice_ to expand macro
-calls in them.
-
- Most of the time, this has no effect. If the argument contained any
-macro calls, they are expanded during the first scan. The result
-therefore contains no macro calls, so the second scan does not change
-it. If the argument were substituted as given, with no prescan, the
-single remaining scan would find the same macro calls and produce the
-same results.
-
- You might expect the double scan to change the results when a
-self-referential macro is used in an argument of another macro (*note
-Self-Referential Macros::): the self-referential macro would be
-expanded once in the first scan, and a second time in the second scan.
-However, this is not what happens. The self-references that do not
-expand in the first scan are marked so that they will not expand in the
-second scan either.
-
- You might wonder, "Why mention the prescan, if it makes no
-difference? And why not skip it and make the preprocessor faster?"
-The answer is that the prescan does make a difference in three special
-cases:
-
- * Nested calls to a macro.
-
- We say that "nested" calls to a macro occur when a macro's argument
- contains a call to that very macro. For example, if `f' is a macro
- that expects one argument, `f (f (1))' is a nested pair of calls to
- `f'. The desired expansion is made by expanding `f (1)' and
- substituting that into the definition of `f'. The prescan causes
- the expected result to happen. Without the prescan, `f (1)' itself
- would be substituted as an argument, and the inner use of `f' would
- appear during the main scan as an indirect self-reference and
- would not be expanded.
-
- * Macros that call other macros that stringify or concatenate.
-
- If an argument is stringified or concatenated, the prescan does not
- occur. If you _want_ to expand a macro, then stringify or
- concatenate its expansion, you can do that by causing one macro to
- call another macro that does the stringification or concatenation.
- For instance, if you have
-
- #define AFTERX(x) X_ ## x
- #define XAFTERX(x) AFTERX(x)
- #define TABLESIZE 1024
- #define BUFSIZE TABLESIZE
-
- then `AFTERX(BUFSIZE)' expands to `X_BUFSIZE', and
- `XAFTERX(BUFSIZE)' expands to `X_1024'. (Not to `X_TABLESIZE'.
- Prescan always does a complete expansion.)
-
- * Macros used in arguments, whose expansions contain unshielded
- commas.
-
- This can cause a macro expanded on the second scan to be called
- with the wrong number of arguments. Here is an example:
-
- #define foo a,b
- #define bar(x) lose(x)
- #define lose(x) (1 + (x))
-
- We would like `bar(foo)' to turn into `(1 + (foo))', which would
- then turn into `(1 + (a,b))'. Instead, `bar(foo)' expands into
- `lose(a,b)', and you get an error because `lose' requires a single
- argument. In this case, the problem is easily solved by the same
- parentheses that ought to be used to prevent misnesting of
- arithmetic operations:
-
- #define foo (a,b)
- or
- #define bar(x) lose((x))
-
- The extra pair of parentheses prevents the comma in `foo''s
- definition from being interpreted as an argument separator.
-
-
-\1f
-File: cpp.info, Node: Newlines in Arguments, Prev: Argument Prescan, Up: Macro Pitfalls
-
-Newlines in Arguments
----------------------
-
- The invocation of a function-like macro can extend over many logical
-lines. However, in the present implementation, the entire expansion
-comes out on one line. Thus line numbers emitted by the compiler or
-debugger refer to the line the invocation started on, which might be
-different to the line containing the argument causing the problem.
-
- Here is an example illustrating this:
-
- #define ignore_second_arg(a,b,c) a; c
-
- ignore_second_arg (foo (),
- ignored (),
- syntax error);
-
-The syntax error triggered by the tokens `syntax error' results in an
-error message citing line three--the line of ignore_second_arg-- even
-though the problematic code comes from line five.
-
- We consider this a bug, and intend to fix it in the near future.
-
-\1f
-File: cpp.info, Node: Conditionals, Next: Diagnostics, Prev: Macros, Up: Top
-
-Conditionals
-************
-
- A "conditional" is a directive that instructs the preprocessor to
-select whether or not to include a chunk of code in the final token
-stream passed to the compiler. Preprocessor conditionals can test
-arithmetic expressions, or whether a name is defined as a macro, or both
-simultaneously using the special `defined' operator.
-
- A conditional in the C preprocessor resembles in some ways an `if'
-statement in C, but it is important to understand the difference between
-them. The condition in an `if' statement is tested during the
-execution of your program. Its purpose is to allow your program to
-behave differently from run to run, depending on the data it is
-operating on. The condition in a preprocessing conditional directive is
-tested when your program is compiled. Its purpose is to allow different
-code to be included in the program depending on the situation at the
-time of compilation.
-
- However, the distinction is becoming less clear. Modern compilers
-often do test `if' statements when a program is compiled, if their
-conditions are known not to vary at run time, and eliminate code which
-can never be executed. If you can count on your compiler to do this,
-you may find that your program is more readable if you use `if'
-statements with constant conditions (perhaps determined by macros). Of
-course, you can only use this to exclude code, not type definitions or
-other preprocessing directives, and you can only do it if the code
-remains syntactically valid when it is not to be used.
-
- GCC version 3 eliminates this kind of never-executed code even when
-not optimizing. Older versions did it only when optimizing.
-
-* Menu:
-
-* Conditional Uses::
-* Conditional Syntax::
-* Deleted Code::
-
-\1f
-File: cpp.info, Node: Conditional Uses, Next: Conditional Syntax, Up: Conditionals
-
-Conditional Uses
-================
-
- There are three general reasons to use a conditional.
-
- * A program may need to use different code depending on the machine
- or operating system it is to run on. In some cases the code for
- one operating system may be erroneous on another operating system;
- for example, it might refer to data types or constants that do not
- exist on the other system. When this happens, it is not enough to
- avoid executing the invalid code. Its mere presence will cause
- the compiler to reject the program. With a preprocessing
- conditional, the offending code can be effectively excised from
- the program when it is not valid.
-
- * You may want to be able to compile the same source file into two
- different programs. One version might make frequent time-consuming
- consistency checks on its intermediate data, or print the values of
- those data for debugging, and the other not.
-
- * A conditional whose condition is always false is one way to
- exclude code from the program but keep it as a sort of comment for
- future reference.
-
- Simple programs that do not need system-specific logic or complex
-debugging hooks generally will not need to use preprocessing
-conditionals.
-
-\1f
-File: cpp.info, Node: Conditional Syntax, Next: Deleted Code, Prev: Conditional Uses, Up: Conditionals
-
-Conditional Syntax
-==================
-
- A conditional in the C preprocessor begins with a "conditional
-directive": `#if', `#ifdef' or `#ifndef'.
-
-* Menu:
-
-* Ifdef::
-* If::
-* Defined::
-* Else::
-* Elif::
-
projects / msp430-gcc.git / blobdiff