X-Git-Url: https://git.gag.com/?a=blobdiff_plain;f=support%2Fcpp%2Fcpp.texi;fp=support%2Fcpp%2Fcpp.texi;h=0000000000000000000000000000000000000000;hb=bdc517ae4a26d2047e7379cbd7d94b2ab665c2df;hp=1de8371701e34e98a8b9b73d47fb19574a0df633;hpb=541d83d9229c4cae95e807891dc56cceba4a5bd5;p=fw%2Fsdcc diff --git a/support/cpp/cpp.texi b/support/cpp/cpp.texi deleted file mode 100644 index 1de83717..00000000 --- a/support/cpp/cpp.texi +++ /dev/null @@ -1,2856 +0,0 @@ -\input texinfo -@setfilename cpp.info -@settitle The C Preprocessor - -@ignore -@ifinfo -@format -START-INFO-DIR-ENTRY -* Cpp: (cpp). The C preprocessor. -END-INFO-DIR-ENTRY -@end format -@end ifinfo -@end ignore - -@c @smallbook -@c @cropmarks -@c @finalout -@setchapternewpage odd -@ifinfo -This file documents the GNU C Preprocessor. - -Copyright 1987, 1989, 1991, 1992, 1993, 1994, 1995 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 July 1992 -@subtitle for GCC version 2 -@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 -Copyright @copyright{} 1987, 1989, 1991, 1992, 1993, 1994, 1995 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. -@end titlepage -@page - -@node Top, Global Actions,, (DIR) -@chapter The C Preprocessor - -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 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, the C Compatible Compiler Preprocessor. The GNU C -preprocessor provides a superset of the features of ANSI Standard C. - -ANSI Standard C requires the rejection of many harmless constructs commonly -used by today's C programs. Such incompatibility would be inconvenient for -users, so the GNU C preprocessor is configured to accept these constructs -by default. Strictly speaking, to get ANSI Standard C, you must use the -options @samp{-trigraphs}, @samp{-undef} and @samp{-pedantic}, but in -practice the consequences of having strict ANSI Standard C make it -undesirable to do this. @xref{Invocation}. - -@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. -* Combining Sources:: Use of line control when you combine source files. -* Other Directives:: Miscellaneous preprocessing directives. -* Output:: Format of output from the C preprocessor. -* 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 - -Most C preprocessor features are inactive unless you give specific directives -to request their use. (Preprocessing directives are lines starting with -@samp{#}; @pxref{Directives}). But there are three transformations that the -preprocessor always makes on all the input it receives, even in the absence -of directives. - -@itemize @bullet -@item -All C comments are replaced with single spaces. - -@item -Backslash-Newline sequences are deleted, no matter where. This -feature allows you to break long lines for cosmetic purposes without -changing their meaning. - -@item -Predefined macro names are replaced with their expansions -(@pxref{Predefined}). -@end itemize - -The first two transformations are done @emph{before} nearly all other parsing -and before preprocessing directives are recognized. Thus, for example, you -can split a line cosmetically with Backslash-Newline anywhere (except -when trigraphs are in use; see below). - -@example -/* -*/ # /* -*/ defi\ -ne FO\ -O 10\ -20 -@end example - -@noindent -is equivalent into @samp{#define FOO 1020}. You can split even an escape -sequence with Backslash-Newline. For example, you can split @code{"foo\bar"} -between the @samp{\} and the @samp{b} to get - -@example -"foo\\ -bar" -@end example - -@noindent -This behavior is unclean: in all other contexts, a Backslash can be -inserted in a string constant as an ordinary character by writing a double -Backslash, and this creates an exception. But the ANSI C standard requires -it. (Strict ANSI C does not allow Newlines in string constants, so they -do not consider this a problem.) - -But there are a few exceptions to all three transformations. - -@itemize @bullet -@item -C comments and predefined macro names are not recognized inside a -@samp{#include} directive in which the file name is delimited with -@samp{<} and @samp{>}. - -@item -C comments and predefined macro names are never recognized within a -character or string constant. (Strictly speaking, this is the rule, -not an exception, but it is worth noting here anyway.) - -@item -Backslash-Newline may not safely be used within an ANSI ``trigraph''. -Trigraphs are converted before Backslash-Newline is deleted. If you -write what looks like a trigraph with a Backslash-Newline inside, the -Backslash-Newline is deleted as usual, but it is then too late to -recognize the trigraph. - -This exception is relevant only if you use the @samp{-trigraphs} -option to enable trigraph processing. @xref{Invocation}. -@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{#}. -The @samp{#} is followed by an identifier that is the @dfn{directive name}. -For example, @samp{#define} is the directive that defines a macro. -Whitespace is also allowed before and after the @samp{#}. - -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{Simple Macros}. - -A preprocessing directive cannot be more than one line in normal circumstances. -It may be split cosmetically with Backslash-Newline, but that has no effect -on its meaning. Comments containing Newlines can also divide the -directive into multiple lines, but the comments are changed to Spaces -before the directive is interpreted. The only way a significant Newline -can occur in a preprocessing directive is within a string constant or -character constant. Note that -most C compilers that might be applied to the output from the preprocessor -do not accept string or character constants containing Newlines. - -The @samp{#} and the directive name cannot come from a macro expansion. For -example, if @samp{foo} is defined as a macro expanding to @samp{define}, -that does not make @samp{#foo} a valid preprocessing directive. - -@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. -@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 -@findex 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. But 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 parsing of this form of @samp{#include} is slightly special -because comments are not recognized within the @samp{<@dots{}>}. -Thus, in @samp{#include } the @samp{/*} does not start a comment -and the directive specifies inclusion of a system header file named -@file{x/*y}. Of course, a header file with such a name is unlikely to -exist on Unix, where shell wildcard features would make it hard to -manipulate.@refill - -The argument @var{file} may not contain a @samp{>} character. It may, -however, 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.) - -The argument @var{file} may not contain @samp{"} characters. 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. It is not clear why this behavior is ever useful, but -the ANSI standard specifies it. - -@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 fit one of the above two variants---in particular, the expanded -text must in the end be surrounded by either quotes or angle braces. - -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, then it records -that fact. If a subsequent @samp{#include} specifies the same file, -and the macro in the @samp{#ifndef} is already defined, then the file -is entirely skipped, without even reading it. - -@findex #pragma once -There is also an explicit directive to tell the preprocessor that it need -not include a file more than once. This is called @samp{#pragma once}, -and was used @emph{in addition to} the @samp{#ifndef} conditional around -the contents of the header file. @samp{#pragma once} is now obsolete -and should not be used 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,, 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 -@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 using the option @samp{-I.} for compilation, and -writing a file @file{sys/signal.h} that does what the application -program expects. But making this file include the standard -@file{sys/signal.h} is not so easy---writing @samp{#include -} 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 } 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 that -both directories contain a file named @file{sys/signal.h}. Ordinary -@samp{#include } finds the file under -@file{/usr/local/include}. If that file contains @samp{#include_next -}, it starts searching after that directory, and finds the -file in @file{/usr/include}. - -@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 -* Simple Macros:: Macros that always expand the same way. -* Argument Macros:: Macros that accept arguments that are substituted - into the macro expansion. -* 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. -* Macro Pitfalls:: Macros can confuse the unwary. Here we explain - several common problems and strange features. -@end menu - -@node Simple Macros, Argument Macros, Macros, Macros -@subsection Simple Macros -@cindex simple macro -@cindex manifest constant - -A @dfn{simple 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 code it should be an abbreviation for. For example, - -@example -#define BUFFER_SIZE 1020 -@end example - -@noindent -defines a macro named @samp{BUFFER_SIZE} as an abbreviation for the text -@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 must be a single line, like all C -preprocessing directives. (You can split a long macro definition -cosmetically with Backslash-Newline.) There is one exception: Newlines -can be included in the macro definition if within a string or character -constant. This is because it is not possible for a macro definition to -contain an unbalanced quote character; the definition automatically -extends to include the matching quote character that ends the string or -character constant. Comments within a macro definition may contain -Newlines, which make no difference since the comments are entirely -replaced with Spaces regardless of their contents. - -Aside from the above, there is no restriction on what can go in a macro -body. Parentheses need not balance. The body need not resemble valid C -code. (But 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 - -After the preprocessor expands a macro name, the macro's definition body is -appended to the front of the remaining input, and the check for macro calls -continues. Therefore, the macro body can contain calls to other macros. -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 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. -@xref{Cascaded Macros}. - -@node Argument Macros, Predefined, Simple Macros, Macros -@subsection Macros with Arguments -@cindex macros with argument -@cindex arguments in macro definitions -@cindex function-like macro - -A simple macro always stands for exactly the same text, each time it is -used. Macros can be more flexible when they accept @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{argument names} in parentheses after the name of the -macro. The argument names may be any valid C identifiers, separated by -commas and optionally whitespace. The open-parenthesis must follow the -macro name immediately, with no space in between. - -For 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 use a macro that expects arguments, you write the name of the macro -followed by a list of @dfn{actual arguments} in parentheses, separated by -commas. The number of actual arguments you give must match the number of -arguments the macro expects. 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 of the argument names of the macro is replaced, throughout the -macro definition, with the corresponding actual argument. 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 in the actual arguments must balance; a comma within -parentheses does not end an argument. However, there is no requirement -for 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 actual arguments are substituted into the macro body, the entire -result is appended to the front of the remaining input, and the check for -macro calls continues. Therefore, the actual arguments can contain calls -to other macros, either with or without arguments, or even to the same -macro. The macro body can also contain calls to other macros. 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 blank macro arguments -@cindex space as macro argument -If a macro @code{foo} takes one argument, and you want to supply an -empty argument, you must write at least some whitespace between the -parentheses, like this: @samp{foo ( )}. Just @samp{foo ()} is providing -no arguments, which is an error if @code{foo} expects an argument. But -@samp{foo0 ()} is the correct way to call a macro defined to take zero -arguments, like this: - -@example -#define foo0() @dots{} -@end example - -If you use the macro name followed by something other than an -open-parenthesis (after ignoring any spaces, tabs and comments that -follow), it is not a call to the macro, and the preprocessor does not -change what you have written. Therefore, it is possible for the same name -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). - -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}. - -You may not define the same name as both a simple macro and a macro with -arguments. - -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 about spaces 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 Predefined, Stringification, Argument Macros, Macros -@subsection Predefined Macros - -@cindex predefined macros -Several simple macros are predefined. You can use them without giving -definitions for them. 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 ANSI 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. - -@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{Combining Sources}. - -@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 @samp{"Jan 29 1987"} or @w{@samp{"Apr -1 1905"}}. - -@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 ANSI -Standard C. (Whether that is actually true depends on what C compiler -will operate on the output from the preprocessor.) - -@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. - -@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.3 is known to support a feature, you -can test for @code{__GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 6)}). -The last number, @samp{3} in the -example above, denotes the bugfix level of the compiler; no macro -contains this value. - -@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 draft ANSI standard for C++ used to require predefining this -variable. Though it is no longer required, GNU C++ continues to define -it, as do other popular C++ compilers. You can use @samp{__cplusplus} -to test whether a header is compiled by a C compiler or a C++ compiler. - -@item __STRICT_ANSI__ -@findex __STRICT_ANSI__ -This macro is defined if and only if the @samp{-ansi} switch 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 -ANSI 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 -as an argument when the C compiler was invoked. - -@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 every -end of file. For input files specified by command line arguments, -the nesting level is zero. - -@item __VERSION__ -@findex __VERSION__ -This macro expands to a string 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"}. The only reasonable use of this -macro is to incorporate it into a string constant. - -@item __OPTIMIZE__ -@findex __OPTIMIZE__ -This macro is defined in optimizing compilations. It causes certain -GNU header files to define alternative macro definitions for some -system library functions. It is unwise to 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__ -This macro is defined if and only if the data type @code{char} is -unsigned on the target machine. It exists to cause the standard -header file @file{limit.h} to work correctly. It is bad practice -to refer to this macro yourself; instead, refer to the standard -macros defined in @file{limit.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 describing the prefix applied to cpu -registers in assembler code. It can be used to write assembler code -that is usable in multiple environments. 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 string -@samp{"%"}. - -@item __USER_LABEL_PREFIX__ -@findex __USER_LABEL_PREFIX__ -This macro expands to a string describing the prefix applied to -user generated labels in assembler code. It can be used to write -assembler code that is usable in multiple environments. -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 string @samp{""}. -@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 -ANSI 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 ANSI 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 code fragment into a string constant -whose contents are the text for the code fragment. For example, -stringifying @samp{foo (z)} results in @samp{"foo (z)"}. - -In the C preprocessor, stringification is an option available when macro -arguments are substituted into the macro definition. In the body of the -definition, when an argument name appears, the character @samp{#} before -the name specifies stringification of the corresponding actual argument -when it is substituted at that point in the definition. The same argument -may be substituted in other places in the definition without -stringification if the argument name appears in those places with no -@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 actual argument for @samp{EXP} is substituted once as given, -into the @samp{if} statement, and once as 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 one macro argument -into one string constant: there is no way to combine the argument with -other text and then stringify it all together. But the example above shows -how an equivalent result can be obtained in ANSI Standard C using the -feature that adjacent string constants are concatenated as one 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 C 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 doublequote characters -around the fragment; it is necessary to put backslashes in front of all -doublequote characters, and all backslashes in 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 of 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 lexical units -into one longer one. Specifically, an actual argument to the macro can be -concatenated with another actual argument or with fixed text to produce -a longer name. The longer name might be the name of a function, -variable or 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 macro, you request concatenation with the special -operator @samp{##} in the macro body. When the macro is called, -after actual arguments are substituted, all @samp{##} operators are -deleted, and so is any whitespace next to them (including whitespace -that was part of an actual argument). The result is to concatenate -the syntactic tokens on either side of the @samp{##}. - -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. But 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. In some cases it is even -possible to piece together a string constant. However, two pieces of text -that don't together form a valid lexical unit cannot be concatenated. For -example, concatenation with @samp{x} on one side and @samp{+} on the other -is not meaningful because those two characters can't fit together in any -lexical unit of C. The ANSI standard says that such attempts at -concatenation are undefined, but in the GNU C preprocessor it is well -defined: it puts the @samp{x} and @samp{+} side by side with no particular -special results. - -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 lexical unit, but rather the beginning of a ``long'' space -character. Also, you can freely use comments next to a @samp{##} in a -macro definition, or in actual arguments that will be concatenated, because -the comments will be converted to spaces at first sight, and concatenation -will later discard the spaces. - -@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, Macro Pitfalls, 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 new definition 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. - -@item -Whitespace may be changed in the middle (but not inside strings). -However, it may not be eliminated entirely, and it may not be added -where there was no whitespace at all. -@end itemize - -Recall that a comment counts as whitespace. - -@node Macro Pitfalls,, Redefining, 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:: Actual 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 actual 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 -But 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. - -However, 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 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. But it looks like a -function call. So it minimizes confusion if you can use it like a function -call, writing a semicolon afterward, as in @samp{SKIP_SPACES (p, lim);} - -But 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 ANSI 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? - -But 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))}. - -It is not clear that this behavior would ever be useful, but it is specified -by the ANSI 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 -actual arguments, is scanned over again for macro calls to be expanded. - -What really happens is more subtle: first each actual argument text is scanned -separately for macro calls. Then the results of this 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 actual arguments are scanned @emph{twice} to expand -macro calls in them. - -Most of the time, this has no effect. If the actual 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 actual 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 actual 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. But 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 as -written, in un-prescanned form. The same actual argument would be used in -prescanned 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 actual -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 actual 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. - -But 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))}. But 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 actual 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 - -Traditional macro processing carries forward all newlines in macro -arguments into the expansion of the macro. This means that, if some of -the arguments are substituted more than once, or not at all, or out of -order, newlines can be duplicated, lost, or moved around within the -expansion. If the expansion consists of multiple statements, then the -effect is to distort the line numbers of some of these statements. The -result can be incorrect line numbers, in error messages or displayed in -a debugger. - -The GNU C preprocessor operating in ANSI C mode adjusts appropriately -for multiple use of an argument---the first use expands all the -newlines, and subsequent uses of the same argument produce no newlines. -But even in this mode, it can produce incorrect line numbering if -arguments are used out of order, or not used at all. - -Here is an example illustrating this problem: - -@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 four, even though the statement text -comes from line five. - -@node Conditionals, Combining Sources, 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. -* Assertions:: How and why to use assertions. -* 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 ANSI 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{||}). - -@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. Contrariwise, 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, -singlequote characters must balance. But comments often contain -unbalanced singlequote 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} 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. For 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. - -@findex #ifdef -@findex #ifndef -Conditionals that test whether just one name 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 Assertions -@subsection 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. 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 assertion is with -@samp{#unassert}. @samp{#unassert} has the same syntax as -@samp{#assert}. You can also remove all assertions about -@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 #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 rest of the line that follows @samp{#error} is used as the -error message. - -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 rest of -the line that follows @samp{#warning} is used as the warning message. - -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 Combining Sources, Other Directives, Conditionals, 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 doublequote 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, Combining Sources, Top -@section Miscellaneous Preprocessing Directives - -@cindex null directive -This section describes three additional preprocessing directives. They are -not very useful, but are mentioned for completeness. - -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. - -@findex #pragma -The ANSI standard specifies that the @samp{#pragma} directive has an -arbitrary, implementation-defined effect. In the GNU C preprocessor, -@samp{#pragma} directives are not used, except for @samp{#pragma once} -(@pxref{Once-Only}). However, they are left in the preprocessor output, -so they are available to the compilation pass. - -@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. - -@node Output, Invocation, 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. Whitespace within a line is not altered; -however, a space is inserted after the expansions of most macro calls. - -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 middle of the input (but never -within a string or character constant). 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 Invocation, Concept Index, Output, 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. - -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 @var{outfile} or both file names are omitted, -the standard output and standard input are used for the omitted file names. - -@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 (@pxref{Output}). 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. - -@item -C -@findex -C -Do not discard comments: pass them through to the output file. -Comments appearing in arguments of a macro call will be copied to the -output before the expansion of the macro call. - -@item -traditional -@findex -traditional -Try to imitate the behavior of old-fashioned C, as opposed to ANSI C. - -@itemize @bullet -@item -Traditional macro expansion pays no attention to singlequote or -doublequote 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 ANSI -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 ANSI C.) - -@item -Traditionally, @samp{\} inside a macro argument suppresses the syntactic -significance of the following character. -@end itemize - -@item -trigraphs -@findex -trigraphs -Process ANSI standard trigraph sequences. These are three-character -sequences, all starting with @samp{??}, that are defined by ANSI C to -stand for single characters. For example, @samp{??/} stands for -@samp{\}, so @samp{'??/n'} is a character constant for a newline. -Strictly speaking, the GNU C preprocessor does not support all -programs in ANSI Standard C unless @samp{-trigraphs} is used, but if -you ever notice the difference it will be with relief. - -You don't want to know any more about trigraphs. - -@item -pedantic -@findex -pedantic -Issue warnings required by the ANSI 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 -Wtrigraphs -@findex -Wtrigraphs -Warn if any trigraphs are encountered (assuming they are enabled). - -@item -Wcomment -@findex -Wcomment -@ignore -@c "Not worth documenting" both singular and plural forms of this -@c option, per RMS. But also unclear which is better; hence may need to -@c switch this at some future date. pesch@cygnus.com, 2jan92. -@itemx -Wcomments -(Both forms have the same effect). -@end ignore -Warn whenever a comment-start sequence @samp{/*} appears in a comment. - -@item -Wall -@findex -Wall -Requests both @samp{-Wtrigraphs} and @samp{-Wcomment} (but not -@samp{-Wtraditional}). - -@item -Wtraditional -@findex -Wtraditional -Warn about certain constructs that behave differently in traditional and -ANSI C. - -@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. - -@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 libg++.) - -@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. - -@item -U @var{name} -@findex -U -Do not predefine @var{name}. If both @samp{-U} and @samp{-D} are -specified for one name, the @samp{-U} beats the @samp{-D} and the name -is not predefined. - -@item -undef -@findex -undef -Do not predefine any nonstandard macros. - -@item -A @var{predicate}(@var{answer}) -@findex -A -Make an assertion with the predicate @var{predicate} and answer -@var{answer}. @xref{Assertions}. - -@noindent -You can use @samp{-A-} to disable all predefined assertions; it also -undefines all predefined macros that identify the type of target system. - -@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 -M [-MG] -@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. If there are many included files then the -rule is split into several lines using @samp{\}-newline. - -@samp{-MG} says to treat missing header files as generated files and assume -they live in the same directory as the source file. It must be specified -in addition to @samp{-M}. - -This feature is used in automatic updating of makefiles. - -@item -MM [-MG] -@findex -MM -Like @samp{-M} but mention only the files included with @samp{#include -"@var{file}"}. System header files included with @samp{#include -<@var{file}>} are omitted. - -@item -MD @var{file} -@findex -MD -Like @samp{-M} but the dependency information is written to @var{file}. -This is in addition to compiling the file as specified---@samp{-MD} does -not inhibit ordinary compilation the way @samp{-M} does. - -When invoking gcc, do not specify the @var{file} argument. -Gcc will create file names made by replacing ".c" with ".d" at -the end of the input file names. - -In Mach, you can use the utility @code{md} to merge multiple dependency -files into a single dependency file suitable for using with the @samp{make} -command. - -@item -MMD @var{file} -@findex -MMD -Like @samp{-MD} except mention only user header files, not system -header files. - -@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, discarding the resulting output, before -processing the regular input file. Because the output generated from -@var{file} is discarded, the only 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, -before processing the regular input file. - -@item -idirafter @var{dir} -@findex -idirafter -@cindex second include path -Add the directory @var{dir} to the second include path. 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. - -@item -iwithprefix @var{dir} -@findex -iwithprefix -Add a directory to the second include path. 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. - -@item -lang-c -@itemx -lang-c89 -@itemx -lang-c++ -@itemx -lang-objc -@itemx -lang-objc++ -@findex -lang-c -@findex -lang-c89 -@findex -lang-c++ -@findex -lang-objc -@findex -lang-objc++ -Specify the source language. @samp{-lang-c} is the default; it -allows recognition of C++ comments (comments that begin with -@samp{//} and end at end of line), since this is -a common feature and it will most likely be in the next C standard. -@samp{-lang-c89} disables recognition of C++ comments. @samp{-lang-c++} -handles C++ comment syntax and includes extra default include -directories for C++. @samp{-lang-objc} enables the Objective C -@samp{#import} directive. @samp{-lang-objc++} enables both C++ and Objective C -extensions. - -These options are generated by the compiler driver @code{gcc}, but not -passed from the @samp{gcc} command line unless you use the driver's -@samp{-Wp} option. - -@item -lint -Look for commands to the program checker @code{lint} embedded in -comments, and emit them preceded by @samp{#pragma lint}. For example, -the comment @samp{/* NOTREACHED */} becomes @samp{#pragma lint -NOTREACHED}. - -This option is available only when you call @code{cpp} directly; -@code{gcc} will not pass it from its command line. - -@item -$ -@findex -$ -Forbid the use of @samp{$} in identifiers. This is required for ANSI -conformance. @code{gcc} automatically supplies this option to the -preprocessor if you specify @samp{-ansi}, but @code{gcc} doesn't -recognize the @samp{-$} option itself---to use it without the other -effects of @samp{-ansi}, you must call the preprocessor directly. - -@end table - -@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