+2001-01-12 Joseph S. Myers <jsm28@cam.ac.uk>
+
+ * cpp.texi, extend.texi, gcc.texi, install.texi, invoke.texi,
+ tm.texi: Consistently refer to ISO C instead of ANSI C. Refer to
+ -std options alongside references to -ansi. Update some
+ documentation for C99.
+ * cpp.1: Regenerate.
+
2001-01-12 Andreas Jaeger <aj@suse.de>
* haifa-sched.c (restore_line_notes): Remove argument block B
.\" Automatically generated by Pod::Man version 1.1
-.\" Wed Jan 3 20:06:19 2001
+.\" Fri Jan 12 18:47:56 2001
.\"
.\" Standard preamble:
.\" ======================================================================
.\" ======================================================================
.\"
.IX Title "CPP 1"
-.TH CPP 1 "gcc-2.97" "2001-01-03" "GNU"
+.TH CPP 1 "gcc-2.97" "2001-01-12" "GNU"
.UC
.SH "NAME"
cpp \- The C Preprocessor
[\fB\-W\fR\fIwarn\fR...] [\fB\-I\fR\fIdir\fR...]
[\fB\-D\fR\fImacro\fR[=\fIdefn\fR]...] [\fB\-U\fR\fImacro\fR]
[\fB\-A\fR\fIpredicate\fR(\fIanswer\fR)]
- [\fB\-M\fR|\fB\-MM\fR|\fB\-MD\fR|\fB\-MMD\fR [\fB\-MG\fR]]
+ [\fB\-M\fR|\fB\-MM\fR][\fB\-MG\fR][\fB\-MF\fR\fIfilename\fR]
+ [\fB\-MP\fR][\fB\-MQ\fR\fItarget\fR...][\fB\-MT\fR\fItarget\fR...]
[\fB\-x\fR \fIlanguage\fR] [\fB\-std=\fR\fIstandard\fR]
\fIinfile\fR \fIoutfile\fR
.PP
Do not search the standard system directories for header files.
Only the directories you have specified with \fB\-I\fR options
(and the current directory, if appropriate) are searched.
+.Sp
+By using both \fB\-nostdinc\fR and \fB\-I-\fR, you can limit the include-file
+search path to only those directories you specify explicitly.
.Ip "\fB\-nostdinc++\fR" 4
.IX Item "-nostdinc++"
Do not search for header files in the \*(C+\-specific standard directories,
spaces that have a meaning in the shell syntax. If you use more than
one \fB\-D\fR for the same \fIname\fR, the rightmost definition takes
effect.
+.Sp
+Any \fB\-D\fR and \fB\-U\fR options on the command line are processed in
+order, and always before \fB\-imacros\fR \fIfile\fR, regardless of the
+order in which they are written.
.Ip "\fB\-U\fR \fIname\fR" 4
.IX Item "-U name"
-Do not predefine \fIname\fR. If both \fB\-U\fR and \fB\-D\fR are
-specified for one name, whichever one appears later on the command line
-wins.
+Do not predefine \fIname\fR.
+.Sp
+Any \fB\-D\fR and \fB\-U\fR options on the command line are processed in
+order, and always before \fB\-imacros\fR \fIfile\fR, regardless of the
+order in which they are written.
.Ip "\fB\-undef\fR" 4
.IX Item "-undef"
Do not predefine any nonstandard macros.
.IX Item "-dI"
Output \fB#include\fR directives in addition to the result of
preprocessing.
-.Ip "\fB\-M [\-MG]\fR" 4
-.IX Item "-M [-MG]"
+.Ip "\fB\-M\fR" 4
+.IX Item "-M"
Instead of outputting the result of preprocessing, output a rule
suitable for \f(CW\*(C`make\*(C'\fR describing the dependencies of the main source
file. The preprocessor outputs one \f(CW\*(C`make\*(C'\fR 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 \fB\e\fR\-newline.
-.Sp
-\&\fB\-MG\fR 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 \fB\-M\fR.
-.Sp
-This feature is used in automatic updating of makefiles.
-.Ip "\fB\-MM [\-MG]\fR" 4
-.IX Item "-MM [-MG]"
-Like \fB\-M\fR but mention only the files included with \fB#include
+.Ip "\fB\-MM\fR" 4
+.IX Item "-MM"
+Like \fB\-M\fR, but mention only the files included with \fB#include
"\fR\fIfile\fR\fB"\fR. System header files included with \fB#include
<\fR\fIfile\fR\fB>\fR are omitted.
-.Ip "\fB\-MD\fR \fIfile\fR" 4
-.IX Item "-MD file"
-Like \fB\-M\fR but the dependency information is written to \fIfile\fR.
-This is in addition to compiling the file as specified \-\-\- \fB\-MD\fR
-does not inhibit ordinary compilation the way \fB\-M\fR does.
+.Ip "\fB\-MF\fR \fIfile\fR" 4
+.IX Item "-MF file"
+When used with \fB\-M\fR or \fB\-MM\fR, specifies a file to write the
+dependencies to. This allows the preprocessor to write the preprocessed
+file to stdout normally. If no \fB\-MF\fR switch is given, \s-1CPP\s0 sends
+the rules to stdout and suppresses normal preprocessed output.
+.Ip "\fB\-MG\fR" 4
+.IX Item "-MG"
+When used with \fB\-M\fR or \fB\-MM\fR, \fB\-MG\fR says to treat missing
+header files as generated files and assume they live in the same
+directory as the source file. It suppresses preprocessed output, as a
+missing header file is ordinarily an error.
+.Sp
+This feature is used in automatic updating of makefiles.
+.Ip "\fB\-MP\fR" 4
+.IX Item "-MP"
+This option instructs \s-1CPP\s0 to add a phony target for each dependency
+other than the main file, causing each to depend on nothing. These
+dummy rules work around errors \f(CW\*(C`make\*(C'\fR gives if you remove header
+files without updating the \f(CW\*(C`Makefile\*(C'\fR to match.
+.Sp
+This is typical output:\-
+.Sp
+.Vb 1
+\& /tmp/test.o: /tmp/test.c /tmp/test.h
+.Ve
+.Vb 1
+\& /tmp/test.h:
+.Ve
+.Ip "\fB\-MQ\fR \fItarget\fR" 4
+.IX Item "-MQ target"
+.PD 0
+.Ip "\fB\-MT\fR \fItarget\fR" 4
+.IX Item "-MT target"
+.PD
+By default \s-1CPP\s0 uses the main file name, including any path, and appends
+the object suffix, normally ``.o'', to it to obtain the name of the
+target for dependency generation. With \fB\-MT\fR you can specify a
+target yourself, overriding the default one.
+.Sp
+If you want multiple targets, you can specify them as a single argument
+to \fB\-MT\fR, or use multiple \fB\-MT\fR options.
.Sp
-When invoking \f(CW\*(C`gcc\*(C'\fR, do not specify the \fIfile\fR argument.
-\&\f(CW\*(C`gcc\*(C'\fR will create file names made by replacing \*(L".c\*(R" with \*(L".d\*(R" at
-the end of the input file names.
+The targets you specify are output in the order they appear on the
+command line. \fB\-MQ\fR is identical to \fB\-MT\fR, except that the
+target name is quoted for Make, but with \fB\-MT\fR it isn't. For
+example, \-MT '$(objpfx)foo.o' gives
.Sp
-In Mach, you can use the utility \f(CW\*(C`md\*(C'\fR to merge multiple dependency
-files into a single dependency file suitable for using with the
-\&\fBmake\fR command.
-.Ip "\fB\-MMD\fR \fIfile\fR" 4
-.IX Item "-MMD file"
-Like \fB\-MD\fR except mention only user header files, not system
-header files.
+.Vb 1
+\& $(objpfx)foo.o: /tmp/foo.c
+.Ve
+but \-MQ '$(objpfx)foo.o' gives
+.Sp
+.Vb 1
+\& $$(objpfx)foo.o: /tmp/foo.c
+.Ve
+The default target is automatically quoted, as if it were given with
+\&\fB\-MQ\fR.
.Ip "\fB\-H\fR" 4
.IX Item "-H"
Print the name of each header file used, in addition to other normal
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996,
-1997, 1998, 1999, 2000
+1997, 1998, 1999, 2000, 2001
Free Software Foundation, Inc.
.PP
Permission is granted to make and distribute verbatim copies of
@titlepage
@c @finalout
@title The C Preprocessor
-@subtitle Last revised November 2000
+@subtitle Last revised January 2001
@subtitle for GCC version 2
@author Richard M. Stallman
@page
@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.
+GNU C defines this macro if and only if the @option{-ansi} switch, or a
+@option{-std} switch specifying strict conformance to some version of ISO C,
+was specified when GNU C was invoked. Its definition is the null string.
This macro exists primarily to direct certain GNU header files not to
define certain traditional Unix constructs which are incompatible with
ISO C@.
@cindex extensions, C language
@cindex C language extensions
-GNU C provides several language features not found in ANSI standard C.
+GNU C provides several language features not found in ISO standard C.
(The @samp{-pedantic} option directs GNU CC to print a warning message if
any of these features is used.) To test for the availability of these
features in conditional compilation, check for a predefined macro
also available in C++. @xref{C++ Extensions,,Extensions to the
C++ Language}, for extensions that apply @emph{only} to C++.
+@c FIXME: document clearly which features are in ISO C99, but also
+@c accepted as extensions for -std=gnu89 and possibly for C++.
+@c See PR other/930.
+
+@c FIXME: the documentation for preprocessor extensions here is out of
+@c date. See PR other/928.
+
@c The only difference between the two versions of this menu is that the
@c version for clear INTERNALS has an extra node, "Constraints" (which
@c appears in a separate chapter in the other version of the manual).
@noindent
Here the type described is that of pointers to @code{int}.
-If you are writing a header file that must work when included in ANSI C
+If you are writing a header file that must work when included in ISO C
programs, write @code{__typeof__} instead of @code{typeof}.
@xref{Alternate Keywords}.
@cindex old-style function definitions
@cindex promotion of formal parameters
-GNU C extends ANSI C to allow a function prototype to override a later
+GNU C extends ISO C to allow a function prototype to override a later
old-style non-prototype definition. Consider the following example:
@example
@}
@end example
-Suppose the type @code{uid_t} happens to be @code{short}. ANSI C does
+Suppose the type @code{uid_t} happens to be @code{short}. ISO C does
not allow this example, because subword arguments in old-style
non-prototype definitions are promoted. Therefore in this example the
function definition's argument is really an @code{int}, which does not
match the prototype argument type of @code{short}.
-This restriction of ANSI C makes it hard to write code that is portable
+This restriction of ISO C makes it hard to write code that is portable
to traditional C compilers, because the programmer does not know
whether the @code{uid_t} type is @code{short}, @code{int}, or
@code{long}. Therefore, in cases like these GNU C allows a prototype
continue until the end of the line. Many other C implementations allow
such comments, and they are likely to be in a future C standard.
However, C++ style comments are not recognized if you specify
-@w{@samp{-ansi}} or @w{@samp{-traditional}}, since they are incompatible
+@w{@samp{-ansi}}, a @option{-std} option specifying a version of ISO C
+before C99, or @w{@samp{-traditional}}, since they are incompatible
with traditional constructs like @code{dividend//*comment*/divisor}.
@node Dollar Signs
another, thus improving run-time efficiency.
Note that the alignment of any given @code{struct} or @code{union} type
-is required by the ANSI C standard to be at least a perfect multiple of
+is required by the ISO C standard to be at least a perfect multiple of
the lowest common multiple of the alignments of all of the members of
the @code{struct} or @code{union} in question. This means that you @emph{can}
effectively adjust the alignment of a @code{struct} or @code{union}
@}
@end example
-(If you are writing a header file to be included in ANSI C programs, write
+(If you are writing a header file to be included in ISO C programs, write
@code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}.)
You can also make all ``simple enough'' functions inline with the option
@samp{-finline-functions}.
an assembler instruction access to the condition code left by previous
instructions.
-If you are writing a header file that should be includable in ANSI C
+If you are writing a header file that should be includable in ISO C
programs, write @code{__asm__} instead of @code{asm}. @xref{Alternate
Keywords}.
@cindex alternate keywords
@cindex keywords, alternate
-The option @samp{-traditional} disables certain keywords; @samp{-ansi}
-disables certain others. This causes trouble when you want to use GNU C
-extensions, or ANSI C features, in a general-purpose header file that
-should be usable by all programs, including ANSI C programs and traditional
-ones. The keywords @code{asm}, @code{typeof} and @code{inline} cannot be
-used since they won't work in a program compiled with @samp{-ansi}, while
-the keywords @code{const}, @code{volatile}, @code{signed}, @code{typeof}
-and @code{inline} won't work in a program compiled with
-@samp{-traditional}.@refill
+The option @option{-traditional} disables certain keywords;
+@option{-ansi} and the various @option{-std} options disable certain
+others. This causes trouble when you want to use GNU C extensions, or
+ISO C features, in a general-purpose header file that should be usable
+by all programs, including ISO C programs and traditional ones. The
+keywords @code{asm}, @code{typeof} and @code{inline} cannot be used
+since they won't work in a program compiled with @option{-ansi}
+(although @code{inline} can be used in a program compiled with
+@option{-std=c99}), while the keywords @code{const}, @code{volatile},
+@code{signed}, @code{typeof} and @code{inline} won't work in a program
+compiled with @option{-traditional}. The ISO C99 keyword
+@code{restrict} is only available when @option{-std=gnu99} (which will
+eventually be the default) or @option{-std=c99} (or the equivalent
+@option{-std=iso9899:1999}) is used.@refill
The way to solve these problems is to put @samp{__} at the beginning and
end of each problematical keyword. For example, use @code{__asm__}
@sp 2
@center Richard M. Stallman
@sp 3
-@center Last updated 20 December 2000
+@center Last updated 12 January 2001
@sp 1
@c The version number appears five times more in this file.
for pragmatic reasons, not as a requirement.
GCC normally defines @code{__STDC__} to be 1, and in addition
-defines @code{__STRICT_ANSI__} if you specify the @samp{-ansi} option.
+defines @code{__STRICT_ANSI__} if you specify the @option{-ansi} option,
+or a @option{-std} option for strict conformance to some version of ISO C.
On some hosts, system include files use a different convention, where
@code{__STDC__} is normally 0, but is 1 if the user specifies strict
conformance to the C Standard. GCC follows the host convention when
@code{fixincludes} on the header files in @file{$(tooldir)/include}.
(If the cross compilation header files need to be fixed, they must be
installed before GNU CC is built. If the cross compilation header files
-are already suitable for ANSI C and GNU CC, nothing special need be
+are already suitable for ISO C and GNU CC, nothing special need be
done).
@code{GPLUSPLUS_INCLUDE_DIR} means the same thing for native and cross. It
previous C standards. For example, you may use @code{__restrict__} even
when @option{-std=c99} is not specified.
+The @option{-std} options specifying some version of ISO C have the same
+effects as @option{-ansi}, except that features that were not in ISO C89
+but are in the specified version (for example, @samp{//} comments and
+the @code{inline} keyword in ISO C99) are not disabled.
+
@xref{Standards,,Language Standards Supported by GCC}, for details of
these standard versions.
In C++, this switch only affects the @code{typeof} keyword, since
@code{asm} and @code{inline} are standard keywords. You may want to
-use the @samp{-fno-gnu-keywords} flag instead, which has the same effect.
+use the @samp{-fno-gnu-keywords} flag instead, which has the same
+effect. In C99 mode (@option{-std=c99} or @option{-std=gnu99}), this
+switch only affects the @code{asm} and @code{typeof} keywords, since
+@code{inline} is a standard keyword in ISO C99.
@item -fno-builtin
@cindex builtin functions
Don't recognize builtin functions that do not begin with
@samp{__builtin_} as prefix. @xref{Other Builtins,,Other built-in
functions provided by GNU CC}, for details of the functions affected,
-including those which are not builtin functions when @samp{-ansi} is
-used because they do not have an ISO standard meaning.
+including those which are not builtin functions when @option{-ansi} or
+@option{-std} options for strict ISO C conformance are used because they
+do not have an ISO standard meaning.
GCC normally generates special code to handle certain builtin functions
more efficiently; for instance, calls to @code{alloca} may become single
@item -trigraphs
Support ISO C trigraphs. You don't want to know about this
-brain-damage. The @samp{-ansi} option implies @samp{-trigraphs}.
+brain-damage. The @option{-ansi} option (and @option{-std} options for
+strict ISO C conformance) implies @option{-trigraphs}.
@cindex traditional C language
@cindex C language, traditional
version of the ISO C standard specified by any @samp{-std} option used.
Valid ISO C and ISO C++ programs should compile properly with or without
-this option (though a rare few will require @samp{-ansi}). However,
+this option (though a rare few will require @option{-ansi} or a
+@option{-std} option specifying the required version of ISO C). However,
without this option, certain GNU extensions and traditional C and C++
features are supported as well. With this option, they are rejected.
@item CPP_PREDEFINES
Define this to be a string constant containing @samp{-D} options to
define the predefined macros that identify this machine and system.
-These macros will be predefined unless the @samp{-ansi} option is
-specified.
+These macros will be predefined unless the @option{-ansi} option (or a
+@option{-std} option for strict ISO C conformance) is specified.
In addition, a parallel set of macros are predefined, whose names are
made by appending @samp{__} at the beginning and at the end. These
-@samp{__} macros are permitted by the ANSI standard, so they are
-predefined regardless of whether @samp{-ansi} is specified.
+@samp{__} macros are permitted by the ISO standard, so they are
+predefined regardless of whether @option{-ansi} or a @option{-std} option
+is specified.
For example, on the Sun, one can use the following value:
argument is also stored on the stack.
@cindex @file{stdarg.h} and register arguments
-The usual way to make the ANSI library @file{stdarg.h} work on a machine
+The usual way to make the ISO library @file{stdarg.h} work on a machine
where some arguments are usually passed in registers, is to cause
nameless arguments to be passed on the stack instead. This is done
by making @code{FUNCTION_ARG} return 0 whenever @var{named} is 0.
varargs, and the two machine independent header files must have
conditionals to include it.
-ANSI @file{stdarg.h} differs from traditional @file{varargs.h} mainly in
+ISO @file{stdarg.h} differs from traditional @file{varargs.h} mainly in
the calling convention for @code{va_start}. The traditional
implementation takes just one argument, which is the variable in which
-to store the argument pointer. The ANSI implementation of
+to store the argument pointer. The ISO implementation of
@code{va_start} takes an additional second argument. The user is
supposed to write the last named argument of the function here.
@findex __builtin_saveregs
@item __builtin_saveregs ()
Use this built-in function to save the argument registers in memory so
-that the varargs mechanism can access them. Both ANSI and traditional
+that the varargs mechanism can access them. Both ISO and traditional
versions of @code{va_start} must use @code{__builtin_saveregs}, unless
you use @code{SETUP_INCOMING_VARARGS} (see below) instead.
@cindex @code{bzero}, implicit usage
@cindex @code{memset}, implicit usage
@item TARGET_MEM_FUNCTIONS
-Define this macro if GCC should generate calls to the System V
-(and ANSI C) library functions @code{memcpy} and @code{memset}
+Define this macro if GCC should generate calls to the ISO C
+(and System V) library functions @code{memcpy} and @code{memset}
rather than the BSD functions @code{bcopy} and @code{bzero}.
@findex LIBGCC_NEEDS_DOUBLE
@item NEED_ATEXIT
@findex NEED_ATEXIT
Define this if the target system lacks the function @code{atexit}
-from the ANSI C standard. If this macro is defined, a default definition
+from the ISO C standard. If this macro is defined, a default definition
will be provided to support C++. If @code{ON_EXIT} is not defined,
a default @code{exit} function will also be provided.
projects / gcc.git / commitdiff