From 78b1f6163226be37876ba7473acd9fac7b24282a Mon Sep 17 00:00:00 2001 From: jsm28 Date: Fri, 12 Jan 2001 18:51:27 +0000 Subject: [PATCH] * 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. git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@38956 138bc75d-0d04-0410-961f-82ee72b054a4 --- gcc/ChangeLog | 8 ++++ gcc/cpp.1 | 111 ++++++++++++++++++++++++++++++++++++++----------------- gcc/cpp.texi | 7 ++-- gcc/extend.texi | 49 +++++++++++++++--------- gcc/gcc.texi | 5 ++- gcc/install.texi | 2 +- gcc/invoke.texi | 21 ++++++++--- gcc/tm.texi | 23 ++++++------ 8 files changed, 153 insertions(+), 73 deletions(-) diff --git a/gcc/ChangeLog b/gcc/ChangeLog index 06feedc0240..1de53d4f1b3 100644 --- a/gcc/ChangeLog +++ b/gcc/ChangeLog @@ -1,3 +1,11 @@ +2001-01-12 Joseph S. Myers + + * 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 * haifa-sched.c (restore_line_notes): Remove argument block B diff --git a/gcc/cpp.1 b/gcc/cpp.1 index 6f5281ac2f0..aa00123c8ad 100644 --- a/gcc/cpp.1 +++ b/gcc/cpp.1 @@ -1,5 +1,5 @@ .\" Automatically generated by Pod::Man version 1.1 -.\" Wed Jan 3 20:06:19 2001 +.\" Fri Jan 12 18:47:56 2001 .\" .\" Standard preamble: .\" ====================================================================== @@ -138,7 +138,7 @@ .\" ====================================================================== .\" .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 @@ -149,7 +149,8 @@ cpp [\fB\-P\fR] [\fB\-C\fR] [\fB\-gcc\fR] [\fB\-traditional\fR] [\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 @@ -417,6 +418,9 @@ the current one and which are searched after. 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, @@ -442,11 +446,17 @@ 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 \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. @@ -493,42 +503,77 @@ Like \fB\-dD\fR, but emit only the macro names, not their expansions. .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 @@ -668,7 +713,7 @@ common extension. .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 diff --git a/gcc/cpp.texi b/gcc/cpp.texi index 3d48cdd6c17..02b6253c535 100644 --- a/gcc/cpp.texi +++ b/gcc/cpp.texi @@ -42,7 +42,7 @@ into another language, under the above conditions for modified versions. @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 @@ -1156,8 +1156,9 @@ conformance with the standard. @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@. diff --git a/gcc/extend.texi b/gcc/extend.texi index 0b583a03250..45dda7cb319 100644 --- a/gcc/extend.texi +++ b/gcc/extend.texi @@ -7,7 +7,7 @@ @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 @@ -17,6 +17,13 @@ These extensions are available in C and Objective C. Most of them are 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). @@ -590,7 +597,7 @@ typeof (int *) @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}. @@ -1932,7 +1939,7 @@ Preprocessing Directives, cpp, The C Preprocessor}. @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 @@ -1955,13 +1962,13 @@ isroot (x) /* ??? lossage here ??? */ @} @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 @@ -1994,7 +2001,8 @@ In GNU C, you may use C++ style comments, which start with @samp{//} and 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 @@ -2336,7 +2344,7 @@ store) instructions when copying one variable of type @code{struct S} to 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} @@ -2512,7 +2520,7 @@ inc (int *a) @} @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}. @@ -2840,7 +2848,7 @@ For reasons similar to those described above, it is not possible to give 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}. @@ -3165,15 +3173,20 @@ be deleted or moved or simplified. @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__} diff --git a/gcc/gcc.texi b/gcc/gcc.texi index 8e29cf154a9..6fbc6e9f9d2 100644 --- a/gcc/gcc.texi +++ b/gcc/gcc.texi @@ -151,7 +151,7 @@ instead of in the original English. @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. @@ -2192,7 +2192,8 @@ is relevant to the design of plain @samp{gcc} without @samp{-ansi} only 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 diff --git a/gcc/install.texi b/gcc/install.texi index b963bbbe606..65397a4df6b 100644 --- a/gcc/install.texi +++ b/gcc/install.texi @@ -2267,7 +2267,7 @@ stores the fixed include files. A cross compiled GNU CC runs @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 diff --git a/gcc/invoke.texi b/gcc/invoke.texi index 6eff6b6fe25..667a0642538 100644 --- a/gcc/invoke.texi +++ b/gcc/invoke.texi @@ -908,6 +908,11 @@ features of newer standards in so far as they do not conflict with 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. @@ -919,15 +924,19 @@ instead. @samp{-ansi} implies @samp{-fno-asm}. 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 @@ -960,7 +969,8 @@ freestanding and hosted environments. @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 @@ -1559,7 +1569,8 @@ programs that do not follow ISO C and ISO C++. For ISO C, follows the 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. diff --git a/gcc/tm.texi b/gcc/tm.texi index 769583eba90..402101f994a 100644 --- a/gcc/tm.texi +++ b/gcc/tm.texi @@ -547,13 +547,14 @@ Here are run-time target specifications. @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: @@ -3001,7 +3002,7 @@ RTX may have a first operand of zero. This indicates that the entire 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. @@ -3900,10 +3901,10 @@ on the stack. Other machines require their own implementations of 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. @@ -3915,7 +3916,7 @@ below. @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. @@ -4345,8 +4346,8 @@ macro, a reasonable default is used. @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 @@ -8159,7 +8160,7 @@ appropriate rtl instructions. It is used only when compiling the end of @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. -- 2.11.0