2968 lines
109 KiB
Plaintext
2968 lines
109 KiB
Plaintext
\input texinfo
|
|
@setfilename cpp.info
|
|
@settitle The C Preprocessor
|
|
|
|
@ifinfo
|
|
@dircategory Programming
|
|
@direntry
|
|
* Cpp: (cpp). The GNU C preprocessor.
|
|
@end direntry
|
|
@end ifinfo
|
|
|
|
@c @smallbook
|
|
@c @cropmarks
|
|
@c @finalout
|
|
@setchapternewpage odd
|
|
@ifinfo
|
|
This file documents the GNU C Preprocessor.
|
|
|
|
Copyright 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1997, 1998 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 September 1998
|
|
@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-1998
|
|
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}.
|
|
|
|
The C preprocessor is designed for C-like languages; you may run into
|
|
problems if you apply it to other kinds of languages, because it assumes
|
|
that it is dealing with C@. For example, the C preprocessor sometimes
|
|
outputs extra white space to avoid inadvertent C token concatenation,
|
|
and this may cause problems with other languages.
|
|
|
|
@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 <x/*y>} 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{sys/signal.h}, but the version of @file{/usr/include/sys/signal.h}
|
|
on a particular system doesn't do what the application program expects.
|
|
It might be convenient to define a ``local'' version, perhaps under the
|
|
name @file{/usr/local/include/sys/signal.h}, to override or add to the
|
|
one supplied by the system.
|
|
|
|
You can do this by compiling with the option @samp{-I.}, and
|
|
writing a file @file{sys/signal.h} that does what the application
|
|
program expects. But making this file include the standard
|
|
@file{sys/signal.h} is not so easy---writing @samp{#include
|
|
<sys/signal.h>} in that file doesn't work, because it includes your own
|
|
version of the file, not the standard system version. Used in that file
|
|
itself, this leads to an infinite recursion and a fatal error in
|
|
compilation.
|
|
|
|
@samp{#include </usr/include/sys/signal.h>} would find the proper file,
|
|
but that is not clean, since it makes an assumption about where the
|
|
system header file is found. This is bad for maintenance, since it
|
|
means that any change in where the system's header files are kept
|
|
requires a change somewhere else.
|
|
|
|
@findex #include_next
|
|
The clean way to solve this problem is to use
|
|
@samp{#include_next}, which means, ``Include the @emph{next} file with
|
|
this name.'' This directive works like @samp{#include} except in
|
|
searching for the specified file: it starts searching the list of header
|
|
file directories @emph{after} the directory in which the current file
|
|
was found.
|
|
|
|
Suppose you specify @samp{-I /usr/local/include}, and the list of
|
|
directories to search also includes @file{/usr/include}; and suppose
|
|
both directories contain @file{sys/signal.h}. Ordinary
|
|
@samp{#include <sys/signal.h>} finds the file under
|
|
@file{/usr/local/include}. If that file contains @samp{#include_next
|
|
<sys/signal.h>}, it starts searching after that directory, and finds the
|
|
file in @file{/usr/include}.
|
|
|
|
@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 @w{@samp{"Feb 1 1996"}}.
|
|
@c After reformatting the above, check that the date remains `Feb 1 1996',
|
|
@c all on one line, with two spaces between the `Feb' and the `1'.
|
|
|
|
@item __TIME__
|
|
@findex __TIME__
|
|
This macro expands to a string constant that describes the time at
|
|
which the preprocessor is being run. The string constant contains
|
|
eight characters and looks like @samp{"23:59:01"}.
|
|
|
|
@item __STDC__
|
|
@findex __STDC__
|
|
This macro expands to the constant 1, to signify that this is ANSI
|
|
Standard C@. (Whether that is actually true depends on what C compiler
|
|
will operate on the output from the preprocessor.)
|
|
|
|
On some hosts, system include files use a different convention, where
|
|
@samp{__STDC__} is normally 0, but is 1 if the user specifies strict
|
|
conformance to the C Standard. The preprocessor follows the host convention
|
|
when processing system include files, but when processing user files it follows
|
|
the usual GNU C convention.
|
|
|
|
This macro is not defined if the @samp{-traditional} option is used.
|
|
|
|
@item __STDC_VERSION__
|
|
@findex __STDC_VERSION__
|
|
This macro expands to the C Standard's version number,
|
|
a long integer constant of the form @samp{@var{yyyy}@var{mm}L}
|
|
where @var{yyyy} and @var{mm} are the year and month of the Standard version.
|
|
This signifies which version of the C Standard the preprocessor conforms to.
|
|
Like @samp{__STDC__}, whether this version number is accurate
|
|
for the entire implementation depends on what C compiler
|
|
will operate on the output from the preprocessor.
|
|
|
|
This macro is not defined if the @samp{-traditional} option is used.
|
|
|
|
@item __GNUC__
|
|
@findex __GNUC__
|
|
This macro is defined if and only if this is GNU C@. This macro is
|
|
defined only when the entire GNU C compiler is in use; if you invoke the
|
|
preprocessor directly, @samp{__GNUC__} is undefined. The value
|
|
identifies the major version number of GNU CC (@samp{1} for GNU CC
|
|
version 1, which is now obsolete, and @samp{2} for version 2).
|
|
|
|
@item __GNUC_MINOR__
|
|
@findex __GNUC_MINOR__
|
|
The macro contains the minor version number of the compiler. This can
|
|
be used to work around differences between different releases of the
|
|
compiler (for example, if gcc 2.6.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__
|
|
GNU C defines this macro 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 constant which describes the version number of
|
|
GNU C@. The string is normally a sequence of decimal numbers separated
|
|
by periods, such as @samp{"2.6.0"}.
|
|
|
|
@item __OPTIMIZE__
|
|
@findex __OPTIMIZE__
|
|
GNU CC defines this macro in optimizing compilations. It causes certain
|
|
GNU header files to define alternative macro definitions for some system
|
|
library functions. You should not refer to or test the definition of
|
|
this macro unless you make very sure that programs will execute with the
|
|
same effect regardless.
|
|
|
|
@item __CHAR_UNSIGNED__
|
|
@findex __CHAR_UNSIGNED__
|
|
GNU C defines this macro if and only if the data type @code{char} is
|
|
unsigned on the target machine. It exists to cause the standard header
|
|
file @file{limits.h} to work correctly. You should not refer to this
|
|
macro yourself; instead, refer to the standard macros defined in
|
|
@file{limits.h}. The preprocessor uses this macro to determine whether
|
|
or not to sign-extend large character constants written in octal; see
|
|
@ref{#if Directive,,The @samp{#if} Directive}.
|
|
|
|
@item __REGISTER_PREFIX__
|
|
@findex __REGISTER_PREFIX__
|
|
This macro expands to a string (not a string constant) describing the
|
|
prefix applied to CPU registers in assembler code. You can use it to
|
|
write assembler code that is usable in multiple environments. For
|
|
example, in the @samp{m68k-aout} environment it expands to the null
|
|
string, but in the @samp{m68k-coff} environment it expands to the string
|
|
@samp{%}.
|
|
|
|
@item __USER_LABEL_PREFIX__
|
|
@findex __USER_LABEL_PREFIX__
|
|
Similar to @code{__REGISTER_PREFIX__}, but describes the prefix applied
|
|
to user generated labels in assembler code. For example, in the
|
|
@samp{m68k-aout} environment it expands to the string @samp{_}, but in
|
|
the @samp{m68k-coff} environment it expands to the null string. This
|
|
does not work with the @samp{-mno-underscores} option that the i386
|
|
OSF/rose and m88k targets provide nor with the @samp{-mcall*} options of
|
|
the rs6000 System V Release 4 target.
|
|
@end table
|
|
|
|
@node Nonstandard Predefined,, Standard Predefined, Predefined
|
|
@subsubsection Nonstandard Predefined Macros
|
|
|
|
The C preprocessor normally has several predefined macros that vary between
|
|
machines because their purpose is to indicate what type of system and
|
|
machine is in use. This manual, being for all systems and machines, cannot
|
|
tell you exactly what their names are; instead, we offer a list of some
|
|
typical ones. You can use @samp{cpp -dM} to see the values of
|
|
predefined macros; see @ref{Invocation}.
|
|
|
|
Some nonstandard predefined macros describe the operating system in use,
|
|
with more or less specificity. For example,
|
|
|
|
@table @code
|
|
@item unix
|
|
@findex unix
|
|
@samp{unix} is normally predefined on all Unix systems.
|
|
|
|
@item BSD
|
|
@findex BSD
|
|
@samp{BSD} is predefined on recent versions of Berkeley Unix
|
|
(perhaps only in version 4.3).
|
|
@end table
|
|
|
|
Other nonstandard predefined macros describe the kind of CPU, with more or
|
|
less specificity. For example,
|
|
|
|
@table @code
|
|
@item vax
|
|
@findex vax
|
|
@samp{vax} is predefined on Vax computers.
|
|
|
|
@item mc68000
|
|
@findex mc68000
|
|
@samp{mc68000} is predefined on most computers whose CPU is a Motorola
|
|
68000, 68010 or 68020.
|
|
|
|
@item m68k
|
|
@findex m68k
|
|
@samp{m68k} is also predefined on most computers whose CPU is a 68000,
|
|
68010 or 68020; however, some makers use @samp{mc68000} and some use
|
|
@samp{m68k}. Some predefine both names. What happens in GNU C
|
|
depends on the system you are using it on.
|
|
|
|
@item M68020
|
|
@findex M68020
|
|
@samp{M68020} has been observed to be predefined on some systems that
|
|
use 68020 CPUs---in addition to @samp{mc68000} and @samp{m68k}, which
|
|
are less specific.
|
|
|
|
@item _AM29K
|
|
@findex _AM29K
|
|
@itemx _AM29000
|
|
@findex _AM29000
|
|
Both @samp{_AM29K} and @samp{_AM29000} are predefined for the AMD 29000
|
|
CPU family.
|
|
|
|
@item ns32000
|
|
@findex ns32000
|
|
@samp{ns32000} is predefined on computers which use the National
|
|
Semiconductor 32000 series CPU.
|
|
@end table
|
|
|
|
Yet other nonstandard predefined macros describe the manufacturer of
|
|
the system. For example,
|
|
|
|
@table @code
|
|
@item sun
|
|
@findex sun
|
|
@samp{sun} is predefined on all models of Sun computers.
|
|
|
|
@item pyr
|
|
@findex pyr
|
|
@samp{pyr} is predefined on all models of Pyramid computers.
|
|
|
|
@item sequent
|
|
@findex sequent
|
|
@samp{sequent} is predefined on all models of Sequent computers.
|
|
@end table
|
|
|
|
These predefined symbols are not only nonstandard, they are contrary to the
|
|
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.
|
|
|
|
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. The line must consist of complete tokens.
|
|
|
|
You would use @samp{#error} inside of a conditional that detects a
|
|
combination of parameters which you know the program does not properly
|
|
support. For example, if you know that the program will not run
|
|
properly on a Vax, you might write
|
|
|
|
@smallexample
|
|
@group
|
|
#ifdef __vax__
|
|
#error "Won't work on Vaxen. See comments at get_last_object."
|
|
#endif
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
@xref{Nonstandard Predefined}, for why this works.
|
|
|
|
If you have several configuration parameters that must be set up by
|
|
the installation in a consistent way, you can use conditionals to detect
|
|
an inconsistency and report it with @samp{#error}. For example,
|
|
|
|
@smallexample
|
|
#if HASH_TABLE_SIZE % 2 == 0 || HASH_TABLE_SIZE % 3 == 0 \
|
|
|| HASH_TABLE_SIZE % 5 == 0
|
|
#error HASH_TABLE_SIZE should not be divisible by a small prime
|
|
#endif
|
|
@end smallexample
|
|
|
|
@findex #warning
|
|
The directive @samp{#warning} is like the directive @samp{#error}, but causes
|
|
the preprocessor to issue a warning and continue preprocessing. The 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 effect of the @samp{#pragma}
|
|
directive is implementation-defined. 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, unless @samp{-traditional} is used, spaces may be inserted into
|
|
the expansions of macro calls to prevent tokens from being concatenated.
|
|
|
|
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
|
|
|
|
@cindex Fortran
|
|
@cindex unterminated
|
|
Use the @samp{-traditional} option when preprocessing Fortran code,
|
|
so that singlequotes and doublequotes
|
|
within Fortran comment lines
|
|
(which are generally not recognized as such by the preprocessor)
|
|
do not cause diagnostics
|
|
about unterminated character or string constants.
|
|
|
|
However, this option does not prevent diagnostics
|
|
about unterminated comments
|
|
when a C-style comment appears to start, but not end,
|
|
within Fortran-style commentary.
|
|
|
|
So, the following Fortran comment lines are accepted with
|
|
@samp{-traditional}:
|
|
|
|
@smallexample
|
|
C This isn't an unterminated character constant
|
|
C Neither is "20000000000, an octal constant
|
|
C in some dialects of Fortran
|
|
@end smallexample
|
|
|
|
However, this type of comment line will likely produce a diagnostic,
|
|
or at least unexpected output from the preprocessor,
|
|
due to the unterminated comment:
|
|
|
|
@smallexample
|
|
C Some Fortran compilers accept /* as starting
|
|
C an inline comment.
|
|
@end smallexample
|
|
|
|
@cindex g77
|
|
Note that @code{g77} automatically supplies
|
|
the @samp{-traditional} option
|
|
when it invokes the preprocessor.
|
|
However, a future version of @code{g77}
|
|
might use a different, more-Fortran-aware preprocessor
|
|
in place of @code{cpp}.
|
|
|
|
@item -trigraphs
|
|
@findex -trigraphs
|
|
Process 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. Currently this only works if you
|
|
have turned trigraphs on with @samp{-trigraphs} or @samp{-ansi}; in the
|
|
future this restriction will be removed.
|
|
|
|
@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 @samp{/*}
|
|
comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
|
|
|
|
@item -Wall
|
|
@findex -Wall
|
|
Requests both @samp{-Wtrigraphs} and @samp{-Wcomment} (but not
|
|
@samp{-Wtraditional} or @samp{-Wundef}).
|
|
|
|
@item -Wtraditional
|
|
@findex -Wtraditional
|
|
Warn about certain constructs that behave differently in traditional and
|
|
ANSI C@.
|
|
|
|
@item -Wundef
|
|
@findex -Wundef
|
|
Warn if an undefined identifier is evaluated in an @samp{#if} directive.
|
|
|
|
@item -I @var{directory}
|
|
@findex -I
|
|
Add the directory @var{directory} to the head of the list of
|
|
directories to be searched for header files (@pxref{Include Syntax}).
|
|
This can be used to override a system header file, substituting your
|
|
own version, since these directories are searched before the system
|
|
header file directories. If you use more than one @samp{-I} option,
|
|
the directories are scanned in left-to-right order; the standard
|
|
system directories come after.
|
|
|
|
@item -I-
|
|
Any directories specified with @samp{-I} options before the @samp{-I-}
|
|
option are searched only for the case of @samp{#include "@var{file}"};
|
|
they are not searched for @samp{#include <@var{file}>}.
|
|
|
|
If additional directories are specified with @samp{-I} options after
|
|
the @samp{-I-}, these directories are searched for all @samp{#include}
|
|
directives.
|
|
|
|
In addition, the @samp{-I-} option inhibits the use of the current
|
|
directory as the first search directory for @samp{#include "@var{file}"}.
|
|
Therefore, the current directory is searched only if it is requested
|
|
explicitly with @samp{-I.}. Specifying both @samp{-I-} and @samp{-I.}
|
|
allows you to control precisely which directories are searched before
|
|
the current one and which are searched after.
|
|
|
|
@item -nostdinc
|
|
@findex -nostdinc
|
|
Do not search the standard system directories for header files.
|
|
Only the directories you have specified with @samp{-I} options
|
|
(and the current directory, if appropriate) are searched.
|
|
|
|
@item -nostdinc++
|
|
@findex -nostdinc++
|
|
Do not search for header files in the C++-specific standard directories,
|
|
but do still search the other standard directories.
|
|
(This option is used when building the C++ library.)
|
|
|
|
@item -remap
|
|
@findex -remap
|
|
When searching for a header file in a directory, remap file names if a
|
|
file named @file{header.gcc} exists in that directory. This can be used
|
|
to work around limitations of file systems with file name restrictions.
|
|
The @file{header.gcc} file should contain a series of lines with two
|
|
tokens on each line: the first token is the name to map, and the second
|
|
token is the actual name to use.
|
|
|
|
@item -D @var{name}
|
|
@findex -D
|
|
Predefine @var{name} as a macro, with definition @samp{1}.
|
|
|
|
@item -D @var{name}=@var{definition}
|
|
Predefine @var{name} as a macro, with definition @var{definition}.
|
|
There are no restrictions on the contents of @var{definition}, but if
|
|
you are invoking the preprocessor from a shell or shell-like program you
|
|
may need to use the shell's quoting syntax to protect characters such as
|
|
spaces that have a meaning in the shell syntax. If you use more than
|
|
one @samp{-D} for the same @var{name}, the rightmost definition takes
|
|
effect.
|
|
|
|
@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 -gcc
|
|
@findex -gcc
|
|
Define the macros @var{__GNUC__} and @var{__GNUC_MINOR__}. These are
|
|
defined automatically when you use @samp{gcc -E}; you can turn them off
|
|
in that case with @samp{-no-gcc}.
|
|
|
|
@item -A @var{predicate}(@var{answer})
|
|
@findex -A
|
|
Make an assertion with the predicate @var{predicate} and answer
|
|
@var{answer}. @xref{Assertions}.
|
|
|
|
@noindent
|
|
You can use @samp{-A-} to disable all predefined assertions; it also
|
|
undefines all predefined macros and all macros that preceded it on the
|
|
command line.
|
|
|
|
@item -dM
|
|
@findex -dM
|
|
Instead of outputting the result of preprocessing, output a list of
|
|
@samp{#define} directives for all the macros defined during the
|
|
execution of the preprocessor, including predefined macros. This gives
|
|
you a way of finding out what is predefined in your version of the
|
|
preprocessor; assuming you have no file @samp{foo.h}, the command
|
|
|
|
@example
|
|
touch foo.h; cpp -dM foo.h
|
|
@end example
|
|
|
|
@noindent
|
|
will show the values of any predefined macros.
|
|
|
|
@item -dD
|
|
@findex -dD
|
|
Like @samp{-dM} except in two respects: it does @emph{not} include the
|
|
predefined macros, and it outputs @emph{both} the @samp{#define}
|
|
directives and the result of preprocessing. Both kinds of output go to
|
|
the standard output file.
|
|
|
|
@item -dI
|
|
@findex -dI
|
|
Output @samp{#include} directives in addition to the result of preprocessing.
|
|
|
|
@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 @code{gcc}, do not specify the @var{file} argument.
|
|
@code{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 -x c
|
|
@itemx -x c++
|
|
@itemx -x objective-c
|
|
@itemx -x assembler-with-cpp
|
|
@findex -x c
|
|
@findex -x objective-c
|
|
@findex -x assembler-with-cpp
|
|
Specify the source language: C, C++, Objective-C, or assembly. This has
|
|
nothing to do with standards conformance or extensions; it merely
|
|
selects which base syntax to expect. If you give none of these options,
|
|
cpp will deduce the language from the extension of the source file:
|
|
@samp{.c}, @samp{.cc}, @samp{.m}, or @samp{.S}. Some other common
|
|
extensions for C++ and assembly are also recognized. If cpp does not
|
|
recognize the extension, it will treat the file as C; this is the most
|
|
generic mode.
|
|
|
|
@strong{Note:} Previous versions of cpp accepted a @samp{-lang} option
|
|
which selected both the language and the standards conformance level.
|
|
This option has been removed, because it conflicts with the @samp{-l}
|
|
option.
|
|
|
|
@item -std=@var{standard}
|
|
@itemx -ansi
|
|
@findex -std
|
|
@findex -ansi
|
|
Specify the standard to which the code should conform. Currently cpp
|
|
only knows about the standards for C; other language standards will be
|
|
added in the future.
|
|
|
|
@var{standard}
|
|
may be one of:
|
|
@table @code
|
|
@item iso9899:1990
|
|
The ISO C standard from 1990.
|
|
|
|
@item iso9899:199409
|
|
@itemx c89
|
|
The 1990 C standard, as amended in 1994. @samp{c89} is the customary
|
|
shorthand for this version of the standard.
|
|
|
|
The @samp{-ansi} option is equivalent to @samp{-std=c89}.
|
|
|
|
@item iso9899:199x
|
|
@itemx c9x
|
|
The revised ISO C standard, which is expected to be promulgated some
|
|
time in 1999. It has not been approved yet, hence the @samp{x}.
|
|
|
|
@item gnu89
|
|
The 1990 C standard plus GNU extensions. This is the default.
|
|
|
|
@item gnu9x
|
|
The 199x C standard plus GNU extensions.
|
|
@end table
|
|
|
|
@item -Wp,-lint
|
|
@findex -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}.
|
|
|
|
Because of the clash with @samp{-l}, you must use the awkward syntax
|
|
above. In a future release, this option will be replaced by
|
|
@samp{-flint} or @samp{-Wlint}; we are not sure which yet.
|
|
|
|
@item -$
|
|
@findex -$
|
|
Forbid the use of @samp{$} in identifiers. The C standard does not
|
|
permit this, but it is a common extension.
|
|
|
|
@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
|