| \input texinfo |
| @setfilename cpp.info |
| @settitle The C Preprocessor |
| |
| @ifinfo |
| @dircategory Programming |
| @direntry |
| * Cpp: (cpp). The GNU C preprocessor. |
| @end direntry |
| @end ifinfo |
| |
| @c @smallbook |
| @c @cropmarks |
| @c @finalout |
| @setchapternewpage odd |
| @ifinfo |
| This file documents the GNU C Preprocessor. |
| |
| Copyright 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, |
| 1999, 2000, 2001 Free Software Foundation, Inc. |
| |
| Permission is granted to make and distribute verbatim copies of |
| this manual provided the copyright notice and this permission notice |
| are preserved on all copies. |
| |
| @ignore |
| Permission is granted to process this file through Tex and print the |
| results, provided the printed document carries copying permission |
| notice identical to this one except for the removal of this paragraph |
| (this paragraph not being relevant to the printed manual). |
| |
| @end ignore |
| Permission is granted to copy and distribute modified versions of this |
| manual under the conditions for verbatim copying, provided also that |
| the entire resulting derived work is distributed under the terms of a |
| permission notice identical to this one. |
| |
| Permission is granted to copy and distribute translations of this manual |
| into another language, under the above conditions for modified versions. |
| @end ifinfo |
| |
| @titlepage |
| @c @finalout |
| @title The C Preprocessor |
| @subtitle Last revised January 2001 |
| @subtitle for GCC version 3 |
| @author Richard M. Stallman |
| @page |
| @vskip 2pc |
| This booklet is eventually intended to form the first chapter of a GNU |
| C Language manual. |
| |
| @vskip 0pt plus 1filll |
| @c man begin COPYRIGHT |
| Copyright @copyright{} 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, |
| 1997, 1998, 1999, 2000, 2001 |
| Free Software Foundation, Inc. |
| |
| Permission is granted to make and distribute verbatim copies of |
| this manual provided the copyright notice and this permission notice |
| are preserved on all copies. |
| |
| Permission is granted to copy and distribute modified versions of this |
| manual under the conditions for verbatim copying, provided also that |
| the entire resulting derived work is distributed under the terms of a |
| permission notice identical to this one. |
| |
| Permission is granted to copy and distribute translations of this manual |
| into another language, under the above conditions for modified versions. |
| @c man end |
| @end titlepage |
| @page |
| |
| @node Top, Global Actions,, (DIR) |
| @chapter The C Preprocessor |
| @c man begin DESCRIPTION |
| |
| The C preprocessor is a @dfn{macro processor} that is used automatically |
| by the C compiler to transform your program before actual compilation. |
| It is called a macro processor because it allows you to define |
| @dfn{macros}, which are brief abbreviations for longer constructs. |
| |
| The C preprocessor is intended only for macro processing of C, C++ and |
| Objective C source files. For macro processing of other files, you are |
| strongly encouraged to use alternatives like M4, which will likely give |
| you better results and avoid many problems. For example, normally the C |
| preprocessor does not preserve arbitrary whitespace verbatim, but |
| instead replaces each sequence with a single space. |
| |
| For use on C-like source files, the C preprocessor provides four |
| separate facilities that you can use as you see fit: |
| |
| @itemize @bullet |
| @item |
| Inclusion of header files. These are files of declarations that can be |
| substituted into your program. |
| |
| @item |
| Macro expansion. You can define @dfn{macros}, which are abbreviations |
| for arbitrary fragments of C code, and then the C preprocessor will |
| replace the macros with their definitions throughout the program. |
| |
| @item |
| Conditional compilation. Using special preprocessing directives, you |
| can include or exclude parts of the program according to various |
| conditions. |
| |
| @item |
| Line control. If you use a program to combine or rearrange source files |
| into an intermediate file which is then compiled, you can use line |
| control to inform the compiler of where each source line originally came |
| from. |
| @end itemize |
| |
| C preprocessors vary in some details. This manual discusses the GNU C |
| preprocessor, which provides a small superset of the features of ISO |
| Standard C@. |
| |
| In its default mode, the GNU C preprocessor does not do a few things |
| required by the standard. These are features which are rarely, if ever, |
| used, and may cause surprising changes to the meaning of a program which |
| does not expect them. To get strict ISO Standard C, you should use the |
| @samp{-std=c89} or @samp{-std=c99} options, depending on which version |
| of the standard you want. To get all the mandatory diagnostics, you |
| must also use @samp{-pedantic}. @xref{Invocation}. |
| |
| @c man end |
| |
| @menu |
| * Global Actions:: Actions made uniformly on all input files. |
| * Directives:: General syntax of preprocessing directives. |
| * Header Files:: How and why to use header files. |
| * Macros:: How and why to use macros. |
| * Conditionals:: How and why to use conditionals. |
| * Assertions:: How and why to use assertions. |
| * Line Control:: Use of line control when you combine source files. |
| * Other Directives:: Miscellaneous preprocessing directives. |
| * Output:: Format of output from the C preprocessor. |
| * Implementation:: Implementation limits and behavior. |
| * Unreliable Features:: Undefined behavior and deprecated features. |
| * Invocation:: How to invoke the preprocessor; command options. |
| * Concept Index:: Index of concepts and terms. |
| * Index:: Index of directives, predefined macros and options. |
| @end menu |
| |
| @node Global Actions, Directives, Top, Top |
| @section Transformations Made Globally |
| @cindex ASCII NUL handling |
| |
| Most C preprocessor features are inactive unless you give specific |
| directives to request their use. (Preprocessing directives are lines |
| starting with a @samp{#} token, possibly preceded by whitespace; |
| @pxref{Directives}). However, there are four transformations that the |
| preprocessor always makes on all the input it receives, even in the |
| absence of directives. These are, in order: |
| |
| @enumerate |
| @item |
| Trigraphs, if enabled, are replaced with the character they represent. |
| |
| @item |
| Backslash-newline sequences are deleted, no matter where. This |
| feature allows you to break long lines for cosmetic purposes without |
| changing their meaning. |
| |
| Recently, the non-traditional preprocessor has relaxed its treatment of |
| escaped newlines. Previously, the newline had to immediately follow a |
| backslash. The current implementation allows whitespace in the form of |
| spaces, horizontal and vertical tabs, and form feeds between the |
| backslash and the subsequent newline. The preprocessor issues a |
| warning, but treats it as a valid escaped newline and combines the two |
| lines to form a single logical line. This works within comments and |
| tokens, as well as between tokens. Comments are @emph{not} treated as |
| whitespace for the purposes of this relaxation, since they have not yet |
| been replaced with spaces. |
| |
| @item |
| All comments are replaced with single spaces. |
| |
| @item |
| Predefined macro names are replaced with their expansions |
| (@pxref{Predefined}). |
| @end enumerate |
| |
| For end-of-line indicators, any of \n, \r\n, \n\r and \r are recognised, |
| and treated as ending a single line. As a result, if you mix these in a |
| single file you might get incorrect line numbering, because the |
| preprocessor would interpret the two-character versions as ending just |
| one line. Previous implementations would only handle UNIX-style \n |
| correctly, so DOS-style \r\n would need to be passed through a filter |
| first. |
| |
| The first three transformations are done @emph{before} all other parsing |
| and before preprocessing directives are recognized. Thus, for example, |
| you can split a line mechanically with backslash-newline anywhere |
| (except within trigraphs since they are replaced first; see below). |
| |
| @example |
| /* |
| */ # /* |
| */ defi\ |
| ne FO\ |
| O 10\ |
| 20 |
| @end example |
| |
| @noindent |
| is equivalent into @samp{#define FOO 1020}. |
| |
| There is no way to prevent a backslash at the end of a line from being |
| interpreted as a backslash-newline. For example, |
| |
| @example |
| "foo\\ |
| bar" |
| @end example |
| |
| is equivalent to @code{"foo\bar"}, not to @code{"foo\\bar"}. To avoid |
| having to worry about this, do not use the deprecated GNU extension |
| which permits multi-line strings. Instead, use string literal |
| concatenation: |
| |
| @example |
| "foo\\" |
| "bar" |
| @end example |
| |
| Your program will be more portable this way, too. |
| |
| There are a few things to note about the above four transformations. |
| |
| @itemize @bullet |
| @item |
| Comments and predefined macro names (or any macro names, for that |
| matter) are not recognized inside the argument of an @samp{#include} |
| directive, when it is delimited with quotes or with @samp{<} and |
| @samp{>}. |
| |
| @item |
| Comments and predefined macro names are never recognized within a |
| character or string constant. |
| |
| @item |
| ISO ``trigraphs'' are converted before backslash-newlines are deleted. |
| If you write what looks like a trigraph with a backslash-newline inside, |
| the backslash-newline is deleted as usual, but it is too late to |
| recognize the trigraph. |
| |
| This is relevant only if you use the @samp{-trigraphs} option to enable |
| trigraph processing. @xref{Invocation}. |
| @end itemize |
| |
| The preprocessor handles null characters embedded in the input file |
| depending upon the context in which the null appears. Note that here we |
| are referring not to the two-character escape sequence "\0", but to the |
| single character ASCII NUL. |
| |
| There are three different contexts in which a null character may |
| appear: |
| |
| @itemize @bullet |
| @item |
| Within comments. Here, null characters are silently ignored. |
| |
| @item |
| Within a string or character constant. Here the preprocessor emits a |
| warning, but preserves the null character and passes it through to the |
| output file or compiler front-end. |
| |
| @item |
| In any other context, the preprocessor issues a warning, and discards |
| the null character. The preprocessor treats it like whitespace, |
| combining it with any surrounding whitespace to become a single |
| whitespace block. Representing the null character by "^@@", this means |
| that code like |
| |
| @example |
| #define X^@@1 |
| @end example |
| |
| is equivalent to |
| |
| @example |
| #define X 1 |
| @end example |
| |
| and X is defined with replacement text "1". |
| @end itemize |
| |
| @node Directives, Header Files, Global Actions, Top |
| @section Preprocessing Directives |
| |
| @cindex preprocessing directives |
| @cindex directives |
| Most preprocessor features are active only if you use preprocessing |
| directives to request their use. |
| |
| Preprocessing directives are lines in your program that start with |
| @samp{#}. Whitespace is allowed before and after the @samp{#}. The |
| @samp{#} is followed by an identifier that is the @dfn{directive name}. |
| For example, @samp{#define} is the directive that defines a macro. |
| |
| Since the @samp{#} must be the first token on the line, it cannot come |
| from a macro expansion if you wish it to begin a directive. Also, the |
| directive name is not macro expanded. Thus, if @samp{foo} is defined as |
| a macro expanding to @samp{define}, that does not make @samp{#foo} a |
| valid preprocessing directive. |
| |
| The set of valid directive names is fixed. Programs cannot define new |
| preprocessing directives. |
| |
| Some directive names require arguments; these make up the rest of the |
| directive line and must be separated from the directive name by |
| whitespace. For example, @samp{#define} must be followed by a macro |
| name and the intended expansion of the macro. @xref{Object-like |
| Macros}. |
| |
| A preprocessing directive cannot cover more than one line. It may be |
| logically extended with backslash-newline, but that has no effect on its |
| meaning. Comments containing newlines can also divide the directive |
| into multiple lines, but a comment is replaced by a single space before |
| the directive is interpreted. |
| |
| @node Header Files, Macros, Directives, Top |
| @section Header Files |
| |
| @cindex header file |
| A header file is a file containing C declarations and macro definitions |
| (@pxref{Macros}) to be shared between several source files. You request |
| the use of a header file in your program with the C preprocessing |
| directive @samp{#include}. |
| |
| @menu |
| * Header Uses:: What header files are used for. |
| * Include Syntax:: How to write @samp{#include} directives. |
| * Include Operation:: What @samp{#include} does. |
| * Once-Only:: Preventing multiple inclusion of one header file. |
| * Inheritance:: Including one header file in another header file. |
| * System Headers:: Special treatment for some header files. |
| @end menu |
| |
| @node Header Uses, Include Syntax, Header Files, Header Files |
| @subsection Uses of Header Files |
| |
| Header files serve two kinds of purposes. |
| |
| @itemize @bullet |
| @item |
| @cindex system header files |
| System header files declare the interfaces to parts of the operating |
| system. You include them in your program to supply the definitions and |
| declarations you need to invoke system calls and libraries. |
| |
| @item |
| Your own header files contain declarations for interfaces between the |
| source files of your program. Each time you have a group of related |
| declarations and macro definitions all or most of which are needed in |
| several different source files, it is a good idea to create a header |
| file for them. |
| @end itemize |
| |
| Including a header file produces the same results in C compilation as |
| copying the header file into each source file that needs it. Such |
| copying would be time-consuming and error-prone. With a header file, |
| the related declarations appear in only one place. If they need to be |
| changed, they can be changed in one place, and programs that include the |
| header file will automatically use the new version when next recompiled. |
| The header file eliminates the labor of finding and changing all the |
| copies as well as the risk that a failure to find one copy will result |
| in inconsistencies within a program. |
| |
| The usual convention is to give header files names that end with |
| @file{.h}. Avoid unusual characters in header file names, as they |
| reduce portability. |
| |
| @node Include Syntax, Include Operation, Header Uses, Header Files |
| @subsection The @samp{#include} Directive |
| |
| @findex #include |
| Both user and system header files are included using the preprocessing |
| directive @samp{#include}. It has three variants: |
| |
| @table @code |
| @item #include <@var{file}> |
| This variant is used for system header files. It searches for a file |
| named @var{file} in a list of directories specified by you, then in a |
| standard list of system directories. You specify directories to search |
| for header files with the command option @samp{-I} (@pxref{Invocation}). |
| The option @samp{-nostdinc} inhibits searching the standard system |
| directories; in this case only the directories you specify are searched. |
| |
| The first @samp{>} character terminates the file name. The file name |
| may contain a @samp{<} character. |
| |
| @item #include "@var{file}" |
| This variant is used for header files of your own program. It searches |
| for a file named @var{file} first in the current directory, then in the |
| same directories used for system header files. The current directory is |
| the directory of the current input file. It is tried first because it |
| is presumed to be the location of the files that the current input file |
| refers to. (If the @samp{-I-} option is used, the special treatment of |
| the current directory is inhibited. @xref{Invocation}.) |
| |
| The first @samp{"} character terminates the file name. |
| |
| In both these variants, the argument behaves like a string constant in |
| that comments are not recognized, and macro names are not expanded. |
| Thus, in @samp{#include <x/*y>} the @samp{/*} does not start a comment |
| and the directive specifies inclusion of a system header file named |
| @file{x/*y}. |
| |
| However, in either variant, if backslashes occur within @var{file}, they |
| are considered ordinary text characters, not escape characters. None of |
| the character escape sequences appropriate to string constants in C are |
| processed. Thus, @samp{#include "x\n\\y"} specifies a filename |
| containing three backslashes. |
| |
| @item #include @var{anything else} |
| @cindex computed @samp{#include} |
| This variant is called a @dfn{computed #include}. Any @samp{#include} |
| directive whose argument does not fit the above two forms is a computed |
| include. The text @var{anything else} is checked for macro calls, which |
| are expanded (@pxref{Macros}). When this is done, the result must match |
| one of the above two variants --- in particular, the expansion must form |
| a string literal token, or a sequence of tokens surrounded by angle |
| braces. @xref{Implementation}. |
| |
| This feature allows you to define a macro which controls the file name |
| to be used at a later point in the program. One application of this is |
| to allow a site-specific configuration file for your program to specify |
| the names of the system include files to be used. This can help in |
| porting the program to various operating systems in which the necessary |
| system header files are found in different places. |
| @end table |
| |
| @node Include Operation, Once-Only, Include Syntax, Header Files |
| @subsection How @samp{#include} Works |
| |
| The @samp{#include} directive works by directing the C preprocessor to |
| scan the specified file as input 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 |
| @samp{#include} directive. For example, given a header file |
| @file{header.h} as follows, |
| |
| @example |
| char *test (); |
| @end example |
| |
| @noindent |
| and a main program called @file{program.c} that uses the header file, |
| like this, |
| |
| @example |
| int x; |
| #include "header.h" |
| |
| main () |
| @{ |
| printf (test ()); |
| @} |
| @end example |
| |
| @noindent |
| the output generated by the C preprocessor for @file{program.c} as input |
| would be |
| |
| @example |
| int x; |
| char *test (); |
| |
| main () |
| @{ |
| printf (test ()); |
| @} |
| @end example |
| |
| Included files are not limited to declarations and macro definitions; |
| those are merely the typical uses. Any fragment of a C program can be |
| included from another file. The include file could even contain the |
| beginning of a statement that is concluded in the containing file, or |
| the end of a statement that was started in the including file. However, |
| a comment or a string or character constant may not start in the |
| included file and finish in the including file. An unterminated |
| comment, string constant or character constant in an included file is |
| considered to end (with an error message) at the end of the file. |
| |
| It is possible for a header file to begin or end a syntactic unit such |
| as a function definition, but that would be very confusing, so don't do |
| it. |
| |
| The line following the @samp{#include} directive is always treated as a |
| separate line by the C preprocessor, even if the included file lacks a |
| final newline. |
| |
| @node Once-Only, Inheritance, Include Operation, Header Files |
| @subsection Once-Only Include Files |
| @cindex repeated inclusion |
| @cindex including just once |
| |
| Very often, one header file includes another. It can easily result that |
| a certain header file is included more than once. This may lead to |
| errors, if the header file defines structure types or typedefs, and is |
| certainly wasteful. Therefore, we often wish to prevent multiple |
| inclusion of a header file. |
| |
| The standard way to do this is to enclose the entire real contents of the |
| file in a conditional, like this: |
| |
| @example |
| #ifndef FILE_FOO_SEEN |
| #define FILE_FOO_SEEN |
| |
| @var{the entire file} |
| |
| #endif /* FILE_FOO_SEEN */ |
| @end example |
| |
| The macro @code{FILE_FOO_SEEN} indicates that the file has been included |
| once already. In a user header file, the macro name should not begin |
| with @samp{_}. In a system header file, this name should begin with |
| @samp{__} to avoid conflicts with user programs. In any kind of header |
| file, the macro name should contain the name of the file and some |
| additional text, to avoid conflicts with other header files. |
| |
| The GNU C preprocessor is programmed to notice when a header file uses |
| this particular construct and handle it efficiently. If a header file |
| is contained entirely in a @samp{#ifndef} conditional, modulo whitespace |
| and comments, then it remembers that fact. If a subsequent |
| @samp{#include} specifies the same file, and the macro in the |
| @samp{#ifndef} is already defined, then the directive is skipped without |
| processing the specified file at all. |
| |
| @findex #import |
| In the Objective C language, there is a variant of @samp{#include} |
| called @samp{#import} which includes a file, but does so at most once. |
| If you use @samp{#import} @emph{instead of} @samp{#include}, then you |
| don't need the conditionals inside the header file to prevent multiple |
| execution of the contents. |
| |
| @samp{#import} is obsolete because it is not a well designed feature. |
| It requires the users of a header file --- the applications programmers |
| --- to know that a certain header file should 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. Using @samp{#ifndef} accomplishes |
| this goal. |
| |
| @node Inheritance, System Headers, Once-Only, Header Files |
| @subsection Inheritance and Header Files |
| @cindex inheritance |
| @cindex overriding a header file |
| |
| @dfn{Inheritance} is what happens when one object or file derives some |
| of its contents by virtual copying from another object or file. In |
| the case of C header files, inheritance means that one header file |
| includes another header file and then replaces or adds something. |
| |
| If the inheriting header file and the base header file have different |
| names, then inheritance is straightforward: simply write @samp{#include |
| "@var{base}"} in the inheriting file. |
| |
| Sometimes it is necessary to give the inheriting file the same name as |
| the base file. This is less straightforward. |
| |
| For example, suppose an application program uses the system header |
| @file{sys/signal.h}, but the version of @file{/usr/include/sys/signal.h} |
| on a particular system doesn't do what the application program expects. |
| It might be convenient to define a ``local'' version, perhaps under the |
| name @file{/usr/local/include/sys/signal.h}, to override or add to the |
| one supplied by the system. |
| |
| You can do this by compiling with the option @samp{-I.}, and writing a |
| file @file{sys/signal.h} that does what the application program expects. |
| Making this file include the standard @file{sys/signal.h} is not so easy |
| --- writing @samp{#include <sys/signal.h>} in that file doesn't work, |
| because it includes your own version of the file, not the standard |
| system version. Used in that file itself, this leads to an infinite |
| recursion and a fatal error in compilation. |
| |
| @samp{#include </usr/include/sys/signal.h>} would find the proper file, |
| but that is not clean, since it makes an assumption about where the |
| system header file is found. This is bad for maintenance, since it |
| means that any change in where the system's header files are kept |
| requires a change somewhere else. |
| |
| @findex #include_next |
| The clean way to solve this problem is to use |
| @samp{#include_next}, which means, ``Include the @emph{next} file with |
| this name.'' This directive works like @samp{#include} except in |
| searching for the specified file: it starts searching the list of header |
| file directories @emph{after} the directory in which the current file |
| was found. |
| |
| Suppose you specify @samp{-I /usr/local/include}, and the list of |
| directories to search also includes @file{/usr/include}; and suppose |
| both directories contain @file{sys/signal.h}. Ordinary @samp{#include |
| <sys/signal.h>} finds the file under @file{/usr/local/include}. If that |
| file contains @samp{#include_next <sys/signal.h>}, it starts searching |
| after that directory, and finds the file in @file{/usr/include}. |
| |
| @samp{#include_next} is a GCC extension and should not be used in |
| programs intended to be portable to other compilers. |
| |
| @node System Headers,, Inheritance, Header Files |
| @subsection System Headers |
| @cindex system header files |
| |
| The header files declaring interfaces to the operating system and |
| runtime libraries often cannot be written in strictly conforming C. |
| Therefore, GNU C gives code found in @dfn{system headers} special |
| treatment. Certain categories of warnings are suppressed, notably those |
| enabled by @samp{-pedantic}. |
| |
| Normally, only the headers found in specific directories are considered |
| system headers. The set of these directories is determined when GCC is |
| compiled. There are, however, two ways to add to the set. |
| |
| @findex -isystem |
| The @samp{-isystem} command line option adds its argument to the list of |
| directories to search for headers, just like @samp{-I}. In addition, |
| any headers found in that directory will be considered system headers. |
| Note that unlike @samp{-I}, you must put a space between @samp{-isystem} |
| and its argument. |
| |
| All directories named by @samp{-isystem} are searched @strong{after} all |
| directories named by @samp{-I}, no matter what their order was on the |
| command line. If the same directory is named by both @samp{-I} and |
| @samp{-isystem}, @samp{-I} wins; it is as if the @samp{-isystem} option |
| had never been specified at all. |
| |
| @findex #pragma GCC system_header |
| There is also a directive, @samp{#pragma GCC system_header}, which tells |
| GCC to consider the rest of the current include file a system header, no |
| matter where it was found. Code that comes before the @samp{#pragma} in |
| the file will not be affected. |
| |
| @samp{#pragma GCC system_header} has no effect in the primary source file. |
| |
| @node Macros, Conditionals, Header Files, Top |
| @section Macros |
| |
| A macro is a sort of abbreviation which you can define once and then |
| use later. There are many complicated features associated with macros |
| in the C preprocessor. |
| |
| @menu |
| * Object-like Macros:: Macros that always expand the same way. |
| * Function-like Macros:: Macros that accept arguments that are substituted |
| into the macro expansion. |
| * Macro Varargs:: Macros with variable number of arguments. |
| * Predefined:: Predefined macros that are always available. |
| * Stringification:: Macro arguments converted into string constants. |
| * Concatenation:: Building tokens from parts taken from macro arguments. |
| * Undefining:: Cancelling a macro's definition. |
| * Redefining:: Changing a macro's definition. |
| * Poisoning:: Ensuring a macro is never defined or used. |
| * Macro Pitfalls:: Macros can confuse the unwary. Here we explain |
| several common problems and strange features. |
| @end menu |
| |
| @node Object-like Macros, Function-like Macros, Macros, Macros |
| @subsection Object-like Macros |
| @cindex object-like macro |
| @cindex manifest constant |
| |
| An @dfn{object-like macro} is a kind of abbreviation. It is a name |
| which stands for a fragment of code. Some people refer to these as |
| @dfn{manifest constants}. |
| |
| Before you can use a macro, you must @dfn{define} it explicitly with the |
| @samp{#define} directive. @samp{#define} is followed by the name of the |
| macro and then the token sequence it should be an abbreviation for, |
| which is variously referred to as the macro's @dfn{body}, |
| @dfn{expansion} or @dfn{replacement list}. For example, |
| |
| @example |
| #define BUFFER_SIZE 1020 |
| @end example |
| |
| @noindent |
| defines a macro named @samp{BUFFER_SIZE} as an abbreviation for the |
| token @samp{1020}. If somewhere after this @samp{#define} directive |
| there comes a C statement of the form |
| |
| @example |
| foo = (char *) xmalloc (BUFFER_SIZE); |
| @end example |
| |
| @noindent |
| then the C preprocessor will recognize and @dfn{expand} the macro |
| @samp{BUFFER_SIZE}, resulting in |
| |
| @example |
| foo = (char *) xmalloc (1020); |
| @end example |
| |
| The use of all upper case for macro names is a standard convention. |
| Programs are easier to read when it is possible to tell at a glance |
| which names are macros. |
| |
| Normally, a macro definition can only span a single logical line, like |
| all C preprocessing directives. Comments within a macro definition may |
| contain newlines, which make no difference since each comment is |
| replaced by a space regardless of its contents. |
| |
| Apart from this, there is no restriction on what can go in a macro body |
| provided it decomposes into valid preprocessing tokens. In particular, |
| 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, so macro definitions |
| take effect at the place you write them. Therefore, the following input |
| to the C preprocessor |
| |
| @example |
| foo = X; |
| #define X 4 |
| bar = X; |
| @end example |
| |
| @noindent |
| produces as output |
| |
| @example |
| foo = X; |
| |
| bar = 4; |
| @end example |
| |
| When the preprocessor expands a macro name, the macro's expansion |
| replaces the macro invocation, and the result is re-scanned for more |
| macros to expand. For example, after |
| |
| @example |
| #define BUFSIZE 1020 |
| #define TABLESIZE BUFSIZE |
| @end example |
| |
| @noindent |
| the name @samp{TABLESIZE} when used in the program would go through two |
| stages of expansion, resulting ultimately in @samp{1020}. |
| |
| This is not the same as defining @samp{TABLESIZE} to be @samp{1020}. |
| The @samp{#define} for @samp{TABLESIZE} uses exactly the expansion you |
| specify --- in this case, @samp{BUFSIZE} --- and does not check to see |
| whether it too contains macro names. Only when you @emph{use} |
| @samp{TABLESIZE} is the result of its expansion scanned for more macro |
| names. @xref{Cascaded Macros}. |
| |
| @node Function-like Macros, Macro Varargs, Object-like Macros, Macros |
| @subsection Macros with Arguments |
| @cindex macros with argument |
| @cindex arguments in macro definitions |
| @cindex function-like macro |
| |
| An object-like macro is always replaced by exactly the same tokens each |
| time it is used. Macros can be made more flexible by taking |
| @dfn{arguments}. Arguments are fragments of code that you supply each |
| time the macro is used. These fragments are included in the expansion |
| of the macro according to the directions in the macro definition. A |
| macro that accepts arguments is called a @dfn{function-like macro} |
| because the syntax for using it looks like a function call. |
| |
| @findex #define |
| To define a macro that uses arguments, you write a @samp{#define} |
| directive with a list of @dfn{parameters} in parentheses after the name |
| of the macro. The parameters must be valid C identifiers, separated by |
| commas and optionally whitespace. The @samp{(} must follow the macro |
| name immediately, with no space in between. If you leave a space, you |
| instead define an object-like macro whose expansion begins with a |
| @samp{(}, and often leads to confusing errors at compile time. |
| |
| As an example, here is a macro that computes the minimum of two numeric |
| values, as it is defined in many C programs: |
| |
| @example |
| #define min(X, Y) ((X) < (Y) ? (X) : (Y)) |
| @end example |
| |
| @noindent |
| (This is not the best way to define a ``minimum'' macro in GNU C@. |
| @xref{Side Effects}, for more information.) |
| |
| To invoke a function-like macro, you write the name of the macro |
| followed by a list of @dfn{arguments} in parentheses, separated by |
| commas. The invocation of the macro need not be restricted to a single |
| logical line - it can cross as many lines in the source file as you |
| wish. The number of arguments you give must match the number of |
| parameters in the macro definition; empty arguments are fine. Examples |
| of use of the macro @samp{min} include @samp{min (1, 2)} and @samp{min |
| (x + 28, *p)}. |
| |
| The expansion text of the macro depends on the arguments you use. Each |
| macro parameter is replaced throughout the macro expansion with the |
| tokens of the corresponding argument. Leading and trailing argument |
| whitespace is dropped, and all whitespace between the tokens of an |
| argument is reduced to a single space. Using the same macro @samp{min} |
| defined above, @samp{min (1, 2)} expands into |
| |
| @example |
| ((1) < (2) ? (1) : (2)) |
| @end example |
| |
| @noindent |
| where @samp{1} has been substituted for @samp{X} and @samp{2} for @samp{Y}. |
| |
| Likewise, @samp{min (x + 28, *p)} expands into |
| |
| @example |
| ((x + 28) < (*p) ? (x + 28) : (*p)) |
| @end example |
| |
| Parentheses within each argument must balance; a comma within such |
| parentheses does not end the argument. However, there is no requirement |
| for square brackets or braces to balance, and they do not prevent a |
| comma from separating arguments. Thus, |
| |
| @example |
| macro (array[x = y, x + 1]) |
| @end example |
| |
| @noindent |
| passes two arguments to @code{macro}: @samp{array[x = y} and @samp{x + |
| 1]}. If you want to supply @samp{array[x = y, x + 1]} as an argument, |
| you must write it as @samp{array[(x = y, x + 1)]}, which is equivalent C |
| code. |
| |
| After the arguments have been substituted into the macro body, the |
| resulting expansion replaces the macro invocation, and re-scanned for |
| more macro calls. Therefore even arguments can contain calls to other |
| macros, either with or without arguments, and even to the same macro. |
| For example, @samp{min (min (a, b), c)} expands into this text: |
| |
| @example |
| ((((a) < (b) ? (a) : (b))) < (c) |
| ? (((a) < (b) ? (a) : (b))) |
| : (c)) |
| @end example |
| |
| @noindent |
| (Line breaks shown here for clarity would not actually be generated.) |
| |
| @cindex empty macro arguments |
| If a macro @code{foo} takes one argument, and you want to supply an |
| empty argument, simply supply no preprocessing tokens. Since whitespace |
| does not form a preprocessing token, it is optional. For example, |
| @samp{foo ()}, @samp{foo ( )} and @samp{bar (, arg2)}. |
| |
| 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. |
| |
| If you use a macro name followed by something other than a @samp{(} |
| (after ignoring any whitespace that might follow), it does not form an |
| invocation of the macro, and the preprocessor does not change what you |
| have written. Therefore, it is possible for the same identifier to be a |
| variable or function in your program as well as a macro, and you can |
| choose in each instance whether to refer to the macro (if an actual |
| argument list follows) or the variable or function (if an argument list |
| does not follow). For example, |
| |
| @example |
| #define foo(X) X |
| foo bar foo(baz) |
| @end example |
| |
| expands to @samp{foo bar baz}. Such dual use of one name could be |
| confusing and should be avoided except when the two meanings are |
| effectively synonymous: that is, when the name is both a macro and a |
| function and the two have similar effects. You can think of the name |
| simply as a function; use of the name for purposes other than calling it |
| (such as, to take the address) will refer to the function, while calls |
| will expand the macro and generate better but equivalent code. |
| |
| For example, you can use a function named @samp{min} in the same source |
| file that defines the macro. If you write @samp{&min} with no argument |
| list, you refer to the function. If you write @samp{min (x, bb)}, with |
| an argument list, the macro is expanded. If you write @samp{(min) (a, |
| bb)}, where the name @samp{min} is not followed by an open-parenthesis, |
| the macro is not expanded, so you wind up with a call to the function |
| @samp{min}. |
| |
| In the definition of a macro with arguments, the list of argument names |
| must follow the macro name immediately with no space in between. If |
| there is a space after the macro name, the macro is defined as taking no |
| arguments, and all the rest of the line is taken to be the expansion. |
| The reason for this is that it is often useful to define a macro that |
| takes no arguments and whose definition begins with an identifier in |
| parentheses. This rule makes it possible for you to do either this: |
| |
| @example |
| #define FOO(x) - 1 / (x) |
| @end example |
| |
| @noindent |
| (which defines @samp{FOO} to take an argument and expand into minus the |
| reciprocal of that argument) or this: |
| |
| @example |
| #define BAR (x) - 1 / (x) |
| @end example |
| |
| @noindent |
| (which defines @samp{BAR} to take no argument and always expand into |
| @samp{(x) - 1 / (x)}). |
| |
| Note that the @emph{uses} of a macro with arguments can have spaces |
| before the left parenthesis; it's the @emph{definition} where it matters |
| whether there is a space. |
| |
| @node Macro Varargs, Predefined, Function-like Macros, Macros |
| @subsection Macros with Variable Numbers of Arguments |
| @cindex variable number of arguments |
| @cindex macro with variable arguments |
| @cindex rest argument (in macro) |
| |
| In the ISO C standard of 1999, 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: |
| |
| @example |
| #define eprintf(...) fprintf (stderr, __VA_ARGS__) |
| @end example |
| |
| Here @samp{@dots{}} is a @dfn{variable argument}. In the invocation of |
| such a macro, it represents the zero or more tokens until the closing |
| parenthesis that ends the invocation, including any commas. This set of |
| tokens replaces the identifier @code{__VA_ARGS__} in the macro body |
| wherever it appears. Thus, we have this expansion: |
| |
| @example |
| eprintf ("%s:%d: ", input_file_name, line_number) |
| @expansion{} |
| fprintf (stderr, "%s:%d: " , input_file_name, line_number) |
| @end example |
| |
| Within a @samp{#define} directive, ISO C mandates that the only place |
| the identifier @code{__VA_ARGS__} can appear is in the replacement list |
| of a variable-argument 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. |
| |
| If your macro is complicated, you may want a more descriptive name for |
| the variable argument than @code{__VA_ARGS__}. GNU cpp permits this, as |
| an extension. You may write an argument name immediately before the |
| @samp{@dots{}}; that name is used for the variable argument. The |
| @code{eprintf} macro above could be written |
| |
| @example |
| #define eprintf(args...) fprintf (stderr, args) |
| @end example |
| |
| @noindent |
| using this extension. You cannot use @code{__VA_ARGS__} and this |
| extension in the same macro. |
| |
| We might instead have defined eprintf as follows: |
| |
| @example |
| #define eprintf(format, ...) fprintf (stderr, format, __VA_ARGS__) |
| @end example |
| |
| This formulation looks more descriptive, but cannot be used as flexibly. |
| There is no way to produce expanded output of |
| |
| @example |
| fprintf (stderr, "success!\n") |
| @end example |
| |
| @noindent |
| because, in standard C, you are not allowed to leave the variable |
| argument out entirely, and passing an empty argument for the variable |
| arguments will not do what you want. Writing |
| |
| @example |
| eprintf ("success!\n", ) |
| @end example |
| |
| @noindent |
| produces |
| |
| @example |
| fprintf (stderr, "success!\n",) |
| @end example |
| |
| @noindent |
| where the extra comma originates from the replacement list and not from |
| the arguments to eprintf. |
| |
| There is another extension in the GNU C preprocessor which deals with |
| this difficulty. First, you are allowed to leave the variable argument |
| out entirely: |
| |
| @example |
| eprintf ("success!\n") |
| @end example |
| |
| Second, the @samp{##} token paste operator has a special meaning when |
| placed between a comma and a variable argument. If you write |
| |
| @example |
| #define eprintf(format, ...) fprintf (stderr, format, ##__VA_ARGS__) |
| @end example |
| |
| and the variable argument is left out when the @samp{eprintf} macro is |
| used, then the comma before the @samp{##} will be deleted. This does |
| @emph{not} happen if you pass an empty argument, nor does it happen if |
| the token preceding @samp{##} is anything other than a comma. |
| |
| Previous versions of the preprocessor implemented this extension much |
| more generally. We have restricted it in order to minimize the |
| difference from the C standard. @xref{Unreliable Features}. |
| |
| @node Predefined, Stringification, Macro Varargs, Macros |
| @subsection Predefined Macros |
| |
| @cindex predefined macros |
| Several object-like macros are predefined; you use them without |
| supplying their definitions. They fall into two classes: standard |
| macros and system-specific macros. |
| |
| @menu |
| * Standard Predefined:: Standard predefined macros. |
| * Nonstandard Predefined:: Nonstandard predefined macros. |
| @end menu |
| |
| @node Standard Predefined, Nonstandard Predefined, Predefined, Predefined |
| @subsubsection Standard Predefined Macros |
| @cindex standard predefined macros |
| |
| The standard predefined macros are available with the same meanings |
| regardless of the machine or operating system on which you are using GNU |
| C@. Their names all start and end with double underscores. Those |
| preceding @code{__GNUC__} in this table are standardized by ISO C; the |
| rest are GNU C extensions. |
| |
| @table @code |
| @item __FILE__ |
| @findex __FILE__ |
| This macro expands to the name of the current input file, in the form of |
| a C string constant. The precise name returned is the one that was |
| specified in @samp{#include} or as the input file name argument. For |
| example, @samp{"/usr/local/include/myheader.h"} is a possible expansion |
| of this macro. |
| |
| @item __LINE__ |
| @findex __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. |
| |
| This and @samp{__FILE__} 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, |
| |
| @smallexample |
| fprintf (stderr, "Internal error: " |
| "negative string length " |
| "%d at %s, line %d.", |
| length, __FILE__, __LINE__); |
| @end smallexample |
| |
| A @samp{#include} directive changes the expansions of @samp{__FILE__} |
| and @samp{__LINE__} to correspond to the included file. At the end of |
| that file, when processing resumes on the input file that contained |
| the @samp{#include} directive, the expansions of @samp{__FILE__} and |
| @samp{__LINE__} revert to the values they had before the |
| @samp{#include} (but @samp{__LINE__} is then incremented by one as |
| processing moves to the line after the @samp{#include}). |
| |
| The expansions of both @samp{__FILE__} and @samp{__LINE__} are altered |
| if a @samp{#line} directive is used. @xref{Line Control}. |
| |
| @item __DATE__ |
| @findex __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 @w{@samp{"Feb 1 1996"}}. |
| @c After reformatting the above, check that the date remains `Feb 1 1996', |
| @c all on one line, with two spaces between the `Feb' and the `1'. |
| |
| @item __TIME__ |
| @findex __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 @samp{"23:59:01"}. |
| |
| @item __STDC__ |
| @findex __STDC__ |
| This macro expands to the constant 1, to signify that this is ISO |
| Standard C@. (Whether that is actually true depends on what C compiler |
| will operate on the output from the preprocessor.) |
| |
| On some hosts, system include files use a different convention, where |
| @samp{__STDC__} is normally 0, but is 1 if the user specifies strict |
| conformance to the C Standard. The preprocessor follows the host |
| convention when processing system include files, but when processing |
| user files it follows the usual GNU C convention. |
| |
| This macro is not defined if the @samp{-traditional} option is used. |
| |
| @item __STDC_VERSION__ |
| @findex __STDC_VERSION__ |
| This macro expands to the C Standard's version number, a long integer |
| constant of the form @samp{@var{yyyy}@var{mm}L} where @var{yyyy} and |
| @var{mm} are the year and month of the Standard version. This signifies |
| which version of the C Standard the preprocessor conforms to. Like |
| @samp{__STDC__}, whether this version number is accurate for the entire |
| implementation depends on what C compiler will operate on the output |
| from the preprocessor. |
| |
| This macro is not defined if the @samp{-traditional} option is used. |
| |
| @item __GNUC__ |
| @findex __GNUC__ |
| This macro is defined if and only if this is GNU C@. This macro is |
| defined only when the entire GNU C compiler is in use; if you invoke the |
| preprocessor directly, @samp{__GNUC__} is undefined. The value |
| identifies the major version number of GNU CC (@samp{1} for GNU CC |
| version 1, which is now obsolete, and @samp{2} for version 2). |
| |
| @item __GNUC_MINOR__ |
| @findex __GNUC_MINOR__ |
| The macro contains the minor version number of the compiler. This can |
| be used to work around differences between different releases of the |
| compiler (for example, if GCC 2.6.x is known to support a feature, you |
| can test for @code{__GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 6)}). |
| |
| @item __GNUC_PATCHLEVEL__ |
| @findex __GNUC_PATCHLEVEL__ |
| This macro contains the patch level of the compiler. This can be |
| used to work around differences between different patch level releases |
| of the compiler (for example, if GCC 2.6.2 is known to contain a bug, |
| whereas GCC 2.6.3 contains a fix, and you have code which can workaround |
| the problem depending on whether the bug is fixed or not, you can test for |
| @code{__GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ > 6) || |
| (__GNUC__ == 2 && __GNUC_MINOR__ == 6 && __GNUC_PATCHLEVEL__ >= 3)}). |
| |
| @item __GNUG__ |
| @findex __GNUG__ |
| The GNU C compiler defines this when the compilation language is |
| C++; use @samp{__GNUG__} to distinguish between GNU C and GNU |
| C++. |
| |
| @item __cplusplus |
| @findex __cplusplus |
| The ISO standard for C++ requires predefining this variable. You can |
| use @samp{__cplusplus} to test whether a header is compiled by a C |
| compiler or a C++ compiler. The compiler currently uses a value of |
| @samp{1}, instead of the value @samp{199711L}, which would indicate full |
| conformance with the standard. |
| |
| @item __STRICT_ANSI__ |
| @findex __STRICT_ANSI__ |
| GNU C defines this macro if and only if the @option{-ansi} switch, or a |
| @option{-std} switch specifying strict conformance to some version of ISO C, |
| was specified when GNU C was invoked. Its definition is the null string. |
| This macro exists primarily to direct certain GNU header files not to |
| define certain traditional Unix constructs which are incompatible with |
| ISO C@. |
| |
| @item __BASE_FILE__ |
| @findex __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. |
| |
| @item __INCLUDE_LEVEL__ |
| @findex __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 @samp{#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. |
| |
| @item __VERSION__ |
| @findex __VERSION__ |
| This macro expands to a string constant which describes the version |
| number of GNU C@. The string is normally a sequence of decimal numbers |
| separated by periods, such as @samp{"2.6.0"}. |
| |
| @item __OPTIMIZE__ |
| @findex __OPTIMIZE__ |
| GNU CC defines this macro in optimizing compilations. It causes certain |
| GNU header files to define alternative macro definitions for some system |
| library functions. You should not refer to or test the definition of |
| this macro unless you make very sure that programs will execute with the |
| same effect regardless. |
| |
| @item __OPTIMIZE_SIZE__ |
| @findex __OPTIMIZE_SIZE__ |
| GNU CC defines this macro when optimizing for size with @samp{-Os}. It |
| causes certain GNU header files to define alternative macro definitions |
| for some system library functions. You should not refer to or test the |
| definition of this macro unless you make very sure that programs will |
| execute with the same effect regardless. |
| |
| @item __CHAR_UNSIGNED__ |
| @findex __CHAR_UNSIGNED__ |
| GNU C defines this macro if and only if the data type @code{char} is |
| unsigned on the target machine. It exists to cause the standard header |
| file @file{limits.h} to work correctly. You should not refer to this |
| macro yourself; instead, refer to the standard macros defined in |
| @file{limits.h}. The preprocessor uses this macro to determine whether |
| or not to sign-extend large character constants written in octal; see |
| @ref{#if Directive,,The @samp{#if} Directive}. |
| |
| @item __REGISTER_PREFIX__ |
| @findex __REGISTER_PREFIX__ |
| This macro expands to a string (not a string constant) describing the |
| prefix applied to CPU registers in assembler code. You can use it to |
| write assembler code that is usable in multiple environments. For |
| example, in the @samp{m68k-aout} environment it expands to the null |
| string, but in the @samp{m68k-coff} environment it expands to the string |
| @samp{%}. |
| |
| @item __USER_LABEL_PREFIX__ |
| @findex __USER_LABEL_PREFIX__ |
| Similar to @code{__REGISTER_PREFIX__}, but describes the prefix applied |
| to user generated labels in assembler code. For example, in the |
| @samp{m68k-aout} environment it expands to the string @samp{_}, but in |
| the @samp{m68k-coff} environment it expands to the null string. This |
| does not work with the @samp{-mno-underscores} option that the i386 |
| OSF/rose and m88k targets provide nor with the @samp{-mcall*} options of |
| the rs6000 System V Release 4 target. |
| @end table |
| |
| @node Nonstandard Predefined,, Standard Predefined, Predefined |
| @subsubsection Nonstandard Predefined Macros |
| |
| The C preprocessor normally has several predefined macros that vary |
| between machines because their purpose is to indicate what type of |
| system and machine is in use. This manual, being for all systems and |
| machines, cannot tell you exactly what their names are; instead, we |
| offer a list of some typical ones. You can use @samp{cpp -dM} to see |
| the values of predefined macros; see @ref{Invocation}. |
| |
| Some nonstandard predefined macros describe the operating system in use, |
| with more or less specificity. For example, |
| |
| @table @code |
| @item unix |
| @findex unix |
| @samp{unix} is normally predefined on all Unix systems. |
| |
| @item BSD |
| @findex BSD |
| @samp{BSD} is predefined on recent versions of Berkeley Unix |
| (perhaps only in version 4.3). |
| @end table |
| |
| Other nonstandard predefined macros describe the kind of CPU, with more or |
| less specificity. For example, |
| |
| @table @code |
| @item vax |
| @findex vax |
| @samp{vax} is predefined on Vax computers. |
| |
| @item mc68000 |
| @findex mc68000 |
| @samp{mc68000} is predefined on most computers whose CPU is a Motorola |
| 68000, 68010 or 68020. |
| |
| @item m68k |
| @findex m68k |
| @samp{m68k} is also predefined on most computers whose CPU is a 68000, |
| 68010 or 68020; however, some makers use @samp{mc68000} and some use |
| @samp{m68k}. Some predefine both names. What happens in GNU C |
| depends on the system you are using it on. |
| |
| @item M68020 |
| @findex M68020 |
| @samp{M68020} has been observed to be predefined on some systems that |
| use 68020 CPUs --- in addition to @samp{mc68000} and @samp{m68k}, which |
| are less specific. |
| |
| @item _AM29K |
| @findex _AM29K |
| @itemx _AM29000 |
| @findex _AM29000 |
| Both @samp{_AM29K} and @samp{_AM29000} are predefined for the AMD 29000 |
| CPU family. |
| |
| @item ns32000 |
| @findex ns32000 |
| @samp{ns32000} is predefined on computers which use the National |
| Semiconductor 32000 series CPU. |
| @end table |
| |
| Yet other nonstandard predefined macros describe the manufacturer of |
| the system. For example, |
| |
| @table @code |
| @item sun |
| @findex sun |
| @samp{sun} is predefined on all models of Sun computers. |
| |
| @item pyr |
| @findex pyr |
| @samp{pyr} is predefined on all models of Pyramid computers. |
| |
| @item sequent |
| @findex sequent |
| @samp{sequent} is predefined on all models of Sequent computers. |
| @end table |
| |
| These predefined symbols are not only nonstandard, they are contrary to the |
| ISO standard because their names do not start with underscores. |
| Therefore, the option @samp{-ansi} inhibits the definition of these |
| symbols. |
| |
| This tends to make @samp{-ansi} useless, since many programs depend on |
| the customary nonstandard predefined symbols. Even system header files |
| check them and will generate incorrect declarations if they do not find |
| the names that are expected. You might think that the header files |
| supplied for the Uglix computer would not need to test what machine they |
| are running on, because they can simply assume it is the Uglix; but |
| often they do, and they do so using the customary names. As a result, |
| very few C programs will compile with @samp{-ansi}. We intend to avoid |
| such problems on the GNU system. |
| |
| What, then, should you do in an ISO C program to test the type of machine |
| it will run on? |
| |
| GNU C offers a parallel series of symbols for this purpose, whose names |
| are made from the customary ones by adding @samp{__} at the beginning |
| and end. Thus, the symbol @code{__vax__} would be available on a Vax, |
| and so on. |
| |
| The set of nonstandard predefined names in the GNU C preprocessor is |
| controlled (when @code{cpp} is itself compiled) by the macro |
| @samp{CPP_PREDEFINES}, which should be a string containing @samp{-D} |
| options, separated by spaces. For example, on the Sun 3, we use the |
| following definition: |
| |
| @example |
| #define CPP_PREDEFINES "-Dmc68000 -Dsun -Dunix -Dm68k" |
| @end example |
| |
| @noindent |
| This macro is usually specified in @file{tm.h}. |
| |
| @node Stringification, Concatenation, Predefined, Macros |
| @subsection Stringification |
| |
| @cindex stringification |
| @dfn{Stringification} means turning a sequence of preprocessing tokens |
| into a string literal. For example, stringifying @samp{foo (z)} results |
| in @samp{"foo (z)"}. |
| |
| In the C preprocessor, stringification is possible when macro arguments |
| are substituted during macro expansion. When a parameter appears |
| preceded by a @samp{#} token in the replacement list of a function-like |
| macro, it indicates that both tokens should be replaced with the |
| stringification of the corresponding argument during expansion. The |
| same argument may be substituted in other places in the definition |
| without stringification if the argument name appears in those places |
| with no preceding @samp{#}. |
| |
| Here is an example of a macro definition that uses stringification: |
| |
| @smallexample |
| @group |
| #define WARN_IF(EXP) \ |
| do @{ if (EXP) \ |
| fprintf (stderr, "Warning: " #EXP "\n"); @} \ |
| while (0) |
| @end group |
| @end smallexample |
| |
| @noindent |
| Here the argument for @samp{EXP} is substituted once, as-is, into the |
| @samp{if} statement, and once, stringified, into the argument to |
| @samp{fprintf}. The @samp{do} and @samp{while (0)} are a kludge to make |
| it possible to write @samp{WARN_IF (@var{arg});}, which the resemblance |
| of @samp{WARN_IF} to a function would make C programmers want to do; see |
| @ref{Swallow Semicolon}. |
| |
| The stringification feature is limited to transforming the tokens of a |
| macro argument into a string constant: there is no way to combine the |
| argument with surrounding text and stringify it all together. The |
| example above shows how an equivalent result can be obtained in ISO |
| Standard C, using the fact that adjacent string constants are |
| concatenated by the C compiler to form a single string constant. The |
| preprocessor stringifies the actual value of @samp{EXP} into a separate |
| string constant, resulting in text like |
| |
| @smallexample |
| @group |
| do @{ if (x == 0) \ |
| fprintf (stderr, "Warning: " "x == 0" "\n"); @} \ |
| while (0) |
| @end group |
| @end smallexample |
| |
| @noindent |
| but the compiler then sees three consecutive string constants and |
| concatenates them into one, producing effectively |
| |
| @smallexample |
| do @{ if (x == 0) \ |
| fprintf (stderr, "Warning: x == 0\n"); @} \ |
| while (0) |
| @end smallexample |
| |
| Stringification in C involves more than putting double-quote characters |
| around the fragment. The preprocessor backslash-escapes the surrounding |
| quotes of string literals, and all backslashes within string and |
| character constants, in order to get a valid C string constant with the |
| proper contents. Thus, stringifying @samp{p = "foo\n";} results in |
| @samp{"p = \"foo\\n\";"}. However, backslashes that are not inside |
| string or character constants are not duplicated: @samp{\n} by itself |
| stringifies to @samp{"\n"}. |
| |
| Whitespace (including comments) in the text being stringified is handled |
| according to precise rules. All leading and trailing whitespace is |
| ignored. Any sequence of whitespace in the middle of the text is |
| converted to a single space in the stringified result. |
| |
| @node Concatenation, Undefining, Stringification, Macros |
| @subsection Concatenation |
| @cindex concatenation |
| @cindex @samp{##} |
| @dfn{Concatenation} means joining two strings into one. In the context |
| of macro expansion, concatenation refers to joining two preprocessing |
| tokens to form one. In particular, a token of a macro argument can be |
| concatenated with another argument's token or with fixed text to produce |
| a longer name. The longer name might be the name of a function, |
| variable, type, or a C keyword; it might even be the name of another |
| macro, in which case it will be expanded. |
| |
| When you define a function-like or object-like macro, you request |
| concatenation with the special operator @samp{##} in the macro's |
| replacement list. When the macro is called, any arguments are |
| substituted without performing macro expansion, every @samp{##} operator |
| is deleted, and the two tokens on either side of it are concatenated to |
| form a single token. |
| |
| 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: |
| |
| @example |
| struct command |
| @{ |
| char *name; |
| void (*function) (); |
| @}; |
| |
| struct command commands[] = |
| @{ |
| @{ "quit", quit_command@}, |
| @{ "help", help_command@}, |
| @dots{} |
| @}; |
| @end example |
| |
| 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 @samp{_command}. Here is how it is done: |
| |
| @example |
| #define COMMAND(NAME) @{ #NAME, NAME ## _command @} |
| |
| struct command commands[] = |
| @{ |
| COMMAND (quit), |
| COMMAND (help), |
| @dots{} |
| @}; |
| @end example |
| |
| The usual case of concatenation is concatenating two names (or a name |
| and a number) into a longer name. This isn't the only valid case. |
| It is also possible to concatenate two numbers (or a number and a name, |
| such as @samp{1.5} and @samp{e3}) into a number. Also, multi-character |
| operators such as @samp{+=} can be formed by concatenation. However, |
| two tokens that don't together form a valid token cannot be |
| concatenated. For example, concatenation of @samp{x} on one side and |
| @samp{+} on the other is not meaningful because those two tokens do not |
| form a valid preprocessing token when concatenated. UNDEFINED |
| |
| Keep in mind that the C preprocessor converts comments to whitespace |
| before macros are even considered. Therefore, you cannot create a |
| comment by concatenating @samp{/} and @samp{*}: the @samp{/*} sequence |
| that starts a comment is not a token, but rather the beginning of a |
| comment. You can freely use comments next to @samp{##} in a macro |
| definition, or in arguments that will be concatenated, because the |
| comments will be converted to spaces at first sight, and concatenation |
| operates on tokens and so ignores whitespace. |
| |
| @node Undefining, Redefining, Concatenation, Macros |
| @subsection Undefining Macros |
| |
| @cindex undefining macros |
| To @dfn{undefine} a macro means to cancel its definition. This is done |
| with the @samp{#undef} directive. @samp{#undef} is followed by the macro |
| name to be undefined. |
| |
| Like definition, undefinition occurs at a specific point in the source |
| file, and it applies starting from that point. The name ceases to be a |
| macro name, and from that point on it is treated by the preprocessor as |
| if it had never been a macro name. |
| |
| For example, |
| |
| @example |
| #define FOO 4 |
| x = FOO; |
| #undef FOO |
| x = FOO; |
| @end example |
| |
| @noindent |
| expands into |
| |
| @example |
| x = 4; |
| |
| x = FOO; |
| @end example |
| |
| @noindent |
| In this example, @samp{FOO} had better be a variable or function as well |
| as (temporarily) a macro, in order for the result of the expansion to be |
| valid C code. |
| |
| The same form of @samp{#undef} directive will cancel definitions with |
| arguments or definitions that don't expect arguments. The @samp{#undef} |
| directive has no effect when used on a name not currently defined as a |
| macro. |
| |
| @node Redefining, Poisoning, Undefining, Macros |
| @subsection Redefining Macros |
| |
| @cindex redefining macros |
| @dfn{Redefining} a macro means defining (with @samp{#define}) a name that |
| is already defined as a macro. |
| |
| A redefinition is trivial if the new definition is transparently |
| identical to the old one. You probably wouldn't deliberately write a |
| trivial redefinition, but they can happen automatically when a header |
| file is included more than once (@pxref{Header Files}), so they are |
| accepted silently and without effect. |
| |
| Nontrivial redefinition is considered likely to be an error, so it |
| provokes a warning message from the preprocessor. However, sometimes it |
| is useful to change the definition of a macro in mid-compilation. You |
| can inhibit the warning by undefining the macro with @samp{#undef} |
| before the second definition. |
| |
| In order for a redefinition to be trivial, the parameter names must |
| match and be in the same order, and the new replacement list must |
| exactly match the one already in effect, with two possible exceptions: |
| |
| @itemize @bullet |
| @item |
| Whitespace may be added or deleted at the beginning or the end of the |
| replacement list. In a sense this is vacuous, since strictly such |
| whitespace doesn't form part of the macro's expansion. |
| |
| @item |
| Between tokens in the expansion, any two forms of whitespace are |
| considered equivalent. In particular, whitespace may not be eliminated |
| entirely, nor may it be added where there previously wasn't any. |
| @end itemize |
| |
| Recall that a comment counts as whitespace. |
| |
| As a particular case of the above, you may not redefine an object-like |
| macro as a function-like macro, and vice-versa. |
| |
| @node Poisoning, Macro Pitfalls, Redefining, Macros |
| @subsection Poisoning Macros |
| @cindex poisoning macros |
| @findex #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, the @samp{#pragma GCC poison} directive can be used. |
| @samp{#pragma GCC poison} is followed by a list of identifiers to |
| poison, and takes effect for the rest of the source. You cannot |
| @samp{#undef} a poisoned identifier or test to see if it's defined with |
| @samp{#ifdef}. |
| |
| For example, |
| |
| @example |
| #pragma GCC poison printf sprintf fprintf |
| sprintf(some_string, "hello"); |
| @end example |
| |
| @noindent |
| will produce an error. |
| |
| Note, if the poisoned identifier appears through the result of macro |
| expansion it @emph{won't} cause an error. So if you poison an |
| identifier you need not worry about system headers defining macros that |
| use it. |
| |
| For example, |
| |
| @example |
| #define strrchr rindex |
| #pragma GCC poison rindex |
| strrchr(some_string, 'h'); |
| @end example |
| |
| @noindent |
| will not produce an error. |
| |
| @node Macro Pitfalls,, Poisoning, Macros |
| @subsection Pitfalls and Subtleties of Macros |
| @cindex problems with macros |
| @cindex pitfalls of macros |
| |
| 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 |
| counterintuitive consequences that you must watch out for. |
| |
| @menu |
| * Misnesting:: Macros can contain unmatched parentheses. |
| * Macro Parentheses:: Why apparently superfluous parentheses |
| may be necessary to avoid incorrect grouping. |
| * Swallow Semicolon:: Macros that look like functions |
| but expand into compound statements. |
| * Side Effects:: Unsafe macros that cause trouble when |
| arguments contain side effects. |
| * Self-Reference:: Macros whose definitions use the macros' own names. |
| * Argument Prescan:: Arguments are checked for macro calls before they |
| are substituted. |
| * Cascaded Macros:: Macros whose definitions use other macros. |
| * Newlines in Args:: Sometimes line numbers get confused. |
| @end menu |
| |
| @node Misnesting, Macro Parentheses, Macro Pitfalls, Macro Pitfalls |
| @subsubsection Improperly Nested Constructs |
| |
| Recall that 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, |
| |
| @example |
| #define double(x) (2*(x)) |
| #define call_with_1(x) x(1) |
| @end example |
| |
| @noindent |
| would expand @samp{call_with_1 (double)} into @samp{(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, |
| |
| @example |
| #define strange(file) fprintf (file, "%s %d", |
| @dots{} |
| strange(stderr) p, 35) |
| @end example |
| |
| @noindent |
| This bizarre example expands to @samp{fprintf (stderr, "%s %d", p, 35)}! |
| |
| @node Macro Parentheses, Swallow Semicolon, Misnesting, Macro Pitfalls |
| @subsubsection Unintended Grouping of Arithmetic |
| @cindex parentheses in macro bodies |
| |
| 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, |
| |
| @example |
| #define ceil_div(x, y) (x + y - 1) / y |
| @end example |
| |
| @noindent |
| whose purpose is to divide, rounding up. (One use for this operation is |
| to compute how many @samp{int} objects are needed to hold a certain |
| number of @samp{char} objects.) Then suppose it is used as follows: |
| |
| @example |
| a = ceil_div (b & c, sizeof (int)); |
| @end example |
| |
| @noindent |
| This expands into |
| |
| @example |
| a = (b & c + sizeof (int) - 1) / sizeof (int); |
| @end example |
| |
| @noindent |
| which does not do what is intended. The operator-precedence rules of |
| C make it equivalent to this: |
| |
| @example |
| a = (b & (c + sizeof (int) - 1)) / sizeof (int); |
| @end example |
| |
| @noindent |
| What we want is this: |
| |
| @example |
| a = ((b & c) + sizeof (int) - 1)) / sizeof (int); |
| @end example |
| |
| @noindent |
| Defining the macro as |
| |
| @example |
| #define ceil_div(x, y) ((x) + (y) - 1) / (y) |
| @end example |
| |
| @noindent |
| provides the desired result. |
| |
| Unintended grouping can result in another way. Consider @samp{sizeof |
| ceil_div(1, 2)}. That has the appearance of a C expression that would |
| compute the size of the type of @samp{ceil_div (1, 2)}, but in fact it |
| means something very different. Here is what it expands to: |
| |
| @example |
| sizeof ((1) + (2) - 1) / (2) |
| @end example |
| |
| @noindent |
| This would take the size of an integer and divide it by two. The |
| precedence rules have put the division outside the @samp{sizeof} when it |
| was intended to be inside. |
| |
| Parentheses around the entire macro definition can prevent such |
| problems. Here, then, is the recommended way to define @samp{ceil_div}: |
| |
| @example |
| #define ceil_div(x, y) (((x) + (y) - 1) / (y)) |
| @end example |
| |
| @node Swallow Semicolon, Side Effects, Macro Parentheses, Macro Pitfalls |
| @subsubsection Swallowing the Semicolon |
| |
| @cindex semicolons (after macro calls) |
| 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 @samp{p} says where to find it) across whitespace |
| characters: |
| |
| @example |
| #define SKIP_SPACES(p, limit) \ |
| @{ register char *lim = (limit); \ |
| while (p != lim) @{ \ |
| if (*p++ != ' ') @{ \ |
| p--; break; @}@}@} |
| @end example |
| |
| @noindent |
| Here backslash-newline is used to split the macro definition, which must |
| be a single logical line, so that it resembles the way such C code would |
| be laid out if not part of a macro definition. |
| |
| A call to this macro might be @samp{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 |
| @samp{SKIP_SPACES (p, lim);} |
| |
| This can cause trouble before @samp{else} statements, because the |
| semicolon is actually a null statement. Suppose you write |
| |
| @example |
| if (*p != 0) |
| SKIP_SPACES (p, lim); |
| else @dots{} |
| @end example |
| |
| @noindent |
| The presence of two statements --- the compound statement and a null |
| statement --- in between the @samp{if} condition and the @samp{else} |
| makes invalid C code. |
| |
| The definition of the macro @samp{SKIP_SPACES} can be altered to solve |
| this problem, using a @samp{do @dots{} while} statement. Here is how: |
| |
| @example |
| #define SKIP_SPACES(p, limit) \ |
| do @{ register char *lim = (limit); \ |
| while (p != lim) @{ \ |
| if (*p++ != ' ') @{ \ |
| p--; break; @}@}@} \ |
| while (0) |
| @end example |
| |
| Now @samp{SKIP_SPACES (p, lim);} expands into |
| |
| @example |
| do @{@dots{}@} while (0); |
| @end example |
| |
| @noindent |
| which is one statement. |
| |
| @node Side Effects, Self-Reference, Swallow Semicolon, Macro Pitfalls |
| @subsubsection Duplication of Side Effects |
| |
| @cindex side effects (in macro arguments) |
| @cindex unsafe macros |
| Many C programs define a macro @samp{min}, for ``minimum'', like this: |
| |
| @example |
| #define min(X, Y) ((X) < (Y) ? (X) : (Y)) |
| @end example |
| |
| When you use this macro with an argument containing a side effect, |
| as shown here, |
| |
| @example |
| next = min (x + y, foo (z)); |
| @end example |
| |
| @noindent |
| it expands as follows: |
| |
| @example |
| next = ((x + y) < (foo (z)) ? (x + y) : (foo (z))); |
| @end example |
| |
| @noindent |
| where @samp{x + y} has been substituted for @samp{X} and @samp{foo (z)} |
| for @samp{Y}. |
| |
| The function @samp{foo} is used only once in the statement as it appears |
| in the program, but the expression @samp{foo (z)} has been substituted |
| twice into the macro expansion. As a result, @samp{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 @samp{min} is an @dfn{unsafe} macro. |
| |
| The best solution to this problem is to define @samp{min} in a way that |
| computes the value of @samp{foo (z)} only once. The C language offers |
| no standard way to do this, but it can be done with GNU C extensions as |
| follows: |
| |
| @example |
| #define min(X, Y) \ |
| (@{ typeof (X) __x = (X), __y = (Y); \ |
| (__x < __y) ? __x : __y; @}) |
| @end example |
| |
| If you do not wish to use GNU C extensions, the only solution is to be |
| careful when @emph{using} the macro @samp{min}. For example, you can |
| calculate the value of @samp{foo (z)}, save it in a variable, and use |
| that variable in @samp{min}: |
| |
| @example |
| #define min(X, Y) ((X) < (Y) ? (X) : (Y)) |
| @dots{} |
| @{ |
| int tem = foo (z); |
| next = min (x + y, tem); |
| @} |
| @end example |
| |
| @noindent |
| (where we assume that @samp{foo} returns type @samp{int}). |
| |
| @node Self-Reference, Argument Prescan, Side Effects, Macro Pitfalls |
| @subsubsection Self-Referential Macros |
| |
| @cindex self-reference |
| A @dfn{self-referential} macro is one whose name appears in its |
| definition. A special feature of ISO Standard C is that the |
| self-reference is not considered a macro call. It is passed into the |
| preprocessor output unchanged. |
| |
| Let's consider an example: |
| |
| @example |
| #define foo (4 + foo) |
| @end example |
| |
| @noindent |
| where @samp{foo} is also a variable in your program. |
| |
| Following the ordinary rules, each reference to @samp{foo} will expand |
| into @samp{(4 + foo)}; then this will be rescanned and will expand into |
| @samp{(4 + (4 + foo))}; and so on until it causes a fatal error (memory |
| full) in the preprocessor. |
| |
| However, the special rule about self-reference cuts this process short |
| after one step, at @samp{(4 + foo)}. Therefore, this macro definition |
| has the possibly useful effect of causing the program to add 4 to the |
| value of @samp{foo} wherever @samp{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 @samp{foo} is a variable will |
| not expect that it is a macro as well. The reader will come across the |
| identifier @samp{foo} in the program and think its value should be that |
| of the variable @samp{foo}, whereas in fact the value is four greater. |
| |
| The special rule for self-reference applies also to @dfn{indirect} |
| self-reference. This is the case where a macro @var{x} expands to use a |
| macro @samp{y}, and the expansion of @samp{y} refers to the macro |
| @samp{x}. The resulting reference to @samp{x} comes indirectly from the |
| expansion of @samp{x}, so it is a self-reference and is not further |
| expanded. Thus, after |
| |
| @example |
| #define x (4 + y) |
| #define y (2 * x) |
| @end example |
| |
| @noindent |
| @samp{x} would expand into @samp{(4 + (2 * x))}. Clear? |
| |
| Suppose @samp{y} is used elsewhere, not from the definition of @samp{x}. |
| Then the use of @samp{x} in the expansion of @samp{y} is not a |
| self-reference because @samp{x} is not ``in progress''. So it does |
| expand. However, the expansion of @samp{x} contains a reference to |
| @samp{y}, and that is an indirect self-reference now because @samp{y} is |
| ``in progress''. The result is that @samp{y} expands to @samp{(2 * (4 + |
| y))}. |
| |
| This behavior is specified by the ISO C standard, so you may need to |
| understand it. |
| |
| @node Argument Prescan, Cascaded Macros, Self-Reference, Macro Pitfalls |
| @subsubsection Separate Expansion of Macro Arguments |
| @cindex expansion of arguments |
| @cindex macro argument expansion |
| @cindex prescan of macro arguments |
| |
| We have explained that the expansion of a macro, including the substituted |
| arguments, is re-scanned for macro calls to be expanded. |
| |
| What really happens is more subtle: first each argument is scanned |
| separately for macro calls. Then the resulting tokens are substituted |
| into the macro body to produce the macro expansion, and the macro |
| expansion is scanned again for macros to expand. |
| |
| The result is that the arguments are scanned @emph{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 |
| (@pxref{Self-Reference}): 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. |
| |
| The prescan is not done when an argument is stringified or concatenated. |
| Thus, |
| |
| @example |
| #define str(s) #s |
| #define foo 4 |
| str (foo) |
| @end example |
| |
| @noindent |
| expands to @samp{"foo"}. Once more, prescan has been prevented from |
| having any noticeable effect. |
| |
| More precisely, stringification and concatenation use the argument |
| tokens as given without initially scanning for macros. The same |
| argument would be used in expanded form if it is substituted elsewhere |
| without stringification or concatenation. |
| |
| @example |
| #define str(s) #s lose(s) |
| #define foo 4 |
| str (foo) |
| @end example |
| |
| expands to @samp{"foo" lose(4)}. |
| |
| You might now ask, ``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: |
| |
| @itemize @bullet |
| @item |
| Nested calls to a macro. |
| |
| @item |
| Macros that call other macros that stringify or concatenate. |
| |
| @item |
| Macros whose expansions contain unshielded commas. |
| @end itemize |
| |
| We say that @dfn{nested} calls to a macro occur when a macro's argument |
| contains a call to that very macro. For example, if @samp{f} is a macro |
| that expects one argument, @samp{f (f (1))} is a nested pair of calls to |
| @samp{f}. The desired expansion is made by expanding @samp{f (1)} and |
| substituting that into the definition of @samp{f}. The prescan causes |
| the expected result to happen. Without the prescan, @samp{f (1)} itself |
| would be substituted as an argument, and the inner use of @samp{f} would |
| appear during the main scan as an indirect self-reference and would not |
| be expanded. Here, the prescan cancels an undesirable side effect (in |
| the medical, not computational, sense of the term) of the special rule |
| for self-referential macros. |
| |
| Prescan causes trouble in certain other cases of nested macro calls. |
| Here is an example: |
| |
| @example |
| #define foo a,b |
| #define bar(x) lose(x) |
| #define lose(x) (1 + (x)) |
| |
| bar(foo) |
| @end example |
| |
| @noindent |
| We would like @samp{bar(foo)} to turn into @samp{(1 + (foo))}, which |
| would then turn into @samp{(1 + (a,b))}. Instead, @samp{bar(foo)} |
| expands into @samp{lose(a,b)}, and you get an error because @code{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: |
| |
| @example |
| #define foo (a,b) |
| #define bar(x) lose((x)) |
| @end example |
| |
| The problem is more serious when the operands of the macro are not |
| expressions; for example, when they are statements. Then parentheses |
| are unacceptable because they would make for invalid C code: |
| |
| @example |
| #define foo @{ int a, b; @dots{} @} |
| @end example |
| |
| @noindent |
| In GNU C you can shield the commas using the @samp{(@{@dots{}@})} |
| construct which turns a compound statement into an expression: |
| |
| @example |
| #define foo (@{ int a, b; @dots{} @}) |
| @end example |
| |
| Or you can rewrite the macro definition to avoid such commas: |
| |
| @example |
| #define foo @{ int a; int b; @dots{} @} |
| @end example |
| |
| There is also one case where prescan is useful. It is possible to use |
| prescan to expand an argument and then stringify it --- if you use two |
| levels of macros. Let's add a new macro @samp{xstr} to the example |
| shown above: |
| |
| @example |
| #define xstr(s) str(s) |
| #define str(s) #s |
| #define foo 4 |
| xstr (foo) |
| @end example |
| |
| This expands into @samp{"4"}, not @samp{"foo"}. The reason for the |
| difference is that the argument of @samp{xstr} is expanded at prescan |
| (because @samp{xstr} does not specify stringification or concatenation |
| of the argument). The result of prescan then forms the argument for |
| @samp{str}. @samp{str} uses its argument without prescan because it |
| performs stringification; but it cannot prevent or undo the prescanning |
| already done by @samp{xstr}. |
| |
| @node Cascaded Macros, Newlines in Args, Argument Prescan, Macro Pitfalls |
| @subsubsection Cascaded Use of Macros |
| |
| @cindex cascaded macros |
| @cindex macro body uses macro |
| A @dfn{cascade} of macros is when one macro's body contains a reference |
| to another macro. This is very common practice. For example, |
| |
| @example |
| #define BUFSIZE 1020 |
| #define TABLESIZE BUFSIZE |
| @end example |
| |
| This is not at all the same as defining @samp{TABLESIZE} to be |
| @samp{1020}. The @samp{#define} for @samp{TABLESIZE} uses exactly the |
| body you specify --- in this case, @samp{BUFSIZE} --- and does not check |
| to see whether it too is the name of a macro. |
| |
| It's only when you @emph{use} @samp{TABLESIZE} that the result of its |
| expansion is checked for more macro names. |
| |
| This makes a difference if you change the definition of @samp{BUFSIZE} |
| at some point in the source file. @samp{TABLESIZE}, defined as shown, |
| will always expand using the definition of @samp{BUFSIZE} that is |
| currently in effect: |
| |
| @example |
| #define BUFSIZE 1020 |
| #define TABLESIZE BUFSIZE |
| #undef BUFSIZE |
| #define BUFSIZE 37 |
| @end example |
| |
| @noindent |
| Now @samp{TABLESIZE} expands (in two stages) to @samp{37}. (The |
| @samp{#undef} is to prevent any warning about the nontrivial |
| redefinition of @code{BUFSIZE}.) |
| |
| @node Newlines in Args,, Cascaded Macros, Macro Pitfalls |
| @subsection Newlines in Macro Arguments |
| @cindex newlines in macro arguments |
| |
| The invocation of a function-like macro can extend over many logical |
| lines. The ISO C standard requires that newlines within a macro |
| invocation be treated as ordinary whitespace. This means that when the |
| expansion of a function-like macro replaces its invocation, it appears |
| on the same line as the macro name did. 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: |
| |
| @example |
| #define ignore_second_arg(a,b,c) a; c |
| |
| ignore_second_arg (foo (), |
| ignored (), |
| syntax error); |
| @end example |
| |
| @noindent |
| The syntax error triggered by the tokens @samp{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. |
| |
| @node Conditionals, Assertions, Macros, Top |
| @section Conditionals |
| |
| @cindex conditionals |
| In a macro processor, a @dfn{conditional} is a directive that allows a |
| part of the program to be ignored during compilation, on some |
| conditions. In the C preprocessor, a conditional can test either an |
| arithmetic expression or whether a name is defined as a macro. |
| |
| A conditional in the C preprocessor resembles in some ways an @samp{if} |
| statement in C, but it is important to understand the difference between |
| them. The condition in an @samp{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. |
| |
| @menu |
| * Uses: Conditional Uses. What conditionals are for. |
| * Syntax: Conditional Syntax. How conditionals are written. |
| * Deletion: Deleted Code. Making code into a comment. |
| * Macros: Conditionals-Macros. Why conditionals are used with macros. |
| * Errors: #error Directive. Detecting inconsistent compilation parameters. |
| @end menu |
| |
| @node Conditional Uses |
| @subsection Why Conditionals are Used |
| |
| Generally there are three kinds of reason to use a conditional. |
| |
| @itemize @bullet |
| @item |
| 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 library routines that do not exist on the |
| other system. When this happens, it is not enough to avoid executing |
| the invalid code: merely having it in the program makes it impossible to |
| link the program and run it. With a preprocessing conditional, the |
| offending code can be effectively excised from the program when it is |
| not valid. |
| |
| @item |
| You may want to be able to compile the same source file into two |
| different programs. Sometimes the difference between the programs is |
| that one makes frequent time-consuming consistency checks on its |
| intermediate data, or prints the values of those data for debugging, |
| while the other does not. |
| |
| @item |
| A conditional whose condition is always false is a good way to exclude |
| code from the program but keep it as a sort of comment for future |
| reference. |
| @end itemize |
| |
| Most simple programs that are intended to run on only one machine will |
| not need to use preprocessing conditionals. |
| |
| @node Conditional Syntax |
| @subsection Syntax of Conditionals |
| |
| @findex #if |
| A conditional in the C preprocessor begins with a @dfn{conditional |
| directive}: @samp{#if}, @samp{#ifdef} or @samp{#ifndef}. |
| @xref{Conditionals-Macros}, for information on @samp{#ifdef} and |
| @samp{#ifndef}; only @samp{#if} is explained here. |
| |
| @menu |
| * If: #if Directive. Basic conditionals using @samp{#if} and @samp{#endif}. |
| * Else: #else Directive. Including some text if the condition fails. |
| * Elif: #elif Directive. Testing several alternative possibilities. |
| @end menu |
| |
| @node #if Directive |
| @subsubsection The @samp{#if} Directive |
| |
| The @samp{#if} directive in its simplest form consists of |
| |
| @example |
| #if @var{expression} |
| @var{controlled text} |
| #endif /* @var{expression} */ |
| @end example |
| |
| The comment following the @samp{#endif} is not required, but it is a |
| good practice because it helps people match the @samp{#endif} to the |
| corresponding @samp{#if}. Such comments should always be used, except |
| in short conditionals that are not nested. In fact, you can put |
| anything at all after the @samp{#endif} and it will be ignored by the |
| GNU C preprocessor, but only comments are acceptable in ISO Standard C@. |
| |
| @var{expression} is a C expression of integer type, subject to stringent |
| restrictions. It may contain |
| |
| @itemize @bullet |
| @item |
| Integer constants, which are all regarded as @code{long} or |
| @code{unsigned long}. |
| |
| @item |
| Character constants, which are interpreted according to the character |
| set and conventions of the machine and operating system on which the |
| preprocessor is running. The GNU C preprocessor uses the C data type |
| @samp{char} for these character constants; therefore, whether some |
| character codes are negative is determined by the C compiler used to |
| compile the preprocessor. If it treats @samp{char} as signed, then |
| character codes large enough to set the sign bit will be considered |
| negative; otherwise, no character code is considered negative. |
| |
| @item |
| Arithmetic operators for addition, subtraction, multiplication, |
| division, bitwise operations, shifts, comparisons, and logical |
| operations (@samp{&&} and @samp{||}). The latter two obey the usual |
| short-circuiting rules of standard C. |
| |
| @item |
| Identifiers that are not macros, which are all treated as zero(!). |
| |
| @item |
| Macro calls. All macro calls in the expression are expanded before |
| actual computation of the expression's value begins. |
| @end itemize |
| |
| Note that @samp{sizeof} operators and @code{enum}-type values are not |
| allowed. @code{enum}-type values, like all other identifiers that are |
| not taken as macro calls and expanded, are treated as zero. |
| |
| The @var{controlled text} inside of a conditional can include |
| preprocessing directives. Then the directives inside the conditional |
| are obeyed only if that branch of the conditional succeeds. The text |
| can also contain other conditional groups. However, the @samp{#if} and |
| @samp{#endif} directives must balance. |
| |
| @node #else Directive |
| @subsubsection The @samp{#else} Directive |
| |
| @findex #else |
| The @samp{#else} directive can be added to a conditional to provide |
| alternative text to be used if the condition is false. This is what |
| it looks like: |
| |
| @example |
| #if @var{expression} |
| @var{text-if-true} |
| #else /* Not @var{expression} */ |
| @var{text-if-false} |
| #endif /* Not @var{expression} */ |
| @end example |
| |
| If @var{expression} is nonzero, and thus the @var{text-if-true} is |
| active, then @samp{#else} acts like a failing conditional and the |
| @var{text-if-false} is ignored. Conversely, if the @samp{#if} |
| conditional fails, the @var{text-if-false} is considered included. |
| |
| @node #elif Directive |
| @subsubsection The @samp{#elif} Directive |
| |
| @findex #elif |
| One common case of nested conditionals is used to check for more than two |
| possible alternatives. For example, you might have |
| |
| @example |
| #if X == 1 |
| @dots{} |
| #else /* X != 1 */ |
| #if X == 2 |
| @dots{} |
| #else /* X != 2 */ |
| @dots{} |
| #endif /* X != 2 */ |
| #endif /* X != 1 */ |
| @end example |
| |
| Another conditional directive, @samp{#elif}, allows this to be |
| abbreviated as follows: |
| |
| @example |
| #if X == 1 |
| @dots{} |
| #elif X == 2 |
| @dots{} |
| #else /* X != 2 and X != 1*/ |
| @dots{} |
| #endif /* X != 2 and X != 1*/ |
| @end example |
| |
| @samp{#elif} stands for ``else if''. Like @samp{#else}, it goes in the |
| middle of a @samp{#if}-@samp{#endif} pair and subdivides it; it does not |
| require a matching @samp{#endif} of its own. Like @samp{#if}, the |
| @samp{#elif} directive includes an expression to be tested. |
| |
| The text following the @samp{#elif} is processed only if the original |
| @samp{#if}-condition failed and the @samp{#elif} condition succeeds. |
| More than one @samp{#elif} can go in the same @samp{#if}-@samp{#endif} |
| group. Then the text after each @samp{#elif} is processed only if the |
| @samp{#elif} condition succeeds after the original @samp{#if} and any |
| previous @samp{#elif} directives within it have failed. @samp{#else} is |
| equivalent to @samp{#elif 1}, and @samp{#else} is allowed after any |
| number of @samp{#elif} directives, but @samp{#elif} may not follow |
| @samp{#else}. |
| |
| @node Deleted Code |
| @subsection Keeping Deleted Code for Future Reference |
| @cindex commenting out code |
| |
| If you replace or delete a part of the program but want to keep the old |
| code around as a comment for future reference, the easy way to do this |
| is to put @samp{#if 0} before it and @samp{#endif} after it. This is |
| better than using comment delimiters @samp{/*} and @samp{*/} since those |
| won't work if the code already contains comments (C comments do not |
| nest). |
| |
| This works even if the code being turned off contains conditionals, but |
| they must be entire conditionals (balanced @samp{#if} and @samp{#endif}). |
| |
| Conversely, do not use @samp{#if 0} for comments which are not C code. |
| Use the comment delimiters @samp{/*} and @samp{*/} instead. The |
| interior of @samp{#if 0} must consist of complete tokens; in particular, |
| single-quote characters must balance. Comments often contain unbalanced |
| single-quote characters (known in English as apostrophes). These |
| confuse @samp{#if 0}. They do not confuse @samp{/*}. |
| |
| @node Conditionals-Macros |
| @subsection Conditionals and Macros |
| |
| Conditionals are useful in connection with macros or assertions, because |
| those are the only ways that an expression's value can vary from one |
| compilation to another. A @samp{#if} directive whose expression uses no |
| macros or assertions is equivalent to @samp{#if 1} or @samp{#if 0}; you |
| might as well determine which one, by computing the value of the |
| expression yourself, and then simplify the program. |
| |
| For example, here is a conditional that tests the expression |
| @samp{BUFSIZE == 1020}, where @samp{BUFSIZE} must be a macro. |
| |
| @example |
| #if BUFSIZE == 1020 |
| printf ("Large buffers!\n"); |
| #endif /* BUFSIZE is large */ |
| @end example |
| |
| (Programmers often wish they could test the size of a variable or data |
| type in @samp{#if}, but this does not work. The preprocessor does not |
| understand @code{sizeof}, or typedef names, or even the type keywords |
| such as @code{int}.) |
| |
| @findex defined |
| The special operator @samp{defined} is used in @samp{#if} and |
| @samp{#elif} expressions to test whether a certain name is defined as a |
| macro. Either @samp{defined @var{name}} or @samp{defined (@var{name})} |
| is an expression whose value is 1 if @var{name} is defined as macro at |
| the current point in the program, and 0 otherwise. To the |
| @samp{defined} operator it makes no difference what the definition of |
| the macro is; all that matters is whether there is a definition. Thus, |
| for example,@refill |
| |
| @example |
| #if defined (vax) || defined (ns16000) |
| @end example |
| |
| @noindent |
| would succeed if either of the names @samp{vax} and @samp{ns16000} is |
| defined as a macro. You can test the same condition using assertions |
| (@pxref{Assertions}), like this: |
| |
| @example |
| #if #cpu (vax) || #cpu (ns16000) |
| @end example |
| |
| If a macro is defined and later undefined with @samp{#undef}, subsequent |
| use of the @samp{defined} operator returns 0, because the name is no |
| longer defined. If the macro is defined again with another |
| @samp{#define}, @samp{defined} will recommence returning 1. |
| |
| If the @samp{defined} operator appears as a result of a macro expansion, |
| the C standard says the behavior is undefined. GNU cpp treats it as a |
| genuine @samp{defined} operator and evaluates it normally. It will warn |
| wherever your code uses this feature if you use the command-line option |
| @samp{-pedantic}, since other compilers may handle it differently. |
| |
| @findex #ifdef |
| @findex #ifndef |
| Conditionals that test whether a single macro is defined are very common, |
| so there are two special short conditional directives for this case. |
| |
| @table @code |
| @item #ifdef @var{name} |
| is equivalent to @samp{#if defined (@var{name})}. |
| |
| @item #ifndef @var{name} |
| is equivalent to @samp{#if ! defined (@var{name})}. |
| @end table |
| |
| Macro definitions can vary between compilations for several reasons. |
| |
| @itemize @bullet |
| @item |
| Some macros are predefined on each kind of machine. For example, on a |
| Vax, the name @samp{vax} is a predefined macro. On other machines, it |
| would not be defined. |
| |
| @item |
| Many more macros are defined by system header files. Different systems |
| and machines define different macros, or give them different values. It |
| is useful to test these macros with conditionals to avoid using a system |
| feature on a machine where it is not implemented. |
| |
| @item |
| Macros are a common way of allowing users to customize a program for |
| different machines or applications. For example, the macro |
| @samp{BUFSIZE} might be defined in a configuration file for your program |
| that is included as a header file in each source file. You would use |
| @samp{BUFSIZE} in a preprocessing conditional in order to generate |
| different code depending on the chosen configuration. |
| |
| @item |
| Macros can be defined or undefined with @samp{-D} and @samp{-U} command |
| options when you compile the program. You can arrange to compile the |
| same source file into two different programs by choosing a macro name to |
| specify which program you want, writing conditionals to test whether or |
| how this macro is defined, and then controlling the state of the macro |
| with compiler command options. @xref{Invocation}. |
| @end itemize |
| |
| @ifinfo |
| Assertions are usually predefined, but can be defined with preprocessor |
| directives or command-line options. |
| @end ifinfo |
| |
| @node #error Directive |
| @subsection The @samp{#error} and @samp{#warning} Directives |
| |
| @findex #error |
| The directive @samp{#error} causes the preprocessor to report a fatal |
| error. The tokens forming the rest of the line following @samp{#error} |
| are used as the error message, and not macro-expanded. Internal |
| whitespace sequences are each replaced with a single space. The line |
| must consist of complete tokens. |
| |
| You would use @samp{#error} inside of a conditional that detects a |
| combination of parameters which you know the program does not properly |
| support. For example, if you know that the program will not run |
| properly on a Vax, you might write |
| |
| @smallexample |
| @group |
| #ifdef __vax__ |
| #error "Won't work on Vaxen. See comments at get_last_object." |
| #endif |
| @end group |
| @end smallexample |
| |
| @noindent |
| @xref{Nonstandard Predefined}, for why this works. |
| |
| If you have several configuration parameters that must be set up by |
| the installation in a consistent way, you can use conditionals to detect |
| an inconsistency and report it with @samp{#error}. For example, |
| |
| @smallexample |
| #if HASH_TABLE_SIZE % 2 == 0 || HASH_TABLE_SIZE % 3 == 0 \ |
| || HASH_TABLE_SIZE % 5 == 0 |
| #error HASH_TABLE_SIZE should not be divisible by a small prime |
| #endif |
| @end smallexample |
| |
| @findex #warning |
| The directive @samp{#warning} is like the directive @samp{#error}, but |
| causes the preprocessor to issue a warning and continue preprocessing. |
| The tokens following @samp{#warning} are used as the warning message, |
| and not macro-expanded. |
| |
| You might use @samp{#warning} in obsolete header files, with a message |
| directing the user to the header file which should be used instead. |
| |
| @node Assertions, Line Control, Conditionals, Top |
| @section Assertions |
| @cindex assertions |
| @dfn{Assertions} are a more systematic alternative to macros in writing |
| conditionals to test what sort of computer or system the compiled |
| program will run on. Assertions are usually predefined, but you can |
| define them with preprocessing directives or command-line options. |
| |
| @cindex predicates |
| The macros traditionally used to describe the type of target are not |
| classified in any way according to which question they answer; they may |
| indicate a hardware architecture, a particular hardware model, an |
| operating system, a particular version of an operating system, or |
| specific configuration options. These are jumbled together in a single |
| namespace. In contrast, each assertion consists of a named question and |
| an answer. The question is usually called the @dfn{predicate}. An |
| assertion looks like this: |
| |
| @example |
| #@var{predicate} (@var{answer}) |
| @end example |
| |
| @noindent |
| You must use a properly formed identifier for @var{predicate}. The |
| value of @var{answer} can be any sequence of words; all characters are |
| significant except for leading and trailing whitespace, and differences |
| in internal whitespace sequences are ignored. (This is similar to the |
| rules governing macro redefinition.) Thus, @samp{x + y} is different |
| from @samp{x+y} but equivalent to @samp{ x + y }. @samp{)} is not |
| allowed in an answer. |
| |
| @cindex testing predicates |
| Here is a conditional to test whether the answer @var{answer} is asserted |
| for the predicate @var{predicate}: |
| |
| @example |
| #if #@var{predicate} (@var{answer}) |
| @end example |
| |
| @noindent |
| There may be more than one answer asserted for a given predicate. If |
| you omit the answer, you can test whether @emph{any} answer is asserted |
| for @var{predicate}: |
| |
| @example |
| #if #@var{predicate} |
| @end example |
| |
| @findex #system |
| @findex #machine |
| @findex #cpu |
| Most of the time, the assertions you test will be predefined assertions. |
| GNU C provides three predefined predicates: @code{system}, @code{cpu}, |
| and @code{machine}. @code{system} is for assertions about the type of |
| software, @code{cpu} describes the type of computer architecture, and |
| @code{machine} gives more information about the computer. For example, |
| on a GNU system, the following assertions would be true: |
| |
| @example |
| #system (gnu) |
| #system (mach) |
| #system (mach 3) |
| #system (mach 3.@var{subversion}) |
| #system (hurd) |
| #system (hurd @var{version}) |
| @end example |
| |
| @noindent |
| and perhaps others. The alternatives with |
| more or less version information let you ask more or less detailed |
| questions about the type of system software. |
| |
| On a Unix system, you would find @code{#system (unix)} and perhaps one of: |
| @code{#system (aix)}, @code{#system (bsd)}, @code{#system (hpux)}, |
| @code{#system (lynx)}, @code{#system (mach)}, @code{#system (posix)}, |
| @code{#system (svr3)}, @code{#system (svr4)}, or @code{#system (xpg4)} |
| with possible version numbers following. |
| |
| Other values for @code{system} are @code{#system (mvs)} |
| and @code{#system (vms)}. |
| |
| @strong{Portability note:} Many Unix C compilers provide only one answer |
| for the @code{system} assertion: @code{#system (unix)}, if they support |
| assertions at all. This is less than useful. |
| |
| An assertion with a multi-word answer is completely different from several |
| assertions with individual single-word answers. For example, the presence |
| of @code{system (mach 3.0)} does not mean that @code{system (3.0)} is true. |
| It also does not directly imply @code{system (mach)}, but in GNU C, that |
| last will normally be asserted as well. |
| |
| The current list of possible assertion values for @code{cpu} is: |
| @code{#cpu (a29k)}, @code{#cpu (alpha)}, @code{#cpu (arm)}, @code{#cpu |
| (clipper)}, @code{#cpu (convex)}, @code{#cpu (elxsi)}, @code{#cpu |
| (tron)}, @code{#cpu (h8300)}, @code{#cpu (i370)}, @code{#cpu (i386)}, |
| @code{#cpu (i860)}, @code{#cpu (i960)}, @code{#cpu (m68k)}, @code{#cpu |
| (m88k)}, @code{#cpu (mips)}, @code{#cpu (ns32k)}, @code{#cpu (hppa)}, |
| @code{#cpu (pyr)}, @code{#cpu (ibm032)}, @code{#cpu (rs6000)}, |
| @code{#cpu (sh)}, @code{#cpu (sparc)}, @code{#cpu (spur)}, @code{#cpu |
| (tahoe)}, @code{#cpu (vax)}, @code{#cpu (we32000)}. |
| |
| @findex #assert |
| You can create assertions within a C program using @samp{#assert}, like |
| this: |
| |
| @example |
| #assert @var{predicate} (@var{answer}) |
| @end example |
| |
| @noindent |
| (Note the absence of a @samp{#} before @var{predicate}.) |
| |
| @cindex unassert |
| @cindex assertions, undoing |
| @cindex retracting assertions |
| @findex #unassert |
| Each time you do this, you assert a new true answer for @var{predicate}. |
| Asserting one answer does not invalidate previously asserted answers; |
| they all remain true. The only way to remove an answer is with |
| @samp{#unassert}. @samp{#unassert} has the same syntax as |
| @samp{#assert}. You can also remove all answers to a @var{predicate} |
| like this: |
| |
| @example |
| #unassert @var{predicate} |
| @end example |
| |
| You can also add or cancel assertions using command options |
| when you run @code{gcc} or @code{cpp}. @xref{Invocation}. |
| |
| @node Line Control, Other Directives, Assertions, Top |
| @section Combining Source Files |
| |
| @cindex line control |
| One of the jobs of the C preprocessor is to inform the C compiler of where |
| each line of C code came from: which source file and which line number. |
| |
| C code can come from multiple source files if you use @samp{#include}; |
| both @samp{#include} and the use of conditionals and macros can cause |
| the line number of a line in the preprocessor output to be different |
| from the line's number in the original source file. You will appreciate |
| the value of making both the C compiler (in error messages) and symbolic |
| debuggers such as GDB use the line numbers in your source file. |
| |
| The C preprocessor builds on this feature by offering a directive by |
| which you can control the feature explicitly. This is useful when a |
| file for input to the C preprocessor is the output from another program |
| such as the @code{bison} parser generator, which operates on another |
| file that is the true source file. Parts of the output from |
| @code{bison} are generated from scratch, other parts come from a |
| standard parser file. The rest are copied nearly verbatim from the |
| source file, but their line numbers in the @code{bison} output are not |
| the same as their original line numbers. Naturally you would like |
| compiler error messages and symbolic debuggers to know the original |
| source file and line number of each line in the @code{bison} input. |
| |
| @findex #line |
| @code{bison} arranges this by writing @samp{#line} directives into the output |
| file. @samp{#line} is a directive that specifies the original line number |
| and source file name for subsequent input in the current preprocessor input |
| file. @samp{#line} has three variants: |
| |
| @table @code |
| @item #line @var{linenum} |
| Here @var{linenum} is a decimal integer constant. This specifies that |
| the line number of the following line of input, in its original source file, |
| was @var{linenum}. |
| |
| @item #line @var{linenum} @var{filename} |
| Here @var{linenum} is a decimal integer constant and @var{filename} is a |
| string constant. This specifies that the following line of input came |
| originally from source file @var{filename} and its line number there was |
| @var{linenum}. Keep in mind that @var{filename} is not just a file |
| name; it is surrounded by double-quote characters so that it looks like |
| a string constant. |
| |
| @item #line @var{anything else} |
| @var{anything else} is checked for macro calls, which are expanded. |
| The result should be a decimal integer constant followed optionally |
| by a string constant, as described above. |
| @end table |
| |
| @samp{#line} directives alter the results of the @samp{__FILE__} and |
| @samp{__LINE__} predefined macros from that point on. @xref{Standard |
| Predefined}. |
| |
| The output of the preprocessor (which is the input for the rest of the |
| compiler) contains directives that look much like @samp{#line} |
| directives. They start with just @samp{#} instead of @samp{#line}, but |
| this is followed by a line number and file name as in @samp{#line}. |
| @xref{Output}. |
| |
| @node Other Directives, Output, Line Control, Top |
| @section Miscellaneous Preprocessing Directives |
| |
| This section describes some additional, rarely used, preprocessing |
| directives. |
| |
| @findex #pragma |
| @findex #pragma GCC |
| |
| The ISO standard specifies that the effect of the @samp{#pragma} |
| directive is implementation-defined. The GNU C preprocessor recognizes |
| some pragmas, and passes unrecognized ones through to the preprocessor |
| output, so they are available to the compilation pass. |
| |
| In line with the C99 standard, which introduces a STDC namespace for C99 |
| pragmas, the preprocessor introduces a GCC namespace for GCC pragmas. |
| Supported GCC preprocessor pragmas are of the form @samp{#pragma GCC |
| ...}. For backwards compatibility previously supported pragmas are also |
| recognized without the @samp{GCC} prefix, however that use is |
| deprecated. Pragmas that are already deprecated are not recognized with |
| a @samp{GCC} prefix. |
| |
| @findex #pragma GCC dependency |
| The @samp{#pragma GCC dependency} allows you to check the relative dates |
| of the current file and another file. If the other file is more recent |
| than the current file, a warning is issued. This is useful if the |
| include file is derived from the other file, and should be regenerated. |
| The other file is searched for using the normal include search path. |
| Optional trailing text can be used to give more information in the |
| warning message. |
| |
| @smallexample |
| #pragma GCC dependency "parse.y" |
| #pragma GCC dependency "/usr/include/time.h" rerun /path/to/fixincludes |
| @end smallexample |
| |
| @findex _Pragma |
| The C99 standard also introduces the @samp{_Pragma} operator. The |
| syntax is @code{_Pragma (string-literal)}, where @samp{string-literal} |
| can be either a normal or wide-character string literal. It is |
| destringized, by replacing all @samp{\\} with a single @samp{\} and all |
| @samp{\"} with a @samp{"}. The result is then processed as if it had |
| appeared as the right hand side of a @samp{#pragma} directive. For |
| example, |
| |
| @smallexample |
| _Pragma ("GCC dependency \"parse.y\"") |
| @end smallexample |
| |
| @noindent has the same effect as @samp{#pragma GCC dependency |
| "parse.y"}. The same effect could be achieved using macros, for example |
| |
| @smallexample |
| #define DO_PRAGMA(x) _Pragma (#x) |
| DO_PRAGMA (GCC dependency "parse.y") |
| @end smallexample |
| |
| The standard is unclear on where a @samp{_Pragma} operator can appear. |
| The preprocessor accepts it even within a preprocessing conditional |
| directive like @samp{#if}. To be safe, you are probably best keeping it |
| out of directives other than @samp{#define}, and putting it on a line of |
| its own. |
| |
| @findex #ident |
| The @samp{#ident} directive is supported for compatibility with certain |
| other systems. It is followed by a line of text. On some systems, the |
| text is copied into a special place in the object file; on most systems, |
| the text is ignored and this directive has no effect. Typically |
| @samp{#ident} is only used in header files supplied with those systems |
| where it is meaningful. |
| |
| @cindex null directive |
| The @dfn{null directive} consists of a @samp{#} followed by a newline, |
| with only whitespace (including comments) in between. A null directive |
| is understood as a preprocessing directive but has no effect on the |
| preprocessor output. The primary significance of the existence of the |
| null directive is that an input line consisting of just a @samp{#} will |
| produce no output, rather than a line of output containing just a |
| @samp{#}. Supposedly some old C programs contain such lines. |
| |
| @node Output, Implementation, Other Directives, Top |
| @section C Preprocessor Output |
| |
| @cindex output format |
| 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. |
| |
| The ISO standard specifies that it is implementation defined whether a |
| preprocessor preserves whitespace between tokens, or replaces it with |
| e.g. a single space. In the GNU C preprocessor, whitespace between |
| tokens is collapsed to become a single space, with the exception that |
| the first token on a non-directive line is preceded with sufficient |
| spaces that it appears in the same column in the preprocessed output |
| that it appeared in in the original source file. This is so the output |
| is easy to read. @xref{Unreliable Features}. |
| |
| Source file name and line number information is conveyed by lines |
| of the form |
| |
| @example |
| # @var{linenum} @var{filename} @var{flags} |
| @end example |
| |
| @noindent |
| which are inserted as needed into the output (but never within a string |
| or character constant), and in place of long sequences of empty lines. |
| Such a line means that the following line originated in file |
| @var{filename} at line @var{linenum}. |
| |
| After the file name comes zero or more flags, which are @samp{1}, |
| @samp{2}, @samp{3}, or @samp{4}. If there are multiple flags, spaces |
| separate them. Here is what the flags mean: |
| |
| @table @samp |
| @item 1 |
| This indicates the start of a new file. |
| @item 2 |
| This indicates returning to a file (after having included another file). |
| @item 3 |
| This indicates that the following text comes from a system header file, |
| so certain warnings should be suppressed. |
| @item 4 |
| This indicates that the following text should be treated as C@. |
| @c maybe cross reference NO_IMPLICIT_EXTERN_C |
| @end table |
| |
| @node Implementation, Unreliable Features, Output, Top |
| @section Implementation-defined Behavior and Implementation Limits |
| @cindex implementation limits |
| @cindex implementation-defined behavior |
| |
| The ISO C standard mandates that implementations document various |
| aspects of preprocessor behavior. You should try to avoid undue |
| reliance on behaviour described here, as it is possible that it will |
| change subtly in future implementations. |
| |
| @itemize @bullet |
| |
| @item The mapping of physical source file multi-byte characters to the |
| execution character set. |
| |
| Currently, GNU cpp only supports character sets that are strict supersets |
| of ASCII, and performs no translation of characters. |
| |
| @item Non-empty sequences of whitespace characters. |
| |
| Each whitespace sequence is not preserved, but collapsed to a single |
| space. For aesthetic reasons, the first token on each non-directive |
| line of output is preceded with sufficient spaces that it appears in the |
| same column as it did in the original source file. |
| |
| @item The numeric value of character constants in preprocessor expressions. |
| |
| The preprocessor interprets character constants in preprocessing |
| directives on the host machine. Expressions outside preprocessing |
| directives are compiled to be interpreted on the target machine. In the |
| normal case of a native compiler, these two environments are the same |
| and so character constants will be evaluated identically in both cases. |
| However, in the case of a cross compiler, the values may be different. |
| |
| Multi-character character constants are interpreted a character at a |
| time, shifting the previous result left by the number of bits per |
| character on the host, and adding the new character. For example, 'ab' |
| on an 8-bit host would be interpreted as 'a' * 256 + 'b'. If there are |
| more characters in the constant than can fit in the widest native |
| integer type on the host, usually a @samp{long}, the behavior is |
| undefined. |
| |
| Evaluation of wide character constants is not properly implemented yet. |
| |
| @item Source file inclusion. |
| |
| For a discussion on how the preprocessor locates header files, |
| @pxref{Include Operation}. |
| |
| @item Interpretation of the filename resulting from a macro-expanded |
| @samp{#include} directive. |
| |
| If the macro expands to a string literal, the @samp{#include} directive |
| is processed as if the string had been specified directly. Otherwise, |
| the macro must expand to a token stream beginning with a @samp{<} token |
| and including a @samp{>} token. In this case, the tokens between the |
| @samp{<} and the first @samp{>} are combined to form the filename to be |
| included. Any whitespace between tokens is reduced to a single space; |
| then any space after the initial @samp{<} is retained, but a trailing |
| space before the closing @samp{>} is ignored. |
| |
| In either case, if any excess tokens remain, an error occurs and the |
| directive is not processed. |
| |
| @item Treatment of a @samp{#pragma} directive that after macro-expansion |
| results in a standard pragma. |
| |
| The pragma is processed as if it were a normal standard pragma. |
| |
| @end itemize |
| |
| The following documents internal limits of GNU cpp. |
| |
| @itemize @bullet |
| |
| @item Nesting levels of @samp{#include} files. |
| |
| We impose an arbitrary limit of 200 levels, to avoid runaway recursion. |
| The standard requires at least 15 levels. |
| |
| @item Nesting levels of conditional inclusion. |
| |
| The C standard mandates this be at least 63. The GNU C preprocessor |
| is limited only by available memory. |
| |
| @item Levels of parenthesised expressions within a full expression. |
| |
| The C standard requires this to be at least 63. In preprocessor |
| conditional expressions it is limited only by available memory. |
| |
| @item Significant initial characters in an identifier or macro name. |
| |
| The preprocessor treats all characters as significant. The C standard |
| requires only that the first 63 be significant. |
| |
| @item Number of macros simultaneously defined in a single translation unit. |
| |
| The standard requires at least 4095 be possible; GNU cpp is limited only |
| by available memory. |
| |
| @item Number of parameters in a macro definition and arguments in a macro call. |
| |
| We allow USHRT_MAX, which is normally 65,535, and above the minimum of |
| 127 required by the standard. |
| |
| @item Number of characters on a logical source line. |
| |
| The C standard requires a minimum of 4096 be permitted. GNU cpp places |
| no limits on this, but you may get incorrect column numbers reported in |
| diagnostics for lines longer than 65,535 characters. |
| |
| @end itemize |
| |
| @node Unreliable Features, Invocation, Implementation, Top |
| @section Undefined Behavior and Deprecated Features |
| @cindex undefined behavior |
| @cindex deprecated features |
| |
| This section details GNU C preprocessor behavior that is subject to |
| change or deprecated. You are @emph{strongly advised} to write your |
| software so it does not rely on anything described here; future versions |
| of the preprocessor may subtly change such behavior or even remove the |
| feature altogether. |
| |
| Preservation of the form of whitespace between tokens is unlikely to |
| change from current behavior (@ref{Output}), but you are advised not |
| to rely on it. |
| |
| The following are undocumented and subject to change:- |
| |
| @itemize @bullet |
| |
| @item Precedence of ## operators with respect to each other |
| |
| Whether a sequence of ## operators is evaluated left-to-right, |
| right-to-left or indeed in a consistent direction at all is not |
| specified. An example of where this might matter is pasting the |
| arguments @samp{1}, @samp{e} and @samp{-2}. This would be fine for |
| left-to-right pasting, but right-to-left pasting would produce an |
| invalid token @samp{e-2}. It is possible to guarantee precedence by |
| suitable use of nested macros. |
| |
| @item Precedence of # operator with respect to the ## operator |
| |
| Which of these two operators is evaluated first is not specified. |
| |
| @end itemize |
| |
| The following features are in flux and should not be used in portable |
| code: |
| |
| @itemize @bullet |
| |
| @item Optional argument when invoking rest argument macros |
| |
| As an extension, GCC permits you to omit the variable arguments entirely |
| when you use a variable argument macro. This works whether or not you |
| give the variable argument a name. For example, the two macro |
| invocations in the example below expand to the same thing: |
| |
| @smallexample |
| #define debug(format, ...) printf (format, __VA_ARGS__) |
| debug("string"); /* Not permitted by C standard. */ |
| debug("string",); /* OK. */ |
| @end smallexample |
| |
| This extension will be preserved, but the special behavior of @samp{##} |
| in this context has changed in the past and may change again in the |
| future. |
| |
| @item ## swallowing preceding text in rest argument macros |
| |
| Formerly, in a macro expansion, if @samp{##} appeared before a variable |
| arguments parameter, and the set of tokens specified for that argument in |
| the macro invocation was empty, previous versions of the GNU C |
| preprocessor would back up and remove the preceding sequence of |
| non-whitespace characters (@strong{not} the preceding token). This |
| extension is in direct conflict with the 1999 C standard and has been |
| drastically pared back. |
| |
| In the current version of the preprocessor, if @samp{##} appears between |
| a comma and a variable arguments parameter, and the variable argument is |
| omitted entirely, the comma will be removed from the expansion. If the |
| variable argument is empty, or the token before @samp{##} is not a |
| comma, then @samp{##} behaves as a normal token paste. |
| |
| Portable code should avoid this extension at all costs. |
| |
| @end itemize |
| |
| The following features are deprecated and will likely be removed at some |
| point in the future:- |
| |
| @itemize @bullet |
| |
| @item Attempting to paste two tokens which together do not form a valid |
| preprocessing token |
| |
| The preprocessor currently warns about this and outputs the two tokens |
| adjacently, which is probably the behavior the programmer intends. It |
| may not work in future, though. |
| |
| Most of the time, when you get this warning, you will find that @samp{##} |
| is being used superstitiously, to guard against whitespace appearing |
| between two tokens. It is almost always safe to delete the @samp{##}. |
| |
| @findex #pragma once |
| @item #pragma once |
| |
| This pragma was once used to tell the preprocessor that it need not |
| include a file more than once. It is now obsolete and should not be |
| used at all. |
| |
| @item #pragma poison |
| |
| This pragma has been superseded by @samp{#pragma GCC poison}. |
| @xref{Poisoning}. |
| |
| @item Multi-line string literals |
| |
| The preprocessor currently allows raw newlines in string literals. This |
| extension is deprecated and will be removed in a future version of GCC. |
| The preprocessor already forbids such string literals in all directives |
| apart from #define. |
| |
| Instead, make use of ISO C concatenation of adjacent string literals, or |
| use @samp{\n} followed by an escaped newline. |
| |
| @item Preprocessing things which are not C |
| |
| The C preprocessor is intended to be used only with C, C++, and |
| Objective C source code. In the past, it has been abused as a general |
| text processor. It will choke on input which is not lexically valid C; |
| for example, apostrophes will be interpreted as the beginning of |
| character constants, and cause errors. Also, you cannot rely on it |
| preserving characteristics of the input which are not significant to |
| C-family languages. For instance, if a Makefile is preprocessed, all |
| the hard tabs will be lost, and the Makefile will not work. |
| |
| Having said that, you can often get away with using cpp on things which |
| are not C. Other Algol-ish programming languages are often safe |
| (Pascal, Ada, ...) and so is assembly, with caution. @samp{-traditional} |
| mode is much more permissive, and can safely be used with e.g. Fortran. |
| Many of the problems go away if you write C or C++ style comments |
| instead of native language comments, and if you avoid elaborate macros. |
| |
| Wherever possible, you should use a preprocessor geared to the language |
| you are writing in. Modern versions of the GNU assembler have macro |
| facilities. Most high level programming languages have their own |
| conditional compilation and inclusion mechanism. If all else fails, |
| try a true general text processor, such as @xref{Top, M4, , m4, GNU `m4'}. |
| |
| @end itemize |
| |
| @node Invocation, Concept Index, Unreliable Features, Top |
| @section Invoking the C Preprocessor |
| @cindex invocation of the preprocessor |
| |
| 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. |
| |
| @ignore |
| @c man begin SYNOPSIS |
| cpp [@samp{-P}] [@samp{-C}] [@samp{-gcc}] [@samp{-traditional}] |
| [@samp{-undef}] [@samp{-trigraphs}] [@samp{-pedantic}] |
| [@samp{-W}@var{warn}...] [@samp{-I}@var{dir}...] |
| [@samp{-D}@var{macro}[=@var{defn}]...] [@samp{-U}@var{macro}] |
| [@samp{-A}@var{predicate}(@var{answer})] |
| [@samp{-M}|@samp{-MM}][@samp{-MG}][@samp{-MF}@var{filename}] |
| [@samp{-MP}][@samp{-MQ}@var{target}...][@samp{-MT}@var{target}...] |
| [@samp{-x} @var{language}] [@samp{-std=}@var{standard}] |
| @var{infile} @var{outfile} |
| |
| Only the most useful options are listed here; see below for the remainder. |
| @c man end |
| @c man begin SEEALSO |
| gcc(1), as(1), ld(1), and the Info entries for @file{cpp}, @file{gcc}, and |
| @file{binutils}. |
| @c man end |
| @end ignore |
| |
| @c man begin OPTIONS |
| The C preprocessor expects two file names as arguments, @var{infile} and |
| @var{outfile}. The preprocessor reads @var{infile} together with any |
| other files it specifies with @samp{#include}. All the output generated |
| by the combined input files is written in @var{outfile}. |
| |
| Either @var{infile} or @var{outfile} may be @samp{-}, which as |
| @var{infile} means to read from standard input and as @var{outfile} |
| means to write to standard output. Also, if either file is omitted, it |
| means the same as if @samp{-} had been specified for that file. |
| |
| @cindex options |
| Here is a table of command options accepted by the C preprocessor. |
| These options can also be given when compiling a C program; they are |
| passed along automatically to the preprocessor when it is invoked by the |
| compiler. |
| |
| @table @samp |
| @item -P |
| @findex -P |
| Inhibit generation of @samp{#}-lines with line-number information in the |
| output from the preprocessor. This might be useful when running the |
| preprocessor on something that is not C code and will be sent to a |
| program which might be confused by the @samp{#}-lines. @xref{Output}. |
| |
| @item -C |
| @findex -C |
| Do not discard comments. All comments are passed through to the output |
| file, except for comments in processed directives, which are deleted |
| along with the directive. Comments appearing in the expansion list of a |
| macro will be preserved, and appear in place wherever the macro is |
| invoked. |
| |
| You should be prepared for side effects when using @samp{-C}; it causes |
| the preprocessor to treat comments as tokens in their own right. For |
| example, macro redefinitions that were trivial when comments were |
| replaced by a single space might become significant when comments are |
| retained. Also, comments appearing at the start of what would be a |
| directive line have the effect of turning that line into an ordinary |
| source line, since the first token on the line is no longer a @samp{#}. |
| |
| @item -traditional |
| @findex -traditional |
| Try to imitate the behavior of old-fashioned C, as opposed to ISO C@. |
| |
| @itemize @bullet |
| @item |
| Traditional macro expansion pays no attention to single-quote or |
| double-quote characters; macro argument symbols are replaced by the |
| argument values even when they appear within apparent string or |
| character constants. |
| |
| @item |
| Traditionally, it is permissible for a macro expansion to end in the |
| middle of a string or character constant. The constant continues into |
| the text surrounding the macro call. |
| |
| @item |
| However, traditionally the end of the line terminates a string or |
| character constant, with no error. |
| |
| @item |
| In traditional C, a comment is equivalent to no text at all. (In ISO |
| C, a comment counts as whitespace.) |
| |
| @item |
| Traditional C does not have the concept of a ``preprocessing number''. |
| It considers @samp{1.0e+4} to be three tokens: @samp{1.0e}, @samp{+}, |
| and @samp{4}. |
| |
| @item |
| A macro is not suppressed within its own definition, in traditional C@. |
| Thus, any macro that is used recursively inevitably causes an error. |
| |
| @item |
| The character @samp{#} has no special meaning within a macro definition |
| in traditional C@. |
| |
| @item |
| In traditional C, the text at the end of a macro expansion can run |
| together with the text after the macro call, to produce a single token. |
| (This is impossible in ISO C@.) |
| |
| @item |
| None of the GNU extensions to the preprocessor are available in |
| @samp{-traditional} mode. |
| |
| @end itemize |
| |
| @cindex Fortran |
| @cindex unterminated |
| Use the @samp{-traditional} option when preprocessing Fortran code, so |
| that single-quotes and double-quotes within Fortran comment lines (which |
| are generally not recognized as such by the preprocessor) do not cause |
| diagnostics about unterminated character or string constants. |
| |
| However, this option does not prevent diagnostics about unterminated |
| comments when a C-style comment appears to start, but not end, within |
| Fortran-style commentary. |
| |
| So, the following Fortran comment lines are accepted with |
| @samp{-traditional}: |
| |
| @smallexample |
| C This isn't an unterminated character constant |
| C Neither is "20000000000, an octal constant |
| C in some dialects of Fortran |
| @end smallexample |
| |
| However, this type of comment line will likely produce a diagnostic, or |
| at least unexpected output from the preprocessor, due to the |
| unterminated comment: |
| |
| @smallexample |
| C Some Fortran compilers accept /* as starting |
| C an inline comment. |
| @end smallexample |
| |
| @cindex g77 |
| Note that @code{g77} automatically supplies the @samp{-traditional} |
| option when it invokes the preprocessor. However, a future version of |
| @code{g77} might use a different, more-Fortran-aware preprocessor in |
| place of @code{cpp}. |
| |
| @item -trigraphs |
| @findex -trigraphs |
| Process ISO standard trigraph sequences. These are three-character |
| sequences, all starting with @samp{??}, that are defined by ISO C to |
| stand for single characters. For example, @samp{??/} stands for |
| @samp{\}, so @samp{'??/n'} is a character constant for a newline. By |
| default, GCC ignores trigraphs, but in standard-conforming modes it |
| converts them. See the @samp{-std} option. |
| |
| The nine trigraph sequences are |
| @table @samp |
| @item ??( |
| -> @samp{[} |
| |
| @item ??) |
| -> @samp{]} |
| |
| @item ??< |
| -> @samp{@{} |
| |
| @item ??> |
| -> @samp{@}} |
| |
| @item ??= |
| -> @samp{#} |
| |
| @item ??/ |
| -> @samp{\} |
| |
| @item ??' |
| -> @samp{^} |
| |
| @item ??! |
| -> @samp{|} |
| |
| @item ??- |
| -> @samp{~} |
| |
| @end table |
| |
| Trigraph support is not popular, so many compilers do not implement it |
| properly. Portable code should not rely on trigraphs being either |
| converted or ignored. |
| |
| @item -pedantic |
| @findex -pedantic |
| Issue warnings required by the ISO C standard in certain cases such |
| as when text other than a comment follows @samp{#else} or @samp{#endif}. |
| |
| @item -pedantic-errors |
| @findex -pedantic-errors |
| Like @samp{-pedantic}, except that errors are produced rather than |
| warnings. |
| |
| @item -Wcomment |
| @findex -Wcomment |
| @itemx -Wcomments |
| (Both forms have the same effect). |
| Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*} |
| comment, or whenever a backslash-newline appears in a @samp{//} comment. |
| |
| @item -Wtrigraphs |
| @findex -Wtrigraphs |
| Warn if any trigraphs are encountered. This option used to take effect |
| only if @samp{-trigraphs} was also specified, but now works |
| independently. Warnings are not given for trigraphs within comments, as |
| we feel this is obnoxious. |
| |
| @item -Wwhite-space |
| @findex -Wwhite-space |
| Warn about possible white space confusion, e.g. white space between a |
| backslash and a newline. |
| |
| @item -Wall |
| @findex -Wall |
| Requests @samp{-Wcomment}, @samp{-Wtrigraphs}, and @samp{-Wwhite-space} |
| (but not @samp{-Wtraditional} or @samp{-Wundef}). |
| |
| @item -Wtraditional |
| @findex -Wtraditional |
| Warn about certain constructs that behave differently in traditional and |
| ISO C@. |
| |
| @itemize @bullet |
| @item |
| Macro parameters that appear within string literals in the macro body. |
| In traditional C macro replacement takes place within string literals, |
| but does not in ISO C. |
| |
| @item |
| In traditional C, some preprocessor directives did not exist. |
| Traditional preprocessors would only consider a line to be a directive |
| if the @samp{#} appeared in column 1 on the line. Therefore |
| @samp{-Wtraditional} warns about directives that traditional C |
| understands but would ignore because the @samp{#} does not appear as the |
| first character on the line. It also suggests you hide directives like |
| @samp{#pragma} not understood by traditional C by indenting them. Some |
| traditional implementations would not recognise @samp{#elif}, so it |
| suggests avoiding it altogether. |
| |
| @item |
| A function-like macro that appears without arguments. |
| |
| @item |
| The unary plus operator. |
| |
| @item |
| The `U' integer constant suffix. (Traditonal C does support the `L' |
| suffix on integer constants.) Note, these suffixes appear in macros |
| defined in the system headers of most modern systems, e.g. the _MIN/_MAX |
| macros in limits.h. Use of these macros can lead to spurious warnings |
| as they do not necessarily reflect whether the code in question is any |
| less portable to traditional C given that suitable backup definitions |
| are provided. |
| @end itemize |
| |
| @item -Wundef |
| @findex -Wundef |
| Warn if an undefined identifier is evaluated in an @samp{#if} directive. |
| |
| @item -I @var{directory} |
| @findex -I |
| Add the directory @var{directory} to the head of the list of |
| directories to be searched for header files (@pxref{Include Syntax}). |
| This can be used to override a system header file, substituting your |
| own version, since these directories are searched before the system |
| header file directories. If you use more than one @samp{-I} option, |
| the directories are scanned in left-to-right order; the standard |
| system directories come after. |
| |
| @item -I- |
| Any directories specified with @samp{-I} options before the @samp{-I-} |
| option are searched only for the case of @samp{#include "@var{file}"}; |
| they are not searched for @samp{#include <@var{file}>}. |
| |
| If additional directories are specified with @samp{-I} options after |
| the @samp{-I-}, these directories are searched for all @samp{#include} |
| directives. |
| |
| In addition, the @samp{-I-} option inhibits the use of the current |
| directory as the first search directory for @samp{#include "@var{file}"}. |
| Therefore, the current directory is searched only if it is requested |
| explicitly with @samp{-I.}. Specifying both @samp{-I-} and @samp{-I.} |
| allows you to control precisely which directories are searched before |
| the current one and which are searched after. |
| |
| @item -nostdinc |
| @findex -nostdinc |
| Do not search the standard system directories for header files. |
| Only the directories you have specified with @samp{-I} options |
| (and the current directory, if appropriate) are searched. |
| |
| By using both @samp{-nostdinc} and @samp{-I-}, you can limit the include-file |
| search path to only those directories you specify explicitly. |
| |
| @item -nostdinc++ |
| @findex -nostdinc++ |
| Do not search for header files in the C++-specific standard directories, |
| but do still search the other standard directories. (This option is |
| used when building the C++ library.) |
| |
| @item -remap |
| @findex -remap |
| When searching for a header file in a directory, remap file names if a |
| file named @file{header.gcc} exists in that directory. This can be used |
| to work around limitations of file systems with file name restrictions. |
| The @file{header.gcc} file should contain a series of lines with two |
| tokens on each line: the first token is the name to map, and the second |
| token is the actual name to use. |
| |
| @item -D @var{name} |
| @findex -D |
| Predefine @var{name} as a macro, with definition @samp{1}. |
| |
| @item -D @var{name}=@var{definition} |
| Predefine @var{name} as a macro, with definition @var{definition}. |
| There are no restrictions on the contents of @var{definition}, but if |
| you are invoking the preprocessor from a shell or shell-like program you |
| may need to use the shell's quoting syntax to protect characters such as |
| spaces that have a meaning in the shell syntax. If you use more than |
| one @samp{-D} for the same @var{name}, the rightmost definition takes |
| effect. |
| |
| Any @samp{-D} and @samp{-U} options on the command line are processed in |
| order, and always before @samp{-imacros @var{file}}, regardless of the |
| order in which they are written. |
| |
| @item -U @var{name} |
| @findex -U |
| Do not predefine @var{name}. |
| |
| Any @samp{-D} and @samp{-U} options on the command line are processed in |
| order, and always before @samp{-imacros @var{file}}, regardless of the |
| order in which they are written. |
| |
| @item -undef |
| @findex -undef |
| Do not predefine any nonstandard macros. |
| |
| @item -gcc |
| @findex -gcc |
| Define the macros @var{__GNUC__}, @var{__GNUC_MINOR__} and |
| @var{__GNUC_PATCHLEVEL__}. These are defined automatically when you use |
| @samp{gcc -E}; you can turn them off in that case with @samp{-no-gcc}. |
| |
| @item -A @var{predicate}=@var{answer} |
| @findex -A |
| Make an assertion with the predicate @var{predicate} and answer |
| @var{answer}. This form is preferred to the older form @samp{-A |
| @var{predicate}(@var{answer})}, which is still supported, because |
| it does not use shell special characters. @xref{Assertions}. |
| |
| @item -A -@var{predicate}=@var{answer} |
| Disable an assertion with the predicate @var{predicate} and answer |
| @var{answer}. Specifying no predicate, by @samp{-A-} or @samp{-A -}, |
| disables all predefined assertions and all assertions preceding it on |
| the command line; and also undefines all predefined macros and all |
| macros preceding it on the command line. |
| |
| @item -dM |
| @findex -dM |
| Instead of outputting the result of preprocessing, output a list of |
| @samp{#define} directives for all the macros defined during the |
| execution of the preprocessor, including predefined macros. This gives |
| you a way of finding out what is predefined in your version of the |
| preprocessor; assuming you have no file @samp{foo.h}, the command |
| |
| @example |
| touch foo.h; cpp -dM foo.h |
| @end example |
| |
| @noindent |
| will show the values of any predefined macros. |
| |
| @item -dD |
| @findex -dD |
| Like @samp{-dM} except in two respects: it does @emph{not} include the |
| predefined macros, and it outputs @emph{both} the @samp{#define} |
| directives and the result of preprocessing. Both kinds of output go to |
| the standard output file. |
| |
| @item -dN |
| @findex -dN |
| Like @samp{-dD}, but emit only the macro names, not their expansions. |
| |
| @item -dI |
| @findex -dI |
| Output @samp{#include} directives in addition to the result of |
| preprocessing. |
| |
| @item -M |
| @findex -M |
| Instead of outputting the result of preprocessing, output a rule |
| suitable for @code{make} describing the dependencies of the main source |
| file. The preprocessor outputs one @code{make} rule containing the |
| object file name for that source file, a colon, and the names of all the |
| included files, including those coming from @samp{-include} or |
| @samp{-imacros} command line options. Unless specified explicitly (with |
| @samp{-MT} or @samp{-MQ}), the object file name consists of the basename |
| of the source file with any suffix replaced with object file suffix. |
| If there are many included files |
| then the rule is split into several lines using @samp{\}-newline. |
| |
| @item -MM |
| @findex -MM |
| Like @samp{-M}, but mention only the files included with @samp{#include |
| "@var{file}"} or with @samp{-include} or @samp{-imacros} command line |
| options. System header files included with @samp{#include <@var{file}>} |
| are omitted. |
| |
| @item -MF @var{file} |
| @findex -MF |
| When used with @samp{-M} or @samp{-MM}, specifies a file to write the |
| dependencies to. This allows the preprocessor to write the preprocessed |
| file to stdout normally. If no @samp{-MF} switch is given, CPP sends |
| the rules to stdout and suppresses normal preprocessed output. |
| |
| @item -MG |
| @findex -MG |
| When used with @samp{-M} or @samp{-MM}, @samp{-MG} says to treat missing |
| header files as generated files and assume they live in the same |
| directory as the source file. It suppresses preprocessed output, as a |
| missing header file is ordinarily an error. |
| |
| This feature is used in automatic updating of makefiles. |
| |
| @item -MP |
| @findex -MP |
| This option instructs CPP to add a phony target for each dependency |
| other than the main file, causing each to depend on nothing. These |
| dummy rules work around errors @code{make} gives if you remove header |
| files without updating the @code{Makefile} to match. |
| |
| This is typical output:- |
| |
| @smallexample |
| /tmp/test.o: /tmp/test.c /tmp/test.h |
| |
| /tmp/test.h: |
| @end smallexample |
| |
| @item -MQ @var{target} |
| @item -MT @var{target} |
| @findex -MQ |
| @findex -MT |
| By default CPP uses the main file name, including any path, and appends |
| the object suffix, normally ``.o'', to it to obtain the name of the |
| target for dependency generation. With @samp{-MT} you can specify a |
| target yourself, overriding the default one. |
| |
| If you want multiple targets, you can specify them as a single argument |
| to @samp{-MT}, or use multiple @samp{-MT} options. |
| |
| The targets you specify are output in the order they appear on the |
| command line. @samp{-MQ} is identical to @samp{-MT}, except that the |
| target name is quoted for Make, but with @samp{-MT} it isn't. For |
| example, -MT '$(objpfx)foo.o' gives |
| |
| @smallexample |
| $(objpfx)foo.o: /tmp/foo.c |
| @end smallexample |
| |
| but -MQ '$(objpfx)foo.o' gives |
| |
| @smallexample |
| $$(objpfx)foo.o: /tmp/foo.c |
| @end smallexample |
| |
| The default target is automatically quoted, as if it were given with |
| @samp{-MQ}. |
| |
| @item -H |
| @findex -H |
| Print the name of each header file used, in addition to other normal |
| activities. |
| |
| @item -imacros @var{file} |
| @findex -imacros |
| Process @var{file} as input and discard the resulting output. |
| |
| This has all the effects of @code{#include "file"} appearing on the |
| first line of the main source file, such as generating dependencies and |
| being listed with the @samp{-H} option, except that no output is |
| generated, and that the first directory searched for @var{file} is the |
| preprocessor's working directory @emph{instead of} the directory |
| containing the main source file. If not found there, it is searched for |
| in the remainder of the @code{#include "..."} search chain as normal. |
| |
| Because the output is discarded, the main effect of @samp{-imacros |
| @var{file}} is to make the macros defined in @var{file} available for |
| use in the main input. |
| |
| @item -include @var{file} |
| @findex -include |
| Process @var{file} as input, and include all the resulting output. |
| |
| This has all the effects of @code{#include "file"} appearing on the |
| first line of the main source file, such as generating dependencies and |
| being listed with the @samp{-H} option, except that the first directory |
| searched for @var{file} is the preprocessor's working directory |
| @emph{instead of} the directory containing the main source file. If not |
| found there, it is searched for in the remainder of the @code{#include |
| "..."} search chain as normal. |
| |
| @item -idirafter @var{dir} |
| @findex -idirafter |
| @cindex second include path |
| Add the directory @var{dir} to the second include path, marking it as a |
| system directory. The directories on the second include path are searched |
| when a header file is not found in any of the directories in the main |
| include path (the one that @samp{-I} adds to). |
| |
| @item -iprefix @var{prefix} |
| @findex -iprefix |
| Specify @var{prefix} as the prefix for subsequent @samp{-iwithprefix} |
| options. If the prefix represents a directory, you should include the |
| final @samp{/}. |
| |
| @item -iwithprefix @var{dir} |
| @findex -iwithprefix |
| Add a directory to the second include path, marking it as a system |
| directory. The directory's name is made by concatenating @var{prefix} |
| and @var{dir}, where @var{prefix} was specified previously with |
| @samp{-iprefix}. |
| |
| @item -isystem @var{dir} |
| @findex -isystem |
| Add a directory to the beginning of the second include path, marking it |
| as a system directory, so that it gets the same special treatment as |
| is applied to the standard system directories. @xref{System Headers}. |
| |
| @item -x c |
| @itemx -x c++ |
| @itemx -x objective-c |
| @itemx -x assembler-with-cpp |
| @findex -x c |
| @findex -x objective-c |
| @findex -x assembler-with-cpp |
| Specify the source language: C, C++, Objective-C, or assembly. This has |
| nothing to do with standards conformance or extensions; it merely |
| selects which base syntax to expect. If you give none of these options, |
| cpp will deduce the language from the extension of the source file: |
| @samp{.c}, @samp{.cc}, @samp{.m}, or @samp{.S}. Some other common |
| extensions for C++ and assembly are also recognized. If cpp does not |
| recognize the extension, it will treat the file as C; this is the most |
| generic mode. |
| |
| @strong{Note:} Previous versions of cpp accepted a @samp{-lang} option |
| which selected both the language and the standards conformance level. |
| This option has been removed, because it conflicts with the @samp{-l} |
| option. |
| |
| @item -std=@var{standard} |
| @itemx -ansi |
| @findex -std |
| @findex -ansi |
| Specify the standard to which the code should conform. Currently cpp |
| only knows about the standards for C; other language standards will be |
| added in the future. |
| |
| @var{standard} |
| may be one of: |
| @table @code |
| @item iso9899:1990 |
| @itemx c89 |
| The ISO C standard from 1990. @samp{c89} is the customary shorthand for |
| this version of the standard. |
| |
| The @samp{-ansi} option is equivalent to @samp{-std=c89}. |
| |
| @item iso9899:199409 |
| The 1990 C standard, as amended in 1994. |
| |
| @item iso9899:1999 |
| @itemx c99 |
| @itemx iso9899:199x |
| @itemx c9x |
| The revised ISO C standard, published in December 1999. Before |
| publication, this was known as C9X. |
| |
| @item gnu89 |
| The 1990 C standard plus GNU extensions. This is the default. |
| |
| @item gnu99 |
| @itemx gnu9x |
| The 1999 C standard plus GNU extensions. |
| @end table |
| |
| @item -ftabstop=NUMBER |
| @findex -ftabstop |
| Set the distance between tab stops. This helps the preprocessor |
| report correct column numbers in warnings or errors, even if tabs appear |
| on the line. Values less than 1 or greater than 100 are ignored. The |
| default is 8. |
| |
| @item -$ |
| @findex -$ |
| Forbid the use of @samp{$} in identifiers. The C standard allows |
| implementations to define extra characters that can appear in |
| identifiers. By default the GNU C preprocessor permits @samp{$}, a |
| common extension. |
| @end table |
| @c man end |
| |
| @node Concept Index, Index, Invocation, Top |
| @unnumbered Concept Index |
| @printindex cp |
| |
| @node Index,, Concept Index, Top |
| @unnumbered Index of Directives, Macros and Options |
| @printindex fn |
| |
| @contents |
| @bye |