X-Git-Url: https://oss.titaniummirror.com/gitweb/?a=blobdiff_plain;f=gcc%2Fdoc%2Fcpp.info-2;fp=gcc%2Fdoc%2Fcpp.info-2;h=0000000000000000000000000000000000000000;hb=6fed43773c9b0ce596dca5686f37ac3fc0fa11c0;hp=7193b5fe01cedba5aaae57f42341db0d9f93c4d8;hpb=27b11d56b743098deb193d510b337ba22dc52e5c;p=msp430-gcc.git diff --git a/gcc/doc/cpp.info-2 b/gcc/doc/cpp.info-2 deleted file mode 100644 index 7193b5fe..00000000 --- a/gcc/doc/cpp.info-2 +++ /dev/null @@ -1,1148 +0,0 @@ -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 - - -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. - - -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), - ... - }; - - -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. - - -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:: - - -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. - - - -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. - - -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'. - - -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' `^=' - - -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. - - -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:: - - -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. - - -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)) - - -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. - - -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'). - - -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. - - -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. - - - -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. - - -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:: - - -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. - - -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:: -