1. Manuals
  2. Brands
  3. Red Hat Manuals
  4. Software
  5. ENTERPRISE LINUX 3 - USING BINUTILS
  6. Using instructions

Red Hat ENTERPRISE LINUX 3 - USING CPP Using Instructions

Using cpp, the c preprocessor
Hide thumbs Also See for ENTERPRISE LINUX 3 - USING CPP:
Table of Contents

Advertisement

Quick Links

Download this manual See also: Instructions for Using
Red Hat Enterprise Linux 3
Using cpp, the C Preprocessor

Advertisement

Table of Contents
loading

Related Manuals for Red Hat ENTERPRISE LINUX 3 - USING CPP

Summary of Contents for Red Hat ENTERPRISE LINUX 3 - USING CPP

  • Page 1 Red Hat Enterprise Linux 3 Using cpp, the C Preprocessor...
  • Page 2 HTML, PDF, and RPM versions of the manuals are available on the Documentation CD and online at http://www.redhat.com/docs/. 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...

  • Page 3: Table Of Contents

    Table of Contents 1. Overview ............................1 1.1. Initial processing........................ 1 1.2. Tokenization........................3 1.3. The preprocessing language....................5 2. Header Files............................. 7 2.1. Include Syntax ........................7 2.2. Include Operation....................... 7 2.3. Search Path......................... 8 2.4. Once-Only Headers......................9 2.5.
  • Page 4 11.2. Implementation limits ....................51 11.3. Obsolete Features......................52 11.3.1. Assertions......................52 11.3.2. Obsolete once-only headers ................53 11.3.3. Miscellaneous obsolete features ..............54 11.4. Differences from previous versions ................54 12. Invocation ............................ 57 13. Environment Variables ....................... 65 14.

  • Page 5: Overview

    Chapter 1. Overview 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. It is called a macro processor because it allows you to define macros, which are brief abbreviations for longer constructs. The C preprocessor implements the macro language used to transform C, C++, and Objective-C pro- grams before they are compiled.
  • Page 6 Chapter 1. Overview different one and use it without conversion. (GCC may lose track of the current line number if a file doesn’t consistently use one convention, as sometimes happens when it is edited on computers with different conventions that share a network file system.) LF CR is included because it has been reported as an end-of-line marker under exotic conditions.

  • Page 7: Tokenization

    Chapter 1. Overview But beware of commenting out one end of a block comment with a line comment. // l.c. /* block comment begins oops! this isn’t a comment anymore */ Comments are not recognized within string literals. "/* blah */" is the string constant /* blah */ not an empty string.
  • Page 8 Chapter 1. Overview When faced with a sequence of characters that has more than one possible tokenization, the prepro- cessor is greedy. It always makes each token, starting from the left, as big as possible before moving on to the next token. For instance, is interpreted as , not as a+++++b...

  • Page 9: The Preprocessing Language

    Chapter 1. Overview is no limit on the length of a character constant, but the value of a character constant that contains more than one character is implementation-defined. Refer to Chapter 11 Implementation Details. Header file names either look like string constants, ". . . ", or are written with angle brackets instead, ¢...
  • Page 10 Chapter 1. Overview Macro expansion. You can define macros, which are abbreviations for arbitrary fragments of C • code. The preprocessor will replace the macros with their definitions throughout the program. Some macros are automatically defined for you. Conditional compilation. You can include or exclude parts of the program according to various •...

  • Page 11: Header Files

    Chapter 2. Header Files A header file is a file containing C declarations and macro definitions (Refer to 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.

  • Page 12: Include Operation

    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.

  • Page 13: Once-Only Headers

    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.

  • Page 14: Computed Includes

    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. GNU CPP optimizes even further.

  • Page 15: Wrapper Headers

    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...

  • Page 16: System Headers

    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 (Refer to Chapter 5 Diagnostics), are #warning suppressed while GCC is processing a system header.

  • Page 17: Macros

    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.

  • Page 18: Function-Like Macros

    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.

  • Page 19: Macro Arguments

    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 20 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); ==>...

  • Page 21: Stringification

    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.

  • Page 22: Concatenation

    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) ==>...

  • Page 23: Variadic Macros

    Chapter 3. Macros 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.
  • Page 24 Chapter 3. Macros using this extension. You cannot use and this extension in the same macro. __VA_ARGS__ 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.

  • Page 25: Predefined Macros

    Chapter 3. Macros 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)
  • Page 26 Chapter 3. Macros C99 introduces , and GCC has provided for a long time. Both of these are __func__ __FUNCTION__ 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 , though.

  • Page 27: Common Predefined Macros

    Chapter 3. Macros 3.7.2. 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.
  • Page 28 Chapter 3. Macros __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.

  • Page 29: System-Specific Predefined Macros

    Chapter 3. Macros work correctly. You should not use these macros directly; instead, include the appro- wchar.h priate 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 for exception handling.

  • Page 30: Undefining And Redefining Macros

    Chapter 3. Macros or_eq xor_eq 3.8. Undefining and Redefining Macros If a macro ceases to be useful, it may be undefined with the directive. takes a single #undef #undef argument, the name of the macro to undefine. You use the bare macro name, even if the macro is function-like.

  • Page 31: Macro Pitfalls

    Chapter 3. Macros 3.9. 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. 3.9.1. 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.

  • Page 32: Swallowing The Semicolon

    Chapter 3. Macros 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 .

  • Page 33: Duplication Of Side Effects

    Chapter 3. Macros if (*p != 0) SKIP_SPACES (p, lim); else ... The presence of two statements--the compound statement and a null statement--in between the condition and the makes invalid C code. else The definition of the macro can be altered to solve this problem, using a SKIP_SPACES do ...

  • Page 34: Self-Referential Macros

    Chapter 3. Macros #define min(X, Y) ({ typeof (X) x_ = (X); typeof (Y) y_ = (Y); y_) ? x_ : y_; }) notation produces a compound statement that acts as an expression. Its value is the ({ ... }) value of its last statement.

  • Page 35: Argument Prescan

    Chapter 3. Macros then the macro expands to . Effectively, it is left alone by the preprocessor whenever EPERM EPERM it’s used in running text. You can tell that it’s a macro with . You might do this if you want to #ifdef define numeric constants with an , but have...

  • Page 36: Newlines In Arguments

    Chapter 3. Macros 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...

  • Page 37: Conditionals

    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 38 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...

  • Page 39: Defined

    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, •...

  • Page 40: Else

    Chapter 4. Conditionals " #if defined BUFSIZE && BUFSIZE = 1024 " 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.

  • Page 41: Deleted Code

    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.
  • Page 42 Chapter 4. Conditionals...

  • Page 43: Diagnostics

    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.
  • Page 44 Chapter 5. Diagnostics...

  • Page 45: Line Control

    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 46 Chapter 6. Line Control distribution was created. If GCC tries to search for headers in those directories, the build is likely to fail. 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.

  • Page 47: Pragmas

    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 48 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.

  • Page 49: Other Directives

    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.
  • Page 50 Chapter 8. Other Directives...

  • Page 51: Preprocessor Output

    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 52 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.

  • Page 53: Traditional Mode

    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 prepro- -traditional cessor. We do not guarantee that GCC’s behavior under matches any pre-standard -traditional preprocessor exactly.
  • Page 54 Chapter 10. Traditional Mode warn about features of ISO C which you must use when you are using a conforming compiler, such as the operators. Presently warns about: -Wtraditional Macro parameters that appear within string literals in the macro body. In traditional C macro re- •...

  • Page 55: Implementation Details

    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 GNU CPP.

  • Page 56: Obsolete Features

    Chapter 11. Implementation Details Where we say something is limited only by available memory, that means that internal data structures impose no intrinsic limit, and space is allocated with or equivalent. The actual limit will malloc therefore depend on many things, such as the size of other things allocated by the compiler at the same time, the amount of memory consumed by other processes on the same computer, etc.

  • Page 57: Obsolete Once-Only Headers

    Chapter 11. Implementation Details An assertion looks like this: predicate answer must be a single identifier. can be any sequence of tokens; all characters are predicate answer significant except for leading and trailing whitespace, and differences in internal whitespace sequences are ignored.

  • Page 58: Miscellaneous Obsolete Features

    Chapter 11. Implementation Details is not a well designed feature. It requires the users of a header file to know that it should #import only be included once. It is much better for the header file’s implementor to write the file so that users don’t need to know this.
  • Page 59 Chapter 11. Implementation Details GCC 3.0 evaluates at the same time and strictly left to right. Older versions evaluated all operators first, then all operators, in an unreliable order. The form of whitespace betwen tokens in preprocessor output • Refer to Chapter 9 Preprocessor Output for the current textual format. This is also the format used by stringification.
  • Page 60 Chapter 11. Implementation Details...

  • Page 61: Invocation

    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 62 Chapter 12. Invocation Add the directory to the list of directories to be searched for header files. Refer to Sec- tion 2.3 Search Path. Directories named by are searched before the standard system include directories. It is dangerous to specify a standard system include directory in an option.
  • Page 63 Chapter 12. Invocation -pedantic Issue all the mandatory diagnostics listed in the C standard. Some of them are left out by default, since they trigger frequently on harmless code. -pedantic-errors Issue all the mandatory diagnostics, and make all mandatory diagnostics into errors. This includes mandatory diagnostics that GCC issues without but treats as warnings.
  • Page 64 Chapter 12. Invocation target Change the target of the rule emitted by dependency generation. By default CPP takes the name of the main input file, including any path, deletes any file suffix such as , and appends the platform’s usual object suffix. The result is the target. option will set the target to be exactly the string you specify.
  • Page 65 Chapter 12. Invocation iso9899:1990 The ISO C standard from 1990. is the customary shorthand for this version of the standard. option is equivalent to -ansi -std=c89 iso9899:199409 The 1990 C standard, as amended in 1994. iso9899:1999 iso9899:199x The revised ISO C standard, published in December 1999. Before publication, this was known as C9X.
  • Page 66 Chapter 12. Invocation -imacros file Exactly like , except that any output produced by scanning is thrown away. -include file Macros it defines remain defined. This allows you to acquire all the macros from a header without also processing its declarations. All files specified by are processed before all files specified by -imacros...
  • Page 67 Chapter 12. Invocation Cancel all predefined assertions and all assertions preceding it on the command line. Also, unde- fine all predefined macros and all macros preceding it on the command line. (This is a historical wart and may change in the future.) -dCHARS is a sequence of one or more of the following characters, and must not be preceded by a CHARS...
  • Page 68 Chapter 12. Invocation -traditional Try to imitate the behavior of old-fashioned C, as opposed to ISO C. Refer to Chapter 10 Tradi- tional Mode. -trigraphs Process trigraph sequences. Refer to Section 1.1 Initial processing. -remap Enable special code to work around file systems which only permit very short file names, such as MS-DOS.

  • Page 69: Environment Variables

    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 output with options like (Refer to Chapter 12 Invocation).
  • Page 70 Chapter 13. Environment Variables...

  • Page 71: Gnu Free Documentation License

    Chapter 14. GNU Free Documentation License Version 1.1, March 2000 Copyright © 2000 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. 1.
  • Page 72 Chapter 14. GNU Free Documentation License A "Transparent" copy of the Document means a machine-readable copy, represented in a for- mat whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pix- els) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suit- able for input to text formatters.
  • Page 73 Chapter 14. GNU Free Documentation License version of the Document. 5. MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sec- tions 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and mod- ification of the Modified Version to whoever possesses a copy of it.
  • Page 74 Chapter 14. GNU Free Documentation License You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version.

  • Page 75: Addendum: How To Use This License For Your Documents

    Chapter 14. GNU Free Documentation License permission from their copyright holders, but you may include translations of some or all Invari- ant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License.
  • Page 76 Chapter 14. GNU Free Documentation License...

  • Page 77: Option Index

    Option Index iwithprefixbefore, Refer to Chapter 12 Invocation CPP’s command line options are indexed here without any initial M, Refer to Chapter 12 Invocation MD, Refer to Chapter 12 Invocation $, Refer to Chapter 12 Invocation MF, Refer to Chapter 12 Invocation MG, Refer to Chapter 12 Invocation MM, Refer to Chapter 12 Invocation MMD, Refer to Chapter 12 Invocation...
  • Page 78 Option Index v, Refer to Chapter 12 Invocation version, Refer to Chapter 12 Invocation w, Refer to Chapter 12 Invocation Wall, Refer to Chapter 12 Invocation Wcomment, Refer to Chapter 12 Invocation Wcomments, Refer to Chapter 12 Invocation Werror, Refer to Chapter 12 Invocation Wimport, Refer to Chapter 12 Invocation Wsystem-headers, Refer to Chapter 12 Invocation Wtraditional, Refer to Chapter 12 Invocation...

  • Page 79: Index Of Directives

    Index of Directives #assert, Refer to Section 11.3.1 Assertions #define, Refer to Section 3.1 Object-like Macros #elif, Refer to Section 4.2.5 Elif #else, Refer to Section 4.2.4 Else #endif, Refer to Section 4.2.1 Ifdef #error, Refer to Chapter 5 Diagnostics #ident, Refer to Chapter 8 Other Directives #if, Refer to Section 4.2 Conditional Syntax #ifdef, Refer to Section 4.2.1 Ifdef...

  • Page 81: Concept Index

    Concept Index differences from previous versions, Refer to Section 11.4 Differences from previous versions digraphs, Refer to Section 1.2 Tokenization directive line, Refer to Section 1.3 The preprocessing operator, Refer to Section 3.4 Stringification language operator, Refer to Section 3.5 Concatenation directive name, Refer to Section 1.3 The preprocess- , Refer to Chapter 7 Pragmas _Pragma...
  • Page 82 Concept Index predefined macros, system-specific, Refer to Section 3.7.3 System-specific Predefined Macros line comments, Refer to Section 1.1 Initial processing predicates, Refer to Section 11.3.1 Assertions line control, Refer to Chapter 6 Line Control preprocessing directives, Refer to Section 1.3 The pre- line endings, Refer to Section 1.1 Initial processing processing language linemarkers, Refer to Chapter 9 Preprocessor Output...
  • Page 83 Concept Index trigraphs, Refer to Section 1.1 Initial processing undefining macros, Refer to Section 3.8 Undefining and Redefining Macros unsafe macros, Refer to Section 3.9.4 Duplication of Side Effects variable number of arguments, Refer to Section 3.6 Variadic Macros variadic macros, Refer to Section 3.6 Variadic Macros wrapper , Refer to Section 2.4 Once-Only #ifndef...

This manual is also suitable for:

Enterprise linux 3

Table of Contents