Global network block device, using gnbd with red hat global file system (24 pages)
Summary of Contents for Red Hat ENTERPRISE LINUX 4 - USING CPP
Page 1
Red Hat Enterprise Linux 4 Using cpp, the C Preprocessor...
Page 2
All other trademarks referenced herein are the property of their respective owners. The GPG fingerprint of the security@redhat.com key is: CA 20 86 86 2B D6 9D FC 65 F6 EC C4 21 91 80 CD DB 42 A6 0E...
Chapter 1. Overview The C preprocessor implements the macro language used to transform C, C++, and Objective-C pro- grams before they are compiled. It can also be useful on its own. The C preprocessor, often known as cpp, is a macro processor that is used automatically by the C compiler to transform your program before compilation.
Chapter 1. Overview 1.1. Character sets Source code character set processing in C and related languages is rather complicated. The C standard discusses two character sets, but there are really at least four. The files input to CPP might be in any character set at all. CPP’s very first action, before it even looks for line boundaries, is to convert the file into the character set it uses for internal processing.
Page 9
Chapter 1. Overview These are nine three-character sequences, all starting with , that are defined by ISO C to stand for single characters. They permit obsolete systems that lack some of C’s punctuation to use C. For example, stands for , so ’??/n’...
Chapter 1. Overview Comments are not recognized within string literals. "/* blah */" is the string constant /* blah */ not an empty string. Line comments are not in the 1989 edition of the C standard, but they are recognized by GCC as an extension.
Page 11
Chapter 1. Overview instance. The only identifier which can be considered a preprocessing keyword is . Section defined 4.2.3 Defined. This is mostly true of other languages which use the C preprocessor. However, a few of the keywords of C++ are significant even in the preprocessor. Section 3.7.4 C++ Named Operators. In the 1999 C standard, identifiers may contain letters which are not part of the "basic source charac- ter set,"...
Chapter 1. Overview Any other single character is considered "other." It is passed on to the preprocessor’s output unmo- lested. The C compiler will almost certainly reject source code containing "other" tokens. In ASCII, the only other characters are , and control characters other than NUL (all bits zero). (Note that ‘...
Page 13
Chapter 1. Overview Some directives require arguments; these make up the rest of the directive line and must be separated from the directive name by whitespace. For example, must be followed by a macro name #define and the intended expansion of the macro. A preprocessing directive cannot cover more than one line.
Chapter 2. Header Files A header file is a file containing C declarations and macro definitions (Chapter 3 Macros) to be shared between several source files. You request the use of a header file in your program by including it, with the C preprocessing directive #include Header files serve two purposes.
Chapter 2. Header Files 2.2. Include Operation directive works by directing the C preprocessor to scan the specified file as input #include before continuing with the rest of the current file. The output from the preprocessor contains the output already generated, followed by the output resulting from the included file, followed by the output that comes from the text after the directive.
Chapter 2. Header Files /usr/include For C++ programs, it will also look in , first. In the above, is the /usr/include/g++-v3 target canonical name of the system GCC was configured to compile code for; often but not always the same as the canonical name of the system it runs on.
Chapter 2. Header Files This construct is commonly known as a wrapper #ifndef . When the header is included again, the conditional will be false, because is defined. The preprocessor will skip over the FILE_FOO_SEEN entire contents of the file, and the compiler will not see it twice. CPP optimizes even further.
Chapter 2. Header Files #include HEADER looks for a file named . CPP searches for the file according to the rules for double-quoted in- a\"b cludes. If the line expands to a token stream beginning with a token and including a token, then the tokens between the and the first...
Chapter 2. Header Files 2.7. System Headers The header files declaring interfaces to the operating system and runtime libraries often cannot be written in strictly conforming C. Therefore, GCC gives code found in system headers special treat- ment. All warnings, other than those generated by (Chapter 5 Diagnostics), are suppressed #warning while GCC is processing a system header.
Chapter 3. Macros A macro is a fragment of code which has been given a name. Whenever the name is used, it is replaced by the contents of the macro. There are two kinds of macros. They differ mostly in what they look like when they are used.
Chapter 3. Macros The most common visible consequence of this is surprising line numbers in error messages. There is no restriction on what can go in a macro body provided it decomposes into valid preprocessing tokens. Parentheses need not balance, and the body need not resemble valid C code. (If it does not, you may get error messages from the C compiler when you use the macro.) The C preprocessor scans your program sequentially.
Chapter 3. Macros 3.2. Function-like Macros You can also define macros whose use looks like a function call. These are called function-like macros. To define a function-like macro, you use the same directive, but you put a pair of parentheses #define immediately after the macro name.
Page 24
Chapter 3. Macros #define min(X, Y) ((X) (Y) ? (X) : (Y)) x = min(a, b); ==> x = ((a) (b) ? (a) : (b)); y = min(1, 2); ==> y = ((1) (2) ? (1) : (2)); z = min(a + 28, *p); ==>...
Chapter 3. Macros Whitespace is not a preprocessing token, so if a macro takes one argument, foo () foo ( both supply it an empty argument. Previous GNU preprocessor implementations and documentation were incorrect on this point, insisting that a function-like macro that takes a single argument be passed a space if an empty argument was required.
Chapter 3. Macros 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) ==>...
Chapter 3. Macros { "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.
Page 28
Chapter 3. Macros You can have named arguments as well as variable arguments in a variadic macro. We could define like this, instead: eprintf #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.
Chapter 3. Macros Previous versions of 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)
Page 30
Chapter 3. Macros 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 , though. __FILE__ __LINE__ __DATE__ This macro expands to a string constant that describes the date on which the preprocessor is being run.
Chapter 3. Macros __OBJC__ This macro is defined, with value 1, when the Objective-C compiler is in use. You can use to test whether a header is compiled by a C compiler or a Objective-C compiler. __OBJC__ __ASSEMBLER__ This macro is defined with value 1 when preprocessing assembly language. 3.7.2.
Page 32
Chapter 3. Macros __STRICT_ANSI__ GCC defines this macro if and only if the switch, or a switch specifying strict -ansi -std conformance to some version of ISO C, was specified when GCC was invoked. It is defined to . 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.
Chapter 3. Macros __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 environment it expands to an , but in m68k-aout environment it expands to nothing. m68k-coff This macro will have the correct definition even if is in use, but it...
Chapter 3. Macros all. Chapter 12 Invocation. All system-specific predefined macros expand to the constant 1, so you can test them with either #ifdef 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.
Chapter 3. Macros function-like. It is an error if anything appears on the line after the macro name. has no effect #undef if the name is not a macro. #define FOO 4 x = FOO; ==> x = 4; #undef FOO x = FOO;...
Chapter 3. Macros If, within a macro invocation, that macro is redefined, then the new definition takes effect in time for argument pre-expansion, but the original definition is still used for argument replacement. Here is a pathological example: #define f(x) x x f (1 #undef f #define f 2...
Chapter 3. Macros 3.10.2. 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.
Chapter 3. Macros 3.10.3. 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 says where to find it) across whitespace characters: #define SKIP_SPACES(p, limit) { char *lim = (limit);...
Chapter 3. Macros 3.10.4. Duplication of Side Effects Many C programs define a macro , 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));...
Page 40
Chapter 3. Macros 3.10.5. 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.
Chapter 3. Macros 3.10.6. Argument Prescan Macro arguments are completely macro-expanded before they are substituted into a macro body, un- less 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.
Chapter 3. Macros 3.10.7. 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 com- piler or debugger refer to the line the invocation started on, which might be different to the line containing the argument causing the problem.
Chapter 4. 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 arith- metic expressions, or whether a name is defined as a macro, or both simultaneously using the special operator.
Page 44
Chapter 4. Conditionals #ifdef MACRO controlled text #endif /* MACRO This block is called a conditional group. will be included in the output of the controlled text preprocessor if and only if is defined. We say that the conditional succeeds if is defined, MACRO MACRO...
Chapter 4. Conditionals controlled text #endif /* expression is a C expression of integer type, subject to stringent restrictions. It may contain expression Integer constants. • Character constants, which are interpreted as they would be in normal code. • Arithmetic operators for addition, subtraction, multiplication, division, bitwise operations, shifts, •...
Chapter 4. Conditionals " can generally be simplified to just , since if is not defined, it will #if BUFSIZE = 1024 BUFSIZE be interpreted as having the value zero. If the operator appears as a result of a macro expansion, the C standard says the behavior is defined undefined.
Chapter 4. Conditionals stands for "else if". Like , it goes in the middle of a conditional group and subdivides #elif #else it; it does not require a matching of its own. Like , the directive includes an #endif #elif expression to be tested.
Chapter 5. Diagnostics The directive causes the preprocessor to report a fatal error. The tokens forming the rest of #error the line following are used as the error message. #error You would use inside of a conditional that detects a combination of parameters which you #error know the program does not properly support.
Chapter 6. Line Control The C preprocessor informs the C compiler of the location in your source code where each token came from. Presently, this is just the file name and line number. All the tokens resulting from macro expansion are reported as having appeared on the line of the source file where the outermost macro was used.
Page 52
Chapter 6. Line Control The new behavior can cause failures too, if the generated file is not in the same directory as its source and it attempts to include a header which would be visible searching from the directory containing the source file.
Chapter 7. Pragmas directive is the method specified by the C standard for providing additional information #pragma to the compiler, beyond what is conveyed in the language itself. Three forms of this directive (com- monly known as pragmas) are specified by the 1999 C standard. A C compiler is free to attach any meaning it likes to other pragmas.
Page 54
Chapter 7. Pragmas #pragma GCC poison Sometimes, there is an identifier that you want to remove completely from your program, and make sure that it never creeps back in. To enforce this, you can poison the identifier with this pragma. is followed by a list of identifiers to poison.
Chapter 8. Other Directives directive takes one argument, a string constant. On some systems, that string constant is #ident copied into a special segment of the object file. On other systems, the directive is ignored. This directive is not part of the C standard, but it is not an official GNU extension either. We believe it came from System V.
Chapter 9. Preprocessor Output When the C preprocessor is used with the C, C++, or Objective-C compilers, it is integrated into the compiler and communicates a stream of binary tokens directly to the compiler’s parser. However, it can also be used in the more conventional standalone mode, where it produces textual output. The output from the C preprocessor looks much like the input, except that all preprocessing directive lines have been replaced with blank lines and all comments with spaces.
Page 58
Chapter 9. Preprocessor Output column, and there will be no space between the and the directive name. If macro expansion happens to generate tokens which might be mistaken for a duplicated directive, a space will be inserted between and the directive name.
Chapter 10. Traditional Mode Traditional (pre-standard) C preprocessing is rather different from the preprocessing specified by the standard. When GCC is given the option, it attempts to emulate a traditional -traditional-cpp preprocessor. GCC versions 3.2 and later only support traditional mode semantics in the preprocessor, and not in the compiler front ends.
Chapter 10. Traditional Mode course, if you attempt to compile preprocessed output containing an unmatched quote you will get a syntax error. However, all preprocessing directives other than require matching quotes. For example: #define #define m This macro’s fine and has an unmatched quote "/* This is not a comment.
Chapter 10. Traditional Mode f( ) is treated as an invocation of the macro with a single argument consisting of a single space. If you want to invoke a function-like macro that takes no arguments, you must not leave any whitespace between the parentheses.
Page 62
Chapter 10. Traditional Mode In traditional C, some preprocessor directives did not exist. Traditional preprocessors would • only consider a line to be a directive if the appeared in column 1 on the line. Therefore warns about directives that traditional C understands but would ignore because -Wtraditional does not appear as the first character on the line.
Chapter 11. Implementation Details Here we document details of how the preprocessor’s implementation affects its user-visible behavior. You should try to avoid undue reliance on behavior described here, as it is possible that it will change subtly in future implementations. Also documented here are obsolete features and changes from previous versions of CPP.
Chapter 11. Implementation Details Interpretation of the filename resulting from a macro-expanded directive. • #include Section 2.5 Computed Includes. Treatment of a directive that after macro-expansion results in a standard pragma. • #pragma No macro expansion occurs on any directive line, so the question does not arise. #pragma Note that GCC does not yet implement any of the standard pragmas.
Chapter 11. Implementation Details 11.3. Obsolete Features CPP has a number of features which are present mainly for compatibility with older programs. We discourage their use in new code. In some cases, we plan to remove the feature in a future version of GCC.
Chapter 11. Implementation Details In either form, if no such assertion has been made, has no effect. #unassert You can also make or cancel assertions using command line options. Chapter 12 Invocation. 11.3.2. Obsolete once-only headers CPP supports two more ways of indicating that a header file should be read only once. Neither one is as portable as a wrapper , and we recommend you do not use them in new programs.
Page 67
Chapter 11. Implementation Details Older versions of GCC preserved all whitespace provided by the user and inserted lots more whites- pace of their own, because they could not accurately predict when extra spaces were needed to prevent accidental token pasting. Optional argument when invoking rest argument macros •...
Chapter 12. Invocation Most often when you use the C preprocessor you will not have to invoke it explicitly: the C compiler will do so automatically. However, the preprocessor is sometimes useful on its own. All the options listed here are also acceptable to the C compiler and have the same meaning, except that the C compiler has different rules for specifying the output file.
Page 70
Chapter 12. Invocation Add the directory to the list of directories to be searched for header files. Section 2.3 Search Path. Directories named by are searched before the standard system include directories. If the directory is a standard system include directory, the option is ignored to ensure that the default search order for system directories and the special treatment of system headers are not defeated (Section 2.7 System Headers) .
Page 71
Chapter 12. Invocation Note: If a macro is actually used, but only used in skipped conditional blocks, then CPP will report it as unused. To avoid the warning in such a case, you might improve the scope of the macro’s definition by, for example, moving it into the first skipped block. Alternatively, you could provide a dummy use with something like: #if defined the_macro_causing_the_warning #endif...
Page 72
Chapter 12. Invocation Like but do not mention header files that are found in system header directories, nor header files that are included, directly or indirectly, from such a header. This implies that the choice of angle brackets or double quotes in an directive does #include not in itself determine whether that header will appear in...
Page 73
Chapter 12. Invocation is used in conjunction with , any switch is understood to specify the dependency output file, but if used without , each is understood to specify a target object file. Since is not implied, can be used to generate a dependency output file as a side-effect of the compilation process.
Page 74
Chapter 12. Invocation c++98 The 1998 ISO C++ standard plus amendments. gnu++98 The same as plus GNU extensions. This is the default for C++ code. -std=c++98 Split the include path. Any directories specified with options before are searched only & for headers requested with ;...
Page 75
Chapter 12. Invocation -isystem Search for header files, after all directories specified by but before the standard system directories. Mark it as a system directory, so that it gets the same special treatment as is applied to the standard system directories. Section 2.7 System Headers. -fdollars-in-identifiers Accept in identifiers.
Page 76
Chapter 12. Invocation predicate answer Make an assertion with the predicate and answer . This form is preferred to predicate answer the older form , which is still supported, because it does not use shell predicate answer special characters. Section 11.3.1 Assertions. -A - predicate answer...
Page 77
Chapter 12. Invocation Do not discard comments, including during macro expansion. This is like , except that com- ments contained within macros are also passed through to the output file where the macro is expanded. In addition to the side-effects of the option, the option causes all C++-style comments inside a macro to be converted to C-style comments.
Chapter 13. Environment Variables This section describes the environment variables that affect how CPP operates. You can use them to specify directories or prefixes to use when searching for include files, or to control dependency output. Note that you can also specify places to search using options such as , and control dependency out- put with options like (Chapter 12 Invocation).
Page 82
Chapter 14. GNU Free Documentation License The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words. A "Transparent"...
Page 83
Chapter 14. GNU Free Documentation License on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
Page 84
Chapter 14. GNU Free Documentation License for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. K.
Chapter 14. GNU Free Documentation License single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
Page 86
Chapter 14. GNU Free Documentation License 14.1. ADDENDUM: How to use this License for your documents To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page: Copyright (C) year your name...
Index of Directives #assert, see Section 11.3.1 Assertions #define, see Section 3.1 Object-like Macros #elif, see Section 4.2.5 Elif #else, see Section 4.2.4 Else #endif, see Section 4.2.1 Ifdef #error, see Chapter 5 Diagnostics #ident, see Chapter 8 Other Directives #if, see Section 4.2 Conditional Syntax #ifdef, see Section 4.2.1 Ifdef #ifndef, see Section 4.2.1 Ifdef...
Option Index M, see Chapter 12 Invocation CPP’s command line options and environment MD, see Chapter 12 Invocation variables are indexed here without any initial MF, see Chapter 12 Invocation MG, see Chapter 12 Invocation MM, see Chapter 12 Invocation MMD, see Chapter 12 Invocation MP, see Chapter 12 Invocation A, see Chapter 12 Invocation...
Page 90
Option Index w, see Chapter 12 Invocation Wall, see Chapter 12 Invocation Wcomment, see Chapter 12 Invocation Wcomments, see Chapter 12 Invocation Wendif-labels, see Chapter 12 Invocation Werror, see Chapter 12 Invocation Wimport, see Chapter 12 Invocation Wsystem-headers, see Chapter 12 Invocation Wtraditional, see Chapter 12 Invocation Wtrigraphs, see Chapter 12 Invocation Wundef, see Chapter 12 Invocation...
Concept Index directive name, see Section 1.4 The preprocessing lan- guage directives, see Section 1.4 The preprocessing lan- guage operator, see Section 3.4 Stringification operator, see Section 3.5 Concatenation , see Chapter 7 Pragmas _Pragma empty macro arguments, see Section 3.3 Macro Argu- ments environment variables, see Chapter 13 Environment alternative tokens, see Section 1.3 Tokenization...
Page 92
Concept Index macro argument expansion, see Section 3.10.6 Argu- redefining macros, see Section 3.8 Undefining and Re- ment Prescan defining Macros macro arguments and directives, see Section 3.9 Di- repeated inclusion, see Section 2.4 Once-Only Head- rectives Within Macro Arguments macros in include, see Section 2.5 Computed Includes reporting errors, see Chapter 5 Diagnostics macros with arguments, see Section 3.3 Macro Argu-...
Page 93
Concept Index wrapper , see Section 2.4 Once-Only Head- #ifndef wrapper headers, see Section 2.6 Wrapper Headers...
Need help?
Do you have a question about the ENTERPRISE LINUX 4 - USING CPP and is the answer not in the manual?
Questions and answers