From cafd8c6cc744754bcc594f8f496348868fe235d0 Mon Sep 17 00:00:00 2001 From: sandra Date: Tue, 17 Apr 2012 02:34:20 +0000 Subject: [PATCH] 2012-04-16 Sandra Loosemore gcc/ * doc/invoke.texi: Copy-edit to put verbs in the present tense when describing the current behavior of GCC. git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@186523 138bc75d-0d04-0410-961f-82ee72b054a4 --- gcc/ChangeLog | 5 + gcc/doc/invoke.texi | 1320 ++++++++++++++++++++++++++------------------------- 2 files changed, 669 insertions(+), 656 deletions(-) diff --git a/gcc/ChangeLog b/gcc/ChangeLog index 29193e3..3d8388b 100644 --- a/gcc/ChangeLog +++ b/gcc/ChangeLog @@ -1,3 +1,8 @@ +2012-04-16 Sandra Loosemore + + * doc/invoke.texi: Copy-edit to put verbs in the present tense + when describing the current behavior of GCC. + 2012-04-16 Richard Sandiford * genemit.c (gen_exp): Remove ADDRESS handling. diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi index a6297be..a033985 100644 --- a/gcc/doc/invoke.texi +++ b/gcc/doc/invoke.texi @@ -113,7 +113,7 @@ Many options have long names starting with @samp{-f} or with @samp{-W}---for example, @option{-fmove-loop-invariants}, @option{-Wformat} and so on. Most of these have both positive and negative forms; the negative form of -@option{-ffoo} would be @option{-fno-foo}. This manual documents +@option{-ffoo} is @option{-fno-foo}. This manual documents only one of these two forms, whichever one is not the default. @c man end @@ -1181,11 +1181,11 @@ has not been used at all). @item -pass-exit-codes @opindex pass-exit-codes -Normally the @command{gcc} program will exit with the code of 1 if any +Normally the @command{gcc} program exits with the code of 1 if any phase of the compiler returns a non-success return code. If you specify -@option{-pass-exit-codes}, the @command{gcc} program will instead return with -numerically highest error produced by any phase that returned an error -indication. The C, C++, and Fortran frontends return 4, if an internal +@option{-pass-exit-codes}, the @command{gcc} program instead returns with +the numerically highest error produced by any phase returning an error +indication. The C, C++, and Fortran front ends return 4 if an internal compiler error is encountered. @end table @@ -1264,11 +1264,11 @@ no trouble. @opindex help Print (on the standard output) a description of the command-line options understood by @command{gcc}. If the @option{-v} option is also specified -then @option{--help} will also be passed on to the various processes +then @option{--help} is also passed on to the various processes invoked by @command{gcc}, so that they can display the command-line options they accept. If the @option{-Wextra} option has also been specified (prior to the @option{--help} option), then command-line options that -have no documentation associated with them will also be displayed. +have no documentation associated with them are also displayed. @item --target-help @opindex target-help @@ -1283,30 +1283,30 @@ and qualifiers. These are the supported classes: @table @asis @item @samp{optimizers} -This will display all of the optimization options supported by the +Display all of the optimization options supported by the compiler. @item @samp{warnings} -This will display all of the options controlling warning messages +Display all of the options controlling warning messages produced by the compiler. @item @samp{target} -This will display target-specific options. Unlike the +Display target-specific options. Unlike the @option{--target-help} option however, target-specific options of the -linker and assembler will not be displayed. This is because those +linker and assembler are not displayed. This is because those tools do not currently support the extended @option{--help=} syntax. @item @samp{params} -This will display the values recognized by the @option{--param} +Display the values recognized by the @option{--param} option. @item @var{language} -This will display the options supported for @var{language}, where +Display the options supported for @var{language}, where @var{language} is the name of one of the languages supported in this version of GCC@. @item @samp{common} -This will display the options that are common to all languages. +Display the options that are common to all languages. @end table These are the supported qualifiers: @@ -1355,7 +1355,7 @@ optimization options the following can be used: @end smallexample The @option{--help=} option can be repeated on the command line. Each -successive use will display its requested class of options, skipping +successive use displays its requested class of options, skipping those that have already been displayed. If the @option{-Q} option appears on the command line before the @@ -1412,8 +1412,9 @@ list. gcc -c t.c -wrapper gdb,--args @end smallexample -This will invoke all subprograms of @command{gcc} under -@samp{gdb --args}, thus the invocation of @command{cc1} will be +@noindent +This invokes all subprograms of @command{gcc} under +@samp{gdb --args}, thus the invocation of @command{cc1} is @samp{gdb --args cc1 @dots{}}. @item -fplugin=@var{name}.so @@ -1524,7 +1525,7 @@ from declaring certain functions or defining certain macros that the ISO standard doesn't call for; this is to avoid interfering with any programs that might use these names for other things. -Functions that would normally be built in but do not have semantics +Functions that are normally built in but do not have semantics defined by ISO C (such as @code{alloca} and @code{ffs}) are not built-in functions when @option{-ansi} is used. @xref{Other Builtins,,Other built-in functions provided by GCC}, for details of the functions @@ -1538,8 +1539,8 @@ is currently only supported when compiling C or C++. The compiler can accept several base standards, such as @samp{c90} or @samp{c++98}, and GNU dialects of those standards, such as -@samp{gnu90} or @samp{gnu++98}. By specifying a base standard, the -compiler will accept all programs following that standard and those +@samp{gnu90} or @samp{gnu++98}. When a base standard is specified, the +compiler accepts all programs following that standard plus those using GNU extensions that do not contradict it. For example, @option{-std=c90} turns off certain features of GCC that are incompatible with ISO C90, such as the @code{asm} and @code{typeof} @@ -1763,8 +1764,8 @@ have support for @option{-pthread}. @item -fgnu-tm @opindex fgnu-tm -When the option @option{-fgnu-tm} is specified, the compiler will -generate code for the Linux variant of Intel's current Transactional +When the option @option{-fgnu-tm} is specified, the compiler +generates code for the Linux variant of Intel's current Transactional Memory ABI specification document (Revision 1.1, May 6 2009). This is an experimental feature whose interface may change in future versions of GCC, as the official specification changes. Please note that not @@ -1937,8 +1938,8 @@ around bugs in the access control code. Check that the pointer returned by @code{operator new} is non-null before attempting to modify the storage allocated. This check is normally unnecessary because the C++ standard specifies that -@code{operator new} will only return @code{0} if it is declared -@samp{throw()}, in which case the compiler will always check the +@code{operator new} only returns @code{0} if it is declared +@samp{throw()}, in which case the compiler always checks the return value even without this option. In all other cases, when @code{operator new} has a non-empty exception specification, memory exhaustion is signalled by throwing @code{std::bad_alloc}. See also @@ -1951,7 +1952,7 @@ common segment, as C does. This saves space in the executable at the cost of not diagnosing duplicate definitions. If you compile with this flag and your program mysteriously crashes after @code{main()} has completed, you may have an object that is being destroyed twice because -two definitions were merged. +two definitions are merged. This option is no longer useful on most targets, now that support has been added for putting variables into BSS without making them common. @@ -2013,8 +2014,8 @@ at run time. This option violates the C++ standard, but may be useful for reducing code size in production builds, much like defining @samp{NDEBUG}. This does not give user code permission to throw exceptions in violation of the exception specifications; the compiler -will still optimize based on the specifications, so throwing an -unexpected exception will result in undefined behavior. +still optimizes based on the specifications, so throwing an +unexpected exception results in undefined behavior at run time. @item -ffor-scope @itemx -fno-for-scope @@ -2048,12 +2049,12 @@ implicitly (i.e.@: by use); only emit code for explicit instantiations. @opindex fno-implicit-inline-templates Don't emit code for implicit instantiations of inline templates, either. The default is to handle inlines differently so that compiles with and -without optimization will need the same set of explicit instantiations. +without optimization need the same set of explicit instantiations. @item -fno-implement-inlines @opindex fno-implement-inlines To save space, do not emit out-of-line copies of inline functions -controlled by @samp{#pragma implementation}. This will cause linker +controlled by @samp{#pragma implementation}. This causes linker errors if these functions are not inlined everywhere they are called. @item -fms-extensions @@ -2069,14 +2070,14 @@ ANSI/ISO C@. These include @code{ffs}, @code{alloca}, @code{_exit}, @item -fnothrow-opt @opindex fnothrow-opt -Treat a @code{throw()} exception specification as though it were a +Treat a @code{throw()} exception specification as if it were a @code{noexcept} specification to reduce or eliminate the text size overhead relative to a function with no exception specification. If the function has local variables of types with non-trivial -destructors, the exception specification will actually make the +destructors, the exception specification actually makes the function smaller because the EH cleanups for those variables can be optimized away. The semantic effect is that an exception thrown out of -a function with such an exception specification will result in a call +a function with such an exception specification results in a call to @code{terminate} rather than @code{unexpected}. @item -fno-operator-names @@ -2094,21 +2095,21 @@ a name having multiple meanings within a class. @item -fpermissive @opindex fpermissive Downgrade some diagnostics about nonconformant code from errors to -warnings. Thus, using @option{-fpermissive} will allow some +warnings. Thus, using @option{-fpermissive} allows some nonconforming code to compile. @item -fno-pretty-templates @opindex fno-pretty-templates When an error message refers to a specialization of a function -template, the compiler will normally print the signature of the +template, the compiler normally prints the signature of the template followed by the template arguments and any typedefs or typenames in the signature (e.g. @code{void f(T) [with T = int]} rather than @code{void f(int)}) so that it's clear which template is involved. When an error message refers to a specialization of a class -template, the compiler will omit any template arguments that match +template, the compiler omits any template arguments that match the default template arguments for that template. If either of these behaviors make it harder to understand the error message rather than -easier, using @option{-fno-pretty-templates} will disable them. +easier, you can use @option{-fno-pretty-templates} to disable them. @item -frepo @opindex frepo @@ -2122,7 +2123,7 @@ Disable generation of information about every class with virtual functions for use by the C++ run-time type identification features (@samp{dynamic_cast} and @samp{typeid}). If you don't use those parts of the language, you can save some space by using this flag. Note that -exception handling uses the same information, but it will generate it as +exception handling uses the same information, but G++ generates it as needed. The @samp{dynamic_cast} operator can still be used for casts that do not require run-time type information, i.e.@: casts to @code{void *} or to unambiguous base classes. @@ -2167,20 +2168,20 @@ thread-safe. Register destructors for objects with static storage duration with the @code{__cxa_atexit} function rather than the @code{atexit} function. This option is required for fully standards-compliant handling of static -destructors, but will only work if your C library supports +destructors, but only works if your C library supports @code{__cxa_atexit}. @item -fno-use-cxa-get-exception-ptr @opindex fno-use-cxa-get-exception-ptr Don't use the @code{__cxa_get_exception_ptr} runtime routine. This -will cause @code{std::uncaught_exception} to be incorrect, but is necessary +causes @code{std::uncaught_exception} to be incorrect, but is necessary if the runtime routine is not available. @item -fvisibility-inlines-hidden @opindex fvisibility-inlines-hidden This switch declares that the user does not attempt to compare pointers to inline functions or methods where the addresses of the two functions -were taken in different shared objects. +are taken in different shared objects. The effect of this is that GCC may, effectively, mark inline methods with @code{__attribute__ ((visibility ("hidden")))} so that they do not @@ -2198,7 +2199,7 @@ You may mark a method as having a visibility explicitly to negate the effect of the switch for that method. For example, if you do want to compare pointers to a particular inline method, you might mark it as having default visibility. Marking the enclosing class with explicit -visibility will have no effect. +visibility has no effect. Explicitly instantiated inline methods are unaffected by this option as their linkage might otherwise cross a shared library boundary. @@ -2221,9 +2222,9 @@ Types, but not their members, are not hidden by default. @item The One Definition Rule is relaxed for types without explicit -visibility specifications that are defined in more than one different -shared object: those declarations are permitted if they would have -been permitted when this option was not used. +visibility specifications that are defined in more than one +shared object: those declarations are permitted if they are +permitted when this option is not used. @end enumerate In new code it is better to use @option{-fvisibility=hidden} and @@ -2233,7 +2234,7 @@ on the Visual Studio behavior. Among the consequences of these changes are that static data members of the same type with the same name but defined in different shared -objects will be different, so changing one will not change the other; +objects are different, so changing one does not change the other; and that pointers to function members defined in different shared objects may not compare equal. When this flag is given, it is a violation of the ODR to define types with the same name differently. @@ -2241,9 +2242,9 @@ violation of the ODR to define types with the same name differently. @item -fno-weak @opindex fno-weak Do not use weak symbol support, even if it is provided by the linker. -By default, G++ will use weak symbols if they are available. This +By default, G++ uses weak symbols if they are available. This option exists only for testing, and should not be used by end-users; -it will result in inferior code and has no benefits. This option may +it results in inferior code and has no benefits. This option may be removed in a future release of G++. @item -nostdinc++ @@ -2261,7 +2262,7 @@ have meanings only for C++ programs: @opindex fno-default-inline Do not assume @samp{inline} for functions defined inside a class scope. @xref{Optimize Options,,Options That Control Optimization}. Note that these -functions will have linkage like inline functions; they just won't be +functions have linkage like inline functions; they just aren't inlined by default. @item -Wabi @r{(C, Objective-C, C++ and Objective-C++ only)} @@ -2272,7 +2273,7 @@ vendor-neutral C++ ABI@. Although an effort has been made to warn about all such cases, there are probably some cases that are not warned about, even though G++ is generating incompatible code. There may also be cases where warnings are emitted even though the code that is generated -will be compatible. +is compatible. You should rewrite your code to avoid these warnings if you are concerned about the fact that code generated by G++ may not be binary @@ -2315,11 +2316,11 @@ struct B : public A @{ int f2 : 1; @}; @end smallexample @noindent -In this case, G++ will place @code{B::f2} into the same byte -as@code{A::f1}; other compilers will not. You can avoid this problem +In this case, G++ places @code{B::f2} into the same byte +as@code{A::f1}; other compilers do not. You can avoid this problem by explicitly padding @code{A} so that its size is a multiple of the -byte size on your platform; that will cause G++ and other compilers to -layout @code{B} identically. +byte size on your platform; that causes G++ and other compilers to +lay out @code{B} identically. @item Incorrect handling of tail-padding for virtual bases. G++ does not use @@ -2332,11 +2333,11 @@ struct C : public A, public virtual B @{@}; @end smallexample @noindent -In this case, G++ will not place @code{B} into the tail-padding for -@code{A}; other compilers will. You can avoid this problem by +In this case, G++ does not place @code{B} into the tail-padding for +@code{A}; other compilers do. You can avoid this problem by explicitly padding @code{A} so that its size is a multiple of its -alignment (ignoring virtual base classes); that will cause G++ and other -compilers to layout @code{C} identically. +alignment (ignoring virtual base classes); that causes G++ and other +compilers to lay out @code{C} identically. @item Incorrect handling of bit-fields with declared widths greater than that @@ -2348,7 +2349,7 @@ union U @{ int i : 4096; @}; @end smallexample @noindent -Assuming that an @code{int} does not have 4096 bits, G++ will make the +Assuming that an @code{int} does not have 4096 bits, G++ makes the union too small by the number of bits in an @code{int}. @item @@ -2366,7 +2367,7 @@ struct C : public B, public A @{@}; @end smallexample @noindent -G++ will place the @code{A} base class of @code{C} at a nonzero offset; +G++ places the @code{A} base class of @code{C} at a nonzero offset; it should be placed at offset zero. G++ mistakenly believes that the @code{A} data member of @code{B} is already at offset zero. @@ -2452,8 +2453,8 @@ the compiler to never throw an exception. @item -Wnon-virtual-dtor @r{(C++ and Objective-C++ only)} @opindex Wnon-virtual-dtor @opindex Wno-non-virtual-dtor -Warn when a class has virtual functions and accessible non-virtual -destructor, in which case it would be possible but unsafe to delete +Warn when a class has virtual functions and an accessible non-virtual +destructor, in which case it is possible but unsafe to delete an instance of a derived class through a pointer to the base class. This warning is also enabled if @option{-Weffc++} is specified. @@ -2473,7 +2474,8 @@ struct A @{ @}; @end smallexample -The compiler will rearrange the member initializers for @samp{i} +@noindent +The compiler rearranges the member initializers for @samp{i} and @samp{j} to match the declaration order of the members, emitting a warning to that effect. This warning is enabled by @option{-Wall}. @end table @@ -2583,7 +2585,8 @@ B* b; b->f(); @end smallexample -will fail to compile. +@noindent +fails to compile. @item -Wno-pmf-conversions @r{(C++ and Objective-C++ only)} @opindex Wno-pmf-conversions @@ -2596,7 +2599,7 @@ to a plain pointer. @opindex Wno-sign-promo Warn when overload resolution chooses a promotion from unsigned or enumerated type to a signed type, over a conversion to an unsigned type of -the same size. Previous versions of G++ would try to preserve +the same size. Previous versions of G++ tried to preserve unsignedness, but the standard mandates the current behavior. @smallexample @@ -2612,8 +2615,9 @@ main () @} @end smallexample -In this example, G++ will synthesize a default @samp{A& operator = -(const A&);}, while cfront will use the user-defined @samp{operator =}. +@noindent +In this example, G++ synthesizes a default @samp{A& operator = +(const A&);}, while cfront uses the user-defined @samp{operator =}. @end table @node Objective-C and Objective-C++ Dialect Options @@ -2655,7 +2659,7 @@ Use @var{class-name} as the name of the class to instantiate for each literal string specified with the syntax @code{@@"@dots{}"}. The default class name is @code{NXConstantString} if the GNU runtime is being used, and @code{NSConstantString} if the NeXT runtime is being used (see below). The -@option{-fconstant-cfstrings} option, if also present, will override the +@option{-fconstant-cfstrings} option, if also present, overrides the @option{-fconstant-string-class} setting and cause @code{@@"@dots{}"} literals to be laid out as constant CoreFoundation strings. @@ -2694,21 +2698,21 @@ machines, and Version 2 on 64-bit target machines. @opindex fobjc-call-cxx-cdtors For each Objective-C class, check if any of its instance variables is a C++ object with a non-trivial default constructor. If so, synthesize a -special @code{- (id) .cxx_construct} instance method which will run +special @code{- (id) .cxx_construct} instance method which runs non-trivial default constructors on any such instance variables, in order, and then return @code{self}. Similarly, check if any instance variable is a C++ object with a non-trivial destructor, and if so, synthesize a -special @code{- (void) .cxx_destruct} method which will run +special @code{- (void) .cxx_destruct} method which runs all such default destructors, in reverse order. The @code{- (id) .cxx_construct} and @code{- (void) .cxx_destruct} -methods thusly generated will only operate on instance variables +methods thusly generated only operate on instance variables declared in the current Objective-C class, and not those inherited from superclasses. It is the responsibility of the Objective-C runtime to invoke all such methods in an object's inheritance -hierarchy. The @code{- (id) .cxx_construct} methods will be invoked +hierarchy. The @code{- (id) .cxx_construct} methods are invoked by the runtime immediately after a new object instance is allocated; -the @code{- (void) .cxx_destruct} methods will be invoked immediately +the @code{- (void) .cxx_destruct} methods are invoked immediately before the runtime deallocates an object instance. As of this writing, only the NeXT runtime on Mac OS X 10.4 and later has @@ -2823,7 +2827,7 @@ being used. Warn if multiple methods with differing argument and/or return types are found for a given selector when attempting to send a message using this selector to a receiver of type @code{id} or @code{Class}. When this flag -is off (which is the default behavior), the compiler will omit such warnings +is off (which is the default behavior), the compiler omits such warnings if any differences found are confined to types that share the same size and alignment. @@ -2855,12 +2859,12 @@ value, if any. @cindex message formatting Traditionally, diagnostic messages have been formatted irrespective of -the output device's aspect (e.g.@: its width, @dots{}). The options described -below can be used to control the diagnostic messages formatting -algorithm, e.g.@: how many characters per line, how often source location -information should be reported. Right now, only the C++ front end can -honor these options. However it is expected, in the near future, that -the remaining front ends would be able to digest them correctly. +the output device's aspect (e.g.@: its width, @dots{}). You can use the +options described below +to control the formatting algorithm for diagnostic messages, +e.g.@: how many characters per line, how often source location +information should be reported. Note that some language front ends may not +honor these options. @table @gcctabopt @item -fmessage-length=@var{n} @@ -2868,7 +2872,7 @@ the remaining front ends would be able to digest them correctly. Try to format error messages so that they fit on lines of about @var{n} characters. The default is 72 characters for @command{g++} and 0 for the rest of the front ends supported by GCC@. If @var{n} is zero, then no -line-wrapping will be done; each error message will appear on a single +line-wrapping is done; each error message appears on a single line. @opindex fdiagnostics-show-location @@ -2981,13 +2985,13 @@ language-specific options also refer to @ref{C++ Dialect Options} and @ref{Objective-C and Objective-C++ Dialect Options}. When an unrecognized warning option is requested (e.g., -@option{-Wunknown-warning}), GCC will emit a diagnostic stating +@option{-Wunknown-warning}), GCC emits a diagnostic stating that the option is not recognized. However, if the @option{-Wno-} form -is used, the behavior is slightly different: No diagnostic will be +is used, the behavior is slightly different: no diagnostic is produced for @option{-Wno-unknown-warning} unless other diagnostics are being produced. This allows the use of new @option{-Wno-} options -with old compilers, but if something goes wrong, the compiler will -warn that an unrecognized option was used. +with old compilers, but if something goes wrong, the compiler +warns that an unrecognized option is present. @table @gcctabopt @item -pedantic @@ -2998,7 +3002,7 @@ programs that do not follow ISO C and ISO C++. For ISO C, follows the version of the ISO C standard specified by any @option{-std} option used. Valid ISO C and ISO C++ programs should compile properly with or without -this option (though a rare few will require @option{-ansi} or a +this option (though a rare few 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. @@ -3025,7 +3029,7 @@ Where the standard specified with @option{-std} represents a GNU extended dialect of C, such as @samp{gnu90} or @samp{gnu99}, there is a corresponding @dfn{base standard}, the version of ISO C on which the GNU extended dialect is based. Warnings from @option{-pedantic} are given -where they are required by the base standard. (It would not make sense +where they are required by the base standard. (It does not make sense for such warnings to be given only for features not in the specified GNU C dialect, since by definition the GNU dialects of C include all features the compiler supports with the given option, and there would be @@ -3157,8 +3161,8 @@ This warning is enabled by @option{-Wall}. @opindex Wno-coverage-mismatch Warn if feedback profiles do not match when using the @option{-fprofile-use} option. -If a source file was changed between @option{-fprofile-gen} and -@option{-fprofile-use}, the files with the profile feedback can fail +If a source file is changed between compiling with @option{-fprofile-gen} and +with @option{-fprofile-use}, the files with the profile feedback can fail to match the source file and GCC cannot use the profile feedback information. By default, this warning is enabled and is treated as an error. @option{-Wno-coverage-mismatch} can be used to disable the @@ -3194,7 +3198,7 @@ float area(float radius) @} @end group @end smallexample -the compiler will perform the entire computation with @code{double} +the compiler performs the entire computation with @code{double} because the floating-point literal is a @code{double}. @item -Wformat @@ -3220,7 +3224,7 @@ as features from the Single Unix Specification and some BSD and GNU extensions. Other library implementations may not support all these features; GCC does not support warning about features that go beyond a particular library's limitations. However, if @option{-pedantic} is used -with @option{-Wformat}, warnings will be given about format features not +with @option{-Wformat}, warnings are given about format features not in the selected standard version (but not for @code{strfmon} formats, since those are not in any version of the C standard). @xref{C Dialect Options,,Options Controlling C Dialect}. @@ -3257,7 +3261,7 @@ Where the unused arguments lie between used arguments that are specified with @samp{$} operand number specifications, normally warnings are still given, since the implementation could not know what type to pass to @code{va_arg} to skip the unused arguments. However, -in the case of @code{scanf} formats, this option will suppress the +in the case of @code{scanf} formats, this option suppresses the warning if the unused arguments are all pointers, since the Single Unix Specification says that such unused arguments are allowed. @@ -3309,7 +3313,7 @@ can be disabled with the @option{-Wno-nonnull} option. Warn about uninitialized variables that are initialized with themselves. Note this option can only be used with the @option{-Wuninitialized} option. -For example, GCC will warn about @code{i} being uninitialized in the +For example, GCC warns about @code{i} being uninitialized in the following snippet only when @option{-Winit-self} has been specified: @smallexample @group @@ -3415,11 +3419,11 @@ In C/C++, every @code{else} branch belongs to the innermost possible @code{if} statement, which in this example is @code{if (b)}. This is often not what the programmer expected, as illustrated in the above example by indentation the programmer chose. When there is the -potential for this confusion, GCC will issue a warning when this flag +potential for this confusion, GCC issues a warning when this flag is specified. To eliminate the warning, add explicit braces around the innermost @code{if} statement so there is no way the @code{else} -could belong to the enclosing @code{if}. The resulting code would -look like this: +can belong to the enclosing @code{if}. The resulting code +looks like this: @smallexample @group @@ -3435,10 +3439,10 @@ look like this: @end group @end smallexample -Also warn for dangerous uses of the -?: with omitted middle operand GNU extension. When the condition -in the ?: operator is a boolean expression the omitted value will -be always 1. Often the user expects it to be a value computed +Also warn for dangerous uses of the GNU extension to +@code{?:} with omitted middle operand. When the condition +in the @code{?}: operator is a boolean expression, the omitted value is +always 1. Often programmers expect it to be a value computed inside the conditional expression instead. This warning is enabled by @option{-Wall}. @@ -3623,8 +3627,8 @@ Warn whenever a statement computes a result that is explicitly not used. To suppress this warning cast the unused expression to @samp{void}. This includes an expression-statement or the left-hand side of a comma expression that contains no side effects. For example, -an expression such as @samp{x[i,j]} will cause a warning, while -@samp{x[(void)i,j]} will not. +an expression such as @samp{x[i,j]} causes a warning, while +@samp{x[(void)i,j]} does not. This warning is enabled by @option{-Wall}. @@ -3653,7 +3657,7 @@ elements of structure, union or array variables as well as for variables that are uninitialized or clobbered as a whole. They do not occur for variables or elements declared @code{volatile}. Because these warnings depend on optimization, the exact variables or elements -for which there are warnings will depend on the precise optimization +for which there are warnings depends on the precise optimization options and version of GCC used. Note that there may be no warning about a variable that is used only @@ -3666,11 +3670,11 @@ are printed. @opindex Wno-maybe-uninitialized For an automatic variable, if there exists a path from the function entry to a use of the variable that is initialized, but there exist -some other paths the variable is not initialized, the compiler will -emit a warning if it can not prove the uninitialized paths do not -happen at run time. These warnings are made optional because GCC is +some other paths for which the variable is not initialized, the compiler +emits a warning if it cannot prove the uninitialized paths are not +executed at run time. These warnings are made optional because GCC is not smart enough to see all the reasons why the code might be correct -despite appearing to have an error. Here is one example of how +in spite of appearing to have an error. Here is one example of how this can happen: @smallexample @@ -3693,7 +3697,7 @@ this can happen: @noindent If the value of @code{y} is always 1, 2 or 3, then @code{x} is always initialized, but GCC doesn't know this. To suppress the -warning, the user needs to provide a default case with assert(0) or +warning, you need to provide a default case with assert(0) or similar code. @cindex @code{longjmp} warnings @@ -3720,9 +3724,9 @@ This warning is enabled by @option{-Wall} or @option{-Wextra}. @cindex unknown pragmas, warning @cindex pragmas, warning of unknown Warn when a @code{#pragma} directive is encountered that is not understood by -GCC@. If this command-line option is used, warnings will even be issued +GCC@. If this command-line option is used, warnings are even issued for unknown pragmas in system header files. This is not the case if -the warnings were only enabled by the @option{-Wall} command-line option. +the warnings are only enabled by the @option{-Wall} command-line option. @item -Wno-pragmas @opindex Wno-pragmas @@ -3793,14 +3797,14 @@ easily give a false positive: a warning about code that is not actually a problem. To help focus on important issues, several warning levels are defined. No warnings are issued for the use of undefined signed overflow when estimating how many iterations a loop -will require, in particular when determining whether a loop will be +requires, in particular when determining whether a loop will be executed at all. @table @gcctabopt @item -Wstrict-overflow=1 Warn about cases that are both questionable and easy to avoid. For -example: @code{x + 1 > x}; with @option{-fstrict-overflow}, the -compiler will simplify this to @code{1}. This level of +example, with @option{-fstrict-overflow}, the compiler simplifies +@code{x + 1 > x} to @code{1}. This level of @option{-Wstrict-overflow} is enabled by @option{-Wall}; higher levels are not, and must be explicitly requested. @@ -3814,18 +3818,18 @@ zero. @option{-Wstrict-overflow} (with no level) is the same as @item -Wstrict-overflow=3 Also warn about other cases where a comparison is simplified. For -example: @code{x + 1 > 1} will be simplified to @code{x > 0}. +example: @code{x + 1 > 1} is simplified to @code{x > 0}. @item -Wstrict-overflow=4 Also warn about other simplifications not covered by the above cases. -For example: @code{(x * 10) / 5} will be simplified to @code{x * 2}. +For example: @code{(x * 10) / 5} is simplified to @code{x * 2}. @item -Wstrict-overflow=5 Also warn about cases where the compiler reduces the magnitude of a -constant involved in a comparison. For example: @code{x + 2 > y} will -be simplified to @code{x + 1 >= y}. This is reported only at the +constant involved in a comparison. For example: @code{x + 2 > y} is +simplified to @code{x + 1 >= y}. This is reported only at the highest warning level because this simplification applies to many -comparisons, so this warning level will give a very large number of +comparisons, so this warning level gives a very large number of false positives. @end table @@ -3881,7 +3885,7 @@ that they usually do not indicate real problems and would only make the compiler output harder to read. Using this command-line option tells GCC to emit warnings from system headers as if they occurred in user code. However, note that using @option{-Wall} in conjunction with this -option will @emph{not} warn about unknown pragmas in system +option does @emph{not} warn about unknown pragmas in system headers---for that, @option{-Wunknown-pragmas} must also be used. @item -Wtrampolines @@ -3908,7 +3912,7 @@ to compute (by analyzing the code, or in some other way) the maximum or likely maximum error that the computation introduces, and allow for it when performing comparisons (and when producing output, but that's a different problem). In particular, instead of testing for equality, you -would check to see whether the two values have ranges that overlap; and +should check to see whether the two values have ranges that overlap; and this is done with the relational operators, so equality comparisons are probably mistaken. @@ -3927,13 +3931,13 @@ but does not in ISO C@. @item In traditional C, some preprocessor directives did not exist. -Traditional preprocessors would only consider a line to be a directive +Traditional preprocessors only considered a line to be a directive if the @samp{#} appeared in column 1 on the line. Therefore @option{-Wtraditional} warns about directives that traditional C -understands but would ignore because the @samp{#} does not appear as the +understands but ignores because the @samp{#} does not appear as the first character on the line. It also suggests you hide directives like @samp{#pragma} not understood by traditional C by indenting them. Some -traditional implementations would not recognize @samp{#elif}, so it +traditional implementations do not recognize @samp{#elif}, so this option suggests avoiding it altogether. @item @@ -3988,13 +3992,13 @@ traditional C case. @item Conversions by prototypes between fixed/floating-point values and vice versa. The absence of these prototypes when compiling with traditional -C would cause serious problems. This is a subset of the possible -conversion warnings, for the full set use @option{-Wtraditional-conversion}. +C causes serious problems. This is a subset of the possible +conversion warnings; for the full set use @option{-Wtraditional-conversion}. @item Use of ISO C style function definitions. This warning intentionally is @emph{not} issued for prototype declarations or variadic functions -because these ISO C features will appear in your code when using +because these ISO C features appear in your code when using libiberty's traditional C compatibility macros, @code{PARAMS} and @code{VPARAMS}. This warning is also bypassed for nested functions because that feature is already a GCC extension and thus not relevant to @@ -4033,8 +4037,8 @@ Do not warn whenever an @samp{#else} or an @samp{#endif} are followed by text. @opindex Wno-shadow Warn whenever a local variable or type declaration shadows another variable, parameter, type, or class member (in C++), or whenever a built-in function -is shadowed. Note that in C++, the compiler will not warn if a local variable -shadows a struct/class/enum, but will warn if it shadows an explicit typedef. +is shadowed. Note that in C++, the compiler warns if a local variable +shadows an explicit typedef, but not if it shadows a struct/class/enum. @item -Wlarger-than=@var{len} @opindex Wlarger-than=@var{len} @@ -4092,9 +4096,9 @@ If the stack usage is (partly) dynamic and not bounded, it's: @item -Wunsafe-loop-optimizations @opindex Wunsafe-loop-optimizations @opindex Wno-unsafe-loop-optimizations -Warn if the loop cannot be optimized because the compiler could not +Warn if the loop cannot be optimized because the compiler cannot assume anything on the bounds of the loop indices. With -@option{-funsafe-loop-optimizations} warn if the compiler made +@option{-funsafe-loop-optimizations} warn if the compiler makes such assumptions. @item -Wno-pedantic-ms-format @r{(MinGW targets only)} @@ -4173,11 +4177,11 @@ two- or four-byte boundaries. @opindex Wno-write-strings When compiling C, give string constants the type @code{const char[@var{length}]} so that copying the address of one into a -non-@code{const} @code{char *} pointer will get a warning. These -warnings will help you find at compile time code that can try to write +non-@code{const} @code{char *} pointer produces a warning. These +warnings help you find at compile time code that can try to write into a string constant, but only if you have been very careful about -using @code{const} in declarations and prototypes. Otherwise, it will -just be a nuisance. This is why we did not make @option{-Wall} request +using @code{const} in declarations and prototypes. Otherwise, it is +just a nuisance. This is why we did not make @option{-Wall} request these warnings. When compiling C++, warn about the deprecated conversion from string @@ -4204,7 +4208,7 @@ conversions between signed and unsigned integers can be disabled by using @option{-Wno-sign-conversion}. For C++, also warn for confusing overload resolution for user-defined -conversions; and conversions that will never use a type conversion +conversions; and conversions that never use a type conversion operator: conversions to @code{void}, the same type, a base class or a reference to them. Warnings about conversions between signed and unsigned integers are disabled by default in C++ unless @@ -4306,7 +4310,7 @@ a warning.) @opindex Wattributes Do not warn if an unexpected @code{__attribute__} is used, such as unrecognized attributes, function attributes applied to variables, -etc. This will not stop errors for incorrect use of supported +etc. This does not stop errors for incorrect use of supported attributes. @item -Wno-builtin-macro-redefined @@ -4374,7 +4378,7 @@ or for inline functions, or for functions in anonymous namespaces. @opindex Wextra @opindex Wno-extra Warn if a structure's initializer has some fields missing. For -example, the following code would cause such a warning, because +example, the following code causes such a warning, because @code{x.h} is implicitly zero: @smallexample @@ -4383,7 +4387,7 @@ struct s x = @{ 3, 4 @}; @end smallexample This option does not warn about designated initializers, so the following -modification would not trigger a warning: +modification does not trigger a warning: @smallexample struct s @{ int f, g, h; @}; @@ -4400,7 +4404,7 @@ warnings without this one, use @option{-Wextra -Wno-missing-field-initializers}. @opindex Wno-format Warn about function pointers that might be candidates for @code{format} attributes. Note these are only possible candidates, not absolute ones. -GCC will guess that function pointers with @code{format} attributes that +GCC guesses that function pointers with @code{format} attributes that are used in assignment, initialization, parameter passing or return statements should have a corresponding @code{format} attribute in the resulting type. I.e.@: the left-hand side of the assignment or @@ -4408,9 +4412,9 @@ initialization, the type of the parameter variable, or the return type of the containing function respectively should also have a @code{format} attribute to avoid the warning. -GCC will also warn about function definitions that might be +GCC also warns about function definitions that might be candidates for @code{format} attributes. Again, these are only -possible candidates. GCC will guess that @code{format} attributes +possible candidates. GCC guesses that @code{format} attributes might be appropriate for any function that calls a function like @code{vprintf} or @code{vscanf}, but this might not always be the case, and some functions for which @code{format} attributes are @@ -4451,22 +4455,22 @@ It is hoped that future versions of the standards involved will correct this, which is why this option is not the default. You can switch the warning off for all characters by writing -@option{-Wnormalized=none}. You would only want to do this if you -were using some other normalization scheme (like ``D''), because +@option{-Wnormalized=none}. You should only do this if you +are using some other normalization scheme (like ``D''), because otherwise you can easily create bugs that are literally impossible to see. Some characters in ISO 10646 have distinct meanings but look identical in some fonts or display methodologies, especially once formatting has been applied. For instance @code{\u207F}, ``SUPERSCRIPT LATIN SMALL -LETTER N'', will display just like a regular @code{n} that has been +LETTER N'', displays just like a regular @code{n} that has been placed in a superscript. ISO 10646 defines the @dfn{NFKC} normalization scheme to convert all these into a standard form as -well, and GCC will warn if your code is not in NFKC if you use +well, and GCC warns if your code is not in NFKC if you use @option{-Wnormalized=nfkc}. This warning is comparable to warning about every identifier that contains the letter O because it might be confused with the digit 0, and so is not the default, but may be -useful as a local coding convention if the programming environment is -unable to be fixed to display these characters distinctly. +useful as a local coding convention if the programming environment +cannot be fixed to display these characters distinctly. @item -Wno-deprecated @opindex Wno-deprecated @@ -4507,7 +4511,7 @@ Warn if a structure is given the packed attribute, but the packed attribute has no effect on the layout or size of the structure. Such structures may be mis-aligned for little benefit. For instance, in this code, the variable @code{f.x} in @code{struct bar} -will be misaligned even though @code{struct bar} does not itself +is misaligned even though @code{struct bar} does not itself have the packed attribute: @smallexample @@ -4566,8 +4570,8 @@ Warn if an @code{extern} declaration is encountered within a function. @item -Winline @opindex Winline @opindex Wno-inline -Warn if a function can not be inlined and it was declared as inline. -Even with this option, the compiler will not warn about failures to +Warn if a function that is declared as inline cannot be inlined. +Even with this option, the compiler does not warn about failures to inline functions declared in system headers. The compiler uses a variety of heuristics to determine whether or not @@ -4643,7 +4647,7 @@ scalar type. @opindex Wvla @opindex Wno-vla Warn if variable length array is used in the code. -@option{-Wno-vla} will prevent the @option{-pedantic} warning of +@option{-Wno-vla} prevents the @option{-pedantic} warning of the variable length array. @item -Wvolatile-register-var @@ -4659,9 +4663,9 @@ and/or writes to register variables. This warning is enabled by @opindex Wno-disabled-optimization Warn if a requested optimization pass is disabled. This warning does not generally indicate that there is anything wrong with your code; it -merely indicates that GCC's optimizers were unable to handle the code +merely indicates that GCC's optimizers are unable to handle the code effectively. Often, the problem is that your code is too big or too -complex; GCC will refuse to optimize programs when the optimization +complex; GCC refuses to optimize programs when the optimization itself is likely to take inordinate amounts of time. @item -Wpointer-sign @r{(C and Objective-C only)} @@ -4676,7 +4680,7 @@ This option is only supported for C and Objective-C@. It is implied by @opindex Wstack-protector @opindex Wno-stack-protector This option is only active when @option{-fstack-protector} is active. It -warns about functions that will not be protected against stack smashing. +warns about functions that are not protected against stack smashing. @item -Wno-mudflap @opindex Wno-mudflap @@ -4703,9 +4707,9 @@ This option is implied by @option{-pedantic}, and can be disabled with @item -Wunsuffixed-float-constants @r{(C and Objective-C only)} @opindex Wunsuffixed-float-constants -GCC will issue a warning for any floating constant that does not have -a suffix. When used together with @option{-Wsystem-headers} it will -warn about such constants in system header files. This can be useful +Issue a warning for any floating constant that does not have +a suffix. When used together with @option{-Wsystem-headers} it +warns about such constants in system header files. This can be useful when preparing code to use with the @code{FLOAT_CONST_DECIMAL64} pragma from the decimal floating-point extension to C99. @end table @@ -4727,7 +4731,7 @@ information. On most systems that use stabs format, @option{-g} enables use of extra debugging information that only GDB can use; this extra information -makes debugging work better in GDB but will probably make other debuggers +makes debugging work better in GDB but probably makes other debuggers crash or refuse to read the program. If you want to control for certain whether to generate the extra information, use @option{-gstabs+}, @option{-gstabs}, @@ -4738,8 +4742,8 @@ GCC allows you to use @option{-g} with produce surprising results: some variables you declared may not exist at all; flow of control may briefly move where you did not expect it; some statements may not be executed because they compute constant -results or their values were already at hand; some statements may -execute in different places because they were moved out of loops. +results or their values are already at hand; some statements may +execute in different places because they have been moved out of loops. Nevertheless it proves possible to debug optimized output. This makes it reasonable to use the optimizer for programs that might have bugs. @@ -4772,17 +4776,17 @@ Instead of emitting debugging information for a C++ class in only one object file, emit it in all object files using the class. This option should be used only with debuggers that are unable to handle the way GCC normally emits debugging information for classes because using this -option will increase the size of debugging information by as much as a +option increases the size of debugging information by as much as a factor of two. @item -fno-debug-types-section @opindex fno-debug-types-section @opindex fdebug-types-section -By default when using DWARF Version 4 or higher type DIEs will be put into -their own .debug_types section instead of making them part of the -.debug_info section. It is more efficient to put them in a separate -comdat sections since the linker will then be able to remove duplicates. -But not all DWARF consumers support .debug_types sections yet. +By default when using DWARF Version 4 or higher, type DIEs are put into +their own @code{.debug_types} section instead of making them part of the +@code{.debug_info} section. It is more efficient to put them in a separate +comdat sections since the linker can then remove duplicates. +But not all DWARF consumers support @code{.debug_types} sections yet. @item -gstabs+ @opindex gstabs+ @@ -4815,8 +4819,8 @@ assembler (GAS) to fail with an error. Produce debugging information in DWARF format (if that is supported). The value of @var{version} may be either 2, 3 or 4; the default version is 2. -Note that with DWARF Version 2 some ports require, and will always -use, some non-conflicting DWARF 3 extensions in the unwind tables. +Note that with DWARF Version 2, some ports require and always +use some non-conflicting DWARF 3 extensions in the unwind tables. Version 4 may require GDB 7.0 and @option{-fvar-tracking-assignments} for maximum benefit. @@ -4882,9 +4886,9 @@ debug level for DWARF. @item -gtoggle @opindex gtoggle -Turn off generation of debug info, if leaving out this option would have -generated it, or turn it on at level 2 otherwise. The position of this -argument in the command line does not matter, it takes effect after all +Turn off generation of debug info, if leaving out this option +generates it, or turn it on at level 2 otherwise. The position of this +argument in the command line does not matter; it takes effect after all other options are processed, and it does so only once, no matter how many times it is given. This is mainly intended to be used with @option{-fcompare-debug}. @@ -4893,7 +4897,7 @@ many times it is given. This is mainly intended to be used with @opindex fdump-final-insns Dump the final internal representation (RTL) to @var{file}. If the optional argument is omitted (or if @var{file} is @code{.}), the name -of the dump file will be determined by appending @code{.gkd} to the +of the dump file is determined by appending @code{.gkd} to the compilation output file name. @item -fcompare-debug@r{[}=@var{opts}@r{]} @@ -4919,7 +4923,7 @@ of the final representation and the second compilation, preventing even To verify full coverage during @option{-fcompare-debug} testing, set @env{GCC_COMPARE_DEBUG} to say @samp{-fcompare-debug-not-overridden}, -which GCC will reject as an invalid option in any actual compilation +which GCC rejects as an invalid option in any actual compilation (rather than preprocessing, assembly or linking). To get just a warning, setting @env{GCC_COMPARE_DEBUG} to @samp{-w%n-fcompare-debug not overridden} will do. @@ -4947,7 +4951,7 @@ generating DWARF 2 debugging information with @option{-gdwarf-2}. @item -femit-struct-debug-baseonly Emit debug information for struct-like types only when the base name of the compilation source file -matches the base name of file in which the struct was defined. +matches the base name of file in which the struct is defined. This option substantially reduces the size of debugging information, but at significant potential loss in type information to the debugger. @@ -4959,7 +4963,7 @@ This option works only with DWARF 2. @item -femit-struct-debug-reduced Emit debug information for struct-like types only when the base name of the compilation source file -matches the base name of file in which the type was defined, +matches the base name of file in which the type is defined, unless the struct is a template or defined in a system header. This option significantly reduces the size of debugging information, @@ -4971,13 +4975,13 @@ This option works only with DWARF 2. @item -femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]} Specify the struct-like types -for which the compiler will generate debug information. +for which the compiler generates debug information. The intent is to reduce duplicate struct debug information between different object files within the same program. This option is a detailed version of @option{-femit-struct-debug-reduced} and @option{-femit-struct-debug-baseonly}, -which will serve for most needs. +which serves for most needs. A specification has the syntax@* [@samp{dir:}|@samp{ind:}][@samp{ord:}|@samp{gen:}](@samp{any}|@samp{sys}|@samp{base}|@samp{none}) @@ -4986,7 +4990,7 @@ The optional first word limits the specification to structs that are used directly (@samp{dir:}) or used indirectly (@samp{ind:}). A struct type is used directly when it is the type of a variable, member. Indirect uses arise through pointers to structs. -That is, when use of an incomplete struct would be legal, the use is indirect. +That is, when use of an incomplete struct is valid, the use is indirect. An example is @samp{struct one direct; struct two * indirect;}. @@ -4999,14 +5003,14 @@ Other programming languages have generics, but @option{-femit-struct-debug-detailed} does not yet implement them. The third word specifies the source files for those -structs for which the compiler will emit debug information. +structs for which the compiler should emit debug information. The values @samp{none} and @samp{any} have the normal meaning. The value @samp{base} means that the base of name of the file in which the type declaration appears must match the base of the name of the main compilation file. -In practice, this means that -types declared in @file{foo.c} and @file{foo.h} will have debug information, -but types declared in other header will not. +In practice, this means that when compiling @file{foo.c}, debug information +is generated for types declared in that file and @file{foo.h}, +but not other header files. The value @samp{sys} means those types satisfying @samp{base} or declared in system or compiler headers. @@ -5181,8 +5185,8 @@ Produce a notes file that the @command{gcov} code-coverage utility show program coverage. Each source file's note file is called @file{@var{auxname}.gcno}. Refer to the @option{-fprofile-arcs} option above for a description of @var{auxname} and instructions on how to -generate test coverage data. Coverage data will match the source files -more closely, if you do not optimize. +generate test coverage data. Coverage data matches the source files +more closely if you do not optimize. @item -fdbg-cnt-list @opindex fdbg-cnt-list @@ -5573,7 +5577,7 @@ standard error. @item -dp @opindex dp Annotate the assembler output with a comment indicating which -pattern and alternative was used. The length of each instruction is +pattern and alternative is used. The length of each instruction is also printed. @item -dP @@ -5665,8 +5669,8 @@ Enable and control dumping of pass statistics in a separate file. The file name is generated by appending a suffix ending in @samp{.statistics} to the source file name, and the file is created in the same directory as the output file. If the @samp{-@var{option}} -form is used, @samp{-stats} will cause counters to be summed over the -whole compilation unit while @samp{-details} will dump every event as +form is used, @samp{-stats} causes counters to be summed over the +whole compilation unit while @samp{-details} dumps every event as the passes generate them. The default with no option is to sum counters for each function compiled. @@ -5680,7 +5684,7 @@ created in the same directory as the output file. If the @samp{-@var{options}} form is used, @var{options} is a list of @samp{-} separated options which control the details of the dump. Not all options are applicable to all dumps; those that are not -meaningful will be ignored. The following options are available +meaningful are ignored. The following options are available @table @samp @item address @@ -5749,7 +5753,7 @@ made by appending @file{.cfg} to the source file name. Dump the control flow graph of each function to a file in VCG format. The file name is made by appending @file{.vcg} to the source file name. Note that if the file contains more than one function, the generated file cannot -be used directly by VCG@. You will need to cut and paste each function's +be used directly by VCG@. You must cut and paste each function's graph into its own separate file first. @item ch @@ -5898,8 +5902,8 @@ that @option{-fdump-tree-vect-details} uses. @item -frandom-seed=@var{string} @opindex frandom-seed -This option provides a seed that GCC uses when it would otherwise use -random numbers. It is used to generate certain symbol names +This option provides a seed that GCC uses in place of +random numbers in generating certain symbol names that have to be different in every compiled file. It is also used to place unique stamps in coverage data files and the object files that produce them. You can use the @option{-frandom-seed} option to produce @@ -5930,7 +5934,7 @@ dependence info. @opindex save-temps Store the usual ``temporary'' intermediate files permanently; place them in the current directory and name them based on the source file. Thus, -compiling @file{foo.c} with @option{-c -save-temps} would produce files +compiling @file{foo.c} with @option{-c -save-temps} produces files @file{foo.i} and @file{foo.s}, as well as @file{foo.o}. This creates a preprocessed @file{foo.i} output file even though the compiler now normally uses an integrated preprocessor. @@ -5970,7 +5974,8 @@ gcc -save-temps=obj -c bar.c -o dir/xbar.o gcc -save-temps=obj foobar.c -o dir2/yfoobar @end smallexample -would create @file{foo.i}, @file{foo.s}, @file{dir/xbar.i}, +@noindent +creates @file{foo.i}, @file{foo.s}, @file{dir/xbar.i}, @file{dir/xbar.s}, @file{dir2/yfoobar.i}, @file{dir2/yfoobar.s}, and @file{dir2/yfoobar.o}. @@ -6023,7 +6028,7 @@ way to the end, in an attempt to improve debug information while optimizing. Use of @option{-gdwarf-4} is recommended along with it. It can be enabled even if var-tracking is disabled, in which case -annotations will be created and maintained, but discarded at the end. +annotations are created and maintained, but discarded at the end. @item -fvar-tracking-assignments-toggle @opindex fvar-tracking-assignments-toggle @@ -6080,7 +6085,7 @@ gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name` @item -print-search-dirs @opindex print-search-dirs Print the name of the configured installation directory and a list of -program and library directories @command{gcc} will search---and don't do anything else. +program and library directories @command{gcc} searches---and don't do anything else. This is useful when @command{gcc} prints the error message @samp{installation problem, cannot exec cpp0: No such file or directory}. @@ -6092,7 +6097,7 @@ Don't forget the trailing @samp{/}. @item -print-sysroot @opindex print-sysroot -Print the target sysroot directory that will be used during +Print the target sysroot directory that is used during compilation. This is the target sysroot specified either at configure time or using the @option{--sysroot} option, possibly with an extra suffix that depends on compilation options. If no target sysroot is @@ -6121,14 +6126,14 @@ is used when GCC itself is being built.) @xref{Spec Files}. @item -feliminate-unused-debug-types @opindex feliminate-unused-debug-types -Normally, when producing DWARF 2 output, GCC will emit debugging +Normally, when producing DWARF 2 output, GCC emits debugging information for all types declared in a compilation unit, regardless of whether or not they are actually used in that compilation unit. Sometimes this is useful, such as if, in the debugger, you want to cast a value to a type that is not actually used in your program (but is declared). More often, however, this results in a significant amount of wasted space. -With this option, GCC will avoid producing debug symbol output +With this option, GCC avoids producing debug symbol output for types that are nowhere used in the source file being compiled. @end table @@ -6144,7 +6149,7 @@ cost of compilation and to make debugging produce the expected results. Statements are independent: if you stop the program with a breakpoint between statements, you can then assign a new value to any variable or change the program counter to any other statement in the -function and get exactly the results you would expect from the source +function and get exactly the results you expect from the source code. Turning on optimization flags makes the compiler attempt to improve @@ -6293,8 +6298,8 @@ the last such option is the one that is effective. Options of the form @option{-f@var{flag}} specify machine-independent flags. Most flags have both positive and negative forms; the negative -form of @option{-ffoo} would be @option{-fno-foo}. In the table -below, only one of the forms is listed---the one you typically will +form of @option{-ffoo} is @option{-fno-foo}. In the table +below, only one of the forms is listed---the one you typically use. You can figure out the other form by either removing @samp{no-} or adding it. @@ -6489,7 +6494,7 @@ Emit variables declared @code{static const} when optimization isn't turned on, even if the variables aren't referenced. GCC enables this option by default. If you want to force the compiler to -check if the variable was referenced, regardless of whether or not +check if a variable is referenced, regardless of whether or not optimization is turned on, use the @option{-fno-keep-static-consts} option. @item -fmerge-constants @@ -6512,7 +6517,7 @@ This option implies @option{-fmerge-constants}. In addition to arrays or initialized constant variables with integral or floating-point types. Languages like C or C++ require each variable, including multiple instances of the same variable in recursive calls, to have distinct locations, -so using this option will result in non-conforming +so using this option results in non-conforming behavior. @item -fmodulo-sched @@ -6523,9 +6528,9 @@ instructions by overlapping different iterations. @item -fmodulo-sched-allow-regmoves @opindex fmodulo-sched-allow-regmoves -Perform more aggressive SMS based modulo scheduling with register moves -allowed. By setting this flag certain anti-dependences edges will be -deleted which will trigger the generation of reg-moves based on the +Perform more aggressive SMS-based modulo scheduling with register moves +allowed. By setting this flag certain anti-dependences edges are +deleted, which triggers the generation of reg-moves based on the life-range analysis. This option is effective only with @option{-fmodulo-sched} enabled. @@ -6575,7 +6580,7 @@ string/heap functions, and some other associated constructs with range/validity tests. Modules so instrumented should be immune to buffer overflows, invalid heap use, and some other classes of C/C++ programming errors. The instrumentation relies on a separate runtime -library (@file{libmudflap}), which will be linked into a program if +library (@file{libmudflap}), which is linked into a program if @option{-fmudflap} is given at link time. Run-time behavior of the instrumented program is controlled by the @env{MUDFLAP_OPTIONS} environment variable. See @code{env MUDFLAP_OPTIONS=-help a.out} @@ -6614,7 +6619,7 @@ Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, In common subexpression elimination (CSE), scan through jump instructions when the target of the jump is not reached by any other path. For example, when CSE encounters an @code{if} statement with an -@code{else} clause, CSE will follow the jump when the condition +@code{else} clause, CSE follows the jump when the condition tested is false. Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. @@ -6631,7 +6636,7 @@ Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. @item -frerun-cse-after-loop @opindex frerun-cse-after-loop -Re-run common subexpression elimination after loop optimizations has been +Re-run common subexpression elimination after loop optimizations are performed. Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. @@ -6650,17 +6655,17 @@ Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. @item -fgcse-lm @opindex fgcse-lm -When @option{-fgcse-lm} is enabled, global common subexpression elimination will -attempt to move loads that are only killed by stores into themselves. This +When @option{-fgcse-lm} is enabled, global common subexpression elimination +attempts to move loads that are only killed by stores into themselves. This allows a loop containing a load/store sequence to be changed to a load outside the loop, and a copy/store within the loop. -Enabled by default when gcse is enabled. +Enabled by default when @option{-fgcse} is enabled. @item -fgcse-sm @opindex fgcse-sm When @option{-fgcse-sm} is enabled, a store motion pass is run after -global common subexpression elimination. This pass will attempt to move +global common subexpression elimination. This pass attempts to move stores out of loops. When used in conjunction with @option{-fgcse-lm}, loops containing a load/store sequence can be changed to a load before the loop and a store after the loop. @@ -6683,11 +6688,11 @@ redundant spilling. @item -funsafe-loop-optimizations @opindex funsafe-loop-optimizations -If given, the loop optimizer will assume that loop indices do not +If given, the loop optimizer assumes that loop indices do not overflow, and that the loops with nontrivial exit condition are not infinite. This enables a wider range of loop optimizations even if the loop optimizer itself cannot prove that these assumptions are valid. -Using @option{-Wunsafe-loop-optimizations}, the compiler will warn you +If you use @option{-Wunsafe-loop-optimizations}, the compiler warns you if it finds this kind of loop. @item -fcrossjumping @@ -6911,8 +6916,8 @@ sense when scheduling before register allocation, i.e.@: with @itemx -fsched-stalled-insns=@var{n} @opindex fsched-stalled-insns Define how many insns (if any) can be moved prematurely from the queue -of stalled insns into the ready list, during the second scheduling pass. -@option{-fno-sched-stalled-insns} means that no insns will be moved +of stalled insns into the ready list during the second scheduling pass. +@option{-fno-sched-stalled-insns} means that no insns are moved prematurely, @option{-fsched-stalled-insns=0} means there is no limit on how many queued insns can be moved prematurely. @option{-fsched-stalled-insns} without a value is equivalent to @@ -6921,8 +6926,8 @@ on how many queued insns can be moved prematurely. @item -fsched-stalled-insns-dep @itemx -fsched-stalled-insns-dep=@var{n} @opindex fsched-stalled-insns-dep -Define how many insn groups (cycles) will be examined for a dependency -on a stalled insn that is candidate for premature removal from the queue +Define how many insn groups (cycles) are examined for a dependency +on a stalled insn that is a candidate for premature removal from the queue of stalled insns. This has an effect only during the second scheduling pass, and only if @option{-fsched-stalled-insns} is used. @option{-fno-sched-stalled-insns-dep} is equivalent to @@ -6989,9 +6994,9 @@ at @option{-O2} or higher. @item -freschedule-modulo-scheduled-loops @opindex freschedule-modulo-scheduled-loops -The modulo scheduling comes before the traditional scheduling, if a loop -was modulo scheduled we may want to prevent the later scheduling passes -from changing its schedule, we use this option to control that. +The modulo scheduling comes before the traditional scheduling. If a loop +is modulo scheduled you may want to prevent the later scheduling passes +from changing its schedule; use this option to control that. @item -fselective-scheduling @opindex fselective-scheduling @@ -7022,10 +7027,10 @@ rather than at the top of the function. This flag is enabled by default at @item -fcaller-saves @opindex fcaller-saves -Enable values to be allocated in registers that will be clobbered by +Enable allocation of values to registers that are clobbered by function calls, by emitting extra instructions to save and restore the registers around such calls. Such allocation is done only when it -seems to result in better code than would otherwise be produced. +seems to result in better code. This option is always enabled by default on certain machines, usually those which have no call-preserved registers to use instead. @@ -7041,7 +7046,7 @@ Enabled by default at @option{-O1} and higher. @item -fconserve-stack @opindex fconserve-stack -Attempt to minimize stack usage. The compiler will attempt to use less +Attempt to minimize stack usage. The compiler attempts to use less stack space, even if that makes the program slower. This option implies setting the @option{large-stack-frame} parameter to 100 and the @option{large-stack-frame-growth} parameter to 400. @@ -7119,7 +7124,7 @@ This flag is enabled by default at @option{-O2}, @option{-Os} and @option{-O3}. @item -fipa-cp-clone @opindex fipa-cp-clone Perform function cloning to make interprocedural constant propagation stronger. -When enabled, interprocedural constant propagation will perform function cloning +When enabled, interprocedural constant propagation performs function cloning when externally visible function can be called with constant arguments. Because this optimization can create multiple copies of functions, it may significantly increase code size @@ -7227,7 +7232,7 @@ DO J = 1, M ENDDO ENDDO @end smallexample -loop interchange will transform the loop as if the user had written: +loop interchange transforms the loop as if it were written: @smallexample DO I = 1, N DO J = 1, M @@ -7257,7 +7262,7 @@ DO I = 1, N A(I) = A(I) + C ENDDO @end smallexample -loop strip mining will transform the loop as if the user had written: +loop strip mining transforms the loop as if it were written: @smallexample DO II = 1, N, 51 DO I = II, min (II + 50, N) @@ -7284,7 +7289,7 @@ DO I = 1, N ENDDO ENDDO @end smallexample -loop blocking will transform the loop as if the user had written: +loop blocking transforms the loop as if it were written: @smallexample DO II = 1, N, 51 DO JJ = 1, M, 51 @@ -7297,7 +7302,7 @@ DO II = 1, N, 51 ENDDO @end smallexample which can be beneficial when @code{M} is larger than the caches, -because the innermost loop will iterate over a smaller amount of data +because the innermost loop iterates over a smaller amount of data which can be kept in the caches. This optimization applies to all the languages supported by GCC and is not limited to Fortran. To use this code transformation, GCC has to be configured with @option{--with-ppl} @@ -7342,7 +7347,7 @@ for (i = 0; i < N; i++) if (cond) A[i] = expr; @end smallexample -would be transformed to +is transformed to @smallexample for (i = 0; i < N; i++) A[i] = cond ? expr : A[i]; @@ -7395,7 +7400,7 @@ and the initialization loop is transformed into a call to memset zero. @item -ftree-loop-im @opindex ftree-loop-im Perform loop invariant motion on trees. This pass moves only invariants that -would be hard to handle at RTL level (function calls, operations that expand to +are hard to handle at RTL level (function calls, operations that expand to nontrivial sequences of insns). With @option{-funswitch-loops} it also moves operands of conditions that are invariant out of the loop, so that we can use just trivial invariantness analysis in loop unswitching. The pass also includes @@ -7517,8 +7522,8 @@ This optimization is enabled by default. @item -fvariable-expansion-in-unroller @opindex fvariable-expansion-in-unroller -With this option, the compiler will create multiple copies of some -local variables when unrolling a loop which can result in superior code. +With this option, the compiler creates multiple copies of some +local variables when unrolling a loop, which can result in superior code. @item -fpartial-inlining @opindex fpartial-inlining @@ -7562,10 +7567,10 @@ other, a few use both. @opindex fno-guess-branch-probability Do not guess branch probabilities using heuristics. -GCC will use heuristics to guess branch probabilities if they are +GCC uses heuristics to guess branch probabilities if they are not provided by profiling feedback (@option{-fprofile-arcs}). These heuristics are based on the control flow graph. If some branch probabilities -are specified by @samp{__builtin_expect}, then the heuristics will be +are specified by @samp{__builtin_expect}, then the heuristics are used to guess branch probabilities for the rest of the control flow graph, taking the @samp{__builtin_expect} info into account. The interactions between the heuristics and @samp{__builtin_expect} can be complex, and in @@ -7635,7 +7640,7 @@ int f() @{ The practice of reading from a different union member than the one most recently written to (called ``type-punning'') is common. Even with @option{-fstrict-aliasing}, type-punning is allowed, provided the memory -is accessed through the union type. So, the code above will work as +is accessed through the union type. So, the code above works as expected. @xref{Structures unions enumerations and bit-fields implementation}. However, this code might not: @smallexample @@ -7666,14 +7671,14 @@ The @option{-fstrict-aliasing} option is enabled at levels Allow the compiler to assume strict signed overflow rules, depending on the language being compiled. For C (and C++) this means that overflow when doing arithmetic with signed numbers is undefined, which -means that the compiler may assume that it will not happen. This -permits various optimizations. For example, the compiler will assume -that an expression like @code{i + 10 > i} will always be true for +means that the compiler may assume that it does not happen. This +permits various optimizations. For example, the compiler assumes +that an expression like @code{i + 10 > i} is always true for signed @code{i}. This assumption is only valid if signed overflow is undefined, as the expression is false if @code{i + 10} overflows when using twos complement arithmetic. When this option is in effect any -attempt to determine whether an operation on signed numbers will -overflow must be written carefully to not actually involve overflow. +attempt to determine whether an operation on signed numbers +overflows must be written carefully to not actually involve overflow. This option also allows the compiler to assume strict pointer semantics: given a pointer to an object, if adding an offset to that @@ -7702,11 +7707,11 @@ The @option{-fstrict-overflow} option is enabled at levels Align the start of functions to the next power-of-two greater than @var{n}, skipping up to @var{n} bytes. For instance, @option{-falign-functions=32} aligns functions to the next 32-byte -boundary, but @option{-falign-functions=24} would align to the next +boundary, but @option{-falign-functions=24} aligns to the next 32-byte boundary only if this can be done by skipping 23 bytes or less. @option{-fno-align-functions} and @option{-falign-functions=1} are -equivalent and mean that functions will not be aligned. +equivalent and mean that functions are not aligned. Some assemblers only support this flag when @var{n} is a power of two; in that case, it is rounded up. @@ -7724,7 +7729,7 @@ make code slower, because it must insert dummy operations for when the branch target is reached in the usual flow of the code. @option{-fno-align-labels} and @option{-falign-labels=1} are -equivalent and mean that labels will not be aligned. +equivalent and mean that labels are not aligned. If @option{-falign-loops} or @option{-falign-jumps} are applicable and are greater than this value, then their values are used instead. @@ -7738,12 +7743,12 @@ Enabled at levels @option{-O2}, @option{-O3}. @itemx -falign-loops=@var{n} @opindex falign-loops Align loops to a power-of-two boundary, skipping up to @var{n} bytes -like @option{-falign-functions}. The hope is that the loop will be -executed many times, which will make up for any execution of the dummy +like @option{-falign-functions}. If the loops are +executed many times, this makes up for any execution of the dummy operations. @option{-fno-align-loops} and @option{-falign-loops=1} are -equivalent and mean that loops will not be aligned. +equivalent and mean that loops are not aligned. If @var{n} is not specified or is zero, use a machine-dependent default. @@ -7758,7 +7763,7 @@ bytes like @option{-falign-functions}. In this case, no dummy operations need be executed. @option{-fno-align-jumps} and @option{-falign-jumps=1} are -equivalent and mean that loops will not be aligned. +equivalent and mean that loops are not aligned. If @var{n} is not specified or is zero, use a machine-dependent default. @@ -7777,7 +7782,7 @@ Enabled by default. Do not reorder top-level functions, variables, and @code{asm} statements. Output them in the same order that they appear in the input file. When this option is used, unreferenced static variables -will not be removed. This option is intended to support existing code +are not removed. This option is intended to support existing code that relies on a particular ordering. For new code, it is better to use attributes. @@ -7791,7 +7796,7 @@ Constructs webs as commonly used for register allocation purposes and assign each web individual pseudo register. This allows the register allocation pass to operate on pseudos directly, but also strengthens several other optimization passes, such as CSE, loop optimizer and trivial dead code remover. It can, -however, make debugging impossible, since variables will no longer stay in a +however, make debugging impossible, since variables no longer stay in a ``home register''. Enabled by default with @option{-funroll-loops}. @@ -8068,8 +8073,8 @@ Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. @opindex fprofile-correction Profiles collected using an instrumented binary for multi-threaded programs may be inconsistent due to missed counter updates. When this option is specified, -GCC will use heuristics to correct or smooth out such inconsistencies. By -default, GCC will emit an error message when an inconsistent profile is detected. +GCC uses heuristics to correct or smooth out such inconsistencies. By +default, GCC emits an error message when an inconsistent profile is detected. @item -fprofile-dir=@var{path} @opindex fprofile-dir @@ -8079,8 +8084,8 @@ This option affects only the profile data generated by @option{-fprofile-generate}, @option{-ftest-coverage}, @option{-fprofile-arcs} and used by @option{-fprofile-use} and @option{-fbranch-probabilities} and its related options. Both absolute and relative paths can be used. -By default, GCC will use the current directory as @var{path}, thus the -profile data file will appear in the same directory as the object file. +By default, GCC uses the current directory as @var{path}, thus the +profile data file appears in the same directory as the object file. @item -fprofile-generate @itemx -fprofile-generate=@var{path} @@ -8093,7 +8098,7 @@ compiling and when linking your program. The following options are enabled: @code{-fprofile-arcs}, @code{-fprofile-values}, @code{-fvpt}. -If @var{path} is specified, GCC will look at the @var{path} to find +If @var{path} is specified, GCC looks at the @var{path} to find the profile feedback data files. See @option{-fprofile-dir}. @item -fprofile-use @@ -8110,7 +8115,7 @@ match the source code. This error can be turned into a warning by using @option{-Wcoverage-mismatch}. Note this may result in poorly optimized code. -If @var{path} is specified, GCC will look at the @var{path} to find +If @var{path} is specified, GCC looks at the @var{path} to find the profile feedback data files. See @option{-fprofile-dir}. @end table @@ -8145,7 +8150,7 @@ operations are carried out in the precision of the registers and that it is unpredictable when rounding to the types specified in the source code takes place. When compiling C, if @option{-fexcess-precision=standard} is specified then excess -precision will follow the rules specified in ISO C99; in particular, +precision follows the rules specified in ISO C99; in particular, both casts and assignments cause values to be rounded to their semantic types (whereas @option{-ffloat-store} only affects assignments). This option is enabled by default for C if a strict @@ -8392,9 +8397,9 @@ using the knowledge about the value of the denominator. @opindex frename-registers Attempt to avoid false dependencies in scheduled code by making use of registers left over after register allocation. This optimization -will most benefit processors with lots of registers. Depending on the +most benefits processors with lots of registers. Depending on the debug information format adopted by the target, however, it can -make debugging impossible, since variables will no longer stay in +make debugging impossible, since variables no longer stay in a ``home register''. Enabled by default with @option{-funroll-loops} and @option{-fpeel-loops}. @@ -8459,10 +8464,10 @@ linkers with such optimizations. AIX may have these optimizations in the future. Only use these options when there are significant benefits from doing -so. When you specify these options, the assembler and linker will -create larger object and executable files and will also be slower. -You will not be able to use @code{gprof} on all systems if you -specify this option and you may have problems with debugging if +so. When you specify these options, the assembler and linker +create larger object and executable files and are also slower. +You cannot use @code{gprof} on all systems if you +specify this option, and you may have problems with debugging if you specify both this option and @option{-g}. @item -fbranch-target-load-optimize @@ -8510,8 +8515,9 @@ static int a, b, c; int foo (void) @{ return a + b + c; @} @end smallexample -would usually calculate the addresses of all three variables, but if you -compile it with @option{-fsection-anchors}, it will access the variables +@noindent +usually calculates the addresses of all three variables, but if you +compile it with @option{-fsection-anchors}, it accesses the variables from a common anchor point instead. The effect is similar to the following pseudocode (which isn't valid C): @@ -8528,7 +8534,7 @@ Not all targets support this option. @item --param @var{name}=@var{value} @opindex param In some places, GCC uses various constants to control the amount of -optimization that is done. For example, GCC will not inline functions +optimization that is done. For example, GCC does not inline functions that contain more than a certain number of instructions. You can control some of these constants on the command line using the @option{--param} option. @@ -8554,7 +8560,7 @@ probably small improvement in executable size. @item min-crossjump-insns The minimum number of instructions that must be matched at the end -of two blocks before crossjumping will be performed on them. This +of two blocks before crossjumping is performed on them. This value is ignored in the case where all instructions in the block being crossjumped from are matched. The default value is 5. @@ -8574,8 +8580,8 @@ unfactored. The default value is 8. @item max-delay-slot-insn-search The maximum number of instructions to consider when looking for an instruction to fill a delay slot. If more than this arbitrary number of -instructions is searched, the time savings from filling the delay slot -will be minimal so stop searching. Increasing values mean more +instructions are searched, the time savings from filling the delay slot +are minimal, so stop searching. Increasing values mean more aggressive optimization, making the compilation time increase with probably small improvement in execution time. @@ -8588,18 +8594,18 @@ should be removed when the delay slot code is rewritten to maintain the control-flow graph. @item max-gcse-memory -The approximate maximum amount of memory that will be allocated in +The approximate maximum amount of memory that can be allocated in order to perform the global common subexpression elimination optimization. If more memory than specified is required, the -optimization will not be done. +optimization is not done. @item max-gcse-insertion-ratio If the ratio of expression insertions to deletions is larger than this value -for any expression, then RTL PRE will insert or remove the expression and thus -leave partially redundant computations in the instruction stream. The default value is 20. +for any expression, then RTL PRE inserts or removes the expression and thus +leaves partially redundant computations in the instruction stream. The default value is 20. @item max-pending-list-length -The maximum number of pending dependencies scheduling will allow +The maximum number of pending dependencies scheduling allows before flushing the current state and starting over. Large functions with few branches or calls can create excessively large lists which needlessly consume memory and resources. @@ -8613,14 +8619,14 @@ compilation time. Several parameters control the tree inliner used in GCC@. This number sets the maximum number of instructions (counted in GCC's internal representation) in a single function that the tree inliner -will consider for inlining. This only affects functions declared +considers for inlining. This only affects functions declared inline and methods implemented in a class declaration (C++). The default value is 400. @item max-inline-insns-auto When you use @option{-finline-functions} (included in @option{-O3}), a lot of functions that would otherwise not be considered for inlining -by the compiler will be investigated. To those functions, a different +by the compiler are investigated. To those functions, a different (more restrictive) limit compared to functions declared inline can be applied. The default value is 40. @@ -8714,10 +8720,10 @@ late inlining. @item comdat-sharing-probability @itemx comdat-sharing-probability Probability (in percent) that C++ inline function with comdat visibility -will be shared across multiple compilation units. The default value is 20. +are shared across multiple compilation units. The default value is 20. @item min-vect-loop-bound -The minimum number of iterations under which a loop will not get vectorized +The minimum number of iterations under which a loop is not vectorized when @option{-ftree-vectorize} is used. The number of iterations after vectorization needs to be greater than the value specified by this option to allow vectorization. The default value is 0. @@ -8726,23 +8732,23 @@ to allow vectorization. The default value is 0. Scaling factor in calculation of maximum distance an expression can be moved by GCSE optimizations. This is currently supported only in the code hoisting pass. The bigger the ratio, the more aggressive code hoisting -will be with simple expressions, i.e., the expressions that have cost -less than @option{gcse-unrestricted-cost}. Specifying 0 will disable +is with simple expressions, i.e., the expressions that have cost +less than @option{gcse-unrestricted-cost}. Specifying 0 disables hoisting of simple expressions. The default value is 10. @item gcse-unrestricted-cost Cost, roughly measured as the cost of a single typical machine -instruction, at which GCSE optimizations will not constrain +instruction, at which GCSE optimizations do not constrain the distance an expression can travel. This is currently supported only in the code hoisting pass. The lesser the cost, -the more aggressive code hoisting will be. Specifying 0 will -allow all expressions to travel unrestricted distances. +the more aggressive code hoisting is. Specifying 0 +allows all expressions to travel unrestricted distances. The default value is 3. @item max-hoist-depth The depth of search in the dominator tree for expressions to hoist. This is used to avoid quadratic behavior in hoisting algorithm. -The value of 0 will avoid limiting the search, but may slow down compilation +The value of 0 does not limit on the search, but may slow down compilation of huge functions. The default value is 30. @item max-tail-merge-comparisons @@ -8828,8 +8834,8 @@ The maximum number of equalities in an Omega constraint system. The default value is 128. @item omega-max-wild-cards -The maximum number of wildcard variables that the Omega solver will -be able to insert. The default value is 18. +The maximum number of wildcard variables that the Omega solver is +able to insert. The default value is 18. @item omega-hash-table-size The size of the hash table in the Omega solver. The default value is @@ -8868,19 +8874,20 @@ function given basic block needs to have to be considered hot. @item max-predicted-iterations The maximum number of loop iterations we predict statically. This is useful -in cases where function contain single loop with known bound and other loop -with unknown. We predict the known number of iterations correctly, while +in cases where a function contains a single loop with known bound and +another loop with unknown bound. +The known number of iterations is predicted correctly, while the unknown number of iterations average to roughly 10. This means that the -loop without bounds would appear artificially cold relative to the other one. +loop without bounds appears artificially cold relative to the other one. @item align-threshold -Select fraction of the maximal frequency of executions of basic block in -function given basic block will get aligned. +Select fraction of the maximal frequency of executions of a basic block in +a function to align the basic block. @item align-loop-iterations -A loop expected to iterate at lest the selected number of iterations will get +A loop expected to iterate at least the selected number of iterations is aligned. @item tracer-dynamic-coverage @@ -8896,7 +8903,7 @@ ones) are much less balanced allowing the threshold to be larger value. @item tracer-max-code-growth Stop tail duplication once code growth has reached given percentage. This is -rather hokey argument, as most of the duplicates will be eliminated later in +a rather artificial limit, as most of the duplicates are eliminated later in cross jumping, so it may be set to much higher values than is the desired code growth. @@ -8908,7 +8915,7 @@ threshold (in percent). @item tracer-min-branch-ratio @itemx tracer-min-branch-ratio-feedback -Stop forward growth if the best edge do have probability lower than this +Stop forward growth if the best edge has probability lower than this threshold. Similarly to @option{tracer-dynamic-coverage} two values are present, one for @@ -9017,7 +9024,7 @@ The default value is 3. @item sched-spec-prob-cutoff The minimal probability of speculation success (in percents), so that -speculative insn will be scheduled. +speculative insns are scheduled. The default value is 40. @item sched-mem-true-dep-cost @@ -9030,7 +9037,7 @@ depth of search for available instructions. The default value is 50. @item selsched-max-sched-times -The maximum number of times that an instruction will be scheduled during +The maximum number of times that an instruction is scheduled during selective scheduling. This is the limit on the number of iterations through which the instruction may be pipelined. The default value is 2. @@ -9039,8 +9046,8 @@ The maximum number of best instructions in the ready list that are considered for renaming in the selective scheduler. The default value is 2. @item sms-min-sc -The minimum value of stage count that swing modulo scheduler will -generate. The default value is 2. +The minimum value of stage count that swing modulo scheduler +generates. The default value is 2. @item max-last-value-rtl The maximum size measured as number of RTLs that can be recorded in an expression @@ -9065,7 +9072,7 @@ SSA updater switches to a full update for those symbols. The default ratio is 3. @item ssp-buffer-size -The minimum size of buffers (i.e.@: arrays) that will receive stack smashing +The minimum size of buffers (i.e.@: arrays) that receive stack smashing protection when @option{-fstack-protection} is used. @item max-jump-thread-duplication-stmts @@ -9073,7 +9080,7 @@ Maximum number of statements allowed in a block that needs to be duplicated when threading jumps. @item max-fields-for-field-sensitive -Maximum number of fields in a structure we will treat in +Maximum number of fields in a structure treated in a field sensitive manner during pointer analysis. The default is zero for @option{-O0} and @option{-O1}, and 100 for @option{-Os}, @option{-O2}, and @option{-O3}. @@ -9112,7 +9119,7 @@ bugs in the canonical type system are causing compilation failures, set this value to 0 to disable canonical types. @item switch-conversion-max-branch-ratio -Switch initialization conversion will refuse to create arrays that are +Switch initialization conversion refuses to create arrays that are bigger than @option{switch-conversion-max-branch-ratio} times the number of branches in the switch. @@ -9124,13 +9131,13 @@ the enhanced partial redundancy elimination optimization can run away, consuming all of the memory available on the host machine. This parameter sets a limit on the length of the sets that are computed, which prevents the runaway behavior. Setting a value of 0 for -this parameter will allow an unlimited set length. +this parameter allows an unlimited set length. @item sccvn-max-scc-size Maximum size of a strongly connected component (SCC) during SCCVN processing. If this limit is hit, SCCVN processing for the whole -function will not be done and optimizations depending on it will -be disabled. The default maximum SCC size is 10000. +function is not done and optimizations depending on it are +disabled. The default maximum SCC size is 10000. @item ira-max-loops-num IRA uses regional register allocation by default. If a function @@ -9166,8 +9173,8 @@ parameter is 1000 for @option{-O1} and 10000 for @option{-O2} and above. @item loop-max-datarefs-for-datadeps Building data dapendencies is expensive for very large loops. This parameter limits the number of data references in loops that are -considered for data dependence analysis. These large loops will not -be handled then by the optimizations using loop data dependencies. +considered for data dependence analysis. These large loops are no +handled by the optimizations using loop data dependencies. The default value is 1000. @item max-vartrack-size @@ -9195,14 +9202,14 @@ the parameter is reserved exclusively for debug insns created by (non-overlapping) uids above it if the reserved range is exhausted. @item ipa-sra-ptr-growth-factor -IPA-SRA will replace a pointer to an aggregate with one or more new +IPA-SRA replaces a pointer to an aggregate with one or more new parameters only when their cumulative size is less or equal to @option{ipa-sra-ptr-growth-factor} times the size of the original pointer parameter. @item tm-max-aggregate-size When making copies of thread-local variables in a transaction, this -parameter specifies the size in bytes after which variables will be +parameter specifies the size in bytes after which variables are saved with the logging functions as opposed to save/restore code sequence pairs. This option only applies when using @option{-fgnu-tm}. @@ -9438,9 +9445,9 @@ or @option{-nodefaultlibs} is used. @item -nodefaultlibs @opindex nodefaultlibs Do not use the standard system libraries when linking. -Only the libraries you specify will be passed to the linker, options +Only the libraries you specify are passed to the linker, and options specifying linkage of the system libraries, such as @code{-static-libgcc} -or @code{-shared-libgcc}, will be ignored. +or @code{-shared-libgcc}, are ignored. The standard startup files are used normally, unless @option{-nostartfiles} is used. The compiler may generate calls to @code{memcmp}, @code{memset}, @code{memcpy} and @code{memmove}. @@ -9451,9 +9458,10 @@ mechanism when this option is specified. @item -nostdlib @opindex nostdlib Do not use the standard system startup files or libraries when linking. -No startup files and only the libraries you specify will be passed to -the linker, options specifying linkage of the system libraries, such as -@code{-static-libgcc} or @code{-shared-libgcc}, will be ignored. +No startup files and only the libraries you specify are passed to +the linker, and options specifying linkage of the system libraries, such as +@code{-static-libgcc} or @code{-shared-libgcc}, are ignored. + The compiler may generate calls to @code{memcmp}, @code{memset}, @code{memcpy} and @code{memmove}. These entries are usually resolved by entries in @@ -9477,16 +9485,17 @@ In most cases, you need @file{libgcc.a} even when you want to avoid other standard libraries. In other words, when you specify @option{-nostdlib} or @option{-nodefaultlibs} you should usually specify @option{-lgcc} as well. This ensures that you have no unresolved references to internal GCC -library subroutines. (For example, @samp{__main}, used to ensure C++ -constructors will be called; @pxref{Collect2,,@code{collect2}, gccint, +library subroutines. +(An example of such an internal subroutine is @samp{__main}, used to ensure C++ +constructors are called; @pxref{Collect2,,@code{collect2}, gccint, GNU Compiler Collection (GCC) Internals}.) @item -pie @opindex pie Produce a position independent executable on targets that support it. For predictable results, you must also specify the same set of options -that were used to generate code (@option{-fpie}, @option{-fPIE}, -or model suboptions) when you specify this option. +used for compilation (@option{-fpie}, @option{-fPIE}, +or model suboptions) when you specify this linker option. @item -rdynamic @opindex rdynamic @@ -9509,9 +9518,9 @@ libraries. On other systems, this option has no effect. @opindex shared Produce a shared object which can then be linked with other objects to form an executable. Not all systems support this option. For predictable -results, you must also specify the same set of options that were used to -generate code (@option{-fpic}, @option{-fPIC}, or model suboptions) -when you specify this option.@footnote{On some systems, @samp{gcc -shared} +results, you must also specify the same set of options used for compilation +(@option{-fpic}, @option{-fPIC}, or model suboptions) when +you specify this linker option.@footnote{On some systems, @samp{gcc -shared} needs to build supplementary stub code for constructors to work. On multi-libbed systems, @samp{gcc -shared} must select the correct support libraries to link against. Failing to supply the correct flags may lead @@ -9539,11 +9548,11 @@ executable, because C++ and Java programs typically use exceptions, so this is the right thing to do. If, instead, you use the GCC driver to create shared libraries, you may -find that they will not always be linked with the shared @file{libgcc}. +find that they are not always linked with the shared @file{libgcc}. If GCC finds, at its configuration time, that you have a non-GNU linker or a GNU linker that does not support option @option{--eh-frame-hdr}, -it will link the shared version of @file{libgcc} into shared libraries -by default. Otherwise, it will take advantage of the linker and optimize +it links the shared version of @file{libgcc} into shared libraries +by default. Otherwise, it takes advantage of the linker and optimizes away the linking with the shared version of @file{libgcc}, linking with the static version of libgcc by default. This allows exceptions to propagate through such shared libraries, without incurring relocation @@ -9556,10 +9565,10 @@ for the languages used in the program, or using the option @file{libgcc}. @item -static-libstdc++ -When the @command{g++} program is used to link a C++ program, it will -normally automatically link against @option{libstdc++}. If +When the @command{g++} program is used to link a C++ program, it +normally automatically links against @option{libstdc++}. If @file{libstdc++} is available as a shared library, and the -@option{-static} option is not used, then this will link against the +@option{-static} option is not used, then this links against the shared version of @file{libstdc++}. That is normally fine. However, it is sometimes useful to freeze the version of @file{libstdc++} used by the program without going all the way to a fully static link. The @@ -9640,7 +9649,7 @@ order; the standard system directories come after. If a standard system include directory, or a directory specified with @option{-isystem}, is also specified with @option{-I}, the @option{-I} -option will be ignored. The directory will still be searched but as a +option is ignored. The directory is still searched but as a system directory at its normal position in the system include chain. This is to ensure that GCC's procedure to fix buggy system headers and the ordering for the @code{include_next} directive are not inadvertently changed. @@ -9677,14 +9686,14 @@ without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}). For each subprogram to be run, the compiler driver first tries the @option{-B} prefix, if any. If that name is not found, or if @option{-B} -was not specified, the driver tries two standard prefixes, +is not specified, the driver tries two standard prefixes, @file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc/}. If neither of those results in a file name that is found, the unmodified program name is searched for using the directories specified in your @env{PATH} environment variable. -The compiler will check to see if the path provided by the @option{-B} -refers to a directory, and if necessary it will add a directory +The compiler checks to see if the path provided by the @option{-B} +refers to a directory, and if necessary it adds a directory separator character at the end of the path. @option{-B} prefixes that effectively specify directory names also apply @@ -9705,7 +9714,7 @@ Variables}. As a special kludge, if the path provided by @option{-B} is @file{[dir/]stage@var{N}/}, where @var{N} is a number in the range 0 to -9, then it will be replaced by @file{[dir/]include}. This is to help +9, then it is replaced by @file{[dir/]include}. This is to help with boot-strapping the compiler. @item -specs=@var{file} @@ -9720,18 +9729,18 @@ are processed in order, from left to right. @item --sysroot=@var{dir} @opindex sysroot Use @var{dir} as the logical root directory for headers and libraries. -For example, if the compiler would normally search for headers in -@file{/usr/include} and libraries in @file{/usr/lib}, it will instead -search @file{@var{dir}/usr/include} and @file{@var{dir}/usr/lib}. +For example, if the compiler normally searches for headers in +@file{/usr/include} and libraries in @file{/usr/lib}, it instead +searches @file{@var{dir}/usr/include} and @file{@var{dir}/usr/lib}. If you use both this option and the @option{-isysroot} option, then -the @option{--sysroot} option will apply to libraries, but the -@option{-isysroot} option will apply to header files. +the @option{--sysroot} option applies to libraries, but the +@option{-isysroot} option applies to header files. The GNU linker (beginning with version 2.16) has the necessary support for this option. If your linker does not support this option, the -header file aspect of @option{--sysroot} will still work, but the -library aspect will not. +header file aspect of @option{--sysroot} still works, but the +library aspect does not. @item -I- @opindex I- @@ -9750,7 +9759,7 @@ In addition, the @option{-I-} option inhibits the use of the current directory (where the current input file came from) as the first search directory for @samp{#include "@var{file}"}. There is no way to override this effect of @option{-I-}. With @option{-I.} you can specify -searching the directory that was current when the compiler was +searching the directory that is current when the compiler is invoked. That is not exactly the same as what the preprocessor does by default, but it is often satisfactory. @@ -9807,18 +9816,18 @@ Rename the spec string @var{old_name} to @var{new_name}. This tells the compiler to create, override or delete the named spec string. All lines after this directive up to the next directive or blank line are considered to be the text for the spec string. If this -results in an empty string then the spec will be deleted. (Or, if the -spec did not exist, then nothing will happen.) Otherwise, if the spec -does not currently exist a new spec will be created. If the spec does -exist then its contents will be overridden by the text of this +results in an empty string then the spec is deleted. (Or, if the +spec did not exist, then nothing happens.) Otherwise, if the spec +does not currently exist a new spec is created. If the spec does +exist then its contents are overridden by the text of this directive, unless the first character of that text is the @samp{+} -character, in which case the text will be appended to the spec. +character, in which case the text is appended to the spec. @item [@var{suffix}]: Creates a new @samp{[@var{suffix}] spec} pair. All lines after this directive and up to the next directive or blank line are considered to make up the spec string for the indicated suffix. When the compiler encounters an -input file with the named suffix, it will processes the spec string in +input file with the named suffix, it processes the spec string in order to work out how to compile that file. For example: @smallexample @@ -9856,7 +9865,7 @@ This causes an error messages saying: @end table GCC already has an extensive list of suffixes built into it. -This directive will add an entry to the end of the list of suffixes, but +This directive adds an entry to the end of the list of suffixes, but since the list is searched from the end backwards, it is effectively possible to override earlier entries using this technique. @@ -9926,7 +9935,7 @@ the last period). @item %d Marks the argument containing or following the @samp{%d} as a -temporary file name, so that that file will be deleted if GCC exits +temporary file name, so that that file is deleted if GCC exits successfully. Unlike @samp{%g}, this contributes no text to the argument. @@ -9944,15 +9953,15 @@ without regard to any appended suffix (which was therefore treated just like ordinary text), making such attacks more likely to succeed. @item %u@var{suffix} -Like @samp{%g}, but generates a new temporary file name even if -@samp{%u@var{suffix}} was already seen. +Like @samp{%g}, but generates a new temporary file name +each time it appears instead of once per compilation. @item %U@var{suffix} Substitutes the last file name generated with @samp{%u@var{suffix}}, generating a new one if there is no such last file name. In the absence of any @samp{%u@var{suffix}}, this is just like @samp{%g@var{suffix}}, except they don't share the same suffix @emph{space}, so @samp{%g.s @dots{} %U.s @dots{} %g.s @dots{} %U.s} -would involve the generation of two distinct file names, one +involves the generation of two distinct file names, one for each @samp{%g.s} and another for each @samp{%U.s}. Previously, @samp{%U} was simply substituted with a file name chosen for the previous @samp{%u}, without regard to any appended suffix. @@ -9982,7 +9991,7 @@ terminated by the next space or %. @item %w Marks the argument containing or following the @samp{%w} as the designated output file of this compilation. This puts the argument -into the sequence of arguments that @samp{%o} will substitute later. +into the sequence of arguments that @samp{%o} substitutes. @item %o Substitutes the names of all the output files, with spaces @@ -9990,8 +9999,8 @@ automatically placed around them. You should write spaces around the @samp{%o} as well or the results are undefined. @samp{%o} is for use in the specs for running the linker. Input files whose names have no recognized suffix are not compiled -at all, but they are included among the output files, so they will -be linked. +at all, but they are included among the output files, so they are +linked. @item %O Substitutes the suffix for object files. Note that this is @@ -9999,7 +10008,7 @@ handled specially when it immediately follows @samp{%g, %u, or %U}, because of the need for those to form complete file names. The handling is such that @samp{%O} is treated exactly as if it had already been substituted, except that @samp{%g, %u, and %U} do not currently -support additional @var{suffix} characters following @samp{%O} as they would +support additional @var{suffix} characters following @samp{%O} as they do following, for example, @samp{.o}. @item %p @@ -10063,30 +10072,30 @@ needed. @item %l Process the @code{link} spec. This is the spec for computing the -command line passed to the linker. Typically it will make use of the +command line passed to the linker. Typically it makes use of the @samp{%L %G %S %D and %E} sequences. @item %D Dump out a @option{-L} option for each directory that GCC believes might contain startup files. If the target supports multilibs then the -current multilib directory will be prepended to each of these paths. +current multilib directory is prepended to each of these paths. @item %L Process the @code{lib} spec. This is a spec string for deciding which -libraries should be included on the command line to the linker. +libraries are included on the command line to the linker. @item %G Process the @code{libgcc} spec. This is a spec string for deciding -which GCC support library should be included on the command line to the linker. +which GCC support library is included on the command line to the linker. @item %S Process the @code{startfile} spec. This is a spec for deciding which -object files should be the first ones passed to the linker. Typically +object files are the first ones passed to the linker. Typically this might be a file named @file{crt0.o}. @item %E Process the @code{endfile} spec. This is a spec string that specifies -the last object files that will be passed to the linker. +the last object files that are passed to the linker. @item %C Process the @code{cpp} spec. This is used to construct the arguments @@ -10108,8 +10117,8 @@ a single space. @item %<@code{S} Remove all occurrences of @code{-S} from the command line. Note---this command is position dependent. @samp{%} commands in the spec string -before this one will see @code{-S}, @samp{%} commands in the spec string -after this one will not. +before this one see @code{-S}, @samp{%} commands in the spec string +after this one do not. @item %:@var{function}(@var{args}) Call the named function @var{function}, passing it @var{args}. @@ -10204,12 +10213,12 @@ in the @option{--target-help} output. @end table @item %@{@code{S}@} -Substitutes the @code{-S} switch, if that switch was given to GCC@. -If that switch was not specified, this substitutes nothing. Note that +Substitutes the @code{-S} switch, if that switch is given to GCC@. +If that switch is not specified, this substitutes nothing. Note that the leading dash is omitted when specifying this option, and it is automatically inserted if the substitution is performed. Thus the spec -string @samp{%@{foo@}} would match the command-line option @option{-foo} -and would output the command-line option @option{-foo}. +string @samp{%@{foo@}} matches the command-line option @option{-foo} +and outputs the command-line option @option{-foo}. @item %W@{@code{S}@} Like %@{@code{S}@} but mark last argument supplied within as a file to be @@ -10220,8 +10229,8 @@ Substitutes all the switches specified to GCC whose names start with @code{-S}, but which also take an argument. This is used for switches like @option{-o}, @option{-D}, @option{-I}, etc. GCC considers @option{-o foo} as being -one switch whose names starts with @samp{o}. %@{o*@} would substitute this -text, including the space. Thus two arguments would be generated. +one switch whose name starts with @samp{o}. %@{o*@} substitutes this +text, including the space. Thus two arguments are generated. @item %@{@code{S}*&@code{T}*@} Like %@{@code{S}*@}, but preserve order of @code{S} and @code{T} options @@ -10230,18 +10239,18 @@ There can be any number of ampersand-separated variables; for each the wild card is optional. Useful for CPP as @samp{%@{D*&U*&A*@}}. @item %@{@code{S}:@code{X}@} -Substitutes @code{X}, if the @option{-S} switch was given to GCC@. +Substitutes @code{X}, if the @option{-S} switch is given to GCC@. @item %@{!@code{S}:@code{X}@} -Substitutes @code{X}, if the @option{-S} switch was @emph{not} given to GCC@. +Substitutes @code{X}, if the @option{-S} switch is @emph{not} given to GCC@. @item %@{@code{S}*:@code{X}@} Substitutes @code{X} if one or more switches whose names start with @code{-S} are specified to GCC@. Normally @code{X} is substituted only once, no matter how many such switches appeared. However, if @code{%*} -appears somewhere in @code{X}, then @code{X} will be substituted once +appears somewhere in @code{X}, then @code{X} is substituted once for each matching switch, with the @code{%*} replaced by the part of -that switch that matched the @code{*}. +that switch matching the @code{*}. @item %@{.@code{S}:@code{X}@} Substitutes @code{X}, if processing a file with suffix @code{S}. @@ -10256,7 +10265,7 @@ Substitutes @code{X}, if processing a file for language @code{S}. Substitutes @code{X}, if not processing a file for language @code{S}. @item %@{@code{S}|@code{P}:@code{X}@} -Substitutes @code{X} if either @code{-S} or @code{-P} was given to +Substitutes @code{X} if either @code{-S} or @code{-P} is given to GCC@. This may be combined with @samp{!}, @samp{.}, @samp{,}, and @code{*} sequences as well, although they have a stronger binding than the @samp{|}. If @code{%*} appears in @code{X}, all of the @@ -10269,7 +10278,8 @@ For example, a spec string like this: %@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@} @end smallexample -will output the following command-line options from the following input +@noindent +outputs the following command-line options from the following input command-line options: @smallexample @@ -10281,7 +10291,7 @@ jim.d -bar -boggle @item %@{S:X; T:Y; :D@} -If @code{S} was given to GCC, substitutes @code{X}; else if @code{T} was +If @code{S} is given to GCC, substitutes @code{X}; else if @code{T} is given to GCC, substitutes @code{Y}; else substitutes @code{D}. There can be as many clauses as you need. This may be combined with @code{.}, @code{,}, @code{!}, @code{|}, and @code{*} as needed. @@ -10458,7 +10468,7 @@ can be used by leaf functions without stack allocation. Values other than @samp{8} or @samp{16} are untested and unlikely to work. Note also that this option changes the ABI, compiling a program with a different stack offset than the libraries have been compiled with -will generally not work. +generally does not work. This option can be useful if you want to evaluate if a different stack offset would give you better code, but to actually use a different stack offset to build working programs, it is recommended to configure the @@ -10546,13 +10556,13 @@ Change the preferred SIMD mode to SImode. The default is The maximum alignment for SIMD vector mode types. @var{num} may be 4 or 8. The default is 8. Note that this is an ABI change, even though many library function -interfaces will be unaffected, if they don't use SIMD vector modes -in places where they affect size and/or alignment of relevant types. +interfaces are unaffected if they don't use SIMD vector modes +in places that affect size and/or alignment of relevant types. @item -msplit-vecmove-early @opindex msplit-vecmove-early Split vector moves into single word moves before reload. In theory this -could give better register allocation, but so far the reverse seems to be +can give better register allocation, but so far the reverse seems to be generally the case. @item -m1reg-@var{reg} @@ -10584,7 +10594,7 @@ Generate code for the specified ABI@. Permissible values are: @samp{apcs-gnu}, Generate a stack frame that is compliant with the ARM Procedure Call Standard for all functions, even if this is not strictly necessary for correct execution of the code. Specifying @option{-fomit-frame-pointer} -with this option will cause the stack frames not to be generated for +with this option causes the stack frames not to be generated for leaf functions. The default is @option{-mno-apcs-frame}. @item -mapcs @@ -10598,7 +10608,7 @@ This is a synonym for @option{-mapcs-frame}. Generate code to check the amount of stack space available upon entry to every function (that actually uses some stack space). If there is insufficient space available then either the function -@samp{__rt_stkovf_split_small} or @samp{__rt_stkovf_split_big} will be +@samp{__rt_stkovf_split_small} or @samp{__rt_stkovf_split_big} is called, depending upon the amount of stack space required. The runtime system is required to provide these functions. The default is @option{-mno-apcs-stack-check}, since this produces smaller code. @@ -10633,10 +10643,10 @@ configurations this option is meaningless. @opindex mno-sched-prolog Prevent the reordering of instructions in the function prologue, or the merging of those instruction with the instructions in the function's -body. This means that all functions will start with a recognizable set +body. This means that all functions start with a recognizable set of instructions (or in fact one of a choice from a small set of different function prologues), and this information can be used to -locate the start if functions inside an executable piece of code. The +locate the start of functions inside an executable piece of code. The default is @option{-msched-prolog}. @item -mfloat-abi=@var{name} @@ -10722,8 +10732,8 @@ This option is very similar to the @option{-mcpu=} option, except that instead of specifying the actual target processor type, and hence restricting which instructions can be used, it specifies that GCC should tune the performance of the code as if the target were of the type -specified in this option, but still choosing the instructions that it -will generate based on the CPU specified by a @option{-mcpu=} option. +specified in this option, but still choosing the instructions it +generates based on the CPU specified by a @option{-mcpu=} option. For some ARM implementations better performance can be obtained by using this option. @@ -10778,7 +10788,7 @@ floating-point values. If the selected floating-point hardware includes the NEON extension (e.g. @option{-mfpu}=@samp{neon}), note that floating-point -operations will not be used by GCC's auto-vectorization pass unless +operations are not generated by GCC's auto-vectorization pass unless @option{-funsafe-math-optimizations} is also specified. This is because NEON hardware does not fully implement the IEEE 754 standard for floating-point arithmetic (in particular denormal values are treated as @@ -10793,7 +10803,7 @@ defined. @xref{Half-Precision}, for more information. @item -mstructure-size-boundary=@var{n} @opindex mstructure-size-boundary -The size of all structures and unions will be rounded up to a multiple +The sizes of all structures and unions are rounded up to a multiple of the number of bits set by this option. Permissible values are 8, 32 and 64. The default value varies for different toolchains. For the COFF targeted toolchain the default value is 8. A value of 64 is only allowed @@ -10808,7 +10818,7 @@ information using structures or unions. @item -mabort-on-noreturn @opindex mabort-on-noreturn Generate a call to the function @code{abort} at the end of a -@code{noreturn} function. It will be executed if the function tries to +@code{noreturn} function. It is executed if the function tries to return. @item -mlong-calls @@ -10818,22 +10828,22 @@ return. Tells the compiler to perform function calls by first loading the address of the function into a register and then performing a subroutine call on this register. This switch is needed if the target function -will lie outside of the 64 megabyte addressing range of the offset based +lies outside of the 64-megabyte addressing range of the offset-based version of subroutine call instruction. -Even if this switch is enabled, not all function calls will be turned +Even if this switch is enabled, not all function calls are turned into long calls. The heuristic is that static functions, functions that have the @samp{short-call} attribute, functions that are inside -the scope of a @samp{#pragma no_long_calls} directive and functions whose +the scope of a @samp{#pragma no_long_calls} directive, and functions whose definitions have already been compiled within the current compilation -unit, will not be turned into long calls. The exception to this rule is +unit are not turned into long calls. The exceptions to this rule are that weak function definitions, functions with the @samp{long-call} attribute or the @samp{section} attribute, and functions that are within -the scope of a @samp{#pragma long_calls} directive, will always be +the scope of a @samp{#pragma long_calls} directive are always turned into long calls. This feature is not enabled by default. Specifying -@option{-mno-long-calls} will restore the default behavior, as will +@option{-mno-long-calls} restores the default behavior, as does placing the function calls within the scope of a @samp{#pragma long_calls_off} directive. Note these switches have no effect on how the compiler generates code to handle function calls via function @@ -11088,8 +11098,8 @@ integers. The default branch cost is 0. @item -mcall-prologues @opindex mcall-prologues -Functions prologues/epilogues expanded as call to appropriate -subroutines. Code size will be smaller. +Functions prologues/epilogues are expanded as calls to appropriate +subroutines. Code size is smaller. @item -mint8 @opindex mint8 @@ -11102,7 +11112,7 @@ size. @item -mno-interrupts @opindex mno-interrupts Generated code is not compatible with hardware interrupts. -Code size will be smaller. +Code size is smaller. @item -mrelax @opindex mrelax @@ -11113,7 +11123,7 @@ linker command line when the linker is called. Jump relaxing is performed by the linker because jump offsets are not known before code is located. Therefore, the assembler code generated by the -compiler will be the same, but the instructions in the executable may +compiler is the same, but the instructions in the executable may differ from instructions in the assembler code. @item -mshort-calls @@ -11126,14 +11136,14 @@ See also the @code{-mrelax} command line option. @item -mstrict-X @opindex mstrict-X Use address register @code{X} in a way proposed by the hardware. This means -that @code{X} will only be used in indirect, post-increment or +that @code{X} is only used in indirect, post-increment or pre-decrement addressing. Without this option, the @code{X} register may be used in the same way as @code{Y} or @code{Z} which then is emulated by additional instructions. For example, loading a value with @code{X+const} addressing with a -small non-negative @code{const < 64} to a register @var{Rn} will be +small non-negative @code{const < 64} to a register @var{Rn} is performed as @example @@ -11179,9 +11189,9 @@ saved/restored in function or interrupt service routine prologue/epilogue. @item -For indirect calls to functions and computed goto, the linker will -generate @emph{stubs}. Stubs are jump pads sometimes also called -@emph{trampolines}. Thus, the indirect call/jump will jump to such a stub. +For indirect calls to functions and computed goto, the linker +generates @emph{stubs}. Stubs are jump pads sometimes also called +@emph{trampolines}. Thus, the indirect call/jump jumps to such a stub. The stub contains a direct jump to the desired address. @item @@ -11220,7 +11230,7 @@ init3_set_eind (void) The @code{__trampolines_start} symbol is defined in the linker script. @item -Stubs will be generated automatically by the linker if +Stubs are generated automatically by the linker if the following two conditions are met: @itemize @minus @@ -11235,7 +11245,7 @@ LDI r25, hi8(gs(@var{func})) @end itemize @item -The compiler will emit such @code{gs} modifiers for code labels in the +The compiler emits such @code{gs} modifiers for code labels in the following situations: @itemize @minus @item Taking address of a function or code label. @@ -11297,17 +11307,17 @@ registers with zero. @item If a @ref{AVR Named Address Spaces,named address space} other than -generic or @code{__flash} is used, then @code{RAMPZ} will be set +generic or @code{__flash} is used, then @code{RAMPZ} is set as needed before the operation. @item If the device supports RAM larger than 64@tie{KiB} and the compiler needs to change @code{RAMPZ} to accomplish an operation, @code{RAMPZ} -will be reset to zero after the operation. +is reset to zero after the operation. @item If the device comes with a specific @code{RAMP} register, the ISR -prologue/epilogue will save/restore that SFR and initialize it with +prologue/epilogue saves/restores that SFR and initializes it with zero in case the ISR code might (implicitly) use it. @item @@ -11332,7 +11342,7 @@ For even more AVR-specific built-in macros see @item __AVR_@var{Device}__ Setting @code{-mmcu=@var{device}} defines this built-in macro which reflects -the device's name. For example, @code{-mmcu=atmega8} will define the +the device's name. For example, @code{-mmcu=atmega8} defines the built-in macro @code{__AVR_ATmega8__}, @code{-mmcu=attiny261a} defines @code{__AVR_ATtiny261A__}, etc. @@ -11426,9 +11436,9 @@ can be one of @samp{bf512}, @samp{bf514}, @samp{bf516}, @samp{bf518}, @samp{bf561}, @samp{bf592}. The optional @var{sirevision} specifies the silicon revision of the target Blackfin processor. Any workarounds available for the targeted silicon revision -will be enabled. If @var{sirevision} is @samp{none}, no workarounds are enabled. +are enabled. If @var{sirevision} is @samp{none}, no workarounds are enabled. If @var{sirevision} is @samp{any}, all workarounds for the targeted processor -will be enabled. The @code{__SILICON_REVISION__} macro is defined to two +are enabled. The @code{__SILICON_REVISION__} macro is defined to two hexadecimal digits representing the major and minor numbers in the silicon revision. If @var{sirevision} is @samp{none}, the @code{__SILICON_REVISION__} is not defined. If @var{sirevision} is @samp{any}, the @@ -11461,7 +11471,7 @@ which might make debugging harder. @item -mspecld-anomaly @opindex mspecld-anomaly -When enabled, the compiler will ensure that the generated code does not +When enabled, the compiler ensures that the generated code does not contain speculative loads after jump instructions. If this option is used, @code{__WORKAROUND_SPECULATIVE_LOADS} is defined. @@ -11471,7 +11481,7 @@ Don't generate extra code to prevent speculative loads from occurring. @item -mcsync-anomaly @opindex mcsync-anomaly -When enabled, the compiler will ensure that the generated code does not +When enabled, the compiler ensures that the generated code does not contain CSYNC or SSYNC instructions too soon after conditional branches. If this option is used, @code{__WORKAROUND_SPECULATIVE_SYNCS} is defined. @@ -11516,14 +11526,14 @@ and calls. @item -mno-leaf-id-shared-library @opindex mno-leaf-id-shared-library Do not assume that the code being compiled won't link against any ID shared -libraries. Slower code will be generated for jump and call insns. +libraries. Slower code is generated for jump and call insns. @item -mshared-library-id=n @opindex mshared-library-id -Specified the identification number of the ID based shared library being -compiled. Specifying a value of 0 will generate more compact code, specifying -other values will force the allocation of that number to the current -library but is no more space or time efficient than omitting this option. +Specifies the identification number of the ID-based shared library being +compiled. Specifying a value of 0 generates more compact code; specifying +other values forces the allocation of that number to the current +library but is no more space- or time-efficient than omitting this option. @item -msep-data @opindex msep-data @@ -11548,7 +11558,7 @@ lies outside of the 24-bit addressing range of the offset-based version of subroutine call instruction. This feature is not enabled by default. Specifying -@option{-mno-long-calls} will restore the default behavior. Note these +@option{-mno-long-calls} restores the default behavior. Note these switches have no effect on how the compiler generates code to handle function calls via function pointers. @@ -11566,7 +11576,7 @@ not known to bind locally. It has no effect without @option{-mfdpic}. @item -mmulticore @opindex mmulticore Build standalone application for multicore Blackfin processor. Proper -start files and link scripts will be used to support multicore. +start files and link scripts are used to support multicore. This option defines @code{__BFIN_MULTICORE}. It can only be used with @option{-mcpu=bf561@r{[}-@var{sirevision}@r{]}}. It can be used with @option{-mcorea} or @option{-mcoreb}. If it's used without @@ -11581,14 +11591,14 @@ model is used. @opindex mcorea Build standalone application for Core A of BF561 when using one application per core programming model. Proper start files -and link scripts will be used to support Core A. This option +and link scripts are used to support Core A. This option defines @code{__BFIN_COREA}. It must be used with @option{-mmulticore}. @item -mcoreb @opindex mcoreb Build standalone application for Core B of BF561 when using one application per core programming model. Proper start files -and link scripts will be used to support Core B. This option +and link scripts are used to support Core B. This option defines @code{__BFIN_COREB}. When this option is used, coreb_main should be used instead of main. It must be used with @option{-mmulticore}. @@ -11596,7 +11606,7 @@ should be used instead of main. It must be used with @item -msdram @opindex msdram Build standalone application for SDRAM. Proper start files and -link scripts will be used to put the application into SDRAM. +link scripts are used to put the application into SDRAM. Loader should initialize SDRAM before loading the application into SDRAM. This option defines @code{__BFIN_SDRAM}. @@ -11830,8 +11840,8 @@ CR16C architecture does not support the far data model. These options are defined for all architectures running the Darwin operating system. -FSF GCC on Darwin does not create ``fat'' object files; it will create -an object file for the single architecture that it was built to +FSF GCC on Darwin does not create ``fat'' object files; it creates +an object file for the single architecture that GCC was built to target. Apple's GCC on Darwin does create ``fat'' files if multiple @option{-arch} options are used; it does so by running the compiler or linker multiple times and joining the results together with @@ -11843,14 +11853,14 @@ that GCC is targetting, like @option{-mcpu} or @option{-march}. The @option{-force_cpusubtype_ALL} option can be used to override this. The Darwin tools vary in their behavior when presented with an ISA -mismatch. The assembler, @file{as}, will only permit instructions to +mismatch. The assembler, @file{as}, only permits instructions to be used that are valid for the subtype of the file it is generating, so you cannot put 64-bit instructions in a @samp{ppc750} object file. -The linker for shared libraries, @file{/usr/bin/libtool}, will fail -and print an error if asked to create a shared library with a less +The linker for shared libraries, @file{/usr/bin/libtool}, fails +and prints an error if asked to create a shared library with a less restrictive subtype than its input files (for instance, trying to put a @samp{ppc970} object file in a @samp{ppc7400} library). The linker -for executables, @command{ld}, will quietly give the executable the most +for executables, @command{ld}, quietly gives the executable the most restrictive subtype of any of its input files. @table @gcctabopt @@ -11873,8 +11883,8 @@ Includes of subframework headers can only appear in a header of a framework that contains the subframework, or in a sibling subframework header. Two subframeworks are siblings if they occur in the same framework. A subframework should not have the same name as a -framework, a warning will be issued if this is violated. Currently a -subframework cannot have subframeworks, in the future, the mechanism +framework; a warning is issued if this is violated. Currently a +subframework cannot have subframeworks; in the future, the mechanism may be extended to support this. The standard frameworks can be found in @file{/System/Library/Frameworks} and @file{/Library/Frameworks}. An example include looks like @@ -11966,12 +11976,12 @@ See man ld(1) for more information. @item -bundle_loader @var{executable} @opindex bundle_loader -This option specifies the @var{executable} that will be loading the build +This option specifies the @var{executable} that will load the build output file being linked. See man ld(1) for more information. @item -dynamiclib @opindex dynamiclib -When passed this option, GCC will produce a dynamic library instead of +When passed this option, GCC produces a dynamic library instead of an executable when linking, using the Darwin @file{libtool} command. @item -force_cpusubtype_ALL @@ -12116,10 +12126,10 @@ These @samp{-m} options are defined for the DEC Alpha implementations: @opindex msoft-float Use (do not use) the hardware floating-point instructions for floating-point operations. When @option{-msoft-float} is specified, -functions in @file{libgcc.a} will be used to perform floating-point +functions in @file{libgcc.a} are used to perform floating-point operations. Unless they are replaced by routines that emulate the floating-point operations, or compiled in such a way as to call such -emulations routines, these routines will issue floating-point +emulations routines, these routines issue floating-point operations. If you are compiling for an Alpha without floating-point operations, you must ensure that the library is built so as not to call them. @@ -12257,13 +12267,13 @@ generated assembly file. @opindex mbuild-constants Normally GCC examines a 32- or 64-bit integer constant to see if it can construct it from smaller constants in two or three -instructions. If it cannot, it will output the constant as a literal and -generate code to load it from the data segment at run time. +instructions. If it cannot, it outputs the constant as a literal and +generates code to load it from the data segment at run time. Use this option to require GCC to construct @emph{all} integer constants using code, even if it takes more instructions (the maximum is six). -You would typically use this option to build a shared library dynamic +You typically use this option to build a shared library dynamic loader. Itself a shared library, it must relocate itself in memory before it can find the variables and constants in its own data segment. @@ -12286,7 +12296,7 @@ before it can find the variables and constants in its own data segment. Indicate whether GCC should generate code to use the optional BWX, CIX, FIX and MAX instruction sets. The default is to use the instruction sets supported by the CPU type specified via @option{-mcpu=} option or that -of the CPU on which GCC was built if none was specified. +of the CPU on which GCC was built if none is specified. @item -mfloat-vax @itemx -mfloat-ieee @@ -12345,9 +12355,9 @@ The default is @option{-mlarge-text}. Set the instruction set and instruction scheduling parameters for machine type @var{cpu_type}. You can specify either the @samp{EV} style name or the corresponding chip number. GCC supports scheduling -parameters for the EV4, EV5 and EV6 family of processors and will -choose the default values for the instruction set from the processor -you specify. If you do not specify a processor type, GCC will default +parameters for the EV4, EV5 and EV6 family of processors and +chooses the default values for the instruction set from the processor +you specify. If you do not specify a processor type, GCC defaults to the processor on which the compiler was built. Supported values for @var{cpu_type} are @@ -12431,7 +12441,7 @@ These options are defined specifically for the FR30 port. @item -msmall-model @opindex msmall-model Use the small address space model. This can produce smaller code, but -it does assume that all symbolic values and addresses will fit into a +it does assume that all symbolic values and addresses fit into a 20-bit range. @item -mno-lsim @@ -12867,7 +12877,7 @@ Generate code for the specified architecture. The choices for 1.1, and @samp{2.0} for PA 2.0 processors. Refer to @file{/usr/lib/sched.models} on an HP-UX system to determine the proper architecture option for your machine. Code compiled for lower numbered -architectures will run on higher numbered architectures, but not the +architectures runs on higher numbered architectures, but not the other way around. @item -mpa-risc-1-0 @@ -12914,7 +12924,7 @@ Such code is suitable for level 0 PA systems and kernels. Generate code that assumes calls never cross space boundaries. This allows GCC to emit code that performs faster indirect calls. -This option will not work in the presence of shared libraries or nested +This option does not work in the presence of shared libraries or nested functions. @item -mfixed-range=@var{register-range} @@ -13021,7 +13031,7 @@ Distances are measured from the beginning of functions when using the and @option{-mno-portable-runtime} options together under HP-UX with the SOM linker. -It is normally not desirable to use this option as it will degrade +It is normally not desirable to use this option as it degrades performance. However, it may be useful in large applications, particularly when partial linking is used to build the application. @@ -14408,8 +14418,8 @@ runtime library for whatever I/O functions are needed. @item -memregs=@var{number} @opindex memregs= -Specifies the number of memory-based pseudo-registers GCC will use -during code generation. These pseudo-registers will be used like real +Specifies the number of memory-based pseudo-registers GCC uses +during code generation. These pseudo-registers are used like real registers, so there is a tradeoff between GCC's ability to fit the code into available registers, and the performance penalty of using memory instead of registers. Note that all modules in a program must @@ -14451,21 +14461,21 @@ The addressability of a particular object can be set with the @item -mmodel=medium @opindex mmodel=medium Assume objects may be anywhere in the 32-bit address space (the compiler -will generate @code{seth/add3} instructions to load their addresses), and +generates @code{seth/add3} instructions to load their addresses), and assume all subroutines are reachable with the @code{bl} instruction. @item -mmodel=large @opindex mmodel=large Assume objects may be anywhere in the 32-bit address space (the compiler -will generate @code{seth/add3} instructions to load their addresses), and +generates @code{seth/add3} instructions to load their addresses), and assume subroutines may not be reachable with the @code{bl} instruction -(the compiler will generate the much slower @code{seth/add3/jl} +(the compiler generates the much slower @code{seth/add3/jl} instruction sequence). @item -msdata=none @opindex msdata=none -Disable use of the small data area. Variables will be put into -one of @samp{.data}, @samp{bss}, or @samp{.rodata} (unless the +Disable use of the small data area. Variables are put into +one of @samp{.data}, @samp{.bss}, or @samp{.rodata} (unless the @code{section} attribute has been specified). This is the default. @@ -14494,7 +14504,7 @@ for this option to have any effect. All modules should be compiled with the same @option{-G @var{num}} value. Compiling with different values of @var{num} may or may not work; if it -doesn't the linker will give an error message---incorrect code will not be +doesn't the linker gives an error message---incorrect code is not generated. @item -mdebug @@ -14517,9 +14527,8 @@ or 2. @item -mbranch-cost=@var{number} @opindex mbranch-cost=@var{number} -@var{number} can only be 1 or 2. If it is 1 then branches will be -preferred over conditional code, if it is 2, then the opposite will -apply. +@var{number} can only be 1 or 2. If it is 1 then branches are +preferred over conditional code, if it is 2, then the opposite applies. @item -mflush-trap=@var{number} @opindex mflush-trap=@var{number} @@ -14534,7 +14543,7 @@ Specifies that the cache cannot be flushed by using a trap. @opindex mflush-func=@var{name} Specifies the name of the operating system function to call to flush the cache. The default is @emph{_flush_cache}, but a function call -will only be used if a trap is not available. +is only used if a trap is not available. @item -mno-flush-func @opindex mno-flush-func @@ -14822,10 +14831,10 @@ compiled with the Unix compiler. Also, you must provide function prototypes for all functions that take variable numbers of arguments (including @code{printf}); -otherwise incorrect code will be generated for calls to those +otherwise incorrect code is generated for calls to those functions. -In addition, seriously incorrect code will result if you call a +In addition, seriously incorrect code results if you call a function with too many arguments. (Normally, extra arguments are harmlessly ignored.) @@ -14847,8 +14856,8 @@ boundary (@option{-malign-int}) or a 16-bit boundary (@option{-mno-align-int}). Aligning variables on 32-bit boundaries produces code that runs somewhat faster on processors with 32-bit busses at the expense of more memory. -@strong{Warning:} if you use the @option{-malign-int} switch, GCC will -align structures containing the above types differently than +@strong{Warning:} if you use the @option{-malign-int} switch, GCC +aligns structures containing the above types differently than most published application binary interface specifications for the m68k. @item -mpcrel @@ -14863,7 +14872,7 @@ not presently supported with @option{-mpcrel}, though this could be supported fo @itemx -mstrict-align @opindex mno-strict-align @opindex mstrict-align -Do not (do) assume that unaligned memory references will be handled by +Do not (do) assume that unaligned memory references are handled by the system. @item -msep-data @@ -14886,10 +14895,10 @@ Generate code that doesn't assume ID based shared libraries are being used. This is the default. @item -mshared-library-id=n -Specified the identification number of the ID based shared library being -compiled. Specifying a value of 0 will generate more compact code, specifying -other values will force the allocation of that number to the current -library but is no more space or time efficient than omitting this option. +Specifies the identification number of the ID-based shared library being +compiled. Specifying a value of 0 generates more compact code; specifying +other values forces the allocation of that number to the current +library, but is no more space- or time-efficient than omitting this option. @item -mxgot @itemx -mno-xgot @@ -15029,7 +15038,7 @@ registers. @item -mbased=@var{n} @opindex mbased= -Variables of size @var{n} bytes or smaller will be placed in the +Variables of size @var{n} bytes or smaller are placed in the @code{.based} section by default. Based variables use the @code{$tp} register as a base register, and there is a 128-byte limit to the @code{.based} section. @@ -15042,7 +15051,7 @@ test-and-set (@code{tas}). @item -mc=@var{name} @opindex mc= -Selects which section constant data will be placed in. @var{name} may +Selects which section constant data is placed in. @var{name} may be @code{tiny}, @code{near}, or @code{far}. @item -mclip @@ -15160,7 +15169,7 @@ this option, functions default to the @code{.near} section. @item -mtiny=@var{n} @opindex mtiny= -Variables that are @var{n} bytes or smaller will be allocated to the +Variables that are @var{n} bytes or smaller are allocated to the @code{.tiny} section. These variables use the @code{$gp} base register. The default for this option is 4, but note that there's a 65536-byte limit to the @code{.tiny} section. @@ -15282,7 +15291,7 @@ configurations. @item -march=@var{arch} @opindex march -Generate code that will run on @var{arch}, which can be the name of a +Generate code that runs on @var{arch}, which can be the name of a generic MIPS ISA, or the name of a particular processor. The ISA names are: @samp{mips1}, @samp{mips2}, @samp{mips3}, @samp{mips4}, @@ -15336,11 +15345,11 @@ GCC defines two macros based on the value of this option. The first is @samp{_MIPS_ARCH}, which gives the name of target architecture, as a string. The second has the form @samp{_MIPS_ARCH_@var{foo}}, where @var{foo} is the capitalized value of @samp{_MIPS_ARCH}@. -For example, @option{-march=r2000} will set @samp{_MIPS_ARCH} -to @samp{"r2000"} and define the macro @samp{_MIPS_ARCH_R2000}. +For example, @option{-march=r2000} sets @samp{_MIPS_ARCH} +to @samp{"r2000"} and defines the macro @samp{_MIPS_ARCH_R2000}. Note that the @samp{_MIPS_ARCH} macro uses the processor names given -above. In other words, it will have the full prefix and will not +above. In other words, it has the full prefix and does not abbreviate @samp{000} as @samp{k}. In the case of @samp{from-abi}, the macro names the resolved architecture (either @samp{"mips1"} or @samp{"mips3"}). It names the default architecture when no @@ -15353,10 +15362,10 @@ the way instructions are scheduled, and the perceived cost of arithmetic operations. The list of @var{arch} values is the same as for @option{-march}. -When this option is not used, GCC will optimize for the processor +When this option is not used, GCC optimizes for the processor specified by @option{-march}. By using @option{-march} and -@option{-mtune} together, it is possible to generate code that will -run on a family of processors, but optimize the code for one +@option{-mtune} together, it is possible to generate code that +runs on a family of processors, but optimize the code for one particular member of that family. @option{-mtune} defines the macros @samp{_MIPS_TUNE} and @@ -15400,7 +15409,7 @@ Equivalent to @option{-march=mips64r2}. @opindex mips16 @opindex mno-mips16 Generate (do not generate) MIPS16 code. If GCC is targetting a -MIPS32 or MIPS64 architecture, it will make use of the MIPS16e ASE@. +MIPS32 or MIPS64 architecture, it makes use of the MIPS16e ASE@. MIPS16 code generation can also be controlled on a per-function basis by means of @code{mips16} and @code{nomips16} attributes. @@ -15480,7 +15489,7 @@ functions. This mode is selected by @option{-mno-shared}. @option{-mno-shared} depends on binutils 2.16 or higher and generates objects that can only be linked by the GNU linker. However, the option does not affect the ABI of the final executable; it only affects the ABI -of relocatable objects. Using @option{-mno-shared} will generally make +of relocatable objects. Using @option{-mno-shared} generally makes executables both smaller and quicker. @option{-mshared} is the default. @@ -15506,8 +15515,8 @@ Lift (do not lift) the usual restrictions on the size of the global offset table. GCC normally uses a single instruction to load values from the GOT@. -While this is relatively efficient, it will only work if the GOT -is smaller than about 64k. Anything larger will cause the linker +While this is relatively efficient, it only works if the GOT +is smaller than about 64k. Anything larger causes the linker to report an error such as: @cindex relocation truncated to fit (MIPS) @@ -15516,8 +15525,8 @@ relocation truncated to fit: R_MIPS_GOT16 foobar @end smallexample If this happens, you should recompile your code with @option{-mxgot}. -It should then work with very large GOTs, although it will also be -less efficient, since it will take three instructions to fetch the +This works with very large GOTs, although the code is also +less efficient, since it takes three instructions to fetch the value of a global symbol. Note that some linkers can create multiple GOTs. If you have such a @@ -15568,7 +15577,7 @@ operations. This is the default. @opindex mno-llsc Use (do not use) @samp{ll}, @samp{sc}, and @samp{sync} instructions to implement atomic memory built-in functions. When neither option is -specified, GCC will use the instructions if the target architecture +specified, GCC uses the instructions if the target architecture supports them. @option{-mllsc} is useful if the runtime environment can emulate the @@ -15682,8 +15691,8 @@ more room for the main program. @itemx -mno-extern-sdata @opindex mextern-sdata @opindex mno-extern-sdata -Assume (do not assume) that externally-defined data will be in -a small data section if that data is within the @option{-G} limit. +Assume (do not assume) that externally-defined data is in +a small data section if the size of that data is within the @option{-G} limit. @option{-mextern-sdata} is the default for all configurations. If you compile a module @var{Mod} with @option{-mextern-sdata} @option{-G @@ -15715,8 +15724,8 @@ configurations. @option{-mno-gpopt} is useful for cases where the @code{$gp} register might not hold the value of @code{_gp}. For example, if the code is part of a library that might be used in a boot monitor, programs that -call boot monitor routines will pass an unknown value in @code{$gp}. -(In such situations, the boot monitor itself would usually be compiled +call boot monitor routines pass an unknown value in @code{$gp}. +(In such situations, the boot monitor itself is usually compiled with @option{-G0}.) @option{-mno-gpopt} implies @option{-mno-local-sdata} and @@ -15924,7 +15933,7 @@ instructions. These errata are handled by the assembler, not by GCC itself. @opindex mfix-vr4130 Work around the VR4130 @code{mflo}/@code{mfhi} errata. The workarounds are implemented by the assembler rather than by GCC, -although GCC will avoid using @code{mflo} and @code{mfhi} if the +although GCC avoids using @code{mflo} and @code{mfhi} if the VR4130 @code{macc}, @code{macchi}, @code{dmacc} and @code{dmacchi} instructions are available instead. @@ -15943,7 +15952,7 @@ side-effects of speculation on R10K processors. In common with many processors, the R10K tries to predict the outcome of a conditional branch and speculatively executes instructions from the ``taken'' branch. It later aborts these instructions if the -predicted outcome was wrong. However, on the R10K, even aborted +predicted outcome is wrong. However, on the R10K, even aborted instructions can have side effects. This problem only affects kernel stores and, depending on the system, @@ -15951,14 +15960,14 @@ kernel loads. As an example, a speculatively-executed store may load the target memory into cache and mark the cache line as dirty, even if the store itself is later aborted. If a DMA operation writes to the same area of memory before the ``dirty'' line is flushed, the cached -data will overwrite the DMA-ed data. See the R10K processor manual +data overwrites the DMA-ed data. See the R10K processor manual for a full description, including other potential problems. One workaround is to insert cache barrier instructions before every memory access that might be speculatively executed and that might have side effects even if aborted. @option{-mr10k-cache-barrier=@var{setting}} controls GCC's implementation of this workaround. It assumes that -aborted accesses to any byte in the following regions will not have +aborted accesses to any byte in the following regions does not have side effects: @enumerate @@ -16029,14 +16038,15 @@ default for the selected architecture. By default, Branch Likely instructions may be generated if they are supported by the selected architecture. An exception is for the MIPS32 and MIPS64 architectures and processors that implement those architectures; for those, Branch -Likely instructions will not be generated by default because the MIPS32 +Likely instructions are not be generated by default because the MIPS32 and MIPS64 architectures specifically deprecate their use. @item -mfp-exceptions @itemx -mno-fp-exceptions @opindex mfp-exceptions -Specifies whether FP exceptions are enabled. This affects how we schedule -FP instructions for some processors. The default is that FP exceptions are +Specifies whether FP exceptions are enabled. This affects how +FP instructions are scheduled for some processors. +The default is that FP exceptions are enabled. For instance, on the SB-1, if FP exceptions are disabled, and we are emitting @@ -16048,7 +16058,7 @@ FP pipe. @opindex mvr4130-align The VR4130 pipeline is two-way superscalar, but can only issue two instructions together if the first one is 8-byte aligned. When this -option is enabled, GCC will align pairs of instructions that it +option is enabled, GCC aligns pairs of instructions that it thinks should execute in parallel. This option only has an effect when optimizing for the VR4130. @@ -16060,7 +16070,7 @@ It is enabled by default at optimization level @option{-O3}. @opindex msynci Enable (disable) generation of @code{synci} instructions on architectures that support it. The @code{synci} instructions (if -enabled) will be generated when @code{__builtin___clear_cache()} is +enabled) are generated when @code{__builtin___clear_cache()} is compiled. This option defaults to @code{-mno-synci}, but the default can be @@ -16068,7 +16078,7 @@ overridden by configuring with @code{--with-synci}. When compiling code for single processor systems, it is generally safe to use @code{synci}. However, on many multi-core (SMP) systems, it -will not invalidate the instruction caches on all cores and may lead +does not invalidate the instruction caches on all cores and may lead to undefined behavior. @item -mrelax-pic-calls @@ -16238,8 +16248,8 @@ type. The CPU type must be one of @samp{mn10300}, @samp{am33}, @opindex mreturn-pointer-on-d0 When generating a function that returns a pointer, return the pointer in both @code{a0} and @code{d0}. Otherwise, the pointer is returned -only in a0, and attempts to call such functions without a prototype -would result in errors. Note that this option is on by default; use +only in @code{a0}, and attempts to call such functions without a prototype +result in errors. Note that this option is on by default; use @option{-mno-return-pointer-on-d0} to disable it. @item -mno-crt0 @@ -16392,9 +16402,9 @@ parameters for array element type @var{ae_type}. Supported values for @var{ae_type} are @samp{ANY}, @samp{MUL}, and @samp{MAC}. @option{-mae=ANY} selects a completely generic AE type. Code -generated with this option will run on any of the other AE types. The -code will not be as efficient as it would be if compiled for a specific -AE type, and some types of operation (e.g., multiplication) will not +generated with this option runs on any of the other AE types. The +code is not as efficient as it would be if compiled for a specific +AE type, and some types of operation (e.g., multiplication) do not work properly on all types of AE. @option{-mae=MUL} selects a MUL AE type. This is the most useful AE type @@ -16407,7 +16417,7 @@ since the DSP AE does not provide hardware support for byte load/stores. @item -msymbol-as-address Enable the compiler to directly use a symbol name as an address in a load/store instruction, without first loading it into a -register. Typically, the use of this option will generate larger +register. Typically, the use of this option generates larger programs, which run faster than when the option isn't used. However, the results vary from program to program, so it is left as a user option, rather than being permanently enabled. @@ -16418,10 +16428,10 @@ warnings can be generated, for example, when compiling code that performs byte-level memory operations on the MAC AE type. The MAC AE has no hardware support for byte-level memory operations, so all byte load/stores must be synthesized from word load/store operations. This is -inefficient and a warning will be generated indicating to the programmer -that they should rewrite the code to avoid byte operations, or to target -an AE type that has the necessary hardware support. This option enables -the warning to be turned off. +inefficient and a warning is generated to indicate +that you should rewrite the code to avoid byte operations, or to target +an AE type that has the necessary hardware support. This option disables +these warnings. @end table @@ -16578,8 +16588,8 @@ and to treat GPRs as 64-bit, doubleword quantities. GCC defaults to @option{-mno-powerpc64}. If you specify both @option{-mno-power} and @option{-mno-powerpc}, GCC -will use only the instructions in the common subset of both -architectures plus some special AIX common-mode calls, and will not use +uses only the instructions in the common subset of both +architectures plus some special AIX common-mode calls, and does not use the MQ register. Specifying both @option{-mpower} and @option{-mpowerpc} permits GCC to use any instruction from either architecture and to allow use of the MQ register; specify this for the Motorola MPC601. @@ -16618,9 +16628,9 @@ Supported values for @var{cpu_type} are @samp{401}, @samp{403}, @samp{rios1}, @samp{rios2}, @samp{rsc}, and @samp{rs64}. @option{-mcpu=common} selects a completely generic processor. Code -generated under this option will run on any POWER or PowerPC processor. -GCC will use only the instructions in the common subset of both -architectures, and will not use the MQ register. GCC assumes a generic +generated under this option runs on any POWER or PowerPC processor. +GCC uses only the instructions in the common subset of both +architectures, and does not use the MQ register. GCC assumes a generic processor model for scheduling purposes. @option{-mcpu=power}, @option{-mcpu=power2}, @option{-mcpu=powerpc}, and @@ -16630,7 +16640,7 @@ types, with an appropriate, generic processor model assumed for scheduling purposes. The other options specify a specific processor. Code generated under -those options will run best on that processor, and may not run at all on +those options runs best on that processor, and may not run at all on others. The @option{-mcpu} options automatically enable or disable the @@ -16641,7 +16651,7 @@ following options: -mpowerpc-gpopt -mpowerpc-gfxopt -msingle-float -mdouble-float @gol -msimple-fpu -mstring -mmulhw -mdlmzb -mmfpgpr -mvsx} -The particular options set for any particular CPU will vary between +The particular options set for any particular CPU varies between compiler versions, depending on what setting seems to produce optimal code for that CPU; it doesn't necessarily reflect the actual hardware's capabilities. If you wish to set an individual option to a particular @@ -16658,9 +16668,9 @@ environment. @opindex mtune Set the instruction scheduling parameters for machine type @var{cpu_type}, but do not set the architecture type, register usage, or -choice of mnemonics, as @option{-mcpu=@var{cpu_type}} would. The same +choice of mnemonics, as @option{-mcpu=@var{cpu_type}} does. The same values for @var{cpu_type} are used for @option{-mtune} as for -@option{-mcpu}. If both are specified, the code generated will use the +@option{-mcpu}. If both are specified, the code generated uses the architecture, registers, and mnemonics set by @option{-mcpu}, but the scheduling parameters set by @option{-mtune}. @@ -16796,9 +16806,9 @@ pointer to 64 bits, and generates code for PowerPC64, as for @opindex mminimal-toc Modify generation of the TOC (Table Of Contents), which is created for every executable file. The @option{-mfull-toc} option is selected by -default. In that case, GCC will allocate at least one TOC entry for +default. In that case, GCC allocates at least one TOC entry for each unique non-automatic variable reference in your program. GCC -will also place floating-point constants in the TOC@. However, only +also places floating-point constants in the TOC@. However, only 16,384 entries are available in the TOC@. If you receive a linker error message that saying you have overflowed @@ -16814,9 +16824,9 @@ slower and larger code at the expense of conserving TOC space. If you still run out of space in the TOC even when you specify both of these options, specify @option{-mminimal-toc} instead. This option causes GCC to make only one TOC entry for every file. When you specify this -option, GCC will produce code that is slower and larger but which +option, GCC produces code that is slower and larger but which uses extremely little TOC space. You may wish to use this option -only on files that contain less frequently executed code. +only on files that contain less frequently-executed code. @item -maix64 @itemx -maix32 @@ -17000,7 +17010,7 @@ size. @opindex mno-strict-align @opindex mstrict-align On System V.4 and embedded PowerPC systems do not (do) assume that -unaligned memory references will be handled by the system. +unaligned memory references are handled by the system. @item -mrelocatable @itemx -mno-relocatable @@ -17099,7 +17109,7 @@ Any dependence for which the latency is greater than or equal to @item -minsert-sched-nops=@var{scheme} @opindex minsert-sched-nops -This option controls which NOP insertion scheme will be used during +This option controls which NOP insertion scheme is used during the second scheduling pass. The argument @var{scheme} takes one of the following values: @@ -17206,10 +17216,10 @@ On System V.4 and embedded PowerPC systems assume that all calls to variable argument functions are properly prototyped. Otherwise, the compiler must insert an instruction before every non prototyped call to set or clear bit 6 of the condition code register (@var{CR}) to -indicate whether floating-point values were passed in the floating-point +indicate whether floating-point values are passed in the floating-point registers in case the function takes variable arguments. With @option{-mprototype}, only calls to prototyped variable argument functions -will set or clear the bit. +set or clear the bit. @item -msim @opindex msim @@ -17259,7 +17269,7 @@ environment, and the @option{-msdata} option can use both @code{r2} and @code{r13} to point to two separate small data areas. Selecting @option{-mno-eabi} means that the stack is aligned to a 16-byte boundary, do not call an initialization function from @code{main}, and the -@option{-msdata} option will only use @code{r13} to point to a single +@option{-msdata} option only uses @code{r13} to point to a single small data area. The @option{-meabi} option is on by default if you configured GCC using one of the @samp{powerpc*-*-eabi*} options. @@ -17339,7 +17349,7 @@ names in the assembly language output using symbolic forms. By default assume that all calls are far away so that a longer more expensive calling sequence is required. This is required for calls further than 32 megabytes (33,554,432 bytes) from the current location. -A short call will be generated if the compiler knows +A short call is generated if the compiler knows the call cannot be that far away. This setting can be overridden by the @code{shortcall} function attribute, or by @code{#pragma longcall(0)}. @@ -17350,12 +17360,12 @@ generate slower code. As of this writing, the AIX linker can do this, as can the GNU linker for PowerPC/64. It is planned to add this feature to the GNU linker for 32-bit PowerPC systems as well. -On Darwin/PPC systems, @code{#pragma longcall} will generate @code{jbsr +On Darwin/PPC systems, @code{#pragma longcall} generates @code{jbsr callee, L42}, plus a @dfn{branch island} (glue code). The two target addresses represent the callee and the branch island. The -Darwin/PPC linker will prefer the first address and generate a @code{bl -callee} if the PPC @code{bl} instruction will reach the callee directly; -otherwise, the linker will generate @code{bl L42} to call the branch +Darwin/PPC linker prefers the first address and generates a @code{bl +callee} if the PPC @code{bl} instruction reaches the callee directly; +otherwise, the linker generates @code{bl L42} to call the branch island. The branch island is appended to the body of the calling function; it computes the full 32-bit address of the callee and jumps to it. @@ -17364,7 +17374,7 @@ On Mach-O (Darwin) systems, this option directs the compiler emit to the glue for every direct call, and the Darwin linker decides whether to use or discard it. -In the future, we may cause GCC to ignore all longcall specifications +In the future, GCC may ignore all longcall specifications when the linker is known to generate glue. @item -mtls-markers @@ -17385,7 +17395,7 @@ This option sets flags for both the preprocessor and linker. @item -mrecip @itemx -mno-recip @opindex mrecip -This option will enable GCC to use the reciprocal estimate and +This option enables use of the reciprocal estimate and reciprocal square root estimate instructions with additional Newton-Raphson steps to increase precision instead of doing a divide or square root and divide for floating-point arguments. You should use @@ -17413,7 +17423,7 @@ be preceded by a @code{!} to invert the option: @code{rsqrtf}: enable the single-precision reciprocal square root approximation instructions; @code{rsqrtd}: enable the double-precision reciprocal square root approximation instructions; -So for example, @option{-mrecip=all,!rsqrtd} would enable the +So, for example, @option{-mrecip=all,!rsqrtd} enables all of the reciprocal estimate instructions, except for the @code{FRSQRTE}, @code{XSRSQRTEDP}, and @code{XVRSQRTEDP} instructions which handle the double-precision reciprocal square root calculations. @@ -17435,7 +17445,7 @@ Specifies the ABI type to use for vectorizing intrinsics using an external library. The only type supported at present is @code{mass}, which specifies to use IBM's Mathematical Acceleration Subsystem (MASS) libraries for vectorizing intrinsics using external libraries. -GCC will currently emit calls to @code{acosd2}, @code{acosf4}, +GCC currently emits calls to @code{acosd2}, @code{acosf4}, @code{acoshd2}, @code{acoshf4}, @code{asind2}, @code{asinf4}, @code{asinhd2}, @code{asinhf4}, @code{atan2d2}, @code{atan2f4}, @code{atand2}, @code{atanf4}, @code{atanhd2}, @code{atanhf4}, @@ -17450,8 +17460,8 @@ GCC will currently emit calls to @code{acosd2}, @code{acosf4}, @code{sinhf4}, @code{sqrtd2}, @code{sqrtf4}, @code{tand2}, @code{tanf4}, @code{tanhd2}, and @code{tanhf4} when generating code for power7. Both @option{-ftree-vectorize} and -@option{-funsafe-math-optimizations} have to be enabled. The MASS -libraries will have to be specified at link time. +@option{-funsafe-math-optimizations} must also be enabled. The MASS +libraries must be specified at link time. @item -mfriz @itemx -mno-friz @@ -17470,8 +17480,8 @@ Generate (do not generate) code to load up the static chain register systems where a function pointer points to a 3-word descriptor giving the function address, TOC value to be loaded in register @var{r2}, and static chain value to be loaded in register @var{r11}. The -@option{-mpointers-to-nested-functions} is on by default. You will -not be able to call through pointers to nested functions or pointers +@option{-mpointers-to-nested-functions} is on by default. You cannot +call through pointers to nested functions or pointers to functions compiled in other languages that use the static chain if you use the @option{-mno-pointers-to-nested-functions}. @@ -17510,9 +17520,9 @@ Enables (@option{-fpu}) or disables (@option{-nofpu}) the use of RX floating-point hardware. The default is enabled for the @var{RX600} series and disabled for the @var{RX200} series. -Floating-point instructions will only be generated for 32-bit floating-point -values however, so if the @option{-m64bit-doubles} option is in -use then the FPU hardware will not be used for doubles. +Floating-point instructions are only generated for 32-bit floating-point +values, however, so the FPU hardware is not used for doubles if the +@option{-m64bit-doubles} option is used. @emph{Note} If the @option{-fpu} option is enabled then @option{-funsafe-math-optimizations} is also enabled automatically. @@ -17548,9 +17558,8 @@ limited and it is up to the programmer to ensure that the area does not overflow. Also when the small data area is used one of the RX's registers (usually @code{r13}) is reserved for use pointing to this area, so it is no longer available for use by the compiler. This -could result in slower and/or larger code if variables which once -could have been held in the reserved register are now pushed onto the -stack. +could result in slower and/or larger code if variables are pushed onto +the stack instead of being held in this register. Note, common variables (variables that have not been initialized) and constants are not placed into the small data area as they are assigned @@ -17596,14 +17605,14 @@ or 4 means that constants of any size are allowed. @item -mrelax @opindex mrelax Enable linker relaxation. Linker relaxation is a process whereby the -linker will attempt to reduce the size of a program by finding shorter +linker attempts to reduce the size of a program by finding shorter versions of various instructions. Disabled by default. @item -mint-register=@var{N} @opindex mint-register Specify the number of registers to reserve for fast interrupt handler functions. The value @var{N} can be between 0 and 4. A value of 1 -means that register @code{r13} will be reserved for the exclusive use +means that register @code{r13} is reserved for the exclusive use of fast interrupt handlers. A value of 2 reserves @code{r13} and @code{r12}. A value of 3 reserves @code{r13}, @code{r12} and @code{r11}, and a value of 4 reserves @code{r13} through @code{r10}. @@ -17622,7 +17631,7 @@ makes the interrupt handlers faster. @opindex mpid @opindex mno-pid Enables the generation of position independent data. When enabled any -access to constant data will done via an offset from a base address +access to constant data is done via an offset from a base address held in a register. This allows the location of constant data to be determined at run time without requiring the executable to be relocated, which is a benefit to embedded applications with tight @@ -17651,7 +17660,7 @@ via the @option{-mno-pid} command-line option. @emph{Note:} The generic GCC command-line option @option{-ffixed-@var{reg}} has special significance to the RX port when used with the @code{interrupt} function attribute. This attribute indicates a -function intended to process fast interrupts. GCC will will ensure +function intended to process fast interrupts. GCC ensures that it only uses the registers @code{r10}, @code{r11}, @code{r12} and/or @code{r13} and only provided that the normal use of the corresponding registers have been restricted via the @@ -17671,7 +17680,7 @@ These are the @samp{-m} options defined for the S/390 and zSeries architecture. @opindex msoft-float Use (do not use) the hardware floating-point instructions and registers for floating-point operations. When @option{-msoft-float} is specified, -functions in @file{libgcc.a} will be used to perform floating-point +functions in @file{libgcc.a} are used to perform floating-point operations. When @option{-mhard-float} is specified, the compiler generates IEEE floating-point instructions. This is the default. @@ -17681,7 +17690,7 @@ generates IEEE floating-point instructions. This is the default. @opindex mno-hard-dfp Use (do not use) the hardware decimal-floating-point instructions for decimal-floating-point operations. When @option{-mno-hard-dfp} is -specified, functions in @file{libgcc.a} will be used to perform +specified, functions in @file{libgcc.a} are used to perform decimal-floating-point operations. When @option{-mhard-dfp} is specified, the compiler generates decimal-floating-point hardware instructions. This is the default for @option{-march=z9-ec} or higher. @@ -17794,7 +17803,7 @@ The default is to not print debug information. @item -march=@var{cpu-type} @opindex march -Generate code that will run on @var{cpu-type}, which is the name of a system +Generate code that runs on @var{cpu-type}, which is the name of a system representing a certain processor type. Possible values for @var{cpu-type} are @samp{g5}, @samp{g6}, @samp{z900}, @samp{z990}, @samp{z9-109}, @samp{z9-ec} and @samp{z10}. @@ -18000,7 +18009,7 @@ Compile code for the processor in little-endian mode. @item -mdalign @opindex mdalign Align doubles at 64-bit boundaries. Note that this changes the calling -conventions, and thus some functions from the standard C library will +conventions, and thus some functions from the standard C library do not work unless you recompile it first with @option{-mdalign}. @item -mrelax @@ -18058,10 +18067,10 @@ This option has no effect if @option{-musermode} is in effect and the selected code generation option (e.g. @option{-m4}) does not allow the use of the @code{icbi} instruction. If the selected code generation option does not allow the use of the @code{icbi} -instruction, and @option{-musermode} is not in effect, the inlined code will -manipulate the instruction cache address array directly with an associative -write. This not only requires privileged mode, but it will also -fail if the cache line had been mapped via the TLB and has become unmapped. +instruction, and @option{-musermode} is not in effect, the inlined code +manipulates the instruction cache address array directly with an associative +write. This not only requires privileged mode at run time, but it also +fails if the cache line had been mapped via the TLB and has become unmapped. @item -misize @opindex misize @@ -18163,7 +18172,7 @@ in that case. @item inv20u @itemx inv20l Variants of the @samp{inv:minlat} strategy. In the case -that the inverse calculation was not separated from the multiply, they speed +that the inverse calculation is not separated from the multiply, they speed up division where the dividend fits into 20 bits (plus sign where applicable) by inserting a test to skip a number of operations in this case; this test slows down the case of larger dividends. @samp{inv20u} assumes the case of a such @@ -18247,7 +18256,7 @@ of symbol loads. The default is @option{-mno-invalid-symbols}. @item -mbranch-cost=@var{num} @opindex mbranch-cost=@var{num} Assume @var{num} to be the cost for a branch instruction. Higher numbers -will make the compiler try to generate more branch-free code if possible. +make the compiler try to generate more branch-free code if possible. If not specified the value is selected depending on the processor type that is being compiled for. @@ -18290,7 +18299,7 @@ code into a shared object. @option{-mimpure-text} suppresses the ``relocations remain against allocatable but non-writable sections'' linker error message. -However, the necessary relocations will trigger copy-on-write, and the +However, the necessary relocations trigger copy-on-write, and the shared object is not actually shared across processes. Instead of using @option{-mimpure-text}, you should compile all source code with @option{-fpic} or @option{-fPIC}. @@ -18338,7 +18347,7 @@ software with this option. With @option{-mflat}, the compiler does not generate save/restore instructions and uses a ``flat'' or single register window model. This model is compatible with the regular register window model. The local registers and the input -registers (0--5) are still treated as ``call-saved'' registers and will be +registers (0--5) are still treated as ``call-saved'' registers and are saved on the stack as needed. With @option{-mno-flat} (the default), the compiler generates save/restore @@ -18410,7 +18419,7 @@ should have 8-byte alignment. This enables the use of pairs of assignment, in place of twice as many @code{ld} and @code{st} pairs. However, the use of this changed alignment directly violates the SPARC ABI@. Thus, it's intended only for use on targets where the developer -acknowledges that their resulting code will not be directly in line with +acknowledges that their resulting code is not directly in line with the rules of the ABI@. @item -mcpu=@var{cpu_type} @@ -18497,7 +18506,7 @@ additionally optimizes it for Sun UltraSPARC T4 chips. @opindex mtune Set the instruction scheduling parameters for machine type @var{cpu_type}, but do not set the instruction set or register set that the -option @option{-mcpu=@var{cpu_type}} would. +option @option{-mcpu=@var{cpu_type}} does. The same values for @option{-mcpu=@var{cpu_type}} can be used for @option{-mtune=@var{cpu_type}}, but the only useful values are those @@ -18662,9 +18671,9 @@ These @samp{-m} options are supported on the SPU: @opindex merror-reloc The loader for SPU does not handle dynamic relocations. By default, GCC -will give an error when it generates code that requires a dynamic +gives an error when it generates code that requires a dynamic relocation. @option{-mno-error-reloc} disables the error, -@option{-mwarn-reloc} will generate a warning instead. +@option{-mwarn-reloc} generates a warning instead. @item -msafe-dma @itemx -munsafe-dma @@ -18683,9 +18692,9 @@ the DMA instructions as potentially affecting all memory. @item -mbranch-hints @opindex mbranch-hints -By default, GCC will generate a branch hint instruction to avoid -pipeline stalls for always taken or probably taken branches. A hint -will not be generated closer than 8 instructions away from its branch. +By default, GCC generates a branch hint instruction to avoid +pipeline stalls for always-taken or probably-taken branches. A hint +is not generated closer than 8 instructions away from its branch. There is little reason to disable them, except for debugging purposes, or to make an object a little bit smaller. @@ -18703,7 +18712,7 @@ a full 32-bit address. By default, GCC links against startup code that assumes the SPU-style main function interface (which has an unconventional parameter list). -With @option{-mstdmain}, GCC will link your program against startup +With @option{-mstdmain}, GCC links your program against startup code that assumes a C99-style interface to @code{main}, including a local copy of @code{argv} strings. @@ -18750,36 +18759,36 @@ This option controls the version of libgcc that the compiler links to an executable and selects whether atomic updates to the software-managed cache of PPU-side variables are used. If you use atomic updates, changes to a PPU variable from SPU code using the @code{__ea} named address space -qualifier will not interfere with changes to other PPU variables residing +qualifier do not interfere with changes to other PPU variables residing in the same cache line from PPU code. If you do not use atomic updates, -such interference may occur; however, writing back cache lines will be +such interference may occur; however, writing back cache lines is more efficient. The default behavior is to use atomic updates. @item -mdual-nops @itemx -mdual-nops=@var{n} @opindex mdual-nops -By default, GCC will insert nops to increase dual issue when it expects +By default, GCC inserts nops to increase dual issue when it expects it to increase performance. @var{n} can be a value from 0 to 10. A -smaller @var{n} will insert fewer nops. 10 is the default, 0 is the +smaller @var{n} inserts fewer nops. 10 is the default, 0 is the same as @option{-mno-dual-nops}. Disabled with @option{-Os}. @item -mhint-max-nops=@var{n} @opindex mhint-max-nops Maximum number of nops to insert for a branch hint. A branch hint must -be at least 8 instructions away from the branch it is effecting. GCC -will insert up to @var{n} nops to enforce this, otherwise it will not +be at least 8 instructions away from the branch it is affecting. GCC +inserts up to @var{n} nops to enforce this, otherwise it does not generate the branch hint. @item -mhint-max-distance=@var{n} @opindex mhint-max-distance The encoding of the branch hint instruction limits the hint to be within -256 instructions of the branch it is effecting. By default, GCC makes +256 instructions of the branch it is affecting. By default, GCC makes sure it is within 125. @item -msafe-hints @opindex msafe-hints Work around a hardware bug that causes the SPU to stall indefinitely. -By default, GCC will insert the @code{hbrp} instruction to make sure +By default, GCC inserts the @code{hbrp} instruction to make sure this stall won't happen. @end table @@ -18871,8 +18880,8 @@ These @samp{-m} options are defined for V850 implementations: @opindex mlong-calls @opindex mno-long-calls Treat all calls as being far away (near). If calls are assumed to be -far away, the compiler will always load the functions address up into a -register, and call indirect through the pointer. +far away, the compiler always loads the function's address into a +register, and calls indirect through the pointer. @item -mno-ep @itemx -mep @@ -18927,28 +18936,28 @@ table. @item -mapp-regs @opindex mapp-regs -This option will cause r2 and r5 to be used in the code generated by +This option causes r2 and r5 to be used in the code generated by the compiler. This setting is the default. @item -mno-app-regs @opindex mno-app-regs -This option will cause r2 and r5 to be treated as fixed registers. +This option causes r2 and r5 to be treated as fixed registers. @item -mv850e2v3 @opindex mv850e2v3 Specify that the target processor is the V850E2V3. The preprocessor -constants @samp{__v850e2v3__} will be defined if +constant @samp{__v850e2v3__} is defined if this option is used. @item -mv850e2 @opindex mv850e2 Specify that the target processor is the V850E2. The preprocessor -constants @samp{__v850e2__} will be defined if this option is used. +constant @samp{__v850e2__} is defined if this option is used. @item -mv850e1 @opindex mv850e1 Specify that the target processor is the V850E1. The preprocessor -constants @samp{__v850e1__} and @samp{__v850e__} will be defined if +constants @samp{__v850e1__} and @samp{__v850e__} are defined if this option is used. @item -mv850es @@ -18959,21 +18968,21 @@ the @option{-mv850e1} option. @item -mv850e @opindex mv850e Specify that the target processor is the V850E@. The preprocessor -constant @samp{__v850e__} will be defined if this option is used. +constant @samp{__v850e__} is defined if this option is used. If neither @option{-mv850} nor @option{-mv850e} nor @option{-mv850e1} nor @option{-mv850e2} nor @option{-mv850e2v3} -are defined then a default target processor will be chosen and the -relevant @samp{__v850*__} preprocessor constant will be defined. +are defined then a default target processor is chosen and the +relevant @samp{__v850*__} preprocessor constant is defined. The preprocessor constants @samp{__v850} and @samp{__v851__} are always defined, regardless of which processor variant is the target. @item -mdisable-callt @opindex mdisable-callt -This option will suppress generation of the CALLT instruction for the +This option suppresses generation of the @code{CALLT} instruction for the v850e, v850e1, v850e2 and v850e2v3 flavors of the v850 architecture. The default is -@option{-mno-disable-callt} which allows the CALLT instruction to be used. +@option{-mno-disable-callt} which allows the @code{CALLT} instruction to be used. @end table @@ -18992,8 +19001,8 @@ ranges. @item -mgnu @opindex mgnu -Do output those jump instructions, on the assumption that you -will assemble with the GNU assembler. +Do output those jump instructions, on the assumption that the +GNU assembler is being used. @item -mg @opindex mg @@ -19159,11 +19168,11 @@ automatically align instructions to reduce branch penalties at the expense of some code density. The assembler attempts to widen density instructions to align branch targets and the instructions following call instructions. If there are not enough preceding safe density -instructions to align a target, no widening will be performed. The +instructions to align a target, no widening is performed. The default is @option{-mtarget-align}. These options do not affect the treatment of auto-aligned instructions like @code{LOOP}, which the -assembler will always align, either by widening density instructions or -by inserting no-op instructions. +assembler always aligns, either by widening density instructions or +by inserting NOP instructions. @item -mlongcalls @itemx -mno-longcalls @@ -19178,10 +19187,10 @@ instruction into an @code{L32R} followed by a @code{CALLX} instruction. The default is @option{-mno-longcalls}. This option should be used in programs where the call target can potentially be out of range. This option is implemented in the assembler, not the compiler, so the -assembly code generated by GCC will still show direct call +assembly code generated by GCC still shows direct call instructions---look at the disassembled object code to see the actual -instructions. Note that the assembler will use an indirect call for -every cross-file call, not just those that really will be out of range. +instructions. Note that the assembler uses an indirect call for +every cross-file call, not just those that really are out of range. @end table @node zSeries Options @@ -19200,7 +19209,7 @@ These machine-independent options control the interface conventions used in code generation. Most of them have both positive and negative forms; the negative form -of @option{-ffoo} would be @option{-fno-foo}. In the table below, only +of @option{-ffoo} is @option{-fno-foo}. In the table below, only one of the forms is listed---the one that is not the default. You can figure out the other form by either removing @samp{no-} or adding it. @@ -19229,11 +19238,11 @@ front end, as required by the Java language specification. @item -fexceptions @opindex fexceptions Enable exception handling. Generates extra code needed to propagate -exceptions. For some targets, this implies GCC will generate frame +exceptions. For some targets, this implies GCC generates frame unwind information for all functions, which can produce significant data size overhead, although it does not affect execution. If you do not -specify this option, GCC will enable it by default for languages like -C++ that normally require exception handling, and disable it for +specify this option, GCC enables it by default for languages like +C++ that normally require exception handling, and disables it for languages like C that do not normally require it. However, you may need to enable this option when compiling C code that needs to interoperate properly with exception handlers written in C++. You may also wish to @@ -19251,10 +19260,10 @@ arbitrary signal handlers such as @code{SIGALRM}. @item -funwind-tables @opindex funwind-tables -Similar to @option{-fexceptions}, except that it will just generate any needed -static data, but will not affect the generated code in any other way. -You will normally not enable this option; instead, a language processor -that needs this handling would enable it on your behalf. +Similar to @option{-fexceptions}, except that it just generates any needed +static data, but does not affect the generated code in any other way. +You normally do not need to enable this option; instead, a language processor +that needs this handling enables it on your behalf. @item -fasynchronous-unwind-tables @opindex fasynchronous-unwind-tables @@ -19303,7 +19312,7 @@ Use it to conform to a non-default application binary interface. @opindex fshort-enums Allocate to an @code{enum} type only as many bytes as it needs for the declared range of possible values. Specifically, the @code{enum} type -will be equivalent to the smallest integer type that has enough room. +is equivalent to the smallest integer type that has enough room. @strong{Warning:} the @option{-fshort-enums} switch causes GCC to generate code that is not binary compatible with code generated without that switch. @@ -19342,7 +19351,7 @@ uninitialized global variables in the data section of the object file, rather than generating them as common blocks. This has the effect that if the same variable is declared (without @code{extern}) in two different compilations, -you will get a multiple-definition error when you link them. +you get a multiple-definition error when you link them. In this case, you must compile with @option{-fcommon} instead. Compiling with @option{-fno-common} is useful on targets for which it provides better performance, or if you wish to verify that the @@ -19374,7 +19383,7 @@ files. @item -frecord-gcc-switches @opindex frecord-gcc-switches -This switch causes the command line that was used to invoke the +This switch causes the command line used to invoke the compiler to be recorded into the object file that is being created. This switch is only implemented on some targets and the exact format of the recording is target and binary file format dependent, but it @@ -19427,7 +19436,7 @@ are defined to 2. @opindex fPIE These options are similar to @option{-fpic} and @option{-fPIC}, but generated position independent code can be only linked into executables. -Usually these options are used when @option{-pie} GCC option will be +Usually these options are used when @option{-pie} GCC option is used during linking. @option{-fpie} and @option{-fPIE} both define the macros @@ -19461,11 +19470,11 @@ three-way choice. Treat the register named @var{reg} as an allocable register that is clobbered by function calls. It may be allocated for temporaries or variables that do not live across a call. Functions compiled this way -will not save and restore the register @var{reg}. +do not save and restore the register @var{reg}. -It is an error to used this flag with the frame pointer or stack pointer. +It is an error to use this flag with the frame pointer or stack pointer. Use of this flag for other registers that have fixed pervasive roles in -the machine's execution model will produce disastrous results. +the machine's execution model produces disastrous results. This flag does not have a negative form, because it specifies a three-way choice. @@ -19474,14 +19483,14 @@ three-way choice. @opindex fcall-saved Treat the register named @var{reg} as an allocable register saved by functions. It may be allocated even for temporaries or variables that -live across a call. Functions compiled this way will save and restore +live across a call. Functions compiled this way save and restore the register @var{reg} if they use it. -It is an error to used this flag with the frame pointer or stack pointer. +It is an error to use this flag with the frame pointer or stack pointer. Use of this flag for other registers that have fixed pervasive roles in -the machine's execution model will produce disastrous results. +the machine's execution model produces disastrous results. -A different sort of disaster will result from the use of this flag for +A different sort of disaster results from the use of this flag for a register in which function values may be returned. This flag does not have a negative form, because it specifies a @@ -19493,7 +19502,7 @@ Without a value specified, pack all structure members together without holes. When a value is specified (which must be a small power of two), pack structure members according to this value, representing the maximum alignment (that is, objects with default alignment requirements larger than -this will be output potentially unaligned at the next fitting location. +this are output potentially unaligned at the next fitting location. @strong{Warning:} the @option{-fpack-struct} switch causes GCC to generate code that is not binary compatible with code generated without that switch. @@ -19504,7 +19513,7 @@ Use it to conform to a non-default application binary interface. @opindex finstrument-functions Generate instrumentation calls for entry and exit to functions. Just after function entry and just before function exit, the following -profiling functions will be called with the address of the current +profiling functions are called with the address of the current function and its call site. (On some platforms, @code{__builtin_return_address} does not work beyond the current function, so the call site information may not be available to the @@ -19521,18 +19530,18 @@ The first argument is the address of the start of the current function, which may be looked up exactly in the symbol table. This instrumentation is also done for functions expanded inline in other -functions. The profiling calls will indicate where, conceptually, the +functions. The profiling calls indicate where, conceptually, the inline function is entered and exited. This means that addressable versions of such functions must be available. If all your uses of a function are expanded inline, this may mean an additional expansion of code size. If you use @samp{extern inline} in your C code, an addressable version of such functions must be provided. (This is -normally the case anyways, but if you get lucky and the optimizer always +normally the case anyway, but if you get lucky and the optimizer always expands the functions inline, you might have gotten away without providing static copies.) A function may be given the attribute @code{no_instrument_function}, in -which case this instrumentation will not be done. This can be used, for +which case this instrumentation is not done. This can be used, for example, for the profiling functions listed above, high-priority interrupt routines, and any functions from which the profiling functions cannot safely be called (perhaps signal handlers, if the profiling @@ -19555,7 +19564,7 @@ For example: @end smallexample @noindent -will exclude any inline function defined in files whose pathnames +excludes any inline function defined in files whose pathnames contain @code{/bits/stl} or @code{include/sys}. If, for some reason, you want to include letter @code{','} in one of @@ -19598,7 +19607,7 @@ target support in the compiler but comes with the following drawbacks: @enumerate @item -Modified allocation strategy for large objects: they will always be +Modified allocation strategy for large objects: they are always allocated dynamically if their size exceeds a fixed threshold. @item @@ -19621,8 +19630,8 @@ Note that old-style stack checking is also the fallback method for @opindex fstack-limit-symbol @opindex fno-stack-limit Generate code to ensure that the stack does not grow beyond a certain value, -either the value of a register or the address of a symbol. If the stack -would grow beyond the value, a signal is raised. For most targets, +either the value of a register or the address of a symbol. If a larger +stack is required, a signal is raised at run time. For most targets, the signal is raised before the stack overruns the boundary, so it is possible to catch the signal without taking special precautions. @@ -19674,7 +19683,7 @@ The default without @option{-fpic} is @code{initial-exec}; with @item -fvisibility=@var{default|internal|hidden|protected} @opindex fvisibility Set the default ELF image symbol visibility to the specified option---all -symbols will be marked with this unless overridden within the code. +symbols are marked with this unless overridden within the code. Using this feature can very substantially improve linking and load times of shared object libraries, produce more optimized code, provide near-perfect API export and prevent symbol clashes. @@ -19684,7 +19693,7 @@ you distribute. Despite the nomenclature, @code{default} always means public; i.e., available to be linked against from outside the shared object. @code{protected} and @code{internal} are pretty useless in real-world -usage so the only other commonly used option will be @code{hidden}. +usage so the only other commonly used option is @code{hidden}. The default if @option{-fvisibility} isn't specified is @code{default}, i.e., make every symbol public---this causes the same behavior as previous versions of @@ -19725,15 +19734,15 @@ before including any such headers. @samp{extern} declarations are not affected by @option{-fvisibility}, so a lot of code can be recompiled with @option{-fvisibility=hidden} with no modifications. However, this means that calls to @code{extern} -functions with no explicit visibility will use the PLT, so it is more +functions with no explicit visibility use the PLT, so it is more effective to use @code{__attribute ((visibility))} and/or @code{#pragma GCC visibility} to tell the compiler which @code{extern} declarations should be treated as hidden. Note that @option{-fvisibility} does affect C++ vague linkage -entities. This means that, for instance, an exception class that will +entities. This means that, for instance, an exception class that is be thrown between DSOs must be explicitly marked with default -visibility so that the @samp{type_info} nodes will be unified between +visibility so that the @samp{type_info} nodes are unified between the DSOs. An overview of these techniques, their benefits and how to use them @@ -19751,9 +19760,9 @@ declare all peripheral bit-fields as @code{unsigned short} (assuming short is 16 bits on these targets) to force GCC to use 16-bit accesses instead of, perhaps, a more efficient 32-bit access. -If this option is disabled, the compiler will use the most efficient +If this option is disabled, the compiler uses the most efficient instruction. In the previous example, that might be a 32-bit load -instruction, even though that will access bytes that do not contain +instruction, even though that accesses bytes that do not contain any portion of the bit-field, or memory-mapped registers unrelated to the one being updated. @@ -19818,7 +19827,7 @@ Kingdom encoded in UTF-8. The @env{LC_CTYPE} environment variable specifies character classification. GCC uses it to determine the character boundaries in a string; this is needed for some multibyte encodings that contain quote -and escape characters that would otherwise be interpreted as a string +and escape characters that are otherwise interpreted as a string end or escape. The @env{LC_MESSAGES} environment variable specifies the language to @@ -19851,8 +19860,8 @@ names of the subprograms executed by the compiler. No slash is added when this prefix is combined with the name of a subprogram, but you can specify a prefix that ends with a slash if you wish. -If @env{GCC_EXEC_PREFIX} is not set, GCC will attempt to figure out -an appropriate prefix to use based on the pathname it was invoked with. +If @env{GCC_EXEC_PREFIX} is not set, GCC attempts to figure out +an appropriate prefix to use based on the pathname it is invoked with. If GCC cannot find the subprogram using the specified prefix, it tries looking in the usual places for the subprogram. @@ -19872,10 +19881,10 @@ directories to search for header files. For each of the standard directories whose name normally begins with @samp{/usr/local/lib/gcc} (more precisely, with the value of @env{GCC_INCLUDE_DIR}), GCC tries replacing that beginning with the specified prefix to produce an -alternate directory name. Thus, with @option{-Bfoo/}, GCC will search -@file{foo/bar} where it would normally search @file{/usr/local/lib/bar}. -These alternate directories are searched first; the standard directories -come next. If a standard directory begins with the configured +alternate directory name. Thus, with @option{-Bfoo/}, GCC searches +@file{foo/bar} just before it searches the standard directory +@file{/usr/local/lib/bar}. +If a standard directory begins with the configured @var{prefix} then the value of @var{prefix} is replaced by @env{GCC_EXEC_PREFIX} when looking for header files. @@ -19915,12 +19924,12 @@ Recognize EUCJP characters. @end table If @env{LANG} is not defined, or if it has some other value, then the -compiler will use mblen and mbtowc as defined by the default locale to +compiler uses @code{mblen} and @code{mbtowc} as defined by the default locale to recognize and translate multibyte characters. @end table @noindent -Some additional environments variables affect the behavior of the +Some additional environment variables affect the behavior of the preprocessor. @include cppenv.texi @@ -19935,17 +19944,16 @@ preprocessor. Often large projects have many header files that are included in every source file. The time the compiler takes to process these header files over and over again can account for nearly all of the time required to -build the project. To make builds faster, GCC allows users to -@dfn{precompile} a header file; then, if builds can use the precompiled -header file they will be much faster. +build the project. To make builds faster, GCC allows you to +@dfn{precompile} a header file. To create a precompiled header file, simply compile it as you would any other file, if necessary using the @option{-x} option to make the driver -treat it as a C or C++ header file. You will probably want to use a +treat it as a C or C++ header file. You may want to use a tool like @command{make} to keep the precompiled header up-to-date when the headers it contains change. -A precompiled header file will be searched for when @code{#include} is +A precompiled header file is searched for when @code{#include} is seen in the compilation. As it searches for the included file (@pxref{Search Path,,Search Path,cpp,The C Preprocessor}) the compiler looks for a precompiled header in each directory just before it @@ -19955,8 +19963,8 @@ the precompiled header file can't be used, it is ignored. For instance, if you have @code{#include "all.h"}, and you have @file{all.h.gch} in the same directory as @file{all.h}, then the -precompiled header file will be used if possible, and the original -header will be used otherwise. +precompiled header file is used if possible, and the original +header is used otherwise. Alternatively, you might decide to put the precompiled header file in a directory and use @option{-I} to ensure that directory is searched @@ -19970,17 +19978,17 @@ precompiled headers, good for projects not designed with precompiled header files in mind, is to simply take most of the header files used by a project, include them from another header file, precompile that header file, and @option{-include} the precompiled header. If the header files -have guards against multiple inclusion, they will be skipped because +have guards against multiple inclusion, they are skipped because they've already been included (in the precompiled header). If you need to precompile the same header file for different languages, targets, or compiler options, you can instead make a @emph{directory} named like @file{all.h.gch}, and put each precompiled header in the directory, perhaps using @option{-o}. It doesn't matter -what you call the files in the directory, every precompiled header in -the directory will be considered. The first precompiled header -encountered in the directory that is valid for this compilation will -be used; they're searched in no particular order. +what you call the files in the directory; every precompiled header in +the directory is considered. The first precompiled header +encountered in the directory that is valid for this compilation is +used; they're searched in no particular order. There are many other possibilities, limited only by your imagination, good sense, and the constraints of your build system. @@ -20047,14 +20055,14 @@ precompiled header. The following are known to be safe: @end itemize -For all of these except the last, the compiler will automatically -ignore the precompiled header if the conditions aren't met. If you +For all of these except the last, the compiler automatically +ignores the precompiled header if the conditions aren't met. If you find an option combination that doesn't work and doesn't cause the precompiled header to be ignored, please consider filing a bug report, see @ref{Bugs}. If you do use differing options when generating and using the -precompiled header, the actual behavior will be a mixture of the +precompiled header, the actual behavior is a mixture of the behavior for the options. For instance, if you use @option{-g} to generate the precompiled header but not when using it, you may or may not get debugging information for routines in the precompiled header. -- 2.7.4