1629@item -fno-weak
1630@opindex fno-weak
1631Do not use weak symbol support, even if it is provided by the linker.
1632By default, G++ will use weak symbols if they are available. This
1633option exists only for testing, and should not be used by end-users;
1634it will result in inferior code and has no benefits. This option may
1635be removed in a future release of G++.
1636
1637@item -nostdinc++
1638@opindex nostdinc++
1639Do not search for header files in the standard directories specific to
1640C++, but do still search the other standard directories. (This option
1641is used when building the C++ library.)
1642@end table
1643
1644In addition, these optimization, warning, and code generation options
1645have meanings only for C++ programs:
1646
1647@table @gcctabopt
1648@item -fno-default-inline
1649@opindex fno-default-inline
1650Do not assume @samp{inline} for functions defined inside a class scope.
1651@xref{Optimize Options,,Options That Control Optimization}. Note that these
1652functions will have linkage like inline functions; they just won't be
1653inlined by default.
1654
1655@item -Wabi @r{(C++ only)}
1656@opindex Wabi
1657Warn when G++ generates code that is probably not compatible with the
1658vendor-neutral C++ ABI@. Although an effort has been made to warn about
1659all such cases, there are probably some cases that are not warned about,
1660even though G++ is generating incompatible code. There may also be
1661cases where warnings are emitted even though the code that is generated
1662will be compatible.
1663
1664You should rewrite your code to avoid these warnings if you are
1665concerned about the fact that code generated by G++ may not be binary
1666compatible with code generated by other compilers.
1667
1668The known incompatibilities at this point include:
1669
1670@itemize @bullet
1671
1672@item
1673Incorrect handling of tail-padding for bit-fields. G++ may attempt to
1674pack data into the same byte as a base class. For example:
1675
1676@smallexample
1677struct A @{ virtual void f(); int f1 : 1; @};
1678struct B : public A @{ int f2 : 1; @};
1679@end smallexample
1680
1681@noindent
1682In this case, G++ will place @code{B::f2} into the same byte
1683as@code{A::f1}; other compilers will not. You can avoid this problem
1684by explicitly padding @code{A} so that its size is a multiple of the
1685byte size on your platform; that will cause G++ and other compilers to
1686layout @code{B} identically.
1687
1688@item
1689Incorrect handling of tail-padding for virtual bases. G++ does not use
1690tail padding when laying out virtual bases. For example:
1691
1692@smallexample
1693struct A @{ virtual void f(); char c1; @};
1694struct B @{ B(); char c2; @};
1695struct C : public A, public virtual B @{@};
1696@end smallexample
1697
1698@noindent
1699In this case, G++ will not place @code{B} into the tail-padding for
1700@code{A}; other compilers will. You can avoid this problem by
1701explicitly padding @code{A} so that its size is a multiple of its
1702alignment (ignoring virtual base classes); that will cause G++ and other
1703compilers to layout @code{C} identically.
1704
1705@item
1706Incorrect handling of bit-fields with declared widths greater than that
1707of their underlying types, when the bit-fields appear in a union. For
1708example:
1709
1710@smallexample
1711union U @{ int i : 4096; @};
1712@end smallexample
1713
1714@noindent
1715Assuming that an @code{int} does not have 4096 bits, G++ will make the
1716union too small by the number of bits in an @code{int}.
1717
1718@item
1719Empty classes can be placed at incorrect offsets. For example:
1720
1721@smallexample
1722struct A @{@};
1723
1724struct B @{
1725 A a;
1726 virtual void f ();
1727@};
1728
1729struct C : public B, public A @{@};
1730@end smallexample
1731
1732@noindent
1733G++ will place the @code{A} base class of @code{C} at a nonzero offset;
1734it should be placed at offset zero. G++ mistakenly believes that the
1735@code{A} data member of @code{B} is already at offset zero.
1736
1737@item
1738Names of template functions whose types involve @code{typename} or
1739template template parameters can be mangled incorrectly.
1740
1741@smallexample
1742template <typename Q>
1743void f(typename Q::X) @{@}
1744
1745template <template <typename> class Q>
1746void f(typename Q<int>::X) @{@}
1747@end smallexample
1748
1749@noindent
1750Instantiations of these templates may be mangled incorrectly.
1751
1752@end itemize
1753
1754@item -Wctor-dtor-privacy @r{(C++ only)}
1755@opindex Wctor-dtor-privacy
1756Warn when a class seems unusable because all the constructors or
1757destructors in that class are private, and it has neither friends nor
1758public static member functions.
1759
1760@item -Wnon-virtual-dtor @r{(C++ only)}
1761@opindex Wnon-virtual-dtor
1762Warn when a class appears to be polymorphic, thereby requiring a virtual
1763destructor, yet it declares a non-virtual one. This warning is also
1764enabled if -Weffc++ is specified.
1765
1766@item -Wreorder @r{(C++ only)}
1767@opindex Wreorder
1768@cindex reordering, warning
1769@cindex warning for reordering of member initializers
1770Warn when the order of member initializers given in the code does not
1771match the order in which they must be executed. For instance:
1772
1773@smallexample
1774struct A @{
1775 int i;
1776 int j;
1777 A(): j (0), i (1) @{ @}
1778@};
1779@end smallexample
1780
1781The compiler will rearrange the member initializers for @samp{i}
1782and @samp{j} to match the declaration order of the members, emitting
1783a warning to that effect. This warning is enabled by @option{-Wall}.
1784@end table
1785
1786The following @option{-W@dots{}} options are not affected by @option{-Wall}.
1787
1788@table @gcctabopt
1789@item -Weffc++ @r{(C++ only)}
1790@opindex Weffc++
1791Warn about violations of the following style guidelines from Scott Meyers'
1792@cite{Effective C++} book:
1793
1794@itemize @bullet
1795@item
1796Item 11: Define a copy constructor and an assignment operator for classes
1797with dynamically allocated memory.
1798
1799@item
1800Item 12: Prefer initialization to assignment in constructors.
1801
1802@item
1803Item 14: Make destructors virtual in base classes.
1804
1805@item
1806Item 15: Have @code{operator=} return a reference to @code{*this}.
1807
1808@item
1809Item 23: Don't try to return a reference when you must return an object.
1810
1811@end itemize
1812
1813Also warn about violations of the following style guidelines from
1814Scott Meyers' @cite{More Effective C++} book:
1815
1816@itemize @bullet
1817@item
1818Item 6: Distinguish between prefix and postfix forms of increment and
1819decrement operators.
1820
1821@item
1822Item 7: Never overload @code{&&}, @code{||}, or @code{,}.
1823
1824@end itemize
1825
1826When selecting this option, be aware that the standard library
1827headers do not obey all of these guidelines; use @samp{grep -v}
1828to filter out those warnings.
1829
1830@item -Wno-deprecated @r{(C++ only)}
1831@opindex Wno-deprecated
1832Do not warn about usage of deprecated features. @xref{Deprecated Features}.
1833
1834@item -Wstrict-null-sentinel @r{(C++ only)}
1835@opindex Wstrict-null-sentinel
1836Warn also about the use of an uncasted @code{NULL} as sentinel. When
1837compiling only with GCC this is a valid sentinel, as @code{NULL} is defined
1838to @code{__null}. Although it is a null pointer constant not a null pointer,
1839it is guaranteed to of the same size as a pointer. But this use is
1840not portable across different compilers.
1841
1842@item -Wno-non-template-friend @r{(C++ only)}
1843@opindex Wno-non-template-friend
1844Disable warnings when non-templatized friend functions are declared
1845within a template. Since the advent of explicit template specification
1846support in G++, if the name of the friend is an unqualified-id (i.e.,
1847@samp{friend foo(int)}), the C++ language specification demands that the
1848friend declare or define an ordinary, nontemplate function. (Section
184914.5.3). Before G++ implemented explicit specification, unqualified-ids
1850could be interpreted as a particular specialization of a templatized
1851function. Because this non-conforming behavior is no longer the default
1852behavior for G++, @option{-Wnon-template-friend} allows the compiler to
1853check existing code for potential trouble spots and is on by default.
1854This new compiler behavior can be turned off with
1855@option{-Wno-non-template-friend} which keeps the conformant compiler code
1856but disables the helpful warning.
1857
1858@item -Wold-style-cast @r{(C++ only)}
1859@opindex Wold-style-cast
1860Warn if an old-style (C-style) cast to a non-void type is used within
1861a C++ program. The new-style casts (@samp{dynamic_cast},
1862@samp{static_cast}, @samp{reinterpret_cast}, and @samp{const_cast}) are
1863less vulnerable to unintended effects and much easier to search for.
1864
1865@item -Woverloaded-virtual @r{(C++ only)}
1866@opindex Woverloaded-virtual
1867@cindex overloaded virtual fn, warning
1868@cindex warning for overloaded virtual fn
1869Warn when a function declaration hides virtual functions from a
1870base class. For example, in:
1871
1872@smallexample
1873struct A @{
1874 virtual void f();
1875@};
1876
1877struct B: public A @{
1878 void f(int);
1879@};
1880@end smallexample
1881
1882the @code{A} class version of @code{f} is hidden in @code{B}, and code
1883like:
1884
1885@smallexample
1886B* b;
1887b->f();
1888@end smallexample
1889
1890will fail to compile.
1891
1892@item -Wno-pmf-conversions @r{(C++ only)}
1893@opindex Wno-pmf-conversions
1894Disable the diagnostic for converting a bound pointer to member function
1895to a plain pointer.
1896
1897@item -Wsign-promo @r{(C++ only)}
1898@opindex Wsign-promo
1899Warn when overload resolution chooses a promotion from unsigned or
1900enumerated type to a signed type, over a conversion to an unsigned type of
1901the same size. Previous versions of G++ would try to preserve
1902unsignedness, but the standard mandates the current behavior.
1903
1904@smallexample
1905struct A @{
1906 operator int ();
1907 A& operator = (int);
1908@};
1909
1910main ()
1911@{
1912 A a,b;
1913 a = b;
1914@}
1915@end smallexample
1916
1917In this example, G++ will synthesize a default @samp{A& operator =
1918(const A&);}, while cfront will use the user-defined @samp{operator =}.
1919@end table
1920
1921@node Language Independent Options
1922@section Options to Control Diagnostic Messages Formatting
1923@cindex options to control diagnostics formatting
1924@cindex diagnostic messages
1925@cindex message formatting
1926
1927Traditionally, diagnostic messages have been formatted irrespective of
1928the output device's aspect (e.g.@: its width, @dots{}). The options described
1929below can be used to control the diagnostic messages formatting
1930algorithm, e.g.@: how many characters per line, how often source location
1931information should be reported. Right now, only the C++ front end can
1932honor these options. However it is expected, in the near future, that
1933the remaining front ends would be able to digest them correctly.
1934
1935@table @gcctabopt
1936@item -fmessage-length=@var{n}
1937@opindex fmessage-length
1938Try to format error messages so that they fit on lines of about @var{n}
1939characters. The default is 72 characters for @command{g++} and 0 for the rest of
1940the front ends supported by GCC@. If @var{n} is zero, then no
1941line-wrapping will be done; each error message will appear on a single
1942line.
1943
1944@opindex fdiagnostics-show-location
1945@item -fdiagnostics-show-location=once
1946Only meaningful in line-wrapping mode. Instructs the diagnostic messages
1947reporter to emit @emph{once} source location information; that is, in
1948case the message is too long to fit on a single physical line and has to
1949be wrapped, the source location won't be emitted (as prefix) again,
1950over and over, in subsequent continuation lines. This is the default
1951behavior.
1952
1953@item -fdiagnostics-show-location=every-line
1954Only meaningful in line-wrapping mode. Instructs the diagnostic
1955messages reporter to emit the same source location information (as
1956prefix) for physical lines that result from the process of breaking
1957a message which is too long to fit on a single line.
1958
1959@item -fdiagnostics-show-option
1960@opindex fdiagnostics-show-option
1961This option instructs the diagnostic machinery to add text to each
1962diagnostic emitted, which indicates which command line option directly
1963controls that diagnostic, when such an option is known to the
1964diagnostic machinery.
1965
1966@end table
1967
1968@node Warning Options
1969@section Options to Request or Suppress Warnings
1970@cindex options to control warnings
1971@cindex warning messages
1972@cindex messages, warning
1973@cindex suppressing warnings
1974
1975Warnings are diagnostic messages that report constructions which
1976are not inherently erroneous but which are risky or suggest there
1977may have been an error.
1978
1979You can request many specific warnings with options beginning @samp{-W},
1980for example @option{-Wimplicit} to request warnings on implicit
1981declarations. Each of these specific warning options also has a
1982negative form beginning @samp{-Wno-} to turn off warnings;
1983for example, @option{-Wno-implicit}. This manual lists only one of the
1984two forms, whichever is not the default.
1985
1986The following options control the amount and kinds of warnings produced
1987by GCC; for further, language-specific options also refer to
1988@ref{C++ Dialect Options}.
1989
1990@table @gcctabopt
1991@cindex syntax checking
1992@item -fsyntax-only
1993@opindex fsyntax-only
1994Check the code for syntax errors, but don't do anything beyond that.
1995
1996@item -pedantic
1997@opindex pedantic
1998Issue all the warnings demanded by strict ISO C and ISO C++;
1999reject all programs that use forbidden extensions, and some other
2000programs that do not follow ISO C and ISO C++. For ISO C, follows the
2001version of the ISO C standard specified by any @option{-std} option used.
2002
2003Valid ISO C and ISO C++ programs should compile properly with or without
2004this option (though a rare few will require @option{-ansi} or a
2005@option{-std} option specifying the required version of ISO C)@. However,
2006without this option, certain GNU extensions and traditional C and C++
2007features are supported as well. With this option, they are rejected.
2008
2009@option{-pedantic} does not cause warning messages for use of the
2010alternate keywords whose names begin and end with @samp{__}. Pedantic
2011warnings are also disabled in the expression that follows
2012@code{__extension__}. However, only system header files should use
2013these escape routes; application programs should avoid them.
2014@xref{Alternate Keywords}.
2015
2016Some users try to use @option{-pedantic} to check programs for strict ISO
2017C conformance. They soon find that it does not do quite what they want:
2018it finds some non-ISO practices, but not all---only those for which
2019ISO C @emph{requires} a diagnostic, and some others for which
2020diagnostics have been added.
2021
2022A feature to report any failure to conform to ISO C might be useful in
2023some instances, but would require considerable additional work and would
2024be quite different from @option{-pedantic}. We don't have plans to
2025support such a feature in the near future.
2026
2027Where the standard specified with @option{-std} represents a GNU
2028extended dialect of C, such as @samp{gnu89} or @samp{gnu99}, there is a
2029corresponding @dfn{base standard}, the version of ISO C on which the GNU
2030extended dialect is based. Warnings from @option{-pedantic} are given
2031where they are required by the base standard. (It would not make sense
2032for such warnings to be given only for features not in the specified GNU
2033C dialect, since by definition the GNU dialects of C include all
2034features the compiler supports with the given option, and there would be
2035nothing to warn about.)
2036
2037@item -pedantic-errors
2038@opindex pedantic-errors
2039Like @option{-pedantic}, except that errors are produced rather than
2040warnings.
2041
2042@item -w
2043@opindex w
2044Inhibit all warning messages.
2045
2046@item -Wno-import
2047@opindex Wno-import
2048Inhibit warning messages about the use of @samp{#import}.
2049
2050@item -Wchar-subscripts
2051@opindex Wchar-subscripts
2052Warn if an array subscript has type @code{char}. This is a common cause
2053of error, as programmers often forget that this type is signed on some
2054machines.
2055This warning is enabled by @option{-Wall}.
2056
2057@item -Wcomment
2058@opindex Wcomment
2059Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
2060comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
2061This warning is enabled by @option{-Wall}.
2062
2063@item -Wfatal-errors
2064@opindex Wfatal-errors
2065This option causes the compiler to abort compilation on the first error
2066occurred rather than trying to keep going and printing further error
2067messages.
2068
2069@item -Wformat
2070@opindex Wformat
2071@opindex ffreestanding
2072@opindex fno-builtin
2073Check calls to @code{printf} and @code{scanf}, etc., to make sure that
2074the arguments supplied have types appropriate to the format string
2075specified, and that the conversions specified in the format string make
2076sense. This includes standard functions, and others specified by format
2077attributes (@pxref{Function Attributes}), in the @code{printf},
2078@code{scanf}, @code{strftime} and @code{strfmon} (an X/Open extension,
2079not in the C standard) families (or other target-specific families).
2080Which functions are checked without format attributes having been
2081specified depends on the standard version selected, and such checks of
2082functions without the attribute specified are disabled by
2083@option{-ffreestanding} or @option{-fno-builtin}.
2084
2085The formats are checked against the format features supported by GNU
2086libc version 2.2. These include all ISO C90 and C99 features, as well
2087as features from the Single Unix Specification and some BSD and GNU
2088extensions. Other library implementations may not support all these
2089features; GCC does not support warning about features that go beyond a
2090particular library's limitations. However, if @option{-pedantic} is used
2091with @option{-Wformat}, warnings will be given about format features not
2092in the selected standard version (but not for @code{strfmon} formats,
2093since those are not in any version of the C standard). @xref{C Dialect
2094Options,,Options Controlling C Dialect}.
2095
2096Since @option{-Wformat} also checks for null format arguments for
2097several functions, @option{-Wformat} also implies @option{-Wnonnull}.
2098
2099@option{-Wformat} is included in @option{-Wall}. For more control over some
2100aspects of format checking, the options @option{-Wformat-y2k},
2101@option{-Wno-format-extra-args}, @option{-Wno-format-zero-length},
2102@option{-Wformat-nonliteral}, @option{-Wformat-security}, and
2103@option{-Wformat=2} are available, but are not included in @option{-Wall}.
2104
2105@item -Wformat-y2k
2106@opindex Wformat-y2k
2107If @option{-Wformat} is specified, also warn about @code{strftime}
2108formats which may yield only a two-digit year.
2109
2110@item -Wno-format-extra-args
2111@opindex Wno-format-extra-args
2112If @option{-Wformat} is specified, do not warn about excess arguments to a
2113@code{printf} or @code{scanf} format function. The C standard specifies
2114that such arguments are ignored.
2115
2116Where the unused arguments lie between used arguments that are
2117specified with @samp{$} operand number specifications, normally
2118warnings are still given, since the implementation could not know what
2119type to pass to @code{va_arg} to skip the unused arguments. However,
2120in the case of @code{scanf} formats, this option will suppress the
2121warning if the unused arguments are all pointers, since the Single
2122Unix Specification says that such unused arguments are allowed.
2123
2124@item -Wno-format-zero-length
2125@opindex Wno-format-zero-length
2126If @option{-Wformat} is specified, do not warn about zero-length formats.
2127The C standard specifies that zero-length formats are allowed.
2128
2129@item -Wformat-nonliteral
2130@opindex Wformat-nonliteral
2131If @option{-Wformat} is specified, also warn if the format string is not a
2132string literal and so cannot be checked, unless the format function
2133takes its format arguments as a @code{va_list}.
2134
2135@item -Wformat-security
2136@opindex Wformat-security
2137If @option{-Wformat} is specified, also warn about uses of format
2138functions that represent possible security problems. At present, this
2139warns about calls to @code{printf} and @code{scanf} functions where the
2140format string is not a string literal and there are no format arguments,
2141as in @code{printf (foo);}. This may be a security hole if the format
2142string came from untrusted input and contains @samp{%n}. (This is
2143currently a subset of what @option{-Wformat-nonliteral} warns about, but
2144in future warnings may be added to @option{-Wformat-security} that are not
2145included in @option{-Wformat-nonliteral}.)
2146
2147@item -Wformat=2
2148@opindex Wformat=2
2149Enable @option{-Wformat} plus format checks not included in
2150@option{-Wformat}. Currently equivalent to @samp{-Wformat
2151-Wformat-nonliteral -Wformat-security -Wformat-y2k}.
2152
2153@item -Wnonnull
2154@opindex Wnonnull
2155Warn about passing a null pointer for arguments marked as
2156requiring a non-null value by the @code{nonnull} function attribute.
2157
2158@option{-Wnonnull} is included in @option{-Wall} and @option{-Wformat}. It
2159can be disabled with the @option{-Wno-nonnull} option.
2160
2161@item -Winit-self @r{(C and C++ only)}
2162@opindex Winit-self
2163Warn about uninitialized variables which are initialized with themselves.
2164Note this option can only be used with the @option{-Wuninitialized} option,
2165which in turn only works with @option{-O1} and above.
2166
2167For example, GCC will warn about @code{i} being uninitialized in the
2168following snippet only when @option{-Winit-self} has been specified:
2169@smallexample
2170@group
2171int f()
2172@{
2173 int i = i;
2174 return i;
2175@}
2176@end group
2177@end smallexample
2178
2179@item -Wimplicit-int
2180@opindex Wimplicit-int
2181Warn when a declaration does not specify a type.
2182This warning is enabled by @option{-Wall}.
2183
2184@item -Wimplicit-function-declaration
2185@itemx -Werror-implicit-function-declaration
2186@opindex Wimplicit-function-declaration
2187@opindex Werror-implicit-function-declaration
2188Give a warning (or error) whenever a function is used before being
2189declared. The form @option{-Wno-error-implicit-function-declaration}
2190is not supported.
2191This warning is enabled by @option{-Wall} (as a warning, not an error).
2192
2193@item -Wimplicit
2194@opindex Wimplicit
2195Same as @option{-Wimplicit-int} and @option{-Wimplicit-function-declaration}.
2196This warning is enabled by @option{-Wall}.
2197
2198@item -Wmain
2199@opindex Wmain
2200Warn if the type of @samp{main} is suspicious. @samp{main} should be a
2201function with external linkage, returning int, taking either zero
2202arguments, two, or three arguments of appropriate types.
2203This warning is enabled by @option{-Wall}.
2204
2205@item -Wmissing-braces
2206@opindex Wmissing-braces
2207Warn if an aggregate or union initializer is not fully bracketed. In
2208the following example, the initializer for @samp{a} is not fully
2209bracketed, but that for @samp{b} is fully bracketed.
2210
2211@smallexample
2212int a[2][2] = @{ 0, 1, 2, 3 @};
2213int b[2][2] = @{ @{ 0, 1 @}, @{ 2, 3 @} @};
2214@end smallexample
2215
2216This warning is enabled by @option{-Wall}.
2217
2218@item -Wmissing-include-dirs @r{(C and C++ only)}
2219@opindex Wmissing-include-dirs
2220Warn if a user-supplied include directory does not exist.
2221
2222@item -Wparentheses
2223@opindex Wparentheses
2224Warn if parentheses are omitted in certain contexts, such
2225as when there is an assignment in a context where a truth value
2226is expected, or when operators are nested whose precedence people
2227often get confused about.
2228
2229Also warn if a comparison like @samp{x<=y<=z} appears; this is
2230equivalent to @samp{(x<=y ? 1 : 0) <= z}, which is a different
2231interpretation from that of ordinary mathematical notation.
2232
2233Also warn about constructions where there may be confusion to which
2234@code{if} statement an @code{else} branch belongs. Here is an example of
2235such a case:
2236
2237@smallexample
2238@group
2239@{
2240 if (a)
2241 if (b)
2242 foo ();
2243 else
2244 bar ();
2245@}
2246@end group
2247@end smallexample
2248
2249In C/C++, every @code{else} branch belongs to the innermost possible
2250@code{if} statement, which in this example is @code{if (b)}. This is
2251often not what the programmer expected, as illustrated in the above
2252example by indentation the programmer chose. When there is the
2253potential for this confusion, GCC will issue a warning when this flag
2254is specified. To eliminate the warning, add explicit braces around
2255the innermost @code{if} statement so there is no way the @code{else}
2256could belong to the enclosing @code{if}. The resulting code would
2257look like this:
2258
2259@smallexample
2260@group
2261@{
2262 if (a)
2263 @{
2264 if (b)
2265 foo ();
2266 else
2267 bar ();
2268 @}
2269@}
2270@end group
2271@end smallexample
2272
2273This warning is enabled by @option{-Wall}.
2274
2275@item -Wsequence-point
2276@opindex Wsequence-point
2277Warn about code that may have undefined semantics because of violations
2278of sequence point rules in the C and C++ standards.
2279
2280The C and C++ standards defines the order in which expressions in a C/C++
2281program are evaluated in terms of @dfn{sequence points}, which represent
2282a partial ordering between the execution of parts of the program: those
2283executed before the sequence point, and those executed after it. These
2284occur after the evaluation of a full expression (one which is not part
2285of a larger expression), after the evaluation of the first operand of a
2286@code{&&}, @code{||}, @code{? :} or @code{,} (comma) operator, before a
2287function is called (but after the evaluation of its arguments and the
2288expression denoting the called function), and in certain other places.
2289Other than as expressed by the sequence point rules, the order of
2290evaluation of subexpressions of an expression is not specified. All
2291these rules describe only a partial order rather than a total order,
2292since, for example, if two functions are called within one expression
2293with no sequence point between them, the order in which the functions
2294are called is not specified. However, the standards committee have
2295ruled that function calls do not overlap.
2296
2297It is not specified when between sequence points modifications to the
2298values of objects take effect. Programs whose behavior depends on this
2299have undefined behavior; the C and C++ standards specify that ``Between
2300the previous and next sequence point an object shall have its stored
2301value modified at most once by the evaluation of an expression.
2302Furthermore, the prior value shall be read only to determine the value
2303to be stored.''. If a program breaks these rules, the results on any
2304particular implementation are entirely unpredictable.
2305
2306Examples of code with undefined behavior are @code{a = a++;}, @code{a[n]
2307= b[n++]} and @code{a[i++] = i;}. Some more complicated cases are not
2308diagnosed by this option, and it may give an occasional false positive
2309result, but in general it has been found fairly effective at detecting
2310this sort of problem in programs.
2311
2312The standard is worded confusingly, therefore there is some debate
2313over the precise meaning of the sequence point rules in subtle cases.
2314Links to discussions of the problem, including proposed formal
2315definitions, may be found on the GCC readings page, at
2316@w{@uref{http://gcc.gnu.org/readings.html}}.
2317
2318This warning is enabled by @option{-Wall} for C and C++.
2319
2320@item -Wreturn-type
2321@opindex Wreturn-type
2322Warn whenever a function is defined with a return-type that defaults to
2323@code{int}. Also warn about any @code{return} statement with no
2324return-value in a function whose return-type is not @code{void}.
2325
2326For C, also warn if the return type of a function has a type qualifier
2327such as @code{const}. Such a type qualifier has no effect, since the
2328value returned by a function is not an lvalue. ISO C prohibits
2329qualified @code{void} return types on function definitions, so such
2330return types always receive a warning even without this option.
2331
2332For C++, a function without return type always produces a diagnostic
2333message, even when @option{-Wno-return-type} is specified. The only
2334exceptions are @samp{main} and functions defined in system headers.
2335
2336This warning is enabled by @option{-Wall}.
2337
2338@item -Wswitch
2339@opindex Wswitch
2340Warn whenever a @code{switch} statement has an index of enumerated type
2341and lacks a @code{case} for one or more of the named codes of that
2342enumeration. (The presence of a @code{default} label prevents this
2343warning.) @code{case} labels outside the enumeration range also
2344provoke warnings when this option is used.
2345This warning is enabled by @option{-Wall}.
2346
2347@item -Wswitch-default
2348@opindex Wswitch-switch
2349Warn whenever a @code{switch} statement does not have a @code{default}
2350case.
2351
2352@item -Wswitch-enum
2353@opindex Wswitch-enum
2354Warn whenever a @code{switch} statement has an index of enumerated type
2355and lacks a @code{case} for one or more of the named codes of that
2356enumeration. @code{case} labels outside the enumeration range also
2357provoke warnings when this option is used.
2358
2359@item -Wtrigraphs
2360@opindex Wtrigraphs
2361Warn if any trigraphs are encountered that might change the meaning of
2362the program (trigraphs within comments are not warned about).
2363This warning is enabled by @option{-Wall}.
2364
2365@item -Wunused-function
2366@opindex Wunused-function
2367Warn whenever a static function is declared but not defined or a
2368non-inline static function is unused.
2369This warning is enabled by @option{-Wall}.
2370
2371@item -Wunused-label
2372@opindex Wunused-label
2373Warn whenever a label is declared but not used.
2374This warning is enabled by @option{-Wall}.
2375
2376To suppress this warning use the @samp{unused} attribute
2377(@pxref{Variable Attributes}).
2378
2379@item -Wunused-parameter
2380@opindex Wunused-parameter
2381Warn whenever a function parameter is unused aside from its declaration.
2382
2383To suppress this warning use the @samp{unused} attribute
2384(@pxref{Variable Attributes}).
2385
2386@item -Wunused-variable
2387@opindex Wunused-variable
2388Warn whenever a local variable or non-constant static variable is unused
2389aside from its declaration.
2390This warning is enabled by @option{-Wall}.
2391
2392To suppress this warning use the @samp{unused} attribute
2393(@pxref{Variable Attributes}).
2394
2395@item -Wunused-value
2396@opindex Wunused-value
2397Warn whenever a statement computes a result that is explicitly not used.
2398This warning is enabled by @option{-Wall}.
2399
2400To suppress this warning cast the expression to @samp{void}.
2401
2402@item -Wunused
2403@opindex Wunused
2404All the above @option{-Wunused} options combined.
2405
2406In order to get a warning about an unused function parameter, you must
2407either specify @samp{-Wextra -Wunused} (note that @samp{-Wall} implies
2408@samp{-Wunused}), or separately specify @option{-Wunused-parameter}.
2409
2410@item -Wuninitialized
2411@opindex Wuninitialized
2412Warn if an automatic variable is used without first being initialized or
2413if a variable may be clobbered by a @code{setjmp} call.
2414
2415These warnings are possible only in optimizing compilation,
2416because they require data flow information that is computed only
2417when optimizing. If you do not specify @option{-O}, you will not get
2418these warnings. Instead, GCC will issue a warning about @option{-Wuninitialized}
2419requiring @option{-O}.
2420
2421If you want to warn about code which uses the uninitialized value of the
2422variable in its own initializer, use the @option{-Winit-self} option.
2423
2424These warnings occur for individual uninitialized or clobbered
2425elements of structure, union or array variables as well as for
2426variables which are uninitialized or clobbered as a whole. They do
2427not occur for variables or elements declared @code{volatile}. Because
2428these warnings depend on optimization, the exact variables or elements
2429for which there are warnings will depend on the precise optimization
2430options and version of GCC used.
2431
2432Note that there may be no warning about a variable that is used only
2433to compute a value that itself is never used, because such
2434computations may be deleted by data flow analysis before the warnings
2435are printed.
2436
2437These warnings are made optional because GCC is not smart
2438enough to see all the reasons why the code might be correct
2439despite appearing to have an error. Here is one example of how
2440this can happen:
2441
2442@smallexample
2443@group
2444@{
2445 int x;
2446 switch (y)
2447 @{
2448 case 1: x = 1;
2449 break;
2450 case 2: x = 4;
2451 break;
2452 case 3: x = 5;
2453 @}
2454 foo (x);
2455@}
2456@end group
2457@end smallexample
2458
2459@noindent
2460If the value of @code{y} is always 1, 2 or 3, then @code{x} is
2461always initialized, but GCC doesn't know this. Here is
2462another common case:
2463
2464@smallexample
2465@{
2466 int save_y;
2467 if (change_y) save_y = y, y = new_y;
2468 @dots{}
2469 if (change_y) y = save_y;
2470@}
2471@end smallexample
2472
2473@noindent
2474This has no bug because @code{save_y} is used only if it is set.
2475
2476@cindex @code{longjmp} warnings
2477This option also warns when a non-volatile automatic variable might be
2478changed by a call to @code{longjmp}. These warnings as well are possible
2479only in optimizing compilation.
2480
2481The compiler sees only the calls to @code{setjmp}. It cannot know
2482where @code{longjmp} will be called; in fact, a signal handler could
2483call it at any point in the code. As a result, you may get a warning
2484even when there is in fact no problem because @code{longjmp} cannot
2485in fact be called at the place which would cause a problem.
2486
2487Some spurious warnings can be avoided if you declare all the functions
2488you use that never return as @code{noreturn}. @xref{Function
2489Attributes}.
2490
2491This warning is enabled by @option{-Wall}.
2492
2493@item -Wunknown-pragmas
2494@opindex Wunknown-pragmas
2495@cindex warning for unknown pragmas
2496@cindex unknown pragmas, warning
2497@cindex pragmas, warning of unknown
2498Warn when a #pragma directive is encountered which is not understood by
2499GCC@. If this command line option is used, warnings will even be issued
2500for unknown pragmas in system header files. This is not the case if
2501the warnings were only enabled by the @option{-Wall} command line option.
2502
2503@item -Wno-pragmas
2504@opindex Wno-pragmas
2505@opindex Wpragmas
2506Do not warn about misuses of pragmas, such as incorrect parameters,
2507invalid syntax, or conflicts between pragmas. See also
2508@samp{-Wunknown-pragmas}.
2509
2510@item -Wstrict-aliasing
2511@opindex Wstrict-aliasing
2512This option is only active when @option{-fstrict-aliasing} is active.
2513It warns about code which might break the strict aliasing rules that the
2514compiler is using for optimization. The warning does not catch all
2515cases, but does attempt to catch the more common pitfalls. It is
2516included in @option{-Wall}.
2517It is equivalent to -Wstrict-aliasing=3
2518
2519@item -Wstrict-aliasing=n
2520@opindex Wstrict-aliasing=n
2521This option is only active when @option{-fstrict-aliasing} is active.
2522It warns about code which might break the strict aliasing rules that the
2523compiler is using for optimization.
2524Higher levels correspond to higher accuracy (fewer false positives).
2525Higher levels also correspond to more effort, similar to the way -O works.
2526@option{-Wstrict-aliasing} is equivalent to @option{-Wstrict-aliasing=n},
2527with n=3.
2528
2529Level 1: Most aggressive, quick, least accurate.
2530Possibly useful when higher levels
2531do not warn but -fstrict-aliasing still breaks the code, as it has very few
2532false negatives. However, it has many false positives.
2533Warns for all pointer conversions between possibly incompatible types,
2534even if never dereferenced. Runs in the frontend only.
2535
2536Level 2: Aggressive, quick, not too precise.
2537May still have many false positives (not as many as level 1 though),
2538and few false negatives (but possibly more than level 1).
2539Unlike level 1, it only warns when an address is taken. Warns about
2540incomplete types. Runs in the frontend only.
2541
2542Level 3 (default for @option{-Wstrict-aliasing}):
2543Should have very few false positives and few false
2544negatives. Slightly slower than levels 1 or 2 when optimization is enabled.
2545Takes care of the common punn+dereference pattern in the frontend:
2546@code{*(int*)&some_float}.
2547If optimization is enabled, it also runs in the backend, where it deals
2548with multiple statement cases using flow-sensitive points-to information.
2549Only warns when the converted pointer is dereferenced.
2550Does not warn about incomplete types.
2551
2552@item -Wstrict-overflow
2553@item -Wstrict-overflow=@var{n}
2554@opindex Wstrict-overflow
2555This option is only active when @option{-fstrict-overflow} is active.
2556It warns about cases where the compiler optimizes based on the
2557assumption that signed overflow does not occur. Note that it does not
2558warn about all cases where the code might overflow: it only warns
2559about cases where the compiler implements some optimization. Thus
2560this warning depends on the optimization level.
2561
2562An optimization which assumes that signed overflow does not occur is
2563perfectly safe if the values of the variables involved are such that
2564overflow never does, in fact, occur. Therefore this warning can
2565easily give a false positive: a warning about code which is not
2566actually a problem. To help focus on important issues, several
2567warning levels are defined. No warnings are issued for the use of
2568undefined signed overflow when estimating how many iterations a loop
2569will require, in particular when determining whether a loop will be
2570executed at all.
2571
2572@table @option
2573@item -Wstrict-overflow=1
2574Warn about cases which are both questionable and easy to avoid. For
2575example: @code{x + 1 > x}; with @option{-fstrict-overflow}, the
2576compiler will simplify this to @code{1}. This level of
2577@option{-Wstrict-overflow} is enabled by @option{-Wall}; higher levels
2578are not, and must be explicitly requested.
2579
2580@item -Wstrict-overflow=2
2581Also warn about other cases where a comparison is simplified to a
2582constant. For example: @code{abs (x) >= 0}. This can only be
2583simplified when @option{-fstrict-overflow} is in effect, because
2584@code{abs (INT_MIN)} overflows to @code{INT_MIN}, which is less than
2585zero. @option{-Wstrict-overflow} (with no level) is the same as
2586@option{-Wstrict-overflow=2}.
2587
2588@item -Wstrict-overflow=3
2589Also warn about other cases where a comparison is simplified. For
2590example: @code{x + 1 > 1} will be simplified to @code{x > 0}.
2591
2592@item -Wstrict-overflow=4
2593Also warn about other simplifications not covered by the above cases.
2594For example: @code{(x * 10) / 5} will be simplified to @code{x * 2}.
2595
2596@item -Wstrict-overflow=5
2597Also warn about cases where the compiler reduces the magnitude of a
2598constant involved in a comparison. For example: @code{x + 2 > y} will
2599be simplified to @code{x + 1 >= y}. This is reported only at the
2600highest warning level because this simplification applies to many
2601comparisons, so this warning level will give a very large number of
2602false positives.
2603@end table
2604
2605@item -Wall
2606@opindex Wall
2607All of the above @samp{-W} options combined. This enables all the
2608warnings about constructions that some users consider questionable, and
2609that are easy to avoid (or modify to prevent the warning), even in
2610conjunction with macros. This also enables some language-specific
2611warnings described in @ref{C++ Dialect Options}.
2612@end table
2613
2614The following @option{-W@dots{}} options are not implied by @option{-Wall}.
2615Some of them warn about constructions that users generally do not
2616consider questionable, but which occasionally you might wish to check
2617for; others warn about constructions that are necessary or hard to avoid
2618in some cases, and there is no simple way to modify the code to suppress
2619the warning.
2620
2621@table @gcctabopt
2622@item -Wextra
2623@opindex W
2624@opindex Wextra
2625(This option used to be called @option{-W}. The older name is still
2626supported, but the newer name is more descriptive.) Print extra warning
2627messages for these events:
2628
2629@itemize @bullet
2630@item
2631A function can return either with or without a value. (Falling
2632off the end of the function body is considered returning without
2633a value.) For example, this function would evoke such a
2634warning:
2635
2636@smallexample
2637@group
2638foo (a)
2639@{
2640 if (a > 0)
2641 return a;
2642@}
2643@end group
2644@end smallexample
2645
2646@item
2647An expression-statement or the left-hand side of a comma expression
2648contains no side effects.
2649To suppress the warning, cast the unused expression to void.
2650For example, an expression such as @samp{x[i,j]} will cause a warning,
2651but @samp{x[(void)i,j]} will not.
2652
2653@item
2654An unsigned value is compared against zero with @samp{<} or @samp{>=}.
2655
2656@item
2657Storage-class specifiers like @code{static} are not the first things in
2658a declaration. According to the C Standard, this usage is obsolescent.
2659
2660@item
2661If @option{-Wall} or @option{-Wunused} is also specified, warn about unused
2662arguments.
2663
2664@item
2665A comparison between signed and unsigned values could produce an
2666incorrect result when the signed value is converted to unsigned.
2667(But don't warn if @option{-Wno-sign-compare} is also specified.)
2668
2669@item
2670An aggregate has an initializer which does not initialize all members.
2671This warning can be independently controlled by
2672@option{-Wmissing-field-initializers}.
2673
2674@item
2675An initialized field without side effects is overridden when using
2676designated initializers (@pxref{Designated Inits, , Designated
2677Initializers}). This warning can be independently controlled by
2678@option{-Woverride-init}.
2679
2680@item
2681A function parameter is declared without a type specifier in K&R-style
2682functions:
2683
2684@smallexample
2685void foo(bar) @{ @}
2686@end smallexample
2687
2688@item
2689An empty body occurs in an @samp{if} or @samp{else} statement.
2690
2691@item
2692A pointer is compared against integer zero with @samp{<}, @samp{<=},
2693@samp{>}, or @samp{>=}.
2694
2695@item
2696A variable might be changed by @samp{longjmp} or @samp{vfork}.
2697
2698@item @r{(C++ only)}
2699An enumerator and a non-enumerator both appear in a conditional expression.
2700
2701@item @r{(C++ only)}
2702A non-static reference or non-static @samp{const} member appears in a
2703class without constructors.
2704
2705@item @r{(C++ only)}
2706Ambiguous virtual bases.
2707
2708@item @r{(C++ only)}
2709Subscripting an array which has been declared @samp{register}.
2710
2711@item @r{(C++ only)}
2712Taking the address of a variable which has been declared @samp{register}.
2713
2714@item @r{(C++ only)}
2715A base class is not initialized in a derived class' copy constructor.
2716@end itemize
2717
2718@item -Wno-div-by-zero
2719@opindex Wno-div-by-zero
2720@opindex Wdiv-by-zero
2721Do not warn about compile-time integer division by zero. Floating point
2722division by zero is not warned about, as it can be a legitimate way of
2723obtaining infinities and NaNs.
2724
2725@item -Wsystem-headers
2726@opindex Wsystem-headers
2727@cindex warnings from system headers
2728@cindex system headers, warnings from
2729Print warning messages for constructs found in system header files.
2730Warnings from system headers are normally suppressed, on the assumption
2731that they usually do not indicate real problems and would only make the
2732compiler output harder to read. Using this command line option tells
2733GCC to emit warnings from system headers as if they occurred in user
2734code. However, note that using @option{-Wall} in conjunction with this
2735option will @emph{not} warn about unknown pragmas in system
2736headers---for that, @option{-Wunknown-pragmas} must also be used.
2737
2738@item -Wfloat-equal
2739@opindex Wfloat-equal
2740Warn if floating point values are used in equality comparisons.
2741
2742The idea behind this is that sometimes it is convenient (for the
2743programmer) to consider floating-point values as approximations to
2744infinitely precise real numbers. If you are doing this, then you need
2745to compute (by analyzing the code, or in some other way) the maximum or
2746likely maximum error that the computation introduces, and allow for it
2747when performing comparisons (and when producing output, but that's a
2748different problem). In particular, instead of testing for equality, you
2749would check to see whether the two values have ranges that overlap; and
2750this is done with the relational operators, so equality comparisons are
2751probably mistaken.
2752
2753@item -Wtraditional @r{(C only)}
2754@opindex Wtraditional
2755Warn about certain constructs that behave differently in traditional and
2756ISO C@. Also warn about ISO C constructs that have no traditional C
2757equivalent, and/or problematic constructs which should be avoided.
2758
2759@itemize @bullet
2760@item
2761Macro parameters that appear within string literals in the macro body.
2762In traditional C macro replacement takes place within string literals,
2763but does not in ISO C@.
2764
2765@item
2766In traditional C, some preprocessor directives did not exist.
2767Traditional preprocessors would only consider a line to be a directive
2768if the @samp{#} appeared in column 1 on the line. Therefore
2769@option{-Wtraditional} warns about directives that traditional C
2770understands but would ignore because the @samp{#} does not appear as the
2771first character on the line. It also suggests you hide directives like
2772@samp{#pragma} not understood by traditional C by indenting them. Some
2773traditional implementations would not recognize @samp{#elif}, so it
2774suggests avoiding it altogether.
2775
2776@item
2777A function-like macro that appears without arguments.
2778
2779@item
2780The unary plus operator.
2781
2782@item
2783The @samp{U} integer constant suffix, or the @samp{F} or @samp{L} floating point
2784constant suffixes. (Traditional C does support the @samp{L} suffix on integer
2785constants.) Note, these suffixes appear in macros defined in the system
2786headers of most modern systems, e.g.@: the @samp{_MIN}/@samp{_MAX} macros in @code{<limits.h>}.
2787Use of these macros in user code might normally lead to spurious
2788warnings, however GCC's integrated preprocessor has enough context to
2789avoid warning in these cases.
2790
2791@item
2792A function declared external in one block and then used after the end of
2793the block.
2794
2795@item
2796A @code{switch} statement has an operand of type @code{long}.
2797
2798@item
2799A non-@code{static} function declaration follows a @code{static} one.
2800This construct is not accepted by some traditional C compilers.
2801
2802@item
2803The ISO type of an integer constant has a different width or
2804signedness from its traditional type. This warning is only issued if
2805the base of the constant is ten. I.e.@: hexadecimal or octal values, which
2806typically represent bit patterns, are not warned about.
2807
2808@item
2809Usage of ISO string concatenation is detected.
2810
2811@item
2812Initialization of automatic aggregates.
2813
2814@item
2815Identifier conflicts with labels. Traditional C lacks a separate
2816namespace for labels.
2817
2818@item
2819Initialization of unions. If the initializer is zero, the warning is
2820omitted. This is done under the assumption that the zero initializer in
2821user code appears conditioned on e.g.@: @code{__STDC__} to avoid missing
2822initializer warnings and relies on default initialization to zero in the
2823traditional C case.
2824
2825@item
2826Conversions by prototypes between fixed/floating point values and vice
2827versa. The absence of these prototypes when compiling with traditional
2828C would cause serious problems. This is a subset of the possible
2829conversion warnings, for the full set use @option{-Wconversion}.
2830
2831@item
2832Use of ISO C style function definitions. This warning intentionally is
2833@emph{not} issued for prototype declarations or variadic functions
2834because these ISO C features will appear in your code when using
2835libiberty's traditional C compatibility macros, @code{PARAMS} and
2836@code{VPARAMS}. This warning is also bypassed for nested functions
2837because that feature is already a GCC extension and thus not relevant to
2838traditional C compatibility.
2839@end itemize
2840
2841@item -Wdeclaration-after-statement @r{(C only)}
2842@opindex Wdeclaration-after-statement
2843Warn when a declaration is found after a statement in a block. This
2844construct, known from C++, was introduced with ISO C99 and is by default
2845allowed in GCC@. It is not supported by ISO C90 and was not supported by
2846GCC versions before GCC 3.0. @xref{Mixed Declarations}.
2847
2848@item -Wundef
2849@opindex Wundef
2850Warn if an undefined identifier is evaluated in an @samp{#if} directive.
2851
2852@item -Wno-endif-labels
2853@opindex Wno-endif-labels
2854@opindex Wendif-labels
2855Do not warn whenever an @samp{#else} or an @samp{#endif} are followed by text.
2856
2857@item -Wshadow
2858@opindex Wshadow
2859Warn whenever a local variable shadows another local variable, parameter or
2860global variable or whenever a built-in function is shadowed.
2861
2862@item -Wlarger-than-@var{len}
2863@opindex Wlarger-than
2864Warn whenever an object of larger than @var{len} bytes is defined.
2865
2866@item -Wframe-larger-than-@var{len}
2867@opindex Wframe-larger-than
2868Warn whenever the frame size of a function is larger than @var{len} bytes.
2869
2870@item -Wunsafe-loop-optimizations
2871@opindex Wunsafe-loop-optimizations
2872Warn if the loop cannot be optimized because the compiler could not
2873assume anything on the bounds of the loop indices. With
2874@option{-funsafe-loop-optimizations} warn if the compiler made
2875such assumptions.
2876
2877@item -Wpointer-arith
2878@opindex Wpointer-arith
2879Warn about anything that depends on the ``size of'' a function type or
2880of @code{void}. GNU C assigns these types a size of 1, for
2881convenience in calculations with @code{void *} pointers and pointers
2882to functions.
2883
2884@item -Wbad-function-cast @r{(C only)}
2885@opindex Wbad-function-cast
2886Warn whenever a function call is cast to a non-matching type.
2887For example, warn if @code{int malloc()} is cast to @code{anything *}.
2888
2889@item -Wc++-compat
2890Warn about ISO C constructs that are outside of the common subset of
2891ISO C and ISO C++, e.g.@: request for implicit conversion from
2892@code{void *} to a pointer to non-@code{void} type.
2893
2894@item -Wcast-qual
2895@opindex Wcast-qual
2896Warn whenever a pointer is cast so as to remove a type qualifier from
2897the target type. For example, warn if a @code{const char *} is cast
2898to an ordinary @code{char *}.
2899
2900@item -Wcast-align
2901@opindex Wcast-align
2902Warn whenever a pointer is cast such that the required alignment of the
2903target is increased. For example, warn if a @code{char *} is cast to
2904an @code{int *} on machines where integers can only be accessed at
2905two- or four-byte boundaries.
2906
2907@item -Wwrite-strings
2908@opindex Wwrite-strings
2909When compiling C, give string constants the type @code{const
2910char[@var{length}]} so that
2911copying the address of one into a non-@code{const} @code{char *}
2912pointer will get a warning; when compiling C++, warn about the
2913deprecated conversion from string literals to @code{char *}. This
2914warning, by default, is enabled for C++ programs.
2915These warnings will help you find at
2916compile time code that can try to write into a string constant, but
2917only if you have been very careful about using @code{const} in
2918declarations and prototypes. Otherwise, it will just be a nuisance;
2919this is why we did not make @option{-Wall} request these warnings.
2920
2921@item -Wconversion
2922@opindex Wconversion
2923Warn if a prototype causes a type conversion that is different from what
2924would happen to the same argument in the absence of a prototype. This
2925includes conversions of fixed point to floating and vice versa, and
2926conversions changing the width or signedness of a fixed point argument
2927except when the same as the default promotion.
2928
2929Also, warn if a negative integer constant expression is implicitly
2930converted to an unsigned type. For example, warn about the assignment
2931@code{x = -1} if @code{x} is unsigned. But do not warn about explicit
2932casts like @code{(unsigned) -1}.
2933
2934@item -Wsign-compare
2935@opindex Wsign-compare
2936@cindex warning for comparison of signed and unsigned values
2937@cindex comparison of signed and unsigned values, warning
2938@cindex signed and unsigned values, comparison warning
2939Warn when a comparison between signed and unsigned values could produce
2940an incorrect result when the signed value is converted to unsigned.
2941This warning is also enabled by @option{-Wextra}; to get the other warnings
2942of @option{-Wextra} without this warning, use @samp{-Wextra -Wno-sign-compare}.
2943
2944@item -Waddress
2945@opindex Waddress
2946@opindex Wno-address
2947Warn about suspicious uses of memory addresses. These include using
2948the address of a function in a conditional expression, such as
2949@code{void func(void); if (func)}, and comparisons against the memory
2950address of a string literal, such as @code{if (x == "abc")}. Such
2951uses typically indicate a programmer error: the address of a function
2952always evaluates to true, so their use in a conditional usually
2953indicate that the programmer forgot the parentheses in a function
2954call; and comparisons against string literals result in unspecified
2955behavior and are not portable in C, so they usually indicate that the
2956programmer intended to use @code{strcmp}. This warning is enabled by
2957@option{-Wall}.
2958
2959@item -Waggregate-return
2960@opindex Waggregate-return
2961Warn if any functions that return structures or unions are defined or
2962called. (In languages where you can return an array, this also elicits
2963a warning.)
2964
2965@item -Wno-attributes
2966@opindex Wno-attributes
2967@opindex Wattributes
2968Do not warn if an unexpected @code{__attribute__} is used, such as
2969unrecognized attributes, function attributes applied to variables,
2970etc. This will not stop errors for incorrect use of supported
2971attributes.
2972
2973@item -Wstrict-prototypes @r{(C only)}
2974@opindex Wstrict-prototypes
2975Warn if a function is declared or defined without specifying the
2976argument types. (An old-style function definition is permitted without
2977a warning if preceded by a declaration which specifies the argument
2978types.)
2979
2980@item -Wold-style-definition @r{(C only)}
2981@opindex Wold-style-definition
2982Warn if an old-style function definition is used. A warning is given
2983even if there is a previous prototype.
2984
2985@item -Wmissing-prototypes @r{(C only)}
2986@opindex Wmissing-prototypes
2987Warn if a global function is defined without a previous prototype
2988declaration. This warning is issued even if the definition itself
2989provides a prototype. The aim is to detect global functions that fail
2990to be declared in header files.
2991
2992@item -Wmissing-declarations @r{(C only)}
2993@opindex Wmissing-declarations
2994Warn if a global function is defined without a previous declaration.
2995Do so even if the definition itself provides a prototype.
2996Use this option to detect global functions that are not declared in
2997header files.
2998
2999@item -Wmissing-field-initializers
3000@opindex Wmissing-field-initializers
3001@opindex W
3002@opindex Wextra
3003Warn if a structure's initializer has some fields missing. For
3004example, the following code would cause such a warning, because
3005@code{x.h} is implicitly zero:
3006
3007@smallexample
3008struct s @{ int f, g, h; @};
3009struct s x = @{ 3, 4 @};
3010@end smallexample
3011
3012This option does not warn about designated initializers, so the following
3013modification would not trigger a warning:
3014
3015@smallexample
3016struct s @{ int f, g, h; @};
3017struct s x = @{ .f = 3, .g = 4 @};
3018@end smallexample
3019
3020This warning is included in @option{-Wextra}. To get other @option{-Wextra}
3021warnings without this one, use @samp{-Wextra -Wno-missing-field-initializers}.
3022
3023@item -Wmissing-noreturn
3024@opindex Wmissing-noreturn
3025Warn about functions which might be candidates for attribute @code{noreturn}.
3026Note these are only possible candidates, not absolute ones. Care should
3027be taken to manually verify functions actually do not ever return before
3028adding the @code{noreturn} attribute, otherwise subtle code generation
3029bugs could be introduced. You will not get a warning for @code{main} in
3030hosted C environments.
3031
3032@item -Wmissing-format-attribute
3033@opindex Wmissing-format-attribute
3034@opindex Wformat
3035Warn about function pointers which might be candidates for @code{format}
3036attributes. Note these are only possible candidates, not absolute ones.
3037GCC will guess that function pointers with @code{format} attributes that
3038are used in assignment, initialization, parameter passing or return
3039statements should have a corresponding @code{format} attribute in the
3040resulting type. I.e.@: the left-hand side of the assignment or
3041initialization, the type of the parameter variable, or the return type
3042of the containing function respectively should also have a @code{format}
3043attribute to avoid the warning.
3044
3045GCC will also warn about function definitions which might be
3046candidates for @code{format} attributes. Again, these are only
3047possible candidates. GCC will guess that @code{format} attributes
3048might be appropriate for any function that calls a function like
3049@code{vprintf} or @code{vscanf}, but this might not always be the
3050case, and some functions for which @code{format} attributes are
3051appropriate may not be detected.
3052
3053@item -Wno-multichar
3054@opindex Wno-multichar
3055@opindex Wmultichar
3056Do not warn if a multicharacter constant (@samp{'FOOF'}) is used.
3057Usually they indicate a typo in the user's code, as they have
3058implementation-defined values, and should not be used in portable code.
3059
3060@item -Wnormalized=<none|id|nfc|nfkc>
3061@opindex Wnormalized
3062@cindex NFC
3063@cindex NFKC
3064@cindex character set, input normalization
3065In ISO C and ISO C++, two identifiers are different if they are
3066different sequences of characters. However, sometimes when characters
3067outside the basic ASCII character set are used, you can have two
3068different character sequences that look the same. To avoid confusion,
3069the ISO 10646 standard sets out some @dfn{normalization rules} which
3070when applied ensure that two sequences that look the same are turned into
3071the same sequence. GCC can warn you if you are using identifiers which
3072have not been normalized; this option controls that warning.
3073
3074There are four levels of warning that GCC supports. The default is
3075@option{-Wnormalized=nfc}, which warns about any identifier which is
3076not in the ISO 10646 ``C'' normalized form, @dfn{NFC}. NFC is the
3077recommended form for most uses.
3078
3079Unfortunately, there are some characters which ISO C and ISO C++ allow
3080in identifiers that when turned into NFC aren't allowable as
3081identifiers. That is, there's no way to use these symbols in portable
3082ISO C or C++ and have all your identifiers in NFC.
3083@option{-Wnormalized=id} suppresses the warning for these characters.
3084It is hoped that future versions of the standards involved will correct
3085this, which is why this option is not the default.
3086
3087You can switch the warning off for all characters by writing
3088@option{-Wnormalized=none}. You would only want to do this if you
3089were using some other normalization scheme (like ``D''), because
3090otherwise you can easily create bugs that are literally impossible to see.
3091
3092Some characters in ISO 10646 have distinct meanings but look identical
3093in some fonts or display methodologies, especially once formatting has
3094been applied. For instance @code{\u207F}, ``SUPERSCRIPT LATIN SMALL
3095LETTER N'', will display just like a regular @code{n} which has been
3096placed in a superscript. ISO 10646 defines the @dfn{NFKC}
3097normalization scheme to convert all these into a standard form as
3098well, and GCC will warn if your code is not in NFKC if you use
3099@option{-Wnormalized=nfkc}. This warning is comparable to warning
3100about every identifier that contains the letter O because it might be
3101confused with the digit 0, and so is not the default, but may be
3102useful as a local coding convention if the programming environment is
3103unable to be fixed to display these characters distinctly.
3104
3105@item -Wno-deprecated-declarations
3106@opindex Wno-deprecated-declarations
3107Do not warn about uses of functions (@pxref{Function Attributes}),
3108variables (@pxref{Variable Attributes}), and types (@pxref{Type
3109Attributes}) marked as deprecated by using the @code{deprecated}
3110attribute.
3111
3112@item -Wno-overflow
3113@opindex Wno-overflow
3114Do not warn about compile-time overflow in constant expressions.
3115
3116@item -Woverride-init
3117@opindex Woverride-init
3118@opindex W
3119@opindex Wextra
3120Warn if an initialized field without side effects is overridden when
3121using designated initializers (@pxref{Designated Inits, , Designated
3122Initializers}).
3123
3124This warning is included in @option{-Wextra}. To get other
3125@option{-Wextra} warnings without this one, use @samp{-Wextra
3126-Wno-override-init}.
3127
3128@item -Wpacked
3129@opindex Wpacked
3130Warn if a structure is given the packed attribute, but the packed
3131attribute has no effect on the layout or size of the structure.
3132Such structures may be mis-aligned for little benefit. For
3133instance, in this code, the variable @code{f.x} in @code{struct bar}
3134will be misaligned even though @code{struct bar} does not itself
3135have the packed attribute:
3136
3137@smallexample
3138@group
3139struct foo @{
3140 int x;
3141 char a, b, c, d;
3142@} __attribute__((packed));
3143struct bar @{
3144 char z;
3145 struct foo f;
3146@};
3147@end group
3148@end smallexample
3149
3150@item -Wpadded
3151@opindex Wpadded
3152Warn if padding is included in a structure, either to align an element
3153of the structure or to align the whole structure. Sometimes when this
3154happens it is possible to rearrange the fields of the structure to
3155reduce the padding and so make the structure smaller.
3156
3157@item -Wredundant-decls
3158@opindex Wredundant-decls
3159Warn if anything is declared more than once in the same scope, even in
3160cases where multiple declaration is valid and changes nothing.
3161
3162@item -Wnested-externs @r{(C only)}
3163@opindex Wnested-externs
3164Warn if an @code{extern} declaration is encountered within a function.
3165
3166@item -Wunreachable-code
3167@opindex Wunreachable-code
3168Warn if the compiler detects that code will never be executed.
3169
3170This option is intended to warn when the compiler detects that at
3171least a whole line of source code will never be executed, because
3172some condition is never satisfied or because it is after a
3173procedure that never returns.
3174
3175It is possible for this option to produce a warning even though there
3176are circumstances under which part of the affected line can be executed,
3177so care should be taken when removing apparently-unreachable code.
3178
3179For instance, when a function is inlined, a warning may mean that the
3180line is unreachable in only one inlined copy of the function.
3181
3182This option is not made part of @option{-Wall} because in a debugging
3183version of a program there is often substantial code which checks
3184correct functioning of the program and is, hopefully, unreachable
3185because the program does work. Another common use of unreachable
3186code is to provide behavior which is selectable at compile-time.
3187
3188@item -Winline
3189@opindex Winline
3190Warn if a function can not be inlined and it was declared as inline.
3191Even with this option, the compiler will not warn about failures to
3192inline functions declared in system headers.
3193
3194The compiler uses a variety of heuristics to determine whether or not
3195to inline a function. For example, the compiler takes into account
3196the size of the function being inlined and the amount of inlining
3197that has already been done in the current function. Therefore,
3198seemingly insignificant changes in the source program can cause the
3199warnings produced by @option{-Winline} to appear or disappear.
3200
3201@item -Wno-invalid-offsetof @r{(C++ only)}
3202@opindex Wno-invalid-offsetof
3203Suppress warnings from applying the @samp{offsetof} macro to a non-POD
3204type. According to the 1998 ISO C++ standard, applying @samp{offsetof}
3205to a non-POD type is undefined. In existing C++ implementations,
3206however, @samp{offsetof} typically gives meaningful results even when
3207applied to certain kinds of non-POD types. (Such as a simple
3208@samp{struct} that fails to be a POD type only by virtue of having a
3209constructor.) This flag is for users who are aware that they are
3210writing nonportable code and who have deliberately chosen to ignore the
3211warning about it.
3212
3213The restrictions on @samp{offsetof} may be relaxed in a future version
3214of the C++ standard.
3215
3216@item -Wno-int-to-pointer-cast @r{(C only)}
3217@opindex Wno-int-to-pointer-cast
3218Suppress warnings from casts to pointer type of an integer of a
3219different size.
3220
3221@item -Wno-pointer-to-int-cast @r{(C only)}
3222@opindex Wno-pointer-to-int-cast
3223Suppress warnings from casts from a pointer to an integer type of a
3224different size.
3225
3226@item -Winvalid-pch
3227@opindex Winvalid-pch
3228Warn if a precompiled header (@pxref{Precompiled Headers}) is found in
3229the search path but can't be used.
3230
3231@item -Wlong-long
3232@opindex Wlong-long
3233@opindex Wno-long-long
3234Warn if @samp{long long} type is used. This is default. To inhibit
3235the warning messages, use @option{-Wno-long-long}. Flags
3236@option{-Wlong-long} and @option{-Wno-long-long} are taken into account
3237only when @option{-pedantic} flag is used.
3238
3239@item -Wvariadic-macros
3240@opindex Wvariadic-macros
3241@opindex Wno-variadic-macros
3242Warn if variadic macros are used in pedantic ISO C90 mode, or the GNU
3243alternate syntax when in pedantic ISO C99 mode. This is default.
3244To inhibit the warning messages, use @option{-Wno-variadic-macros}.
3245
3246@item -Wvla
3247@opindex Wvla
3248@opindex Wno-vla
3249Warn if variable length array is used in the code.
3250@option{-Wno-vla} will prevent the @option{-pedantic} warning of
3251the variable length array.
3252
3253@item -Wvolatile-register-var
3254@opindex Wvolatile-register-var
3255@opindex Wno-volatile-register-var
3256Warn if a register variable is declared volatile. The volatile
3257modifier does not inhibit all optimizations that may eliminate reads
3258and/or writes to register variables.
3259
3260@item -Wdisabled-optimization
3261@opindex Wdisabled-optimization
3262Warn if a requested optimization pass is disabled. This warning does
3263not generally indicate that there is anything wrong with your code; it
3264merely indicates that GCC's optimizers were unable to handle the code
3265effectively. Often, the problem is that your code is too big or too
3266complex; GCC will refuse to optimize programs when the optimization
3267itself is likely to take inordinate amounts of time.
3268
3269@item -Wpointer-sign
3270@opindex Wpointer-sign
3271@opindex Wno-pointer-sign
3272Warn for pointer argument passing or assignment with different signedness.
3273This option is only supported for C. It is implied by @option{-Wall}
3274and by @option{-pedantic}, which can be disabled with
3275@option{-Wno-pointer-sign}.
3276
3277@item -Werror
3278@opindex Werror
3279Make all warnings into errors.
3280
3281@item -Werror=
3282@opindex Werror=
3283Make the specified warning into an errors. The specifier for a
3284warning is appended, for example @option{-Werror=switch} turns the
3285warnings controlled by @option{-Wswitch} into errors. This switch
3286takes a negative form, to be used to negate @option{-Werror} for
3287specific warnings, for example @option{-Wno-error=switch} makes
3288@option{-Wswitch} warnings not be errors, even when @option{-Werror}
3289is in effect. You can use the @option{-fdiagnostics-show-option}
3290option to have each controllable warning amended with the option which
3291controls it, to determine what to use with this option.
3292
3293Note that specifying @option{-Werror=}@var{foo} automatically implies
3294@option{-W}@var{foo}. However, @option{-Wno-error=}@var{foo} does not
3295imply anything.
3296
3297@item -Wstack-protector
3298@opindex Wstack-protector
3299This option is only active when @option{-fstack-protector} is active. It
3300warns about functions that will not be protected against stack smashing.
3301
3302@item -Woverlength-strings
3303@opindex Woverlength-strings
3304Warn about string constants which are longer than the ``minimum
3305maximum'' length specified in the C standard. Modern compilers
3306generally allow string constants which are much longer than the
3307standard's minimum limit, but very portable programs should avoid
3308using longer strings.
3309
3310The limit applies @emph{after} string constant concatenation, and does
3311not count the trailing NUL@. In C89, the limit was 509 characters; in
3312C99, it was raised to 4095. C++98 does not specify a normative
3313minimum maximum, so we do not diagnose overlength strings in C++@.
3314
3315This option is implied by @option{-pedantic}, and can be disabled with
3316@option{-Wno-overlength-strings}.
3317@end table
3318
3319@node Debugging Options
3320@section Options for Debugging Your Program or GCC
3321@cindex options, debugging
3322@cindex debugging information options
3323
3324GCC has various special options that are used for debugging
3325either your program or GCC:
3326
3327@table @gcctabopt
3328@item -g
3329@opindex g
3330Produce debugging information in the operating system's native format
3331(stabs, COFF, XCOFF, or DWARF 2)@. GDB can work with this debugging
3332information.
3333
3334On most systems that use stabs format, @option{-g} enables use of extra
3335debugging information that only GDB can use; this extra information
3336makes debugging work better in GDB but will probably make other debuggers
3337crash or
3338refuse to read the program. If you want to control for certain whether
3339to generate the extra information, use @option{-gstabs+}, @option{-gstabs},
3340@option{-gxcoff+}, @option{-gxcoff}, or @option{-gvms} (see below).
3341
3342GCC allows you to use @option{-g} with
3343@option{-O}. The shortcuts taken by optimized code may occasionally
3344produce surprising results: some variables you declared may not exist
3345at all; flow of control may briefly move where you did not expect it;
3346some statements may not be executed because they compute constant
3347results or their values were already at hand; some statements may
3348execute in different places because they were moved out of loops.
3349
3350Nevertheless it proves possible to debug optimized output. This makes
3351it reasonable to use the optimizer for programs that might have bugs.
3352
3353The following options are useful when GCC is generated with the
3354capability for more than one debugging format.
3355
3356@item -ggdb
3357@opindex ggdb
3358Produce debugging information for use by GDB@. This means to use the
3359most expressive format available (DWARF 2, stabs, or the native format
3360if neither of those are supported), including GDB extensions if at all
3361possible.
3362
3363@item -gstabs
3364@opindex gstabs
3365Produce debugging information in stabs format (if that is supported),
3366without GDB extensions. This is the format used by DBX on most BSD
3367systems. On MIPS, Alpha and System V Release 4 systems this option
3368produces stabs debugging output which is not understood by DBX or SDB@.
3369On System V Release 4 systems this option requires the GNU assembler.
3370
3371@item -feliminate-unused-debug-symbols
3372@opindex feliminate-unused-debug-symbols
3373Produce debugging information in stabs format (if that is supported),
3374for only symbols that are actually used.
3375
3376@item -femit-class-debug-always
3377Instead of emitting debugging information for a C++ class in only one
3378object file, emit it in all object files using the class. This option
3379should be used only with debuggers that are unable to handle the way GCC
3380normally emits debugging information for classes because using this
3381option will increase the size of debugging information by as much as a
3382factor of two.
3383
3384@item -gstabs+
3385@opindex gstabs+
3386Produce debugging information in stabs format (if that is supported),
3387using GNU extensions understood only by the GNU debugger (GDB)@. The
3388use of these extensions is likely to make other debuggers crash or
3389refuse to read the program.
3390
3391@item -gcoff
3392@opindex gcoff
3393Produce debugging information in COFF format (if that is supported).
3394This is the format used by SDB on most System V systems prior to
3395System V Release 4.
3396
3397@item -gxcoff
3398@opindex gxcoff
3399Produce debugging information in XCOFF format (if that is supported).
3400This is the format used by the DBX debugger on IBM RS/6000 systems.
3401
3402@item -gxcoff+
3403@opindex gxcoff+
3404Produce debugging information in XCOFF format (if that is supported),
3405using GNU extensions understood only by the GNU debugger (GDB)@. The
3406use of these extensions is likely to make other debuggers crash or
3407refuse to read the program, and may cause assemblers other than the GNU
3408assembler (GAS) to fail with an error.
3409
3410@item -gdwarf-2
3411@opindex gdwarf-2
3412Produce debugging information in DWARF version 2 format (if that is
3413supported). This is the format used by DBX on IRIX 6. With this
3414option, GCC uses features of DWARF version 3 when they are useful;
3415version 3 is upward compatible with version 2, but may still cause
3416problems for older debuggers.
3417
3418@item -gvms
3419@opindex gvms
3420Produce debugging information in VMS debug format (if that is
3421supported). This is the format used by DEBUG on VMS systems.
3422
3423@item -g@var{level}
3424@itemx -ggdb@var{level}
3425@itemx -gstabs@var{level}
3426@itemx -gcoff@var{level}
3427@itemx -gxcoff@var{level}
3428@itemx -gvms@var{level}
3429Request debugging information and also use @var{level} to specify how
3430much information. The default level is 2.
3431
3432Level 1 produces minimal information, enough for making backtraces in
3433parts of the program that you don't plan to debug. This includes
3434descriptions of functions and external variables, but no information
3435about local variables and no line numbers.
3436
3437Level 3 includes extra information, such as all the macro definitions
3438present in the program. Some debuggers support macro expansion when
3439you use @option{-g3}.
3440
3441@option{-gdwarf-2} does not accept a concatenated debug level, because
3442GCC used to support an option @option{-gdwarf} that meant to generate
3443debug information in version 1 of the DWARF format (which is very
3444different from version 2), and it would have been too confusing. That
3445debug format is long obsolete, but the option cannot be changed now.
3446Instead use an additional @option{-g@var{level}} option to change the
3447debug level for DWARF2.
3448
3449@item -feliminate-dwarf2-dups
3450@opindex feliminate-dwarf2-dups
3451Compress DWARF2 debugging information by eliminating duplicated
3452information about each symbol. This option only makes sense when
3453generating DWARF2 debugging information with @option{-gdwarf-2}.
3454
3455@item -femit-struct-debug-baseonly
3456Emit debug information for struct-like types
3457only when the base name of the compilation source file
3458matches the base name of file in which the struct was defined.
3459
3460This option substantially reduces the size of debugging information,
3461but at significant potential loss in type information to the debugger.
3462See @option{-femit-struct-debug-reduced} for a less aggressive option.
3463See @option{-femit-struct-debug-detailed} for more detailed control.
3464
3465This option works only with DWARF 2.
3466
3467@item -femit-struct-debug-reduced
3468Emit debug information for struct-like types
3469only when the base name of the compilation source file
3470matches the base name of file in which the type was defined,
3471unless the struct is a template or defined in a system header.
3472
3473This option significantly reduces the size of debugging information,
3474with some potential loss in type information to the debugger.
3475See @option{-femit-struct-debug-baseonly} for a more aggressive option.
3476See @option{-femit-struct-debug-detailed} for more detailed control.
3477
3478This option works only with DWARF 2.
3479
3480@item -femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]}
3481Specify the struct-like types
3482for which the compiler will generate debug information.
3483The intent is to reduce duplicate struct debug information
3484between different object files within the same program.
3485
3486This option is a detailed version of
3487@option{-femit-struct-debug-reduced} and @option{-femit-struct-debug-baseonly},
3488which will serve for most needs.
3489
3490A specification has the syntax
3491[@samp{dir:}|@samp{ind:}][@samp{ord:}|@samp{gen:}](@samp{any}|@samp{sys}|@samp{base}|@samp{none})
3492
3493The optional first word limits the specification to
3494structs that are used directly (@samp{dir:}) or used indirectly (@samp{ind:}).
3495A struct type is used directly when it is the type of a variable, member.
3496Indirect uses arise through pointers to structs.
3497That is, when use of an incomplete struct would be legal, the use is indirect.
3498An example is
3499@samp{struct one direct; struct two * indirect;}.
3500
3501The optional second word limits the specification to
3502ordinary structs (@samp{ord:}) or generic structs (@samp{gen:}).
3503Generic structs are a bit complicated to explain.
3504For C++, these are non-explicit specializations of template classes,
3505or non-template classes within the above.
3506Other programming languages have generics,
3507but @samp{-femit-struct-debug-detailed} does not yet implement them.
3508
3509The third word specifies the source files for those
3510structs for which the compiler will emit debug information.
3511The values @samp{none} and @samp{any} have the normal meaning.
3512The value @samp{base} means that
3513the base of name of the file in which the type declaration appears
3514must match the base of the name of the main compilation file.
3515In practice, this means that
3516types declared in @file{foo.c} and @file{foo.h} will have debug information,
3517but types declared in other header will not.
3518The value @samp{sys} means those types satisfying @samp{base}
3519or declared in system or compiler headers.
3520
3521You may need to experiment to determine the best settings for your application.
3522
3523The default is @samp{-femit-struct-debug-detailed=all}.
3524
3525This option works only with DWARF 2.
3526
3527@cindex @command{prof}
3528@item -p
3529@opindex p
3530Generate extra code to write profile information suitable for the
3531analysis program @command{prof}. You must use this option when compiling
3532the source files you want data about, and you must also use it when
3533linking.
3534
3535@cindex @command{gprof}
3536@item -pg
3537@opindex pg
3538Generate extra code to write profile information suitable for the
3539analysis program @command{gprof}. You must use this option when compiling
3540the source files you want data about, and you must also use it when
3541linking.
3542
3543@item -Q
3544@opindex Q
3545Makes the compiler print out each function name as it is compiled, and
3546print some statistics about each pass when it finishes.
3547
3548@item -ftime-report
3549@opindex ftime-report
3550Makes the compiler print some statistics about the time consumed by each
3551pass when it finishes.
3552
3553@item -fmem-report
3554@opindex fmem-report
3555Makes the compiler print some statistics about permanent memory
3556allocation when it finishes.
3557
3558@item -fprofile-arcs
3559@opindex fprofile-arcs
3560Add code so that program flow @dfn{arcs} are instrumented. During
3561execution the program records how many times each branch and call is
3562executed and how many times it is taken or returns. When the compiled
3563program exits it saves this data to a file called
3564@file{@var{auxname}.gcda} for each source file. The data may be used for
3565profile-directed optimizations (@option{-fbranch-probabilities}), or for
3566test coverage analysis (@option{-ftest-coverage}). Each object file's
3567@var{auxname} is generated from the name of the output file, if
3568explicitly specified and it is not the final executable, otherwise it is
3569the basename of the source file. In both cases any suffix is removed
3570(e.g.@: @file{foo.gcda} for input file @file{dir/foo.c}, or
3571@file{dir/foo.gcda} for output file specified as @option{-o dir/foo.o}).
3572@xref{Cross-profiling}.
3573
3574@cindex @command{gcov}
3575@item --coverage
3576@opindex coverage
3577
3578This option is used to compile and link code instrumented for coverage
3579analysis. The option is a synonym for @option{-fprofile-arcs}
3580@option{-ftest-coverage} (when compiling) and @option{-lgcov} (when
3581linking). See the documentation for those options for more details.
3582
3583@itemize
3584
3585@item
3586Compile the source files with @option{-fprofile-arcs} plus optimization
3587and code generation options. For test coverage analysis, use the
3588additional @option{-ftest-coverage} option. You do not need to profile
3589every source file in a program.
3590
3591@item
3592Link your object files with @option{-lgcov} or @option{-fprofile-arcs}
3593(the latter implies the former).
3594
3595@item
3596Run the program on a representative workload to generate the arc profile
3597information. This may be repeated any number of times. You can run
3598concurrent instances of your program, and provided that the file system
3599supports locking, the data files will be correctly updated. Also
3600@code{fork} calls are detected and correctly handled (double counting
3601will not happen).
3602
3603@item
3604For profile-directed optimizations, compile the source files again with
3605the same optimization and code generation options plus
3606@option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that
3607Control Optimization}).
3608
3609@item
3610For test coverage analysis, use @command{gcov} to produce human readable
3611information from the @file{.gcno} and @file{.gcda} files. Refer to the
3612@command{gcov} documentation for further information.
3613
3614@end itemize
3615
3616With @option{-fprofile-arcs}, for each function of your program GCC
3617creates a program flow graph, then finds a spanning tree for the graph.
3618Only arcs that are not on the spanning tree have to be instrumented: the
3619compiler adds code to count the number of times that these arcs are
3620executed. When an arc is the only exit or only entrance to a block, the
3621instrumentation code can be added to the block; otherwise, a new basic
3622block must be created to hold the instrumentation code.
3623
3624@need 2000
3625@item -ftest-coverage
3626@opindex ftest-coverage
3627Produce a notes file that the @command{gcov} code-coverage utility
3628(@pxref{Gcov,, @command{gcov}---a Test Coverage Program}) can use to
3629show program coverage. Each source file's note file is called
3630@file{@var{auxname}.gcno}. Refer to the @option{-fprofile-arcs} option
3631above for a description of @var{auxname} and instructions on how to
3632generate test coverage data. Coverage data will match the source files
3633more closely, if you do not optimize.
3634
3635@item -d@var{letters}
3636@item -fdump-rtl-@var{pass}
3637@opindex d
3638Says to make debugging dumps during compilation at times specified by
3639@var{letters}. This is used for debugging the RTL-based passes of the
3640compiler. The file names for most of the dumps are made by appending a
3641pass number and a word to the @var{dumpname}. @var{dumpname} is generated
3642from the name of the output file, if explicitly specified and it is not
3643an executable, otherwise it is the basename of the source file.
3644
3645Most debug dumps can be enabled either passing a letter to the @option{-d}
3646option, or with a long @option{-fdump-rtl} switch; here are the possible
3647letters for use in @var{letters} and @var{pass}, and their meanings:
3648
3649@table @gcctabopt
3650@item -dA
3651@opindex dA
3652Annotate the assembler output with miscellaneous debugging information.
3653
3654@item -dB
3655@itemx -fdump-rtl-bbro
3656@opindex dB
3657@opindex fdump-rtl-bbro
3658Dump after block reordering, to @file{@var{file}.148r.bbro}.
3659
3660@item -dc
3661@itemx -fdump-rtl-combine
3662@opindex dc
3663@opindex fdump-rtl-combine
3664Dump after instruction combination, to the file @file{@var{file}.129r.combine}.
3665
3666@item -dC
3667@itemx -fdump-rtl-ce1
3668@itemx -fdump-rtl-ce2
3669@opindex dC
3670@opindex fdump-rtl-ce1
3671@opindex fdump-rtl-ce2
3672@option{-dC} and @option{-fdump-rtl-ce1} enable dumping after the
3673first if conversion, to the file @file{@var{file}.117r.ce1}. @option{-dC}
3674and @option{-fdump-rtl-ce2} enable dumping after the second if
3675conversion, to the file @file{@var{file}.130r.ce2}.
3676
3677@item -dd
3678@itemx -fdump-rtl-btl
3679@itemx -fdump-rtl-dbr
3680@opindex dd
3681@opindex fdump-rtl-btl
3682@opindex fdump-rtl-dbr
3683@option{-dd} and @option{-fdump-rtl-btl} enable dumping after branch
3684target load optimization, to @file{@var{file}.31.btl}. @option{-dd}
3685and @option{-fdump-rtl-dbr} enable dumping after delayed branch
3686scheduling, to @file{@var{file}.36.dbr}.
3687
3688@item -dD
3689@opindex dD
3690Dump all macro definitions, at the end of preprocessing, in addition to
3691normal output.
3692
3693@item -dE
3694@itemx -fdump-rtl-ce3
3695@opindex dE
3696@opindex fdump-rtl-ce3
3697Dump after the third if conversion, to @file{@var{file}.146r.ce3}.
3698
3699@item -df
3700@itemx -fdump-rtl-cfg
3701@itemx -fdump-rtl-life
3702@opindex df
3703@opindex fdump-rtl-cfg
3704@opindex fdump-rtl-life
3705@option{-df} and @option{-fdump-rtl-cfg} enable dumping after control
3706and data flow analysis, to @file{@var{file}.116r.cfg}. @option{-df}
3707and @option{-fdump-rtl-cfg} enable dumping dump after life analysis,
3708to @file{@var{file}.128r.life1} and @file{@var{file}.135r.life2}.
3709
3710@item -dg
3711@itemx -fdump-rtl-greg
3712@opindex dg
3713@opindex fdump-rtl-greg
3714Dump after global register allocation, to @file{@var{file}.139r.greg}.
3715
3716@item -dG
3717@itemx -fdump-rtl-gcse
3718@itemx -fdump-rtl-bypass
3719@opindex dG
3720@opindex fdump-rtl-gcse
3721@opindex fdump-rtl-bypass
3722@option{-dG} and @option{-fdump-rtl-gcse} enable dumping after GCSE, to
3723@file{@var{file}.114r.gcse}. @option{-dG} and @option{-fdump-rtl-bypass}
3724enable dumping after jump bypassing and control flow optimizations, to
3725@file{@var{file}.115r.bypass}.
3726
3727@item -dh
3728@itemx -fdump-rtl-eh
3729@opindex dh
3730@opindex fdump-rtl-eh
3731Dump after finalization of EH handling code, to @file{@var{file}.02.eh}.
3732
3733@item -di
3734@itemx -fdump-rtl-sibling
3735@opindex di
3736@opindex fdump-rtl-sibling
3737Dump after sibling call optimizations, to @file{@var{file}.106r.sibling}.
3738
3739@item -dj
3740@itemx -fdump-rtl-jump
3741@opindex dj
3742@opindex fdump-rtl-jump
3743Dump after the first jump optimization, to @file{@var{file}.112r.jump}.
3744
3745@item -dk
3746@itemx -fdump-rtl-stack
3747@opindex dk
3748@opindex fdump-rtl-stack
3749Dump after conversion from registers to stack, to @file{@var{file}.152r.stack}.
3750
3751@item -dl
3752@itemx -fdump-rtl-lreg
3753@opindex dl
3754@opindex fdump-rtl-lreg
3755Dump after local register allocation, to @file{@var{file}.138r.lreg}.
3756
3757@item -dL
3758@itemx -fdump-rtl-loop2
3759@opindex dL
3760@opindex fdump-rtl-loop2
3761@option{-dL} and @option{-fdump-rtl-loop2} enable dumping after the
3762loop optimization pass, to @file{@var{file}.119r.loop2},
3763@file{@var{file}.120r.loop2_init},
3764@file{@var{file}.121r.loop2_invariant}, and
3765@file{@var{file}.125r.loop2_done}.
3766
3767@item -dm
3768@itemx -fdump-rtl-sms
3769@opindex dm
3770@opindex fdump-rtl-sms
3771Dump after modulo scheduling, to @file{@var{file}.136r.sms}.
3772
3773@item -dM
3774@itemx -fdump-rtl-mach
3775@opindex dM
3776@opindex fdump-rtl-mach
3777Dump after performing the machine dependent reorganization pass, to
3778@file{@var{file}.155r.mach}.
3779
3780@item -dn
3781@itemx -fdump-rtl-rnreg
3782@opindex dn
3783@opindex fdump-rtl-rnreg
3784Dump after register renumbering, to @file{@var{file}.147r.rnreg}.
3785
3786@item -dN
3787@itemx -fdump-rtl-regmove
3788@opindex dN
3789@opindex fdump-rtl-regmove
3790Dump after the register move pass, to @file{@var{file}.132r.regmove}.
3791
3792@item -do
3793@itemx -fdump-rtl-postreload
3794@opindex do
3795@opindex fdump-rtl-postreload
3796Dump after post-reload optimizations, to @file{@var{file}.24.postreload}.
3797
3798@item -dr
3799@itemx -fdump-rtl-expand
3800@opindex dr
3801@opindex fdump-rtl-expand
3802Dump after RTL generation, to @file{@var{file}.104r.expand}.
3803
3804@item -dR
3805@itemx -fdump-rtl-sched2
3806@opindex dR
3807@opindex fdump-rtl-sched2
3808Dump after the second scheduling pass, to @file{@var{file}.150r.sched2}.
3809
3810@item -ds
3811@itemx -fdump-rtl-cse
3812@opindex ds
3813@opindex fdump-rtl-cse
3814Dump after CSE (including the jump optimization that sometimes follows
3815CSE), to @file{@var{file}.113r.cse}.
3816
3817@item -dS
3818@itemx -fdump-rtl-sched
3819@opindex dS
3820@opindex fdump-rtl-sched
3821Dump after the first scheduling pass, to @file{@var{file}.21.sched}.
3822
3823@item -dt
3824@itemx -fdump-rtl-cse2
3825@opindex dt
3826@opindex fdump-rtl-cse2
3827Dump after the second CSE pass (including the jump optimization that
3828sometimes follows CSE), to @file{@var{file}.127r.cse2}.
3829
3830@item -dT
3831@itemx -fdump-rtl-tracer
3832@opindex dT
3833@opindex fdump-rtl-tracer
3834Dump after running tracer, to @file{@var{file}.118r.tracer}.
3835
3836@item -dV
3837@itemx -fdump-rtl-vpt
3838@itemx -fdump-rtl-vartrack
3839@opindex dV
3840@opindex fdump-rtl-vpt
3841@opindex fdump-rtl-vartrack
3842@option{-dV} and @option{-fdump-rtl-vpt} enable dumping after the value
3843profile transformations, to @file{@var{file}.10.vpt}. @option{-dV}
3844and @option{-fdump-rtl-vartrack} enable dumping after variable tracking,
3845to @file{@var{file}.154r.vartrack}.
3846
3847@item -dw
3848@itemx -fdump-rtl-flow2
3849@opindex dw
3850@opindex fdump-rtl-flow2
3851Dump after the second flow pass, to @file{@var{file}.142r.flow2}.
3852
3853@item -dz
3854@itemx -fdump-rtl-peephole2
3855@opindex dz
3856@opindex fdump-rtl-peephole2
3857Dump after the peephole pass, to @file{@var{file}.145r.peephole2}.
3858
3859@item -dZ
3860@itemx -fdump-rtl-web
3861@opindex dZ
3862@opindex fdump-rtl-web
3863Dump after live range splitting, to @file{@var{file}.126r.web}.
3864
3865@item -da
3866@itemx -fdump-rtl-all
3867@opindex da
3868@opindex fdump-rtl-all
3869Produce all the dumps listed above.
3870
3871@item -dH
3872@opindex dH
3873Produce a core dump whenever an error occurs.
3874
3875@item -dm
3876@opindex dm
3877Print statistics on memory usage, at the end of the run, to
3878standard error.
3879
3880@item -dp
3881@opindex dp
3882Annotate the assembler output with a comment indicating which
3883pattern and alternative was used. The length of each instruction is
3884also printed.
3885
3886@item -dP
3887@opindex dP
3888Dump the RTL in the assembler output as a comment before each instruction.
3889Also turns on @option{-dp} annotation.
3890
3891@item -dv
3892@opindex dv
3893For each of the other indicated dump files (either with @option{-d} or
3894@option{-fdump-rtl-@var{pass}}), dump a representation of the control flow
3895graph suitable for viewing with VCG to @file{@var{file}.@var{pass}.vcg}.
3896
3897@item -dx
3898@opindex dx
3899Just generate RTL for a function instead of compiling it. Usually used
3900with @samp{r} (@option{-fdump-rtl-expand}).
3901
3902@item -dy
3903@opindex dy
3904Dump debugging information during parsing, to standard error.
3905@end table
3906
3907@item -fdump-noaddr
3908@opindex fdump-noaddr
3909When doing debugging dumps (see @option{-d} option above), suppress
3910address output. This makes it more feasible to use diff on debugging
3911dumps for compiler invocations with different compiler binaries and/or
3912different text / bss / data / heap / stack / dso start locations.
3913
3914@item -fdump-unnumbered
3915@opindex fdump-unnumbered
3916When doing debugging dumps (see @option{-d} option above), suppress instruction
3917numbers, line number note and address output. This makes it more feasible to
3918use diff on debugging dumps for compiler invocations with different
3919options, in particular with and without @option{-g}.
3920
3921@item -fdump-translation-unit @r{(C++ only)}
3922@itemx -fdump-translation-unit-@var{options} @r{(C++ only)}
3923@opindex fdump-translation-unit
3924Dump a representation of the tree structure for the entire translation
3925unit to a file. The file name is made by appending @file{.tu} to the
3926source file name. If the @samp{-@var{options}} form is used, @var{options}
3927controls the details of the dump as described for the
3928@option{-fdump-tree} options.
3929
3930@item -fdump-class-hierarchy @r{(C++ only)}
3931@itemx -fdump-class-hierarchy-@var{options} @r{(C++ only)}
3932@opindex fdump-class-hierarchy
3933Dump a representation of each class's hierarchy and virtual function
3934table layout to a file. The file name is made by appending @file{.class}
3935to the source file name. If the @samp{-@var{options}} form is used,
3936@var{options} controls the details of the dump as described for the
3937@option{-fdump-tree} options.
3938
3939@item -fdump-ipa-@var{switch}
3940@opindex fdump-ipa
3941Control the dumping at various stages of inter-procedural analysis
3942language tree to a file. The file name is generated by appending a switch
3943specific suffix to the source file name. The following dumps are possible:
3944
3945@table @samp
3946@item all
3947Enables all inter-procedural analysis dumps; currently the only produced
3948dump is the @samp{cgraph} dump.
3949
3950@item cgraph
3951Dumps information about call-graph optimization, unused function removal,
3952and inlining decisions.
3953@end table
3954
3955@item -fdump-tree-@var{switch}
3956@itemx -fdump-tree-@var{switch}-@var{options}
3957@opindex fdump-tree
3958Control the dumping at various stages of processing the intermediate
3959language tree to a file. The file name is generated by appending a switch
3960specific suffix to the source file name. If the @samp{-@var{options}}
3961form is used, @var{options} is a list of @samp{-} separated options that
3962control the details of the dump. Not all options are applicable to all
3963dumps, those which are not meaningful will be ignored. The following
3964options are available
3965
3966@table @samp
3967@item address
3968Print the address of each node. Usually this is not meaningful as it
3969changes according to the environment and source file. Its primary use
3970is for tying up a dump file with a debug environment.
3971@item slim
3972Inhibit dumping of members of a scope or body of a function merely
3973because that scope has been reached. Only dump such items when they
3974are directly reachable by some other path. When dumping pretty-printed
3975trees, this option inhibits dumping the bodies of control structures.
3976@item raw
3977Print a raw representation of the tree. By default, trees are
3978pretty-printed into a C-like representation.
3979@item details
3980Enable more detailed dumps (not honored by every dump option).
3981@item stats
3982Enable dumping various statistics about the pass (not honored by every dump
3983option).
3984@item blocks
3985Enable showing basic block boundaries (disabled in raw dumps).
3986@item vops
3987Enable showing virtual operands for every statement.
3988@item lineno
3989Enable showing line numbers for statements.
3990@item uid
3991Enable showing the unique ID (@code{DECL_UID}) for each variable.
3992@item all
3993Turn on all options, except @option{raw}, @option{slim} and @option{lineno}.
3994@end table
3995
3996The following tree dumps are possible:
3997@table @samp
3998
3999@item original
4000Dump before any tree based optimization, to @file{@var{file}.original}.
4001
4002@item optimized
4003Dump after all tree based optimization, to @file{@var{file}.optimized}.
4004
4005@item inlined
4006Dump after function inlining, to @file{@var{file}.inlined}.
4007
4008@item gimple
4009@opindex fdump-tree-gimple
4010Dump each function before and after the gimplification pass to a file. The
4011file name is made by appending @file{.gimple} to the source file name.
4012
4013@item cfg
4014@opindex fdump-tree-cfg
4015Dump the control flow graph of each function to a file. The file name is
4016made by appending @file{.cfg} to the source file name.
4017
4018@item vcg
4019@opindex fdump-tree-vcg
4020Dump the control flow graph of each function to a file in VCG format. The
4021file name is made by appending @file{.vcg} to the source file name. Note
4022that if the file contains more than one function, the generated file cannot
4023be used directly by VCG@. You will need to cut and paste each function's
4024graph into its own separate file first.
4025
4026@item ch
4027@opindex fdump-tree-ch
4028Dump each function after copying loop headers. The file name is made by
4029appending @file{.ch} to the source file name.
4030
4031@item ssa
4032@opindex fdump-tree-ssa
4033Dump SSA related information to a file. The file name is made by appending
4034@file{.ssa} to the source file name.
4035
4036@item salias
4037@opindex fdump-tree-salias
4038Dump structure aliasing variable information to a file. This file name
4039is made by appending @file{.salias} to the source file name.
4040
4041@item alias
4042@opindex fdump-tree-alias
4043Dump aliasing information for each function. The file name is made by
4044appending @file{.alias} to the source file name.
4045
4046@item ccp
4047@opindex fdump-tree-ccp
4048Dump each function after CCP@. The file name is made by appending
4049@file{.ccp} to the source file name.
4050
4051@item storeccp
4052@opindex fdump-tree-storeccp
4053Dump each function after STORE-CCP. The file name is made by appending
4054@file{.storeccp} to the source file name.
4055
4056@item pre
4057@opindex fdump-tree-pre
4058Dump trees after partial redundancy elimination. The file name is made
4059by appending @file{.pre} to the source file name.
4060
4061@item fre
4062@opindex fdump-tree-fre
4063Dump trees after full redundancy elimination. The file name is made
4064by appending @file{.fre} to the source file name.
4065
4066@item copyprop
4067@opindex fdump-tree-copyprop
4068Dump trees after copy propagation. The file name is made
4069by appending @file{.copyprop} to the source file name.
4070
4071@item store_copyprop
4072@opindex fdump-tree-store_copyprop
4073Dump trees after store copy-propagation. The file name is made
4074by appending @file{.store_copyprop} to the source file name.
4075
4076@item dce
4077@opindex fdump-tree-dce
4078Dump each function after dead code elimination. The file name is made by
4079appending @file{.dce} to the source file name.
4080
4081@item mudflap
4082@opindex fdump-tree-mudflap
4083Dump each function after adding mudflap instrumentation. The file name is
4084made by appending @file{.mudflap} to the source file name.
4085
4086@item sra
4087@opindex fdump-tree-sra
4088Dump each function after performing scalar replacement of aggregates. The
4089file name is made by appending @file{.sra} to the source file name.
4090
4091@item sink
4092@opindex fdump-tree-sink
4093Dump each function after performing code sinking. The file name is made
4094by appending @file{.sink} to the source file name.
4095
4096@item dom
4097@opindex fdump-tree-dom
4098Dump each function after applying dominator tree optimizations. The file
4099name is made by appending @file{.dom} to the source file name.
4100
4101@item dse
4102@opindex fdump-tree-dse
4103Dump each function after applying dead store elimination. The file
4104name is made by appending @file{.dse} to the source file name.
4105
4106@item phiopt
4107@opindex fdump-tree-phiopt
4108Dump each function after optimizing PHI nodes into straightline code. The file
4109name is made by appending @file{.phiopt} to the source file name.
4110
4111@item forwprop
4112@opindex fdump-tree-forwprop
4113Dump each function after forward propagating single use variables. The file
4114name is made by appending @file{.forwprop} to the source file name.
4115
4116@item copyrename
4117@opindex fdump-tree-copyrename
4118Dump each function after applying the copy rename optimization. The file
4119name is made by appending @file{.copyrename} to the source file name.
4120
4121@item nrv
4122@opindex fdump-tree-nrv
4123Dump each function after applying the named return value optimization on
4124generic trees. The file name is made by appending @file{.nrv} to the source
4125file name.
4126
4127@item vect
4128@opindex fdump-tree-vect
4129Dump each function after applying vectorization of loops. The file name is
4130made by appending @file{.vect} to the source file name.
4131
4132@item vrp
4133@opindex fdump-tree-vrp
4134Dump each function after Value Range Propagation (VRP). The file name
4135is made by appending @file{.vrp} to the source file name.
4136
4137@item all
4138@opindex fdump-tree-all
4139Enable all the available tree dumps with the flags provided in this option.
4140@end table
4141
4142@item -ftree-vectorizer-verbose=@var{n}
4143@opindex ftree-vectorizer-verbose
4144This option controls the amount of debugging output the vectorizer prints.
4145This information is written to standard error, unless
4146@option{-fdump-tree-all} or @option{-fdump-tree-vect} is specified,
4147in which case it is output to the usual dump listing file, @file{.vect}.
4148For @var{n}=0 no diagnostic information is reported.
4149If @var{n}=1 the vectorizer reports each loop that got vectorized,
4150and the total number of loops that got vectorized.
4151If @var{n}=2 the vectorizer also reports non-vectorized loops that passed
4152the first analysis phase (vect_analyze_loop_form) - i.e. countable,
4153inner-most, single-bb, single-entry/exit loops. This is the same verbosity
4154level that @option{-fdump-tree-vect-stats} uses.
4155Higher verbosity levels mean either more information dumped for each
4156reported loop, or same amount of information reported for more loops:
4157If @var{n}=3, alignment related information is added to the reports.
4158If @var{n}=4, data-references related information (e.g. memory dependences,
4159memory access-patterns) is added to the reports.
4160If @var{n}=5, the vectorizer reports also non-vectorized inner-most loops
4161that did not pass the first analysis phase (i.e. may not be countable, or
4162may have complicated control-flow).
4163If @var{n}=6, the vectorizer reports also non-vectorized nested loops.
4164For @var{n}=7, all the information the vectorizer generates during its
4165analysis and transformation is reported. This is the same verbosity level
4166that @option{-fdump-tree-vect-details} uses.
4167
4168@item -frandom-seed=@var{string}
4169@opindex frandom-string
4170This option provides a seed that GCC uses when it would otherwise use
4171random numbers. It is used to generate certain symbol names
4172that have to be different in every compiled file. It is also used to
4173place unique stamps in coverage data files and the object files that
4174produce them. You can use the @option{-frandom-seed} option to produce
4175reproducibly identical object files.
4176
4177The @var{string} should be different for every file you compile.
4178
4179@item -fsched-verbose=@var{n}
4180@opindex fsched-verbose
4181On targets that use instruction scheduling, this option controls the
4182amount of debugging output the scheduler prints. This information is
4183written to standard error, unless @option{-dS} or @option{-dR} is
4184specified, in which case it is output to the usual dump
4185listing file, @file{.sched} or @file{.sched2} respectively. However
4186for @var{n} greater than nine, the output is always printed to standard
4187error.
4188
4189For @var{n} greater than zero, @option{-fsched-verbose} outputs the
4190same information as @option{-dRS}. For @var{n} greater than one, it
4191also output basic block probabilities, detailed ready list information
4192and unit/insn info. For @var{n} greater than two, it includes RTL
4193at abort point, control-flow and regions info. And for @var{n} over
4194four, @option{-fsched-verbose} also includes dependence info.
4195
4196@item -save-temps
4197@opindex save-temps
4198Store the usual ``temporary'' intermediate files permanently; place them
4199in the current directory and name them based on the source file. Thus,
4200compiling @file{foo.c} with @samp{-c -save-temps} would produce files
4201@file{foo.i} and @file{foo.s}, as well as @file{foo.o}. This creates a
4202preprocessed @file{foo.i} output file even though the compiler now
4203normally uses an integrated preprocessor.
4204
4205When used in combination with the @option{-x} command line option,
4206@option{-save-temps} is sensible enough to avoid over writing an
4207input source file with the same extension as an intermediate file.
4208The corresponding intermediate file may be obtained by renaming the
4209source file before using @option{-save-temps}.
4210
4211@item -time
4212@opindex time
4213Report the CPU time taken by each subprocess in the compilation
4214sequence. For C source files, this is the compiler proper and assembler
4215(plus the linker if linking is done). The output looks like this:
4216
4217@smallexample
4218# cc1 0.12 0.01
4219# as 0.00 0.01
4220@end smallexample
4221
4222The first number on each line is the ``user time'', that is time spent
4223executing the program itself. The second number is ``system time'',
4224time spent executing operating system routines on behalf of the program.
4225Both numbers are in seconds.
4226
4227@item -fvar-tracking
4228@opindex fvar-tracking
4229Run variable tracking pass. It computes where variables are stored at each
4230position in code. Better debugging information is then generated
4231(if the debugging information format supports this information).
4232
4233It is enabled by default when compiling with optimization (@option{-Os},
4234@option{-O}, @option{-O2}, ...), debugging information (@option{-g}) and
4235the debug info format supports it.
4236
4237@item -print-file-name=@var{library}
4238@opindex print-file-name
4239Print the full absolute name of the library file @var{library} that
4240would be used when linking---and don't do anything else. With this
4241option, GCC does not compile or link anything; it just prints the
4242file name.
4243
4244@item -print-multi-directory
4245@opindex print-multi-directory
4246Print the directory name corresponding to the multilib selected by any
4247other switches present in the command line. This directory is supposed
4248to exist in @env{GCC_EXEC_PREFIX}.
4249
4250@item -print-multi-lib
4251@opindex print-multi-lib
4252Print the mapping from multilib directory names to compiler switches
4253that enable them. The directory name is separated from the switches by
4254@samp{;}, and each switch starts with an @samp{@@} instead of the
4255@samp{-}, without spaces between multiple switches. This is supposed to
4256ease shell-processing.
4257
4258@item -print-prog-name=@var{program}
4259@opindex print-prog-name
4260Like @option{-print-file-name}, but searches for a program such as @samp{cpp}.
4261
4262@item -print-libgcc-file-name
4263@opindex print-libgcc-file-name
4264Same as @option{-print-file-name=libgcc.a}.
4265
4266This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs}
4267but you do want to link with @file{libgcc.a}. You can do
4268
4269@smallexample
4270gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
4271@end smallexample
4272
4273@item -print-search-dirs
4274@opindex print-search-dirs
4275Print the name of the configured installation directory and a list of
4276program and library directories @command{gcc} will search---and don't do anything else.
4277
4278This is useful when @command{gcc} prints the error message
4279@samp{installation problem, cannot exec cpp0: No such file or directory}.
4280To resolve this you either need to put @file{cpp0} and the other compiler
4281components where @command{gcc} expects to find them, or you can set the environment
4282variable @env{GCC_EXEC_PREFIX} to the directory where you installed them.
4283Don't forget the trailing @samp{/}.
4284@xref{Environment Variables}.
4285
4286@item -dumpmachine
4287@opindex dumpmachine
4288Print the compiler's target machine (for example,
4289@samp{i686-pc-linux-gnu})---and don't do anything else.
4290
4291@item -dumpversion
4292@opindex dumpversion
4293Print the compiler version (for example, @samp{3.0})---and don't do
4294anything else.
4295
4296@item -dumpspecs
4297@opindex dumpspecs
4298Print the compiler's built-in specs---and don't do anything else. (This
4299is used when GCC itself is being built.) @xref{Spec Files}.
4300
4301@item -feliminate-unused-debug-types
4302@opindex feliminate-unused-debug-types
4303Normally, when producing DWARF2 output, GCC will emit debugging
4304information for all types declared in a compilation
4305unit, regardless of whether or not they are actually used
4306in that compilation unit. Sometimes this is useful, such as
4307if, in the debugger, you want to cast a value to a type that is
4308not actually used in your program (but is declared). More often,
4309however, this results in a significant amount of wasted space.
4310With this option, GCC will avoid producing debug symbol output
4311for types that are nowhere used in the source file being compiled.
4312@end table
4313
4314@node Optimize Options
4315@section Options That Control Optimization
4316@cindex optimize options
4317@cindex options, optimization
4318
4319These options control various sorts of optimizations.
4320
4321Without any optimization option, the compiler's goal is to reduce the
4322cost of compilation and to make debugging produce the expected
4323results. Statements are independent: if you stop the program with a
4324breakpoint between statements, you can then assign a new value to any
4325variable or change the program counter to any other statement in the
4326function and get exactly the results you would expect from the source
4327code.
4328
4329Turning on optimization flags makes the compiler attempt to improve
4330the performance and/or code size at the expense of compilation time
4331and possibly the ability to debug the program.
4332
4333The compiler performs optimization based on the knowledge it has of
4334the program. Optimization levels @option{-O} and above, in
4335particular, enable @emph{unit-at-a-time} mode, which allows the
4336compiler to consider information gained from later functions in
4337the file when compiling a function. Compiling multiple files at
4338once to a single output file in @emph{unit-at-a-time} mode allows
4339the compiler to use information gained from all of the files when
4340compiling each of them.
4341
4342Not all optimizations are controlled directly by a flag. Only
4343optimizations that have a flag are listed.
4344
4345@table @gcctabopt
4346@item -O
4347@itemx -O1
4348@opindex O
4349@opindex O1
4350Optimize. Optimizing compilation takes somewhat more time, and a lot
4351more memory for a large function.
4352
4353With @option{-O}, the compiler tries to reduce code size and execution
4354time, without performing any optimizations that take a great deal of
4355compilation time.
4356
4357@option{-O} turns on the following optimization flags:
4358@gccoptlist{-fdefer-pop @gol
4359-fdelayed-branch @gol
4360-fguess-branch-probability @gol
4361-fcprop-registers @gol
4362-fif-conversion @gol
4363-fif-conversion2 @gol
4364-ftree-ccp @gol
4365-ftree-dce @gol
4366-ftree-dominator-opts @gol
4367-ftree-dse @gol
4368-ftree-ter @gol
4369-ftree-lrs @gol
4370-ftree-sra @gol
4371-ftree-copyrename @gol
4372-ftree-fre @gol
4373-ftree-ch @gol
4374-funit-at-a-time @gol
4375-fmerge-constants}
4376
4377@option{-O} also turns on @option{-fomit-frame-pointer} on machines
4378where doing so does not interfere with debugging.
4379
4380@item -O2
4381@opindex O2
4382Optimize even more. GCC performs nearly all supported optimizations
4383that do not involve a space-speed tradeoff. The compiler does not
4384perform loop unrolling or function inlining when you specify @option{-O2}.
4385As compared to @option{-O}, this option increases both compilation time
4386and the performance of the generated code.
4387
4388@option{-O2} turns on all optimization flags specified by @option{-O}. It
4389also turns on the following optimization flags:
4390@gccoptlist{-fthread-jumps @gol
4391-fcrossjumping @gol
4392-foptimize-sibling-calls @gol
4393-fcse-follow-jumps -fcse-skip-blocks @gol
4394-fgcse -fgcse-lm @gol
4395-fexpensive-optimizations @gol
4396-frerun-cse-after-loop @gol
4397-fcaller-saves @gol
4398-fpeephole2 @gol
4399-fschedule-insns -fschedule-insns2 @gol
4400-fsched-interblock -fsched-spec @gol
4401-fregmove @gol
4402-fstrict-aliasing -fstrict-overflow @gol
4403-fdelete-null-pointer-checks @gol
4404-freorder-blocks -freorder-functions @gol
4405-falign-functions -falign-jumps @gol
4406-falign-loops -falign-labels @gol
4407-ftree-vrp @gol
4408-ftree-pre}
4409
4410Please note the warning under @option{-fgcse} about
4411invoking @option{-O2} on programs that use computed gotos.
4412
4413@option{-O2} doesn't turn on @option{-ftree-vrp} for the Ada compiler.
4414This option must be explicitly specified on the command line to be
4415enabled for the Ada compiler.
4416
4417@item -O3
4418@opindex O3
4419Optimize yet more. @option{-O3} turns on all optimizations specified by
4420@option{-O2} and also turns on the @option{-finline-functions},
4421@option{-funswitch-loops} and @option{-fgcse-after-reload} options.
4422
4423@item -O0
4424@opindex O0
4425Do not optimize. This is the default.
4426
4427@item -Os
4428@opindex Os
4429Optimize for size. @option{-Os} enables all @option{-O2} optimizations that
4430do not typically increase code size. It also performs further
4431optimizations designed to reduce code size.
4432
4433@option{-Os} disables the following optimization flags:
4434@gccoptlist{-falign-functions -falign-jumps -falign-loops @gol
4435-falign-labels -freorder-blocks -freorder-blocks-and-partition @gol
4436-fprefetch-loop-arrays -ftree-vect-loop-version}
4437
4438If you use multiple @option{-O} options, with or without level numbers,
4439the last such option is the one that is effective.
4440@end table
4441
4442Options of the form @option{-f@var{flag}} specify machine-independent
4443flags. Most flags have both positive and negative forms; the negative
4444form of @option{-ffoo} would be @option{-fno-foo}. In the table
4445below, only one of the forms is listed---the one you typically will
4446use. You can figure out the other form by either removing @samp{no-}
4447or adding it.
4448
4449The following options control specific optimizations. They are either
4450activated by @option{-O} options or are related to ones that are. You
4451can use the following flags in the rare cases when ``fine-tuning'' of
4452optimizations to be performed is desired.
4453
4454@table @gcctabopt
4455@item -fno-default-inline
4456@opindex fno-default-inline
4457Do not make member functions inline by default merely because they are
4458defined inside the class scope (C++ only). Otherwise, when you specify
4459@w{@option{-O}}, member functions defined inside class scope are compiled
4460inline by default; i.e., you don't need to add @samp{inline} in front of
4461the member function name.
4462
4463@item -fno-defer-pop
4464@opindex fno-defer-pop
4465Always pop the arguments to each function call as soon as that function
4466returns. For machines which must pop arguments after a function call,
4467the compiler normally lets arguments accumulate on the stack for several
4468function calls and pops them all at once.
4469
4470Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4471
4472@item -fforce-mem
4473@opindex fforce-mem
4474Force memory operands to be copied into registers before doing
4475arithmetic on them. This produces better code by making all memory
4476references potential common subexpressions. When they are not common
4477subexpressions, instruction combination should eliminate the separate
4478register-load. This option is now a nop and will be removed in 4.3.
4479
4480@item -fforce-addr
4481@opindex fforce-addr
4482Force memory address constants to be copied into registers before
4483doing arithmetic on them.
4484
4485@item -fomit-frame-pointer
4486@opindex fomit-frame-pointer
4487Don't keep the frame pointer in a register for functions that
4488don't need one. This avoids the instructions to save, set up and
4489restore frame pointers; it also makes an extra register available
4490in many functions. @strong{It also makes debugging impossible on
4491some machines.}
4492
4493On some machines, such as the VAX, this flag has no effect, because
4494the standard calling sequence automatically handles the frame pointer
4495and nothing is saved by pretending it doesn't exist. The
4496machine-description macro @code{FRAME_POINTER_REQUIRED} controls
4497whether a target machine supports this flag. @xref{Registers,,Register
4498Usage, gccint, GNU Compiler Collection (GCC) Internals}.
4499
4500Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4501
4502@item -foptimize-sibling-calls
4503@opindex foptimize-sibling-calls
4504Optimize sibling and tail recursive calls.
4505
4506Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4507
4508@item -fno-inline
4509@opindex fno-inline
4510Don't pay attention to the @code{inline} keyword. Normally this option
4511is used to keep the compiler from expanding any functions inline.
4512Note that if you are not optimizing, no functions can be expanded inline.
4513
4514@item -finline-functions
4515@opindex finline-functions
4516Integrate all simple functions into their callers. The compiler
4517heuristically decides which functions are simple enough to be worth
4518integrating in this way.
4519
4520If all calls to a given function are integrated, and the function is
4521declared @code{static}, then the function is normally not output as
4522assembler code in its own right.
4523
4524Enabled at level @option{-O3}.
4525
4526@item -finline-functions-called-once
4527@opindex finline-functions-called-once
4528Consider all @code{static} functions called once for inlining into their
4529caller even if they are not marked @code{inline}. If a call to a given
4530function is integrated, then the function is not output as assembler code
4531in its own right.
4532
4533Enabled if @option{-funit-at-a-time} is enabled.
4534
4535@item -fearly-inlining
4536@opindex fearly-inlining
4537Inline functions marked by @code{always_inline} and functions whose body seems
4538smaller than the function call overhead early before doing
4539@option{-fprofile-generate} instrumentation and real inlining pass. Doing so
4540makes profiling significantly cheaper and usually inlining faster on programs
4541having large chains of nested wrapper functions.
4542
4543Enabled by default.
4544
4545@item -finline-limit=@var{n}
4546@opindex finline-limit
4547By default, GCC limits the size of functions that can be inlined. This flag
4548allows the control of this limit for functions that are explicitly marked as
4549inline (i.e., marked with the inline keyword or defined within the class
4550definition in c++). @var{n} is the size of functions that can be inlined in
4551number of pseudo instructions (not counting parameter handling). The default
4552value of @var{n} is 600.
4553Increasing this value can result in more inlined code at
4554the cost of compilation time and memory consumption. Decreasing usually makes
4555the compilation faster and less code will be inlined (which presumably
4556means slower programs). This option is particularly useful for programs that
4557use inlining heavily such as those based on recursive templates with C++.
4558
4559Inlining is actually controlled by a number of parameters, which may be
4560specified individually by using @option{--param @var{name}=@var{value}}.
4561The @option{-finline-limit=@var{n}} option sets some of these parameters
4562as follows:
4563
4564@table @gcctabopt
4565@item max-inline-insns-single
4566 is set to @var{n}/2.
4567@item max-inline-insns-auto
4568 is set to @var{n}/2.
4569@item min-inline-insns
4570 is set to 130 or @var{n}/4, whichever is smaller.
4571@item max-inline-insns-rtl
4572 is set to @var{n}.
4573@end table
4574
4575See below for a documentation of the individual
4576parameters controlling inlining.
4577
4578@emph{Note:} pseudo instruction represents, in this particular context, an
4579abstract measurement of function's size. In no way does it represent a count
4580of assembly instructions and as such its exact meaning might change from one
4581release to an another.
4582
4583@item -fkeep-inline-functions
4584@opindex fkeep-inline-functions
4585In C, emit @code{static} functions that are declared @code{inline}
4586into the object file, even if the function has been inlined into all
4587of its callers. This switch does not affect functions using the
4588@code{extern inline} extension in GNU C@. In C++, emit any and all
4589inline functions into the object file.
4590
4591@item -fkeep-static-consts
4592@opindex fkeep-static-consts
4593Emit variables declared @code{static const} when optimization isn't turned
4594on, even if the variables aren't referenced.
4595
4596GCC enables this option by default. If you want to force the compiler to
4597check if the variable was referenced, regardless of whether or not
4598optimization is turned on, use the @option{-fno-keep-static-consts} option.
4599
4600@item -fmerge-constants
4601Attempt to merge identical constants (string constants and floating point
4602constants) across compilation units.
4603
4604This option is the default for optimized compilation if the assembler and
4605linker support it. Use @option{-fno-merge-constants} to inhibit this
4606behavior.
4607
4608Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4609
4610@item -fmerge-all-constants
4611Attempt to merge identical constants and identical variables.
4612
4613This option implies @option{-fmerge-constants}. In addition to
4614@option{-fmerge-constants} this considers e.g.@: even constant initialized
4615arrays or initialized constant variables with integral or floating point
4616types. Languages like C or C++ require each non-automatic variable to
4617have distinct location, so using this option will result in non-conforming
4618behavior.
4619
4620@item -fmodulo-sched
4621@opindex fmodulo-sched
4622Perform swing modulo scheduling immediately before the first scheduling
4623pass. This pass looks at innermost loops and reorders their
4624instructions by overlapping different iterations.
4625
4626@item -fno-branch-count-reg
4627@opindex fno-branch-count-reg
4628Do not use ``decrement and branch'' instructions on a count register,
4629but instead generate a sequence of instructions that decrement a
4630register, compare it against zero, then branch based upon the result.
4631This option is only meaningful on architectures that support such
4632instructions, which include x86, PowerPC, IA-64 and S/390.
4633
4634The default is @option{-fbranch-count-reg}.
4635
4636@item -fno-function-cse
4637@opindex fno-function-cse
4638Do not put function addresses in registers; make each instruction that
4639calls a constant function contain the function's address explicitly.
4640
4641This option results in less efficient code, but some strange hacks
4642that alter the assembler output may be confused by the optimizations
4643performed when this option is not used.
4644
4645The default is @option{-ffunction-cse}
4646
4647@item -fno-zero-initialized-in-bss
4648@opindex fno-zero-initialized-in-bss
4649If the target supports a BSS section, GCC by default puts variables that
4650are initialized to zero into BSS@. This can save space in the resulting
4651code.
4652
4653This option turns off this behavior because some programs explicitly
4654rely on variables going to the data section. E.g., so that the
4655resulting executable can find the beginning of that section and/or make
4656assumptions based on that.
4657
4658The default is @option{-fzero-initialized-in-bss}.
4659
4660@item -fbounds-check
4661@opindex fbounds-check
4662For front-ends that support it, generate additional code to check that
4663indices used to access arrays are within the declared range. This is
4664currently only supported by the Java and Fortran front-ends, where
4665this option defaults to true and false respectively.
4666
4667@item -fmudflap -fmudflapth -fmudflapir
4668@opindex fmudflap
4669@opindex fmudflapth
4670@opindex fmudflapir
4671@cindex bounds checking
4672@cindex mudflap
4673For front-ends that support it (C and C++), instrument all risky
4674pointer/array dereferencing operations, some standard library
4675string/heap functions, and some other associated constructs with
4676range/validity tests. Modules so instrumented should be immune to
4677buffer overflows, invalid heap use, and some other classes of C/C++
4678programming errors. The instrumentation relies on a separate runtime
4679library (@file{libmudflap}), which will be linked into a program if
4680@option{-fmudflap} is given at link time. Run-time behavior of the
4681instrumented program is controlled by the @env{MUDFLAP_OPTIONS}
4682environment variable. See @code{env MUDFLAP_OPTIONS=-help a.out}
4683for its options.
4684
4685Use @option{-fmudflapth} instead of @option{-fmudflap} to compile and to
4686link if your program is multi-threaded. Use @option{-fmudflapir}, in
4687addition to @option{-fmudflap} or @option{-fmudflapth}, if
4688instrumentation should ignore pointer reads. This produces less
4689instrumentation (and therefore faster execution) and still provides
4690some protection against outright memory corrupting writes, but allows
4691erroneously read data to propagate within a program.
4692
4693@item -fthread-jumps
4694@opindex fthread-jumps
4695Perform optimizations where we check to see if a jump branches to a
4696location where another comparison subsumed by the first is found. If
4697so, the first branch is redirected to either the destination of the
4698second branch or a point immediately following it, depending on whether
4699the condition is known to be true or false.
4700
4701Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4702
4703@item -fcse-follow-jumps
4704@opindex fcse-follow-jumps
4705In common subexpression elimination, scan through jump instructions
4706when the target of the jump is not reached by any other path. For
4707example, when CSE encounters an @code{if} statement with an
4708@code{else} clause, CSE will follow the jump when the condition
4709tested is false.
4710
4711Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4712
4713@item -fcse-skip-blocks
4714@opindex fcse-skip-blocks
4715This is similar to @option{-fcse-follow-jumps}, but causes CSE to
4716follow jumps which conditionally skip over blocks. When CSE
4717encounters a simple @code{if} statement with no else clause,
4718@option{-fcse-skip-blocks} causes CSE to follow the jump around the
4719body of the @code{if}.
4720
4721Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4722
4723@item -frerun-cse-after-loop
4724@opindex frerun-cse-after-loop
4725Re-run common subexpression elimination after loop optimizations has been
4726performed.
4727
4728Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4729
4730@item -fgcse
4731@opindex fgcse
4732Perform a global common subexpression elimination pass.
4733This pass also performs global constant and copy propagation.
4734
4735@emph{Note:} When compiling a program using computed gotos, a GCC
4736extension, you may get better runtime performance if you disable
4737the global common subexpression elimination pass by adding
4738@option{-fno-gcse} to the command line.
4739
4740Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4741
4742@item -fgcse-lm
4743@opindex fgcse-lm
4744When @option{-fgcse-lm} is enabled, global common subexpression elimination will
4745attempt to move loads which are only killed by stores into themselves. This
4746allows a loop containing a load/store sequence to be changed to a load outside
4747the loop, and a copy/store within the loop.
4748
4749Enabled by default when gcse is enabled.
4750
4751@item -fgcse-sm
4752@opindex fgcse-sm
4753When @option{-fgcse-sm} is enabled, a store motion pass is run after
4754global common subexpression elimination. This pass will attempt to move
4755stores out of loops. When used in conjunction with @option{-fgcse-lm},
4756loops containing a load/store sequence can be changed to a load before
4757the loop and a store after the loop.
4758
4759Not enabled at any optimization level.
4760
4761@item -fgcse-las
4762@opindex fgcse-las
4763When @option{-fgcse-las} is enabled, the global common subexpression
4764elimination pass eliminates redundant loads that come after stores to the
4765same memory location (both partial and full redundancies).
4766
4767Not enabled at any optimization level.
4768
4769@item -fgcse-after-reload
4770@opindex fgcse-after-reload
4771When @option{-fgcse-after-reload} is enabled, a redundant load elimination
4772pass is performed after reload. The purpose of this pass is to cleanup
4773redundant spilling.
4774
4775@item -funsafe-loop-optimizations
4776@opindex funsafe-loop-optimizations
4777If given, the loop optimizer will assume that loop indices do not
4778overflow, and that the loops with nontrivial exit condition are not
4779infinite. This enables a wider range of loop optimizations even if
4780the loop optimizer itself cannot prove that these assumptions are valid.
4781Using @option{-Wunsafe-loop-optimizations}, the compiler will warn you
4782if it finds this kind of loop.
4783
4784@item -fcrossjumping
4785@opindex crossjumping
4786Perform cross-jumping transformation. This transformation unifies equivalent code and save code size. The
4787resulting code may or may not perform better than without cross-jumping.
4788
4789Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4790
4791@item -fif-conversion
4792@opindex if-conversion
4793Attempt to transform conditional jumps into branch-less equivalents. This
4794include use of conditional moves, min, max, set flags and abs instructions, and
4795some tricks doable by standard arithmetics. The use of conditional execution
4796on chips where it is available is controlled by @code{if-conversion2}.
4797
4798Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4799
4800@item -fif-conversion2
4801@opindex if-conversion2
4802Use conditional execution (where available) to transform conditional jumps into
4803branch-less equivalents.
4804
4805Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4806
4807@item -fdelete-null-pointer-checks
4808@opindex fdelete-null-pointer-checks
4809Use global dataflow analysis to identify and eliminate useless checks
4810for null pointers. The compiler assumes that dereferencing a null
4811pointer would have halted the program. If a pointer is checked after
4812it has already been dereferenced, it cannot be null.
4813
4814In some environments, this assumption is not true, and programs can
4815safely dereference null pointers. Use
4816@option{-fno-delete-null-pointer-checks} to disable this optimization
4817for programs which depend on that behavior.
4818
4819Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4820
4821@item -fexpensive-optimizations
4822@opindex fexpensive-optimizations
4823Perform a number of minor optimizations that are relatively expensive.
4824
4825Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4826
4827@item -foptimize-register-move
4828@itemx -fregmove
4829@opindex foptimize-register-move
4830@opindex fregmove
4831Attempt to reassign register numbers in move instructions and as
4832operands of other simple instructions in order to maximize the amount of
4833register tying. This is especially helpful on machines with two-operand
4834instructions.
4835
4836Note @option{-fregmove} and @option{-foptimize-register-move} are the same
4837optimization.
4838
4839Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4840
4841@item -fdelayed-branch
4842@opindex fdelayed-branch
4843If supported for the target machine, attempt to reorder instructions
4844to exploit instruction slots available after delayed branch
4845instructions.
4846
4847Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4848
4849@item -fschedule-insns
4850@opindex fschedule-insns
4851If supported for the target machine, attempt to reorder instructions to
4852eliminate execution stalls due to required data being unavailable. This
4853helps machines that have slow floating point or memory load instructions
4854by allowing other instructions to be issued until the result of the load
4855or floating point instruction is required.
4856
4857Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4858
4859@item -fschedule-insns2
4860@opindex fschedule-insns2
4861Similar to @option{-fschedule-insns}, but requests an additional pass of
4862instruction scheduling after register allocation has been done. This is
4863especially useful on machines with a relatively small number of
4864registers and where memory load instructions take more than one cycle.
4865
4866Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4867
4868@item -fno-sched-interblock
4869@opindex fno-sched-interblock
4870Don't schedule instructions across basic blocks. This is normally
4871enabled by default when scheduling before register allocation, i.e.@:
4872with @option{-fschedule-insns} or at @option{-O2} or higher.
4873
4874@item -fno-sched-spec
4875@opindex fno-sched-spec
4876Don't allow speculative motion of non-load instructions. This is normally
4877enabled by default when scheduling before register allocation, i.e.@:
4878with @option{-fschedule-insns} or at @option{-O2} or higher.
4879
4880@item -fsched-spec-load
4881@opindex fsched-spec-load
4882Allow speculative motion of some load instructions. This only makes
4883sense when scheduling before register allocation, i.e.@: with
4884@option{-fschedule-insns} or at @option{-O2} or higher.
4885
4886@item -fsched-spec-load-dangerous
4887@opindex fsched-spec-load-dangerous
4888Allow speculative motion of more load instructions. This only makes
4889sense when scheduling before register allocation, i.e.@: with
4890@option{-fschedule-insns} or at @option{-O2} or higher.
4891
4892@item -fsched-stalled-insns=@var{n}
4893@opindex fsched-stalled-insns
4894Define how many insns (if any) can be moved prematurely from the queue
4895of stalled insns into the ready list, during the second scheduling pass.
4896
4897@item -fsched-stalled-insns-dep=@var{n}
4898@opindex fsched-stalled-insns-dep
4899Define how many insn groups (cycles) will be examined for a dependency
4900on a stalled insn that is candidate for premature removal from the queue
4901of stalled insns. Has an effect only during the second scheduling pass,
4902and only if @option{-fsched-stalled-insns} is used and its value is not zero.
4903
4904@item -fsched2-use-superblocks
4905@opindex fsched2-use-superblocks
4906When scheduling after register allocation, do use superblock scheduling
4907algorithm. Superblock scheduling allows motion across basic block boundaries
4908resulting on faster schedules. This option is experimental, as not all machine
4909descriptions used by GCC model the CPU closely enough to avoid unreliable
4910results from the algorithm.
4911
4912This only makes sense when scheduling after register allocation, i.e.@: with
4913@option{-fschedule-insns2} or at @option{-O2} or higher.
4914
4915@item -fsched2-use-traces
4916@opindex fsched2-use-traces
4917Use @option{-fsched2-use-superblocks} algorithm when scheduling after register
4918allocation and additionally perform code duplication in order to increase the
4919size of superblocks using tracer pass. See @option{-ftracer} for details on
4920trace formation.
4921
4922This mode should produce faster but significantly longer programs. Also
4923without @option{-fbranch-probabilities} the traces constructed may not
4924match the reality and hurt the performance. This only makes
4925sense when scheduling after register allocation, i.e.@: with
4926@option{-fschedule-insns2} or at @option{-O2} or higher.
4927
4928@item -fsee
4929@opindex fsee
4930Eliminates redundant extension instructions and move the non redundant
4931ones to optimal placement using LCM.
4932
4933@item -freschedule-modulo-scheduled-loops
4934@opindex fscheduling-in-modulo-scheduled-loops
4935The modulo scheduling comes before the traditional scheduling, if a loop was modulo scheduled
4936we may want to prevent the later scheduling passes from changing its schedule, we use this
4937option to control that.
4938
4939@item -fcaller-saves
4940@opindex fcaller-saves
4941Enable values to be allocated in registers that will be clobbered by
4942function calls, by emitting extra instructions to save and restore the
4943registers around such calls. Such allocation is done only when it
4944seems to result in better code than would otherwise be produced.
4945
4946This option is always enabled by default on certain machines, usually
4947those which have no call-preserved registers to use instead.
4948
4949Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4950
4951@item -ftree-pre
4952Perform Partial Redundancy Elimination (PRE) on trees. This flag is
4953enabled by default at @option{-O2} and @option{-O3}.
4954
4955@item -ftree-fre
4956Perform Full Redundancy Elimination (FRE) on trees. The difference
4957between FRE and PRE is that FRE only considers expressions
4958that are computed on all paths leading to the redundant computation.
4959This analysis faster than PRE, though it exposes fewer redundancies.
4960This flag is enabled by default at @option{-O} and higher.
4961
4962@item -ftree-copy-prop
4963Perform copy propagation on trees. This pass eliminates unnecessary
4964copy operations. This flag is enabled by default at @option{-O} and
4965higher.
4966
4967@item -ftree-store-copy-prop
4968Perform copy propagation of memory loads and stores. This pass
4969eliminates unnecessary copy operations in memory references
4970(structures, global variables, arrays, etc). This flag is enabled by
4971default at @option{-O2} and higher.
4972
4973@item -ftree-salias
4974Perform structural alias analysis on trees. This flag
4975is enabled by default at @option{-O} and higher.
4976
4977@item -fipa-pta
4978Perform interprocedural pointer analysis.
4979
4980@item -ftree-sink
4981Perform forward store motion on trees. This flag is
4982enabled by default at @option{-O} and higher.
4983
4984@item -ftree-ccp
4985Perform sparse conditional constant propagation (CCP) on trees. This
4986pass only operates on local scalar variables and is enabled by default
4987at @option{-O} and higher.
4988
4989@item -ftree-store-ccp
4990Perform sparse conditional constant propagation (CCP) on trees. This
4991pass operates on both local scalar variables and memory stores and
4992loads (global variables, structures, arrays, etc). This flag is
4993enabled by default at @option{-O2} and higher.
4994
4995@item -ftree-dce
4996Perform dead code elimination (DCE) on trees. This flag is enabled by
4997default at @option{-O} and higher.
4998
4999@item -ftree-dominator-opts
5000Perform a variety of simple scalar cleanups (constant/copy
5001propagation, redundancy elimination, range propagation and expression
5002simplification) based on a dominator tree traversal. This also
5003performs jump threading (to reduce jumps to jumps). This flag is
5004enabled by default at @option{-O} and higher.
5005
5006@item -ftree-ch
5007Perform loop header copying on trees. This is beneficial since it increases
5008effectiveness of code motion optimizations. It also saves one jump. This flag
5009is enabled by default at @option{-O} and higher. It is not enabled
5010for @option{-Os}, since it usually increases code size.
5011
5012@item -ftree-loop-optimize
5013Perform loop optimizations on trees. This flag is enabled by default
5014at @option{-O} and higher.
5015
5016@item -ftree-loop-linear
5017Perform linear loop transformations on tree. This flag can improve cache
5018performance and allow further loop optimizations to take place.
5019
5020@item -ftree-loop-im
5021Perform loop invariant motion on trees. This pass moves only invariants that
5022would be hard to handle at RTL level (function calls, operations that expand to
5023nontrivial sequences of insns). With @option{-funswitch-loops} it also moves
5024operands of conditions that are invariant out of the loop, so that we can use
5025just trivial invariantness analysis in loop unswitching. The pass also includes
5026store motion.
5027
5028@item -ftree-loop-ivcanon
5029Create a canonical counter for number of iterations in the loop for that
5030determining number of iterations requires complicated analysis. Later
5031optimizations then may determine the number easily. Useful especially
5032in connection with unrolling.
5033
5034@item -fivopts
5035Perform induction variable optimizations (strength reduction, induction
5036variable merging and induction variable elimination) on trees.
5037
5038@item -ftree-sra
5039Perform scalar replacement of aggregates. This pass replaces structure
5040references with scalars to prevent committing structures to memory too
5041early. This flag is enabled by default at @option{-O} and higher.
5042
5043@item -ftree-copyrename
5044Perform copy renaming on trees. This pass attempts to rename compiler
5045temporaries to other variables at copy locations, usually resulting in
5046variable names which more closely resemble the original variables. This flag
5047is enabled by default at @option{-O} and higher.
5048
5049@item -ftree-ter
5050Perform temporary expression replacement during the SSA->normal phase. Single
5051use/single def temporaries are replaced at their use location with their
5052defining expression. This results in non-GIMPLE code, but gives the expanders
5053much more complex trees to work on resulting in better RTL generation. This is
5054enabled by default at @option{-O} and higher.
5055
5056@item -ftree-lrs
5057Perform live range splitting during the SSA->normal phase. Distinct live
5058ranges of a variable are split into unique variables, allowing for better
5059optimization later. This is enabled by default at @option{-O} and higher.
5060
5061@item -ftree-vectorize
5062Perform loop vectorization on trees.
5063
5064@item -ftree-vect-loop-version
5065@opindex ftree-vect-loop-version
5066Perform loop versioning when doing loop vectorization on trees. When a loop
5067appears to be vectorizable except that data alignment or data dependence cannot
5068be determined at compile time then vectorized and non-vectorized versions of
5069the loop are generated along with runtime checks for alignment or dependence
5070to control which version is executed. This option is enabled by default
5071except at level @option{-Os} where it is disabled.
5072
5073@item -ftree-vrp
5074Perform Value Range Propagation on trees. This is similar to the
5075constant propagation pass, but instead of values, ranges of values are
5076propagated. This allows the optimizers to remove unnecessary range
5077checks like array bound checks and null pointer checks. This is
5078enabled by default at @option{-O2} and higher. Null pointer check
5079elimination is only done if @option{-fdelete-null-pointer-checks} is
5080enabled.
5081
5082@item -ftracer
5083@opindex ftracer
5084Perform tail duplication to enlarge superblock size. This transformation
5085simplifies the control flow of the function allowing other optimizations to do
5086better job.
5087
5088@item -funroll-loops
5089@opindex funroll-loops
5090Unroll loops whose number of iterations can be determined at compile
5091time or upon entry to the loop. @option{-funroll-loops} implies
5092@option{-frerun-cse-after-loop}. This option makes code larger,
5093and may or may not make it run faster.
5094
5095@item -funroll-all-loops
5096@opindex funroll-all-loops
5097Unroll all loops, even if their number of iterations is uncertain when
5098the loop is entered. This usually makes programs run more slowly.
5099@option{-funroll-all-loops} implies the same options as
5100@option{-funroll-loops},
5101
5102@item -fsplit-ivs-in-unroller
5103@opindex fsplit-ivs-in-unroller
5104Enables expressing of values of induction variables in later iterations
5105of the unrolled loop using the value in the first iteration. This breaks
5106long dependency chains, thus improving efficiency of the scheduling passes.
5107
5108Combination of @option{-fweb} and CSE is often sufficient to obtain the
5109same effect. However in cases the loop body is more complicated than
5110a single basic block, this is not reliable. It also does not work at all
5111on some of the architectures due to restrictions in the CSE pass.
5112
5113This optimization is enabled by default.
5114
5115@item -fvariable-expansion-in-unroller
5116@opindex fvariable-expansion-in-unroller
5117With this option, the compiler will create multiple copies of some
5118local variables when unrolling a loop which can result in superior code.
5119
5120@item -fprefetch-loop-arrays
5121@opindex fprefetch-loop-arrays
5122If supported by the target machine, generate instructions to prefetch
5123memory to improve the performance of loops that access large arrays.
5124
5125This option may generate better or worse code; results are highly
5126dependent on the structure of loops within the source code.
5127
5128Disabled at level @option{-Os}.
5129
5130@item -fno-peephole
5131@itemx -fno-peephole2
5132@opindex fno-peephole
5133@opindex fno-peephole2
5134Disable any machine-specific peephole optimizations. The difference
5135between @option{-fno-peephole} and @option{-fno-peephole2} is in how they
5136are implemented in the compiler; some targets use one, some use the
5137other, a few use both.
5138
5139@option{-fpeephole} is enabled by default.
5140@option{-fpeephole2} enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5141
5142@item -fno-guess-branch-probability
5143@opindex fno-guess-branch-probability
5144Do not guess branch probabilities using heuristics.
5145
5146GCC will use heuristics to guess branch probabilities if they are
5147not provided by profiling feedback (@option{-fprofile-arcs}). These
5148heuristics are based on the control flow graph. If some branch probabilities
5149are specified by @samp{__builtin_expect}, then the heuristics will be
5150used to guess branch probabilities for the rest of the control flow graph,
5151taking the @samp{__builtin_expect} info into account. The interactions
5152between the heuristics and @samp{__builtin_expect} can be complex, and in
5153some cases, it may be useful to disable the heuristics so that the effects
5154of @samp{__builtin_expect} are easier to understand.
5155
5156The default is @option{-fguess-branch-probability} at levels
5157@option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5158
5159@item -freorder-blocks
5160@opindex freorder-blocks
5161Reorder basic blocks in the compiled function in order to reduce number of
5162taken branches and improve code locality.
5163
5164Enabled at levels @option{-O2}, @option{-O3}.
5165
5166@item -freorder-blocks-and-partition
5167@opindex freorder-blocks-and-partition
5168In addition to reordering basic blocks in the compiled function, in order
5169to reduce number of taken branches, partitions hot and cold basic blocks
5170into separate sections of the assembly and .o files, to improve
5171paging and cache locality performance.
5172
5173This optimization is automatically turned off in the presence of
5174exception handling, for linkonce sections, for functions with a user-defined
5175section attribute and on any architecture that does not support named
5176sections.
5177
5178@item -freorder-functions
5179@opindex freorder-functions
5180Reorder functions in the object file in order to
5181improve code locality. This is implemented by using special
5182subsections @code{.text.hot} for most frequently executed functions and
5183@code{.text.unlikely} for unlikely executed functions. Reordering is done by
5184the linker so object file format must support named sections and linker must
5185place them in a reasonable way.
5186
5187Also profile feedback must be available in to make this option effective. See
5188@option{-fprofile-arcs} for details.
5189
5190Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5191
5192@item -fstrict-aliasing
5193@opindex fstrict-aliasing
5194Allows the compiler to assume the strictest aliasing rules applicable to
5195the language being compiled. For C (and C++), this activates
5196optimizations based on the type of expressions. In particular, an
5197object of one type is assumed never to reside at the same address as an
5198object of a different type, unless the types are almost the same. For
5199example, an @code{unsigned int} can alias an @code{int}, but not a
5200@code{void*} or a @code{double}. A character type may alias any other
5201type.
5202
5203Pay special attention to code like this:
5204@smallexample
5205union a_union @{
5206 int i;
5207 double d;
5208@};
5209
5210int f() @{
5211 a_union t;
5212 t.d = 3.0;
5213 return t.i;
5214@}
5215@end smallexample
5216The practice of reading from a different union member than the one most
5217recently written to (called ``type-punning'') is common. Even with
5218@option{-fstrict-aliasing}, type-punning is allowed, provided the memory
5219is accessed through the union type. So, the code above will work as
5220expected. However, this code might not:
5221@smallexample
5222int f() @{
5223 a_union t;
5224 int* ip;
5225 t.d = 3.0;
5226 ip = &t.i;
5227 return *ip;
5228@}
5229@end smallexample
5230
5231Every language that wishes to perform language-specific alias analysis
5232should define a function that computes, given an @code{tree}
5233node, an alias set for the node. Nodes in different alias sets are not
5234allowed to alias. For an example, see the C front-end function
5235@code{c_get_alias_set}.
5236
5237Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5238
5239@item -fstrict-overflow
5240@opindex fstrict-overflow
5241Allow the compiler to assume strict signed overflow rules, depending
5242on the language being compiled. For C (and C++) this means that
5243overflow when doing arithmetic with signed numbers is undefined, which
5244means that the compiler may assume that it will not happen. This
5245permits various optimizations. For example, the compiler will assume
5246that an expression like @code{i + 10 > i} will always be true for
5247signed @code{i}. This assumption is only valid if signed overflow is
5248undefined, as the expression is false if @code{i + 10} overflows when
5249using twos complement arithmetic. When this option is in effect any
5250attempt to determine whether an operation on signed numbers will
5251overflow must be written carefully to not actually involve overflow.
5252
5253See also the @option{-fwrapv} option. Using @option{-fwrapv} means
5254that signed overflow is fully defined: it wraps. When
5255@option{-fwrapv} is used, there is no difference between
5256@option{-fstrict-overflow} and @option{-fno-strict-overflow}. With
5257@option{-fwrapv} certain types of overflow are permitted. For
5258example, if the compiler gets an overflow when doing arithmetic on
5259constants, the overflowed value can still be used with
5260@option{-fwrapv}, but not otherwise.
5261
5262The @option{-fstrict-overflow} option is enabled at levels
5263@option{-O2}, @option{-O3}, @option{-Os}.
5264
5265@item -falign-functions
5266@itemx -falign-functions=@var{n}
5267@opindex falign-functions
5268Align the start of functions to the next power-of-two greater than
5269@var{n}, skipping up to @var{n} bytes. For instance,
5270@option{-falign-functions=32} aligns functions to the next 32-byte
5271boundary, but @option{-falign-functions=24} would align to the next
527232-byte boundary only if this can be done by skipping 23 bytes or less.
5273
5274@option{-fno-align-functions} and @option{-falign-functions=1} are
5275equivalent and mean that functions will not be aligned.
5276
5277Some assemblers only support this flag when @var{n} is a power of two;
5278in that case, it is rounded up.
5279
5280If @var{n} is not specified or is zero, use a machine-dependent default.
5281
5282Enabled at levels @option{-O2}, @option{-O3}.
5283
5284@item -falign-labels
5285@itemx -falign-labels=@var{n}
5286@opindex falign-labels
5287Align all branch targets to a power-of-two boundary, skipping up to
5288@var{n} bytes like @option{-falign-functions}. This option can easily
5289make code slower, because it must insert dummy operations for when the
5290branch target is reached in the usual flow of the code.
5291
5292@option{-fno-align-labels} and @option{-falign-labels=1} are
5293equivalent and mean that labels will not be aligned.
5294
5295If @option{-falign-loops} or @option{-falign-jumps} are applicable and
5296are greater than this value, then their values are used instead.
5297
5298If @var{n} is not specified or is zero, use a machine-dependent default
5299which is very likely to be @samp{1}, meaning no alignment.
5300
5301Enabled at levels @option{-O2}, @option{-O3}.
5302
5303@item -falign-loops
5304@itemx -falign-loops=@var{n}
5305@opindex falign-loops
5306Align loops to a power-of-two boundary, skipping up to @var{n} bytes
5307like @option{-falign-functions}. The hope is that the loop will be
5308executed many times, which will make up for any execution of the dummy
5309operations.
5310
5311@option{-fno-align-loops} and @option{-falign-loops=1} are
5312equivalent and mean that loops will not be aligned.
5313
5314If @var{n} is not specified or is zero, use a machine-dependent default.
5315
5316Enabled at levels @option{-O2}, @option{-O3}.
5317
5318@item -falign-jumps
5319@itemx -falign-jumps=@var{n}
5320@opindex falign-jumps
5321Align branch targets to a power-of-two boundary, for branch targets
5322where the targets can only be reached by jumping, skipping up to @var{n}
5323bytes like @option{-falign-functions}. In this case, no dummy operations
5324need be executed.
5325
5326@option{-fno-align-jumps} and @option{-falign-jumps=1} are
5327equivalent and mean that loops will not be aligned.
5328
5329If @var{n} is not specified or is zero, use a machine-dependent default.
5330
5331Enabled at levels @option{-O2}, @option{-O3}.
5332
5333@item -funit-at-a-time
5334@opindex funit-at-a-time
5335Parse the whole compilation unit before starting to produce code.
5336This allows some extra optimizations to take place but consumes
5337more memory (in general). There are some compatibility issues
5338with @emph{unit-at-a-time} mode:
5339@itemize @bullet
5340@item
5341enabling @emph{unit-at-a-time} mode may change the order
5342in which functions, variables, and top-level @code{asm} statements
5343are emitted, and will likely break code relying on some particular
5344ordering. The majority of such top-level @code{asm} statements,
5345though, can be replaced by @code{section} attributes. The
5346@option{fno-toplevel-reorder} option may be used to keep the ordering
5347used in the input file, at the cost of some optimizations.
5348
5349@item
5350@emph{unit-at-a-time} mode removes unreferenced static variables
5351and functions. This may result in undefined references
5352when an @code{asm} statement refers directly to variables or functions
5353that are otherwise unused. In that case either the variable/function
5354shall be listed as an operand of the @code{asm} statement operand or,
5355in the case of top-level @code{asm} statements the attribute @code{used}
5356shall be used on the declaration.
5357
5358@item
5359Static functions now can use non-standard passing conventions that
5360may break @code{asm} statements calling functions directly. Again,
5361attribute @code{used} will prevent this behavior.
5362@end itemize
5363
5364As a temporary workaround, @option{-fno-unit-at-a-time} can be used,
5365but this scheme may not be supported by future releases of GCC@.
5366
5367Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5368
5369@item -fno-toplevel-reorder
5370Do not reorder top-level functions, variables, and @code{asm}
5371statements. Output them in the same order that they appear in the
5372input file. When this option is used, unreferenced static variables
5373will not be removed. This option is intended to support existing code
5374which relies on a particular ordering. For new code, it is better to
5375use attributes.
5376
5377@item -fweb
5378@opindex fweb
5379Constructs webs as commonly used for register allocation purposes and assign
5380each web individual pseudo register. This allows the register allocation pass
5381to operate on pseudos directly, but also strengthens several other optimization
5382passes, such as CSE, loop optimizer and trivial dead code remover. It can,
5383however, make debugging impossible, since variables will no longer stay in a
5384``home register''.
5385
5386Enabled by default with @option{-funroll-loops}.
5387
5388@item -fwhole-program
5389@opindex fwhole-program
5390Assume that the current compilation unit represents whole program being
5391compiled. All public functions and variables with the exception of @code{main}
5392and those merged by attribute @code{externally_visible} become static functions
5393and in a affect gets more aggressively optimized by interprocedural optimizers.
5394While this option is equivalent to proper use of @code{static} keyword for
5395programs consisting of single file, in combination with option
5396@option{--combine} this flag can be used to compile most of smaller scale C
5397programs since the functions and variables become local for the whole combined
5398compilation unit, not for the single source file itself.
5399
5400
5401@item -fno-cprop-registers
5402@opindex fno-cprop-registers
5403After register allocation and post-register allocation instruction splitting,
5404we perform a copy-propagation pass to try to reduce scheduling dependencies
5405and occasionally eliminate the copy.
5406
5407Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5408
5409@item -fprofile-generate
5410@opindex fprofile-generate
5411
5412Enable options usually used for instrumenting application to produce
5413profile useful for later recompilation with profile feedback based
5414optimization. You must use @option{-fprofile-generate} both when
5415compiling and when linking your program.
5416
5417The following options are enabled: @code{-fprofile-arcs}, @code{-fprofile-values}, @code{-fvpt}.
5418
5419@item -fprofile-use
5420@opindex fprofile-use
5421Enable profile feedback directed optimizations, and optimizations
5422generally profitable only with profile feedback available.
5423
5424The following options are enabled: @code{-fbranch-probabilities}, @code{-fvpt},
5425@code{-funroll-loops}, @code{-fpeel-loops}, @code{-ftracer}
5426
5427@end table
5428
5429The following options control compiler behavior regarding floating
5430point arithmetic. These options trade off between speed and
5431correctness. All must be specifically enabled.
5432
5433@table @gcctabopt
5434@item -ffloat-store
5435@opindex ffloat-store
5436Do not store floating point variables in registers, and inhibit other
5437options that might change whether a floating point value is taken from a
5438register or memory.
5439
5440@cindex floating point precision
5441This option prevents undesirable excess precision on machines such as
5442the 68000 where the floating registers (of the 68881) keep more
5443precision than a @code{double} is supposed to have. Similarly for the
5444x86 architecture. For most programs, the excess precision does only
5445good, but a few programs rely on the precise definition of IEEE floating
5446point. Use @option{-ffloat-store} for such programs, after modifying
5447them to store all pertinent intermediate computations into variables.
5448
5449@item -ffast-math
5450@opindex ffast-math
5451Sets @option{-fno-math-errno}, @option{-funsafe-math-optimizations}, @*
5452@option{-fno-trapping-math}, @option{-ffinite-math-only},
5453@option{-fno-rounding-math}, @option{-fno-signaling-nans}
5454and @option{fcx-limited-range}.
5455
5456This option causes the preprocessor macro @code{__FAST_MATH__} to be defined.
5457
5458This option should never be turned on by any @option{-O} option since
5459it can result in incorrect output for programs which depend on
5460an exact implementation of IEEE or ISO rules/specifications for
5461math functions.
5462
5463@item -fno-math-errno
5464@opindex fno-math-errno
5465Do not set ERRNO after calling math functions that are executed
5466with a single instruction, e.g., sqrt. A program that relies on
5467IEEE exceptions for math error handling may want to use this flag
5468for speed while maintaining IEEE arithmetic compatibility.
5469
5470This option should never be turned on by any @option{-O} option since
5471it can result in incorrect output for programs which depend on
5472an exact implementation of IEEE or ISO rules/specifications for
5473math functions.
5474
5475The default is @option{-fmath-errno}.
5476
5477On Darwin and FreeBSD systems, the math library never sets @code{errno}.
5478There is therefore
5479no reason for the compiler to consider the possibility that it might,
5480and @option{-fno-math-errno} is the default.
5481
5482@item -funsafe-math-optimizations
5483@opindex funsafe-math-optimizations
5484Allow optimizations for floating-point arithmetic that (a) assume
5485that arguments and results are valid and (b) may violate IEEE or
5486ANSI standards. When used at link-time, it may include libraries
5487or startup files that change the default FPU control word or other
5488similar optimizations.
5489
5490This option should never be turned on by any @option{-O} option since
5491it can result in incorrect output for programs which depend on
5492an exact implementation of IEEE or ISO rules/specifications for
5493math functions.
5494
5495The default is @option{-fno-unsafe-math-optimizations}.
5496
5497@item -ffinite-math-only
5498@opindex ffinite-math-only
5499Allow optimizations for floating-point arithmetic that assume
5500that arguments and results are not NaNs or +-Infs.
5501
5502This option should never be turned on by any @option{-O} option since
5503it can result in incorrect output for programs which depend on
5504an exact implementation of IEEE or ISO rules/specifications.
5505
5506The default is @option{-fno-finite-math-only}.
5507
5508@item -fno-trapping-math
5509@opindex fno-trapping-math
5510Compile code assuming that floating-point operations cannot generate
5511user-visible traps. These traps include division by zero, overflow,
5512underflow, inexact result and invalid operation. This option implies
5513@option{-fno-signaling-nans}. Setting this option may allow faster
5514code if one relies on ``non-stop'' IEEE arithmetic, for example.
5515
5516This option should never be turned on by any @option{-O} option since
5517it can result in incorrect output for programs which depend on
5518an exact implementation of IEEE or ISO rules/specifications for
5519math functions.
5520
5521The default is @option{-ftrapping-math}.
5522
5523@item -frounding-math
5524@opindex frounding-math
5525Disable transformations and optimizations that assume default floating
5526point rounding behavior. This is round-to-zero for all floating point
5527to integer conversions, and round-to-nearest for all other arithmetic
5528truncations. This option should be specified for programs that change
5529the FP rounding mode dynamically, or that may be executed with a
5530non-default rounding mode. This option disables constant folding of
5531floating point expressions at compile-time (which may be affected by
5532rounding mode) and arithmetic transformations that are unsafe in the
5533presence of sign-dependent rounding modes.
5534
5535The default is @option{-fno-rounding-math}.
5536
5537This option is experimental and does not currently guarantee to
5538disable all GCC optimizations that are affected by rounding mode.
5539Future versions of GCC may provide finer control of this setting
5540using C99's @code{FENV_ACCESS} pragma. This command line option
5541will be used to specify the default state for @code{FENV_ACCESS}.
5542
5543@item -frtl-abstract-sequences
5544@opindex frtl-abstract-sequences
5545It is a size optimization method. This option is to find identical
5546sequences of code, which can be turned into pseudo-procedures and
5547then replace all occurrences with calls to the newly created
5548subroutine. It is kind of an opposite of @option{-finline-functions}.
5549This optimization runs at RTL level.
5550
5551@item -fsignaling-nans
5552@opindex fsignaling-nans
5553Compile code assuming that IEEE signaling NaNs may generate user-visible
5554traps during floating-point operations. Setting this option disables
5555optimizations that may change the number of exceptions visible with
5556signaling NaNs. This option implies @option{-ftrapping-math}.
5557
5558This option causes the preprocessor macro @code{__SUPPORT_SNAN__} to
5559be defined.
5560
5561The default is @option{-fno-signaling-nans}.
5562
5563This option is experimental and does not currently guarantee to
5564disable all GCC optimizations that affect signaling NaN behavior.
5565
5566@item -fsingle-precision-constant
5567@opindex fsingle-precision-constant
5568Treat floating point constant as single precision constant instead of
5569implicitly converting it to double precision constant.
5570
5571@item -fcx-limited-range
5572@itemx -fno-cx-limited-range
5573@opindex fcx-limited-range
5574@opindex fno-cx-limited-range
5575When enabled, this option states that a range reduction step is not
5576needed when performing complex division. The default is
5577@option{-fno-cx-limited-range}, but is enabled by @option{-ffast-math}.
5578
5579This option controls the default setting of the ISO C99
5580@code{CX_LIMITED_RANGE} pragma. Nevertheless, the option applies to
5581all languages.
5582
5583@end table
5584
5585The following options control optimizations that may improve
5586performance, but are not enabled by any @option{-O} options. This
5587section includes experimental options that may produce broken code.
5588
5589@table @gcctabopt
5590@item -fbranch-probabilities
5591@opindex fbranch-probabilities
5592After running a program compiled with @option{-fprofile-arcs}
5593(@pxref{Debugging Options,, Options for Debugging Your Program or
5594@command{gcc}}), you can compile it a second time using
5595@option{-fbranch-probabilities}, to improve optimizations based on
5596the number of times each branch was taken. When the program
5597compiled with @option{-fprofile-arcs} exits it saves arc execution
5598counts to a file called @file{@var{sourcename}.gcda} for each source
5599file The information in this data file is very dependent on the
5600structure of the generated code, so you must use the same source code
5601and the same optimization options for both compilations.
5602
5603With @option{-fbranch-probabilities}, GCC puts a
5604@samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}.
5605These can be used to improve optimization. Currently, they are only
5606used in one place: in @file{reorg.c}, instead of guessing which path a
5607branch is mostly to take, the @samp{REG_BR_PROB} values are used to
5608exactly determine which path is taken more often.
5609
5610@item -fprofile-values
5611@opindex fprofile-values
5612If combined with @option{-fprofile-arcs}, it adds code so that some
5613data about values of expressions in the program is gathered.
5614
5615With @option{-fbranch-probabilities}, it reads back the data gathered
5616from profiling values of expressions and adds @samp{REG_VALUE_PROFILE}
5617notes to instructions for their later usage in optimizations.
5618
5619Enabled with @option{-fprofile-generate} and @option{-fprofile-use}.
5620
5621@item -fvpt
5622@opindex fvpt
5623If combined with @option{-fprofile-arcs}, it instructs the compiler to add
5624a code to gather information about values of expressions.
5625
5626With @option{-fbranch-probabilities}, it reads back the data gathered
5627and actually performs the optimizations based on them.
5628Currently the optimizations include specialization of division operation
5629using the knowledge about the value of the denominator.
5630
5631@item -frename-registers
5632@opindex frename-registers
5633Attempt to avoid false dependencies in scheduled code by making use
5634of registers left over after register allocation. This optimization
5635will most benefit processors with lots of registers. Depending on the
5636debug information format adopted by the target, however, it can
5637make debugging impossible, since variables will no longer stay in
5638a ``home register''.
5639
5640Enabled by default with @option{-funroll-loops}.
5641
5642@item -ftracer
5643@opindex ftracer
5644Perform tail duplication to enlarge superblock size. This transformation
5645simplifies the control flow of the function allowing other optimizations to do
5646better job.
5647
5648Enabled with @option{-fprofile-use}.
5649
5650@item -funroll-loops
5651@opindex funroll-loops
5652Unroll loops whose number of iterations can be determined at compile time or
5653upon entry to the loop. @option{-funroll-loops} implies
5654@option{-frerun-cse-after-loop}, @option{-fweb} and @option{-frename-registers}.
5655It also turns on complete loop peeling (i.e.@: complete removal of loops with
5656small constant number of iterations). This option makes code larger, and may
5657or may not make it run faster.
5658
5659Enabled with @option{-fprofile-use}.
5660
5661@item -funroll-all-loops
5662@opindex funroll-all-loops
5663Unroll all loops, even if their number of iterations is uncertain when
5664the loop is entered. This usually makes programs run more slowly.
5665@option{-funroll-all-loops} implies the same options as
5666@option{-funroll-loops}.
5667
5668@item -fpeel-loops
5669@opindex fpeel-loops
5670Peels the loops for that there is enough information that they do not
5671roll much (from profile feedback). It also turns on complete loop peeling
5672(i.e.@: complete removal of loops with small constant number of iterations).
5673
5674Enabled with @option{-fprofile-use}.
5675
5676@item -fmove-loop-invariants
5677@opindex fmove-loop-invariants
5678Enables the loop invariant motion pass in the RTL loop optimizer. Enabled
5679at level @option{-O1}
5680
5681@item -funswitch-loops
5682@opindex funswitch-loops
5683Move branches with loop invariant conditions out of the loop, with duplicates
5684of the loop on both branches (modified according to result of the condition).
5685
5686@item -ffunction-sections
5687@itemx -fdata-sections
5688@opindex ffunction-sections
5689@opindex fdata-sections
5690Place each function or data item into its own section in the output
5691file if the target supports arbitrary sections. The name of the
5692function or the name of the data item determines the section's name
5693in the output file.
5694
5695Use these options on systems where the linker can perform optimizations
5696to improve locality of reference in the instruction space. Most systems
5697using the ELF object format and SPARC processors running Solaris 2 have
5698linkers with such optimizations. AIX may have these optimizations in
5699the future.
5700
5701Only use these options when there are significant benefits from doing
5702so. When you specify these options, the assembler and linker will
5703create larger object and executable files and will also be slower.
5704You will not be able to use @code{gprof} on all systems if you
5705specify this option and you may have problems with debugging if
5706you specify both this option and @option{-g}.
5707
5708@item -fbranch-target-load-optimize
5709@opindex fbranch-target-load-optimize
5710Perform branch target register load optimization before prologue / epilogue
5711threading.
5712The use of target registers can typically be exposed only during reload,
5713thus hoisting loads out of loops and doing inter-block scheduling needs
5714a separate optimization pass.
5715
5716@item -fbranch-target-load-optimize2
5717@opindex fbranch-target-load-optimize2
5718Perform branch target register load optimization after prologue / epilogue
5719threading.
5720
5721@item -fbtr-bb-exclusive
5722@opindex fbtr-bb-exclusive
5723When performing branch target register load optimization, don't reuse
5724branch target registers in within any basic block.
5725
5726@item -fstack-protector
5727Emit extra code to check for buffer overflows, such as stack smashing
5728attacks. This is done by adding a guard variable to functions with
5729vulnerable objects. This includes functions that call alloca, and
5730functions with buffers larger than 8 bytes. The guards are initialized
5731when a function is entered and then checked when the function exits.
5732If a guard check fails, an error message is printed and the program exits.
5733
5734@item -fstack-protector-all
5735Like @option{-fstack-protector} except that all functions are protected.
5736
5737@item -fsection-anchors
5738@opindex fsection-anchors
5739Try to reduce the number of symbolic address calculations by using
5740shared ``anchor'' symbols to address nearby objects. This transformation
5741can help to reduce the number of GOT entries and GOT accesses on some
5742targets.
5743
5744For example, the implementation of the following function @code{foo}:
5745
5746@smallexample
5747static int a, b, c;
5748int foo (void) @{ return a + b + c; @}
5749@end smallexample
5750
5751would usually calculate the addresses of all three variables, but if you
5752compile it with @option{-fsection-anchors}, it will access the variables
5753from a common anchor point instead. The effect is similar to the
5754following pseudocode (which isn't valid C):
5755
5756@smallexample
5757int foo (void)
5758@{
5759 register int *xr = &x;
5760 return xr[&a - &x] + xr[&b - &x] + xr[&c - &x];
5761@}
5762@end smallexample
5763
5764Not all targets support this option.
5765
5766@item --param @var{name}=@var{value}
5767@opindex param
5768In some places, GCC uses various constants to control the amount of
5769optimization that is done. For example, GCC will not inline functions
5770that contain more that a certain number of instructions. You can
5771control some of these constants on the command-line using the
5772@option{--param} option.
5773
5774The names of specific parameters, and the meaning of the values, are
5775tied to the internals of the compiler, and are subject to change
5776without notice in future releases.
5777
5778In each case, the @var{value} is an integer. The allowable choices for
5779@var{name} are given in the following table:
5780
5781@table @gcctabopt
5782@item salias-max-implicit-fields
5783The maximum number of fields in a variable without direct
5784structure accesses for which structure aliasing will consider trying
5785to track each field. The default is 5
5786
5787@item salias-max-array-elements
5788The maximum number of elements an array can have and its elements
5789still be tracked individually by structure aliasing. The default is 4
5790
5791@item sra-max-structure-size
5792The maximum structure size, in bytes, at which the scalar replacement
5793of aggregates (SRA) optimization will perform block copies. The
5794default value, 0, implies that GCC will select the most appropriate
5795size itself.
5796
5797@item sra-field-structure-ratio
5798The threshold ratio (as a percentage) between instantiated fields and
5799the complete structure size. We say that if the ratio of the number
5800of bytes in instantiated fields to the number of bytes in the complete
5801structure exceeds this parameter, then block copies are not used. The
5802default is 75.
5803
5804@item max-crossjump-edges
5805The maximum number of incoming edges to consider for crossjumping.
5806The algorithm used by @option{-fcrossjumping} is @math{O(N^2)} in
5807the number of edges incoming to each block. Increasing values mean
5808more aggressive optimization, making the compile time increase with
5809probably small improvement in executable size.
5810
5811@item min-crossjump-insns
5812The minimum number of instructions which must be matched at the end
5813of two blocks before crossjumping will be performed on them. This
5814value is ignored in the case where all instructions in the block being
5815crossjumped from are matched. The default value is 5.
5816
5817@item max-grow-copy-bb-insns
5818The maximum code size expansion factor when copying basic blocks
5819instead of jumping. The expansion is relative to a jump instruction.
5820The default value is 8.
5821
5822@item max-goto-duplication-insns
5823The maximum number of instructions to duplicate to a block that jumps
5824to a computed goto. To avoid @math{O(N^2)} behavior in a number of
5825passes, GCC factors computed gotos early in the compilation process,
5826and unfactors them as late as possible. Only computed jumps at the
5827end of a basic blocks with no more than max-goto-duplication-insns are
5828unfactored. The default value is 8.
5829
5830@item max-delay-slot-insn-search
5831The maximum number of instructions to consider when looking for an
5832instruction to fill a delay slot. If more than this arbitrary number of
5833instructions is searched, the time savings from filling the delay slot
5834will be minimal so stop searching. Increasing values mean more
5835aggressive optimization, making the compile time increase with probably
5836small improvement in executable run time.
5837
5838@item max-delay-slot-live-search
5839When trying to fill delay slots, the maximum number of instructions to
5840consider when searching for a block with valid live register
5841information. Increasing this arbitrarily chosen value means more
5842aggressive optimization, increasing the compile time. This parameter
5843should be removed when the delay slot code is rewritten to maintain the
5844control-flow graph.
5845
5846@item max-gcse-memory
5847The approximate maximum amount of memory that will be allocated in
5848order to perform the global common subexpression elimination
5849optimization. If more memory than specified is required, the
5850optimization will not be done.
5851
5852@item max-gcse-passes
5853The maximum number of passes of GCSE to run. The default is 1.
5854
5855@item max-pending-list-length
5856The maximum number of pending dependencies scheduling will allow
5857before flushing the current state and starting over. Large functions
5858with few branches or calls can create excessively large lists which
5859needlessly consume memory and resources.
5860
5861@item max-inline-insns-single
5862Several parameters control the tree inliner used in gcc.
5863This number sets the maximum number of instructions (counted in GCC's
5864internal representation) in a single function that the tree inliner
5865will consider for inlining. This only affects functions declared
5866inline and methods implemented in a class declaration (C++).
5867The default value is 450.
5868
5869@item max-inline-insns-auto
5870When you use @option{-finline-functions} (included in @option{-O3}),
5871a lot of functions that would otherwise not be considered for inlining
5872by the compiler will be investigated. To those functions, a different
5873(more restrictive) limit compared to functions declared inline can
5874be applied.
5875The default value is 90.
5876
5877@item large-function-insns
5878The limit specifying really large functions. For functions larger than this
5879limit after inlining inlining is constrained by
5880@option{--param large-function-growth}. This parameter is useful primarily
5881to avoid extreme compilation time caused by non-linear algorithms used by the
5882backend.
5883This parameter is ignored when @option{-funit-at-a-time} is not used.
5884The default value is 2700.
5885
5886@item large-function-growth
5887Specifies maximal growth of large function caused by inlining in percents.
5888This parameter is ignored when @option{-funit-at-a-time} is not used.
5889The default value is 100 which limits large function growth to 2.0 times
5890the original size.
5891
5892@item large-unit-insns
5893The limit specifying large translation unit. Growth caused by inlining of
5894units larger than this limit is limited by @option{--param inline-unit-growth}.
5895For small units this might be too tight (consider unit consisting of function A
5896that is inline and B that just calls A three time. If B is small relative to
5897A, the growth of unit is 300\% and yet such inlining is very sane. For very
5898large units consisting of small inlininable functions however the overall unit
5899growth limit is needed to avoid exponential explosion of code size. Thus for
5900smaller units, the size is increased to @option{--param large-unit-insns}
5901before applying @option{--param inline-unit-growth}. The default is 10000
5902
5903@item inline-unit-growth
5904Specifies maximal overall growth of the compilation unit caused by inlining.
5905This parameter is ignored when @option{-funit-at-a-time} is not used.
5906The default value is 50 which limits unit growth to 1.5 times the original
5907size.
5908
5909@item max-inline-insns-recursive
5910@itemx max-inline-insns-recursive-auto
5911Specifies maximum number of instructions out-of-line copy of self recursive inline
5912function can grow into by performing recursive inlining.
5913
5914For functions declared inline @option{--param max-inline-insns-recursive} is
5915taken into account. For function not declared inline, recursive inlining
5916happens only when @option{-finline-functions} (included in @option{-O3}) is
5917enabled and @option{--param max-inline-insns-recursive-auto} is used. The
5918default value is 450.
5919
5920@item max-inline-recursive-depth
5921@itemx max-inline-recursive-depth-auto
5922Specifies maximum recursion depth used by the recursive inlining.
5923
5924For functions declared inline @option{--param max-inline-recursive-depth} is
5925taken into account. For function not declared inline, recursive inlining
5926happens only when @option{-finline-functions} (included in @option{-O3}) is
5927enabled and @option{--param max-inline-recursive-depth-auto} is used. The
5928default value is 450.
5929
5930@item min-inline-recursive-probability
5931Recursive inlining is profitable only for function having deep recursion
5932in average and can hurt for function having little recursion depth by
5933increasing the prologue size or complexity of function body to other
5934optimizers.
5935
5936When profile feedback is available (see @option{-fprofile-generate}) the actual
5937recursion depth can be guessed from probability that function will recurse via
5938given call expression. This parameter limits inlining only to call expression
5939whose probability exceeds given threshold (in percents). The default value is
594010.
5941
5942@item inline-call-cost
5943Specify cost of call instruction relative to simple arithmetics operations
5944(having cost of 1). Increasing this cost disqualifies inlining of non-leaf
5945functions and at the same time increases size of leaf function that is believed to
5946reduce function size by being inlined. In effect it increases amount of
5947inlining for code having large abstraction penalty (many functions that just
5948pass the arguments to other functions) and decrease inlining for code with low
5949abstraction penalty. The default value is 16.
5950
5951@item max-unrolled-insns
5952The maximum number of instructions that a loop should have if that loop
5953is unrolled, and if the loop is unrolled, it determines how many times
5954the loop code is unrolled.
5955
5956@item max-average-unrolled-insns
5957The maximum number of instructions biased by probabilities of their execution
5958that a loop should have if that loop is unrolled, and if the loop is unrolled,
5959it determines how many times the loop code is unrolled.
5960
5961@item max-unroll-times
5962The maximum number of unrollings of a single loop.
5963
5964@item max-peeled-insns
5965The maximum number of instructions that a loop should have if that loop
5966is peeled, and if the loop is peeled, it determines how many times
5967the loop code is peeled.
5968
5969@item max-peel-times
5970The maximum number of peelings of a single loop.
5971
5972@item max-completely-peeled-insns
5973The maximum number of insns of a completely peeled loop.
5974
5975@item max-completely-peel-times
5976The maximum number of iterations of a loop to be suitable for complete peeling.
5977
5978@item max-unswitch-insns
5979The maximum number of insns of an unswitched loop.
5980
5981@item max-unswitch-level
5982The maximum number of branches unswitched in a single loop.
5983
5984@item lim-expensive
5985The minimum cost of an expensive expression in the loop invariant motion.
5986
5987@item iv-consider-all-candidates-bound
5988Bound on number of candidates for induction variables below that
5989all candidates are considered for each use in induction variable
5990optimizations. Only the most relevant candidates are considered
5991if there are more candidates, to avoid quadratic time complexity.
5992
5993@item iv-max-considered-uses
5994The induction variable optimizations give up on loops that contain more
5995induction variable uses.
5996
5997@item iv-always-prune-cand-set-bound
5998If number of candidates in the set is smaller than this value,
5999we always try to remove unnecessary ivs from the set during its
6000optimization when a new iv is added to the set.
6001
6002@item scev-max-expr-size
6003Bound on size of expressions used in the scalar evolutions analyzer.
6004Large expressions slow the analyzer.
6005
6006@item vect-max-version-checks
6007The maximum number of runtime checks that can be performed when doing
6008loop versioning in the vectorizer. See option ftree-vect-loop-version
6009for more information.
6010
6011@item max-iterations-to-track
6012
6013The maximum number of iterations of a loop the brute force algorithm
6014for analysis of # of iterations of the loop tries to evaluate.
6015
6016@item hot-bb-count-fraction
6017Select fraction of the maximal count of repetitions of basic block in program
6018given basic block needs to have to be considered hot.
6019
6020@item hot-bb-frequency-fraction
6021Select fraction of the maximal frequency of executions of basic block in
6022function given basic block needs to have to be considered hot
6023
6024@item max-predicted-iterations
6025The maximum number of loop iterations we predict statically. This is useful
6026in cases where function contain single loop with known bound and other loop
6027with unknown. We predict the known number of iterations correctly, while
6028the unknown number of iterations average to roughly 10. This means that the
6029loop without bounds would appear artificially cold relative to the other one.
6030
6031@item tracer-dynamic-coverage
6032@itemx tracer-dynamic-coverage-feedback
6033
6034This value is used to limit superblock formation once the given percentage of
6035executed instructions is covered. This limits unnecessary code size
6036expansion.
6037
6038The @option{tracer-dynamic-coverage-feedback} is used only when profile
6039feedback is available. The real profiles (as opposed to statically estimated
6040ones) are much less balanced allowing the threshold to be larger value.
6041
6042@item tracer-max-code-growth
6043Stop tail duplication once code growth has reached given percentage. This is
6044rather hokey argument, as most of the duplicates will be eliminated later in
6045cross jumping, so it may be set to much higher values than is the desired code
6046growth.
6047
6048@item tracer-min-branch-ratio
6049
6050Stop reverse growth when the reverse probability of best edge is less than this
6051threshold (in percent).
6052
6053@item tracer-min-branch-ratio
6054@itemx tracer-min-branch-ratio-feedback
6055
6056Stop forward growth if the best edge do have probability lower than this
6057threshold.
6058
6059Similarly to @option{tracer-dynamic-coverage} two values are present, one for
6060compilation for profile feedback and one for compilation without. The value
6061for compilation with profile feedback needs to be more conservative (higher) in
6062order to make tracer effective.
6063
6064@item max-cse-path-length
6065
6066Maximum number of basic blocks on path that cse considers. The default is 10.
6067
6068@item max-cse-insns
6069The maximum instructions CSE process before flushing. The default is 1000.
6070
6071@item global-var-threshold
6072
6073Counts the number of function calls (@var{n}) and the number of
6074call-clobbered variables (@var{v}). If @var{n}x@var{v} is larger than this limit, a
6075single artificial variable will be created to represent all the
6076call-clobbered variables at function call sites. This artificial
6077variable will then be made to alias every call-clobbered variable.
6078(done as @code{int * size_t} on the host machine; beware overflow).
6079
6080@item max-aliased-vops
6081
6082Maximum number of virtual operands allowed to represent aliases
6083before triggering the alias grouping heuristic. Alias grouping
6084reduces compile times and memory consumption needed for aliasing at
6085the expense of precision loss in alias information.
6086
6087@item ggc-min-expand
6088
6089GCC uses a garbage collector to manage its own memory allocation. This
6090parameter specifies the minimum percentage by which the garbage
6091collector's heap should be allowed to expand between collections.
6092Tuning this may improve compilation speed; it has no effect on code
6093generation.
6094
6095The default is 30% + 70% * (RAM/1GB) with an upper bound of 100% when
6096RAM >= 1GB@. If @code{getrlimit} is available, the notion of "RAM" is
6097the smallest of actual RAM and @code{RLIMIT_DATA} or @code{RLIMIT_AS}. If
6098GCC is not able to calculate RAM on a particular platform, the lower
6099bound of 30% is used. Setting this parameter and
6100@option{ggc-min-heapsize} to zero causes a full collection to occur at
6101every opportunity. This is extremely slow, but can be useful for
6102debugging.
6103
6104@item ggc-min-heapsize
6105
6106Minimum size of the garbage collector's heap before it begins bothering
6107to collect garbage. The first collection occurs after the heap expands
6108by @option{ggc-min-expand}% beyond @option{ggc-min-heapsize}. Again,
6109tuning this may improve compilation speed, and has no effect on code
6110generation.
6111
6112The default is the smaller of RAM/8, RLIMIT_RSS, or a limit which
6113tries to ensure that RLIMIT_DATA or RLIMIT_AS are not exceeded, but
6114with a lower bound of 4096 (four megabytes) and an upper bound of
6115131072 (128 megabytes). If GCC is not able to calculate RAM on a
6116particular platform, the lower bound is used. Setting this parameter
6117very large effectively disables garbage collection. Setting this
6118parameter and @option{ggc-min-expand} to zero causes a full collection
6119to occur at every opportunity.
6120
6121@item max-reload-search-insns
6122The maximum number of instruction reload should look backward for equivalent
6123register. Increasing values mean more aggressive optimization, making the
6124compile time increase with probably slightly better performance. The default
6125value is 100.
6126
6127@item max-cselib-memory-locations
6128The maximum number of memory locations cselib should take into account.
6129Increasing values mean more aggressive optimization, making the compile time
6130increase with probably slightly better performance. The default value is 500.
6131
6132@item max-flow-memory-locations
6133Similar as @option{max-cselib-memory-locations} but for dataflow liveness.
6134The default value is 100.
6135
6136@item reorder-blocks-duplicate
6137@itemx reorder-blocks-duplicate-feedback
6138
6139Used by basic block reordering pass to decide whether to use unconditional
6140branch or duplicate the code on its destination. Code is duplicated when its
6141estimated size is smaller than this value multiplied by the estimated size of
6142unconditional jump in the hot spots of the program.
6143
6144The @option{reorder-block-duplicate-feedback} is used only when profile
6145feedback is available and may be set to higher values than
6146@option{reorder-block-duplicate} since information about the hot spots is more
6147accurate.
6148
6149@item max-sched-ready-insns
6150The maximum number of instructions ready to be issued the scheduler should
6151consider at any given time during the first scheduling pass. Increasing
6152values mean more thorough searches, making the compilation time increase
6153with probably little benefit. The default value is 100.
6154
6155@item max-sched-region-blocks
6156The maximum number of blocks in a region to be considered for
6157interblock scheduling. The default value is 10.
6158
6159@item max-sched-region-insns
6160The maximum number of insns in a region to be considered for
6161interblock scheduling. The default value is 100.
6162
6163@item min-spec-prob
6164The minimum probability (in percents) of reaching a source block
6165for interblock speculative scheduling. The default value is 40.
6166
6167@item max-sched-extend-regions-iters
6168The maximum number of iterations through CFG to extend regions.
61690 - disable region extension,
6170N - do at most N iterations.
6171The default value is 0.
6172
6173@item max-sched-insn-conflict-delay
6174The maximum conflict delay for an insn to be considered for speculative motion.
6175The default value is 3.
6176
6177@item sched-spec-prob-cutoff
6178The minimal probability of speculation success (in percents), so that
6179speculative insn will be scheduled.
6180The default value is 40.
6181
6182@item max-last-value-rtl
6183
6184The maximum size measured as number of RTLs that can be recorded in an expression
6185in combiner for a pseudo register as last known value of that register. The default
6186is 10000.
6187
6188@item integer-share-limit
6189Small integer constants can use a shared data structure, reducing the
6190compiler's memory usage and increasing its speed. This sets the maximum
6191value of a shared integer constant's. The default value is 256.
6192
6193@item min-virtual-mappings
6194Specifies the minimum number of virtual mappings in the incremental
6195SSA updater that should be registered to trigger the virtual mappings
6196heuristic defined by virtual-mappings-ratio. The default value is
6197100.
6198
6199@item virtual-mappings-ratio
6200If the number of virtual mappings is virtual-mappings-ratio bigger
6201than the number of virtual symbols to be updated, then the incremental
6202SSA updater switches to a full update for those symbols. The default
6203ratio is 3.
6204
6205@item ssp-buffer-size
6206The minimum size of buffers (i.e. arrays) that will receive stack smashing
6207protection when @option{-fstack-protection} is used.
6208
6209@item max-jump-thread-duplication-stmts
6210Maximum number of statements allowed in a block that needs to be
6211duplicated when threading jumps.
6212
6213@item max-fields-for-field-sensitive
6214Maximum number of fields in a structure we will treat in
6215a field sensitive manner during pointer analysis.
6216
6217@end table
6218@end table
6219
6220@node Preprocessor Options
6221@section Options Controlling the Preprocessor
6222@cindex preprocessor options
6223@cindex options, preprocessor
6224
6225These options control the C preprocessor, which is run on each C source
6226file before actual compilation.
6227
6228If you use the @option{-E} option, nothing is done except preprocessing.
6229Some of these options make sense only together with @option{-E} because
6230they cause the preprocessor output to be unsuitable for actual
6231compilation.
6232
6233@table @gcctabopt
6234@opindex Wp
6235You can use @option{-Wp,@var{option}} to bypass the compiler driver
6236and pass @var{option} directly through to the preprocessor. If
6237@var{option} contains commas, it is split into multiple options at the
6238commas. However, many options are modified, translated or interpreted
6239by the compiler driver before being passed to the preprocessor, and
6240@option{-Wp} forcibly bypasses this phase. The preprocessor's direct
6241interface is undocumented and subject to change, so whenever possible
6242you should avoid using @option{-Wp} and let the driver handle the
6243options instead.
6244
6245@item -Xpreprocessor @var{option}
6246@opindex preprocessor
6247Pass @var{option} as an option to the preprocessor. You can use this to
6248supply system-specific preprocessor options which GCC does not know how to
6249recognize.
6250
6251If you want to pass an option that takes an argument, you must use
6252@option{-Xpreprocessor} twice, once for the option and once for the argument.
6253@end table
6254
6255@include cppopts.texi
6256
6257@node Assembler Options
6258@section Passing Options to the Assembler
6259
6260@c prevent bad page break with this line
6261You can pass options to the assembler.
6262
6263@table @gcctabopt
6264@item -Wa,@var{option}
6265@opindex Wa
6266Pass @var{option} as an option to the assembler. If @var{option}
6267contains commas, it is split into multiple options at the commas.
6268
6269@item -Xassembler @var{option}
6270@opindex Xassembler
6271Pass @var{option} as an option to the assembler. You can use this to
6272supply system-specific assembler options which GCC does not know how to
6273recognize.
6274
6275If you want to pass an option that takes an argument, you must use
6276@option{-Xassembler} twice, once for the option and once for the argument.
6277
6278@end table
6279
6280@node Link Options
6281@section Options for Linking
6282@cindex link options
6283@cindex options, linking
6284
6285These options come into play when the compiler links object files into
6286an executable output file. They are meaningless if the compiler is
6287not doing a link step.
6288
6289@table @gcctabopt
6290@cindex file names
6291@item @var{object-file-name}
6292A file name that does not end in a special recognized suffix is
6293considered to name an object file or library. (Object files are
6294distinguished from libraries by the linker according to the file
6295contents.) If linking is done, these object files are used as input
6296to the linker.
6297
6298@item -c
6299@itemx -S
6300@itemx -E
6301@opindex c
6302@opindex S
6303@opindex E
6304If any of these options is used, then the linker is not run, and
6305object file names should not be used as arguments. @xref{Overall
6306Options}.
6307
6308@cindex Libraries
6309@item -l@var{library}
6310@itemx -l @var{library}
6311@opindex l
6312Search the library named @var{library} when linking. (The second
6313alternative with the library as a separate argument is only for
6314POSIX compliance and is not recommended.)
6315
6316It makes a difference where in the command you write this option; the
6317linker searches and processes libraries and object files in the order they
6318are specified. Thus, @samp{foo.o -lz bar.o} searches library @samp{z}
6319after file @file{foo.o} but before @file{bar.o}. If @file{bar.o} refers
6320to functions in @samp{z}, those functions may not be loaded.
6321
6322The linker searches a standard list of directories for the library,
6323which is actually a file named @file{lib@var{library}.a}. The linker
6324then uses this file as if it had been specified precisely by name.
6325
6326The directories searched include several standard system directories
6327plus any that you specify with @option{-L}.
6328
6329Normally the files found this way are library files---archive files
6330whose members are object files. The linker handles an archive file by
6331scanning through it for members which define symbols that have so far
6332been referenced but not defined. But if the file that is found is an
6333ordinary object file, it is linked in the usual fashion. The only
6334difference between using an @option{-l} option and specifying a file name
6335is that @option{-l} surrounds @var{library} with @samp{lib} and @samp{.a}
6336and searches several directories.
6337
6338@item -nostartfiles
6339@opindex nostartfiles
6340Do not use the standard system startup files when linking.
6341The standard system libraries are used normally, unless @option{-nostdlib}
6342or @option{-nodefaultlibs} is used.
6343
6344@item -nodefaultlibs
6345@opindex nodefaultlibs
6346Do not use the standard system libraries when linking.
6347Only the libraries you specify will be passed to the linker.
6348The standard startup files are used normally, unless @option{-nostartfiles}
6349is used. The compiler may generate calls to @code{memcmp},
6350@code{memset}, @code{memcpy} and @code{memmove}.
6351These entries are usually resolved by entries in
6352libc. These entry points should be supplied through some other
6353mechanism when this option is specified.
6354
6355@item -nostdlib
6356@opindex nostdlib
6357Do not use the standard system startup files or libraries when linking.
6358No startup files and only the libraries you specify will be passed to
6359the linker. The compiler may generate calls to @code{memcmp}, @code{memset},
6360@code{memcpy} and @code{memmove}.
6361These entries are usually resolved by entries in
6362libc. These entry points should be supplied through some other
6363mechanism when this option is specified.
6364
6365@cindex @option{-lgcc}, use with @option{-nostdlib}
6366@cindex @option{-nostdlib} and unresolved references
6367@cindex unresolved references and @option{-nostdlib}
6368@cindex @option{-lgcc}, use with @option{-nodefaultlibs}
6369@cindex @option{-nodefaultlibs} and unresolved references
6370@cindex unresolved references and @option{-nodefaultlibs}
6371One of the standard libraries bypassed by @option{-nostdlib} and
6372@option{-nodefaultlibs} is @file{libgcc.a}, a library of internal subroutines
6373that GCC uses to overcome shortcomings of particular machines, or special
6374needs for some languages.
6375(@xref{Interface,,Interfacing to GCC Output,gccint,GNU Compiler
6376Collection (GCC) Internals},
6377for more discussion of @file{libgcc.a}.)
6378In most cases, you need @file{libgcc.a} even when you want to avoid
6379other standard libraries. In other words, when you specify @option{-nostdlib}
6380or @option{-nodefaultlibs} you should usually specify @option{-lgcc} as well.
6381This ensures that you have no unresolved references to internal GCC
6382library subroutines. (For example, @samp{__main}, used to ensure C++
6383constructors will be called; @pxref{Collect2,,@code{collect2}, gccint,
6384GNU Compiler Collection (GCC) Internals}.)
6385
6386@item -pie
6387@opindex pie
6388Produce a position independent executable on targets which support it.
6389For predictable results, you must also specify the same set of options
6390that were used to generate code (@option{-fpie}, @option{-fPIE},
6391or model suboptions) when you specify this option.
6392
6393@item -rdynamic
6394@opindex rdynamic
6395Pass the flag @option{-export-dynamic} to the ELF linker, on targets
6396that support it. This instructs the linker to add all symbols, not
6397only used ones, to the dynamic symbol table. This option is needed
6398for some uses of @code{dlopen} or to allow obtaining backtraces
6399from within a program.
6400
6401@item -s
6402@opindex s
6403Remove all symbol table and relocation information from the executable.
6404
6405@item -static
6406@opindex static
6407On systems that support dynamic linking, this prevents linking with the shared
6408libraries. On other systems, this option has no effect.
6409
6410@item -shared
6411@opindex shared
6412Produce a shared object which can then be linked with other objects to
6413form an executable. Not all systems support this option. For predictable
6414results, you must also specify the same set of options that were used to
6415generate code (@option{-fpic}, @option{-fPIC}, or model suboptions)
6416when you specify this option.@footnote{On some systems, @samp{gcc -shared}
6417needs to build supplementary stub code for constructors to work. On
6418multi-libbed systems, @samp{gcc -shared} must select the correct support
6419libraries to link against. Failing to supply the correct flags may lead
6420to subtle defects. Supplying them in cases where they are not necessary
6421is innocuous.}
6422
6423@item -shared-libgcc
6424@itemx -static-libgcc
6425@opindex shared-libgcc
6426@opindex static-libgcc
6427On systems that provide @file{libgcc} as a shared library, these options
6428force the use of either the shared or static version respectively.
6429If no shared version of @file{libgcc} was built when the compiler was
6430configured, these options have no effect.
6431
6432There are several situations in which an application should use the
6433shared @file{libgcc} instead of the static version. The most common
6434of these is when the application wishes to throw and catch exceptions
6435across different shared libraries. In that case, each of the libraries
6436as well as the application itself should use the shared @file{libgcc}.
6437
6438Therefore, the G++ and GCJ drivers automatically add
6439@option{-shared-libgcc} whenever you build a shared library or a main
6440executable, because C++ and Java programs typically use exceptions, so
6441this is the right thing to do.
6442
6443If, instead, you use the GCC driver to create shared libraries, you may
6444find that they will not always be linked with the shared @file{libgcc}.
6445If GCC finds, at its configuration time, that you have a non-GNU linker
6446or a GNU linker that does not support option @option{--eh-frame-hdr},
6447it will link the shared version of @file{libgcc} into shared libraries
6448by default. Otherwise, it will take advantage of the linker and optimize
6449away the linking with the shared version of @file{libgcc}, linking with
6450the static version of libgcc by default. This allows exceptions to
6451propagate through such shared libraries, without incurring relocation
6452costs at library load time.
6453
6454However, if a library or main executable is supposed to throw or catch
6455exceptions, you must link it using the G++ or GCJ driver, as appropriate
6456for the languages used in the program, or using the option
6457@option{-shared-libgcc}, such that it is linked with the shared
6458@file{libgcc}.
6459
6460@item -symbolic
6461@opindex symbolic
6462Bind references to global symbols when building a shared object. Warn
6463about any unresolved references (unless overridden by the link editor
6464option @samp{-Xlinker -z -Xlinker defs}). Only a few systems support
6465this option.
6466
6467@item -Xlinker @var{option}
6468@opindex Xlinker
6469Pass @var{option} as an option to the linker. You can use this to
6470supply system-specific linker options which GCC does not know how to
6471recognize.
6472
6473If you want to pass an option that takes an argument, you must use
6474@option{-Xlinker} twice, once for the option and once for the argument.
6475For example, to pass @option{-assert definitions}, you must write
6476@samp{-Xlinker -assert -Xlinker definitions}. It does not work to write
6477@option{-Xlinker "-assert definitions"}, because this passes the entire
6478string as a single argument, which is not what the linker expects.
6479
6480@item -Wl,@var{option}
6481@opindex Wl
6482Pass @var{option} as an option to the linker. If @var{option} contains
6483commas, it is split into multiple options at the commas.
6484
6485@item -u @var{symbol}
6486@opindex u
6487Pretend the symbol @var{symbol} is undefined, to force linking of
6488library modules to define it. You can use @option{-u} multiple times with
6489different symbols to force loading of additional library modules.
6490@end table
6491
6492@node Directory Options
6493@section Options for Directory Search
6494@cindex directory options
6495@cindex options, directory search
6496@cindex search path
6497
6498These options specify directories to search for header files, for
6499libraries and for parts of the compiler:
6500
6501@table @gcctabopt
6502@item -I@var{dir}
6503@opindex I
6504Add the directory @var{dir} to the head of the list of directories to be
6505searched for header files. This can be used to override a system header
6506file, substituting your own version, since these directories are
6507searched before the system header file directories. However, you should
6508not use this option to add directories that contain vendor-supplied
6509system header files (use @option{-isystem} for that). If you use more than
6510one @option{-I} option, the directories are scanned in left-to-right
6511order; the standard system directories come after.
6512
6513If a standard system include directory, or a directory specified with
6514@option{-isystem}, is also specified with @option{-I}, the @option{-I}
6515option will be ignored. The directory will still be searched but as a
6516system directory at its normal position in the system include chain.
6517This is to ensure that GCC's procedure to fix buggy system headers and
6518the ordering for the include_next directive are not inadvertently changed.
6519If you really need to change the search order for system directories,
6520use the @option{-nostdinc} and/or @option{-isystem} options.
6521
6522@item -iquote@var{dir}
6523@opindex iquote
6524Add the directory @var{dir} to the head of the list of directories to
6525be searched for header files only for the case of @samp{#include
6526"@var{file}"}; they are not searched for @samp{#include <@var{file}>},
6527otherwise just like @option{-I}.
6528
6529@item -L@var{dir}
6530@opindex L
6531Add directory @var{dir} to the list of directories to be searched
6532for @option{-l}.
6533
6534@item -B@var{prefix}
6535@opindex B
6536This option specifies where to find the executables, libraries,
6537include files, and data files of the compiler itself.
6538
6539The compiler driver program runs one or more of the subprograms
6540@file{cpp}, @file{cc1}, @file{as} and @file{ld}. It tries
6541@var{prefix} as a prefix for each program it tries to run, both with and
6542without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}).
6543
6544For each subprogram to be run, the compiler driver first tries the
6545@option{-B} prefix, if any. If that name is not found, or if @option{-B}
6546was not specified, the driver tries two standard prefixes, which are
6547@file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc/}. If neither of
6548those results in a file name that is found, the unmodified program
6549name is searched for using the directories specified in your
6550@env{PATH} environment variable.
6551
6552The compiler will check to see if the path provided by the @option{-B}
6553refers to a directory, and if necessary it will add a directory
6554separator character at the end of the path.
6555
6556@option{-B} prefixes that effectively specify directory names also apply
6557to libraries in the linker, because the compiler translates these
6558options into @option{-L} options for the linker. They also apply to
6559includes files in the preprocessor, because the compiler translates these
6560options into @option{-isystem} options for the preprocessor. In this case,
6561the compiler appends @samp{include} to the prefix.
6562
6563The run-time support file @file{libgcc.a} can also be searched for using
6564the @option{-B} prefix, if needed. If it is not found there, the two
6565standard prefixes above are tried, and that is all. The file is left
6566out of the link if it is not found by those means.
6567
6568Another way to specify a prefix much like the @option{-B} prefix is to use
6569the environment variable @env{GCC_EXEC_PREFIX}. @xref{Environment
6570Variables}.
6571
6572As a special kludge, if the path provided by @option{-B} is
6573@file{[dir/]stage@var{N}/}, where @var{N} is a number in the range 0 to
65749, then it will be replaced by @file{[dir/]include}. This is to help
6575with boot-strapping the compiler.
6576
6577@item -specs=@var{file}
6578@opindex specs
6579Process @var{file} after the compiler reads in the standard @file{specs}
6580file, in order to override the defaults that the @file{gcc} driver
6581program uses when determining what switches to pass to @file{cc1},
6582@file{cc1plus}, @file{as}, @file{ld}, etc. More than one
6583@option{-specs=@var{file}} can be specified on the command line, and they
6584are processed in order, from left to right.
6585
6586@item --sysroot=@var{dir}
6587@opindex sysroot
6588Use @var{dir} as the logical root directory for headers and libraries.
6589For example, if the compiler would normally search for headers in
6590@file{/usr/include} and libraries in @file{/usr/lib}, it will instead
6591search @file{@var{dir}/usr/include} and @file{@var{dir}/usr/lib}.
6592
6593If you use both this option and the @option{-isysroot} option, then
6594the @option{--sysroot} option will apply to libraries, but the
6595@option{-isysroot} option will apply to header files.
6596
6597The GNU linker (beginning with version 2.16) has the necessary support
6598for this option. If your linker does not support this option, the
6599header file aspect of @option{--sysroot} will still work, but the
6600library aspect will not.
6601
6602@item -I-
6603@opindex I-
6604This option has been deprecated. Please use @option{-iquote} instead for
6605@option{-I} directories before the @option{-I-} and remove the @option{-I-}.
6606Any directories you specify with @option{-I} options before the @option{-I-}
6607option are searched only for the case of @samp{#include "@var{file}"};
6608they are not searched for @samp{#include <@var{file}>}.
6609
6610If additional directories are specified with @option{-I} options after
6611the @option{-I-}, these directories are searched for all @samp{#include}
6612directives. (Ordinarily @emph{all} @option{-I} directories are used
6613this way.)
6614
6615In addition, the @option{-I-} option inhibits the use of the current
6616directory (where the current input file came from) as the first search
6617directory for @samp{#include "@var{file}"}. There is no way to
6618override this effect of @option{-I-}. With @option{-I.} you can specify
6619searching the directory which was current when the compiler was
6620invoked. That is not exactly the same as what the preprocessor does
6621by default, but it is often satisfactory.
6622
6623@option{-I-} does not inhibit the use of the standard system directories
6624for header files. Thus, @option{-I-} and @option{-nostdinc} are
6625independent.
6626@end table
6627
6628@c man end
6629
6630@node Spec Files
6631@section Specifying subprocesses and the switches to pass to them
6632@cindex Spec Files
6633
6634@command{gcc} is a driver program. It performs its job by invoking a
6635sequence of other programs to do the work of compiling, assembling and
6636linking. GCC interprets its command-line parameters and uses these to
6637deduce which programs it should invoke, and which command-line options
6638it ought to place on their command lines. This behavior is controlled
6639by @dfn{spec strings}. In most cases there is one spec string for each
6640program that GCC can invoke, but a few programs have multiple spec
6641strings to control their behavior. The spec strings built into GCC can
6642be overridden by using the @option{-specs=} command-line switch to specify
6643a spec file.
6644
6645@dfn{Spec files} are plaintext files that are used to construct spec
6646strings. They consist of a sequence of directives separated by blank
6647lines. The type of directive is determined by the first non-whitespace
6648character on the line and it can be one of the following:
6649
6650@table @code
6651@item %@var{command}
6652Issues a @var{command} to the spec file processor. The commands that can
6653appear here are:
6654
6655@table @code
6656@item %include <@var{file}>
6657@cindex %include
6658Search for @var{file} and insert its text at the current point in the
6659specs file.
6660
6661@item %include_noerr <@var{file}>
6662@cindex %include_noerr
6663Just like @samp{%include}, but do not generate an error message if the include
6664file cannot be found.
6665
6666@item %rename @var{old_name} @var{new_name}
6667@cindex %rename
6668Rename the spec string @var{old_name} to @var{new_name}.
6669
6670@end table
6671
6672@item *[@var{spec_name}]:
6673This tells the compiler to create, override or delete the named spec
6674string. All lines after this directive up to the next directive or
6675blank line are considered to be the text for the spec string. If this
6676results in an empty string then the spec will be deleted. (Or, if the
6677spec did not exist, then nothing will happened.) Otherwise, if the spec
6678does not currently exist a new spec will be created. If the spec does
6679exist then its contents will be overridden by the text of this
6680directive, unless the first character of that text is the @samp{+}
6681character, in which case the text will be appended to the spec.
6682
6683@item [@var{suffix}]:
6684Creates a new @samp{[@var{suffix}] spec} pair. All lines after this directive
6685and up to the next directive or blank line are considered to make up the
6686spec string for the indicated suffix. When the compiler encounters an
6687input file with the named suffix, it will processes the spec string in
6688order to work out how to compile that file. For example:
6689
6690@smallexample
6691.ZZ:
6692z-compile -input %i
6693@end smallexample
6694
6695This says that any input file whose name ends in @samp{.ZZ} should be
6696passed to the program @samp{z-compile}, which should be invoked with the
6697command-line switch @option{-input} and with the result of performing the
6698@samp{%i} substitution. (See below.)
6699
6700As an alternative to providing a spec string, the text that follows a
6701suffix directive can be one of the following:
6702
6703@table @code
6704@item @@@var{language}
6705This says that the suffix is an alias for a known @var{language}. This is
6706similar to using the @option{-x} command-line switch to GCC to specify a
6707language explicitly. For example:
6708
6709@smallexample
6710.ZZ:
6711@@c++
6712@end smallexample
6713
6714Says that .ZZ files are, in fact, C++ source files.
6715
6716@item #@var{name}
6717This causes an error messages saying:
6718
6719@smallexample
6720@var{name} compiler not installed on this system.
6721@end smallexample
6722@end table
6723
6724GCC already has an extensive list of suffixes built into it.
6725This directive will add an entry to the end of the list of suffixes, but
6726since the list is searched from the end backwards, it is effectively
6727possible to override earlier entries using this technique.
6728
6729@end table
6730
6731GCC has the following spec strings built into it. Spec files can
6732override these strings or create their own. Note that individual
6733targets can also add their own spec strings to this list.
6734
6735@smallexample
6736asm Options to pass to the assembler
6737asm_final Options to pass to the assembler post-processor
6738cpp Options to pass to the C preprocessor
6739cc1 Options to pass to the C compiler
6740cc1plus Options to pass to the C++ compiler
6741endfile Object files to include at the end of the link
6742link Options to pass to the linker
6743lib Libraries to include on the command line to the linker
6744libgcc Decides which GCC support library to pass to the linker
6745linker Sets the name of the linker
6746predefines Defines to be passed to the C preprocessor
6747signed_char Defines to pass to CPP to say whether @code{char} is signed
6748 by default
6749startfile Object files to include at the start of the link
6750@end smallexample
6751
6752Here is a small example of a spec file:
6753
6754@smallexample
6755%rename lib old_lib
6756
6757*lib:
6758--start-group -lgcc -lc -leval1 --end-group %(old_lib)
6759@end smallexample
6760
6761This example renames the spec called @samp{lib} to @samp{old_lib} and
6762then overrides the previous definition of @samp{lib} with a new one.
6763The new definition adds in some extra command-line options before
6764including the text of the old definition.
6765
6766@dfn{Spec strings} are a list of command-line options to be passed to their
6767corresponding program. In addition, the spec strings can contain
6768@samp{%}-prefixed sequences to substitute variable text or to
6769conditionally insert text into the command line. Using these constructs
6770it is possible to generate quite complex command lines.
6771
6772Here is a table of all defined @samp{%}-sequences for spec
6773strings. Note that spaces are not generated automatically around the
6774results of expanding these sequences. Therefore you can concatenate them
6775together or combine them with constant text in a single argument.
6776
6777@table @code
6778@item %%
6779Substitute one @samp{%} into the program name or argument.
6780
6781@item %i
6782Substitute the name of the input file being processed.
6783
6784@item %b
6785Substitute the basename of the input file being processed.
6786This is the substring up to (and not including) the last period
6787and not including the directory.
6788
6789@item %B
6790This is the same as @samp{%b}, but include the file suffix (text after
6791the last period).
6792
6793@item %d
6794Marks the argument containing or following the @samp{%d} as a
6795temporary file name, so that that file will be deleted if GCC exits
6796successfully. Unlike @samp{%g}, this contributes no text to the
6797argument.
6798
6799@item %g@var{suffix}
6800Substitute a file name that has suffix @var{suffix} and is chosen
6801once per compilation, and mark the argument in the same way as
6802@samp{%d}. To reduce exposure to denial-of-service attacks, the file
6803name is now chosen in a way that is hard to predict even when previously
6804chosen file names are known. For example, @samp{%g.s @dots{} %g.o @dots{} %g.s}
6805might turn into @samp{ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s}. @var{suffix} matches
6806the regexp @samp{[.A-Za-z]*} or the special string @samp{%O}, which is
6807treated exactly as if @samp{%O} had been preprocessed. Previously, @samp{%g}
6808was simply substituted with a file name chosen once per compilation,
6809without regard to any appended suffix (which was therefore treated
6810just like ordinary text), making such attacks more likely to succeed.
6811
6812@item %u@var{suffix}
6813Like @samp{%g}, but generates a new temporary file name even if
6814@samp{%u@var{suffix}} was already seen.
6815
6816@item %U@var{suffix}
6817Substitutes the last file name generated with @samp{%u@var{suffix}}, generating a
6818new one if there is no such last file name. In the absence of any
6819@samp{%u@var{suffix}}, this is just like @samp{%g@var{suffix}}, except they don't share
6820the same suffix @emph{space}, so @samp{%g.s @dots{} %U.s @dots{} %g.s @dots{} %U.s}
6821would involve the generation of two distinct file names, one
6822for each @samp{%g.s} and another for each @samp{%U.s}. Previously, @samp{%U} was
6823simply substituted with a file name chosen for the previous @samp{%u},
6824without regard to any appended suffix.
6825
6826@item %j@var{suffix}
6827Substitutes the name of the @code{HOST_BIT_BUCKET}, if any, and if it is
6828writable, and if save-temps is off; otherwise, substitute the name
6829of a temporary file, just like @samp{%u}. This temporary file is not
6830meant for communication between processes, but rather as a junk
6831disposal mechanism.
6832
6833@item %|@var{suffix}
6834@itemx %m@var{suffix}
6835Like @samp{%g}, except if @option{-pipe} is in effect. In that case
6836@samp{%|} substitutes a single dash and @samp{%m} substitutes nothing at
6837all. These are the two most common ways to instruct a program that it
6838should read from standard input or write to standard output. If you
6839need something more elaborate you can use an @samp{%@{pipe:@code{X}@}}
6840construct: see for example @file{f/lang-specs.h}.
6841
6842@item %.@var{SUFFIX}
6843Substitutes @var{.SUFFIX} for the suffixes of a matched switch's args
6844when it is subsequently output with @samp{%*}. @var{SUFFIX} is
6845terminated by the next space or %.
6846
6847@item %w
6848Marks the argument containing or following the @samp{%w} as the
6849designated output file of this compilation. This puts the argument
6850into the sequence of arguments that @samp{%o} will substitute later.
6851
6852@item %o
6853Substitutes the names of all the output files, with spaces
6854automatically placed around them. You should write spaces
6855around the @samp{%o} as well or the results are undefined.
6856@samp{%o} is for use in the specs for running the linker.
6857Input files whose names have no recognized suffix are not compiled
6858at all, but they are included among the output files, so they will
6859be linked.
6860
6861@item %O
6862Substitutes the suffix for object files. Note that this is
6863handled specially when it immediately follows @samp{%g, %u, or %U},
6864because of the need for those to form complete file names. The
6865handling is such that @samp{%O} is treated exactly as if it had already
6866been substituted, except that @samp{%g, %u, and %U} do not currently
6867support additional @var{suffix} characters following @samp{%O} as they would
6868following, for example, @samp{.o}.
6869
6870@item %p
6871Substitutes the standard macro predefinitions for the
6872current target machine. Use this when running @code{cpp}.
6873
6874@item %P
6875Like @samp{%p}, but puts @samp{__} before and after the name of each
6876predefined macro, except for macros that start with @samp{__} or with
6877@samp{_@var{L}}, where @var{L} is an uppercase letter. This is for ISO
6878C@.
6879
6880@item %I
6881Substitute any of @option{-iprefix} (made from @env{GCC_EXEC_PREFIX}),
6882@option{-isysroot} (made from @env{TARGET_SYSTEM_ROOT}),
6883@option{-isystem} (made from @env{COMPILER_PATH} and @option{-B} options)
6884and @option{-imultilib} as necessary.
6885
6886@item %s
6887Current argument is the name of a library or startup file of some sort.
6888Search for that file in a standard list of directories and substitute
6889the full name found.
6890
6891@item %e@var{str}
6892Print @var{str} as an error message. @var{str} is terminated by a newline.
6893Use this when inconsistent options are detected.
6894
6895@item %(@var{name})
6896Substitute the contents of spec string @var{name} at this point.
6897
6898@item %[@var{name}]
6899Like @samp{%(@dots{})} but put @samp{__} around @option{-D} arguments.
6900
6901@item %x@{@var{option}@}
6902Accumulate an option for @samp{%X}.
6903
6904@item %X
6905Output the accumulated linker options specified by @option{-Wl} or a @samp{%x}
6906spec string.
6907
6908@item %Y
6909Output the accumulated assembler options specified by @option{-Wa}.
6910
6911@item %Z
6912Output the accumulated preprocessor options specified by @option{-Wp}.
6913
6914@item %a
6915Process the @code{asm} spec. This is used to compute the
6916switches to be passed to the assembler.
6917
6918@item %A
6919Process the @code{asm_final} spec. This is a spec string for
6920passing switches to an assembler post-processor, if such a program is
6921needed.
6922
6923@item %l
6924Process the @code{link} spec. This is the spec for computing the
6925command line passed to the linker. Typically it will make use of the
6926@samp{%L %G %S %D and %E} sequences.
6927
6928@item %D
6929Dump out a @option{-L} option for each directory that GCC believes might
6930contain startup files. If the target supports multilibs then the
6931current multilib directory will be prepended to each of these paths.
6932
6933@item %L
6934Process the @code{lib} spec. This is a spec string for deciding which
6935libraries should be included on the command line to the linker.
6936
6937@item %G
6938Process the @code{libgcc} spec. This is a spec string for deciding
6939which GCC support library should be included on the command line to the linker.
6940
6941@item %S
6942Process the @code{startfile} spec. This is a spec for deciding which
6943object files should be the first ones passed to the linker. Typically
6944this might be a file named @file{crt0.o}.
6945
6946@item %E
6947Process the @code{endfile} spec. This is a spec string that specifies
6948the last object files that will be passed to the linker.
6949
6950@item %C
6951Process the @code{cpp} spec. This is used to construct the arguments
6952to be passed to the C preprocessor.
6953
6954@item %1
6955Process the @code{cc1} spec. This is used to construct the options to be
6956passed to the actual C compiler (@samp{cc1}).
6957
6958@item %2
6959Process the @code{cc1plus} spec. This is used to construct the options to be
6960passed to the actual C++ compiler (@samp{cc1plus}).
6961
6962@item %*
6963Substitute the variable part of a matched option. See below.
6964Note that each comma in the substituted string is replaced by
6965a single space.
6966
6967@item %<@code{S}
6968Remove all occurrences of @code{-S} from the command line. Note---this
6969command is position dependent. @samp{%} commands in the spec string
6970before this one will see @code{-S}, @samp{%} commands in the spec string
6971after this one will not.
6972
6973@item %:@var{function}(@var{args})
6974Call the named function @var{function}, passing it @var{args}.
6975@var{args} is first processed as a nested spec string, then split
6976into an argument vector in the usual fashion. The function returns
6977a string which is processed as if it had appeared literally as part
6978of the current spec.
6979
6980The following built-in spec functions are provided:
6981
6982@table @code
6983@item @code{if-exists}
6984The @code{if-exists} spec function takes one argument, an absolute
6985pathname to a file. If the file exists, @code{if-exists} returns the
6986pathname. Here is a small example of its usage:
6987
6988@smallexample
6989*startfile:
6990crt0%O%s %:if-exists(crti%O%s) crtbegin%O%s
6991@end smallexample
6992
6993@item @code{if-exists-else}
6994The @code{if-exists-else} spec function is similar to the @code{if-exists}
6995spec function, except that it takes two arguments. The first argument is
6996an absolute pathname to a file. If the file exists, @code{if-exists-else}
6997returns the pathname. If it does not exist, it returns the second argument.
6998This way, @code{if-exists-else} can be used to select one file or another,
6999based on the existence of the first. Here is a small example of its usage:
7000
7001@smallexample
7002*startfile:
7003crt0%O%s %:if-exists(crti%O%s) \
7004%:if-exists-else(crtbeginT%O%s crtbegin%O%s)
7005@end smallexample
7006
7007@item @code{replace-outfile}
7008The @code{replace-outfile} spec function takes two arguments. It looks for the
7009first argument in the outfiles array and replaces it with the second argument. Here
7010is a small example of its usage:
7011
7012@smallexample
7013%@{static|static-libgcc|static-libstdc++:%:replace-outfile(-lstdc++ \
7014libstdc++.a%s)@}
7015
7016@end smallexample
7017
7018@end table
7019
7020@item %@{@code{S}@}
7021Substitutes the @code{-S} switch, if that switch was given to GCC@.
7022If that switch was not specified, this substitutes nothing. Note that
7023the leading dash is omitted when specifying this option, and it is
7024automatically inserted if the substitution is performed. Thus the spec
7025string @samp{%@{foo@}} would match the command-line option @option{-foo}
7026and would output the command line option @option{-foo}.
7027
7028@item %W@{@code{S}@}
7029Like %@{@code{S}@} but mark last argument supplied within as a file to be
7030deleted on failure.
7031
7032@item %@{@code{S}*@}
7033Substitutes all the switches specified to GCC whose names start
7034with @code{-S}, but which also take an argument. This is used for
7035switches like @option{-o}, @option{-D}, @option{-I}, etc.
7036GCC considers @option{-o foo} as being
7037one switch whose names starts with @samp{o}. %@{o*@} would substitute this
7038text, including the space. Thus two arguments would be generated.
7039
7040@item %@{@code{S}*&@code{T}*@}
7041Like %@{@code{S}*@}, but preserve order of @code{S} and @code{T} options
7042(the order of @code{S} and @code{T} in the spec is not significant).
7043There can be any number of ampersand-separated variables; for each the
7044wild card is optional. Useful for CPP as @samp{%@{D*&U*&A*@}}.
7045
7046@item %@{@code{S}:@code{X}@}
7047Substitutes @code{X}, if the @samp{-S} switch was given to GCC@.
7048
7049@item %@{!@code{S}:@code{X}@}
7050Substitutes @code{X}, if the @samp{-S} switch was @emph{not} given to GCC@.
7051
7052@item %@{@code{S}*:@code{X}@}
7053Substitutes @code{X} if one or more switches whose names start with
7054@code{-S} are specified to GCC@. Normally @code{X} is substituted only
7055once, no matter how many such switches appeared. However, if @code{%*}
7056appears somewhere in @code{X}, then @code{X} will be substituted once
7057for each matching switch, with the @code{%*} replaced by the part of
7058that switch that matched the @code{*}.
7059
7060@item %@{.@code{S}:@code{X}@}
7061Substitutes @code{X}, if processing a file with suffix @code{S}.
7062
7063@item %@{!.@code{S}:@code{X}@}
7064Substitutes @code{X}, if @emph{not} processing a file with suffix @code{S}.
7065
7066@item %@{@code{S}|@code{P}:@code{X}@}
7067Substitutes @code{X} if either @code{-S} or @code{-P} was given to GCC@.
7068This may be combined with @samp{!}, @samp{.}, and @code{*} sequences as well,
7069although they have a stronger binding than the @samp{|}. If @code{%*}
7070appears in @code{X}, all of the alternatives must be starred, and only
7071the first matching alternative is substituted.
7072
7073For example, a spec string like this:
7074
7075@smallexample
7076%@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@}
7077@end smallexample
7078
7079will output the following command-line options from the following input
7080command-line options:
7081
7082@smallexample
7083fred.c -foo -baz
7084jim.d -bar -boggle
7085-d fred.c -foo -baz -boggle
7086-d jim.d -bar -baz -boggle
7087@end smallexample
7088
7089@item %@{S:X; T:Y; :D@}
7090
7091If @code{S} was given to GCC, substitutes @code{X}; else if @code{T} was
7092given to GCC, substitutes @code{Y}; else substitutes @code{D}. There can
7093be as many clauses as you need. This may be combined with @code{.},
7094@code{!}, @code{|}, and @code{*} as needed.
7095
7096
7097@end table
7098
7099The conditional text @code{X} in a %@{@code{S}:@code{X}@} or similar
7100construct may contain other nested @samp{%} constructs or spaces, or
7101even newlines. They are processed as usual, as described above.
7102Trailing white space in @code{X} is ignored. White space may also
7103appear anywhere on the left side of the colon in these constructs,
7104except between @code{.} or @code{*} and the corresponding word.
7105
7106The @option{-O}, @option{-f}, @option{-m}, and @option{-W} switches are
7107handled specifically in these constructs. If another value of
7108@option{-O} or the negated form of a @option{-f}, @option{-m}, or
7109@option{-W} switch is found later in the command line, the earlier
7110switch value is ignored, except with @{@code{S}*@} where @code{S} is
7111just one letter, which passes all matching options.
7112
7113The character @samp{|} at the beginning of the predicate text is used to
7114indicate that a command should be piped to the following command, but
7115only if @option{-pipe} is specified.
7116
7117It is built into GCC which switches take arguments and which do not.
7118(You might think it would be useful to generalize this to allow each
7119compiler's spec to say which switches take arguments. But this cannot
7120be done in a consistent fashion. GCC cannot even decide which input
7121files have been specified without knowing which switches take arguments,
7122and it must know which input files to compile in order to tell which
7123compilers to run).
7124
7125GCC also knows implicitly that arguments starting in @option{-l} are to be
7126treated as compiler output files, and passed to the linker in their
7127proper position among the other output files.
7128
7129@c man begin OPTIONS
7130
7131@node Target Options
7132@section Specifying Target Machine and Compiler Version
7133@cindex target options
7134@cindex cross compiling
7135@cindex specifying machine version
7136@cindex specifying compiler version and target machine
7137@cindex compiler version, specifying
7138@cindex target machine, specifying
7139
7140The usual way to run GCC is to run the executable called @file{gcc}, or
7141@file{<machine>-gcc} when cross-compiling, or
7142@file{<machine>-gcc-<version>} to run a version other than the one that
7143was installed last. Sometimes this is inconvenient, so GCC provides
7144options that will switch to another cross-compiler or version.
7145
7146@table @gcctabopt
7147@item -b @var{machine}
7148@opindex b
7149The argument @var{machine} specifies the target machine for compilation.
7150
7151The value to use for @var{machine} is the same as was specified as the
7152machine type when configuring GCC as a cross-compiler. For
7153example, if a cross-compiler was configured with @samp{configure
7154arm-elf}, meaning to compile for an arm processor with elf binaries,
7155then you would specify @option{-b arm-elf} to run that cross compiler.
7156Because there are other options beginning with @option{-b}, the
7157configuration must contain a hyphen.
7158
7159@item -V @var{version}
7160@opindex V
7161The argument @var{version} specifies which version of GCC to run.
7162This is useful when multiple versions are installed. For example,
7163@var{version} might be @samp{4.0}, meaning to run GCC version 4.0.
7164@end table
7165
7166The @option{-V} and @option{-b} options work by running the
7167@file{<machine>-gcc-<version>} executable, so there's no real reason to
7168use them if you can just run that directly.
7169
7170@node Submodel Options
7171@section Hardware Models and Configurations
7172@cindex submodel options
7173@cindex specifying hardware config
7174@cindex hardware models and configurations, specifying
7175@cindex machine dependent options
7176
7177Earlier we discussed the standard option @option{-b} which chooses among
7178different installed compilers for completely different target
7179machines, such as VAX vs.@: 68000 vs.@: 80386.
7180
7181In addition, each of these target machine types can have its own
7182special options, starting with @samp{-m}, to choose among various
7183hardware models or configurations---for example, 68010 vs 68020,
7184floating coprocessor or none. A single installed version of the
7185compiler can compile for any model or configuration, according to the
7186options specified.
7187
7188Some configurations of the compiler also support additional special
7189options, usually for compatibility with other compilers on the same
7190platform.
7191
7192@c This list is ordered alphanumerically by subsection name.
7193@c It should be the same order and spelling as these options are listed
7194@c in Machine Dependent Options
7195
7196@menu
7197* ARC Options::
7198* ARM Options::
7199* AVR Options::
7200* Blackfin Options::
7201* CRIS Options::
7202* CRX Options::
7203* Darwin Options::
7204* DEC Alpha Options::
7205* DEC Alpha/VMS Options::
7206* FRV Options::
7207* GNU/Linux Options::
7208* H8/300 Options::
7209* HPPA Options::
7210* i386 and x86-64 Options::
7211* IA-64 Options::
7212* M32C Options::
7213* M32R/D Options::
7214* M680x0 Options::
7215* M68hc1x Options::
7216* MCore Options::
7217* MIPS Options::
7218* MMIX Options::
7219* MN10300 Options::
7220* MT Options::
7221* PDP-11 Options::
7222* PowerPC Options::
7223* RS/6000 and PowerPC Options::
7224* S/390 and zSeries Options::
7225* Score Options::
7226* SH Options::
7227* SPARC Options::
7228* System V Options::
7229* TMS320C3x/C4x Options::
7230* V850 Options::
7231* VAX Options::
7232* x86-64 Options::
7233* Xstormy16 Options::
7234* Xtensa Options::
7235* zSeries Options::
7236@end menu
7237
7238@node ARC Options
7239@subsection ARC Options
7240@cindex ARC Options
7241
7242These options are defined for ARC implementations:
7243
7244@table @gcctabopt
7245@item -EL
7246@opindex EL
7247Compile code for little endian mode. This is the default.
7248
7249@item -EB
7250@opindex EB
7251Compile code for big endian mode.
7252
7253@item -mmangle-cpu
7254@opindex mmangle-cpu
7255Prepend the name of the cpu to all public symbol names.
7256In multiple-processor systems, there are many ARC variants with different
7257instruction and register set characteristics. This flag prevents code
7258compiled for one cpu to be linked with code compiled for another.
7259No facility exists for handling variants that are ``almost identical''.
7260This is an all or nothing option.
7261
7262@item -mcpu=@var{cpu}
7263@opindex mcpu
7264Compile code for ARC variant @var{cpu}.
7265Which variants are supported depend on the configuration.
7266All variants support @option{-mcpu=base}, this is the default.
7267
7268@item -mtext=@var{text-section}
7269@itemx -mdata=@var{data-section}
7270@itemx -mrodata=@var{readonly-data-section}
7271@opindex mtext
7272@opindex mdata
7273@opindex mrodata
7274Put functions, data, and readonly data in @var{text-section},
7275@var{data-section}, and @var{readonly-data-section} respectively
7276by default. This can be overridden with the @code{section} attribute.
7277@xref{Variable Attributes}.
7278
7279@end table
7280
7281@node ARM Options
7282@subsection ARM Options
7283@cindex ARM options
7284
7285These @samp{-m} options are defined for Advanced RISC Machines (ARM)
7286architectures:
7287
7288@table @gcctabopt
7289@item -mabi=@var{name}
7290@opindex mabi
7291Generate code for the specified ABI@. Permissible values are: @samp{apcs-gnu},
7292@samp{atpcs}, @samp{aapcs}, @samp{aapcs-linux} and @samp{iwmmxt}.
7293
7294@item -mapcs-frame
7295@opindex mapcs-frame
7296Generate a stack frame that is compliant with the ARM Procedure Call
7297Standard for all functions, even if this is not strictly necessary for
7298correct execution of the code. Specifying @option{-fomit-frame-pointer}
7299with this option will cause the stack frames not to be generated for
7300leaf functions. The default is @option{-mno-apcs-frame}.
7301
7302@item -mapcs
7303@opindex mapcs
7304This is a synonym for @option{-mapcs-frame}.
7305
7306@ignore
7307@c not currently implemented
7308@item -mapcs-stack-check
7309@opindex mapcs-stack-check
7310Generate code to check the amount of stack space available upon entry to
7311every function (that actually uses some stack space). If there is
7312insufficient space available then either the function
7313@samp{__rt_stkovf_split_small} or @samp{__rt_stkovf_split_big} will be
7314called, depending upon the amount of stack space required. The run time
7315system is required to provide these functions. The default is
7316@option{-mno-apcs-stack-check}, since this produces smaller code.
7317
7318@c not currently implemented
7319@item -mapcs-float
7320@opindex mapcs-float
7321Pass floating point arguments using the float point registers. This is
7322one of the variants of the APCS@. This option is recommended if the
7323target hardware has a floating point unit or if a lot of floating point
7324arithmetic is going to be performed by the code. The default is
7325@option{-mno-apcs-float}, since integer only code is slightly increased in
7326size if @option{-mapcs-float} is used.
7327
7328@c not currently implemented
7329@item -mapcs-reentrant
7330@opindex mapcs-reentrant
7331Generate reentrant, position independent code. The default is
7332@option{-mno-apcs-reentrant}.
7333@end ignore
7334
7335@item -mthumb-interwork
7336@opindex mthumb-interwork
7337Generate code which supports calling between the ARM and Thumb
7338instruction sets. Without this option the two instruction sets cannot
7339be reliably used inside one program. The default is
7340@option{-mno-thumb-interwork}, since slightly larger code is generated
7341when @option{-mthumb-interwork} is specified.
7342
7343@item -mno-sched-prolog
7344@opindex mno-sched-prolog
7345Prevent the reordering of instructions in the function prolog, or the
7346merging of those instruction with the instructions in the function's
7347body. This means that all functions will start with a recognizable set
7348of instructions (or in fact one of a choice from a small set of
7349different function prologues), and this information can be used to
7350locate the start if functions inside an executable piece of code. The
7351default is @option{-msched-prolog}.
7352
7353@item -mhard-float
7354@opindex mhard-float
7355Generate output containing floating point instructions. This is the
7356default.
7357
7358@item -msoft-float
7359@opindex msoft-float
7360Generate output containing library calls for floating point.
7361@strong{Warning:} the requisite libraries are not available for all ARM
7362targets. Normally the facilities of the machine's usual C compiler are
7363used, but this cannot be done directly in cross-compilation. You must make
7364your own arrangements to provide suitable library functions for
7365cross-compilation.
7366
7367@option{-msoft-float} changes the calling convention in the output file;
7368therefore, it is only useful if you compile @emph{all} of a program with
7369this option. In particular, you need to compile @file{libgcc.a}, the
7370library that comes with GCC, with @option{-msoft-float} in order for
7371this to work.
7372
7373@item -mfloat-abi=@var{name}
7374@opindex mfloat-abi
7375Specifies which ABI to use for floating point values. Permissible values
7376are: @samp{soft}, @samp{softfp} and @samp{hard}.
7377
7378@samp{soft} and @samp{hard} are equivalent to @option{-msoft-float}
7379and @option{-mhard-float} respectively. @samp{softfp} allows the generation
7380of floating point instructions, but still uses the soft-float calling
7381conventions.
7382
7383@item -mlittle-endian
7384@opindex mlittle-endian
7385Generate code for a processor running in little-endian mode. This is
7386the default for all standard configurations.
7387
7388@item -mbig-endian
7389@opindex mbig-endian
7390Generate code for a processor running in big-endian mode; the default is
7391to compile code for a little-endian processor.
7392
7393@item -mwords-little-endian
7394@opindex mwords-little-endian
7395This option only applies when generating code for big-endian processors.
7396Generate code for a little-endian word order but a big-endian byte
7397order. That is, a byte order of the form @samp{32107654}. Note: this
7398option should only be used if you require compatibility with code for
7399big-endian ARM processors generated by versions of the compiler prior to
74002.8.
7401
7402@item -mcpu=@var{name}
7403@opindex mcpu
7404This specifies the name of the target ARM processor. GCC uses this name
7405to determine what kind of instructions it can emit when generating
7406assembly code. Permissible names are: @samp{arm2}, @samp{arm250},
7407@samp{arm3}, @samp{arm6}, @samp{arm60}, @samp{arm600}, @samp{arm610},
7408@samp{arm620}, @samp{arm7}, @samp{arm7m}, @samp{arm7d}, @samp{arm7dm},
7409@samp{arm7di}, @samp{arm7dmi}, @samp{arm70}, @samp{arm700},
7410@samp{arm700i}, @samp{arm710}, @samp{arm710c}, @samp{arm7100},
7411@samp{arm7500}, @samp{arm7500fe}, @samp{arm7tdmi}, @samp{arm7tdmi-s},
7412@samp{arm8}, @samp{strongarm}, @samp{strongarm110}, @samp{strongarm1100},
7413@samp{arm8}, @samp{arm810}, @samp{arm9}, @samp{arm9e}, @samp{arm920},
7414@samp{arm920t}, @samp{arm922t}, @samp{arm946e-s}, @samp{arm966e-s},
7415@samp{arm968e-s}, @samp{arm926ej-s}, @samp{arm940t}, @samp{arm9tdmi},
7416@samp{arm10tdmi}, @samp{arm1020t}, @samp{arm1026ej-s},
7417@samp{arm10e}, @samp{arm1020e}, @samp{arm1022e},
7418@samp{arm1136j-s}, @samp{arm1136jf-s}, @samp{mpcore}, @samp{mpcorenovfp},
7419@samp{arm1176jz-s}, @samp{arm1176jzf-s}, @samp{xscale}, @samp{iwmmxt},
7420@samp{ep9312}.
7421
7422@itemx -mtune=@var{name}
7423@opindex mtune
7424This option is very similar to the @option{-mcpu=} option, except that
7425instead of specifying the actual target processor type, and hence
7426restricting which instructions can be used, it specifies that GCC should
7427tune the performance of the code as if the target were of the type
7428specified in this option, but still choosing the instructions that it
7429will generate based on the cpu specified by a @option{-mcpu=} option.
7430For some ARM implementations better performance can be obtained by using
7431this option.
7432
7433@item -march=@var{name}
7434@opindex march
7435This specifies the name of the target ARM architecture. GCC uses this
7436name to determine what kind of instructions it can emit when generating
7437assembly code. This option can be used in conjunction with or instead
7438of the @option{-mcpu=} option. Permissible names are: @samp{armv2},
7439@samp{armv2a}, @samp{armv3}, @samp{armv3m}, @samp{armv4}, @samp{armv4t},
7440@samp{armv5}, @samp{armv5t}, @samp{armv5te}, @samp{armv6}, @samp{armv6j},
7441@samp{iwmmxt}, @samp{ep9312}.
7442
7443@item -mfpu=@var{name}
7444@itemx -mfpe=@var{number}
7445@itemx -mfp=@var{number}
7446@opindex mfpu
7447@opindex mfpe
7448@opindex mfp
7449This specifies what floating point hardware (or hardware emulation) is
7450available on the target. Permissible names are: @samp{fpa}, @samp{fpe2},
7451@samp{fpe3}, @samp{maverick}, @samp{vfp}. @option{-mfp} and @option{-mfpe}
7452are synonyms for @option{-mfpu}=@samp{fpe}@var{number}, for compatibility
7453with older versions of GCC@.
7454
7455If @option{-msoft-float} is specified this specifies the format of
7456floating point values.
7457
7458@item -mstructure-size-boundary=@var{n}
7459@opindex mstructure-size-boundary
7460The size of all structures and unions will be rounded up to a multiple
7461of the number of bits set by this option. Permissible values are 8, 32
7462and 64. The default value varies for different toolchains. For the COFF
7463targeted toolchain the default value is 8. A value of 64 is only allowed
7464if the underlying ABI supports it.
7465
7466Specifying the larger number can produce faster, more efficient code, but
7467can also increase the size of the program. Different values are potentially
7468incompatible. Code compiled with one value cannot necessarily expect to
7469work with code or libraries compiled with another value, if they exchange
7470information using structures or unions.
7471
7472@item -mabort-on-noreturn
7473@opindex mabort-on-noreturn
7474Generate a call to the function @code{abort} at the end of a
7475@code{noreturn} function. It will be executed if the function tries to
7476return.
7477
7478@item -mlong-calls
7479@itemx -mno-long-calls
7480@opindex mlong-calls
7481@opindex mno-long-calls
7482Tells the compiler to perform function calls by first loading the
7483address of the function into a register and then performing a subroutine
7484call on this register. This switch is needed if the target function
7485will lie outside of the 64 megabyte addressing range of the offset based
7486version of subroutine call instruction.
7487
7488Even if this switch is enabled, not all function calls will be turned
7489into long calls. The heuristic is that static functions, functions
7490which have the @samp{short-call} attribute, functions that are inside
7491the scope of a @samp{#pragma no_long_calls} directive and functions whose
7492definitions have already been compiled within the current compilation
7493unit, will not be turned into long calls. The exception to this rule is
7494that weak function definitions, functions with the @samp{long-call}
7495attribute or the @samp{section} attribute, and functions that are within
7496the scope of a @samp{#pragma long_calls} directive, will always be
7497turned into long calls.
7498
7499This feature is not enabled by default. Specifying
7500@option{-mno-long-calls} will restore the default behavior, as will
7501placing the function calls within the scope of a @samp{#pragma
7502long_calls_off} directive. Note these switches have no effect on how
7503the compiler generates code to handle function calls via function
7504pointers.
7505
7506@item -mnop-fun-dllimport
7507@opindex mnop-fun-dllimport
7508Disable support for the @code{dllimport} attribute.
7509
7510@item -msingle-pic-base
7511@opindex msingle-pic-base
7512Treat the register used for PIC addressing as read-only, rather than
7513loading it in the prologue for each function. The run-time system is
7514responsible for initializing this register with an appropriate value
7515before execution begins.
7516
7517@item -mpic-register=@var{reg}
7518@opindex mpic-register
7519Specify the register to be used for PIC addressing. The default is R10
7520unless stack-checking is enabled, when R9 is used.
7521
7522@item -mcirrus-fix-invalid-insns
7523@opindex mcirrus-fix-invalid-insns
7524@opindex mno-cirrus-fix-invalid-insns
7525Insert NOPs into the instruction stream to in order to work around
7526problems with invalid Maverick instruction combinations. This option
7527is only valid if the @option{-mcpu=ep9312} option has been used to
7528enable generation of instructions for the Cirrus Maverick floating
7529point co-processor. This option is not enabled by default, since the
7530problem is only present in older Maverick implementations. The default
7531can be re-enabled by use of the @option{-mno-cirrus-fix-invalid-insns}
7532switch.
7533
7534@item -mpoke-function-name
7535@opindex mpoke-function-name
7536Write the name of each function into the text section, directly
7537preceding the function prologue. The generated code is similar to this:
7538
7539@smallexample
7540 t0
7541 .ascii "arm_poke_function_name", 0
7542 .align
7543 t1
7544 .word 0xff000000 + (t1 - t0)
7545 arm_poke_function_name
7546 mov ip, sp
7547 stmfd sp!, @{fp, ip, lr, pc@}
7548 sub fp, ip, #4
7549@end smallexample
7550
7551When performing a stack backtrace, code can inspect the value of
7552@code{pc} stored at @code{fp + 0}. If the trace function then looks at
7553location @code{pc - 12} and the top 8 bits are set, then we know that
7554there is a function name embedded immediately preceding this location
7555and has length @code{((pc[-3]) & 0xff000000)}.
7556
7557@item -mthumb
7558@opindex mthumb
7559Generate code for the 16-bit Thumb instruction set. The default is to
7560use the 32-bit ARM instruction set.
7561
7562@item -mtpcs-frame
7563@opindex mtpcs-frame
7564Generate a stack frame that is compliant with the Thumb Procedure Call
7565Standard for all non-leaf functions. (A leaf function is one that does
7566not call any other functions.) The default is @option{-mno-tpcs-frame}.
7567
7568@item -mtpcs-leaf-frame
7569@opindex mtpcs-leaf-frame
7570Generate a stack frame that is compliant with the Thumb Procedure Call
7571Standard for all leaf functions. (A leaf function is one that does
7572not call any other functions.) The default is @option{-mno-apcs-leaf-frame}.
7573
7574@item -mcallee-super-interworking
7575@opindex mcallee-super-interworking
7576Gives all externally visible functions in the file being compiled an ARM
7577instruction set header which switches to Thumb mode before executing the
7578rest of the function. This allows these functions to be called from
7579non-interworking code.
7580
7581@item -mcaller-super-interworking
7582@opindex mcaller-super-interworking
7583Allows calls via function pointers (including virtual functions) to
7584execute correctly regardless of whether the target code has been
7585compiled for interworking or not. There is a small overhead in the cost
7586of executing a function pointer if this option is enabled.
7587
7588@item -mtp=@var{name}
7589@opindex mtp
7590Specify the access model for the thread local storage pointer. The valid
7591models are @option{soft}, which generates calls to @code{__aeabi_read_tp},
7592@option{cp15}, which fetches the thread pointer from @code{cp15} directly
7593(supported in the arm6k architecture), and @option{auto}, which uses the
7594best available method for the selected processor. The default setting is
7595@option{auto}.
7596
7597@end table
7598
7599@node AVR Options
7600@subsection AVR Options
7601@cindex AVR Options
7602
7603These options are defined for AVR implementations:
7604
7605@table @gcctabopt
7606@item -mmcu=@var{mcu}
7607@opindex mmcu
7608Specify ATMEL AVR instruction set or MCU type.
7609
7610Instruction set avr1 is for the minimal AVR core, not supported by the C
7611compiler, only for assembler programs (MCU types: at90s1200, attiny10,
7612attiny11, attiny12, attiny15, attiny28).
7613
7614Instruction set avr2 (default) is for the classic AVR core with up to
76158K program memory space (MCU types: at90s2313, at90s2323, attiny22,
7616at90s2333, at90s2343, at90s4414, at90s4433, at90s4434, at90s8515,
7617at90c8534, at90s8535).
7618
7619Instruction set avr3 is for the classic AVR core with up to 128K program
7620memory space (MCU types: atmega103, atmega603, at43usb320, at76c711).
7621
7622Instruction set avr4 is for the enhanced AVR core with up to 8K program
7623memory space (MCU types: atmega8, atmega83, atmega85).
7624
7625Instruction set avr5 is for the enhanced AVR core with up to 128K program
7626memory space (MCU types: atmega16, atmega161, atmega163, atmega32, atmega323,
7627atmega64, atmega128, at43usb355, at94k).
7628
7629@item -msize
7630@opindex msize
7631Output instruction sizes to the asm file.
7632
7633@item -minit-stack=@var{N}
7634@opindex minit-stack
7635Specify the initial stack address, which may be a symbol or numeric value,
7636@samp{__stack} is the default.
7637
7638@item -mno-interrupts
7639@opindex mno-interrupts
7640Generated code is not compatible with hardware interrupts.
7641Code size will be smaller.
7642
7643@item -mcall-prologues
7644@opindex mcall-prologues
7645Functions prologues/epilogues expanded as call to appropriate
7646subroutines. Code size will be smaller.
7647
7648@item -mno-tablejump
7649@opindex mno-tablejump
7650Do not generate tablejump insns which sometimes increase code size.
7651
7652@item -mtiny-stack
7653@opindex mtiny-stack
7654Change only the low 8 bits of the stack pointer.
7655
7656@item -mint8
7657@opindex mint8
7658Assume int to be 8 bit integer. This affects the sizes of all types: A
7659char will be 1 byte, an int will be 1 byte, an long will be 2 bytes
7660and long long will be 4 bytes. Please note that this option does not
7661comply to the C standards, but it will provide you with smaller code
7662size.
7663@end table
7664
7665@node Blackfin Options
7666@subsection Blackfin Options
7667@cindex Blackfin Options
7668
7669@table @gcctabopt
7670@item -momit-leaf-frame-pointer
7671@opindex momit-leaf-frame-pointer
7672Don't keep the frame pointer in a register for leaf functions. This
7673avoids the instructions to save, set up and restore frame pointers and
7674makes an extra register available in leaf functions. The option
7675@option{-fomit-frame-pointer} removes the frame pointer for all functions
7676which might make debugging harder.
7677
7678@item -mspecld-anomaly
7679@opindex mspecld-anomaly
7680When enabled, the compiler will ensure that the generated code does not
7681contain speculative loads after jump instructions. This option is enabled
7682by default.
7683
7684@item -mno-specld-anomaly
7685@opindex mno-specld-anomaly
7686Don't generate extra code to prevent speculative loads from occurring.
7687
7688@item -mcsync-anomaly
7689@opindex mcsync-anomaly
7690When enabled, the compiler will ensure that the generated code does not
7691contain CSYNC or SSYNC instructions too soon after conditional branches.
7692This option is enabled by default.
7693
7694@item -mno-csync-anomaly
7695@opindex mno-csync-anomaly
7696Don't generate extra code to prevent CSYNC or SSYNC instructions from
7697occurring too soon after a conditional branch.
7698
7699@item -mlow-64k
7700@opindex mlow-64k
7701When enabled, the compiler is free to take advantage of the knowledge that
7702the entire program fits into the low 64k of memory.
7703
7704@item -mno-low-64k
7705@opindex mno-low-64k
7706Assume that the program is arbitrarily large. This is the default.
7707
7708@item -mid-shared-library
7709@opindex mid-shared-library
7710Generate code that supports shared libraries via the library ID method.
7711This allows for execute in place and shared libraries in an environment
7712without virtual memory management. This option implies @option{-fPIC}.
7713
7714@item -mno-id-shared-library
7715@opindex mno-id-shared-library
7716Generate code that doesn't assume ID based shared libraries are being used.
7717This is the default.
7718
7719@item -mshared-library-id=n
7720@opindex mshared-library-id
7721Specified the identification number of the ID based shared library being
7722compiled. Specifying a value of 0 will generate more compact code, specifying
7723other values will force the allocation of that number to the current
7724library but is no more space or time efficient than omitting this option.
7725
7726@item -mlong-calls
7727@itemx -mno-long-calls
7728@opindex mlong-calls
7729@opindex mno-long-calls
7730Tells the compiler to perform function calls by first loading the
7731address of the function into a register and then performing a subroutine
7732call on this register. This switch is needed if the target function
7733will lie outside of the 24 bit addressing range of the offset based
7734version of subroutine call instruction.
7735
7736This feature is not enabled by default. Specifying
7737@option{-mno-long-calls} will restore the default behavior. Note these
7738switches have no effect on how the compiler generates code to handle
7739function calls via function pointers.
7740@end table
7741
7742@node CRIS Options
7743@subsection CRIS Options
7744@cindex CRIS Options
7745
7746These options are defined specifically for the CRIS ports.
7747
7748@table @gcctabopt
7749@item -march=@var{architecture-type}
7750@itemx -mcpu=@var{architecture-type}
7751@opindex march
7752@opindex mcpu
7753Generate code for the specified architecture. The choices for
7754@var{architecture-type} are @samp{v3}, @samp{v8} and @samp{v10} for
7755respectively ETRAX@w{ }4, ETRAX@w{ }100, and ETRAX@w{ }100@w{ }LX@.
7756Default is @samp{v0} except for cris-axis-linux-gnu, where the default is
7757@samp{v10}.
7758
7759@item -mtune=@var{architecture-type}
7760@opindex mtune
7761Tune to @var{architecture-type} everything applicable about the generated
7762code, except for the ABI and the set of available instructions. The
7763choices for @var{architecture-type} are the same as for
7764@option{-march=@var{architecture-type}}.
7765
7766@item -mmax-stack-frame=@var{n}
7767@opindex mmax-stack-frame
7768Warn when the stack frame of a function exceeds @var{n} bytes.
7769
7770@item -melinux-stacksize=@var{n}
7771@opindex melinux-stacksize
7772Only available with the @samp{cris-axis-aout} target. Arranges for
7773indications in the program to the kernel loader that the stack of the
7774program should be set to @var{n} bytes.
7775
7776@item -metrax4
7777@itemx -metrax100
7778@opindex metrax4
7779@opindex metrax100
7780The options @option{-metrax4} and @option{-metrax100} are synonyms for
7781@option{-march=v3} and @option{-march=v8} respectively.
7782
7783@item -mmul-bug-workaround
7784@itemx -mno-mul-bug-workaround
7785@opindex mmul-bug-workaround
7786@opindex mno-mul-bug-workaround
7787Work around a bug in the @code{muls} and @code{mulu} instructions for CPU
7788models where it applies. This option is active by default.
7789
7790@item -mpdebug
7791@opindex mpdebug
7792Enable CRIS-specific verbose debug-related information in the assembly
7793code. This option also has the effect to turn off the @samp{#NO_APP}
7794formatted-code indicator to the assembler at the beginning of the
7795assembly file.
7796
7797@item -mcc-init
7798@opindex mcc-init
7799Do not use condition-code results from previous instruction; always emit
7800compare and test instructions before use of condition codes.
7801
7802@item -mno-side-effects
7803@opindex mno-side-effects
7804Do not emit instructions with side-effects in addressing modes other than
7805post-increment.
7806
7807@item -mstack-align
7808@itemx -mno-stack-align
7809@itemx -mdata-align
7810@itemx -mno-data-align
7811@itemx -mconst-align
7812@itemx -mno-const-align
7813@opindex mstack-align
7814@opindex mno-stack-align
7815@opindex mdata-align
7816@opindex mno-data-align
7817@opindex mconst-align
7818@opindex mno-const-align
7819These options (no-options) arranges (eliminate arrangements) for the
7820stack-frame, individual data and constants to be aligned for the maximum
7821single data access size for the chosen CPU model. The default is to
7822arrange for 32-bit alignment. ABI details such as structure layout are
7823not affected by these options.
7824
7825@item -m32-bit
7826@itemx -m16-bit
7827@itemx -m8-bit
7828@opindex m32-bit
7829@opindex m16-bit
7830@opindex m8-bit
7831Similar to the stack- data- and const-align options above, these options
7832arrange for stack-frame, writable data and constants to all be 32-bit,
783316-bit or 8-bit aligned. The default is 32-bit alignment.
7834
7835@item -mno-prologue-epilogue
7836@itemx -mprologue-epilogue
7837@opindex mno-prologue-epilogue
7838@opindex mprologue-epilogue
7839With @option{-mno-prologue-epilogue}, the normal function prologue and
7840epilogue that sets up the stack-frame are omitted and no return
7841instructions or return sequences are generated in the code. Use this
7842option only together with visual inspection of the compiled code: no
7843warnings or errors are generated when call-saved registers must be saved,
7844or storage for local variable needs to be allocated.
7845
7846@item -mno-gotplt
7847@itemx -mgotplt
7848@opindex mno-gotplt
7849@opindex mgotplt
7850With @option{-fpic} and @option{-fPIC}, don't generate (do generate)
7851instruction sequences that load addresses for functions from the PLT part
7852of the GOT rather than (traditional on other architectures) calls to the
7853PLT@. The default is @option{-mgotplt}.
7854
7855@item -maout
7856@opindex maout
7857Legacy no-op option only recognized with the cris-axis-aout target.
7858
7859@item -melf
7860@opindex melf
7861Legacy no-op option only recognized with the cris-axis-elf and
7862cris-axis-linux-gnu targets.
7863
7864@item -melinux
7865@opindex melinux
7866Only recognized with the cris-axis-aout target, where it selects a
7867GNU/linux-like multilib, include files and instruction set for
7868@option{-march=v8}.
7869
7870@item -mlinux
7871@opindex mlinux
7872Legacy no-op option only recognized with the cris-axis-linux-gnu target.
7873
7874@item -sim
7875@opindex sim
7876This option, recognized for the cris-axis-aout and cris-axis-elf arranges
7877to link with input-output functions from a simulator library. Code,
7878initialized data and zero-initialized data are allocated consecutively.
7879
7880@item -sim2
7881@opindex sim2
7882Like @option{-sim}, but pass linker options to locate initialized data at
78830x40000000 and zero-initialized data at 0x80000000.
7884@end table
7885
7886@node CRX Options
7887@subsection CRX Options
7888@cindex CRX Options
7889
7890These options are defined specifically for the CRX ports.
7891
7892@table @gcctabopt
7893
7894@item -mmac
7895@opindex mmac
7896Enable the use of multiply-accumulate instructions. Disabled by default.
7897
7898@item -mpush-args
7899@opindex mpush-args
7900Push instructions will be used to pass outgoing arguments when functions
7901are called. Enabled by default.
7902@end table
7903
7904@node Darwin Options
7905@subsection Darwin Options
7906@cindex Darwin options
7907
7908These options are defined for all architectures running the Darwin operating
7909system.
7910
7911FSF GCC on Darwin does not create ``fat'' object files; it will create
7912an object file for the single architecture that it was built to
7913target. Apple's GCC on Darwin does create ``fat'' files if multiple
7914@option{-arch} options are used; it does so by running the compiler or
7915linker multiple times and joining the results together with
7916@file{lipo}.
7917
7918The subtype of the file created (like @samp{ppc7400} or @samp{ppc970} or
7919@samp{i686}) is determined by the flags that specify the ISA
7920that GCC is targetting, like @option{-mcpu} or @option{-march}. The
7921@option{-force_cpusubtype_ALL} option can be used to override this.
7922
7923The Darwin tools vary in their behavior when presented with an ISA
7924mismatch. The assembler, @file{as}, will only permit instructions to
7925be used that are valid for the subtype of the file it is generating,
7926so you cannot put 64-bit instructions in an @samp{ppc750} object file.
7927The linker for shared libraries, @file{/usr/bin/libtool}, will fail
7928and print an error if asked to create a shared library with a less
7929restrictive subtype than its input files (for instance, trying to put
7930a @samp{ppc970} object file in a @samp{ppc7400} library). The linker
7931for executables, @file{ld}, will quietly give the executable the most
7932restrictive subtype of any of its input files.
7933
7934@table @gcctabopt
7935@item -F@var{dir}
7936@opindex F
7937Add the framework directory @var{dir} to the head of the list of
7938directories to be searched for header files. These directories are
7939interleaved with those specified by @option{-I} options and are
7940scanned in a left-to-right order.
7941
7942A framework directory is a directory with frameworks in it. A
7943framework is a directory with a @samp{"Headers"} and/or
7944@samp{"PrivateHeaders"} directory contained directly in it that ends
7945in @samp{".framework"}. The name of a framework is the name of this
7946directory excluding the @samp{".framework"}. Headers associated with
7947the framework are found in one of those two directories, with
7948@samp{"Headers"} being searched first. A subframework is a framework
7949directory that is in a framework's @samp{"Frameworks"} directory.
7950Includes of subframework headers can only appear in a header of a
7951framework that contains the subframework, or in a sibling subframework
7952header. Two subframeworks are siblings if they occur in the same
7953framework. A subframework should not have the same name as a
7954framework, a warning will be issued if this is violated. Currently a
7955subframework cannot have subframeworks, in the future, the mechanism
7956may be extended to support this. The standard frameworks can be found
7957in @samp{"/System/Library/Frameworks"} and
7958@samp{"/Library/Frameworks"}. An example include looks like
7959@code{#include <Framework/header.h>}, where @samp{Framework} denotes
7960the name of the framework and header.h is found in the
7961@samp{"PrivateHeaders"} or @samp{"Headers"} directory.
7962
7963@item -gused
7964@opindex gused
7965Emit debugging information for symbols that are used. For STABS
7966debugging format, this enables @option{-feliminate-unused-debug-symbols}.
7967This is by default ON@.
7968
7969@item -gfull
7970@opindex gfull
7971Emit debugging information for all symbols and types.
7972
7973@item -mmacosx-version-min=@var{version}
7974The earliest version of MacOS X that this executable will run on
7975is @var{version}. Typical values of @var{version} include @code{10.1},
7976@code{10.2}, and @code{10.3.9}.
7977
7978The default for this option is to make choices that seem to be most
7979useful.
7980
7981@item -mkernel
7982@opindex mkernel
7983Enable kernel development mode. The @option{-mkernel} option sets
7984@option{-static}, @option{-fno-common}, @option{-fno-cxa-atexit},
7985@option{-fno-exceptions}, @option{-fno-non-call-exceptions},
7986@option{-fapple-kext}, @option{-fno-weak} and @option{-fno-rtti} where
7987applicable. This mode also sets @option{-mno-altivec},
7988@option{-msoft-float}, @option{-fno-builtin} and
7989@option{-mlong-branch} for PowerPC targets.
7990
7991@item -mone-byte-bool
7992@opindex mone-byte-bool
7993Override the defaults for @samp{bool} so that @samp{sizeof(bool)==1}.
7994By default @samp{sizeof(bool)} is @samp{4} when compiling for
7995Darwin/PowerPC and @samp{1} when compiling for Darwin/x86, so this
7996option has no effect on x86.
7997
7998@strong{Warning:} The @option{-mone-byte-bool} switch causes GCC
7999to generate code that is not binary compatible with code generated
8000without that switch. Using this switch may require recompiling all
8001other modules in a program, including system libraries. Use this
8002switch to conform to a non-default data model.
8003
8004@item -mfix-and-continue
8005@itemx -ffix-and-continue
8006@itemx -findirect-data
8007@opindex mfix-and-continue
8008@opindex ffix-and-continue
8009@opindex findirect-data
8010Generate code suitable for fast turn around development. Needed to
8011enable gdb to dynamically load @code{.o} files into already running
8012programs. @option{-findirect-data} and @option{-ffix-and-continue}
8013are provided for backwards compatibility.
8014
8015@item -all_load
8016@opindex all_load
8017Loads all members of static archive libraries.
8018See man ld(1) for more information.
8019
8020@item -arch_errors_fatal
8021@opindex arch_errors_fatal
8022Cause the errors having to do with files that have the wrong architecture
8023to be fatal.
8024
8025@item -bind_at_load
8026@opindex bind_at_load
8027Causes the output file to be marked such that the dynamic linker will
8028bind all undefined references when the file is loaded or launched.
8029
8030@item -bundle
8031@opindex bundle
8032Produce a Mach-o bundle format file.
8033See man ld(1) for more information.
8034
8035@item -bundle_loader @var{executable}
8036@opindex bundle_loader
8037This option specifies the @var{executable} that will be loading the build
8038output file being linked. See man ld(1) for more information.
8039
8040@item -dynamiclib
8041@opindex dynamiclib
8042When passed this option, GCC will produce a dynamic library instead of
8043an executable when linking, using the Darwin @file{libtool} command.
8044
8045@item -force_cpusubtype_ALL
8046@opindex force_cpusubtype_ALL
8047This causes GCC's output file to have the @var{ALL} subtype, instead of
8048one controlled by the @option{-mcpu} or @option{-march} option.
8049
8050@item -allowable_client @var{client_name}
8051@itemx -client_name
8052@itemx -compatibility_version
8053@itemx -current_version
8054@itemx -dead_strip
8055@itemx -dependency-file
8056@itemx -dylib_file
8057@itemx -dylinker_install_name
8058@itemx -dynamic
8059@itemx -exported_symbols_list
8060@itemx -filelist
8061@itemx -flat_namespace
8062@itemx -force_flat_namespace
8063@itemx -headerpad_max_install_names
8064@itemx -image_base
8065@itemx -init
8066@itemx -install_name
8067@itemx -keep_private_externs
8068@itemx -multi_module
8069@itemx -multiply_defined
8070@itemx -multiply_defined_unused
8071@itemx -noall_load
8072@itemx -no_dead_strip_inits_and_terms
8073@itemx -nofixprebinding
8074@itemx -nomultidefs
8075@itemx -noprebind
8076@itemx -noseglinkedit
8077@itemx -pagezero_size
8078@itemx -prebind
8079@itemx -prebind_all_twolevel_modules
8080@itemx -private_bundle
8081@itemx -read_only_relocs
8082@itemx -sectalign
8083@itemx -sectobjectsymbols
8084@itemx -whyload
8085@itemx -seg1addr
8086@itemx -sectcreate
8087@itemx -sectobjectsymbols
8088@itemx -sectorder
8089@itemx -segaddr
8090@itemx -segs_read_only_addr
8091@itemx -segs_read_write_addr
8092@itemx -seg_addr_table
8093@itemx -seg_addr_table_filename
8094@itemx -seglinkedit
8095@itemx -segprot
8096@itemx -segs_read_only_addr
8097@itemx -segs_read_write_addr
8098@itemx -single_module
8099@itemx -static
8100@itemx -sub_library
8101@itemx -sub_umbrella
8102@itemx -twolevel_namespace
8103@itemx -umbrella
8104@itemx -undefined
8105@itemx -unexported_symbols_list
8106@itemx -weak_reference_mismatches
8107@itemx -whatsloaded
8108
8109@opindex allowable_client
8110@opindex client_name
8111@opindex compatibility_version
8112@opindex current_version
8113@opindex dead_strip
8114@opindex dependency-file
8115@opindex dylib_file
8116@opindex dylinker_install_name
8117@opindex dynamic
8118@opindex exported_symbols_list
8119@opindex filelist
8120@opindex flat_namespace
8121@opindex force_flat_namespace
8122@opindex headerpad_max_install_names
8123@opindex image_base
8124@opindex init
8125@opindex install_name
8126@opindex keep_private_externs
8127@opindex multi_module
8128@opindex multiply_defined
8129@opindex multiply_defined_unused
8130@opindex noall_load
8131@opindex no_dead_strip_inits_and_terms
8132@opindex nofixprebinding
8133@opindex nomultidefs
8134@opindex noprebind
8135@opindex noseglinkedit
8136@opindex pagezero_size
8137@opindex prebind
8138@opindex prebind_all_twolevel_modules
8139@opindex private_bundle
8140@opindex read_only_relocs
8141@opindex sectalign
8142@opindex sectobjectsymbols
8143@opindex whyload
8144@opindex seg1addr
8145@opindex sectcreate
8146@opindex sectobjectsymbols
8147@opindex sectorder
8148@opindex segaddr
8149@opindex segs_read_only_addr
8150@opindex segs_read_write_addr
8151@opindex seg_addr_table
8152@opindex seg_addr_table_filename
8153@opindex seglinkedit
8154@opindex segprot
8155@opindex segs_read_only_addr
8156@opindex segs_read_write_addr
8157@opindex single_module
8158@opindex static
8159@opindex sub_library
8160@opindex sub_umbrella
8161@opindex twolevel_namespace
8162@opindex umbrella
8163@opindex undefined
8164@opindex unexported_symbols_list
8165@opindex weak_reference_mismatches
8166@opindex whatsloaded
8167
8168These options are passed to the Darwin linker. The Darwin linker man page
8169describes them in detail.
8170@end table
8171
8172@node DEC Alpha Options
8173@subsection DEC Alpha Options
8174
8175These @samp{-m} options are defined for the DEC Alpha implementations:
8176
8177@table @gcctabopt
8178@item -mno-soft-float
8179@itemx -msoft-float
8180@opindex mno-soft-float
8181@opindex msoft-float
8182Use (do not use) the hardware floating-point instructions for
8183floating-point operations. When @option{-msoft-float} is specified,
8184functions in @file{libgcc.a} will be used to perform floating-point
8185operations. Unless they are replaced by routines that emulate the
8186floating-point operations, or compiled in such a way as to call such
8187emulations routines, these routines will issue floating-point
8188operations. If you are compiling for an Alpha without floating-point
8189operations, you must ensure that the library is built so as not to call
8190them.
8191
8192Note that Alpha implementations without floating-point operations are
8193required to have floating-point registers.
8194
8195@item -mfp-reg
8196@itemx -mno-fp-regs
8197@opindex mfp-reg
8198@opindex mno-fp-regs
8199Generate code that uses (does not use) the floating-point register set.
8200@option{-mno-fp-regs} implies @option{-msoft-float}. If the floating-point
8201register set is not used, floating point operands are passed in integer
8202registers as if they were integers and floating-point results are passed
8203in @code{$0} instead of @code{$f0}. This is a non-standard calling sequence,
8204so any function with a floating-point argument or return value called by code
8205compiled with @option{-mno-fp-regs} must also be compiled with that
8206option.
8207
8208A typical use of this option is building a kernel that does not use,
8209and hence need not save and restore, any floating-point registers.
8210
8211@item -mieee
8212@opindex mieee
8213The Alpha architecture implements floating-point hardware optimized for
8214maximum performance. It is mostly compliant with the IEEE floating
8215point standard. However, for full compliance, software assistance is
8216required. This option generates code fully IEEE compliant code
8217@emph{except} that the @var{inexact-flag} is not maintained (see below).
8218If this option is turned on, the preprocessor macro @code{_IEEE_FP} is
8219defined during compilation. The resulting code is less efficient but is
8220able to correctly support denormalized numbers and exceptional IEEE
8221values such as not-a-number and plus/minus infinity. Other Alpha
8222compilers call this option @option{-ieee_with_no_inexact}.
8223
8224@item -mieee-with-inexact
8225@opindex mieee-with-inexact
8226This is like @option{-mieee} except the generated code also maintains
8227the IEEE @var{inexact-flag}. Turning on this option causes the
8228generated code to implement fully-compliant IEEE math. In addition to
8229@code{_IEEE_FP}, @code{_IEEE_FP_EXACT} is defined as a preprocessor
8230macro. On some Alpha implementations the resulting code may execute
8231significantly slower than the code generated by default. Since there is
8232very little code that depends on the @var{inexact-flag}, you should
8233normally not specify this option. Other Alpha compilers call this
8234option @option{-ieee_with_inexact}.
8235
8236@item -mfp-trap-mode=@var{trap-mode}
8237@opindex mfp-trap-mode
8238This option controls what floating-point related traps are enabled.
8239Other Alpha compilers call this option @option{-fptm @var{trap-mode}}.
8240The trap mode can be set to one of four values:
8241
8242@table @samp
8243@item n
8244This is the default (normal) setting. The only traps that are enabled
8245are the ones that cannot be disabled in software (e.g., division by zero
8246trap).
8247
8248@item u
8249In addition to the traps enabled by @samp{n}, underflow traps are enabled
8250as well.
8251
8252@item su
8253Like @samp{u}, but the instructions are marked to be safe for software
8254completion (see Alpha architecture manual for details).
8255
8256@item sui
8257Like @samp{su}, but inexact traps are enabled as well.
8258@end table
8259
8260@item -mfp-rounding-mode=@var{rounding-mode}
8261@opindex mfp-rounding-mode
8262Selects the IEEE rounding mode. Other Alpha compilers call this option
8263@option{-fprm @var{rounding-mode}}. The @var{rounding-mode} can be one
8264of:
8265
8266@table @samp
8267@item n
8268Normal IEEE rounding mode. Floating point numbers are rounded towards
8269the nearest machine number or towards the even machine number in case
8270of a tie.
8271
8272@item m
8273Round towards minus infinity.
8274
8275@item c
8276Chopped rounding mode. Floating point numbers are rounded towards zero.
8277
8278@item d
8279Dynamic rounding mode. A field in the floating point control register
8280(@var{fpcr}, see Alpha architecture reference manual) controls the
8281rounding mode in effect. The C library initializes this register for
8282rounding towards plus infinity. Thus, unless your program modifies the
8283@var{fpcr}, @samp{d} corresponds to round towards plus infinity.
8284@end table
8285
8286@item -mtrap-precision=@var{trap-precision}
8287@opindex mtrap-precision
8288In the Alpha architecture, floating point traps are imprecise. This
8289means without software assistance it is impossible to recover from a
8290floating trap and program execution normally needs to be terminated.
8291GCC can generate code that can assist operating system trap handlers
8292in determining the exact location that caused a floating point trap.
8293Depending on the requirements of an application, different levels of
8294precisions can be selected:
8295
8296@table @samp
8297@item p
8298Program precision. This option is the default and means a trap handler
8299can only identify which program caused a floating point exception.
8300
8301@item f
8302Function precision. The trap handler can determine the function that
8303caused a floating point exception.
8304
8305@item i
8306Instruction precision. The trap handler can determine the exact
8307instruction that caused a floating point exception.
8308@end table
8309
8310Other Alpha compilers provide the equivalent options called
8311@option{-scope_safe} and @option{-resumption_safe}.
8312
8313@item -mieee-conformant
8314@opindex mieee-conformant
8315This option marks the generated code as IEEE conformant. You must not
8316use this option unless you also specify @option{-mtrap-precision=i} and either
8317@option{-mfp-trap-mode=su} or @option{-mfp-trap-mode=sui}. Its only effect
8318is to emit the line @samp{.eflag 48} in the function prologue of the
8319generated assembly file. Under DEC Unix, this has the effect that
8320IEEE-conformant math library routines will be linked in.
8321
8322@item -mbuild-constants
8323@opindex mbuild-constants
8324Normally GCC examines a 32- or 64-bit integer constant to
8325see if it can construct it from smaller constants in two or three
8326instructions. If it cannot, it will output the constant as a literal and
8327generate code to load it from the data segment at runtime.
8328
8329Use this option to require GCC to construct @emph{all} integer constants
8330using code, even if it takes more instructions (the maximum is six).
8331
8332You would typically use this option to build a shared library dynamic
8333loader. Itself a shared library, it must relocate itself in memory
8334before it can find the variables and constants in its own data segment.
8335
8336@item -malpha-as
8337@itemx -mgas
8338@opindex malpha-as
8339@opindex mgas
8340Select whether to generate code to be assembled by the vendor-supplied
8341assembler (@option{-malpha-as}) or by the GNU assembler @option{-mgas}.
8342
8343@item -mbwx
8344@itemx -mno-bwx
8345@itemx -mcix
8346@itemx -mno-cix
8347@itemx -mfix
8348@itemx -mno-fix
8349@itemx -mmax
8350@itemx -mno-max
8351@opindex mbwx
8352@opindex mno-bwx
8353@opindex mcix
8354@opindex mno-cix
8355@opindex mfix
8356@opindex mno-fix
8357@opindex mmax
8358@opindex mno-max
8359Indicate whether GCC should generate code to use the optional BWX,
8360CIX, FIX and MAX instruction sets. The default is to use the instruction
8361sets supported by the CPU type specified via @option{-mcpu=} option or that
8362of the CPU on which GCC was built if none was specified.
8363
8364@item -mfloat-vax
8365@itemx -mfloat-ieee
8366@opindex mfloat-vax
8367@opindex mfloat-ieee
8368Generate code that uses (does not use) VAX F and G floating point
8369arithmetic instead of IEEE single and double precision.
8370
8371@item -mexplicit-relocs
8372@itemx -mno-explicit-relocs
8373@opindex mexplicit-relocs
8374@opindex mno-explicit-relocs
8375Older Alpha assemblers provided no way to generate symbol relocations
8376except via assembler macros. Use of these macros does not allow
8377optimal instruction scheduling. GNU binutils as of version 2.12
8378supports a new syntax that allows the compiler to explicitly mark
8379which relocations should apply to which instructions. This option
8380is mostly useful for debugging, as GCC detects the capabilities of
8381the assembler when it is built and sets the default accordingly.
8382
8383@item -msmall-data
8384@itemx -mlarge-data
8385@opindex msmall-data
8386@opindex mlarge-data
8387When @option{-mexplicit-relocs} is in effect, static data is
8388accessed via @dfn{gp-relative} relocations. When @option{-msmall-data}
8389is used, objects 8 bytes long or smaller are placed in a @dfn{small data area}
8390(the @code{.sdata} and @code{.sbss} sections) and are accessed via
839116-bit relocations off of the @code{$gp} register. This limits the
8392size of the small data area to 64KB, but allows the variables to be
8393directly accessed via a single instruction.
8394
8395The default is @option{-mlarge-data}. With this option the data area
8396is limited to just below 2GB@. Programs that require more than 2GB of
8397data must use @code{malloc} or @code{mmap} to allocate the data in the
8398heap instead of in the program's data segment.
8399
8400When generating code for shared libraries, @option{-fpic} implies
8401@option{-msmall-data} and @option{-fPIC} implies @option{-mlarge-data}.
8402
8403@item -msmall-text
8404@itemx -mlarge-text
8405@opindex msmall-text
8406@opindex mlarge-text
8407When @option{-msmall-text} is used, the compiler assumes that the
8408code of the entire program (or shared library) fits in 4MB, and is
8409thus reachable with a branch instruction. When @option{-msmall-data}
8410is used, the compiler can assume that all local symbols share the
8411same @code{$gp} value, and thus reduce the number of instructions
8412required for a function call from 4 to 1.
8413
8414The default is @option{-mlarge-text}.
8415
8416@item -mcpu=@var{cpu_type}
8417@opindex mcpu
8418Set the instruction set and instruction scheduling parameters for
8419machine type @var{cpu_type}. You can specify either the @samp{EV}
8420style name or the corresponding chip number. GCC supports scheduling
8421parameters for the EV4, EV5 and EV6 family of processors and will
8422choose the default values for the instruction set from the processor
8423you specify. If you do not specify a processor type, GCC will default
8424to the processor on which the compiler was built.
8425
8426Supported values for @var{cpu_type} are
8427
8428@table @samp
8429@item ev4
8430@itemx ev45
8431@itemx 21064
8432Schedules as an EV4 and has no instruction set extensions.
8433
8434@item ev5
8435@itemx 21164
8436Schedules as an EV5 and has no instruction set extensions.
8437
8438@item ev56
8439@itemx 21164a
8440Schedules as an EV5 and supports the BWX extension.
8441
8442@item pca56
8443@itemx 21164pc
8444@itemx 21164PC
8445Schedules as an EV5 and supports the BWX and MAX extensions.
8446
8447@item ev6
8448@itemx 21264
8449Schedules as an EV6 and supports the BWX, FIX, and MAX extensions.
8450
8451@item ev67
8452@itemx 21264a
8453Schedules as an EV6 and supports the BWX, CIX, FIX, and MAX extensions.
8454@end table
8455
8456@item -mtune=@var{cpu_type}
8457@opindex mtune
8458Set only the instruction scheduling parameters for machine type
8459@var{cpu_type}. The instruction set is not changed.
8460
8461@item -mmemory-latency=@var{time}
8462@opindex mmemory-latency
8463Sets the latency the scheduler should assume for typical memory
8464references as seen by the application. This number is highly
8465dependent on the memory access patterns used by the application
8466and the size of the external cache on the machine.
8467
8468Valid options for @var{time} are
8469
8470@table @samp
8471@item @var{number}
8472A decimal number representing clock cycles.
8473
8474@item L1
8475@itemx L2
8476@itemx L3
8477@itemx main
8478The compiler contains estimates of the number of clock cycles for
8479``typical'' EV4 & EV5 hardware for the Level 1, 2 & 3 caches
8480(also called Dcache, Scache, and Bcache), as well as to main memory.
8481Note that L3 is only valid for EV5.
8482
8483@end table
8484@end table
8485
8486@node DEC Alpha/VMS Options
8487@subsection DEC Alpha/VMS Options
8488
8489These @samp{-m} options are defined for the DEC Alpha/VMS implementations:
8490
8491@table @gcctabopt
8492@item -mvms-return-codes
8493@opindex mvms-return-codes
8494Return VMS condition codes from main. The default is to return POSIX
8495style condition (e.g.@ error) codes.
8496@end table
8497
8498@node FRV Options
8499@subsection FRV Options
8500@cindex FRV Options
8501
8502@table @gcctabopt
8503@item -mgpr-32
8504@opindex mgpr-32
8505
8506Only use the first 32 general purpose registers.
8507
8508@item -mgpr-64
8509@opindex mgpr-64
8510
8511Use all 64 general purpose registers.
8512
8513@item -mfpr-32
8514@opindex mfpr-32
8515
8516Use only the first 32 floating point registers.
8517
8518@item -mfpr-64
8519@opindex mfpr-64
8520
8521Use all 64 floating point registers
8522
8523@item -mhard-float
8524@opindex mhard-float
8525
8526Use hardware instructions for floating point operations.
8527
8528@item -msoft-float
8529@opindex msoft-float
8530
8531Use library routines for floating point operations.
8532
8533@item -malloc-cc
8534@opindex malloc-cc
8535
8536Dynamically allocate condition code registers.
8537
8538@item -mfixed-cc
8539@opindex mfixed-cc
8540
8541Do not try to dynamically allocate condition code registers, only
8542use @code{icc0} and @code{fcc0}.
8543
8544@item -mdword
8545@opindex mdword
8546
8547Change ABI to use double word insns.
8548
8549@item -mno-dword
8550@opindex mno-dword
8551
8552Do not use double word instructions.
8553
8554@item -mdouble
8555@opindex mdouble
8556
8557Use floating point double instructions.
8558
8559@item -mno-double
8560@opindex mno-double
8561
8562Do not use floating point double instructions.
8563
8564@item -mmedia
8565@opindex mmedia
8566
8567Use media instructions.
8568
8569@item -mno-media
8570@opindex mno-media
8571
8572Do not use media instructions.
8573
8574@item -mmuladd
8575@opindex mmuladd
8576
8577Use multiply and add/subtract instructions.
8578
8579@item -mno-muladd
8580@opindex mno-muladd
8581
8582Do not use multiply and add/subtract instructions.
8583
8584@item -mfdpic
8585@opindex mfdpic
8586
8587Select the FDPIC ABI, that uses function descriptors to represent
8588pointers to functions. Without any PIC/PIE-related options, it
8589implies @option{-fPIE}. With @option{-fpic} or @option{-fpie}, it
8590assumes GOT entries and small data are within a 12-bit range from the
8591GOT base address; with @option{-fPIC} or @option{-fPIE}, GOT offsets
8592are computed with 32 bits.
8593
8594@item -minline-plt
8595@opindex minline-plt
8596
8597Enable inlining of PLT entries in function calls to functions that are
8598not known to bind locally. It has no effect without @option{-mfdpic}.
8599It's enabled by default if optimizing for speed and compiling for
8600shared libraries (i.e., @option{-fPIC} or @option{-fpic}), or when an
8601optimization option such as @option{-O3} or above is present in the
8602command line.
8603
8604@item -mTLS
8605@opindex TLS
8606
8607Assume a large TLS segment when generating thread-local code.
8608
8609@item -mtls
8610@opindex tls
8611
8612Do not assume a large TLS segment when generating thread-local code.
8613
8614@item -mgprel-ro
8615@opindex mgprel-ro
8616
8617Enable the use of @code{GPREL} relocations in the FDPIC ABI for data
8618that is known to be in read-only sections. It's enabled by default,
8619except for @option{-fpic} or @option{-fpie}: even though it may help
8620make the global offset table smaller, it trades 1 instruction for 4.
8621With @option{-fPIC} or @option{-fPIE}, it trades 3 instructions for 4,
8622one of which may be shared by multiple symbols, and it avoids the need
8623for a GOT entry for the referenced symbol, so it's more likely to be a
8624win. If it is not, @option{-mno-gprel-ro} can be used to disable it.
8625
8626@item -multilib-library-pic
8627@opindex multilib-library-pic
8628
8629Link with the (library, not FD) pic libraries. It's implied by
8630@option{-mlibrary-pic}, as well as by @option{-fPIC} and
8631@option{-fpic} without @option{-mfdpic}. You should never have to use
8632it explicitly.
8633
8634@item -mlinked-fp
8635@opindex mlinked-fp
8636
8637Follow the EABI requirement of always creating a frame pointer whenever
8638a stack frame is allocated. This option is enabled by default and can
8639be disabled with @option{-mno-linked-fp}.
8640
8641@item -mlong-calls
8642@opindex mlong-calls
8643
8644Use indirect addressing to call functions outside the current
8645compilation unit. This allows the functions to be placed anywhere
8646within the 32-bit address space.
8647
8648@item -malign-labels
8649@opindex malign-labels
8650
8651Try to align labels to an 8-byte boundary by inserting nops into the
8652previous packet. This option only has an effect when VLIW packing
8653is enabled. It doesn't create new packets; it merely adds nops to
8654existing ones.
8655
8656@item -mlibrary-pic
8657@opindex mlibrary-pic
8658
8659Generate position-independent EABI code.
8660
8661@item -macc-4
8662@opindex macc-4
8663
8664Use only the first four media accumulator registers.
8665
8666@item -macc-8
8667@opindex macc-8
8668
8669Use all eight media accumulator registers.
8670
8671@item -mpack
8672@opindex mpack
8673
8674Pack VLIW instructions.
8675
8676@item -mno-pack
8677@opindex mno-pack
8678
8679Do not pack VLIW instructions.
8680
8681@item -mno-eflags
8682@opindex mno-eflags
8683
8684Do not mark ABI switches in e_flags.
8685
8686@item -mcond-move
8687@opindex mcond-move
8688
8689Enable the use of conditional-move instructions (default).
8690
8691This switch is mainly for debugging the compiler and will likely be removed
8692in a future version.
8693
8694@item -mno-cond-move
8695@opindex mno-cond-move
8696
8697Disable the use of conditional-move instructions.
8698
8699This switch is mainly for debugging the compiler and will likely be removed
8700in a future version.
8701
8702@item -mscc
8703@opindex mscc
8704
8705Enable the use of conditional set instructions (default).
8706
8707This switch is mainly for debugging the compiler and will likely be removed
8708in a future version.
8709
8710@item -mno-scc
8711@opindex mno-scc
8712
8713Disable the use of conditional set instructions.
8714
8715This switch is mainly for debugging the compiler and will likely be removed
8716in a future version.
8717
8718@item -mcond-exec
8719@opindex mcond-exec
8720
8721Enable the use of conditional execution (default).
8722
8723This switch is mainly for debugging the compiler and will likely be removed
8724in a future version.
8725
8726@item -mno-cond-exec
8727@opindex mno-cond-exec
8728
8729Disable the use of conditional execution.
8730
8731This switch is mainly for debugging the compiler and will likely be removed
8732in a future version.
8733
8734@item -mvliw-branch
8735@opindex mvliw-branch
8736
8737Run a pass to pack branches into VLIW instructions (default).
8738
8739This switch is mainly for debugging the compiler and will likely be removed
8740in a future version.
8741
8742@item -mno-vliw-branch
8743@opindex mno-vliw-branch
8744
8745Do not run a pass to pack branches into VLIW instructions.
8746
8747This switch is mainly for debugging the compiler and will likely be removed
8748in a future version.
8749
8750@item -mmulti-cond-exec
8751@opindex mmulti-cond-exec
8752
8753Enable optimization of @code{&&} and @code{||} in conditional execution
8754(default).
8755
8756This switch is mainly for debugging the compiler and will likely be removed
8757in a future version.
8758
8759@item -mno-multi-cond-exec
8760@opindex mno-multi-cond-exec
8761
8762Disable optimization of @code{&&} and @code{||} in conditional execution.
8763
8764This switch is mainly for debugging the compiler and will likely be removed
8765in a future version.
8766
8767@item -mnested-cond-exec
8768@opindex mnested-cond-exec
8769
8770Enable nested conditional execution optimizations (default).
8771
8772This switch is mainly for debugging the compiler and will likely be removed
8773in a future version.
8774
8775@item -mno-nested-cond-exec
8776@opindex mno-nested-cond-exec
8777
8778Disable nested conditional execution optimizations.
8779
8780This switch is mainly for debugging the compiler and will likely be removed
8781in a future version.
8782
8783@item -moptimize-membar
8784@opindex moptimize-membar
8785
8786This switch removes redundant @code{membar} instructions from the
8787compiler generated code. It is enabled by default.
8788
8789@item -mno-optimize-membar
8790@opindex mno-optimize-membar
8791
8792This switch disables the automatic removal of redundant @code{membar}
8793instructions from the generated code.
8794
8795@item -mtomcat-stats
8796@opindex mtomcat-stats
8797
8798Cause gas to print out tomcat statistics.
8799
8800@item -mcpu=@var{cpu}
8801@opindex mcpu
8802
8803Select the processor type for which to generate code. Possible values are
8804@samp{frv}, @samp{fr550}, @samp{tomcat}, @samp{fr500}, @samp{fr450},
8805@samp{fr405}, @samp{fr400}, @samp{fr300} and @samp{simple}.
8806
8807@end table
8808
8809@node GNU/Linux Options
8810@subsection GNU/Linux Options
8811
8812These @samp{-m} options are defined for GNU/Linux targets:
8813
8814@table @gcctabopt
8815@item -mglibc
8816@opindex mglibc
8817Use the GNU C library instead of uClibc. This is the default except
8818on @samp{*-*-linux-*uclibc*} targets.
8819
8820@item -muclibc
8821@opindex muclibc
8822Use uClibc instead of the GNU C library. This is the default on
8823@samp{*-*-linux-*uclibc*} targets.
8824@end table
8825
8826@node H8/300 Options
8827@subsection H8/300 Options
8828
8829These @samp{-m} options are defined for the H8/300 implementations:
8830
8831@table @gcctabopt
8832@item -mrelax
8833@opindex mrelax
8834Shorten some address references at link time, when possible; uses the
8835linker option @option{-relax}. @xref{H8/300,, @code{ld} and the H8/300,
8836ld, Using ld}, for a fuller description.
8837
8838@item -mh
8839@opindex mh
8840Generate code for the H8/300H@.
8841
8842@item -ms
8843@opindex ms
8844Generate code for the H8S@.
8845
8846@item -mn
8847@opindex mn
8848Generate code for the H8S and H8/300H in the normal mode. This switch
8849must be used either with @option{-mh} or @option{-ms}.
8850
8851@item -ms2600
8852@opindex ms2600
8853Generate code for the H8S/2600. This switch must be used with @option{-ms}.
8854
8855@item -mint32
8856@opindex mint32
8857Make @code{int} data 32 bits by default.
8858
8859@item -malign-300
8860@opindex malign-300
8861On the H8/300H and H8S, use the same alignment rules as for the H8/300.
8862The default for the H8/300H and H8S is to align longs and floats on 4
8863byte boundaries.
8864@option{-malign-300} causes them to be aligned on 2 byte boundaries.
8865This option has no effect on the H8/300.
8866@end table
8867
8868@node HPPA Options
8869@subsection HPPA Options
8870@cindex HPPA Options
8871
8872These @samp{-m} options are defined for the HPPA family of computers:
8873
8874@table @gcctabopt
8875@item -march=@var{architecture-type}
8876@opindex march
8877Generate code for the specified architecture. The choices for
8878@var{architecture-type} are @samp{1.0} for PA 1.0, @samp{1.1} for PA
88791.1, and @samp{2.0} for PA 2.0 processors. Refer to
8880@file{/usr/lib/sched.models} on an HP-UX system to determine the proper
8881architecture option for your machine. Code compiled for lower numbered
8882architectures will run on higher numbered architectures, but not the
8883other way around.
8884
8885@item -mpa-risc-1-0
8886@itemx -mpa-risc-1-1
8887@itemx -mpa-risc-2-0
8888@opindex mpa-risc-1-0
8889@opindex mpa-risc-1-1
8890@opindex mpa-risc-2-0
8891Synonyms for @option{-march=1.0}, @option{-march=1.1}, and @option{-march=2.0} respectively.
8892
8893@item -mbig-switch
8894@opindex mbig-switch
8895Generate code suitable for big switch tables. Use this option only if
8896the assembler/linker complain about out of range branches within a switch
8897table.
8898
8899@item -mjump-in-delay
8900@opindex mjump-in-delay
8901Fill delay slots of function calls with unconditional jump instructions
8902by modifying the return pointer for the function call to be the target
8903of the conditional jump.
8904
8905@item -mdisable-fpregs
8906@opindex mdisable-fpregs
8907Prevent floating point registers from being used in any manner. This is
8908necessary for compiling kernels which perform lazy context switching of
8909floating point registers. If you use this option and attempt to perform
8910floating point operations, the compiler will abort.
8911
8912@item -mdisable-indexing
8913@opindex mdisable-indexing
8914Prevent the compiler from using indexing address modes. This avoids some
8915rather obscure problems when compiling MIG generated code under MACH@.
8916
8917@item -mno-space-regs
8918@opindex mno-space-regs
8919Generate code that assumes the target has no space registers. This allows
8920GCC to generate faster indirect calls and use unscaled index address modes.
8921
8922Such code is suitable for level 0 PA systems and kernels.
8923
8924@item -mfast-indirect-calls
8925@opindex mfast-indirect-calls
8926Generate code that assumes calls never cross space boundaries. This
8927allows GCC to emit code which performs faster indirect calls.
8928
8929This option will not work in the presence of shared libraries or nested
8930functions.
8931
8932@item -mfixed-range=@var{register-range}
8933@opindex mfixed-range
8934Generate code treating the given register range as fixed registers.
8935A fixed register is one that the register allocator can not use. This is
8936useful when compiling kernel code. A register range is specified as
8937two registers separated by a dash. Multiple register ranges can be
8938specified separated by a comma.
8939
8940@item -mlong-load-store
8941@opindex mlong-load-store
8942Generate 3-instruction load and store sequences as sometimes required by
8943the HP-UX 10 linker. This is equivalent to the @samp{+k} option to
8944the HP compilers.
8945
8946@item -mportable-runtime
8947@opindex mportable-runtime
8948Use the portable calling conventions proposed by HP for ELF systems.
8949
8950@item -mgas
8951@opindex mgas
8952Enable the use of assembler directives only GAS understands.
8953
8954@item -mschedule=@var{cpu-type}
8955@opindex mschedule
8956Schedule code according to the constraints for the machine type
8957@var{cpu-type}. The choices for @var{cpu-type} are @samp{700}
8958@samp{7100}, @samp{7100LC}, @samp{7200}, @samp{7300} and @samp{8000}. Refer
8959to @file{/usr/lib/sched.models} on an HP-UX system to determine the
8960proper scheduling option for your machine. The default scheduling is
8961@samp{8000}.
8962
8963@item -mlinker-opt
8964@opindex mlinker-opt
8965Enable the optimization pass in the HP-UX linker. Note this makes symbolic
8966debugging impossible. It also triggers a bug in the HP-UX 8 and HP-UX 9
8967linkers in which they give bogus error messages when linking some programs.
8968
8969@item -msoft-float
8970@opindex msoft-float
8971Generate output containing library calls for floating point.
8972@strong{Warning:} the requisite libraries are not available for all HPPA
8973targets. Normally the facilities of the machine's usual C compiler are
8974used, but this cannot be done directly in cross-compilation. You must make
8975your own arrangements to provide suitable library functions for
8976cross-compilation. The embedded target @samp{hppa1.1-*-pro}
8977does provide software floating point support.
8978
8979@option{-msoft-float} changes the calling convention in the output file;
8980therefore, it is only useful if you compile @emph{all} of a program with
8981this option. In particular, you need to compile @file{libgcc.a}, the
8982library that comes with GCC, with @option{-msoft-float} in order for
8983this to work.
8984
8985@item -msio
8986@opindex msio
8987Generate the predefine, @code{_SIO}, for server IO@. The default is
8988@option{-mwsio}. This generates the predefines, @code{__hp9000s700},
8989@code{__hp9000s700__} and @code{_WSIO}, for workstation IO@. These
8990options are available under HP-UX and HI-UX@.
8991
8992@item -mgnu-ld
8993@opindex gnu-ld
8994Use GNU ld specific options. This passes @option{-shared} to ld when
8995building a shared library. It is the default when GCC is configured,
8996explicitly or implicitly, with the GNU linker. This option does not
8997have any affect on which ld is called, it only changes what parameters
8998are passed to that ld. The ld that is called is determined by the
8999@option{--with-ld} configure option, GCC's program search path, and
9000finally by the user's @env{PATH}. The linker used by GCC can be printed
9001using @samp{which `gcc -print-prog-name=ld`}. This option is only available
9002on the 64 bit HP-UX GCC, i.e. configured with @samp{hppa*64*-*-hpux*}.
9003
9004@item -mhp-ld
9005@opindex hp-ld
9006Use HP ld specific options. This passes @option{-b} to ld when building
9007a shared library and passes @option{+Accept TypeMismatch} to ld on all
9008links. It is the default when GCC is configured, explicitly or
9009implicitly, with the HP linker. This option does not have any affect on
9010which ld is called, it only changes what parameters are passed to that
9011ld. The ld that is called is determined by the @option{--with-ld}
9012configure option, GCC's program search path, and finally by the user's
9013@env{PATH}. The linker used by GCC can be printed using @samp{which
9014`gcc -print-prog-name=ld`}. This option is only available on the 64 bit
9015HP-UX GCC, i.e. configured with @samp{hppa*64*-*-hpux*}.
9016
9017@item -mlong-calls
9018@opindex mno-long-calls
9019Generate code that uses long call sequences. This ensures that a call
9020is always able to reach linker generated stubs. The default is to generate
9021long calls only when the distance from the call site to the beginning
9022of the function or translation unit, as the case may be, exceeds a
9023predefined limit set by the branch type being used. The limits for
9024normal calls are 7,600,000 and 240,000 bytes, respectively for the
9025PA 2.0 and PA 1.X architectures. Sibcalls are always limited at
9026240,000 bytes.
9027
9028Distances are measured from the beginning of functions when using the
9029@option{-ffunction-sections} option, or when using the @option{-mgas}
9030and @option{-mno-portable-runtime} options together under HP-UX with
9031the SOM linker.
9032
9033It is normally not desirable to use this option as it will degrade
9034performance. However, it may be useful in large applications,
9035particularly when partial linking is used to build the application.
9036
9037The types of long calls used depends on the capabilities of the
9038assembler and linker, and the type of code being generated. The
9039impact on systems that support long absolute calls, and long pic
9040symbol-difference or pc-relative calls should be relatively small.
9041However, an indirect call is used on 32-bit ELF systems in pic code
9042and it is quite long.
9043
9044@item -munix=@var{unix-std}
9045@opindex march
9046Generate compiler predefines and select a startfile for the specified
9047UNIX standard. The choices for @var{unix-std} are @samp{93}, @samp{95}
9048and @samp{98}. @samp{93} is supported on all HP-UX versions. @samp{95}
9049is available on HP-UX 10.10 and later. @samp{98} is available on HP-UX
905011.11 and later. The default values are @samp{93} for HP-UX 10.00,
9051@samp{95} for HP-UX 10.10 though to 11.00, and @samp{98} for HP-UX 11.11
9052and later.
9053
9054@option{-munix=93} provides the same predefines as GCC 3.3 and 3.4.
9055@option{-munix=95} provides additional predefines for @code{XOPEN_UNIX}
9056and @code{_XOPEN_SOURCE_EXTENDED}, and the startfile @file{unix95.o}.
9057@option{-munix=98} provides additional predefines for @code{_XOPEN_UNIX},
9058@code{_XOPEN_SOURCE_EXTENDED}, @code{_INCLUDE__STDC_A1_SOURCE} and
9059@code{_INCLUDE_XOPEN_SOURCE_500}, and the startfile @file{unix98.o}.
9060
9061It is @emph{important} to note that this option changes the interfaces
9062for various library routines. It also affects the operational behavior
9063of the C library. Thus, @emph{extreme} care is needed in using this
9064option.
9065
9066Library code that is intended to operate with more than one UNIX
9067standard must test, set and restore the variable @var{__xpg4_extended_mask}
9068as appropriate. Most GNU software doesn't provide this capability.
9069
9070@item -nolibdld
9071@opindex nolibdld
9072Suppress the generation of link options to search libdld.sl when the
9073@option{-static} option is specified on HP-UX 10 and later.
9074
9075@item -static
9076@opindex static
9077The HP-UX implementation of setlocale in libc has a dependency on
9078libdld.sl. There isn't an archive version of libdld.sl. Thus,
9079when the @option{-static} option is specified, special link options
9080are needed to resolve this dependency.
9081
9082On HP-UX 10 and later, the GCC driver adds the necessary options to
9083link with libdld.sl when the @option{-static} option is specified.
9084This causes the resulting binary to be dynamic. On the 64-bit port,
9085the linkers generate dynamic binaries by default in any case. The
9086@option{-nolibdld} option can be used to prevent the GCC driver from
9087adding these link options.
9088
9089@item -threads
9090@opindex threads
9091Add support for multithreading with the @dfn{dce thread} library
9092under HP-UX@. This option sets flags for both the preprocessor and
9093linker.
9094@end table
9095
9096@node i386 and x86-64 Options
9097@subsection Intel 386 and AMD x86-64 Options
9098@cindex i386 Options
9099@cindex x86-64 Options
9100@cindex Intel 386 Options
9101@cindex AMD x86-64 Options
9102
9103These @samp{-m} options are defined for the i386 and x86-64 family of
9104computers:
9105
9106@table @gcctabopt
9107@item -mtune=@var{cpu-type}
9108@opindex mtune
9109Tune to @var{cpu-type} everything applicable about the generated code, except
9110for the ABI and the set of available instructions. The choices for
9111@var{cpu-type} are:
9112@table @emph
9113@item generic
9114Produce code optimized for the most common IA32/AMD64/EM64T processors.
9115If you know the CPU on which your code will run, then you should use
9116the corresponding @option{-mtune} option instead of
9117@option{-mtune=generic}. But, if you do not know exactly what CPU users
9118of your application will have, then you should use this option.
9119
9120As new processors are deployed in the marketplace, the behavior of this
9121option will change. Therefore, if you upgrade to a newer version of
9122GCC, the code generated option will change to reflect the processors
9123that were most common when that version of GCC was released.
9124
9125There is no @option{-march=generic} option because @option{-march}
9126indicates the instruction set the compiler can use, and there is no
9127generic instruction set applicable to all processors. In contrast,
9128@option{-mtune} indicates the processor (or, in this case, collection of
9129processors) for which the code is optimized.
9130@item native
9131This selects the CPU to tune for at compilation time by determining
9132the processor type of the compiling machine. Using @option{-mtune=native}
9133will produce code optimized for the local machine under the constraints
9134of the selected instruction set. Using @option{-march=native} will
9135enable all instruction subsets supported by the local machine (hence
9136the result might not run on different machines).
9137@item i386
9138Original Intel's i386 CPU@.
9139@item i486
9140Intel's i486 CPU@. (No scheduling is implemented for this chip.)
9141@item i586, pentium
9142Intel Pentium CPU with no MMX support.
9143@item pentium-mmx
9144Intel PentiumMMX CPU based on Pentium core with MMX instruction set support.
9145@item pentiumpro
9146Intel PentiumPro CPU@.
9147@item i686
9148Same as @code{generic}, but when used as @code{march} option, PentiumPro
9149instruction set will be used, so the code will run on all i686 family chips.
9150@item pentium2
9151Intel Pentium2 CPU based on PentiumPro core with MMX instruction set support.
9152@item pentium3, pentium3m
9153Intel Pentium3 CPU based on PentiumPro core with MMX and SSE instruction set
9154support.
9155@item pentium-m
9156Low power version of Intel Pentium3 CPU with MMX, SSE and SSE2 instruction set
9157support. Used by Centrino notebooks.
9158@item pentium4, pentium4m
9159Intel Pentium4 CPU with MMX, SSE and SSE2 instruction set support.
9160@item prescott
9161Improved version of Intel Pentium4 CPU with MMX, SSE, SSE2 and SSE3 instruction
9162set support.
9163@item nocona
9164Improved version of Intel Pentium4 CPU with 64-bit extensions, MMX, SSE,
9165SSE2 and SSE3 instruction set support.
9166@item core2
9167Intel Core2 CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3 and SSSE3
9168instruction set support.
9169@item k6
9170AMD K6 CPU with MMX instruction set support.
9171@item k6-2, k6-3
9172Improved versions of AMD K6 CPU with MMX and 3dNOW! instruction set support.
9173@item athlon, athlon-tbird
9174AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW! and SSE prefetch instructions
9175support.
9176@item athlon-4, athlon-xp, athlon-mp
9177Improved AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW! and full SSE
9178instruction set support.
9179@item k8, opteron, athlon64, athlon-fx
9180AMD K8 core based CPUs with x86-64 instruction set support. (This supersets
9181MMX, SSE, SSE2, 3dNOW!, enhanced 3dNOW! and 64-bit instruction set extensions.)
9182@item k8-sse3, opteron-sse3, athlon64-sse3
9183Improved versions of k8, opteron and athlon64 with SSE3 instruction set support.
9184@item amdfam10, barcelona
9185AMD Family 10h core based CPUs with x86-64 instruction set support. (This
9186supersets MMX, SSE, SSE2, SSE3, SSE4A, 3dNOW!, enhanced 3dNOW!, ABM and 64-bit
9187instruction set extensions.)
9188@item winchip-c6
9189IDT Winchip C6 CPU, dealt in same way as i486 with additional MMX instruction
9190set support.
9191@item winchip2
9192IDT Winchip2 CPU, dealt in same way as i486 with additional MMX and 3dNOW!
9193instruction set support.
9194@item c3
9195Via C3 CPU with MMX and 3dNOW! instruction set support. (No scheduling is
9196implemented for this chip.)
9197@item c3-2
9198Via C3-2 CPU with MMX and SSE instruction set support. (No scheduling is
9199implemented for this chip.)
9200@item geode
9201Embedded AMD CPU with MMX and 3dNOW! instruction set support.
9202@end table
9203
9204While picking a specific @var{cpu-type} will schedule things appropriately
9205for that particular chip, the compiler will not generate any code that
9206does not run on the i386 without the @option{-march=@var{cpu-type}} option
9207being used.
9208
9209@item -march=@var{cpu-type}
9210@opindex march
9211Generate instructions for the machine type @var{cpu-type}. The choices
9212for @var{cpu-type} are the same as for @option{-mtune}. Moreover,
9213specifying @option{-march=@var{cpu-type}} implies @option{-mtune=@var{cpu-type}}.
9214
9215@item -mcpu=@var{cpu-type}
9216@opindex mcpu
9217A deprecated synonym for @option{-mtune}.
9218
9219@item -m386
9220@itemx -m486
9221@itemx -mpentium
9222@itemx -mpentiumpro
9223@opindex m386
9224@opindex m486
9225@opindex mpentium
9226@opindex mpentiumpro
9227These options are synonyms for @option{-mtune=i386}, @option{-mtune=i486},
9228@option{-mtune=pentium}, and @option{-mtune=pentiumpro} respectively.
9229These synonyms are deprecated.
9230
9231@item -mfpmath=@var{unit}
9232@opindex march
9233Generate floating point arithmetics for selected unit @var{unit}. The choices
9234for @var{unit} are:
9235
9236@table @samp
9237@item 387
9238Use the standard 387 floating point coprocessor present majority of chips and
9239emulated otherwise. Code compiled with this option will run almost everywhere.
9240The temporary results are computed in 80bit precision instead of precision
9241specified by the type resulting in slightly different results compared to most
9242of other chips. See @option{-ffloat-store} for more detailed description.
9243
9244This is the default choice for i386 compiler.
9245
9246@item sse
9247Use scalar floating point instructions present in the SSE instruction set.
9248This instruction set is supported by Pentium3 and newer chips, in the AMD line
9249by Athlon-4, Athlon-xp and Athlon-mp chips. The earlier version of SSE
9250instruction set supports only single precision arithmetics, thus the double and
9251extended precision arithmetics is still done using 387. Later version, present
9252only in Pentium4 and the future AMD x86-64 chips supports double precision
9253arithmetics too.
9254
9255For the i386 compiler, you need to use @option{-march=@var{cpu-type}}, @option{-msse}
9256or @option{-msse2} switches to enable SSE extensions and make this option
9257effective. For the x86-64 compiler, these extensions are enabled by default.
9258
9259The resulting code should be considerably faster in the majority of cases and avoid
9260the numerical instability problems of 387 code, but may break some existing
9261code that expects temporaries to be 80bit.
9262
9263This is the default choice for the x86-64 compiler.
9264
9265@item sse,387
9266Attempt to utilize both instruction sets at once. This effectively double the
9267amount of available registers and on chips with separate execution units for
9268387 and SSE the execution resources too. Use this option with care, as it is
9269still experimental, because the GCC register allocator does not model separate
9270functional units well resulting in instable performance.
9271@end table
9272
9273@item -masm=@var{dialect}
9274@opindex masm=@var{dialect}
9275Output asm instructions using selected @var{dialect}. Supported
9276choices are @samp{intel} or @samp{att} (the default one). Darwin does
9277not support @samp{intel}.
9278
9279@item -mieee-fp
9280@itemx -mno-ieee-fp
9281@opindex mieee-fp
9282@opindex mno-ieee-fp
9283Control whether or not the compiler uses IEEE floating point
9284comparisons. These handle correctly the case where the result of a
9285comparison is unordered.
9286
9287@item -msoft-float
9288@opindex msoft-float
9289Generate output containing library calls for floating point.
9290@strong{Warning:} the requisite libraries are not part of GCC@.
9291Normally the facilities of the machine's usual C compiler are used, but
9292this can't be done directly in cross-compilation. You must make your
9293own arrangements to provide suitable library functions for
9294cross-compilation.
9295
9296On machines where a function returns floating point results in the 80387
9297register stack, some floating point opcodes may be emitted even if
9298@option{-msoft-float} is used.
9299
9300@item -mno-fp-ret-in-387
9301@opindex mno-fp-ret-in-387
9302Do not use the FPU registers for return values of functions.
9303
9304The usual calling convention has functions return values of types
9305@code{float} and @code{double} in an FPU register, even if there
9306is no FPU@. The idea is that the operating system should emulate
9307an FPU@.
9308
9309The option @option{-mno-fp-ret-in-387} causes such values to be returned
9310in ordinary CPU registers instead.
9311
9312@item -mno-fancy-math-387
9313@opindex mno-fancy-math-387
9314Some 387 emulators do not support the @code{sin}, @code{cos} and
9315@code{sqrt} instructions for the 387. Specify this option to avoid
9316generating those instructions. This option is the default on
9317OpenBSD and NetBSD@. This option is overridden when @option{-march}
9318indicates that the target cpu will always have an FPU and so the
9319instruction will not need emulation. As of revision 2.6.1, these
9320instructions are not generated unless you also use the
9321@option{-funsafe-math-optimizations} switch.
9322
9323@item -malign-double
9324@itemx -mno-align-double
9325@opindex malign-double
9326@opindex mno-align-double
9327Control whether GCC aligns @code{double}, @code{long double}, and
9328@code{long long} variables on a two word boundary or a one word
9329boundary. Aligning @code{double} variables on a two word boundary will
9330produce code that runs somewhat faster on a @samp{Pentium} at the
9331expense of more memory.
9332
9333On x86-64, @option{-malign-double} is enabled by default.
9334
9335@strong{Warning:} if you use the @option{-malign-double} switch,
9336structures containing the above types will be aligned differently than
9337the published application binary interface specifications for the 386
9338and will not be binary compatible with structures in code compiled
9339without that switch.
9340
9341@item -m96bit-long-double
9342@itemx -m128bit-long-double
9343@opindex m96bit-long-double
9344@opindex m128bit-long-double
9345These switches control the size of @code{long double} type. The i386
9346application binary interface specifies the size to be 96 bits,
9347so @option{-m96bit-long-double} is the default in 32 bit mode.
9348
9349Modern architectures (Pentium and newer) would prefer @code{long double}
9350to be aligned to an 8 or 16 byte boundary. In arrays or structures
9351conforming to the ABI, this would not be possible. So specifying a
9352@option{-m128bit-long-double} will align @code{long double}
9353to a 16 byte boundary by padding the @code{long double} with an additional
935432 bit zero.
9355
9356In the x86-64 compiler, @option{-m128bit-long-double} is the default choice as
9357its ABI specifies that @code{long double} is to be aligned on 16 byte boundary.
9358
9359Notice that neither of these options enable any extra precision over the x87
9360standard of 80 bits for a @code{long double}.
9361
9362@strong{Warning:} if you override the default value for your target ABI, the
9363structures and arrays containing @code{long double} variables will change
9364their size as well as function calling convention for function taking
9365@code{long double} will be modified. Hence they will not be binary
9366compatible with arrays or structures in code compiled without that switch.
9367
9368@item -mmlarge-data-threshold=@var{number}
9369@opindex mlarge-data-threshold=@var{number}
9370When @option{-mcmodel=medium} is specified, the data greater than
9371@var{threshold} are placed in large data section. This value must be the
9372same across all object linked into the binary and defaults to 65535.
9373
9374@item -msvr3-shlib
9375@itemx -mno-svr3-shlib
9376@opindex msvr3-shlib
9377@opindex mno-svr3-shlib
9378Control whether GCC places uninitialized local variables into the
9379@code{bss} or @code{data} segments. @option{-msvr3-shlib} places them
9380into @code{bss}. These options are meaningful only on System V Release 3.
9381
9382@item -mrtd
9383@opindex mrtd
9384Use a different function-calling convention, in which functions that
9385take a fixed number of arguments return with the @code{ret} @var{num}
9386instruction, which pops their arguments while returning. This saves one
9387instruction in the caller since there is no need to pop the arguments
9388there.
9389
9390You can specify that an individual function is called with this calling
9391sequence with the function attribute @samp{stdcall}. You can also
9392override the @option{-mrtd} option by using the function attribute
9393@samp{cdecl}. @xref{Function Attributes}.
9394
9395@strong{Warning:} this calling convention is incompatible with the one
9396normally used on Unix, so you cannot use it if you need to call
9397libraries compiled with the Unix compiler.
9398
9399Also, you must provide function prototypes for all functions that
9400take variable numbers of arguments (including @code{printf});
9401otherwise incorrect code will be generated for calls to those
9402functions.
9403
9404In addition, seriously incorrect code will result if you call a
9405function with too many arguments. (Normally, extra arguments are
9406harmlessly ignored.)
9407
9408@item -mregparm=@var{num}
9409@opindex mregparm
9410Control how many registers are used to pass integer arguments. By
9411default, no registers are used to pass arguments, and at most 3
9412registers can be used. You can control this behavior for a specific
9413function by using the function attribute @samp{regparm}.
9414@xref{Function Attributes}.
9415
9416@strong{Warning:} if you use this switch, and
9417@var{num} is nonzero, then you must build all modules with the same
9418value, including any libraries. This includes the system libraries and
9419startup modules.
9420
9421@item -msseregparm
9422@opindex msseregparm
9423Use SSE register passing conventions for float and double arguments
9424and return values. You can control this behavior for a specific
9425function by using the function attribute @samp{sseregparm}.
9426@xref{Function Attributes}.
9427
9428@strong{Warning:} if you use this switch then you must build all
9429modules with the same value, including any libraries. This includes
9430the system libraries and startup modules.
9431
9432@item -mstackrealign
9433@opindex mstackrealign
9434Realign the stack at entry. On the Intel x86, the
9435@option{-mstackrealign} option will generate an alternate prologue and
9436epilogue that realigns the runtime stack. This supports mixing legacy
9437codes that keep a 4-byte aligned stack with modern codes that keep a
943816-byte stack for SSE compatibility. The alternate prologue and
9439epilogue are slower and bigger than the regular ones, and the
9440alternate prologue requires an extra scratch register; this lowers the
9441number of registers available if used in conjunction with the
9442@code{regparm} attribute. The @option{-mstackrealign} option is
9443incompatible with the nested function prologue; this is considered a
9444hard error. See also the attribute @code{force_align_arg_pointer},
9445applicable to individual functions.
9446
9447@item -mpreferred-stack-boundary=@var{num}
9448@opindex mpreferred-stack-boundary
9449Attempt to keep the stack boundary aligned to a 2 raised to @var{num}
9450byte boundary. If @option{-mpreferred-stack-boundary} is not specified,
9451the default is 4 (16 bytes or 128 bits).
9452
9453On Pentium and PentiumPro, @code{double} and @code{long double} values
9454should be aligned to an 8 byte boundary (see @option{-malign-double}) or
9455suffer significant run time performance penalties. On Pentium III, the
9456Streaming SIMD Extension (SSE) data type @code{__m128} may not work
9457properly if it is not 16 byte aligned.
9458
9459To ensure proper alignment of this values on the stack, the stack boundary
9460must be as aligned as that required by any value stored on the stack.
9461Further, every function must be generated such that it keeps the stack
9462aligned. Thus calling a function compiled with a higher preferred
9463stack boundary from a function compiled with a lower preferred stack
9464boundary will most likely misalign the stack. It is recommended that
9465libraries that use callbacks always use the default setting.
9466
9467This extra alignment does consume extra stack space, and generally
9468increases code size. Code that is sensitive to stack space usage, such
9469as embedded systems and operating system kernels, may want to reduce the
9470preferred alignment to @option{-mpreferred-stack-boundary=2}.
9471
9472@item -mmmx
9473@itemx -mno-mmx
9474@item -msse
9475@itemx -mno-sse
9476@item -msse2
9477@itemx -mno-sse2
9478@item -msse3
9479@itemx -mno-sse3
9480@item -mssse3
9481@itemx -mno-ssse3
9482@item -msse4a
9483@item -mno-sse4a
9484@item -m3dnow
9485@itemx -mno-3dnow
9486@item -mpopcnt
9487@itemx -mno-popcnt
9488@item -mabm
9489@itemx -mno-abm
9490@item -maes
9491@itemx -mno-aes
9492@opindex mmmx
9493@opindex mno-mmx
9494@opindex msse
9495@opindex mno-sse
9496@opindex m3dnow
9497@opindex mno-3dnow
9498These switches enable or disable the use of instructions in the MMX,
9499SSE, SSE2, SSE3, SSSE3, SSE4A, ABM, AES or 3DNow! extended
9500instruction sets. These extensions are also available as built-in
9501functions: see @ref{X86 Built-in Functions}, for details of the functions
9502enabled and disabled by these switches.
9503
9504To have SSE/SSE2 instructions generated automatically from floating-point
9505code (as opposed to 387 instructions), see @option{-mfpmath=sse}.
9506
9507These options will enable GCC to use these extended instructions in
9508generated code, even without @option{-mfpmath=sse}. Applications which
9509perform runtime CPU detection must compile separate files for each
9510supported architecture, using the appropriate flags. In particular,
9511the file containing the CPU detection code should be compiled without
9512these options.
9513
9514@item -mpush-args
9515@itemx -mno-push-args
9516@opindex mpush-args
9517@opindex mno-push-args
9518Use PUSH operations to store outgoing parameters. This method is shorter
9519and usually equally fast as method using SUB/MOV operations and is enabled
9520by default. In some cases disabling it may improve performance because of
9521improved scheduling and reduced dependencies.
9522
9523@item -maccumulate-outgoing-args
9524@opindex maccumulate-outgoing-args
9525If enabled, the maximum amount of space required for outgoing arguments will be
9526computed in the function prologue. This is faster on most modern CPUs
9527because of reduced dependencies, improved scheduling and reduced stack usage
9528when preferred stack boundary is not equal to 2. The drawback is a notable
9529increase in code size. This switch implies @option{-mno-push-args}.
9530
9531@item -mthreads
9532@opindex mthreads
9533Support thread-safe exception handling on @samp{Mingw32}. Code that relies
9534on thread-safe exception handling must compile and link all code with the
9535@option{-mthreads} option. When compiling, @option{-mthreads} defines
9536@option{-D_MT}; when linking, it links in a special thread helper library
9537@option{-lmingwthrd} which cleans up per thread exception handling data.
9538
9539@item -mno-align-stringops
9540@opindex mno-align-stringops
9541Do not align destination of inlined string operations. This switch reduces
9542code size and improves performance in case the destination is already aligned,
9543but GCC doesn't know about it.
9544
9545@item -minline-all-stringops
9546@opindex minline-all-stringops
9547By default GCC inlines string operations only when destination is known to be
9548aligned at least to 4 byte boundary. This enables more inlining, increase code
9549size, but may improve performance of code that depends on fast memcpy, strlen
9550and memset for short lengths.
9551
9552@item -momit-leaf-frame-pointer
9553@opindex momit-leaf-frame-pointer
9554Don't keep the frame pointer in a register for leaf functions. This
9555avoids the instructions to save, set up and restore frame pointers and
9556makes an extra register available in leaf functions. The option
9557@option{-fomit-frame-pointer} removes the frame pointer for all functions
9558which might make debugging harder.
9559
9560@item -mtls-direct-seg-refs
9561@itemx -mno-tls-direct-seg-refs
9562@opindex mtls-direct-seg-refs
9563Controls whether TLS variables may be accessed with offsets from the
9564TLS segment register (@code{%gs} for 32-bit, @code{%fs} for 64-bit),
9565or whether the thread base pointer must be added. Whether or not this
9566is legal depends on the operating system, and whether it maps the
9567segment to cover the entire TLS area.
9568
9569For systems that use GNU libc, the default is on.
9570@end table
9571
9572These @samp{-m} switches are supported in addition to the above
9573on AMD x86-64 processors in 64-bit environments.
9574
9575@table @gcctabopt
9576@item -m32
9577@itemx -m64
9578@opindex m32
9579@opindex m64
9580Generate code for a 32-bit or 64-bit environment.
9581The 32-bit environment sets int, long and pointer to 32 bits and
9582generates code that runs on any i386 system.
9583The 64-bit environment sets int to 32 bits and long and pointer
9584to 64 bits and generates code for AMD's x86-64 architecture. For
9585darwin only the -m64 option turns off the @option{-fno-pic} and
9586@option{-mdynamic-no-pic} options.
9587
9588@item -mno-red-zone
9589@opindex no-red-zone
9590Do not use a so called red zone for x86-64 code. The red zone is mandated
9591by the x86-64 ABI, it is a 128-byte area beyond the location of the
9592stack pointer that will not be modified by signal or interrupt handlers
9593and therefore can be used for temporary data without adjusting the stack
9594pointer. The flag @option{-mno-red-zone} disables this red zone.
9595
9596@item -mcmodel=small
9597@opindex mcmodel=small
9598Generate code for the small code model: the program and its symbols must
9599be linked in the lower 2 GB of the address space. Pointers are 64 bits.
9600Programs can be statically or dynamically linked. This is the default
9601code model.
9602
9603@item -mcmodel=kernel
9604@opindex mcmodel=kernel
9605Generate code for the kernel code model. The kernel runs in the
9606negative 2 GB of the address space.
9607This model has to be used for Linux kernel code.
9608
9609@item -mcmodel=medium
9610@opindex mcmodel=medium
9611Generate code for the medium model: The program is linked in the lower 2
9612GB of the address space but symbols can be located anywhere in the
9613address space. Programs can be statically or dynamically linked, but
9614building of shared libraries are not supported with the medium model.
9615
9616@item -mcmodel=large
9617@opindex mcmodel=large
9618Generate code for the large model: This model makes no assumptions
9619about addresses and sizes of sections. Currently GCC does not implement
9620this model.
9621@end table
9622
9623@node IA-64 Options
9624@subsection IA-64 Options
9625@cindex IA-64 Options
9626
9627These are the @samp{-m} options defined for the Intel IA-64 architecture.
9628
9629@table @gcctabopt
9630@item -mbig-endian
9631@opindex mbig-endian
9632Generate code for a big endian target. This is the default for HP-UX@.
9633
9634@item -mlittle-endian
9635@opindex mlittle-endian
9636Generate code for a little endian target. This is the default for AIX5
9637and GNU/Linux.
9638
9639@item -mgnu-as
9640@itemx -mno-gnu-as
9641@opindex mgnu-as
9642@opindex mno-gnu-as
9643Generate (or don't) code for the GNU assembler. This is the default.
9644@c Also, this is the default if the configure option @option{--with-gnu-as}
9645@c is used.
9646
9647@item -mgnu-ld
9648@itemx -mno-gnu-ld
9649@opindex mgnu-ld
9650@opindex mno-gnu-ld
9651Generate (or don't) code for the GNU linker. This is the default.
9652@c Also, this is the default if the configure option @option{--with-gnu-ld}
9653@c is used.
9654
9655@item -mno-pic
9656@opindex mno-pic
9657Generate code that does not use a global pointer register. The result
9658is not position independent code, and violates the IA-64 ABI@.
9659
9660@item -mvolatile-asm-stop
9661@itemx -mno-volatile-asm-stop
9662@opindex mvolatile-asm-stop
9663@opindex mno-volatile-asm-stop
9664Generate (or don't) a stop bit immediately before and after volatile asm
9665statements.
9666
9667@item -mregister-names
9668@itemx -mno-register-names
9669@opindex mregister-names
9670@opindex mno-register-names
9671Generate (or don't) @samp{in}, @samp{loc}, and @samp{out} register names for
9672the stacked registers. This may make assembler output more readable.
9673
9674@item -mno-sdata
9675@itemx -msdata
9676@opindex mno-sdata
9677@opindex msdata
9678Disable (or enable) optimizations that use the small data section. This may
9679be useful for working around optimizer bugs.
9680
9681@item -mconstant-gp
9682@opindex mconstant-gp
9683Generate code that uses a single constant global pointer value. This is
9684useful when compiling kernel code.
9685
9686@item -mauto-pic
9687@opindex mauto-pic
9688Generate code that is self-relocatable. This implies @option{-mconstant-gp}.
9689This is useful when compiling firmware code.
9690
9691@item -minline-float-divide-min-latency
9692@opindex minline-float-divide-min-latency
9693Generate code for inline divides of floating point values
9694using the minimum latency algorithm.
9695
9696@item -minline-float-divide-max-throughput
9697@opindex minline-float-divide-max-throughput
9698Generate code for inline divides of floating point values
9699using the maximum throughput algorithm.
9700
9701@item -minline-int-divide-min-latency
9702@opindex minline-int-divide-min-latency
9703Generate code for inline divides of integer values
9704using the minimum latency algorithm.
9705
9706@item -minline-int-divide-max-throughput
9707@opindex minline-int-divide-max-throughput
9708Generate code for inline divides of integer values
9709using the maximum throughput algorithm.
9710
9711@item -minline-sqrt-min-latency
9712@opindex minline-sqrt-min-latency
9713Generate code for inline square roots
9714using the minimum latency algorithm.
9715
9716@item -minline-sqrt-max-throughput
9717@opindex minline-sqrt-max-throughput
9718Generate code for inline square roots
9719using the maximum throughput algorithm.
9720
9721@item -mno-dwarf2-asm
9722@itemx -mdwarf2-asm
9723@opindex mno-dwarf2-asm
9724@opindex mdwarf2-asm
9725Don't (or do) generate assembler code for the DWARF2 line number debugging
9726info. This may be useful when not using the GNU assembler.
9727
9728@item -mearly-stop-bits
9729@itemx -mno-early-stop-bits
9730@opindex mearly-stop-bits
9731@opindex mno-early-stop-bits
9732Allow stop bits to be placed earlier than immediately preceding the
9733instruction that triggered the stop bit. This can improve instruction
9734scheduling, but does not always do so.
9735
9736@item -mfixed-range=@var{register-range}
9737@opindex mfixed-range
9738Generate code treating the given register range as fixed registers.
9739A fixed register is one that the register allocator can not use. This is
9740useful when compiling kernel code. A register range is specified as
9741two registers separated by a dash. Multiple register ranges can be
9742specified separated by a comma.
9743
9744@item -mtls-size=@var{tls-size}
9745@opindex mtls-size
9746Specify bit size of immediate TLS offsets. Valid values are 14, 22, and
974764.
9748
9749@item -mtune=@var{cpu-type}
9750@opindex mtune
9751Tune the instruction scheduling for a particular CPU, Valid values are
9752itanium, itanium1, merced, itanium2, and mckinley.
9753
9754@item -mt
9755@itemx -pthread
9756@opindex mt
9757@opindex pthread
9758Add support for multithreading using the POSIX threads library. This
9759option sets flags for both the preprocessor and linker. It does
9760not affect the thread safety of object code produced by the compiler or
9761that of libraries supplied with it. These are HP-UX specific flags.
9762
9763@item -milp32
9764@itemx -mlp64
9765@opindex milp32
9766@opindex mlp64
9767Generate code for a 32-bit or 64-bit environment.
9768The 32-bit environment sets int, long and pointer to 32 bits.
9769The 64-bit environment sets int to 32 bits and long and pointer
9770to 64 bits. These are HP-UX specific flags.
9771
9772@item -mno-sched-br-data-spec
9773@itemx -msched-br-data-spec
9774@opindex mno-sched-br-data-spec
9775@opindex msched-br-data-spec
9776(Dis/En)able data speculative scheduling before reload.
9777This will result in generation of the ld.a instructions and
9778the corresponding check instructions (ld.c / chk.a).
9779The default is 'disable'.
9780
9781@item -msched-ar-data-spec
9782@itemx -mno-sched-ar-data-spec
9783@opindex msched-ar-data-spec
9784@opindex mno-sched-ar-data-spec
9785(En/Dis)able data speculative scheduling after reload.
9786This will result in generation of the ld.a instructions and
9787the corresponding check instructions (ld.c / chk.a).
9788The default is 'enable'.
9789
9790@item -mno-sched-control-spec
9791@itemx -msched-control-spec
9792@opindex mno-sched-control-spec
9793@opindex msched-control-spec
9794(Dis/En)able control speculative scheduling. This feature is
9795available only during region scheduling (i.e. before reload).
9796This will result in generation of the ld.s instructions and
9797the corresponding check instructions chk.s .
9798The default is 'disable'.
9799
9800@item -msched-br-in-data-spec
9801@itemx -mno-sched-br-in-data-spec
9802@opindex msched-br-in-data-spec
9803@opindex mno-sched-br-in-data-spec
9804(En/Dis)able speculative scheduling of the instructions that
9805are dependent on the data speculative loads before reload.
9806This is effective only with @option{-msched-br-data-spec} enabled.
9807The default is 'enable'.
9808
9809@item -msched-ar-in-data-spec
9810@itemx -mno-sched-ar-in-data-spec
9811@opindex msched-ar-in-data-spec
9812@opindex mno-sched-ar-in-data-spec
9813(En/Dis)able speculative scheduling of the instructions that
9814are dependent on the data speculative loads after reload.
9815This is effective only with @option{-msched-ar-data-spec} enabled.
9816The default is 'enable'.
9817
9818@item -msched-in-control-spec
9819@itemx -mno-sched-in-control-spec
9820@opindex msched-in-control-spec
9821@opindex mno-sched-in-control-spec
9822(En/Dis)able speculative scheduling of the instructions that
9823are dependent on the control speculative loads.
9824This is effective only with @option{-msched-control-spec} enabled.
9825The default is 'enable'.
9826
9827@item -msched-ldc
9828@itemx -mno-sched-ldc
9829@opindex msched-ldc
9830@opindex mno-sched-ldc
9831(En/Dis)able use of simple data speculation checks ld.c .
9832If disabled, only chk.a instructions will be emitted to check
9833data speculative loads.
9834The default is 'enable'.
9835
9836@item -mno-sched-control-ldc
9837@itemx -msched-control-ldc
9838@opindex mno-sched-control-ldc
9839@opindex msched-control-ldc
9840(Dis/En)able use of ld.c instructions to check control speculative loads.
9841If enabled, in case of control speculative load with no speculatively
9842scheduled dependent instructions this load will be emitted as ld.sa and
9843ld.c will be used to check it.
9844The default is 'disable'.
9845
9846@item -mno-sched-spec-verbose
9847@itemx -msched-spec-verbose
9848@opindex mno-sched-spec-verbose
9849@opindex msched-spec-verbose
9850(Dis/En)able printing of the information about speculative motions.
9851
9852@item -mno-sched-prefer-non-data-spec-insns
9853@itemx -msched-prefer-non-data-spec-insns
9854@opindex mno-sched-prefer-non-data-spec-insns
9855@opindex msched-prefer-non-data-spec-insns
9856If enabled, data speculative instructions will be chosen for schedule
9857only if there are no other choices at the moment. This will make
9858the use of the data speculation much more conservative.
9859The default is 'disable'.
9860
9861@item -mno-sched-prefer-non-control-spec-insns
9862@itemx -msched-prefer-non-control-spec-insns
9863@opindex mno-sched-prefer-non-control-spec-insns
9864@opindex msched-prefer-non-control-spec-insns
9865If enabled, control speculative instructions will be chosen for schedule
9866only if there are no other choices at the moment. This will make
9867the use of the control speculation much more conservative.
9868The default is 'disable'.
9869
9870@item -mno-sched-count-spec-in-critical-path
9871@itemx -msched-count-spec-in-critical-path
9872@opindex mno-sched-count-spec-in-critical-path
9873@opindex msched-count-spec-in-critical-path
9874If enabled, speculative dependencies will be considered during
9875computation of the instructions priorities. This will make the use of the
9876speculation a bit more conservative.
9877The default is 'disable'.
9878
9879@end table
9880
9881@node M32C Options
9882@subsection M32C Options
9883@cindex M32C options
9884
9885@table @gcctabopt
9886@item -mcpu=@var{name}
9887@opindex mcpu=
9888Select the CPU for which code is generated. @var{name} may be one of
9889@samp{r8c} for the R8C/Tiny series, @samp{m16c} for the M16C (up to
9890/60) series, @samp{m32cm} for the M16C/80 series, or @samp{m32c} for
9891the M32C/80 series.
9892
9893@item -msim
9894@opindex msim
9895Specifies that the program will be run on the simulator. This causes
9896an alternate runtime library to be linked in which supports, for
9897example, file I/O. You must not use this option when generating
9898programs that will run on real hardware; you must provide your own
9899runtime library for whatever I/O functions are needed.
9900
9901@item -memregs=@var{number}
9902@opindex memregs=
9903Specifies the number of memory-based pseudo-registers GCC will use
9904during code generation. These pseudo-registers will be used like real
9905registers, so there is a tradeoff between GCC's ability to fit the
9906code into available registers, and the performance penalty of using
9907memory instead of registers. Note that all modules in a program must
9908be compiled with the same value for this option. Because of that, you
9909must not use this option with the default runtime libraries gcc
9910builds.
9911
9912@end table
9913
9914@node M32R/D Options
9915@subsection M32R/D Options
9916@cindex M32R/D options
9917
9918These @option{-m} options are defined for Renesas M32R/D architectures:
9919
9920@table @gcctabopt
9921@item -m32r2
9922@opindex m32r2
9923Generate code for the M32R/2@.
9924
9925@item -m32rx
9926@opindex m32rx
9927Generate code for the M32R/X@.
9928
9929@item -m32r
9930@opindex m32r
9931Generate code for the M32R@. This is the default.
9932
9933@item -mmodel=small
9934@opindex mmodel=small
9935Assume all objects live in the lower 16MB of memory (so that their addresses
9936can be loaded with the @code{ld24} instruction), and assume all subroutines
9937are reachable with the @code{bl} instruction.
9938This is the default.
9939
9940The addressability of a particular object can be set with the
9941@code{model} attribute.
9942
9943@item -mmodel=medium
9944@opindex mmodel=medium
9945Assume objects may be anywhere in the 32-bit address space (the compiler
9946will generate @code{seth/add3} instructions to load their addresses), and
9947assume all subroutines are reachable with the @code{bl} instruction.
9948
9949@item -mmodel=large
9950@opindex mmodel=large
9951Assume objects may be anywhere in the 32-bit address space (the compiler
9952will generate @code{seth/add3} instructions to load their addresses), and
9953assume subroutines may not be reachable with the @code{bl} instruction
9954(the compiler will generate the much slower @code{seth/add3/jl}
9955instruction sequence).
9956
9957@item -msdata=none
9958@opindex msdata=none
9959Disable use of the small data area. Variables will be put into
9960one of @samp{.data}, @samp{bss}, or @samp{.rodata} (unless the
9961@code{section} attribute has been specified).
9962This is the default.
9963
9964The small data area consists of sections @samp{.sdata} and @samp{.sbss}.
9965Objects may be explicitly put in the small data area with the
9966@code{section} attribute using one of these sections.
9967
9968@item -msdata=sdata
9969@opindex msdata=sdata
9970Put small global and static data in the small data area, but do not
9971generate special code to reference them.
9972
9973@item -msdata=use
9974@opindex msdata=use
9975Put small global and static data in the small data area, and generate
9976special instructions to reference them.
9977
9978@item -G @var{num}
9979@opindex G
9980@cindex smaller data references
9981Put global and static objects less than or equal to @var{num} bytes
9982into the small data or bss sections instead of the normal data or bss
9983sections. The default value of @var{num} is 8.
9984The @option{-msdata} option must be set to one of @samp{sdata} or @samp{use}
9985for this option to have any effect.
9986
9987All modules should be compiled with the same @option{-G @var{num}} value.
9988Compiling with different values of @var{num} may or may not work; if it
9989doesn't the linker will give an error message---incorrect code will not be
9990generated.
9991
9992@item -mdebug
9993@opindex mdebug
9994Makes the M32R specific code in the compiler display some statistics
9995that might help in debugging programs.
9996
9997@item -malign-loops
9998@opindex malign-loops
9999Align all loops to a 32-byte boundary.
10000
10001@item -mno-align-loops
10002@opindex mno-align-loops
10003Do not enforce a 32-byte alignment for loops. This is the default.
10004
10005@item -missue-rate=@var{number}
10006@opindex missue-rate=@var{number}
10007Issue @var{number} instructions per cycle. @var{number} can only be 1
10008or 2.
10009
10010@item -mbranch-cost=@var{number}
10011@opindex mbranch-cost=@var{number}
10012@var{number} can only be 1 or 2. If it is 1 then branches will be
10013preferred over conditional code, if it is 2, then the opposite will
10014apply.
10015
10016@item -mflush-trap=@var{number}
10017@opindex mflush-trap=@var{number}
10018Specifies the trap number to use to flush the cache. The default is
1001912. Valid numbers are between 0 and 15 inclusive.
10020
10021@item -mno-flush-trap
10022@opindex mno-flush-trap
10023Specifies that the cache cannot be flushed by using a trap.
10024
10025@item -mflush-func=@var{name}
10026@opindex mflush-func=@var{name}
10027Specifies the name of the operating system function to call to flush
10028the cache. The default is @emph{_flush_cache}, but a function call
10029will only be used if a trap is not available.
10030
10031@item -mno-flush-func
10032@opindex mno-flush-func
10033Indicates that there is no OS function for flushing the cache.
10034
10035@end table
10036
10037@node M680x0 Options
10038@subsection M680x0 Options
10039@cindex M680x0 options
10040
10041These are the @samp{-m} options defined for the 68000 series. The default
10042values for these options depends on which style of 68000 was selected when
10043the compiler was configured; the defaults for the most common choices are
10044given below.
10045
10046@table @gcctabopt
10047@item -m68000
10048@itemx -mc68000
10049@opindex m68000
10050@opindex mc68000
10051Generate output for a 68000. This is the default
10052when the compiler is configured for 68000-based systems.
10053
10054Use this option for microcontrollers with a 68000 or EC000 core,
10055including the 68008, 68302, 68306, 68307, 68322, 68328 and 68356.
10056
10057@item -m68020
10058@itemx -mc68020
10059@opindex m68020
10060@opindex mc68020
10061Generate output for a 68020. This is the default
10062when the compiler is configured for 68020-based systems.
10063
10064@item -m68881
10065@opindex m68881
10066Generate output containing 68881 instructions for floating point.
10067This is the default for most 68020 systems unless @option{--nfp} was
10068specified when the compiler was configured.
10069
10070@item -m68030
10071@opindex m68030
10072Generate output for a 68030. This is the default when the compiler is
10073configured for 68030-based systems.
10074
10075@item -m68040
10076@opindex m68040
10077Generate output for a 68040. This is the default when the compiler is
10078configured for 68040-based systems.
10079
10080This option inhibits the use of 68881/68882 instructions that have to be
10081emulated by software on the 68040. Use this option if your 68040 does not
10082have code to emulate those instructions.
10083
10084@item -m68060
10085@opindex m68060
10086Generate output for a 68060. This is the default when the compiler is
10087configured for 68060-based systems.
10088
10089This option inhibits the use of 68020 and 68881/68882 instructions that
10090have to be emulated by software on the 68060. Use this option if your 68060
10091does not have code to emulate those instructions.
10092
10093@item -mcpu32
10094@opindex mcpu32
10095Generate output for a CPU32. This is the default
10096when the compiler is configured for CPU32-based systems.
10097
10098Use this option for microcontrollers with a
10099CPU32 or CPU32+ core, including the 68330, 68331, 68332, 68333, 68334,
1010068336, 68340, 68341, 68349 and 68360.
10101
10102@item -m5200
10103@opindex m5200
10104Generate output for a 520X ``coldfire'' family cpu. This is the default
10105when the compiler is configured for 520X-based systems.
10106
10107Use this option for microcontroller with a 5200 core, including
10108the MCF5202, MCF5203, MCF5204 and MCF5202.
10109
10110@item -mcfv4e
10111@opindex mcfv4e
10112Generate output for a ColdFire V4e family cpu (e.g.@: 547x/548x).
10113This includes use of hardware floating point instructions.
10114
10115@item -m68020-40
10116@opindex m68020-40
10117Generate output for a 68040, without using any of the new instructions.
10118This results in code which can run relatively efficiently on either a
1011968020/68881 or a 68030 or a 68040. The generated code does use the
1012068881 instructions that are emulated on the 68040.
10121
10122@item -m68020-60
10123@opindex m68020-60
10124Generate output for a 68060, without using any of the new instructions.
10125This results in code which can run relatively efficiently on either a
1012668020/68881 or a 68030 or a 68040. The generated code does use the
1012768881 instructions that are emulated on the 68060.
10128
10129@item -msoft-float
10130@opindex msoft-float
10131Generate output containing library calls for floating point.
10132@strong{Warning:} the requisite libraries are not available for all m68k
10133targets. Normally the facilities of the machine's usual C compiler are
10134used, but this can't be done directly in cross-compilation. You must
10135make your own arrangements to provide suitable library functions for
10136cross-compilation. The embedded targets @samp{m68k-*-aout} and
10137@samp{m68k-*-coff} do provide software floating point support.
10138
10139@item -mshort
10140@opindex mshort
10141Consider type @code{int} to be 16 bits wide, like @code{short int}.
10142Additionally, parameters passed on the stack are also aligned to a
1014316-bit boundary even on targets whose API mandates promotion to 32-bit.
10144
10145@item -mnobitfield
10146@opindex mnobitfield
10147Do not use the bit-field instructions. The @option{-m68000}, @option{-mcpu32}
10148and @option{-m5200} options imply @w{@option{-mnobitfield}}.
10149
10150@item -mbitfield
10151@opindex mbitfield
10152Do use the bit-field instructions. The @option{-m68020} option implies
10153@option{-mbitfield}. This is the default if you use a configuration
10154designed for a 68020.
10155
10156@item -mrtd
10157@opindex mrtd
10158Use a different function-calling convention, in which functions
10159that take a fixed number of arguments return with the @code{rtd}
10160instruction, which pops their arguments while returning. This
10161saves one instruction in the caller since there is no need to pop
10162the arguments there.
10163
10164This calling convention is incompatible with the one normally
10165used on Unix, so you cannot use it if you need to call libraries
10166compiled with the Unix compiler.
10167
10168Also, you must provide function prototypes for all functions that
10169take variable numbers of arguments (including @code{printf});
10170otherwise incorrect code will be generated for calls to those
10171functions.
10172
10173In addition, seriously incorrect code will result if you call a
10174function with too many arguments. (Normally, extra arguments are
10175harmlessly ignored.)
10176
10177The @code{rtd} instruction is supported by the 68010, 68020, 68030,
1017868040, 68060 and CPU32 processors, but not by the 68000 or 5200.
10179
10180@item -malign-int
10181@itemx -mno-align-int
10182@opindex malign-int
10183@opindex mno-align-int
10184Control whether GCC aligns @code{int}, @code{long}, @code{long long},
10185@code{float}, @code{double}, and @code{long double} variables on a 32-bit
10186boundary (@option{-malign-int}) or a 16-bit boundary (@option{-mno-align-int}).
10187Aligning variables on 32-bit boundaries produces code that runs somewhat
10188faster on processors with 32-bit busses at the expense of more memory.
10189
10190@strong{Warning:} if you use the @option{-malign-int} switch, GCC will
10191align structures containing the above types differently than
10192most published application binary interface specifications for the m68k.
10193
10194@item -mpcrel
10195@opindex mpcrel
10196Use the pc-relative addressing mode of the 68000 directly, instead of
10197using a global offset table. At present, this option implies @option{-fpic},
10198allowing at most a 16-bit offset for pc-relative addressing. @option{-fPIC} is
10199not presently supported with @option{-mpcrel}, though this could be supported for
1020068020 and higher processors.
10201
10202@item -mno-strict-align
10203@itemx -mstrict-align
10204@opindex mno-strict-align
10205@opindex mstrict-align
10206Do not (do) assume that unaligned memory references will be handled by
10207the system.
10208
10209@item -msep-data
10210Generate code that allows the data segment to be located in a different
10211area of memory from the text segment. This allows for execute in place in
10212an environment without virtual memory management. This option implies
10213@option{-fPIC}.
10214
10215@item -mno-sep-data
10216Generate code that assumes that the data segment follows the text segment.
10217This is the default.
10218
10219@item -mid-shared-library
10220Generate code that supports shared libraries via the library ID method.
10221This allows for execute in place and shared libraries in an environment
10222without virtual memory management. This option implies @option{-fPIC}.
10223
10224@item -mno-id-shared-library
10225Generate code that doesn't assume ID based shared libraries are being used.
10226This is the default.
10227
10228@item -mshared-library-id=n
10229Specified the identification number of the ID based shared library being
10230compiled. Specifying a value of 0 will generate more compact code, specifying
10231other values will force the allocation of that number to the current
10232library but is no more space or time efficient than omitting this option.
10233
10234@end table
10235
10236@node M68hc1x Options
10237@subsection M68hc1x Options
10238@cindex M68hc1x options
10239
10240These are the @samp{-m} options defined for the 68hc11 and 68hc12
10241microcontrollers. The default values for these options depends on
10242which style of microcontroller was selected when the compiler was configured;
10243the defaults for the most common choices are given below.
10244
10245@table @gcctabopt
10246@item -m6811
10247@itemx -m68hc11
10248@opindex m6811
10249@opindex m68hc11
10250Generate output for a 68HC11. This is the default
10251when the compiler is configured for 68HC11-based systems.
10252
10253@item -m6812
10254@itemx -m68hc12
10255@opindex m6812
10256@opindex m68hc12
10257Generate output for a 68HC12. This is the default
10258when the compiler is configured for 68HC12-based systems.
10259
10260@item -m68S12
10261@itemx -m68hcs12
10262@opindex m68S12
10263@opindex m68hcs12
10264Generate output for a 68HCS12.
10265
10266@item -mauto-incdec
10267@opindex mauto-incdec
10268Enable the use of 68HC12 pre and post auto-increment and auto-decrement
10269addressing modes.
10270
10271@item -minmax
10272@itemx -nominmax
10273@opindex minmax
10274@opindex mnominmax
10275Enable the use of 68HC12 min and max instructions.
10276
10277@item -mlong-calls
10278@itemx -mno-long-calls
10279@opindex mlong-calls
10280@opindex mno-long-calls
10281Treat all calls as being far away (near). If calls are assumed to be
10282far away, the compiler will use the @code{call} instruction to
10283call a function and the @code{rtc} instruction for returning.
10284
10285@item -mshort
10286@opindex mshort
10287Consider type @code{int} to be 16 bits wide, like @code{short int}.
10288
10289@item -msoft-reg-count=@var{count}
10290@opindex msoft-reg-count
10291Specify the number of pseudo-soft registers which are used for the
10292code generation. The maximum number is 32. Using more pseudo-soft
10293register may or may not result in better code depending on the program.
10294The default is 4 for 68HC11 and 2 for 68HC12.
10295
10296@end table
10297
10298@node MCore Options
10299@subsection MCore Options
10300@cindex MCore options
10301
10302These are the @samp{-m} options defined for the Motorola M*Core
10303processors.
10304
10305@table @gcctabopt
10306
10307@item -mhardlit
10308@itemx -mno-hardlit
10309@opindex mhardlit
10310@opindex mno-hardlit
10311Inline constants into the code stream if it can be done in two
10312instructions or less.
10313
10314@item -mdiv
10315@itemx -mno-div
10316@opindex mdiv
10317@opindex mno-div
10318Use the divide instruction. (Enabled by default).
10319
10320@item -mrelax-immediate
10321@itemx -mno-relax-immediate
10322@opindex mrelax-immediate
10323@opindex mno-relax-immediate
10324Allow arbitrary sized immediates in bit operations.
10325
10326@item -mwide-bitfields
10327@itemx -mno-wide-bitfields
10328@opindex mwide-bitfields
10329@opindex mno-wide-bitfields
10330Always treat bit-fields as int-sized.
10331
10332@item -m4byte-functions
10333@itemx -mno-4byte-functions
10334@opindex m4byte-functions
10335@opindex mno-4byte-functions
10336Force all functions to be aligned to a four byte boundary.
10337
10338@item -mcallgraph-data
10339@itemx -mno-callgraph-data
10340@opindex mcallgraph-data
10341@opindex mno-callgraph-data
10342Emit callgraph information.
10343
10344@item -mslow-bytes
10345@itemx -mno-slow-bytes
10346@opindex mslow-bytes
10347@opindex mno-slow-bytes
10348Prefer word access when reading byte quantities.
10349
10350@item -mlittle-endian
10351@itemx -mbig-endian
10352@opindex mlittle-endian
10353@opindex mbig-endian
10354Generate code for a little endian target.
10355
10356@item -m210
10357@itemx -m340
10358@opindex m210
10359@opindex m340
10360Generate code for the 210 processor.
10361@end table
10362
10363@node MIPS Options
10364@subsection MIPS Options
10365@cindex MIPS options
10366
10367@table @gcctabopt
10368
10369@item -EB
10370@opindex EB
10371Generate big-endian code.
10372
10373@item -EL
10374@opindex EL
10375Generate little-endian code. This is the default for @samp{mips*el-*-*}
10376configurations.
10377
10378@item -march=@var{arch}
10379@opindex march
10380Generate code that will run on @var{arch}, which can be the name of a
10381generic MIPS ISA, or the name of a particular processor.
10382The ISA names are:
10383@samp{mips1}, @samp{mips2}, @samp{mips3}, @samp{mips4},
10384@samp{mips32}, @samp{mips32r2}, and @samp{mips64}.
10385The processor names are:
10386@samp{4kc}, @samp{4km}, @samp{4kp},
10387@samp{5kc}, @samp{5kf},
10388@samp{20kc},
10389@samp{24k}, @samp{24kc}, @samp{24kf}, @samp{24kx},
10390@samp{m4k},
10391@samp{orion},
10392@samp{r2000}, @samp{r3000}, @samp{r3900}, @samp{r4000}, @samp{r4400},
10393@samp{r4600}, @samp{r4650}, @samp{r6000}, @samp{r8000},
10394@samp{rm7000}, @samp{rm9000},
10395@samp{sb1},
10396@samp{sr71000},
10397@samp{vr4100}, @samp{vr4111}, @samp{vr4120}, @samp{vr4130}, @samp{vr4300},
10398@samp{vr5000}, @samp{vr5400} and @samp{vr5500}.
10399The special value @samp{from-abi} selects the
10400most compatible architecture for the selected ABI (that is,
10401@samp{mips1} for 32-bit ABIs and @samp{mips3} for 64-bit ABIs)@.
10402
10403In processor names, a final @samp{000} can be abbreviated as @samp{k}
10404(for example, @samp{-march=r2k}). Prefixes are optional, and
10405@samp{vr} may be written @samp{r}.
10406
10407GCC defines two macros based on the value of this option. The first
10408is @samp{_MIPS_ARCH}, which gives the name of target architecture, as
10409a string. The second has the form @samp{_MIPS_ARCH_@var{foo}},
10410where @var{foo} is the capitalized value of @samp{_MIPS_ARCH}@.
10411For example, @samp{-march=r2000} will set @samp{_MIPS_ARCH}
10412to @samp{"r2000"} and define the macro @samp{_MIPS_ARCH_R2000}.
10413
10414Note that the @samp{_MIPS_ARCH} macro uses the processor names given
10415above. In other words, it will have the full prefix and will not
10416abbreviate @samp{000} as @samp{k}. In the case of @samp{from-abi},
10417the macro names the resolved architecture (either @samp{"mips1"} or
10418@samp{"mips3"}). It names the default architecture when no
10419@option{-march} option is given.
10420
10421@item -mtune=@var{arch}
10422@opindex mtune
10423Optimize for @var{arch}. Among other things, this option controls
10424the way instructions are scheduled, and the perceived cost of arithmetic
10425operations. The list of @var{arch} values is the same as for
10426@option{-march}.
10427
10428When this option is not used, GCC will optimize for the processor
10429specified by @option{-march}. By using @option{-march} and
10430@option{-mtune} together, it is possible to generate code that will
10431run on a family of processors, but optimize the code for one
10432particular member of that family.
10433
10434@samp{-mtune} defines the macros @samp{_MIPS_TUNE} and
10435@samp{_MIPS_TUNE_@var{foo}}, which work in the same way as the
10436@samp{-march} ones described above.
10437
10438@item -mips1
10439@opindex mips1
10440Equivalent to @samp{-march=mips1}.
10441
10442@item -mips2
10443@opindex mips2
10444Equivalent to @samp{-march=mips2}.
10445
10446@item -mips3
10447@opindex mips3
10448Equivalent to @samp{-march=mips3}.
10449
10450@item -mips4
10451@opindex mips4
10452Equivalent to @samp{-march=mips4}.
10453
10454@item -mips32
10455@opindex mips32
10456Equivalent to @samp{-march=mips32}.
10457
10458@item -mips32r2
10459@opindex mips32r2
10460Equivalent to @samp{-march=mips32r2}.
10461
10462@item -mips64
10463@opindex mips64
10464Equivalent to @samp{-march=mips64}.
10465
10466@item -mips16
10467@itemx -mno-mips16
10468@opindex mips16
10469@opindex mno-mips16
10470Generate (do not generate) MIPS16 code. If GCC is targetting a
10471MIPS32 or MIPS64 architecture, it will make use of the MIPS16e ASE@.
10472
10473@item -mabi=32
10474@itemx -mabi=o64
10475@itemx -mabi=n32
10476@itemx -mabi=64
10477@itemx -mabi=eabi
10478@opindex mabi=32
10479@opindex mabi=o64
10480@opindex mabi=n32
10481@opindex mabi=64
10482@opindex mabi=eabi
10483Generate code for the given ABI@.
10484
10485Note that the EABI has a 32-bit and a 64-bit variant. GCC normally
10486generates 64-bit code when you select a 64-bit architecture, but you
10487can use @option{-mgp32} to get 32-bit code instead.
10488
10489For information about the O64 ABI, see
10490@w{@uref{http://gcc.gnu.org/projects/mipso64-abi.html}}.
10491
10492@item -mabicalls
10493@itemx -mno-abicalls
10494@opindex mabicalls
10495@opindex mno-abicalls
10496Generate (do not generate) code that is suitable for SVR4-style
10497dynamic objects. @option{-mabicalls} is the default for SVR4-based
10498systems.
10499
10500@item -mshared
10501@itemx -mno-shared
10502Generate (do not generate) code that is fully position-independent,
10503and that can therefore be linked into shared libraries. This option
10504only affects @option{-mabicalls}.
10505
10506All @option{-mabicalls} code has traditionally been position-independent,
10507regardless of options like @option{-fPIC} and @option{-fpic}. However,
10508as an extension, the GNU toolchain allows executables to use absolute
10509accesses for locally-binding symbols. It can also use shorter GP
10510initialization sequences and generate direct calls to locally-defined
10511functions. This mode is selected by @option{-mno-shared}.
10512
10513@option{-mno-shared} depends on binutils 2.16 or higher and generates
10514objects that can only be linked by the GNU linker. However, the option
10515does not affect the ABI of the final executable; it only affects the ABI
10516of relocatable objects. Using @option{-mno-shared} will generally make
10517executables both smaller and quicker.
10518
10519@option{-mshared} is the default.
10520
10521@item -mxgot
10522@itemx -mno-xgot
10523@opindex mxgot
10524@opindex mno-xgot
10525Lift (do not lift) the usual restrictions on the size of the global
10526offset table.
10527
10528GCC normally uses a single instruction to load values from the GOT@.
10529While this is relatively efficient, it will only work if the GOT
10530is smaller than about 64k. Anything larger will cause the linker
10531to report an error such as:
10532
10533@cindex relocation truncated to fit (MIPS)
10534@smallexample
10535relocation truncated to fit: R_MIPS_GOT16 foobar
10536@end smallexample
10537
10538If this happens, you should recompile your code with @option{-mxgot}.
10539It should then work with very large GOTs, although it will also be
10540less efficient, since it will take three instructions to fetch the
10541value of a global symbol.
10542
10543Note that some linkers can create multiple GOTs. If you have such a
10544linker, you should only need to use @option{-mxgot} when a single object
10545file accesses more than 64k's worth of GOT entries. Very few do.
10546
10547These options have no effect unless GCC is generating position
10548independent code.
10549
10550@item -mgp32
10551@opindex mgp32
10552Assume that general-purpose registers are 32 bits wide.
10553
10554@item -mgp64
10555@opindex mgp64
10556Assume that general-purpose registers are 64 bits wide.
10557
10558@item -mfp32
10559@opindex mfp32
10560Assume that floating-point registers are 32 bits wide.
10561
10562@item -mfp64
10563@opindex mfp64
10564Assume that floating-point registers are 64 bits wide.
10565
10566@item -mhard-float
10567@opindex mhard-float
10568Use floating-point coprocessor instructions.
10569
10570@item -msoft-float
10571@opindex msoft-float
10572Do not use floating-point coprocessor instructions. Implement
10573floating-point calculations using library calls instead.
10574
10575@item -msingle-float
10576@opindex msingle-float
10577Assume that the floating-point coprocessor only supports single-precision
10578operations.
10579
10580@itemx -mdouble-float
10581@opindex mdouble-float
10582Assume that the floating-point coprocessor supports double-precision
10583operations. This is the default.
10584
10585@itemx -mdsp
10586@itemx -mno-dsp
10587@opindex mdsp
10588@opindex mno-dsp
10589Use (do not use) the MIPS DSP ASE. @xref{MIPS DSP Built-in Functions}.
10590
10591@itemx -mpaired-single
10592@itemx -mno-paired-single
10593@opindex mpaired-single
10594@opindex mno-paired-single
10595Use (do not use) paired-single floating-point instructions.
10596@xref{MIPS Paired-Single Support}. This option can only be used
10597when generating 64-bit code and requires hardware floating-point
10598support to be enabled.
10599
10600@itemx -mips3d
10601@itemx -mno-mips3d
10602@opindex mips3d
10603@opindex mno-mips3d
10604Use (do not use) the MIPS-3D ASE@. @xref{MIPS-3D Built-in Functions}.
10605The option @option{-mips3d} implies @option{-mpaired-single}.
10606
10607@item -mlong64
10608@opindex mlong64
10609Force @code{long} types to be 64 bits wide. See @option{-mlong32} for
10610an explanation of the default and the way that the pointer size is
10611determined.
10612
10613@item -mlong32
10614@opindex mlong32
10615Force @code{long}, @code{int}, and pointer types to be 32 bits wide.
10616
10617The default size of @code{int}s, @code{long}s and pointers depends on
10618the ABI@. All the supported ABIs use 32-bit @code{int}s. The n64 ABI
10619uses 64-bit @code{long}s, as does the 64-bit EABI; the others use
1062032-bit @code{long}s. Pointers are the same size as @code{long}s,
10621or the same size as integer registers, whichever is smaller.
10622
10623@item -msym32
10624@itemx -mno-sym32
10625@opindex msym32
10626@opindex mno-sym32
10627Assume (do not assume) that all symbols have 32-bit values, regardless
10628of the selected ABI@. This option is useful in combination with
10629@option{-mabi=64} and @option{-mno-abicalls} because it allows GCC
10630to generate shorter and faster references to symbolic addresses.
10631
10632@item -G @var{num}
10633@opindex G
10634@cindex smaller data references (MIPS)
10635@cindex gp-relative references (MIPS)
10636Put global and static items less than or equal to @var{num} bytes into
10637the small data or bss section instead of the normal data or bss section.
10638This allows the data to be accessed using a single instruction.
10639
10640All modules should be compiled with the same @option{-G @var{num}}
10641value.
10642
10643@item -membedded-data
10644@itemx -mno-embedded-data
10645@opindex membedded-data
10646@opindex mno-embedded-data
10647Allocate variables to the read-only data section first if possible, then
10648next in the small data section if possible, otherwise in data. This gives
10649slightly slower code than the default, but reduces the amount of RAM required
10650when executing, and thus may be preferred for some embedded systems.
10651
10652@item -muninit-const-in-rodata
10653@itemx -mno-uninit-const-in-rodata
10654@opindex muninit-const-in-rodata
10655@opindex mno-uninit-const-in-rodata
10656Put uninitialized @code{const} variables in the read-only data section.
10657This option is only meaningful in conjunction with @option{-membedded-data}.
10658
10659@item -msplit-addresses
10660@itemx -mno-split-addresses
10661@opindex msplit-addresses
10662@opindex mno-split-addresses
10663Enable (disable) use of the @code{%hi()} and @code{%lo()} assembler
10664relocation operators. This option has been superseded by
10665@option{-mexplicit-relocs} but is retained for backwards compatibility.
10666
10667@item -mexplicit-relocs
10668@itemx -mno-explicit-relocs
10669@opindex mexplicit-relocs
10670@opindex mno-explicit-relocs
10671Use (do not use) assembler relocation operators when dealing with symbolic
10672addresses. The alternative, selected by @option{-mno-explicit-relocs},
10673is to use assembler macros instead.
10674
10675@option{-mexplicit-relocs} is the default if GCC was configured
10676to use an assembler that supports relocation operators.
10677
10678@item -mcheck-zero-division
10679@itemx -mno-check-zero-division
10680@opindex mcheck-zero-division
10681@opindex mno-check-zero-division
10682Trap (do not trap) on integer division by zero. The default is
10683@option{-mcheck-zero-division}.
10684
10685@item -mdivide-traps
10686@itemx -mdivide-breaks
10687@opindex mdivide-traps
10688@opindex mdivide-breaks
10689MIPS systems check for division by zero by generating either a
10690conditional trap or a break instruction. Using traps results in
10691smaller code, but is only supported on MIPS II and later. Also, some
10692versions of the Linux kernel have a bug that prevents trap from
10693generating the proper signal (@code{SIGFPE}). Use @option{-mdivide-traps} to
10694allow conditional traps on architectures that support them and
10695@option{-mdivide-breaks} to force the use of breaks.
10696
10697The default is usually @option{-mdivide-traps}, but this can be
10698overridden at configure time using @option{--with-divide=breaks}.
10699Divide-by-zero checks can be completely disabled using
10700@option{-mno-check-zero-division}.
10701
10702@item -mmemcpy
10703@itemx -mno-memcpy
10704@opindex mmemcpy
10705@opindex mno-memcpy
10706Force (do not force) the use of @code{memcpy()} for non-trivial block
10707moves. The default is @option{-mno-memcpy}, which allows GCC to inline
10708most constant-sized copies.
10709
10710@item -mlong-calls
10711@itemx -mno-long-calls
10712@opindex mlong-calls
10713@opindex mno-long-calls
10714Disable (do not disable) use of the @code{jal} instruction. Calling
10715functions using @code{jal} is more efficient but requires the caller
10716and callee to be in the same 256 megabyte segment.
10717
10718This option has no effect on abicalls code. The default is
10719@option{-mno-long-calls}.
10720
10721@item -mmad
10722@itemx -mno-mad
10723@opindex mmad
10724@opindex mno-mad
10725Enable (disable) use of the @code{mad}, @code{madu} and @code{mul}
10726instructions, as provided by the R4650 ISA@.
10727
10728@item -mfused-madd
10729@itemx -mno-fused-madd
10730@opindex mfused-madd
10731@opindex mno-fused-madd
10732Enable (disable) use of the floating point multiply-accumulate
10733instructions, when they are available. The default is
10734@option{-mfused-madd}.
10735
10736When multiply-accumulate instructions are used, the intermediate
10737product is calculated to infinite precision and is not subject to
10738the FCSR Flush to Zero bit. This may be undesirable in some
10739circumstances.
10740
10741@item -nocpp
10742@opindex nocpp
10743Tell the MIPS assembler to not run its preprocessor over user
10744assembler files (with a @samp{.s} suffix) when assembling them.
10745
10746@item -mfix-r4000
10747@itemx -mno-fix-r4000
10748@opindex mfix-r4000
10749@opindex mno-fix-r4000
10750Work around certain R4000 CPU errata:
10751@itemize @minus
10752@item
10753A double-word or a variable shift may give an incorrect result if executed
10754immediately after starting an integer division.
10755@item
10756A double-word or a variable shift may give an incorrect result if executed
10757while an integer multiplication is in progress.
10758@item
10759An integer division may give an incorrect result if started in a delay slot
10760of a taken branch or a jump.
10761@end itemize
10762
10763@item -mfix-r4400
10764@itemx -mno-fix-r4400
10765@opindex mfix-r4400
10766@opindex mno-fix-r4400
10767Work around certain R4400 CPU errata:
10768@itemize @minus
10769@item
10770A double-word or a variable shift may give an incorrect result if executed
10771immediately after starting an integer division.
10772@end itemize
10773
10774@item -mfix-vr4120
10775@itemx -mno-fix-vr4120
10776@opindex mfix-vr4120
10777Work around certain VR4120 errata:
10778@itemize @minus
10779@item
10780@code{dmultu} does not always produce the correct result.
10781@item
10782@code{div} and @code{ddiv} do not always produce the correct result if one
10783of the operands is negative.
10784@end itemize
10785The workarounds for the division errata rely on special functions in
10786@file{libgcc.a}. At present, these functions are only provided by
10787the @code{mips64vr*-elf} configurations.
10788
10789Other VR4120 errata require a nop to be inserted between certain pairs of
10790instructions. These errata are handled by the assembler, not by GCC itself.
10791
10792@item -mfix-vr4130
10793@opindex mfix-vr4130
10794Work around the VR4130 @code{mflo}/@code{mfhi} errata. The
10795workarounds are implemented by the assembler rather than by GCC,
10796although GCC will avoid using @code{mflo} and @code{mfhi} if the
10797VR4130 @code{macc}, @code{macchi}, @code{dmacc} and @code{dmacchi}
10798instructions are available instead.
10799
10800@item -mfix-sb1
10801@itemx -mno-fix-sb1
10802@opindex mfix-sb1
10803Work around certain SB-1 CPU core errata.
10804(This flag currently works around the SB-1 revision 2
10805``F1'' and ``F2'' floating point errata.)
10806
10807@item -mflush-func=@var{func}
10808@itemx -mno-flush-func
10809@opindex mflush-func
10810Specifies the function to call to flush the I and D caches, or to not
10811call any such function. If called, the function must take the same
10812arguments as the common @code{_flush_func()}, that is, the address of the
10813memory range for which the cache is being flushed, the size of the
10814memory range, and the number 3 (to flush both caches). The default
10815depends on the target GCC was configured for, but commonly is either
10816@samp{_flush_func} or @samp{__cpu_flush}.
10817
10818@item -mbranch-likely
10819@itemx -mno-branch-likely
10820@opindex mbranch-likely
10821@opindex mno-branch-likely
10822Enable or disable use of Branch Likely instructions, regardless of the
10823default for the selected architecture. By default, Branch Likely
10824instructions may be generated if they are supported by the selected
10825architecture. An exception is for the MIPS32 and MIPS64 architectures
10826and processors which implement those architectures; for those, Branch
10827Likely instructions will not be generated by default because the MIPS32
10828and MIPS64 architectures specifically deprecate their use.
10829
10830@item -mfp-exceptions
10831@itemx -mno-fp-exceptions
10832@opindex mfp-exceptions
10833Specifies whether FP exceptions are enabled. This affects how we schedule
10834FP instructions for some processors. The default is that FP exceptions are
10835enabled.
10836
10837For instance, on the SB-1, if FP exceptions are disabled, and we are emitting
1083864-bit code, then we can use both FP pipes. Otherwise, we can only use one
10839FP pipe.
10840
10841@item -mvr4130-align
10842@itemx -mno-vr4130-align
10843@opindex mvr4130-align
10844The VR4130 pipeline is two-way superscalar, but can only issue two
10845instructions together if the first one is 8-byte aligned. When this
10846option is enabled, GCC will align pairs of instructions that it
10847thinks should execute in parallel.
10848
10849This option only has an effect when optimizing for the VR4130.
10850It normally makes code faster, but at the expense of making it bigger.
10851It is enabled by default at optimization level @option{-O3}.
10852@end table
10853
10854@node MMIX Options
10855@subsection MMIX Options
10856@cindex MMIX Options
10857
10858These options are defined for the MMIX:
10859
10860@table @gcctabopt
10861@item -mlibfuncs
10862@itemx -mno-libfuncs
10863@opindex mlibfuncs
10864@opindex mno-libfuncs
10865Specify that intrinsic library functions are being compiled, passing all
10866values in registers, no matter the size.
10867
10868@item -mepsilon
10869@itemx -mno-epsilon
10870@opindex mepsilon
10871@opindex mno-epsilon
10872Generate floating-point comparison instructions that compare with respect
10873to the @code{rE} epsilon register.
10874
10875@item -mabi=mmixware
10876@itemx -mabi=gnu
10877@opindex mabi-mmixware
10878@opindex mabi=gnu
10879Generate code that passes function parameters and return values that (in
10880the called function) are seen as registers @code{$0} and up, as opposed to
10881the GNU ABI which uses global registers @code{$231} and up.
10882
10883@item -mzero-extend
10884@itemx -mno-zero-extend
10885@opindex mzero-extend
10886@opindex mno-zero-extend
10887When reading data from memory in sizes shorter than 64 bits, use (do not
10888use) zero-extending load instructions by default, rather than
10889sign-extending ones.
10890
10891@item -mknuthdiv
10892@itemx -mno-knuthdiv
10893@opindex mknuthdiv
10894@opindex mno-knuthdiv
10895Make the result of a division yielding a remainder have the same sign as
10896the divisor. With the default, @option{-mno-knuthdiv}, the sign of the
10897remainder follows the sign of the dividend. Both methods are
10898arithmetically valid, the latter being almost exclusively used.
10899
10900@item -mtoplevel-symbols
10901@itemx -mno-toplevel-symbols
10902@opindex mtoplevel-symbols
10903@opindex mno-toplevel-symbols
10904Prepend (do not prepend) a @samp{:} to all global symbols, so the assembly
10905code can be used with the @code{PREFIX} assembly directive.
10906
10907@item -melf
10908@opindex melf
10909Generate an executable in the ELF format, rather than the default
10910@samp{mmo} format used by the @command{mmix} simulator.
10911
10912@item -mbranch-predict
10913@itemx -mno-branch-predict
10914@opindex mbranch-predict
10915@opindex mno-branch-predict
10916Use (do not use) the probable-branch instructions, when static branch
10917prediction indicates a probable branch.
10918
10919@item -mbase-addresses
10920@itemx -mno-base-addresses
10921@opindex mbase-addresses
10922@opindex mno-base-addresses
10923Generate (do not generate) code that uses @emph{base addresses}. Using a
10924base address automatically generates a request (handled by the assembler
10925and the linker) for a constant to be set up in a global register. The
10926register is used for one or more base address requests within the range 0
10927to 255 from the value held in the register. The generally leads to short
10928and fast code, but the number of different data items that can be
10929addressed is limited. This means that a program that uses lots of static
10930data may require @option{-mno-base-addresses}.
10931
10932@item -msingle-exit
10933@itemx -mno-single-exit
10934@opindex msingle-exit
10935@opindex mno-single-exit
10936Force (do not force) generated code to have a single exit point in each
10937function.
10938@end table
10939
10940@node MN10300 Options
10941@subsection MN10300 Options
10942@cindex MN10300 options
10943
10944These @option{-m} options are defined for Matsushita MN10300 architectures:
10945
10946@table @gcctabopt
10947@item -mmult-bug
10948@opindex mmult-bug
10949Generate code to avoid bugs in the multiply instructions for the MN10300
10950processors. This is the default.
10951
10952@item -mno-mult-bug
10953@opindex mno-mult-bug
10954Do not generate code to avoid bugs in the multiply instructions for the
10955MN10300 processors.
10956
10957@item -mam33
10958@opindex mam33
10959Generate code which uses features specific to the AM33 processor.
10960
10961@item -mno-am33
10962@opindex mno-am33
10963Do not generate code which uses features specific to the AM33 processor. This
10964is the default.
10965
10966@item -mreturn-pointer-on-d0
10967@opindex mreturn-pointer-on-d0
10968When generating a function which returns a pointer, return the pointer
10969in both @code{a0} and @code{d0}. Otherwise, the pointer is returned
10970only in a0, and attempts to call such functions without a prototype
10971would result in errors. Note that this option is on by default; use
10972@option{-mno-return-pointer-on-d0} to disable it.
10973
10974@item -mno-crt0
10975@opindex mno-crt0
10976Do not link in the C run-time initialization object file.
10977
10978@item -mrelax
10979@opindex mrelax
10980Indicate to the linker that it should perform a relaxation optimization pass
10981to shorten branches, calls and absolute memory addresses. This option only
10982has an effect when used on the command line for the final link step.
10983
10984This option makes symbolic debugging impossible.
10985@end table
10986
10987@node MT Options
10988@subsection MT Options
10989@cindex MT options
10990
10991These @option{-m} options are defined for Morpho MT architectures:
10992
10993@table @gcctabopt
10994
10995@item -march=@var{cpu-type}
10996@opindex march
10997Generate code that will run on @var{cpu-type}, which is the name of a system
10998representing a certain processor type. Possible values for
10999@var{cpu-type} are @samp{ms1-64-001}, @samp{ms1-16-002},
11000@samp{ms1-16-003} and @samp{ms2}.
11001
11002When this option is not used, the default is @option{-march=ms1-16-002}.
11003
11004@item -mbacc
11005@opindex mbacc
11006Use byte loads and stores when generating code.
11007
11008@item -mno-bacc
11009@opindex mno-bacc
11010Do not use byte loads and stores when generating code.
11011
11012@item -msim
11013@opindex msim
11014Use simulator runtime
11015
11016@item -mno-crt0
11017@opindex mno-crt0
11018Do not link in the C run-time initialization object file
11019@file{crti.o}. Other run-time initialization and termination files
11020such as @file{startup.o} and @file{exit.o} are still included on the
11021linker command line.
11022
11023@end table
11024
11025@node PDP-11 Options
11026@subsection PDP-11 Options
11027@cindex PDP-11 Options
11028
11029These options are defined for the PDP-11:
11030
11031@table @gcctabopt
11032@item -mfpu
11033@opindex mfpu
11034Use hardware FPP floating point. This is the default. (FIS floating
11035point on the PDP-11/40 is not supported.)
11036
11037@item -msoft-float
11038@opindex msoft-float
11039Do not use hardware floating point.
11040
11041@item -mac0
11042@opindex mac0
11043Return floating-point results in ac0 (fr0 in Unix assembler syntax).
11044
11045@item -mno-ac0
11046@opindex mno-ac0
11047Return floating-point results in memory. This is the default.
11048
11049@item -m40
11050@opindex m40
11051Generate code for a PDP-11/40.
11052
11053@item -m45
11054@opindex m45
11055Generate code for a PDP-11/45. This is the default.
11056
11057@item -m10
11058@opindex m10
11059Generate code for a PDP-11/10.
11060
11061@item -mbcopy-builtin
11062@opindex bcopy-builtin
11063Use inline @code{movmemhi} patterns for copying memory. This is the
11064default.
11065
11066@item -mbcopy
11067@opindex mbcopy
11068Do not use inline @code{movmemhi} patterns for copying memory.
11069
11070@item -mint16
11071@itemx -mno-int32
11072@opindex mint16
11073@opindex mno-int32
11074Use 16-bit @code{int}. This is the default.
11075
11076@item -mint32
11077@itemx -mno-int16
11078@opindex mint32
11079@opindex mno-int16
11080Use 32-bit @code{int}.
11081
11082@item -mfloat64
11083@itemx -mno-float32
11084@opindex mfloat64
11085@opindex mno-float32
11086Use 64-bit @code{float}. This is the default.
11087
11088@item -mfloat32
11089@itemx -mno-float64
11090@opindex mfloat32
11091@opindex mno-float64
11092Use 32-bit @code{float}.
11093
11094@item -mabshi
11095@opindex mabshi
11096Use @code{abshi2} pattern. This is the default.
11097
11098@item -mno-abshi
11099@opindex mno-abshi
11100Do not use @code{abshi2} pattern.
11101
11102@item -mbranch-expensive
11103@opindex mbranch-expensive
11104Pretend that branches are expensive. This is for experimenting with
11105code generation only.
11106
11107@item -mbranch-cheap
11108@opindex mbranch-cheap
11109Do not pretend that branches are expensive. This is the default.
11110
11111@item -msplit
11112@opindex msplit
11113Generate code for a system with split I&D@.
11114
11115@item -mno-split
11116@opindex mno-split
11117Generate code for a system without split I&D@. This is the default.
11118
11119@item -munix-asm
11120@opindex munix-asm
11121Use Unix assembler syntax. This is the default when configured for
11122@samp{pdp11-*-bsd}.
11123
11124@item -mdec-asm
11125@opindex mdec-asm
11126Use DEC assembler syntax. This is the default when configured for any
11127PDP-11 target other than @samp{pdp11-*-bsd}.
11128@end table
11129
11130@node PowerPC Options
11131@subsection PowerPC Options
11132@cindex PowerPC options
11133
11134These are listed under @xref{RS/6000 and PowerPC Options}.
11135
11136@node RS/6000 and PowerPC Options
11137@subsection IBM RS/6000 and PowerPC Options
11138@cindex RS/6000 and PowerPC Options
11139@cindex IBM RS/6000 and PowerPC Options
11140
11141These @samp{-m} options are defined for the IBM RS/6000 and PowerPC:
11142@table @gcctabopt
11143@item -mpower
11144@itemx -mno-power
11145@itemx -mpower2
11146@itemx -mno-power2
11147@itemx -mpowerpc
11148@itemx -mno-powerpc
11149@itemx -mpowerpc-gpopt
11150@itemx -mno-powerpc-gpopt
11151@itemx -mpowerpc-gfxopt
11152@itemx -mno-powerpc-gfxopt
11153@itemx -mpowerpc64
11154@itemx -mno-powerpc64
11155@itemx -mmfcrf
11156@itemx -mno-mfcrf
11157@itemx -mpopcntb
11158@itemx -mno-popcntb
11159@itemx -mfprnd
11160@itemx -mno-fprnd
11161@opindex mpower
11162@opindex mno-power
11163@opindex mpower2
11164@opindex mno-power2
11165@opindex mpowerpc
11166@opindex mno-powerpc
11167@opindex mpowerpc-gpopt
11168@opindex mno-powerpc-gpopt
11169@opindex mpowerpc-gfxopt
11170@opindex mno-powerpc-gfxopt
11171@opindex mpowerpc64
11172@opindex mno-powerpc64
11173@opindex mmfcrf
11174@opindex mno-mfcrf
11175@opindex mpopcntb
11176@opindex mno-popcntb
11177@opindex mfprnd
11178@opindex mno-fprnd
11179GCC supports two related instruction set architectures for the
11180RS/6000 and PowerPC@. The @dfn{POWER} instruction set are those
11181instructions supported by the @samp{rios} chip set used in the original
11182RS/6000 systems and the @dfn{PowerPC} instruction set is the
11183architecture of the Freescale MPC5xx, MPC6xx, MPC8xx microprocessors, and
11184the IBM 4xx, 6xx, and follow-on microprocessors.
11185
11186Neither architecture is a subset of the other. However there is a
11187large common subset of instructions supported by both. An MQ
11188register is included in processors supporting the POWER architecture.
11189
11190You use these options to specify which instructions are available on the
11191processor you are using. The default value of these options is
11192determined when configuring GCC@. Specifying the
11193@option{-mcpu=@var{cpu_type}} overrides the specification of these
11194options. We recommend you use the @option{-mcpu=@var{cpu_type}} option
11195rather than the options listed above.
11196
11197The @option{-mpower} option allows GCC to generate instructions that
11198are found only in the POWER architecture and to use the MQ register.
11199Specifying @option{-mpower2} implies @option{-power} and also allows GCC
11200to generate instructions that are present in the POWER2 architecture but
11201not the original POWER architecture.
11202
11203The @option{-mpowerpc} option allows GCC to generate instructions that
11204are found only in the 32-bit subset of the PowerPC architecture.
11205Specifying @option{-mpowerpc-gpopt} implies @option{-mpowerpc} and also allows
11206GCC to use the optional PowerPC architecture instructions in the
11207General Purpose group, including floating-point square root. Specifying
11208@option{-mpowerpc-gfxopt} implies @option{-mpowerpc} and also allows GCC to
11209use the optional PowerPC architecture instructions in the Graphics
11210group, including floating-point select.
11211
11212The @option{-mmfcrf} option allows GCC to generate the move from
11213condition register field instruction implemented on the POWER4
11214processor and other processors that support the PowerPC V2.01
11215architecture.
11216The @option{-mpopcntb} option allows GCC to generate the popcount and
11217double precision FP reciprocal estimate instruction implemented on the
11218POWER5 processor and other processors that support the PowerPC V2.02
11219architecture.
11220The @option{-mfprnd} option allows GCC to generate the FP round to
11221integer instructions implemented on the POWER5+ processor and other
11222processors that support the PowerPC V2.03 architecture.
11223
11224The @option{-mpowerpc64} option allows GCC to generate the additional
1122564-bit instructions that are found in the full PowerPC64 architecture
11226and to treat GPRs as 64-bit, doubleword quantities. GCC defaults to
11227@option{-mno-powerpc64}.
11228
11229If you specify both @option{-mno-power} and @option{-mno-powerpc}, GCC
11230will use only the instructions in the common subset of both
11231architectures plus some special AIX common-mode calls, and will not use
11232the MQ register. Specifying both @option{-mpower} and @option{-mpowerpc}
11233permits GCC to use any instruction from either architecture and to
11234allow use of the MQ register; specify this for the Motorola MPC601.
11235
11236@item -mnew-mnemonics
11237@itemx -mold-mnemonics
11238@opindex mnew-mnemonics
11239@opindex mold-mnemonics
11240Select which mnemonics to use in the generated assembler code. With
11241@option{-mnew-mnemonics}, GCC uses the assembler mnemonics defined for
11242the PowerPC architecture. With @option{-mold-mnemonics} it uses the
11243assembler mnemonics defined for the POWER architecture. Instructions
11244defined in only one architecture have only one mnemonic; GCC uses that
11245mnemonic irrespective of which of these options is specified.
11246
11247GCC defaults to the mnemonics appropriate for the architecture in
11248use. Specifying @option{-mcpu=@var{cpu_type}} sometimes overrides the
11249value of these option. Unless you are building a cross-compiler, you
11250should normally not specify either @option{-mnew-mnemonics} or
11251@option{-mold-mnemonics}, but should instead accept the default.
11252
11253@item -mcpu=@var{cpu_type}
11254@opindex mcpu
11255Set architecture type, register usage, choice of mnemonics, and
11256instruction scheduling parameters for machine type @var{cpu_type}.
11257Supported values for @var{cpu_type} are @samp{401}, @samp{403},
11258@samp{405}, @samp{405fp}, @samp{440}, @samp{440fp}, @samp{505},
11259@samp{601}, @samp{602}, @samp{603}, @samp{603e}, @samp{604},
11260@samp{604e}, @samp{620}, @samp{630}, @samp{740}, @samp{7400},
11261@samp{7450}, @samp{750}, @samp{801}, @samp{821}, @samp{823},
11262@samp{860}, @samp{970}, @samp{8540}, @samp{ec603e}, @samp{G3},
11263@samp{G4}, @samp{G5}, @samp{power}, @samp{power2}, @samp{power3},
11264@samp{power4}, @samp{power5}, @samp{power5+}, @samp{power6},
11265@samp{common}, @samp{powerpc}, @samp{powerpc64},
11266@samp{rios}, @samp{rios1}, @samp{rios2}, @samp{rsc}, and @samp{rs64}.
11267
11268@option{-mcpu=common} selects a completely generic processor. Code
11269generated under this option will run on any POWER or PowerPC processor.
11270GCC will use only the instructions in the common subset of both
11271architectures, and will not use the MQ register. GCC assumes a generic
11272processor model for scheduling purposes.
11273
11274@option{-mcpu=power}, @option{-mcpu=power2}, @option{-mcpu=powerpc}, and
11275@option{-mcpu=powerpc64} specify generic POWER, POWER2, pure 32-bit
11276PowerPC (i.e., not MPC601), and 64-bit PowerPC architecture machine
11277types, with an appropriate, generic processor model assumed for
11278scheduling purposes.
11279
11280The other options specify a specific processor. Code generated under
11281those options will run best on that processor, and may not run at all on
11282others.
11283
11284The @option{-mcpu} options automatically enable or disable the
11285following options: @option{-maltivec}, @option{-mfprnd},
11286@option{-mhard-float}, @option{-mmfcrf}, @option{-mmultiple},
11287@option{-mnew-mnemonics}, @option{-mpopcntb}, @option{-mpower},
11288@option{-mpower2}, @option{-mpowerpc64}, @option{-mpowerpc-gpopt},
11289@option{-mpowerpc-gfxopt}, @option{-mstring}, @option{-mmulhw}, @option{-mdlmzb}.
11290The particular options
11291set for any particular CPU will vary between compiler versions,
11292depending on what setting seems to produce optimal code for that CPU;
11293it doesn't necessarily reflect the actual hardware's capabilities. If
11294you wish to set an individual option to a particular value, you may
11295specify it after the @option{-mcpu} option, like @samp{-mcpu=970
11296-mno-altivec}.
11297
11298On AIX, the @option{-maltivec} and @option{-mpowerpc64} options are
11299not enabled or disabled by the @option{-mcpu} option at present because
11300AIX does not have full support for these options. You may still
11301enable or disable them individually if you're sure it'll work in your
11302environment.
11303
11304@item -mtune=@var{cpu_type}
11305@opindex mtune
11306Set the instruction scheduling parameters for machine type
11307@var{cpu_type}, but do not set the architecture type, register usage, or
11308choice of mnemonics, as @option{-mcpu=@var{cpu_type}} would. The same
11309values for @var{cpu_type} are used for @option{-mtune} as for
11310@option{-mcpu}. If both are specified, the code generated will use the
11311architecture, registers, and mnemonics set by @option{-mcpu}, but the
11312scheduling parameters set by @option{-mtune}.
11313
11314@item -mswdiv
11315@itemx -mno-swdiv
11316@opindex mswdiv
11317@opindex mno-swdiv
11318Generate code to compute division as reciprocal estimate and iterative
11319refinement, creating opportunities for increased throughput. This
11320feature requires: optional PowerPC Graphics instruction set for single
11321precision and FRE instruction for double precision, assuming divides
11322cannot generate user-visible traps, and the domain values not include
11323Infinities, denormals or zero denominator.
11324
11325@item -maltivec
11326@itemx -mno-altivec
11327@opindex maltivec
11328@opindex mno-altivec
11329Generate code that uses (does not use) AltiVec instructions, and also
11330enable the use of built-in functions that allow more direct access to
11331the AltiVec instruction set. You may also need to set
11332@option{-mabi=altivec} to adjust the current ABI with AltiVec ABI
11333enhancements.
11334
11335@item -mvrsave
11336@item -mno-vrsave
11337@opindex mvrsave
11338@opindex mno-vrsave
11339Generate VRSAVE instructions when generating AltiVec code.
11340
11341@item -msecure-plt
11342@opindex msecure-plt
11343Generate code that allows ld and ld.so to build executables and shared
11344libraries with non-exec .plt and .got sections. This is a PowerPC
1134532-bit SYSV ABI option.
11346
11347@item -mbss-plt
11348@opindex mbss-plt
11349Generate code that uses a BSS .plt section that ld.so fills in, and
11350requires .plt and .got sections that are both writable and executable.
11351This is a PowerPC 32-bit SYSV ABI option.
11352
11353@item -misel
11354@itemx -mno-isel
11355@opindex misel
11356@opindex mno-isel
11357This switch enables or disables the generation of ISEL instructions.
11358
11359@item -misel=@var{yes/no}
11360This switch has been deprecated. Use @option{-misel} and
11361@option{-mno-isel} instead.
11362
11363@item -mspe
11364@itemx -mno-spe
11365@opindex mspe
11366@opindex mno-spe
11367This switch enables or disables the generation of SPE simd
11368instructions.
11369
11370@item -mspe=@var{yes/no}
11371This option has been deprecated. Use @option{-mspe} and
11372@option{-mno-spe} instead.
11373
11374@item -mfloat-gprs=@var{yes/single/double/no}
11375@itemx -mfloat-gprs
11376@opindex mfloat-gprs
11377This switch enables or disables the generation of floating point
11378operations on the general purpose registers for architectures that
11379support it.
11380
11381The argument @var{yes} or @var{single} enables the use of
11382single-precision floating point operations.
11383
11384The argument @var{double} enables the use of single and
11385double-precision floating point operations.
11386
11387The argument @var{no} disables floating point operations on the
11388general purpose registers.
11389
11390This option is currently only available on the MPC854x.
11391
11392@item -m32
11393@itemx -m64
11394@opindex m32
11395@opindex m64
11396Generate code for 32-bit or 64-bit environments of Darwin and SVR4
11397targets (including GNU/Linux). The 32-bit environment sets int, long
11398and pointer to 32 bits and generates code that runs on any PowerPC
11399variant. The 64-bit environment sets int to 32 bits and long and
11400pointer to 64 bits, and generates code for PowerPC64, as for
11401@option{-mpowerpc64}.
11402
11403@item -mfull-toc
11404@itemx -mno-fp-in-toc
11405@itemx -mno-sum-in-toc
11406@itemx -mminimal-toc
11407@opindex mfull-toc
11408@opindex mno-fp-in-toc
11409@opindex mno-sum-in-toc
11410@opindex mminimal-toc
11411Modify generation of the TOC (Table Of Contents), which is created for
11412every executable file. The @option{-mfull-toc} option is selected by
11413default. In that case, GCC will allocate at least one TOC entry for
11414each unique non-automatic variable reference in your program. GCC
11415will also place floating-point constants in the TOC@. However, only
1141616,384 entries are available in the TOC@.
11417
11418If you receive a linker error message that saying you have overflowed
11419the available TOC space, you can reduce the amount of TOC space used
11420with the @option{-mno-fp-in-toc} and @option{-mno-sum-in-toc} options.
11421@option{-mno-fp-in-toc} prevents GCC from putting floating-point
11422constants in the TOC and @option{-mno-sum-in-toc} forces GCC to
11423generate code to calculate the sum of an address and a constant at
11424run-time instead of putting that sum into the TOC@. You may specify one
11425or both of these options. Each causes GCC to produce very slightly
11426slower and larger code at the expense of conserving TOC space.
11427
11428If you still run out of space in the TOC even when you specify both of
11429these options, specify @option{-mminimal-toc} instead. This option causes
11430GCC to make only one TOC entry for every file. When you specify this
11431option, GCC will produce code that is slower and larger but which
11432uses extremely little TOC space. You may wish to use this option
11433only on files that contain less frequently executed code.
11434
11435@item -maix64
11436@itemx -maix32
11437@opindex maix64
11438@opindex maix32
11439Enable 64-bit AIX ABI and calling convention: 64-bit pointers, 64-bit
11440@code{long} type, and the infrastructure needed to support them.
11441Specifying @option{-maix64} implies @option{-mpowerpc64} and
11442@option{-mpowerpc}, while @option{-maix32} disables the 64-bit ABI and
11443implies @option{-mno-powerpc64}. GCC defaults to @option{-maix32}.
11444
11445@item -mxl-compat
11446@itemx -mno-xl-compat
11447@opindex mxl-compat
11448@opindex mno-xl-compat
11449Produce code that conforms more closely to IBM XL compiler semantics
11450when using AIX-compatible ABI. Pass floating-point arguments to
11451prototyped functions beyond the register save area (RSA) on the stack
11452in addition to argument FPRs. Do not assume that most significant
11453double in 128-bit long double value is properly rounded when comparing
11454values and converting to double. Use XL symbol names for long double
11455support routines.
11456
11457The AIX calling convention was extended but not initially documented to
11458handle an obscure K&R C case of calling a function that takes the
11459address of its arguments with fewer arguments than declared. IBM XL
11460compilers access floating point arguments which do not fit in the
11461RSA from the stack when a subroutine is compiled without
11462optimization. Because always storing floating-point arguments on the
11463stack is inefficient and rarely needed, this option is not enabled by
11464default and only is necessary when calling subroutines compiled by IBM
11465XL compilers without optimization.
11466
11467@item -mpe
11468@opindex mpe
11469Support @dfn{IBM RS/6000 SP} @dfn{Parallel Environment} (PE)@. Link an
11470application written to use message passing with special startup code to
11471enable the application to run. The system must have PE installed in the
11472standard location (@file{/usr/lpp/ppe.poe/}), or the @file{specs} file
11473must be overridden with the @option{-specs=} option to specify the
11474appropriate directory location. The Parallel Environment does not
11475support threads, so the @option{-mpe} option and the @option{-pthread}
11476option are incompatible.
11477
11478@item -malign-natural
11479@itemx -malign-power
11480@opindex malign-natural
11481@opindex malign-power
11482On AIX, 32-bit Darwin, and 64-bit PowerPC GNU/Linux, the option
11483@option{-malign-natural} overrides the ABI-defined alignment of larger
11484types, such as floating-point doubles, on their natural size-based boundary.
11485The option @option{-malign-power} instructs GCC to follow the ABI-specified
11486alignment rules. GCC defaults to the standard alignment defined in the ABI@.
11487
11488On 64-bit Darwin, natural alignment is the default, and @option{-malign-power}
11489is not supported.
11490
11491@item -msoft-float
11492@itemx -mhard-float
11493@opindex msoft-float
11494@opindex mhard-float
11495Generate code that does not use (uses) the floating-point register set.
11496Software floating point emulation is provided if you use the
11497@option{-msoft-float} option, and pass the option to GCC when linking.
11498
11499@item -mmultiple
11500@itemx -mno-multiple
11501@opindex mmultiple
11502@opindex mno-multiple
11503Generate code that uses (does not use) the load multiple word
11504instructions and the store multiple word instructions. These
11505instructions are generated by default on POWER systems, and not
11506generated on PowerPC systems. Do not use @option{-mmultiple} on little
11507endian PowerPC systems, since those instructions do not work when the
11508processor is in little endian mode. The exceptions are PPC740 and
11509PPC750 which permit the instructions usage in little endian mode.
11510
11511@item -mstring
11512@itemx -mno-string
11513@opindex mstring
11514@opindex mno-string
11515Generate code that uses (does not use) the load string instructions
11516and the store string word instructions to save multiple registers and
11517do small block moves. These instructions are generated by default on
11518POWER systems, and not generated on PowerPC systems. Do not use
11519@option{-mstring} on little endian PowerPC systems, since those
11520instructions do not work when the processor is in little endian mode.
11521The exceptions are PPC740 and PPC750 which permit the instructions
11522usage in little endian mode.
11523
11524@item -mupdate
11525@itemx -mno-update
11526@opindex mupdate
11527@opindex mno-update
11528Generate code that uses (does not use) the load or store instructions
11529that update the base register to the address of the calculated memory
11530location. These instructions are generated by default. If you use
11531@option{-mno-update}, there is a small window between the time that the
11532stack pointer is updated and the address of the previous frame is
11533stored, which means code that walks the stack frame across interrupts or
11534signals may get corrupted data.
11535
11536@item -mfused-madd
11537@itemx -mno-fused-madd
11538@opindex mfused-madd
11539@opindex mno-fused-madd
11540Generate code that uses (does not use) the floating point multiply and
11541accumulate instructions. These instructions are generated by default if
11542hardware floating is used.
11543
11544@item -mmulhw
11545@itemx -mno-mulhw
11546@opindex mmulhw
11547@opindex mno-mulhw
11548Generate code that uses (does not use) the half-word multiply and
11549multiply-accumulate instructions on the IBM 405 and 440 processors.
11550These instructions are generated by default when targetting those
11551processors.
11552
11553@item -mdlmzb
11554@itemx -mno-dlmzb
11555@opindex mdlmzb
11556@opindex mno-dlmzb
11557Generate code that uses (does not use) the string-search @samp{dlmzb}
11558instruction on the IBM 405 and 440 processors. This instruction is
11559generated by default when targetting those processors.
11560
11561@item -mno-bit-align
11562@itemx -mbit-align
11563@opindex mno-bit-align
11564@opindex mbit-align
11565On System V.4 and embedded PowerPC systems do not (do) force structures
11566and unions that contain bit-fields to be aligned to the base type of the
11567bit-field.
11568
11569For example, by default a structure containing nothing but 8
11570@code{unsigned} bit-fields of length 1 would be aligned to a 4 byte
11571boundary and have a size of 4 bytes. By using @option{-mno-bit-align},
11572the structure would be aligned to a 1 byte boundary and be one byte in
11573size.
11574
11575@item -mno-strict-align
11576@itemx -mstrict-align
11577@opindex mno-strict-align
11578@opindex mstrict-align
11579On System V.4 and embedded PowerPC systems do not (do) assume that
11580unaligned memory references will be handled by the system.
11581
11582@item -mrelocatable
11583@itemx -mno-relocatable
11584@opindex mrelocatable
11585@opindex mno-relocatable
11586On embedded PowerPC systems generate code that allows (does not allow)
11587the program to be relocated to a different address at runtime. If you
11588use @option{-mrelocatable} on any module, all objects linked together must
11589be compiled with @option{-mrelocatable} or @option{-mrelocatable-lib}.
11590
11591@item -mrelocatable-lib
11592@itemx -mno-relocatable-lib
11593@opindex mrelocatable-lib
11594@opindex mno-relocatable-lib
11595On embedded PowerPC systems generate code that allows (does not allow)
11596the program to be relocated to a different address at runtime. Modules
11597compiled with @option{-mrelocatable-lib} can be linked with either modules
11598compiled without @option{-mrelocatable} and @option{-mrelocatable-lib} or
11599with modules compiled with the @option{-mrelocatable} options.
11600
11601@item -mno-toc
11602@itemx -mtoc
11603@opindex mno-toc
11604@opindex mtoc
11605On System V.4 and embedded PowerPC systems do not (do) assume that
11606register 2 contains a pointer to a global area pointing to the addresses
11607used in the program.
11608
11609@item -mlittle
11610@itemx -mlittle-endian
11611@opindex mlittle
11612@opindex mlittle-endian
11613On System V.4 and embedded PowerPC systems compile code for the
11614processor in little endian mode. The @option{-mlittle-endian} option is
11615the same as @option{-mlittle}.
11616
11617@item -mbig
11618@itemx -mbig-endian
11619@opindex mbig
11620@opindex mbig-endian
11621On System V.4 and embedded PowerPC systems compile code for the
11622processor in big endian mode. The @option{-mbig-endian} option is
11623the same as @option{-mbig}.
11624
11625@item -mdynamic-no-pic
11626@opindex mdynamic-no-pic
11627On Darwin and Mac OS X systems, compile code so that it is not
11628relocatable, but that its external references are relocatable. The
11629resulting code is suitable for applications, but not shared
11630libraries.
11631
11632@item -mprioritize-restricted-insns=@var{priority}
11633@opindex mprioritize-restricted-insns
11634This option controls the priority that is assigned to
11635dispatch-slot restricted instructions during the second scheduling
11636pass. The argument @var{priority} takes the value @var{0/1/2} to assign
11637@var{no/highest/second-highest} priority to dispatch slot restricted
11638instructions.
11639
11640@item -msched-costly-dep=@var{dependence_type}
11641@opindex msched-costly-dep
11642This option controls which dependences are considered costly
11643by the target during instruction scheduling. The argument
11644@var{dependence_type} takes one of the following values:
11645@var{no}: no dependence is costly,
11646@var{all}: all dependences are costly,
11647@var{true_store_to_load}: a true dependence from store to load is costly,
11648@var{store_to_load}: any dependence from store to load is costly,
11649@var{number}: any dependence which latency >= @var{number} is costly.
11650
11651@item -minsert-sched-nops=@var{scheme}
11652@opindex minsert-sched-nops
11653This option controls which nop insertion scheme will be used during
11654the second scheduling pass. The argument @var{scheme} takes one of the
11655following values:
11656@var{no}: Don't insert nops.
11657@var{pad}: Pad with nops any dispatch group which has vacant issue slots,
11658according to the scheduler's grouping.
11659@var{regroup_exact}: Insert nops to force costly dependent insns into
11660separate groups. Insert exactly as many nops as needed to force an insn
11661to a new group, according to the estimated processor grouping.
11662@var{number}: Insert nops to force costly dependent insns into
11663separate groups. Insert @var{number} nops to force an insn to a new group.
11664
11665@item -mcall-sysv
11666@opindex mcall-sysv
11667On System V.4 and embedded PowerPC systems compile code using calling
11668conventions that adheres to the March 1995 draft of the System V
11669Application Binary Interface, PowerPC processor supplement. This is the
11670default unless you configured GCC using @samp{powerpc-*-eabiaix}.
11671
11672@item -mcall-sysv-eabi
11673@opindex mcall-sysv-eabi
11674Specify both @option{-mcall-sysv} and @option{-meabi} options.
11675
11676@item -mcall-sysv-noeabi
11677@opindex mcall-sysv-noeabi
11678Specify both @option{-mcall-sysv} and @option{-mno-eabi} options.
11679
11680@item -mcall-solaris
11681@opindex mcall-solaris
11682On System V.4 and embedded PowerPC systems compile code for the Solaris
11683operating system.
11684
11685@item -mcall-linux
11686@opindex mcall-linux
11687On System V.4 and embedded PowerPC systems compile code for the
11688Linux-based GNU system.
11689
11690@item -mcall-gnu
11691@opindex mcall-gnu
11692On System V.4 and embedded PowerPC systems compile code for the
11693Hurd-based GNU system.
11694
11695@item -mcall-netbsd
11696@opindex mcall-netbsd
11697On System V.4 and embedded PowerPC systems compile code for the
11698NetBSD operating system.
11699
11700@item -maix-struct-return
11701@opindex maix-struct-return
11702Return all structures in memory (as specified by the AIX ABI)@.
11703
11704@item -msvr4-struct-return
11705@opindex msvr4-struct-return
11706Return structures smaller than 8 bytes in registers (as specified by the
11707SVR4 ABI)@.
11708
11709@item -mabi=@var{abi-type}
11710@opindex mabi
11711Extend the current ABI with a particular extension, or remove such extension.
11712Valid values are @var{altivec}, @var{no-altivec}, @var{spe},
11713@var{no-spe}, @var{ibmlongdouble}, @var{ieeelongdouble}@.
11714
11715@item -mabi=spe
11716@opindex mabi=spe
11717Extend the current ABI with SPE ABI extensions. This does not change
11718the default ABI, instead it adds the SPE ABI extensions to the current
11719ABI@.
11720
11721@item -mabi=no-spe
11722@opindex mabi=no-spe
11723Disable Booke SPE ABI extensions for the current ABI@.
11724
11725@item -mabi=ibmlongdouble
11726@opindex mabi=ibmlongdouble
11727Change the current ABI to use IBM extended precision long double.
11728This is a PowerPC 32-bit SYSV ABI option.
11729
11730@item -mabi=ieeelongdouble
11731@opindex mabi=ieeelongdouble
11732Change the current ABI to use IEEE extended precision long double.
11733This is a PowerPC 32-bit Linux ABI option.
11734
11735@item -mprototype
11736@itemx -mno-prototype
11737@opindex mprototype
11738@opindex mno-prototype
11739On System V.4 and embedded PowerPC systems assume that all calls to
11740variable argument functions are properly prototyped. Otherwise, the
11741compiler must insert an instruction before every non prototyped call to
11742set or clear bit 6 of the condition code register (@var{CR}) to
11743indicate whether floating point values were passed in the floating point
11744registers in case the function takes a variable arguments. With
11745@option{-mprototype}, only calls to prototyped variable argument functions
11746will set or clear the bit.
11747
11748@item -msim
11749@opindex msim
11750On embedded PowerPC systems, assume that the startup module is called
11751@file{sim-crt0.o} and that the standard C libraries are @file{libsim.a} and
11752@file{libc.a}. This is the default for @samp{powerpc-*-eabisim}.
11753configurations.
11754
11755@item -mmvme
11756@opindex mmvme
11757On embedded PowerPC systems, assume that the startup module is called
11758@file{crt0.o} and the standard C libraries are @file{libmvme.a} and
11759@file{libc.a}.
11760
11761@item -mads
11762@opindex mads
11763On embedded PowerPC systems, assume that the startup module is called
11764@file{crt0.o} and the standard C libraries are @file{libads.a} and
11765@file{libc.a}.
11766
11767@item -myellowknife
11768@opindex myellowknife
11769On embedded PowerPC systems, assume that the startup module is called
11770@file{crt0.o} and the standard C libraries are @file{libyk.a} and
11771@file{libc.a}.
11772
11773@item -mvxworks
11774@opindex mvxworks
11775On System V.4 and embedded PowerPC systems, specify that you are
11776compiling for a VxWorks system.
11777
11778@item -mwindiss
11779@opindex mwindiss
11780Specify that you are compiling for the WindISS simulation environment.
11781
11782@item -memb
11783@opindex memb
11784On embedded PowerPC systems, set the @var{PPC_EMB} bit in the ELF flags
11785header to indicate that @samp{eabi} extended relocations are used.
11786
11787@item -meabi
11788@itemx -mno-eabi
11789@opindex meabi
11790@opindex mno-eabi
11791On System V.4 and embedded PowerPC systems do (do not) adhere to the
11792Embedded Applications Binary Interface (eabi) which is a set of
11793modifications to the System V.4 specifications. Selecting @option{-meabi}
11794means that the stack is aligned to an 8 byte boundary, a function
11795@code{__eabi} is called to from @code{main} to set up the eabi
11796environment, and the @option{-msdata} option can use both @code{r2} and
11797@code{r13} to point to two separate small data areas. Selecting
11798@option{-mno-eabi} means that the stack is aligned to a 16 byte boundary,
11799do not call an initialization function from @code{main}, and the
11800@option{-msdata} option will only use @code{r13} to point to a single
11801small data area. The @option{-meabi} option is on by default if you
11802configured GCC using one of the @samp{powerpc*-*-eabi*} options.
11803
11804@item -msdata=eabi
11805@opindex msdata=eabi
11806On System V.4 and embedded PowerPC systems, put small initialized
11807@code{const} global and static data in the @samp{.sdata2} section, which
11808is pointed to by register @code{r2}. Put small initialized
11809non-@code{const} global and static data in the @samp{.sdata} section,
11810which is pointed to by register @code{r13}. Put small uninitialized
11811global and static data in the @samp{.sbss} section, which is adjacent to
11812the @samp{.sdata} section. The @option{-msdata=eabi} option is
11813incompatible with the @option{-mrelocatable} option. The
11814@option{-msdata=eabi} option also sets the @option{-memb} option.
11815
11816@item -msdata=sysv
11817@opindex msdata=sysv
11818On System V.4 and embedded PowerPC systems, put small global and static
11819data in the @samp{.sdata} section, which is pointed to by register
11820@code{r13}. Put small uninitialized global and static data in the
11821@samp{.sbss} section, which is adjacent to the @samp{.sdata} section.
11822The @option{-msdata=sysv} option is incompatible with the
11823@option{-mrelocatable} option.
11824
11825@item -msdata=default
11826@itemx -msdata
11827@opindex msdata=default
11828@opindex msdata
11829On System V.4 and embedded PowerPC systems, if @option{-meabi} is used,
11830compile code the same as @option{-msdata=eabi}, otherwise compile code the
11831same as @option{-msdata=sysv}.
11832
11833@item -msdata-data
11834@opindex msdata-data
11835On System V.4 and embedded PowerPC systems, put small global
11836data in the @samp{.sdata} section. Put small uninitialized global
11837data in the @samp{.sbss} section. Do not use register @code{r13}
11838to address small data however. This is the default behavior unless
11839other @option{-msdata} options are used.
11840
11841@item -msdata=none
11842@itemx -mno-sdata
11843@opindex msdata=none
11844@opindex mno-sdata
11845On embedded PowerPC systems, put all initialized global and static data
11846in the @samp{.data} section, and all uninitialized data in the
11847@samp{.bss} section.
11848
11849@item -G @var{num}
11850@opindex G
11851@cindex smaller data references (PowerPC)
11852@cindex .sdata/.sdata2 references (PowerPC)
11853On embedded PowerPC systems, put global and static items less than or
11854equal to @var{num} bytes into the small data or bss sections instead of
11855the normal data or bss section. By default, @var{num} is 8. The
11856@option{-G @var{num}} switch is also passed to the linker.
11857All modules should be compiled with the same @option{-G @var{num}} value.
11858
11859@item -mregnames
11860@itemx -mno-regnames
11861@opindex mregnames
11862@opindex mno-regnames
11863On System V.4 and embedded PowerPC systems do (do not) emit register
11864names in the assembly language output using symbolic forms.
11865
11866@item -mlongcall
11867@itemx -mno-longcall
11868@opindex mlongcall
11869@opindex mno-longcall
11870By default assume that all calls are far away so that a longer more
11871expensive calling sequence is required. This is required for calls
11872further than 32 megabytes (33,554,432 bytes) from the current location.
11873A short call will be generated if the compiler knows
11874the call cannot be that far away. This setting can be overridden by
11875the @code{shortcall} function attribute, or by @code{#pragma
11876longcall(0)}.
11877
11878Some linkers are capable of detecting out-of-range calls and generating
11879glue code on the fly. On these systems, long calls are unnecessary and
11880generate slower code. As of this writing, the AIX linker can do this,
11881as can the GNU linker for PowerPC/64. It is planned to add this feature
11882to the GNU linker for 32-bit PowerPC systems as well.
11883
11884On Darwin/PPC systems, @code{#pragma longcall} will generate ``jbsr
11885callee, L42'', plus a ``branch island'' (glue code). The two target
11886addresses represent the callee and the ``branch island''. The
11887Darwin/PPC linker will prefer the first address and generate a ``bl
11888callee'' if the PPC ``bl'' instruction will reach the callee directly;
11889otherwise, the linker will generate ``bl L42'' to call the ``branch
11890island''. The ``branch island'' is appended to the body of the
11891calling function; it computes the full 32-bit address of the callee
11892and jumps to it.
11893
11894On Mach-O (Darwin) systems, this option directs the compiler emit to
11895the glue for every direct call, and the Darwin linker decides whether
11896to use or discard it.
11897
11898In the future, we may cause GCC to ignore all longcall specifications
11899when the linker is known to generate glue.
11900
11901@item -pthread
11902@opindex pthread
11903Adds support for multithreading with the @dfn{pthreads} library.
11904This option sets flags for both the preprocessor and linker.
11905
11906@end table
11907
11908@node S/390 and zSeries Options
11909@subsection S/390 and zSeries Options
11910@cindex S/390 and zSeries Options
11911
11912These are the @samp{-m} options defined for the S/390 and zSeries architecture.
11913
11914@table @gcctabopt
11915@item -mhard-float
11916@itemx -msoft-float
11917@opindex mhard-float
11918@opindex msoft-float
11919Use (do not use) the hardware floating-point instructions and registers
11920for floating-point operations. When @option{-msoft-float} is specified,
11921functions in @file{libgcc.a} will be used to perform floating-point
11922operations. When @option{-mhard-float} is specified, the compiler
11923generates IEEE floating-point instructions. This is the default.
11924
11925@item -mlong-double-64
11926@itemx -mlong-double-128
11927@opindex mlong-double-64
11928@opindex mlong-double-128
11929These switches control the size of @code{long double} type. A size
11930of 64bit makes the @code{long double} type equivalent to the @code{double}
11931type. This is the default.
11932
11933@item -mbackchain
11934@itemx -mno-backchain
11935@opindex mbackchain
11936@opindex mno-backchain
11937Store (do not store) the address of the caller's frame as backchain pointer
11938into the callee's stack frame.
11939A backchain may be needed to allow debugging using tools that do not understand
11940DWARF-2 call frame information.
11941When @option{-mno-packed-stack} is in effect, the backchain pointer is stored
11942at the bottom of the stack frame; when @option{-mpacked-stack} is in effect,
11943the backchain is placed into the topmost word of the 96/160 byte register
11944save area.
11945
11946In general, code compiled with @option{-mbackchain} is call-compatible with
11947code compiled with @option{-mmo-backchain}; however, use of the backchain
11948for debugging purposes usually requires that the whole binary is built with
11949@option{-mbackchain}. Note that the combination of @option{-mbackchain},
11950@option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
11951to build a linux kernel use @option{-msoft-float}.
11952
11953The default is to not maintain the backchain.
11954
11955@item -mpacked-stack
11956@item -mno-packed-stack
11957@opindex mpacked-stack
11958@opindex mno-packed-stack
11959Use (do not use) the packed stack layout. When @option{-mno-packed-stack} is
11960specified, the compiler uses the all fields of the 96/160 byte register save
11961area only for their default purpose; unused fields still take up stack space.
11962When @option{-mpacked-stack} is specified, register save slots are densely
11963packed at the top of the register save area; unused space is reused for other
11964purposes, allowing for more efficient use of the available stack space.
11965However, when @option{-mbackchain} is also in effect, the topmost word of
11966the save area is always used to store the backchain, and the return address
11967register is always saved two words below the backchain.
11968
11969As long as the stack frame backchain is not used, code generated with
11970@option{-mpacked-stack} is call-compatible with code generated with
11971@option{-mno-packed-stack}. Note that some non-FSF releases of GCC 2.95 for
11972S/390 or zSeries generated code that uses the stack frame backchain at run
11973time, not just for debugging purposes. Such code is not call-compatible
11974with code compiled with @option{-mpacked-stack}. Also, note that the
11975combination of @option{-mbackchain},
11976@option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
11977to build a linux kernel use @option{-msoft-float}.
11978
11979The default is to not use the packed stack layout.
11980
11981@item -msmall-exec
11982@itemx -mno-small-exec
11983@opindex msmall-exec
11984@opindex mno-small-exec
11985Generate (or do not generate) code using the @code{bras} instruction
11986to do subroutine calls.
11987This only works reliably if the total executable size does not
11988exceed 64k. The default is to use the @code{basr} instruction instead,
11989which does not have this limitation.
11990
11991@item -m64
11992@itemx -m31
11993@opindex m64
11994@opindex m31
11995When @option{-m31} is specified, generate code compliant to the
11996GNU/Linux for S/390 ABI@. When @option{-m64} is specified, generate
11997code compliant to the GNU/Linux for zSeries ABI@. This allows GCC in
11998particular to generate 64-bit instructions. For the @samp{s390}
11999targets, the default is @option{-m31}, while the @samp{s390x}
12000targets default to @option{-m64}.
12001
12002@item -mzarch
12003@itemx -mesa
12004@opindex mzarch
12005@opindex mesa
12006When @option{-mzarch} is specified, generate code using the
12007instructions available on z/Architecture.
12008When @option{-mesa} is specified, generate code using the
12009instructions available on ESA/390. Note that @option{-mesa} is
12010not possible with @option{-m64}.
12011When generating code compliant to the GNU/Linux for S/390 ABI,
12012the default is @option{-mesa}. When generating code compliant
12013to the GNU/Linux for zSeries ABI, the default is @option{-mzarch}.
12014
12015@item -mmvcle
12016@itemx -mno-mvcle
12017@opindex mmvcle
12018@opindex mno-mvcle
12019Generate (or do not generate) code using the @code{mvcle} instruction
12020to perform block moves. When @option{-mno-mvcle} is specified,
12021use a @code{mvc} loop instead. This is the default unless optimizing for
12022size.
12023
12024@item -mdebug
12025@itemx -mno-debug
12026@opindex mdebug
12027@opindex mno-debug
12028Print (or do not print) additional debug information when compiling.
12029The default is to not print debug information.
12030
12031@item -march=@var{cpu-type}
12032@opindex march
12033Generate code that will run on @var{cpu-type}, which is the name of a system
12034representing a certain processor type. Possible values for
12035@var{cpu-type} are @samp{g5}, @samp{g6}, @samp{z900}, and @samp{z990}.
12036When generating code using the instructions available on z/Architecture,
12037the default is @option{-march=z900}. Otherwise, the default is
12038@option{-march=g5}.
12039
12040@item -mtune=@var{cpu-type}
12041@opindex mtune
12042Tune to @var{cpu-type} everything applicable about the generated code,
12043except for the ABI and the set of available instructions.
12044The list of @var{cpu-type} values is the same as for @option{-march}.
12045The default is the value used for @option{-march}.
12046
12047@item -mtpf-trace
12048@itemx -mno-tpf-trace
12049@opindex mtpf-trace
12050@opindex mno-tpf-trace
12051Generate code that adds (does not add) in TPF OS specific branches to trace
12052routines in the operating system. This option is off by default, even
12053when compiling for the TPF OS@.
12054
12055@item -mfused-madd
12056@itemx -mno-fused-madd
12057@opindex mfused-madd
12058@opindex mno-fused-madd
12059Generate code that uses (does not use) the floating point multiply and
12060accumulate instructions. These instructions are generated by default if
12061hardware floating point is used.
12062
12063@item -mwarn-framesize=@var{framesize}
12064@opindex mwarn-framesize
12065Emit a warning if the current function exceeds the given frame size. Because
12066this is a compile time check it doesn't need to be a real problem when the program
12067runs. It is intended to identify functions which most probably cause
12068a stack overflow. It is useful to be used in an environment with limited stack
12069size e.g.@: the linux kernel.
12070
12071@item -mwarn-dynamicstack
12072@opindex mwarn-dynamicstack
12073Emit a warning if the function calls alloca or uses dynamically
12074sized arrays. This is generally a bad idea with a limited stack size.
12075
12076@item -mstack-guard=@var{stack-guard}
12077@item -mstack-size=@var{stack-size}
12078@opindex mstack-guard
12079@opindex mstack-size
12080These arguments always have to be used in conjunction. If they are present the s390
12081back end emits additional instructions in the function prologue which trigger a trap
12082if the stack size is @var{stack-guard} bytes above the @var{stack-size}
12083(remember that the stack on s390 grows downward). These options are intended to
12084be used to help debugging stack overflow problems. The additionally emitted code
12085causes only little overhead and hence can also be used in production like systems
12086without greater performance degradation. The given values have to be exact
12087powers of 2 and @var{stack-size} has to be greater than @var{stack-guard} without
12088exceeding 64k.
12089In order to be efficient the extra code makes the assumption that the stack starts
12090at an address aligned to the value given by @var{stack-size}.
12091@end table
12092
12093@node Score Options
12094@subsection Score Options
12095@cindex Score Options
12096
12097These options are defined for Score implementations:
12098
12099@table @gcctabopt
12100@item -meb
12101@opindex meb
12102Compile code for big endian mode. This is the default.
12103
12104@item -mel
12105@opindex mel
12106Compile code for little endian mode.
12107
12108@item -mnhwloop
12109@opindex mnhwloop
12110Disable generate bcnz instruction.
12111
12112@item -muls
12113@opindex muls
12114Enable generate unaligned load and store instruction.
12115
12116@item -mmac
12117@opindex mmac
12118Enable the use of multiply-accumulate instructions. Disabled by default.
12119
12120@item -mscore5
12121@opindex mscore5
12122Specify the SCORE5 as the target architecture.
12123
12124@item -mscore5u
12125@opindex mscore5u
12126Specify the SCORE5U of the target architecture.
12127
12128@item -mscore7
12129@opindex mscore7
12130Specify the SCORE7 as the target architecture. This is the default.
12131
12132@item -mscore7d
12133@opindex mscore7d
12134Specify the SCORE7D as the target architecture.
12135@end table
12136
12137@node SH Options
12138@subsection SH Options
12139
12140These @samp{-m} options are defined for the SH implementations:
12141
12142@table @gcctabopt
12143@item -m1
12144@opindex m1
12145Generate code for the SH1.
12146
12147@item -m2
12148@opindex m2
12149Generate code for the SH2.
12150
12151@item -m2e
12152Generate code for the SH2e.
12153
12154@item -m3
12155@opindex m3
12156Generate code for the SH3.
12157
12158@item -m3e
12159@opindex m3e
12160Generate code for the SH3e.
12161
12162@item -m4-nofpu
12163@opindex m4-nofpu
12164Generate code for the SH4 without a floating-point unit.
12165
12166@item -m4-single-only
12167@opindex m4-single-only
12168Generate code for the SH4 with a floating-point unit that only
12169supports single-precision arithmetic.
12170
12171@item -m4-single
12172@opindex m4-single
12173Generate code for the SH4 assuming the floating-point unit is in
12174single-precision mode by default.
12175
12176@item -m4
12177@opindex m4
12178Generate code for the SH4.
12179
12180@item -m4a-nofpu
12181@opindex m4a-nofpu
12182Generate code for the SH4al-dsp, or for a SH4a in such a way that the
12183floating-point unit is not used.
12184
12185@item -m4a-single-only
12186@opindex m4a-single-only
12187Generate code for the SH4a, in such a way that no double-precision
12188floating point operations are used.
12189
12190@item -m4a-single
12191@opindex m4a-single
12192Generate code for the SH4a assuming the floating-point unit is in
12193single-precision mode by default.
12194
12195@item -m4a
12196@opindex m4a
12197Generate code for the SH4a.
12198
12199@item -m4al
12200@opindex m4al
12201Same as @option{-m4a-nofpu}, except that it implicitly passes
12202@option{-dsp} to the assembler. GCC doesn't generate any DSP
12203instructions at the moment.
12204
12205@item -mb
12206@opindex mb
12207Compile code for the processor in big endian mode.
12208
12209@item -ml
12210@opindex ml
12211Compile code for the processor in little endian mode.
12212
12213@item -mdalign
12214@opindex mdalign
12215Align doubles at 64-bit boundaries. Note that this changes the calling
12216conventions, and thus some functions from the standard C library will
12217not work unless you recompile it first with @option{-mdalign}.
12218
12219@item -mrelax
12220@opindex mrelax
12221Shorten some address references at link time, when possible; uses the
12222linker option @option{-relax}.
12223
12224@item -mbigtable
12225@opindex mbigtable
12226Use 32-bit offsets in @code{switch} tables. The default is to use
1222716-bit offsets.
12228
12229@item -mfmovd
12230@opindex mfmovd
12231Enable the use of the instruction @code{fmovd}.
12232
12233@item -mhitachi
12234@opindex mhitachi
12235Comply with the calling conventions defined by Renesas.
12236
12237@item -mrenesas
12238@opindex mhitachi
12239Comply with the calling conventions defined by Renesas.
12240
12241@item -mno-renesas
12242@opindex mhitachi
12243Comply with the calling conventions defined for GCC before the Renesas
12244conventions were available. This option is the default for all
12245targets of the SH toolchain except for @samp{sh-symbianelf}.
12246
12247@item -mnomacsave
12248@opindex mnomacsave
12249Mark the @code{MAC} register as call-clobbered, even if
12250@option{-mhitachi} is given.
12251
12252@item -mieee
12253@opindex mieee
12254Increase IEEE-compliance of floating-point code.
12255At the moment, this is equivalent to @option{-fno-finite-math-only}.
12256When generating 16 bit SH opcodes, getting IEEE-conforming results for
12257comparisons of NANs / infinities incurs extra overhead in every
12258floating point comparison, therefore the default is set to
12259@option{-ffinite-math-only}.
12260
12261@item -misize
12262@opindex misize
12263Dump instruction size and location in the assembly code.
12264
12265@item -mpadstruct
12266@opindex mpadstruct
12267This option is deprecated. It pads structures to multiple of 4 bytes,
12268which is incompatible with the SH ABI@.
12269
12270@item -mspace
12271@opindex mspace
12272Optimize for space instead of speed. Implied by @option{-Os}.
12273
12274@item -mprefergot
12275@opindex mprefergot
12276When generating position-independent code, emit function calls using
12277the Global Offset Table instead of the Procedure Linkage Table.
12278
12279@item -musermode
12280@opindex musermode
12281Generate a library function call to invalidate instruction cache
12282entries, after fixing up a trampoline. This library function call
12283doesn't assume it can write to the whole memory address space. This
12284is the default when the target is @code{sh-*-linux*}.
12285
12286@item -multcost=@var{number}
12287@opindex multcost=@var{number}
12288Set the cost to assume for a multiply insn.
12289
12290@item -mdiv=@var{strategy}
12291@opindex mdiv=@var{strategy}
12292Set the division strategy to use for SHmedia code. @var{strategy} must be
12293one of: call, call2, fp, inv, inv:minlat, inv20u, inv20l, inv:call,
12294inv:call2, inv:fp .
12295"fp" performs the operation in floating point. This has a very high latency,
12296but needs only a few instructions, so it might be a good choice if
12297your code has enough easily exploitable ILP to allow the compiler to
12298schedule the floating point instructions together with other instructions.
12299Division by zero causes a floating point exception.
12300"inv" uses integer operations to calculate the inverse of the divisor,
12301and then multiplies the dividend with the inverse. This strategy allows
12302cse and hoisting of the inverse calculation. Division by zero calculates
12303an unspecified result, but does not trap.
12304"inv:minlat" is a variant of "inv" where if no cse / hoisting opportunities
12305have been found, or if the entire operation has been hoisted to the same
12306place, the last stages of the inverse calculation are intertwined with the
12307final multiply to reduce the overall latency, at the expense of using a few
12308more instructions, and thus offering fewer scheduling opportunities with
12309other code.
12310"call" calls a library function that usually implements the inv:minlat
12311strategy.
12312This gives high code density for m5-*media-nofpu compilations.
12313"call2" uses a different entry point of the same library function, where it
12314assumes that a pointer to a lookup table has already been set up, which
12315exposes the pointer load to cse / code hoisting optimizations.
12316"inv:call", "inv:call2" and "inv:fp" all use the "inv" algorithm for initial
12317code generation, but if the code stays unoptimized, revert to the "call",
12318"call2", or "fp" strategies, respectively. Note that the
12319potentially-trapping side effect of division by zero is carried by a
12320separate instruction, so it is possible that all the integer instructions
12321are hoisted out, but the marker for the side effect stays where it is.
12322A recombination to fp operations or a call is not possible in that case.
12323"inv20u" and "inv20l" are variants of the "inv:minlat" strategy. In the case
12324that the inverse calculation was nor separated from the multiply, they speed
12325up division where the dividend fits into 20 bits (plus sign where applicable),
12326by inserting a test to skip a number of operations in this case; this test
12327slows down the case of larger dividends. inv20u assumes the case of a such
12328a small dividend to be unlikely, and inv20l assumes it to be likely.
12329
12330@item -mdivsi3_libfunc=@var{name}
12331@opindex mdivsi3_libfunc=@var{name}
12332Set the name of the library function used for 32 bit signed division to
12333@var{name}. This only affect the name used in the call and inv:call
12334division strategies, and the compiler will still expect the same
12335sets of input/output/clobbered registers as if this option was not present.
12336
12337@item -madjust-unroll
12338@opindex madjust-unroll
12339Throttle unrolling to avoid thrashing target registers.
12340This option only has an effect if the gcc code base supports the
12341TARGET_ADJUST_UNROLL_MAX target hook.
12342
12343@item -mindexed-addressing
12344@opindex mindexed-addressing
12345Enable the use of the indexed addressing mode for SHmedia32/SHcompact.
12346This is only safe if the hardware and/or OS implement 32 bit wrap-around
12347semantics for the indexed addressing mode. The architecture allows the
12348implementation of processors with 64 bit MMU, which the OS could use to
12349get 32 bit addressing, but since no current hardware implementation supports
12350this or any other way to make the indexed addressing mode safe to use in
12351the 32 bit ABI, the default is -mno-indexed-addressing.
12352
12353@item -mgettrcost=@var{number}
12354@opindex mgettrcost=@var{number}
12355Set the cost assumed for the gettr instruction to @var{number}.
12356The default is 2 if @option{-mpt-fixed} is in effect, 100 otherwise.
12357
12358@item -mpt-fixed
12359@opindex mpt-fixed
12360Assume pt* instructions won't trap. This will generally generate better
12361scheduled code, but is unsafe on current hardware. The current architecture
12362definition says that ptabs and ptrel trap when the target anded with 3 is 3.
12363This has the unintentional effect of making it unsafe to schedule ptabs /
12364ptrel before a branch, or hoist it out of a loop. For example,
12365__do_global_ctors, a part of libgcc that runs constructors at program
12366startup, calls functions in a list which is delimited by -1. With the
12367-mpt-fixed option, the ptabs will be done before testing against -1.
12368That means that all the constructors will be run a bit quicker, but when
12369the loop comes to the end of the list, the program crashes because ptabs
12370loads -1 into a target register. Since this option is unsafe for any
12371hardware implementing the current architecture specification, the default
12372is -mno-pt-fixed. Unless the user specifies a specific cost with
12373@option{-mgettrcost}, -mno-pt-fixed also implies @option{-mgettrcost=100};
12374this deters register allocation using target registers for storing
12375ordinary integers.
12376
12377@item -minvalid-symbols
12378@opindex minvalid-symbols
12379Assume symbols might be invalid. Ordinary function symbols generated by
12380the compiler will always be valid to load with movi/shori/ptabs or
12381movi/shori/ptrel, but with assembler and/or linker tricks it is possible
12382to generate symbols that will cause ptabs / ptrel to trap.
12383This option is only meaningful when @option{-mno-pt-fixed} is in effect.
12384It will then prevent cross-basic-block cse, hoisting and most scheduling
12385of symbol loads. The default is @option{-mno-invalid-symbols}.
12386@end table
12387
12388@node SPARC Options
12389@subsection SPARC Options
12390@cindex SPARC options
12391
12392These @samp{-m} options are supported on the SPARC:
12393
12394@table @gcctabopt
12395@item -mno-app-regs
12396@itemx -mapp-regs
12397@opindex mno-app-regs
12398@opindex mapp-regs
12399Specify @option{-mapp-regs} to generate output using the global registers
124002 through 4, which the SPARC SVR4 ABI reserves for applications. This
12401is the default.
12402
12403To be fully SVR4 ABI compliant at the cost of some performance loss,
12404specify @option{-mno-app-regs}. You should compile libraries and system
12405software with this option.
12406
12407@item -mfpu
12408@itemx -mhard-float
12409@opindex mfpu
12410@opindex mhard-float
12411Generate output containing floating point instructions. This is the
12412default.
12413
12414@item -mno-fpu
12415@itemx -msoft-float
12416@opindex mno-fpu
12417@opindex msoft-float
12418Generate output containing library calls for floating point.
12419@strong{Warning:} the requisite libraries are not available for all SPARC
12420targets. Normally the facilities of the machine's usual C compiler are
12421used, but this cannot be done directly in cross-compilation. You must make
12422your own arrangements to provide suitable library functions for
12423cross-compilation. The embedded targets @samp{sparc-*-aout} and
12424@samp{sparclite-*-*} do provide software floating point support.
12425
12426@option{-msoft-float} changes the calling convention in the output file;
12427therefore, it is only useful if you compile @emph{all} of a program with
12428this option. In particular, you need to compile @file{libgcc.a}, the
12429library that comes with GCC, with @option{-msoft-float} in order for
12430this to work.
12431
12432@item -mhard-quad-float
12433@opindex mhard-quad-float
12434Generate output containing quad-word (long double) floating point
12435instructions.
12436
12437@item -msoft-quad-float
12438@opindex msoft-quad-float
12439Generate output containing library calls for quad-word (long double)
12440floating point instructions. The functions called are those specified
12441in the SPARC ABI@. This is the default.
12442
12443As of this writing, there are no SPARC implementations that have hardware
12444support for the quad-word floating point instructions. They all invoke
12445a trap handler for one of these instructions, and then the trap handler
12446emulates the effect of the instruction. Because of the trap handler overhead,
12447this is much slower than calling the ABI library routines. Thus the
12448@option{-msoft-quad-float} option is the default.
12449
12450@item -mno-unaligned-doubles
12451@itemx -munaligned-doubles
12452@opindex mno-unaligned-doubles
12453@opindex munaligned-doubles
12454Assume that doubles have 8 byte alignment. This is the default.
12455
12456With @option{-munaligned-doubles}, GCC assumes that doubles have 8 byte
12457alignment only if they are contained in another type, or if they have an
12458absolute address. Otherwise, it assumes they have 4 byte alignment.
12459Specifying this option avoids some rare compatibility problems with code
12460generated by other compilers. It is not the default because it results
12461in a performance loss, especially for floating point code.
12462
12463@item -mno-faster-structs
12464@itemx -mfaster-structs
12465@opindex mno-faster-structs
12466@opindex mfaster-structs
12467With @option{-mfaster-structs}, the compiler assumes that structures
12468should have 8 byte alignment. This enables the use of pairs of
12469@code{ldd} and @code{std} instructions for copies in structure
12470assignment, in place of twice as many @code{ld} and @code{st} pairs.
12471However, the use of this changed alignment directly violates the SPARC
12472ABI@. Thus, it's intended only for use on targets where the developer
12473acknowledges that their resulting code will not be directly in line with
12474the rules of the ABI@.
12475
12476@item -mimpure-text
12477@opindex mimpure-text
12478@option{-mimpure-text}, used in addition to @option{-shared}, tells
12479the compiler to not pass @option{-z text} to the linker when linking a
12480shared object. Using this option, you can link position-dependent
12481code into a shared object.
12482
12483@option{-mimpure-text} suppresses the ``relocations remain against
12484allocatable but non-writable sections'' linker error message.
12485However, the necessary relocations will trigger copy-on-write, and the
12486shared object is not actually shared across processes. Instead of
12487using @option{-mimpure-text}, you should compile all source code with
12488@option{-fpic} or @option{-fPIC}.
12489
12490This option is only available on SunOS and Solaris.
12491
12492@item -mcpu=@var{cpu_type}
12493@opindex mcpu
12494Set the instruction set, register set, and instruction scheduling parameters
12495for machine type @var{cpu_type}. Supported values for @var{cpu_type} are
12496@samp{v7}, @samp{cypress}, @samp{v8}, @samp{supersparc}, @samp{sparclite},
12497@samp{f930}, @samp{f934}, @samp{hypersparc}, @samp{sparclite86x},
12498@samp{sparclet}, @samp{tsc701}, @samp{v9}, @samp{ultrasparc},
12499@samp{ultrasparc3}, and @samp{niagara}.
12500
12501Default instruction scheduling parameters are used for values that select
12502an architecture and not an implementation. These are @samp{v7}, @samp{v8},
12503@samp{sparclite}, @samp{sparclet}, @samp{v9}.
12504
12505Here is a list of each supported architecture and their supported
12506implementations.
12507
12508@smallexample
12509 v7: cypress
12510 v8: supersparc, hypersparc
12511 sparclite: f930, f934, sparclite86x
12512 sparclet: tsc701
12513 v9: ultrasparc, ultrasparc3, niagara
12514@end smallexample
12515
12516By default (unless configured otherwise), GCC generates code for the V7
12517variant of the SPARC architecture. With @option{-mcpu=cypress}, the compiler
12518additionally optimizes it for the Cypress CY7C602 chip, as used in the
12519SPARCStation/SPARCServer 3xx series. This is also appropriate for the older
12520SPARCStation 1, 2, IPX etc.
12521
12522With @option{-mcpu=v8}, GCC generates code for the V8 variant of the SPARC
12523architecture. The only difference from V7 code is that the compiler emits
12524the integer multiply and integer divide instructions which exist in SPARC-V8
12525but not in SPARC-V7. With @option{-mcpu=supersparc}, the compiler additionally
12526optimizes it for the SuperSPARC chip, as used in the SPARCStation 10, 1000 and
125272000 series.
12528
12529With @option{-mcpu=sparclite}, GCC generates code for the SPARClite variant of
12530the SPARC architecture. This adds the integer multiply, integer divide step
12531and scan (@code{ffs}) instructions which exist in SPARClite but not in SPARC-V7.
12532With @option{-mcpu=f930}, the compiler additionally optimizes it for the
12533Fujitsu MB86930 chip, which is the original SPARClite, with no FPU@. With
12534@option{-mcpu=f934}, the compiler additionally optimizes it for the Fujitsu
12535MB86934 chip, which is the more recent SPARClite with FPU@.
12536
12537With @option{-mcpu=sparclet}, GCC generates code for the SPARClet variant of
12538the SPARC architecture. This adds the integer multiply, multiply/accumulate,
12539integer divide step and scan (@code{ffs}) instructions which exist in SPARClet
12540but not in SPARC-V7. With @option{-mcpu=tsc701}, the compiler additionally
12541optimizes it for the TEMIC SPARClet chip.
12542
12543With @option{-mcpu=v9}, GCC generates code for the V9 variant of the SPARC
12544architecture. This adds 64-bit integer and floating-point move instructions,
125453 additional floating-point condition code registers and conditional move
12546instructions. With @option{-mcpu=ultrasparc}, the compiler additionally
12547optimizes it for the Sun UltraSPARC I/II/IIi chips. With
12548@option{-mcpu=ultrasparc3}, the compiler additionally optimizes it for the
12549Sun UltraSPARC III/III+/IIIi/IIIi+/IV/IV+ chips. With
12550@option{-mcpu=niagara}, the compiler additionally optimizes it for
12551Sun UltraSPARC T1 chips.
12552
12553@item -mtune=@var{cpu_type}
12554@opindex mtune
12555Set the instruction scheduling parameters for machine type
12556@var{cpu_type}, but do not set the instruction set or register set that the
12557option @option{-mcpu=@var{cpu_type}} would.
12558
12559The same values for @option{-mcpu=@var{cpu_type}} can be used for
12560@option{-mtune=@var{cpu_type}}, but the only useful values are those
12561that select a particular cpu implementation. Those are @samp{cypress},
12562@samp{supersparc}, @samp{hypersparc}, @samp{f930}, @samp{f934},
12563@samp{sparclite86x}, @samp{tsc701}, @samp{ultrasparc},
12564@samp{ultrasparc3}, and @samp{niagara}.
12565
12566@item -mv8plus
12567@itemx -mno-v8plus
12568@opindex mv8plus
12569@opindex mno-v8plus
12570With @option{-mv8plus}, GCC generates code for the SPARC-V8+ ABI@. The
12571difference from the V8 ABI is that the global and out registers are
12572considered 64-bit wide. This is enabled by default on Solaris in 32-bit
12573mode for all SPARC-V9 processors.
12574
12575@item -mvis
12576@itemx -mno-vis
12577@opindex mvis
12578@opindex mno-vis
12579With @option{-mvis}, GCC generates code that takes advantage of the UltraSPARC
12580Visual Instruction Set extensions. The default is @option{-mno-vis}.
12581@end table
12582
12583These @samp{-m} options are supported in addition to the above
12584on SPARC-V9 processors in 64-bit environments:
12585
12586@table @gcctabopt
12587@item -mlittle-endian
12588@opindex mlittle-endian
12589Generate code for a processor running in little-endian mode. It is only
12590available for a few configurations and most notably not on Solaris and Linux.
12591
12592@item -m32
12593@itemx -m64
12594@opindex m32
12595@opindex m64
12596Generate code for a 32-bit or 64-bit environment.
12597The 32-bit environment sets int, long and pointer to 32 bits.
12598The 64-bit environment sets int to 32 bits and long and pointer
12599to 64 bits.
12600
12601@item -mcmodel=medlow
12602@opindex mcmodel=medlow
12603Generate code for the Medium/Low code model: 64-bit addresses, programs
12604must be linked in the low 32 bits of memory. Programs can be statically
12605or dynamically linked.
12606
12607@item -mcmodel=medmid
12608@opindex mcmodel=medmid
12609Generate code for the Medium/Middle code model: 64-bit addresses, programs
12610must be linked in the low 44 bits of memory, the text and data segments must
12611be less than 2GB in size and the data segment must be located within 2GB of
12612the text segment.
12613
12614@item -mcmodel=medany
12615@opindex mcmodel=medany
12616Generate code for the Medium/Anywhere code model: 64-bit addresses, programs
12617may be linked anywhere in memory, the text and data segments must be less
12618than 2GB in size and the data segment must be located within 2GB of the
12619text segment.
12620
12621@item -mcmodel=embmedany
12622@opindex mcmodel=embmedany
12623Generate code for the Medium/Anywhere code model for embedded systems:
1262464-bit addresses, the text and data segments must be less than 2GB in
12625size, both starting anywhere in memory (determined at link time). The
12626global register %g4 points to the base of the data segment. Programs
12627are statically linked and PIC is not supported.
12628
12629@item -mstack-bias
12630@itemx -mno-stack-bias
12631@opindex mstack-bias
12632@opindex mno-stack-bias
12633With @option{-mstack-bias}, GCC assumes that the stack pointer, and
12634frame pointer if present, are offset by @minus{}2047 which must be added back
12635when making stack frame references. This is the default in 64-bit mode.
12636Otherwise, assume no such offset is present.
12637@end table
12638
12639These switches are supported in addition to the above on Solaris:
12640
12641@table @gcctabopt
12642@item -threads
12643@opindex threads
12644Add support for multithreading using the Solaris threads library. This
12645option sets flags for both the preprocessor and linker. This option does
12646not affect the thread safety of object code produced by the compiler or
12647that of libraries supplied with it.
12648
12649@item -pthreads
12650@opindex pthreads
12651Add support for multithreading using the POSIX threads library. This
12652option sets flags for both the preprocessor and linker. This option does
12653not affect the thread safety of object code produced by the compiler or
12654that of libraries supplied with it.
12655
12656@item -pthread
12657@opindex pthread
12658This is a synonym for @option{-pthreads}.
12659@end table
12660
12661@node System V Options
12662@subsection Options for System V
12663
12664These additional options are available on System V Release 4 for
12665compatibility with other compilers on those systems:
12666
12667@table @gcctabopt
12668@item -G
12669@opindex G
12670Create a shared object.
12671It is recommended that @option{-symbolic} or @option{-shared} be used instead.
12672
12673@item -Qy
12674@opindex Qy
12675Identify the versions of each tool used by the compiler, in a
12676@code{.ident} assembler directive in the output.
12677
12678@item -Qn
12679@opindex Qn
12680Refrain from adding @code{.ident} directives to the output file (this is
12681the default).
12682
12683@item -YP,@var{dirs}
12684@opindex YP
12685Search the directories @var{dirs}, and no others, for libraries
12686specified with @option{-l}.
12687
12688@item -Ym,@var{dir}
12689@opindex Ym
12690Look in the directory @var{dir} to find the M4 preprocessor.
12691The assembler uses this option.
12692@c This is supposed to go with a -Yd for predefined M4 macro files, but
12693@c the generic assembler that comes with Solaris takes just -Ym.
12694@end table
12695
12696@node TMS320C3x/C4x Options
12697@subsection TMS320C3x/C4x Options
12698@cindex TMS320C3x/C4x Options
12699
12700These @samp{-m} options are defined for TMS320C3x/C4x implementations:
12701
12702@table @gcctabopt
12703
12704@item -mcpu=@var{cpu_type}
12705@opindex mcpu
12706Set the instruction set, register set, and instruction scheduling
12707parameters for machine type @var{cpu_type}. Supported values for
12708@var{cpu_type} are @samp{c30}, @samp{c31}, @samp{c32}, @samp{c40}, and
12709@samp{c44}. The default is @samp{c40} to generate code for the
12710TMS320C40.
12711
12712@item -mbig-memory
12713@itemx -mbig
12714@itemx -msmall-memory
12715@itemx -msmall
12716@opindex mbig-memory
12717@opindex mbig
12718@opindex msmall-memory
12719@opindex msmall
12720Generates code for the big or small memory model. The small memory
12721model assumed that all data fits into one 64K word page. At run-time
12722the data page (DP) register must be set to point to the 64K page
12723containing the .bss and .data program sections. The big memory model is
12724the default and requires reloading of the DP register for every direct
12725memory access.
12726
12727@item -mbk
12728@itemx -mno-bk
12729@opindex mbk
12730@opindex mno-bk
12731Allow (disallow) allocation of general integer operands into the block
12732count register BK@.
12733
12734@item -mdb
12735@itemx -mno-db
12736@opindex mdb
12737@opindex mno-db
12738Enable (disable) generation of code using decrement and branch,
12739DBcond(D), instructions. This is enabled by default for the C4x. To be
12740on the safe side, this is disabled for the C3x, since the maximum
12741iteration count on the C3x is @math{2^{23} + 1} (but who iterates loops more than
12742@math{2^{23}} times on the C3x?). Note that GCC will try to reverse a loop so
12743that it can utilize the decrement and branch instruction, but will give
12744up if there is more than one memory reference in the loop. Thus a loop
12745where the loop counter is decremented can generate slightly more
12746efficient code, in cases where the RPTB instruction cannot be utilized.
12747
12748@item -mdp-isr-reload
12749@itemx -mparanoid
12750@opindex mdp-isr-reload
12751@opindex mparanoid
12752Force the DP register to be saved on entry to an interrupt service
12753routine (ISR), reloaded to point to the data section, and restored on
12754exit from the ISR@. This should not be required unless someone has
12755violated the small memory model by modifying the DP register, say within
12756an object library.
12757
12758@item -mmpyi
12759@itemx -mno-mpyi
12760@opindex mmpyi
12761@opindex mno-mpyi
12762For the C3x use the 24-bit MPYI instruction for integer multiplies
12763instead of a library call to guarantee 32-bit results. Note that if one
12764of the operands is a constant, then the multiplication will be performed
12765using shifts and adds. If the @option{-mmpyi} option is not specified for the C3x,
12766then squaring operations are performed inline instead of a library call.
12767
12768@item -mfast-fix
12769@itemx -mno-fast-fix
12770@opindex mfast-fix
12771@opindex mno-fast-fix
12772The C3x/C4x FIX instruction to convert a floating point value to an
12773integer value chooses the nearest integer less than or equal to the
12774floating point value rather than to the nearest integer. Thus if the
12775floating point number is negative, the result will be incorrectly
12776truncated an additional code is necessary to detect and correct this
12777case. This option can be used to disable generation of the additional
12778code required to correct the result.
12779
12780@item -mrptb
12781@itemx -mno-rptb
12782@opindex mrptb
12783@opindex mno-rptb
12784Enable (disable) generation of repeat block sequences using the RPTB
12785instruction for zero overhead looping. The RPTB construct is only used
12786for innermost loops that do not call functions or jump across the loop
12787boundaries. There is no advantage having nested RPTB loops due to the
12788overhead required to save and restore the RC, RS, and RE registers.
12789This is enabled by default with @option{-O2}.
12790
12791@item -mrpts=@var{count}
12792@itemx -mno-rpts
12793@opindex mrpts
12794@opindex mno-rpts
12795Enable (disable) the use of the single instruction repeat instruction
12796RPTS@. If a repeat block contains a single instruction, and the loop
12797count can be guaranteed to be less than the value @var{count}, GCC will
12798emit a RPTS instruction instead of a RPTB@. If no value is specified,
12799then a RPTS will be emitted even if the loop count cannot be determined
12800at compile time. Note that the repeated instruction following RPTS does
12801not have to be reloaded from memory each iteration, thus freeing up the
12802CPU buses for operands. However, since interrupts are blocked by this
12803instruction, it is disabled by default.
12804
12805@item -mloop-unsigned
12806@itemx -mno-loop-unsigned
12807@opindex mloop-unsigned
12808@opindex mno-loop-unsigned
12809The maximum iteration count when using RPTS and RPTB (and DB on the C40)
12810is @math{2^{31} + 1} since these instructions test if the iteration count is
12811negative to terminate the loop. If the iteration count is unsigned
12812there is a possibility than the @math{2^{31} + 1} maximum iteration count may be
12813exceeded. This switch allows an unsigned iteration count.
12814
12815@item -mti
12816@opindex mti
12817Try to emit an assembler syntax that the TI assembler (asm30) is happy
12818with. This also enforces compatibility with the API employed by the TI
12819C3x C compiler. For example, long doubles are passed as structures
12820rather than in floating point registers.
12821
12822@item -mregparm
12823@itemx -mmemparm
12824@opindex mregparm
12825@opindex mmemparm
12826Generate code that uses registers (stack) for passing arguments to functions.
12827By default, arguments are passed in registers where possible rather
12828than by pushing arguments on to the stack.
12829
12830@item -mparallel-insns
12831@itemx -mno-parallel-insns
12832@opindex mparallel-insns
12833@opindex mno-parallel-insns
12834Allow the generation of parallel instructions. This is enabled by
12835default with @option{-O2}.
12836
12837@item -mparallel-mpy
12838@itemx -mno-parallel-mpy
12839@opindex mparallel-mpy
12840@opindex mno-parallel-mpy
12841Allow the generation of MPY||ADD and MPY||SUB parallel instructions,
12842provided @option{-mparallel-insns} is also specified. These instructions have
12843tight register constraints which can pessimize the code generation
12844of large functions.
12845
12846@end table
12847
12848@node V850 Options
12849@subsection V850 Options
12850@cindex V850 Options
12851
12852These @samp{-m} options are defined for V850 implementations:
12853
12854@table @gcctabopt
12855@item -mlong-calls
12856@itemx -mno-long-calls
12857@opindex mlong-calls
12858@opindex mno-long-calls
12859Treat all calls as being far away (near). If calls are assumed to be
12860far away, the compiler will always load the functions address up into a
12861register, and call indirect through the pointer.
12862
12863@item -mno-ep
12864@itemx -mep
12865@opindex mno-ep
12866@opindex mep
12867Do not optimize (do optimize) basic blocks that use the same index
12868pointer 4 or more times to copy pointer into the @code{ep} register, and
12869use the shorter @code{sld} and @code{sst} instructions. The @option{-mep}
12870option is on by default if you optimize.
12871
12872@item -mno-prolog-function
12873@itemx -mprolog-function
12874@opindex mno-prolog-function
12875@opindex mprolog-function
12876Do not use (do use) external functions to save and restore registers
12877at the prologue and epilogue of a function. The external functions
12878are slower, but use less code space if more than one function saves
12879the same number of registers. The @option{-mprolog-function} option
12880is on by default if you optimize.
12881
12882@item -mspace
12883@opindex mspace
12884Try to make the code as small as possible. At present, this just turns
12885on the @option{-mep} and @option{-mprolog-function} options.
12886
12887@item -mtda=@var{n}
12888@opindex mtda
12889Put static or global variables whose size is @var{n} bytes or less into
12890the tiny data area that register @code{ep} points to. The tiny data
12891area can hold up to 256 bytes in total (128 bytes for byte references).
12892
12893@item -msda=@var{n}
12894@opindex msda
12895Put static or global variables whose size is @var{n} bytes or less into
12896the small data area that register @code{gp} points to. The small data
12897area can hold up to 64 kilobytes.
12898
12899@item -mzda=@var{n}
12900@opindex mzda
12901Put static or global variables whose size is @var{n} bytes or less into
12902the first 32 kilobytes of memory.
12903
12904@item -mv850
12905@opindex mv850
12906Specify that the target processor is the V850.
12907
12908@item -mbig-switch
12909@opindex mbig-switch
12910Generate code suitable for big switch tables. Use this option only if
12911the assembler/linker complain about out of range branches within a switch
12912table.
12913
12914@item -mapp-regs
12915@opindex mapp-regs
12916This option will cause r2 and r5 to be used in the code generated by
12917the compiler. This setting is the default.
12918
12919@item -mno-app-regs
12920@opindex mno-app-regs
12921This option will cause r2 and r5 to be treated as fixed registers.
12922
12923@item -mv850e1
12924@opindex mv850e1
12925Specify that the target processor is the V850E1. The preprocessor
12926constants @samp{__v850e1__} and @samp{__v850e__} will be defined if
12927this option is used.
12928
12929@item -mv850e
12930@opindex mv850e
12931Specify that the target processor is the V850E@. The preprocessor
12932constant @samp{__v850e__} will be defined if this option is used.
12933
12934If neither @option{-mv850} nor @option{-mv850e} nor @option{-mv850e1}
12935are defined then a default target processor will be chosen and the
12936relevant @samp{__v850*__} preprocessor constant will be defined.
12937
12938The preprocessor constants @samp{__v850} and @samp{__v851__} are always
12939defined, regardless of which processor variant is the target.
12940
12941@item -mdisable-callt
12942@opindex mdisable-callt
12943This option will suppress generation of the CALLT instruction for the
12944v850e and v850e1 flavors of the v850 architecture. The default is
12945@option{-mno-disable-callt} which allows the CALLT instruction to be used.
12946
12947@end table
12948
12949@node VAX Options
12950@subsection VAX Options
12951@cindex VAX options
12952
12953These @samp{-m} options are defined for the VAX:
12954
12955@table @gcctabopt
12956@item -munix
12957@opindex munix
12958Do not output certain jump instructions (@code{aobleq} and so on)
12959that the Unix assembler for the VAX cannot handle across long
12960ranges.
12961
12962@item -mgnu
12963@opindex mgnu
12964Do output those jump instructions, on the assumption that you
12965will assemble with the GNU assembler.
12966
12967@item -mg
12968@opindex mg
12969Output code for g-format floating point numbers instead of d-format.
12970@end table
12971
12972@node x86-64 Options
12973@subsection x86-64 Options
12974@cindex x86-64 options
12975
12976These are listed under @xref{i386 and x86-64 Options}.
12977
12978@node Xstormy16 Options
12979@subsection Xstormy16 Options
12980@cindex Xstormy16 Options
12981
12982These options are defined for Xstormy16:
12983
12984@table @gcctabopt
12985@item -msim
12986@opindex msim
12987Choose startup files and linker script suitable for the simulator.
12988@end table
12989
12990@node Xtensa Options
12991@subsection Xtensa Options
12992@cindex Xtensa Options
12993
12994These options are supported for Xtensa targets:
12995
12996@table @gcctabopt
12997@item -mconst16
12998@itemx -mno-const16
12999@opindex mconst16
13000@opindex mno-const16
13001Enable or disable use of @code{CONST16} instructions for loading
13002constant values. The @code{CONST16} instruction is currently not a
13003standard option from Tensilica. When enabled, @code{CONST16}
13004instructions are always used in place of the standard @code{L32R}
13005instructions. The use of @code{CONST16} is enabled by default only if
13006the @code{L32R} instruction is not available.
13007
13008@item -mfused-madd
13009@itemx -mno-fused-madd
13010@opindex mfused-madd
13011@opindex mno-fused-madd
13012Enable or disable use of fused multiply/add and multiply/subtract
13013instructions in the floating-point option. This has no effect if the
13014floating-point option is not also enabled. Disabling fused multiply/add
13015and multiply/subtract instructions forces the compiler to use separate
13016instructions for the multiply and add/subtract operations. This may be
13017desirable in some cases where strict IEEE 754-compliant results are
13018required: the fused multiply add/subtract instructions do not round the
13019intermediate result, thereby producing results with @emph{more} bits of
13020precision than specified by the IEEE standard. Disabling fused multiply
13021add/subtract instructions also ensures that the program output is not
13022sensitive to the compiler's ability to combine multiply and add/subtract
13023operations.
13024
13025@item -mtext-section-literals
13026@itemx -mno-text-section-literals
13027@opindex mtext-section-literals
13028@opindex mno-text-section-literals
13029Control the treatment of literal pools. The default is
13030@option{-mno-text-section-literals}, which places literals in a separate
13031section in the output file. This allows the literal pool to be placed
13032in a data RAM/ROM, and it also allows the linker to combine literal
13033pools from separate object files to remove redundant literals and
13034improve code size. With @option{-mtext-section-literals}, the literals
13035are interspersed in the text section in order to keep them as close as
13036possible to their references. This may be necessary for large assembly
13037files.
13038
13039@item -mtarget-align
13040@itemx -mno-target-align
13041@opindex mtarget-align
13042@opindex mno-target-align
13043When this option is enabled, GCC instructs the assembler to
13044automatically align instructions to reduce branch penalties at the
13045expense of some code density. The assembler attempts to widen density
13046instructions to align branch targets and the instructions following call
13047instructions. If there are not enough preceding safe density
13048instructions to align a target, no widening will be performed. The
13049default is @option{-mtarget-align}. These options do not affect the
13050treatment of auto-aligned instructions like @code{LOOP}, which the
13051assembler will always align, either by widening density instructions or
13052by inserting no-op instructions.
13053
13054@item -mlongcalls
13055@itemx -mno-longcalls
13056@opindex mlongcalls
13057@opindex mno-longcalls
13058When this option is enabled, GCC instructs the assembler to translate
13059direct calls to indirect calls unless it can determine that the target
13060of a direct call is in the range allowed by the call instruction. This
13061translation typically occurs for calls to functions in other source
13062files. Specifically, the assembler translates a direct @code{CALL}
13063instruction into an @code{L32R} followed by a @code{CALLX} instruction.
13064The default is @option{-mno-longcalls}. This option should be used in
13065programs where the call target can potentially be out of range. This
13066option is implemented in the assembler, not the compiler, so the
13067assembly code generated by GCC will still show direct call
13068instructions---look at the disassembled object code to see the actual
13069instructions. Note that the assembler will use an indirect call for
13070every cross-file call, not just those that really will be out of range.
13071@end table
13072
13073@node zSeries Options
13074@subsection zSeries Options
13075@cindex zSeries options
13076
13077These are listed under @xref{S/390 and zSeries Options}.
13078
13079@node Code Gen Options
13080@section Options for Code Generation Conventions
13081@cindex code generation conventions
13082@cindex options, code generation
13083@cindex run-time options
13084
13085These machine-independent options control the interface conventions
13086used in code generation.
13087
13088Most of them have both positive and negative forms; the negative form
13089of @option{-ffoo} would be @option{-fno-foo}. In the table below, only
13090one of the forms is listed---the one which is not the default. You
13091can figure out the other form by either removing @samp{no-} or adding
13092it.
13093
13094@table @gcctabopt
13095@item -fbounds-check
13096@opindex fbounds-check
13097For front-ends that support it, generate additional code to check that
13098indices used to access arrays are within the declared range. This is
13099currently only supported by the Java and Fortran front-ends, where
13100this option defaults to true and false respectively.
13101
13102@item -ftrapv
13103@opindex ftrapv
13104This option generates traps for signed overflow on addition, subtraction,
13105multiplication operations.
13106
13107@item -fwrapv
13108@opindex fwrapv
13109This option instructs the compiler to assume that signed arithmetic
13110overflow of addition, subtraction and multiplication wraps around
13111using twos-complement representation. This flag enables some optimizations
13112and disables others. This option is enabled by default for the Java
13113front-end, as required by the Java language specification.
13114
13115@item -fexceptions
13116@opindex fexceptions
13117Enable exception handling. Generates extra code needed to propagate
13118exceptions. For some targets, this implies GCC will generate frame
13119unwind information for all functions, which can produce significant data
13120size overhead, although it does not affect execution. If you do not
13121specify this option, GCC will enable it by default for languages like
13122C++ which normally require exception handling, and disable it for
13123languages like C that do not normally require it. However, you may need
13124to enable this option when compiling C code that needs to interoperate
13125properly with exception handlers written in C++. You may also wish to
13126disable this option if you are compiling older C++ programs that don't
13127use exception handling.
13128
13129@item -fnon-call-exceptions
13130@opindex fnon-call-exceptions
13131Generate code that allows trapping instructions to throw exceptions.
13132Note that this requires platform-specific runtime support that does
13133not exist everywhere. Moreover, it only allows @emph{trapping}
13134instructions to throw exceptions, i.e.@: memory references or floating
13135point instructions. It does not allow exceptions to be thrown from
13136arbitrary signal handlers such as @code{SIGALRM}.
13137
13138@item -funwind-tables
13139@opindex funwind-tables
13140Similar to @option{-fexceptions}, except that it will just generate any needed
13141static data, but will not affect the generated code in any other way.
13142You will normally not enable this option; instead, a language processor
13143that needs this handling would enable it on your behalf.
13144
13145@item -fasynchronous-unwind-tables
13146@opindex fasynchronous-unwind-tables
13147Generate unwind table in dwarf2 format, if supported by target machine. The
13148table is exact at each instruction boundary, so it can be used for stack
13149unwinding from asynchronous events (such as debugger or garbage collector).
13150
13151@item -fpcc-struct-return
13152@opindex fpcc-struct-return
13153Return ``short'' @code{struct} and @code{union} values in memory like
13154longer ones, rather than in registers. This convention is less
13155efficient, but it has the advantage of allowing intercallability between
13156GCC-compiled files and files compiled with other compilers, particularly
13157the Portable C Compiler (pcc).
13158
13159The precise convention for returning structures in memory depends
13160on the target configuration macros.
13161
13162Short structures and unions are those whose size and alignment match
13163that of some integer type.
13164
13165@strong{Warning:} code compiled with the @option{-fpcc-struct-return}
13166switch is not binary compatible with code compiled with the
13167@option{-freg-struct-return} switch.
13168Use it to conform to a non-default application binary interface.
13169
13170@item -freg-struct-return
13171@opindex freg-struct-return
13172Return @code{struct} and @code{union} values in registers when possible.
13173This is more efficient for small structures than
13174@option{-fpcc-struct-return}.
13175
13176If you specify neither @option{-fpcc-struct-return} nor
13177@option{-freg-struct-return}, GCC defaults to whichever convention is
13178standard for the target. If there is no standard convention, GCC
13179defaults to @option{-fpcc-struct-return}, except on targets where GCC is
13180the principal compiler. In those cases, we can choose the standard, and
13181we chose the more efficient register return alternative.
13182
13183@strong{Warning:} code compiled with the @option{-freg-struct-return}
13184switch is not binary compatible with code compiled with the
13185@option{-fpcc-struct-return} switch.
13186Use it to conform to a non-default application binary interface.
13187
13188@item -fshort-enums
13189@opindex fshort-enums
13190Allocate to an @code{enum} type only as many bytes as it needs for the
13191declared range of possible values. Specifically, the @code{enum} type
13192will be equivalent to the smallest integer type which has enough room.
13193
13194@strong{Warning:} the @option{-fshort-enums} switch causes GCC to generate
13195code that is not binary compatible with code generated without that switch.
13196Use it to conform to a non-default application binary interface.
13197
13198@item -fshort-double
13199@opindex fshort-double
13200Use the same size for @code{double} as for @code{float}.
13201
13202@strong{Warning:} the @option{-fshort-double} switch causes GCC to generate
13203code that is not binary compatible with code generated without that switch.
13204Use it to conform to a non-default application binary interface.
13205
13206@item -fshort-wchar
13207@opindex fshort-wchar
13208Override the underlying type for @samp{wchar_t} to be @samp{short
13209unsigned int} instead of the default for the target. This option is
13210useful for building programs to run under WINE@.
13211
13212@strong{Warning:} the @option{-fshort-wchar} switch causes GCC to generate
13213code that is not binary compatible with code generated without that switch.
13214Use it to conform to a non-default application binary interface.
13215
13216@item -fno-common
13217@opindex fno-common
13218In C, allocate even uninitialized global variables in the data section of the
13219object file, rather than generating them as common blocks. This has the
13220effect that if the same variable is declared (without @code{extern}) in
13221two different compilations, you will get an error when you link them.
13222The only reason this might be useful is if you wish to verify that the
13223program will work on other systems which always work this way.
13224
13225@item -fno-ident
13226@opindex fno-ident
13227Ignore the @samp{#ident} directive.
13228
13229@item -finhibit-size-directive
13230@opindex finhibit-size-directive
13231Don't output a @code{.size} assembler directive, or anything else that
13232would cause trouble if the function is split in the middle, and the
13233two halves are placed at locations far apart in memory. This option is
13234used when compiling @file{crtstuff.c}; you should not need to use it
13235for anything else.
13236
13237@item -fverbose-asm
13238@opindex fverbose-asm
13239Put extra commentary information in the generated assembly code to
13240make it more readable. This option is generally only of use to those
13241who actually need to read the generated assembly code (perhaps while
13242debugging the compiler itself).
13243
13244@option{-fno-verbose-asm}, the default, causes the
13245extra information to be omitted and is useful when comparing two assembler
13246files.
13247
13248@item -fpic
13249@opindex fpic
13250@cindex global offset table
13251@cindex PIC
13252Generate position-independent code (PIC) suitable for use in a shared
13253library, if supported for the target machine. Such code accesses all
13254constant addresses through a global offset table (GOT)@. The dynamic
13255loader resolves the GOT entries when the program starts (the dynamic
13256loader is not part of GCC; it is part of the operating system). If
13257the GOT size for the linked executable exceeds a machine-specific
13258maximum size, you get an error message from the linker indicating that
13259@option{-fpic} does not work; in that case, recompile with @option{-fPIC}
13260instead. (These maximums are 8k on the SPARC and 32k
13261on the m68k and RS/6000. The 386 has no such limit.)
13262
13263Position-independent code requires special support, and therefore works
13264only on certain machines. For the 386, GCC supports PIC for System V
13265but not for the Sun 386i. Code generated for the IBM RS/6000 is always
13266position-independent.
13267
13268When this flag is set, the macros @code{__pic__} and @code{__PIC__}
13269are defined to 1.
13270
13271@item -fPIC
13272@opindex fPIC
13273If supported for the target machine, emit position-independent code,
13274suitable for dynamic linking and avoiding any limit on the size of the
13275global offset table. This option makes a difference on the m68k,
13276PowerPC and SPARC@.
13277
13278Position-independent code requires special support, and therefore works
13279only on certain machines.
13280
13281When this flag is set, the macros @code{__pic__} and @code{__PIC__}
13282are defined to 2.
13283
13284@item -fpie
13285@itemx -fPIE
13286@opindex fpie
13287@opindex fPIE
13288These options are similar to @option{-fpic} and @option{-fPIC}, but
13289generated position independent code can be only linked into executables.
13290Usually these options are used when @option{-pie} GCC option will be
13291used during linking.
13292
13293@item -fno-jump-tables
13294@opindex fno-jump-tables
13295Do not use jump tables for switch statements even where it would be
13296more efficient than other code generation strategies. This option is
13297of use in conjunction with @option{-fpic} or @option{-fPIC} for
13298building code which forms part of a dynamic linker and cannot
13299reference the address of a jump table. On some targets, jump tables
13300do not require a GOT and this option is not needed.
13301
13302@item -ffixed-@var{reg}
13303@opindex ffixed
13304Treat the register named @var{reg} as a fixed register; generated code
13305should never refer to it (except perhaps as a stack pointer, frame
13306pointer or in some other fixed role).
13307
13308@var{reg} must be the name of a register. The register names accepted
13309are machine-specific and are defined in the @code{REGISTER_NAMES}
13310macro in the machine description macro file.
13311
13312This flag does not have a negative form, because it specifies a
13313three-way choice.
13314
13315@item -fcall-used-@var{reg}
13316@opindex fcall-used
13317Treat the register named @var{reg} as an allocable register that is
13318clobbered by function calls. It may be allocated for temporaries or
13319variables that do not live across a call. Functions compiled this way
13320will not save and restore the register @var{reg}.
13321
13322It is an error to used this flag with the frame pointer or stack pointer.
13323Use of this flag for other registers that have fixed pervasive roles in
13324the machine's execution model will produce disastrous results.
13325
13326This flag does not have a negative form, because it specifies a
13327three-way choice.
13328
13329@item -fcall-saved-@var{reg}
13330@opindex fcall-saved
13331Treat the register named @var{reg} as an allocable register saved by
13332functions. It may be allocated even for temporaries or variables that
13333live across a call. Functions compiled this way will save and restore
13334the register @var{reg} if they use it.
13335
13336It is an error to used this flag with the frame pointer or stack pointer.
13337Use of this flag for other registers that have fixed pervasive roles in
13338the machine's execution model will produce disastrous results.
13339
13340A different sort of disaster will result from the use of this flag for
13341a register in which function values may be returned.
13342
13343This flag does not have a negative form, because it specifies a
13344three-way choice.
13345
13346@item -fpack-struct[=@var{n}]
13347@opindex fpack-struct
13348Without a value specified, pack all structure members together without
13349holes. When a value is specified (which must be a small power of two), pack
13350structure members according to this value, representing the maximum
13351alignment (that is, objects with default alignment requirements larger than
13352this will be output potentially unaligned at the next fitting location.
13353
13354@strong{Warning:} the @option{-fpack-struct} switch causes GCC to generate
13355code that is not binary compatible with code generated without that switch.
13356Additionally, it makes the code suboptimal.
13357Use it to conform to a non-default application binary interface.
13358
13359@item -finstrument-functions
13360@opindex finstrument-functions
13361Generate instrumentation calls for entry and exit to functions. Just
13362after function entry and just before function exit, the following
13363profiling functions will be called with the address of the current
13364function and its call site. (On some platforms,
13365@code{__builtin_return_address} does not work beyond the current
13366function, so the call site information may not be available to the
13367profiling functions otherwise.)
13368
13369@smallexample
13370void __cyg_profile_func_enter (void *this_fn,
13371 void *call_site);
13372void __cyg_profile_func_exit (void *this_fn,
13373 void *call_site);
13374@end smallexample
13375
13376The first argument is the address of the start of the current function,
13377which may be looked up exactly in the symbol table.
13378
13379This instrumentation is also done for functions expanded inline in other
13380functions. The profiling calls will indicate where, conceptually, the
13381inline function is entered and exited. This means that addressable
13382versions of such functions must be available. If all your uses of a
13383function are expanded inline, this may mean an additional expansion of
13384code size. If you use @samp{extern inline} in your C code, an
13385addressable version of such functions must be provided. (This is
13386normally the case anyways, but if you get lucky and the optimizer always
13387expands the functions inline, you might have gotten away without
13388providing static copies.)
13389
13390A function may be given the attribute @code{no_instrument_function}, in
13391which case this instrumentation will not be done. This can be used, for
13392example, for the profiling functions listed above, high-priority
13393interrupt routines, and any functions from which the profiling functions
13394cannot safely be called (perhaps signal handlers, if the profiling
13395routines generate output or allocate memory).
13396
13397@item -finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{}
13398@opindex finstrument-functions-exclude-file-list
13399
13400Set the list of functions that are excluded from instrumentation (see
13401the description of @code{-finstrument-functions}). If the file that
13402contains a function definition matches with one of @var{file}, then
13403that function is not instrumented. The match is done on substrings:
13404if the @var{file} parameter is a substring of the file name, it is
13405considered to be a match.
13406
13407For example,
13408@code{-finstrument-functions-exclude-file-list=/bits/stl,include/sys}
13409will exclude any inline function defined in files whose pathnames
13410contain @code{/bits/stl} or @code{include/sys}.
13411
13412If, for some reason, you want to include letter @code{','} in one of
13413@var{sym}, write @code{'\,'}. For example,
13414@code{-finstrument-functions-exclude-file-list='\,\,tmp'}
13415(note the single quote surrounding the option).
13416
13417@item -finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{}
13418@opindex finstrument-functions-exclude-function-list
13419
13420This is similar to @code{-finstrument-functions-exclude-file-list},
13421but this option sets the list of function names to be excluded from
13422instrumentation. The function name to be matched is its user-visible
13423name, such as @code{vector<int> blah(const vector<int> &)}, not the
13424internal mangled name (e.g., @code{_Z4blahRSt6vectorIiSaIiEE}). The
13425match is done on substrings: if the @var{sym} parameter is a substring
13426of the function name, it is considered to be a match.
13427
13428@item -fstack-check
13429@opindex fstack-check
13430Generate code to verify that you do not go beyond the boundary of the
13431stack. You should specify this flag if you are running in an
13432environment with multiple threads, but only rarely need to specify it in
13433a single-threaded environment since stack overflow is automatically
13434detected on nearly all systems if there is only one stack.
13435
13436Note that this switch does not actually cause checking to be done; the
13437operating system must do that. The switch causes generation of code
13438to ensure that the operating system sees the stack being extended.
13439
13440@item -fstack-limit-register=@var{reg}
13441@itemx -fstack-limit-symbol=@var{sym}
13442@itemx -fno-stack-limit
13443@opindex fstack-limit-register
13444@opindex fstack-limit-symbol
13445@opindex fno-stack-limit
13446Generate code to ensure that the stack does not grow beyond a certain value,
13447either the value of a register or the address of a symbol. If the stack
13448would grow beyond the value, a signal is raised. For most targets,
13449the signal is raised before the stack overruns the boundary, so
13450it is possible to catch the signal without taking special precautions.
13451
13452For instance, if the stack starts at absolute address @samp{0x80000000}
13453and grows downwards, you can use the flags
13454@option{-fstack-limit-symbol=__stack_limit} and
13455@option{-Wl,--defsym,__stack_limit=0x7ffe0000} to enforce a stack limit
13456of 128KB@. Note that this may only work with the GNU linker.
13457
13458@cindex aliasing of parameters
13459@cindex parameters, aliased
13460@item -fargument-alias
13461@itemx -fargument-noalias
13462@itemx -fargument-noalias-global
13463@itemx -fargument-noalias-anything
13464@opindex fargument-alias
13465@opindex fargument-noalias
13466@opindex fargument-noalias-global
13467@opindex fargument-noalias-anything
13468Specify the possible relationships among parameters and between
13469parameters and global data.
13470
13471@option{-fargument-alias} specifies that arguments (parameters) may
13472alias each other and may alias global storage.@*
13473@option{-fargument-noalias} specifies that arguments do not alias
13474each other, but may alias global storage.@*
13475@option{-fargument-noalias-global} specifies that arguments do not
13476alias each other and do not alias global storage.
13477@option{-fargument-noalias-anything} specifies that arguments do not
13478alias any other storage.
13479
13480Each language will automatically use whatever option is required by
13481the language standard. You should not need to use these options yourself.
13482
13483@item -fleading-underscore
13484@opindex fleading-underscore
13485This option and its counterpart, @option{-fno-leading-underscore}, forcibly
13486change the way C symbols are represented in the object file. One use
13487is to help link with legacy assembly code.
13488
13489@strong{Warning:} the @option{-fleading-underscore} switch causes GCC to
13490generate code that is not binary compatible with code generated without that
13491switch. Use it to conform to a non-default application binary interface.
13492Not all targets provide complete support for this switch.
13493
13494@item -ftls-model=@var{model}
13495Alter the thread-local storage model to be used (@pxref{Thread-Local}).
13496The @var{model} argument should be one of @code{global-dynamic},
13497@code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
13498
13499The default without @option{-fpic} is @code{initial-exec}; with
13500@option{-fpic} the default is @code{global-dynamic}.
13501
13502@item -fvisibility=@var{default|internal|hidden|protected}
13503@opindex fvisibility
13504Set the default ELF image symbol visibility to the specified option---all
13505symbols will be marked with this unless overridden within the code.
13506Using this feature can very substantially improve linking and
13507load times of shared object libraries, produce more optimized
13508code, provide near-perfect API export and prevent symbol clashes.
13509It is @strong{strongly} recommended that you use this in any shared objects
13510you distribute.
13511
13512Despite the nomenclature, @code{default} always means public ie;
13513available to be linked against from outside the shared object.
13514@code{protected} and @code{internal} are pretty useless in real-world
13515usage so the only other commonly used option will be @code{hidden}.
13516The default if @option{-fvisibility} isn't specified is
13517@code{default}, i.e., make every
13518symbol public---this causes the same behavior as previous versions of
13519GCC@.
13520
13521A good explanation of the benefits offered by ensuring ELF
13522symbols have the correct visibility is given by ``How To Write
13523Shared Libraries'' by Ulrich Drepper (which can be found at
13524@w{@uref{http://people.redhat.com/~drepper/}})---however a superior
13525solution made possible by this option to marking things hidden when
13526the default is public is to make the default hidden and mark things
13527public. This is the norm with DLL's on Windows and with @option{-fvisibility=hidden}
13528and @code{__attribute__ ((visibility("default")))} instead of
13529@code{__declspec(dllexport)} you get almost identical semantics with
13530identical syntax. This is a great boon to those working with
13531cross-platform projects.
13532
13533For those adding visibility support to existing code, you may find
13534@samp{#pragma GCC visibility} of use. This works by you enclosing
13535the declarations you wish to set visibility for with (for example)
13536@samp{#pragma GCC visibility push(hidden)} and
13537@samp{#pragma GCC visibility pop}.
13538Bear in mind that symbol visibility should be viewed @strong{as
13539part of the API interface contract} and thus all new code should
13540always specify visibility when it is not the default ie; declarations
13541only for use within the local DSO should @strong{always} be marked explicitly
13542as hidden as so to avoid PLT indirection overheads---making this
13543abundantly clear also aids readability and self-documentation of the code.
13544Note that due to ISO C++ specification requirements, operator new and
13545operator delete must always be of default visibility.
13546
13547Be aware that headers from outside your project, in particular system
13548headers and headers from any other library you use, may not be
13549expecting to be compiled with visibility other than the default. You
13550may need to explicitly say @samp{#pragma GCC visibility push(default)}
13551before including any such headers.
13552
13553@samp{extern} declarations are not affected by @samp{-fvisibility}, so
13554a lot of code can be recompiled with @samp{-fvisibility=hidden} with
13555no modifications. However, this means that calls to @samp{extern}
13556functions with no explicit visibility will use the PLT, so it is more
13557effective to use @samp{__attribute ((visibility))} and/or
13558@samp{#pragma GCC visibility} to tell the compiler which @samp{extern}
13559declarations should be treated as hidden.
13560
13561Note that @samp{-fvisibility} does affect C++ vague linkage
13562entities. This means that, for instance, an exception class that will
13563be thrown between DSOs must be explicitly marked with default
13564visibility so that the @samp{type_info} nodes will be unified between
13565the DSOs.
13566
13567An overview of these techniques, their benefits and how to use them
13568is at @w{@uref{http://gcc.gnu.org/wiki/Visibility}}.
13569
13570@end table
13571
13572@c man end
13573
13574@node Environment Variables
13575@section Environment Variables Affecting GCC
13576@cindex environment variables
13577
13578@c man begin ENVIRONMENT
13579This section describes several environment variables that affect how GCC
13580operates. Some of them work by specifying directories or prefixes to use
13581when searching for various kinds of files. Some are used to specify other
13582aspects of the compilation environment.
13583
13584Note that you can also specify places to search using options such as
13585@option{-B}, @option{-I} and @option{-L} (@pxref{Directory Options}). These
13586take precedence over places specified using environment variables, which
13587in turn take precedence over those specified by the configuration of GCC@.
13588@xref{Driver,, Controlling the Compilation Driver @file{gcc}, gccint,
13589GNU Compiler Collection (GCC) Internals}.
13590
13591@table @env
13592@item LANG
13593@itemx LC_CTYPE
13594@c @itemx LC_COLLATE
13595@itemx LC_MESSAGES
13596@c @itemx LC_MONETARY
13597@c @itemx LC_NUMERIC
13598@c @itemx LC_TIME
13599@itemx LC_ALL
13600@findex LANG
13601@findex LC_CTYPE
13602@c @findex LC_COLLATE
13603@findex LC_MESSAGES
13604@c @findex LC_MONETARY
13605@c @findex LC_NUMERIC
13606@c @findex LC_TIME
13607@findex LC_ALL
13608@cindex locale
13609These environment variables control the way that GCC uses
13610localization information that allow GCC to work with different
13611national conventions. GCC inspects the locale categories
13612@env{LC_CTYPE} and @env{LC_MESSAGES} if it has been configured to do
13613so. These locale categories can be set to any value supported by your
13614installation. A typical value is @samp{en_GB.UTF-8} for English in the United
13615Kingdom encoded in UTF-8.
13616
13617The @env{LC_CTYPE} environment variable specifies character
13618classification. GCC uses it to determine the character boundaries in
13619a string; this is needed for some multibyte encodings that contain quote
13620and escape characters that would otherwise be interpreted as a string
13621end or escape.
13622
13623The @env{LC_MESSAGES} environment variable specifies the language to
13624use in diagnostic messages.
13625
13626If the @env{LC_ALL} environment variable is set, it overrides the value
13627of @env{LC_CTYPE} and @env{LC_MESSAGES}; otherwise, @env{LC_CTYPE}
13628and @env{LC_MESSAGES} default to the value of the @env{LANG}
13629environment variable. If none of these variables are set, GCC
13630defaults to traditional C English behavior.
13631
13632@item TMPDIR
13633@findex TMPDIR
13634If @env{TMPDIR} is set, it specifies the directory to use for temporary
13635files. GCC uses temporary files to hold the output of one stage of
13636compilation which is to be used as input to the next stage: for example,
13637the output of the preprocessor, which is the input to the compiler
13638proper.
13639
13640@item GCC_EXEC_PREFIX
13641@findex GCC_EXEC_PREFIX
13642If @env{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the
13643names of the subprograms executed by the compiler. No slash is added
13644when this prefix is combined with the name of a subprogram, but you can
13645specify a prefix that ends with a slash if you wish.
13646
13647If @env{GCC_EXEC_PREFIX} is not set, GCC will attempt to figure out
13648an appropriate prefix to use based on the pathname it was invoked with.
13649
13650If GCC cannot find the subprogram using the specified prefix, it
13651tries looking in the usual places for the subprogram.
13652
13653The default value of @env{GCC_EXEC_PREFIX} is
13654@file{@var{prefix}/lib/gcc/} where @var{prefix} is the value
13655of @code{prefix} when you ran the @file{configure} script.
13656
13657Other prefixes specified with @option{-B} take precedence over this prefix.
13658
13659This prefix is also used for finding files such as @file{crt0.o} that are
13660used for linking.
13661
13662In addition, the prefix is used in an unusual way in finding the
13663directories to search for header files. For each of the standard
13664directories whose name normally begins with @samp{/usr/local/lib/gcc}
13665(more precisely, with the value of @env{GCC_INCLUDE_DIR}), GCC tries
13666replacing that beginning with the specified prefix to produce an
13667alternate directory name. Thus, with @option{-Bfoo/}, GCC will search
13668@file{foo/bar} where it would normally search @file{/usr/local/lib/bar}.
13669These alternate directories are searched first; the standard directories
13670come next.
13671
13672@item COMPILER_PATH
13673@findex COMPILER_PATH
13674The value of @env{COMPILER_PATH} is a colon-separated list of
13675directories, much like @env{PATH}. GCC tries the directories thus
13676specified when searching for subprograms, if it can't find the
13677subprograms using @env{GCC_EXEC_PREFIX}.
13678
13679@item LIBRARY_PATH
13680@findex LIBRARY_PATH
13681The value of @env{LIBRARY_PATH} is a colon-separated list of
13682directories, much like @env{PATH}. When configured as a native compiler,
13683GCC tries the directories thus specified when searching for special
13684linker files, if it can't find them using @env{GCC_EXEC_PREFIX}. Linking
13685using GCC also uses these directories when searching for ordinary
13686libraries for the @option{-l} option (but directories specified with
13687@option{-L} come first).
13688
13689@item LANG
13690@findex LANG
13691@cindex locale definition
13692This variable is used to pass locale information to the compiler. One way in
13693which this information is used is to determine the character set to be used
13694when character literals, string literals and comments are parsed in C and C++.
13695When the compiler is configured to allow multibyte characters,
13696the following values for @env{LANG} are recognized:
13697
13698@table @samp
13699@item C-JIS
13700Recognize JIS characters.
13701@item C-SJIS
13702Recognize SJIS characters.
13703@item C-EUCJP
13704Recognize EUCJP characters.
13705@end table
13706
13707If @env{LANG} is not defined, or if it has some other value, then the
13708compiler will use mblen and mbtowc as defined by the default locale to
13709recognize and translate multibyte characters.
13710@end table
13711
13712@noindent
13713Some additional environments variables affect the behavior of the
13714preprocessor.
13715
13716@include cppenv.texi
13717
13718@c man end
13719
13720@node Precompiled Headers
13721@section Using Precompiled Headers
13722@cindex precompiled headers
13723@cindex speed of compilation
13724
13725Often large projects have many header files that are included in every
13726source file. The time the compiler takes to process these header files
13727over and over again can account for nearly all of the time required to
13728build the project. To make builds faster, GCC allows users to
13729`precompile' a header file; then, if builds can use the precompiled
13730header file they will be much faster.
13731
13732To create a precompiled header file, simply compile it as you would any
13733other file, if necessary using the @option{-x} option to make the driver
13734treat it as a C or C++ header file. You will probably want to use a
13735tool like @command{make} to keep the precompiled header up-to-date when
13736the headers it contains change.
13737
13738A precompiled header file will be searched for when @code{#include} is
13739seen in the compilation. As it searches for the included file
13740(@pxref{Search Path,,Search Path,cpp,The C Preprocessor}) the
13741compiler looks for a precompiled header in each directory just before it
13742looks for the include file in that directory. The name searched for is
13743the name specified in the @code{#include} with @samp{.gch} appended. If
13744the precompiled header file can't be used, it is ignored.
13745
13746For instance, if you have @code{#include "all.h"}, and you have
13747@file{all.h.gch} in the same directory as @file{all.h}, then the
13748precompiled header file will be used if possible, and the original
13749header will be used otherwise.
13750
13751Alternatively, you might decide to put the precompiled header file in a
13752directory and use @option{-I} to ensure that directory is searched
13753before (or instead of) the directory containing the original header.
13754Then, if you want to check that the precompiled header file is always
13755used, you can put a file of the same name as the original header in this
13756directory containing an @code{#error} command.
13757
13758This also works with @option{-include}. So yet another way to use
13759precompiled headers, good for projects not designed with precompiled
13760header files in mind, is to simply take most of the header files used by
13761a project, include them from another header file, precompile that header
13762file, and @option{-include} the precompiled header. If the header files
13763have guards against multiple inclusion, they will be skipped because
13764they've already been included (in the precompiled header).
13765
13766If you need to precompile the same header file for different
13767languages, targets, or compiler options, you can instead make a
13768@emph{directory} named like @file{all.h.gch}, and put each precompiled
13769header in the directory, perhaps using @option{-o}. It doesn't matter
13770what you call the files in the directory, every precompiled header in
13771the directory will be considered. The first precompiled header
13772encountered in the directory that is valid for this compilation will
13773be used; they're searched in no particular order.
13774
13775There are many other possibilities, limited only by your imagination,
13776good sense, and the constraints of your build system.
13777
13778A precompiled header file can be used only when these conditions apply:
13779
13780@itemize
13781@item
13782Only one precompiled header can be used in a particular compilation.
13783
13784@item
13785A precompiled header can't be used once the first C token is seen. You
13786can have preprocessor directives before a precompiled header; you can
13787even include a precompiled header from inside another header, so long as
13788there are no C tokens before the @code{#include}.
13789
13790@item
13791The precompiled header file must be produced for the same language as
13792the current compilation. You can't use a C precompiled header for a C++
13793compilation.
13794
13795@item
13796The precompiled header file must have been produced by the same compiler
13797binary as the current compilation is using.
13798
13799@item
13800Any macros defined before the precompiled header is included must
13801either be defined in the same way as when the precompiled header was
13802generated, or must not affect the precompiled header, which usually
13803means that they don't appear in the precompiled header at all.
13804
13805The @option{-D} option is one way to define a macro before a
13806precompiled header is included; using a @code{#define} can also do it.
13807There are also some options that define macros implicitly, like
13808@option{-O} and @option{-Wdeprecated}; the same rule applies to macros
13809defined this way.
13810
13811@item If debugging information is output when using the precompiled
13812header, using @option{-g} or similar, the same kind of debugging information
13813must have been output when building the precompiled header. However,
13814a precompiled header built using @option{-g} can be used in a compilation
13815when no debugging information is being output.
13816
13817@item The same @option{-m} options must generally be used when building
13818and using the precompiled header. @xref{Submodel Options},
13819for any cases where this rule is relaxed.
13820
13821@item Each of the following options must be the same when building and using
13822the precompiled header:
13823
13824@gccoptlist{-fexceptions -funit-at-a-time}
13825
13826@item
13827Some other command-line options starting with @option{-f},
13828@option{-p}, or @option{-O} must be defined in the same way as when
13829the precompiled header was generated. At present, it's not clear
13830which options are safe to change and which are not; the safest choice
13831is to use exactly the same options when generating and using the
13832precompiled header. The following are known to be safe:
13833
13834@gccoptlist{-fmessage-length= -fpreprocessed
13835-fsched-interblock -fsched-spec -fsched-spec-load -fsched-spec-load-dangerous
13836-fsched-verbose=<number> -fschedule-insns -fvisibility=
13837-pedantic-errors}
13838
13839@end itemize
13840
13841For all of these except the last, the compiler will automatically
13842ignore the precompiled header if the conditions aren't met. If you
13843find an option combination that doesn't work and doesn't cause the
13844precompiled header to be ignored, please consider filing a bug report,
13845see @ref{Bugs}.
13846
13847If you do use differing options when generating and using the
13848precompiled header, the actual behavior will be a mixture of the
13849behavior for the options. For instance, if you use @option{-g} to
13850generate the precompiled header but not when using it, you may or may
13851not get debugging information for routines in the precompiled header.
13852
13853@node Running Protoize
13854@section Running Protoize
13855
13856The program @code{protoize} is an optional part of GCC@. You can use
13857it to add prototypes to a program, thus converting the program to ISO
13858C in one respect. The companion program @code{unprotoize} does the
13859reverse: it removes argument types from any prototypes that are found.
13860
13861When you run these programs, you must specify a set of source files as
13862command line arguments. The conversion programs start out by compiling
13863these files to see what functions they define. The information gathered
13864about a file @var{foo} is saved in a file named @file{@var{foo}.X}.
13865
13866After scanning comes actual conversion. The specified files are all
13867eligible to be converted; any files they include (whether sources or
13868just headers) are eligible as well.
13869
13870But not all the eligible files are converted. By default,
13871@code{protoize} and @code{unprotoize} convert only source and header
13872files in the current directory. You can specify additional directories
13873whose files should be converted with the @option{-d @var{directory}}
13874option. You can also specify particular files to exclude with the
13875@option{-x @var{file}} option. A file is converted if it is eligible, its
13876directory name matches one of the specified directory names, and its
13877name within the directory has not been excluded.
13878
13879Basic conversion with @code{protoize} consists of rewriting most
13880function definitions and function declarations to specify the types of
13881the arguments. The only ones not rewritten are those for varargs
13882functions.
13883
13884@code{protoize} optionally inserts prototype declarations at the
13885beginning of the source file, to make them available for any calls that
13886precede the function's definition. Or it can insert prototype
13887declarations with block scope in the blocks where undeclared functions
13888are called.
13889
13890Basic conversion with @code{unprotoize} consists of rewriting most
13891function declarations to remove any argument types, and rewriting
13892function definitions to the old-style pre-ISO form.
13893
13894Both conversion programs print a warning for any function declaration or
13895definition that they can't convert. You can suppress these warnings
13896with @option{-q}.
13897
13898The output from @code{protoize} or @code{unprotoize} replaces the
13899original source file. The original file is renamed to a name ending
13900with @samp{.save} (for DOS, the saved filename ends in @samp{.sav}
13901without the original @samp{.c} suffix). If the @samp{.save} (@samp{.sav}
13902for DOS) file already exists, then the source file is simply discarded.
13903
13904@code{protoize} and @code{unprotoize} both depend on GCC itself to
13905scan the program and collect information about the functions it uses.
13906So neither of these programs will work until GCC is installed.
13907
13908Here is a table of the options you can use with @code{protoize} and
13909@code{unprotoize}. Each option works with both programs unless
13910otherwise stated.
13911
13912@table @code
13913@item -B @var{directory}
13914Look for the file @file{SYSCALLS.c.X} in @var{directory}, instead of the
13915usual directory (normally @file{/usr/local/lib}). This file contains
13916prototype information about standard system functions. This option
13917applies only to @code{protoize}.
13918
13919@item -c @var{compilation-options}
13920Use @var{compilation-options} as the options when running @command{gcc} to
13921produce the @samp{.X} files. The special option @option{-aux-info} is
13922always passed in addition, to tell @command{gcc} to write a @samp{.X} file.
13923
13924Note that the compilation options must be given as a single argument to
13925@code{protoize} or @code{unprotoize}. If you want to specify several
13926@command{gcc} options, you must quote the entire set of compilation options
13927to make them a single word in the shell.
13928
13929There are certain @command{gcc} arguments that you cannot use, because they
13930would produce the wrong kind of output. These include @option{-g},
13931@option{-O}, @option{-c}, @option{-S}, and @option{-o} If you include these in
13932the @var{compilation-options}, they are ignored.
13933
13934@item -C
13935Rename files to end in @samp{.C} (@samp{.cc} for DOS-based file
13936systems) instead of @samp{.c}. This is convenient if you are converting
13937a C program to C++. This option applies only to @code{protoize}.
13938
13939@item -g
13940Add explicit global declarations. This means inserting explicit
13941declarations at the beginning of each source file for each function
13942that is called in the file and was not declared. These declarations
13943precede the first function definition that contains a call to an
13944undeclared function. This option applies only to @code{protoize}.
13945
13946@item -i @var{string}
13947Indent old-style parameter declarations with the string @var{string}.
13948This option applies only to @code{protoize}.
13949
13950@code{unprotoize} converts prototyped function definitions to old-style
13951function definitions, where the arguments are declared between the
13952argument list and the initial @samp{@{}. By default, @code{unprotoize}
13953uses five spaces as the indentation. If you want to indent with just
13954one space instead, use @option{-i " "}.
13955
13956@item -k
13957Keep the @samp{.X} files. Normally, they are deleted after conversion
13958is finished.
13959
13960@item -l
13961Add explicit local declarations. @code{protoize} with @option{-l} inserts
13962a prototype declaration for each function in each block which calls the
13963function without any declaration. This option applies only to
13964@code{protoize}.
13965
13966@item -n
13967Make no real changes. This mode just prints information about the conversions
13968that would have been done without @option{-n}.
13969
13970@item -N
13971Make no @samp{.save} files. The original files are simply deleted.
13972Use this option with caution.
13973
13974@item -p @var{program}
13975Use the program @var{program} as the compiler. Normally, the name
13976@file{gcc} is used.
13977
13978@item -q
13979Work quietly. Most warnings are suppressed.
13980
13981@item -v
13982Print the version number, just like @option{-v} for @command{gcc}.
13983@end table
13984
13985If you need special compiler options to compile one of your program's
13986source files, then you should generate that file's @samp{.X} file
13987specially, by running @command{gcc} on that source file with the
13988appropriate options and the option @option{-aux-info}. Then run
13989@code{protoize} on the entire set of files. @code{protoize} will use
13990the existing @samp{.X} file because it is newer than the source file.
13991For example:
13992
13993@smallexample
13994gcc -Dfoo=bar file1.c -aux-info file1.X
13995protoize *.c
13996@end smallexample
13997
13998@noindent
13999You need to include the special files along with the rest in the
14000@code{protoize} command, even though their @samp{.X} files already
14001exist, because otherwise they won't get converted.
14002
14003@xref{Protoize Caveats}, for more information on how to use
14004@code{protoize} successfully.
14005
| 1664@item -fno-weak
1665@opindex fno-weak
1666Do not use weak symbol support, even if it is provided by the linker.
1667By default, G++ will use weak symbols if they are available. This
1668option exists only for testing, and should not be used by end-users;
1669it will result in inferior code and has no benefits. This option may
1670be removed in a future release of G++.
1671
1672@item -nostdinc++
1673@opindex nostdinc++
1674Do not search for header files in the standard directories specific to
1675C++, but do still search the other standard directories. (This option
1676is used when building the C++ library.)
1677@end table
1678
1679In addition, these optimization, warning, and code generation options
1680have meanings only for C++ programs:
1681
1682@table @gcctabopt
1683@item -fno-default-inline
1684@opindex fno-default-inline
1685Do not assume @samp{inline} for functions defined inside a class scope.
1686@xref{Optimize Options,,Options That Control Optimization}. Note that these
1687functions will have linkage like inline functions; they just won't be
1688inlined by default.
1689
1690@item -Wabi @r{(C++ only)}
1691@opindex Wabi
1692Warn when G++ generates code that is probably not compatible with the
1693vendor-neutral C++ ABI@. Although an effort has been made to warn about
1694all such cases, there are probably some cases that are not warned about,
1695even though G++ is generating incompatible code. There may also be
1696cases where warnings are emitted even though the code that is generated
1697will be compatible.
1698
1699You should rewrite your code to avoid these warnings if you are
1700concerned about the fact that code generated by G++ may not be binary
1701compatible with code generated by other compilers.
1702
1703The known incompatibilities at this point include:
1704
1705@itemize @bullet
1706
1707@item
1708Incorrect handling of tail-padding for bit-fields. G++ may attempt to
1709pack data into the same byte as a base class. For example:
1710
1711@smallexample
1712struct A @{ virtual void f(); int f1 : 1; @};
1713struct B : public A @{ int f2 : 1; @};
1714@end smallexample
1715
1716@noindent
1717In this case, G++ will place @code{B::f2} into the same byte
1718as@code{A::f1}; other compilers will not. You can avoid this problem
1719by explicitly padding @code{A} so that its size is a multiple of the
1720byte size on your platform; that will cause G++ and other compilers to
1721layout @code{B} identically.
1722
1723@item
1724Incorrect handling of tail-padding for virtual bases. G++ does not use
1725tail padding when laying out virtual bases. For example:
1726
1727@smallexample
1728struct A @{ virtual void f(); char c1; @};
1729struct B @{ B(); char c2; @};
1730struct C : public A, public virtual B @{@};
1731@end smallexample
1732
1733@noindent
1734In this case, G++ will not place @code{B} into the tail-padding for
1735@code{A}; other compilers will. You can avoid this problem by
1736explicitly padding @code{A} so that its size is a multiple of its
1737alignment (ignoring virtual base classes); that will cause G++ and other
1738compilers to layout @code{C} identically.
1739
1740@item
1741Incorrect handling of bit-fields with declared widths greater than that
1742of their underlying types, when the bit-fields appear in a union. For
1743example:
1744
1745@smallexample
1746union U @{ int i : 4096; @};
1747@end smallexample
1748
1749@noindent
1750Assuming that an @code{int} does not have 4096 bits, G++ will make the
1751union too small by the number of bits in an @code{int}.
1752
1753@item
1754Empty classes can be placed at incorrect offsets. For example:
1755
1756@smallexample
1757struct A @{@};
1758
1759struct B @{
1760 A a;
1761 virtual void f ();
1762@};
1763
1764struct C : public B, public A @{@};
1765@end smallexample
1766
1767@noindent
1768G++ will place the @code{A} base class of @code{C} at a nonzero offset;
1769it should be placed at offset zero. G++ mistakenly believes that the
1770@code{A} data member of @code{B} is already at offset zero.
1771
1772@item
1773Names of template functions whose types involve @code{typename} or
1774template template parameters can be mangled incorrectly.
1775
1776@smallexample
1777template <typename Q>
1778void f(typename Q::X) @{@}
1779
1780template <template <typename> class Q>
1781void f(typename Q<int>::X) @{@}
1782@end smallexample
1783
1784@noindent
1785Instantiations of these templates may be mangled incorrectly.
1786
1787@end itemize
1788
1789@item -Wctor-dtor-privacy @r{(C++ only)}
1790@opindex Wctor-dtor-privacy
1791Warn when a class seems unusable because all the constructors or
1792destructors in that class are private, and it has neither friends nor
1793public static member functions.
1794
1795@item -Wnon-virtual-dtor @r{(C++ only)}
1796@opindex Wnon-virtual-dtor
1797Warn when a class appears to be polymorphic, thereby requiring a virtual
1798destructor, yet it declares a non-virtual one. This warning is also
1799enabled if -Weffc++ is specified.
1800
1801@item -Wreorder @r{(C++ only)}
1802@opindex Wreorder
1803@cindex reordering, warning
1804@cindex warning for reordering of member initializers
1805Warn when the order of member initializers given in the code does not
1806match the order in which they must be executed. For instance:
1807
1808@smallexample
1809struct A @{
1810 int i;
1811 int j;
1812 A(): j (0), i (1) @{ @}
1813@};
1814@end smallexample
1815
1816The compiler will rearrange the member initializers for @samp{i}
1817and @samp{j} to match the declaration order of the members, emitting
1818a warning to that effect. This warning is enabled by @option{-Wall}.
1819@end table
1820
1821The following @option{-W@dots{}} options are not affected by @option{-Wall}.
1822
1823@table @gcctabopt
1824@item -Weffc++ @r{(C++ only)}
1825@opindex Weffc++
1826Warn about violations of the following style guidelines from Scott Meyers'
1827@cite{Effective C++} book:
1828
1829@itemize @bullet
1830@item
1831Item 11: Define a copy constructor and an assignment operator for classes
1832with dynamically allocated memory.
1833
1834@item
1835Item 12: Prefer initialization to assignment in constructors.
1836
1837@item
1838Item 14: Make destructors virtual in base classes.
1839
1840@item
1841Item 15: Have @code{operator=} return a reference to @code{*this}.
1842
1843@item
1844Item 23: Don't try to return a reference when you must return an object.
1845
1846@end itemize
1847
1848Also warn about violations of the following style guidelines from
1849Scott Meyers' @cite{More Effective C++} book:
1850
1851@itemize @bullet
1852@item
1853Item 6: Distinguish between prefix and postfix forms of increment and
1854decrement operators.
1855
1856@item
1857Item 7: Never overload @code{&&}, @code{||}, or @code{,}.
1858
1859@end itemize
1860
1861When selecting this option, be aware that the standard library
1862headers do not obey all of these guidelines; use @samp{grep -v}
1863to filter out those warnings.
1864
1865@item -Wno-deprecated @r{(C++ only)}
1866@opindex Wno-deprecated
1867Do not warn about usage of deprecated features. @xref{Deprecated Features}.
1868
1869@item -Wstrict-null-sentinel @r{(C++ only)}
1870@opindex Wstrict-null-sentinel
1871Warn also about the use of an uncasted @code{NULL} as sentinel. When
1872compiling only with GCC this is a valid sentinel, as @code{NULL} is defined
1873to @code{__null}. Although it is a null pointer constant not a null pointer,
1874it is guaranteed to of the same size as a pointer. But this use is
1875not portable across different compilers.
1876
1877@item -Wno-non-template-friend @r{(C++ only)}
1878@opindex Wno-non-template-friend
1879Disable warnings when non-templatized friend functions are declared
1880within a template. Since the advent of explicit template specification
1881support in G++, if the name of the friend is an unqualified-id (i.e.,
1882@samp{friend foo(int)}), the C++ language specification demands that the
1883friend declare or define an ordinary, nontemplate function. (Section
188414.5.3). Before G++ implemented explicit specification, unqualified-ids
1885could be interpreted as a particular specialization of a templatized
1886function. Because this non-conforming behavior is no longer the default
1887behavior for G++, @option{-Wnon-template-friend} allows the compiler to
1888check existing code for potential trouble spots and is on by default.
1889This new compiler behavior can be turned off with
1890@option{-Wno-non-template-friend} which keeps the conformant compiler code
1891but disables the helpful warning.
1892
1893@item -Wold-style-cast @r{(C++ only)}
1894@opindex Wold-style-cast
1895Warn if an old-style (C-style) cast to a non-void type is used within
1896a C++ program. The new-style casts (@samp{dynamic_cast},
1897@samp{static_cast}, @samp{reinterpret_cast}, and @samp{const_cast}) are
1898less vulnerable to unintended effects and much easier to search for.
1899
1900@item -Woverloaded-virtual @r{(C++ only)}
1901@opindex Woverloaded-virtual
1902@cindex overloaded virtual fn, warning
1903@cindex warning for overloaded virtual fn
1904Warn when a function declaration hides virtual functions from a
1905base class. For example, in:
1906
1907@smallexample
1908struct A @{
1909 virtual void f();
1910@};
1911
1912struct B: public A @{
1913 void f(int);
1914@};
1915@end smallexample
1916
1917the @code{A} class version of @code{f} is hidden in @code{B}, and code
1918like:
1919
1920@smallexample
1921B* b;
1922b->f();
1923@end smallexample
1924
1925will fail to compile.
1926
1927@item -Wno-pmf-conversions @r{(C++ only)}
1928@opindex Wno-pmf-conversions
1929Disable the diagnostic for converting a bound pointer to member function
1930to a plain pointer.
1931
1932@item -Wsign-promo @r{(C++ only)}
1933@opindex Wsign-promo
1934Warn when overload resolution chooses a promotion from unsigned or
1935enumerated type to a signed type, over a conversion to an unsigned type of
1936the same size. Previous versions of G++ would try to preserve
1937unsignedness, but the standard mandates the current behavior.
1938
1939@smallexample
1940struct A @{
1941 operator int ();
1942 A& operator = (int);
1943@};
1944
1945main ()
1946@{
1947 A a,b;
1948 a = b;
1949@}
1950@end smallexample
1951
1952In this example, G++ will synthesize a default @samp{A& operator =
1953(const A&);}, while cfront will use the user-defined @samp{operator =}.
1954@end table
1955
1956@node Language Independent Options
1957@section Options to Control Diagnostic Messages Formatting
1958@cindex options to control diagnostics formatting
1959@cindex diagnostic messages
1960@cindex message formatting
1961
1962Traditionally, diagnostic messages have been formatted irrespective of
1963the output device's aspect (e.g.@: its width, @dots{}). The options described
1964below can be used to control the diagnostic messages formatting
1965algorithm, e.g.@: how many characters per line, how often source location
1966information should be reported. Right now, only the C++ front end can
1967honor these options. However it is expected, in the near future, that
1968the remaining front ends would be able to digest them correctly.
1969
1970@table @gcctabopt
1971@item -fmessage-length=@var{n}
1972@opindex fmessage-length
1973Try to format error messages so that they fit on lines of about @var{n}
1974characters. The default is 72 characters for @command{g++} and 0 for the rest of
1975the front ends supported by GCC@. If @var{n} is zero, then no
1976line-wrapping will be done; each error message will appear on a single
1977line.
1978
1979@opindex fdiagnostics-show-location
1980@item -fdiagnostics-show-location=once
1981Only meaningful in line-wrapping mode. Instructs the diagnostic messages
1982reporter to emit @emph{once} source location information; that is, in
1983case the message is too long to fit on a single physical line and has to
1984be wrapped, the source location won't be emitted (as prefix) again,
1985over and over, in subsequent continuation lines. This is the default
1986behavior.
1987
1988@item -fdiagnostics-show-location=every-line
1989Only meaningful in line-wrapping mode. Instructs the diagnostic
1990messages reporter to emit the same source location information (as
1991prefix) for physical lines that result from the process of breaking
1992a message which is too long to fit on a single line.
1993
1994@item -fdiagnostics-show-option
1995@opindex fdiagnostics-show-option
1996This option instructs the diagnostic machinery to add text to each
1997diagnostic emitted, which indicates which command line option directly
1998controls that diagnostic, when such an option is known to the
1999diagnostic machinery.
2000
2001@end table
2002
2003@node Warning Options
2004@section Options to Request or Suppress Warnings
2005@cindex options to control warnings
2006@cindex warning messages
2007@cindex messages, warning
2008@cindex suppressing warnings
2009
2010Warnings are diagnostic messages that report constructions which
2011are not inherently erroneous but which are risky or suggest there
2012may have been an error.
2013
2014You can request many specific warnings with options beginning @samp{-W},
2015for example @option{-Wimplicit} to request warnings on implicit
2016declarations. Each of these specific warning options also has a
2017negative form beginning @samp{-Wno-} to turn off warnings;
2018for example, @option{-Wno-implicit}. This manual lists only one of the
2019two forms, whichever is not the default.
2020
2021The following options control the amount and kinds of warnings produced
2022by GCC; for further, language-specific options also refer to
2023@ref{C++ Dialect Options}.
2024
2025@table @gcctabopt
2026@cindex syntax checking
2027@item -fsyntax-only
2028@opindex fsyntax-only
2029Check the code for syntax errors, but don't do anything beyond that.
2030
2031@item -pedantic
2032@opindex pedantic
2033Issue all the warnings demanded by strict ISO C and ISO C++;
2034reject all programs that use forbidden extensions, and some other
2035programs that do not follow ISO C and ISO C++. For ISO C, follows the
2036version of the ISO C standard specified by any @option{-std} option used.
2037
2038Valid ISO C and ISO C++ programs should compile properly with or without
2039this option (though a rare few will require @option{-ansi} or a
2040@option{-std} option specifying the required version of ISO C)@. However,
2041without this option, certain GNU extensions and traditional C and C++
2042features are supported as well. With this option, they are rejected.
2043
2044@option{-pedantic} does not cause warning messages for use of the
2045alternate keywords whose names begin and end with @samp{__}. Pedantic
2046warnings are also disabled in the expression that follows
2047@code{__extension__}. However, only system header files should use
2048these escape routes; application programs should avoid them.
2049@xref{Alternate Keywords}.
2050
2051Some users try to use @option{-pedantic} to check programs for strict ISO
2052C conformance. They soon find that it does not do quite what they want:
2053it finds some non-ISO practices, but not all---only those for which
2054ISO C @emph{requires} a diagnostic, and some others for which
2055diagnostics have been added.
2056
2057A feature to report any failure to conform to ISO C might be useful in
2058some instances, but would require considerable additional work and would
2059be quite different from @option{-pedantic}. We don't have plans to
2060support such a feature in the near future.
2061
2062Where the standard specified with @option{-std} represents a GNU
2063extended dialect of C, such as @samp{gnu89} or @samp{gnu99}, there is a
2064corresponding @dfn{base standard}, the version of ISO C on which the GNU
2065extended dialect is based. Warnings from @option{-pedantic} are given
2066where they are required by the base standard. (It would not make sense
2067for such warnings to be given only for features not in the specified GNU
2068C dialect, since by definition the GNU dialects of C include all
2069features the compiler supports with the given option, and there would be
2070nothing to warn about.)
2071
2072@item -pedantic-errors
2073@opindex pedantic-errors
2074Like @option{-pedantic}, except that errors are produced rather than
2075warnings.
2076
2077@item -w
2078@opindex w
2079Inhibit all warning messages.
2080
2081@item -Wno-import
2082@opindex Wno-import
2083Inhibit warning messages about the use of @samp{#import}.
2084
2085@item -Wchar-subscripts
2086@opindex Wchar-subscripts
2087Warn if an array subscript has type @code{char}. This is a common cause
2088of error, as programmers often forget that this type is signed on some
2089machines.
2090This warning is enabled by @option{-Wall}.
2091
2092@item -Wcomment
2093@opindex Wcomment
2094Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
2095comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
2096This warning is enabled by @option{-Wall}.
2097
2098@item -Wfatal-errors
2099@opindex Wfatal-errors
2100This option causes the compiler to abort compilation on the first error
2101occurred rather than trying to keep going and printing further error
2102messages.
2103
2104@item -Wformat
2105@opindex Wformat
2106@opindex ffreestanding
2107@opindex fno-builtin
2108Check calls to @code{printf} and @code{scanf}, etc., to make sure that
2109the arguments supplied have types appropriate to the format string
2110specified, and that the conversions specified in the format string make
2111sense. This includes standard functions, and others specified by format
2112attributes (@pxref{Function Attributes}), in the @code{printf},
2113@code{scanf}, @code{strftime} and @code{strfmon} (an X/Open extension,
2114not in the C standard) families (or other target-specific families).
2115Which functions are checked without format attributes having been
2116specified depends on the standard version selected, and such checks of
2117functions without the attribute specified are disabled by
2118@option{-ffreestanding} or @option{-fno-builtin}.
2119
2120The formats are checked against the format features supported by GNU
2121libc version 2.2. These include all ISO C90 and C99 features, as well
2122as features from the Single Unix Specification and some BSD and GNU
2123extensions. Other library implementations may not support all these
2124features; GCC does not support warning about features that go beyond a
2125particular library's limitations. However, if @option{-pedantic} is used
2126with @option{-Wformat}, warnings will be given about format features not
2127in the selected standard version (but not for @code{strfmon} formats,
2128since those are not in any version of the C standard). @xref{C Dialect
2129Options,,Options Controlling C Dialect}.
2130
2131Since @option{-Wformat} also checks for null format arguments for
2132several functions, @option{-Wformat} also implies @option{-Wnonnull}.
2133
2134@option{-Wformat} is included in @option{-Wall}. For more control over some
2135aspects of format checking, the options @option{-Wformat-y2k},
2136@option{-Wno-format-extra-args}, @option{-Wno-format-zero-length},
2137@option{-Wformat-nonliteral}, @option{-Wformat-security}, and
2138@option{-Wformat=2} are available, but are not included in @option{-Wall}.
2139
2140@item -Wformat-y2k
2141@opindex Wformat-y2k
2142If @option{-Wformat} is specified, also warn about @code{strftime}
2143formats which may yield only a two-digit year.
2144
2145@item -Wno-format-extra-args
2146@opindex Wno-format-extra-args
2147If @option{-Wformat} is specified, do not warn about excess arguments to a
2148@code{printf} or @code{scanf} format function. The C standard specifies
2149that such arguments are ignored.
2150
2151Where the unused arguments lie between used arguments that are
2152specified with @samp{$} operand number specifications, normally
2153warnings are still given, since the implementation could not know what
2154type to pass to @code{va_arg} to skip the unused arguments. However,
2155in the case of @code{scanf} formats, this option will suppress the
2156warning if the unused arguments are all pointers, since the Single
2157Unix Specification says that such unused arguments are allowed.
2158
2159@item -Wno-format-zero-length
2160@opindex Wno-format-zero-length
2161If @option{-Wformat} is specified, do not warn about zero-length formats.
2162The C standard specifies that zero-length formats are allowed.
2163
2164@item -Wformat-nonliteral
2165@opindex Wformat-nonliteral
2166If @option{-Wformat} is specified, also warn if the format string is not a
2167string literal and so cannot be checked, unless the format function
2168takes its format arguments as a @code{va_list}.
2169
2170@item -Wformat-security
2171@opindex Wformat-security
2172If @option{-Wformat} is specified, also warn about uses of format
2173functions that represent possible security problems. At present, this
2174warns about calls to @code{printf} and @code{scanf} functions where the
2175format string is not a string literal and there are no format arguments,
2176as in @code{printf (foo);}. This may be a security hole if the format
2177string came from untrusted input and contains @samp{%n}. (This is
2178currently a subset of what @option{-Wformat-nonliteral} warns about, but
2179in future warnings may be added to @option{-Wformat-security} that are not
2180included in @option{-Wformat-nonliteral}.)
2181
2182@item -Wformat=2
2183@opindex Wformat=2
2184Enable @option{-Wformat} plus format checks not included in
2185@option{-Wformat}. Currently equivalent to @samp{-Wformat
2186-Wformat-nonliteral -Wformat-security -Wformat-y2k}.
2187
2188@item -Wnonnull
2189@opindex Wnonnull
2190Warn about passing a null pointer for arguments marked as
2191requiring a non-null value by the @code{nonnull} function attribute.
2192
2193@option{-Wnonnull} is included in @option{-Wall} and @option{-Wformat}. It
2194can be disabled with the @option{-Wno-nonnull} option.
2195
2196@item -Winit-self @r{(C and C++ only)}
2197@opindex Winit-self
2198Warn about uninitialized variables which are initialized with themselves.
2199Note this option can only be used with the @option{-Wuninitialized} option,
2200which in turn only works with @option{-O1} and above.
2201
2202For example, GCC will warn about @code{i} being uninitialized in the
2203following snippet only when @option{-Winit-self} has been specified:
2204@smallexample
2205@group
2206int f()
2207@{
2208 int i = i;
2209 return i;
2210@}
2211@end group
2212@end smallexample
2213
2214@item -Wimplicit-int
2215@opindex Wimplicit-int
2216Warn when a declaration does not specify a type.
2217This warning is enabled by @option{-Wall}.
2218
2219@item -Wimplicit-function-declaration
2220@itemx -Werror-implicit-function-declaration
2221@opindex Wimplicit-function-declaration
2222@opindex Werror-implicit-function-declaration
2223Give a warning (or error) whenever a function is used before being
2224declared. The form @option{-Wno-error-implicit-function-declaration}
2225is not supported.
2226This warning is enabled by @option{-Wall} (as a warning, not an error).
2227
2228@item -Wimplicit
2229@opindex Wimplicit
2230Same as @option{-Wimplicit-int} and @option{-Wimplicit-function-declaration}.
2231This warning is enabled by @option{-Wall}.
2232
2233@item -Wmain
2234@opindex Wmain
2235Warn if the type of @samp{main} is suspicious. @samp{main} should be a
2236function with external linkage, returning int, taking either zero
2237arguments, two, or three arguments of appropriate types.
2238This warning is enabled by @option{-Wall}.
2239
2240@item -Wmissing-braces
2241@opindex Wmissing-braces
2242Warn if an aggregate or union initializer is not fully bracketed. In
2243the following example, the initializer for @samp{a} is not fully
2244bracketed, but that for @samp{b} is fully bracketed.
2245
2246@smallexample
2247int a[2][2] = @{ 0, 1, 2, 3 @};
2248int b[2][2] = @{ @{ 0, 1 @}, @{ 2, 3 @} @};
2249@end smallexample
2250
2251This warning is enabled by @option{-Wall}.
2252
2253@item -Wmissing-include-dirs @r{(C and C++ only)}
2254@opindex Wmissing-include-dirs
2255Warn if a user-supplied include directory does not exist.
2256
2257@item -Wparentheses
2258@opindex Wparentheses
2259Warn if parentheses are omitted in certain contexts, such
2260as when there is an assignment in a context where a truth value
2261is expected, or when operators are nested whose precedence people
2262often get confused about.
2263
2264Also warn if a comparison like @samp{x<=y<=z} appears; this is
2265equivalent to @samp{(x<=y ? 1 : 0) <= z}, which is a different
2266interpretation from that of ordinary mathematical notation.
2267
2268Also warn about constructions where there may be confusion to which
2269@code{if} statement an @code{else} branch belongs. Here is an example of
2270such a case:
2271
2272@smallexample
2273@group
2274@{
2275 if (a)
2276 if (b)
2277 foo ();
2278 else
2279 bar ();
2280@}
2281@end group
2282@end smallexample
2283
2284In C/C++, every @code{else} branch belongs to the innermost possible
2285@code{if} statement, which in this example is @code{if (b)}. This is
2286often not what the programmer expected, as illustrated in the above
2287example by indentation the programmer chose. When there is the
2288potential for this confusion, GCC will issue a warning when this flag
2289is specified. To eliminate the warning, add explicit braces around
2290the innermost @code{if} statement so there is no way the @code{else}
2291could belong to the enclosing @code{if}. The resulting code would
2292look like this:
2293
2294@smallexample
2295@group
2296@{
2297 if (a)
2298 @{
2299 if (b)
2300 foo ();
2301 else
2302 bar ();
2303 @}
2304@}
2305@end group
2306@end smallexample
2307
2308This warning is enabled by @option{-Wall}.
2309
2310@item -Wsequence-point
2311@opindex Wsequence-point
2312Warn about code that may have undefined semantics because of violations
2313of sequence point rules in the C and C++ standards.
2314
2315The C and C++ standards defines the order in which expressions in a C/C++
2316program are evaluated in terms of @dfn{sequence points}, which represent
2317a partial ordering between the execution of parts of the program: those
2318executed before the sequence point, and those executed after it. These
2319occur after the evaluation of a full expression (one which is not part
2320of a larger expression), after the evaluation of the first operand of a
2321@code{&&}, @code{||}, @code{? :} or @code{,} (comma) operator, before a
2322function is called (but after the evaluation of its arguments and the
2323expression denoting the called function), and in certain other places.
2324Other than as expressed by the sequence point rules, the order of
2325evaluation of subexpressions of an expression is not specified. All
2326these rules describe only a partial order rather than a total order,
2327since, for example, if two functions are called within one expression
2328with no sequence point between them, the order in which the functions
2329are called is not specified. However, the standards committee have
2330ruled that function calls do not overlap.
2331
2332It is not specified when between sequence points modifications to the
2333values of objects take effect. Programs whose behavior depends on this
2334have undefined behavior; the C and C++ standards specify that ``Between
2335the previous and next sequence point an object shall have its stored
2336value modified at most once by the evaluation of an expression.
2337Furthermore, the prior value shall be read only to determine the value
2338to be stored.''. If a program breaks these rules, the results on any
2339particular implementation are entirely unpredictable.
2340
2341Examples of code with undefined behavior are @code{a = a++;}, @code{a[n]
2342= b[n++]} and @code{a[i++] = i;}. Some more complicated cases are not
2343diagnosed by this option, and it may give an occasional false positive
2344result, but in general it has been found fairly effective at detecting
2345this sort of problem in programs.
2346
2347The standard is worded confusingly, therefore there is some debate
2348over the precise meaning of the sequence point rules in subtle cases.
2349Links to discussions of the problem, including proposed formal
2350definitions, may be found on the GCC readings page, at
2351@w{@uref{http://gcc.gnu.org/readings.html}}.
2352
2353This warning is enabled by @option{-Wall} for C and C++.
2354
2355@item -Wreturn-type
2356@opindex Wreturn-type
2357Warn whenever a function is defined with a return-type that defaults to
2358@code{int}. Also warn about any @code{return} statement with no
2359return-value in a function whose return-type is not @code{void}.
2360
2361For C, also warn if the return type of a function has a type qualifier
2362such as @code{const}. Such a type qualifier has no effect, since the
2363value returned by a function is not an lvalue. ISO C prohibits
2364qualified @code{void} return types on function definitions, so such
2365return types always receive a warning even without this option.
2366
2367For C++, a function without return type always produces a diagnostic
2368message, even when @option{-Wno-return-type} is specified. The only
2369exceptions are @samp{main} and functions defined in system headers.
2370
2371This warning is enabled by @option{-Wall}.
2372
2373@item -Wswitch
2374@opindex Wswitch
2375Warn whenever a @code{switch} statement has an index of enumerated type
2376and lacks a @code{case} for one or more of the named codes of that
2377enumeration. (The presence of a @code{default} label prevents this
2378warning.) @code{case} labels outside the enumeration range also
2379provoke warnings when this option is used.
2380This warning is enabled by @option{-Wall}.
2381
2382@item -Wswitch-default
2383@opindex Wswitch-switch
2384Warn whenever a @code{switch} statement does not have a @code{default}
2385case.
2386
2387@item -Wswitch-enum
2388@opindex Wswitch-enum
2389Warn whenever a @code{switch} statement has an index of enumerated type
2390and lacks a @code{case} for one or more of the named codes of that
2391enumeration. @code{case} labels outside the enumeration range also
2392provoke warnings when this option is used.
2393
2394@item -Wtrigraphs
2395@opindex Wtrigraphs
2396Warn if any trigraphs are encountered that might change the meaning of
2397the program (trigraphs within comments are not warned about).
2398This warning is enabled by @option{-Wall}.
2399
2400@item -Wunused-function
2401@opindex Wunused-function
2402Warn whenever a static function is declared but not defined or a
2403non-inline static function is unused.
2404This warning is enabled by @option{-Wall}.
2405
2406@item -Wunused-label
2407@opindex Wunused-label
2408Warn whenever a label is declared but not used.
2409This warning is enabled by @option{-Wall}.
2410
2411To suppress this warning use the @samp{unused} attribute
2412(@pxref{Variable Attributes}).
2413
2414@item -Wunused-parameter
2415@opindex Wunused-parameter
2416Warn whenever a function parameter is unused aside from its declaration.
2417
2418To suppress this warning use the @samp{unused} attribute
2419(@pxref{Variable Attributes}).
2420
2421@item -Wunused-variable
2422@opindex Wunused-variable
2423Warn whenever a local variable or non-constant static variable is unused
2424aside from its declaration.
2425This warning is enabled by @option{-Wall}.
2426
2427To suppress this warning use the @samp{unused} attribute
2428(@pxref{Variable Attributes}).
2429
2430@item -Wunused-value
2431@opindex Wunused-value
2432Warn whenever a statement computes a result that is explicitly not used.
2433This warning is enabled by @option{-Wall}.
2434
2435To suppress this warning cast the expression to @samp{void}.
2436
2437@item -Wunused
2438@opindex Wunused
2439All the above @option{-Wunused} options combined.
2440
2441In order to get a warning about an unused function parameter, you must
2442either specify @samp{-Wextra -Wunused} (note that @samp{-Wall} implies
2443@samp{-Wunused}), or separately specify @option{-Wunused-parameter}.
2444
2445@item -Wuninitialized
2446@opindex Wuninitialized
2447Warn if an automatic variable is used without first being initialized or
2448if a variable may be clobbered by a @code{setjmp} call.
2449
2450These warnings are possible only in optimizing compilation,
2451because they require data flow information that is computed only
2452when optimizing. If you do not specify @option{-O}, you will not get
2453these warnings. Instead, GCC will issue a warning about @option{-Wuninitialized}
2454requiring @option{-O}.
2455
2456If you want to warn about code which uses the uninitialized value of the
2457variable in its own initializer, use the @option{-Winit-self} option.
2458
2459These warnings occur for individual uninitialized or clobbered
2460elements of structure, union or array variables as well as for
2461variables which are uninitialized or clobbered as a whole. They do
2462not occur for variables or elements declared @code{volatile}. Because
2463these warnings depend on optimization, the exact variables or elements
2464for which there are warnings will depend on the precise optimization
2465options and version of GCC used.
2466
2467Note that there may be no warning about a variable that is used only
2468to compute a value that itself is never used, because such
2469computations may be deleted by data flow analysis before the warnings
2470are printed.
2471
2472These warnings are made optional because GCC is not smart
2473enough to see all the reasons why the code might be correct
2474despite appearing to have an error. Here is one example of how
2475this can happen:
2476
2477@smallexample
2478@group
2479@{
2480 int x;
2481 switch (y)
2482 @{
2483 case 1: x = 1;
2484 break;
2485 case 2: x = 4;
2486 break;
2487 case 3: x = 5;
2488 @}
2489 foo (x);
2490@}
2491@end group
2492@end smallexample
2493
2494@noindent
2495If the value of @code{y} is always 1, 2 or 3, then @code{x} is
2496always initialized, but GCC doesn't know this. Here is
2497another common case:
2498
2499@smallexample
2500@{
2501 int save_y;
2502 if (change_y) save_y = y, y = new_y;
2503 @dots{}
2504 if (change_y) y = save_y;
2505@}
2506@end smallexample
2507
2508@noindent
2509This has no bug because @code{save_y} is used only if it is set.
2510
2511@cindex @code{longjmp} warnings
2512This option also warns when a non-volatile automatic variable might be
2513changed by a call to @code{longjmp}. These warnings as well are possible
2514only in optimizing compilation.
2515
2516The compiler sees only the calls to @code{setjmp}. It cannot know
2517where @code{longjmp} will be called; in fact, a signal handler could
2518call it at any point in the code. As a result, you may get a warning
2519even when there is in fact no problem because @code{longjmp} cannot
2520in fact be called at the place which would cause a problem.
2521
2522Some spurious warnings can be avoided if you declare all the functions
2523you use that never return as @code{noreturn}. @xref{Function
2524Attributes}.
2525
2526This warning is enabled by @option{-Wall}.
2527
2528@item -Wunknown-pragmas
2529@opindex Wunknown-pragmas
2530@cindex warning for unknown pragmas
2531@cindex unknown pragmas, warning
2532@cindex pragmas, warning of unknown
2533Warn when a #pragma directive is encountered which is not understood by
2534GCC@. If this command line option is used, warnings will even be issued
2535for unknown pragmas in system header files. This is not the case if
2536the warnings were only enabled by the @option{-Wall} command line option.
2537
2538@item -Wno-pragmas
2539@opindex Wno-pragmas
2540@opindex Wpragmas
2541Do not warn about misuses of pragmas, such as incorrect parameters,
2542invalid syntax, or conflicts between pragmas. See also
2543@samp{-Wunknown-pragmas}.
2544
2545@item -Wstrict-aliasing
2546@opindex Wstrict-aliasing
2547This option is only active when @option{-fstrict-aliasing} is active.
2548It warns about code which might break the strict aliasing rules that the
2549compiler is using for optimization. The warning does not catch all
2550cases, but does attempt to catch the more common pitfalls. It is
2551included in @option{-Wall}.
2552It is equivalent to -Wstrict-aliasing=3
2553
2554@item -Wstrict-aliasing=n
2555@opindex Wstrict-aliasing=n
2556This option is only active when @option{-fstrict-aliasing} is active.
2557It warns about code which might break the strict aliasing rules that the
2558compiler is using for optimization.
2559Higher levels correspond to higher accuracy (fewer false positives).
2560Higher levels also correspond to more effort, similar to the way -O works.
2561@option{-Wstrict-aliasing} is equivalent to @option{-Wstrict-aliasing=n},
2562with n=3.
2563
2564Level 1: Most aggressive, quick, least accurate.
2565Possibly useful when higher levels
2566do not warn but -fstrict-aliasing still breaks the code, as it has very few
2567false negatives. However, it has many false positives.
2568Warns for all pointer conversions between possibly incompatible types,
2569even if never dereferenced. Runs in the frontend only.
2570
2571Level 2: Aggressive, quick, not too precise.
2572May still have many false positives (not as many as level 1 though),
2573and few false negatives (but possibly more than level 1).
2574Unlike level 1, it only warns when an address is taken. Warns about
2575incomplete types. Runs in the frontend only.
2576
2577Level 3 (default for @option{-Wstrict-aliasing}):
2578Should have very few false positives and few false
2579negatives. Slightly slower than levels 1 or 2 when optimization is enabled.
2580Takes care of the common punn+dereference pattern in the frontend:
2581@code{*(int*)&some_float}.
2582If optimization is enabled, it also runs in the backend, where it deals
2583with multiple statement cases using flow-sensitive points-to information.
2584Only warns when the converted pointer is dereferenced.
2585Does not warn about incomplete types.
2586
2587@item -Wstrict-overflow
2588@item -Wstrict-overflow=@var{n}
2589@opindex Wstrict-overflow
2590This option is only active when @option{-fstrict-overflow} is active.
2591It warns about cases where the compiler optimizes based on the
2592assumption that signed overflow does not occur. Note that it does not
2593warn about all cases where the code might overflow: it only warns
2594about cases where the compiler implements some optimization. Thus
2595this warning depends on the optimization level.
2596
2597An optimization which assumes that signed overflow does not occur is
2598perfectly safe if the values of the variables involved are such that
2599overflow never does, in fact, occur. Therefore this warning can
2600easily give a false positive: a warning about code which is not
2601actually a problem. To help focus on important issues, several
2602warning levels are defined. No warnings are issued for the use of
2603undefined signed overflow when estimating how many iterations a loop
2604will require, in particular when determining whether a loop will be
2605executed at all.
2606
2607@table @option
2608@item -Wstrict-overflow=1
2609Warn about cases which are both questionable and easy to avoid. For
2610example: @code{x + 1 > x}; with @option{-fstrict-overflow}, the
2611compiler will simplify this to @code{1}. This level of
2612@option{-Wstrict-overflow} is enabled by @option{-Wall}; higher levels
2613are not, and must be explicitly requested.
2614
2615@item -Wstrict-overflow=2
2616Also warn about other cases where a comparison is simplified to a
2617constant. For example: @code{abs (x) >= 0}. This can only be
2618simplified when @option{-fstrict-overflow} is in effect, because
2619@code{abs (INT_MIN)} overflows to @code{INT_MIN}, which is less than
2620zero. @option{-Wstrict-overflow} (with no level) is the same as
2621@option{-Wstrict-overflow=2}.
2622
2623@item -Wstrict-overflow=3
2624Also warn about other cases where a comparison is simplified. For
2625example: @code{x + 1 > 1} will be simplified to @code{x > 0}.
2626
2627@item -Wstrict-overflow=4
2628Also warn about other simplifications not covered by the above cases.
2629For example: @code{(x * 10) / 5} will be simplified to @code{x * 2}.
2630
2631@item -Wstrict-overflow=5
2632Also warn about cases where the compiler reduces the magnitude of a
2633constant involved in a comparison. For example: @code{x + 2 > y} will
2634be simplified to @code{x + 1 >= y}. This is reported only at the
2635highest warning level because this simplification applies to many
2636comparisons, so this warning level will give a very large number of
2637false positives.
2638@end table
2639
2640@item -Wall
2641@opindex Wall
2642All of the above @samp{-W} options combined. This enables all the
2643warnings about constructions that some users consider questionable, and
2644that are easy to avoid (or modify to prevent the warning), even in
2645conjunction with macros. This also enables some language-specific
2646warnings described in @ref{C++ Dialect Options}.
2647@end table
2648
2649The following @option{-W@dots{}} options are not implied by @option{-Wall}.
2650Some of them warn about constructions that users generally do not
2651consider questionable, but which occasionally you might wish to check
2652for; others warn about constructions that are necessary or hard to avoid
2653in some cases, and there is no simple way to modify the code to suppress
2654the warning.
2655
2656@table @gcctabopt
2657@item -Wextra
2658@opindex W
2659@opindex Wextra
2660(This option used to be called @option{-W}. The older name is still
2661supported, but the newer name is more descriptive.) Print extra warning
2662messages for these events:
2663
2664@itemize @bullet
2665@item
2666A function can return either with or without a value. (Falling
2667off the end of the function body is considered returning without
2668a value.) For example, this function would evoke such a
2669warning:
2670
2671@smallexample
2672@group
2673foo (a)
2674@{
2675 if (a > 0)
2676 return a;
2677@}
2678@end group
2679@end smallexample
2680
2681@item
2682An expression-statement or the left-hand side of a comma expression
2683contains no side effects.
2684To suppress the warning, cast the unused expression to void.
2685For example, an expression such as @samp{x[i,j]} will cause a warning,
2686but @samp{x[(void)i,j]} will not.
2687
2688@item
2689An unsigned value is compared against zero with @samp{<} or @samp{>=}.
2690
2691@item
2692Storage-class specifiers like @code{static} are not the first things in
2693a declaration. According to the C Standard, this usage is obsolescent.
2694
2695@item
2696If @option{-Wall} or @option{-Wunused} is also specified, warn about unused
2697arguments.
2698
2699@item
2700A comparison between signed and unsigned values could produce an
2701incorrect result when the signed value is converted to unsigned.
2702(But don't warn if @option{-Wno-sign-compare} is also specified.)
2703
2704@item
2705An aggregate has an initializer which does not initialize all members.
2706This warning can be independently controlled by
2707@option{-Wmissing-field-initializers}.
2708
2709@item
2710An initialized field without side effects is overridden when using
2711designated initializers (@pxref{Designated Inits, , Designated
2712Initializers}). This warning can be independently controlled by
2713@option{-Woverride-init}.
2714
2715@item
2716A function parameter is declared without a type specifier in K&R-style
2717functions:
2718
2719@smallexample
2720void foo(bar) @{ @}
2721@end smallexample
2722
2723@item
2724An empty body occurs in an @samp{if} or @samp{else} statement.
2725
2726@item
2727A pointer is compared against integer zero with @samp{<}, @samp{<=},
2728@samp{>}, or @samp{>=}.
2729
2730@item
2731A variable might be changed by @samp{longjmp} or @samp{vfork}.
2732
2733@item @r{(C++ only)}
2734An enumerator and a non-enumerator both appear in a conditional expression.
2735
2736@item @r{(C++ only)}
2737A non-static reference or non-static @samp{const} member appears in a
2738class without constructors.
2739
2740@item @r{(C++ only)}
2741Ambiguous virtual bases.
2742
2743@item @r{(C++ only)}
2744Subscripting an array which has been declared @samp{register}.
2745
2746@item @r{(C++ only)}
2747Taking the address of a variable which has been declared @samp{register}.
2748
2749@item @r{(C++ only)}
2750A base class is not initialized in a derived class' copy constructor.
2751@end itemize
2752
2753@item -Wno-div-by-zero
2754@opindex Wno-div-by-zero
2755@opindex Wdiv-by-zero
2756Do not warn about compile-time integer division by zero. Floating point
2757division by zero is not warned about, as it can be a legitimate way of
2758obtaining infinities and NaNs.
2759
2760@item -Wsystem-headers
2761@opindex Wsystem-headers
2762@cindex warnings from system headers
2763@cindex system headers, warnings from
2764Print warning messages for constructs found in system header files.
2765Warnings from system headers are normally suppressed, on the assumption
2766that they usually do not indicate real problems and would only make the
2767compiler output harder to read. Using this command line option tells
2768GCC to emit warnings from system headers as if they occurred in user
2769code. However, note that using @option{-Wall} in conjunction with this
2770option will @emph{not} warn about unknown pragmas in system
2771headers---for that, @option{-Wunknown-pragmas} must also be used.
2772
2773@item -Wfloat-equal
2774@opindex Wfloat-equal
2775Warn if floating point values are used in equality comparisons.
2776
2777The idea behind this is that sometimes it is convenient (for the
2778programmer) to consider floating-point values as approximations to
2779infinitely precise real numbers. If you are doing this, then you need
2780to compute (by analyzing the code, or in some other way) the maximum or
2781likely maximum error that the computation introduces, and allow for it
2782when performing comparisons (and when producing output, but that's a
2783different problem). In particular, instead of testing for equality, you
2784would check to see whether the two values have ranges that overlap; and
2785this is done with the relational operators, so equality comparisons are
2786probably mistaken.
2787
2788@item -Wtraditional @r{(C only)}
2789@opindex Wtraditional
2790Warn about certain constructs that behave differently in traditional and
2791ISO C@. Also warn about ISO C constructs that have no traditional C
2792equivalent, and/or problematic constructs which should be avoided.
2793
2794@itemize @bullet
2795@item
2796Macro parameters that appear within string literals in the macro body.
2797In traditional C macro replacement takes place within string literals,
2798but does not in ISO C@.
2799
2800@item
2801In traditional C, some preprocessor directives did not exist.
2802Traditional preprocessors would only consider a line to be a directive
2803if the @samp{#} appeared in column 1 on the line. Therefore
2804@option{-Wtraditional} warns about directives that traditional C
2805understands but would ignore because the @samp{#} does not appear as the
2806first character on the line. It also suggests you hide directives like
2807@samp{#pragma} not understood by traditional C by indenting them. Some
2808traditional implementations would not recognize @samp{#elif}, so it
2809suggests avoiding it altogether.
2810
2811@item
2812A function-like macro that appears without arguments.
2813
2814@item
2815The unary plus operator.
2816
2817@item
2818The @samp{U} integer constant suffix, or the @samp{F} or @samp{L} floating point
2819constant suffixes. (Traditional C does support the @samp{L} suffix on integer
2820constants.) Note, these suffixes appear in macros defined in the system
2821headers of most modern systems, e.g.@: the @samp{_MIN}/@samp{_MAX} macros in @code{<limits.h>}.
2822Use of these macros in user code might normally lead to spurious
2823warnings, however GCC's integrated preprocessor has enough context to
2824avoid warning in these cases.
2825
2826@item
2827A function declared external in one block and then used after the end of
2828the block.
2829
2830@item
2831A @code{switch} statement has an operand of type @code{long}.
2832
2833@item
2834A non-@code{static} function declaration follows a @code{static} one.
2835This construct is not accepted by some traditional C compilers.
2836
2837@item
2838The ISO type of an integer constant has a different width or
2839signedness from its traditional type. This warning is only issued if
2840the base of the constant is ten. I.e.@: hexadecimal or octal values, which
2841typically represent bit patterns, are not warned about.
2842
2843@item
2844Usage of ISO string concatenation is detected.
2845
2846@item
2847Initialization of automatic aggregates.
2848
2849@item
2850Identifier conflicts with labels. Traditional C lacks a separate
2851namespace for labels.
2852
2853@item
2854Initialization of unions. If the initializer is zero, the warning is
2855omitted. This is done under the assumption that the zero initializer in
2856user code appears conditioned on e.g.@: @code{__STDC__} to avoid missing
2857initializer warnings and relies on default initialization to zero in the
2858traditional C case.
2859
2860@item
2861Conversions by prototypes between fixed/floating point values and vice
2862versa. The absence of these prototypes when compiling with traditional
2863C would cause serious problems. This is a subset of the possible
2864conversion warnings, for the full set use @option{-Wconversion}.
2865
2866@item
2867Use of ISO C style function definitions. This warning intentionally is
2868@emph{not} issued for prototype declarations or variadic functions
2869because these ISO C features will appear in your code when using
2870libiberty's traditional C compatibility macros, @code{PARAMS} and
2871@code{VPARAMS}. This warning is also bypassed for nested functions
2872because that feature is already a GCC extension and thus not relevant to
2873traditional C compatibility.
2874@end itemize
2875
2876@item -Wdeclaration-after-statement @r{(C only)}
2877@opindex Wdeclaration-after-statement
2878Warn when a declaration is found after a statement in a block. This
2879construct, known from C++, was introduced with ISO C99 and is by default
2880allowed in GCC@. It is not supported by ISO C90 and was not supported by
2881GCC versions before GCC 3.0. @xref{Mixed Declarations}.
2882
2883@item -Wundef
2884@opindex Wundef
2885Warn if an undefined identifier is evaluated in an @samp{#if} directive.
2886
2887@item -Wno-endif-labels
2888@opindex Wno-endif-labels
2889@opindex Wendif-labels
2890Do not warn whenever an @samp{#else} or an @samp{#endif} are followed by text.
2891
2892@item -Wshadow
2893@opindex Wshadow
2894Warn whenever a local variable shadows another local variable, parameter or
2895global variable or whenever a built-in function is shadowed.
2896
2897@item -Wlarger-than-@var{len}
2898@opindex Wlarger-than
2899Warn whenever an object of larger than @var{len} bytes is defined.
2900
2901@item -Wframe-larger-than-@var{len}
2902@opindex Wframe-larger-than
2903Warn whenever the frame size of a function is larger than @var{len} bytes.
2904
2905@item -Wunsafe-loop-optimizations
2906@opindex Wunsafe-loop-optimizations
2907Warn if the loop cannot be optimized because the compiler could not
2908assume anything on the bounds of the loop indices. With
2909@option{-funsafe-loop-optimizations} warn if the compiler made
2910such assumptions.
2911
2912@item -Wpointer-arith
2913@opindex Wpointer-arith
2914Warn about anything that depends on the ``size of'' a function type or
2915of @code{void}. GNU C assigns these types a size of 1, for
2916convenience in calculations with @code{void *} pointers and pointers
2917to functions.
2918
2919@item -Wbad-function-cast @r{(C only)}
2920@opindex Wbad-function-cast
2921Warn whenever a function call is cast to a non-matching type.
2922For example, warn if @code{int malloc()} is cast to @code{anything *}.
2923
2924@item -Wc++-compat
2925Warn about ISO C constructs that are outside of the common subset of
2926ISO C and ISO C++, e.g.@: request for implicit conversion from
2927@code{void *} to a pointer to non-@code{void} type.
2928
2929@item -Wcast-qual
2930@opindex Wcast-qual
2931Warn whenever a pointer is cast so as to remove a type qualifier from
2932the target type. For example, warn if a @code{const char *} is cast
2933to an ordinary @code{char *}.
2934
2935@item -Wcast-align
2936@opindex Wcast-align
2937Warn whenever a pointer is cast such that the required alignment of the
2938target is increased. For example, warn if a @code{char *} is cast to
2939an @code{int *} on machines where integers can only be accessed at
2940two- or four-byte boundaries.
2941
2942@item -Wwrite-strings
2943@opindex Wwrite-strings
2944When compiling C, give string constants the type @code{const
2945char[@var{length}]} so that
2946copying the address of one into a non-@code{const} @code{char *}
2947pointer will get a warning; when compiling C++, warn about the
2948deprecated conversion from string literals to @code{char *}. This
2949warning, by default, is enabled for C++ programs.
2950These warnings will help you find at
2951compile time code that can try to write into a string constant, but
2952only if you have been very careful about using @code{const} in
2953declarations and prototypes. Otherwise, it will just be a nuisance;
2954this is why we did not make @option{-Wall} request these warnings.
2955
2956@item -Wconversion
2957@opindex Wconversion
2958Warn if a prototype causes a type conversion that is different from what
2959would happen to the same argument in the absence of a prototype. This
2960includes conversions of fixed point to floating and vice versa, and
2961conversions changing the width or signedness of a fixed point argument
2962except when the same as the default promotion.
2963
2964Also, warn if a negative integer constant expression is implicitly
2965converted to an unsigned type. For example, warn about the assignment
2966@code{x = -1} if @code{x} is unsigned. But do not warn about explicit
2967casts like @code{(unsigned) -1}.
2968
2969@item -Wsign-compare
2970@opindex Wsign-compare
2971@cindex warning for comparison of signed and unsigned values
2972@cindex comparison of signed and unsigned values, warning
2973@cindex signed and unsigned values, comparison warning
2974Warn when a comparison between signed and unsigned values could produce
2975an incorrect result when the signed value is converted to unsigned.
2976This warning is also enabled by @option{-Wextra}; to get the other warnings
2977of @option{-Wextra} without this warning, use @samp{-Wextra -Wno-sign-compare}.
2978
2979@item -Waddress
2980@opindex Waddress
2981@opindex Wno-address
2982Warn about suspicious uses of memory addresses. These include using
2983the address of a function in a conditional expression, such as
2984@code{void func(void); if (func)}, and comparisons against the memory
2985address of a string literal, such as @code{if (x == "abc")}. Such
2986uses typically indicate a programmer error: the address of a function
2987always evaluates to true, so their use in a conditional usually
2988indicate that the programmer forgot the parentheses in a function
2989call; and comparisons against string literals result in unspecified
2990behavior and are not portable in C, so they usually indicate that the
2991programmer intended to use @code{strcmp}. This warning is enabled by
2992@option{-Wall}.
2993
2994@item -Waggregate-return
2995@opindex Waggregate-return
2996Warn if any functions that return structures or unions are defined or
2997called. (In languages where you can return an array, this also elicits
2998a warning.)
2999
3000@item -Wno-attributes
3001@opindex Wno-attributes
3002@opindex Wattributes
3003Do not warn if an unexpected @code{__attribute__} is used, such as
3004unrecognized attributes, function attributes applied to variables,
3005etc. This will not stop errors for incorrect use of supported
3006attributes.
3007
3008@item -Wstrict-prototypes @r{(C only)}
3009@opindex Wstrict-prototypes
3010Warn if a function is declared or defined without specifying the
3011argument types. (An old-style function definition is permitted without
3012a warning if preceded by a declaration which specifies the argument
3013types.)
3014
3015@item -Wold-style-definition @r{(C only)}
3016@opindex Wold-style-definition
3017Warn if an old-style function definition is used. A warning is given
3018even if there is a previous prototype.
3019
3020@item -Wmissing-prototypes @r{(C only)}
3021@opindex Wmissing-prototypes
3022Warn if a global function is defined without a previous prototype
3023declaration. This warning is issued even if the definition itself
3024provides a prototype. The aim is to detect global functions that fail
3025to be declared in header files.
3026
3027@item -Wmissing-declarations @r{(C only)}
3028@opindex Wmissing-declarations
3029Warn if a global function is defined without a previous declaration.
3030Do so even if the definition itself provides a prototype.
3031Use this option to detect global functions that are not declared in
3032header files.
3033
3034@item -Wmissing-field-initializers
3035@opindex Wmissing-field-initializers
3036@opindex W
3037@opindex Wextra
3038Warn if a structure's initializer has some fields missing. For
3039example, the following code would cause such a warning, because
3040@code{x.h} is implicitly zero:
3041
3042@smallexample
3043struct s @{ int f, g, h; @};
3044struct s x = @{ 3, 4 @};
3045@end smallexample
3046
3047This option does not warn about designated initializers, so the following
3048modification would not trigger a warning:
3049
3050@smallexample
3051struct s @{ int f, g, h; @};
3052struct s x = @{ .f = 3, .g = 4 @};
3053@end smallexample
3054
3055This warning is included in @option{-Wextra}. To get other @option{-Wextra}
3056warnings without this one, use @samp{-Wextra -Wno-missing-field-initializers}.
3057
3058@item -Wmissing-noreturn
3059@opindex Wmissing-noreturn
3060Warn about functions which might be candidates for attribute @code{noreturn}.
3061Note these are only possible candidates, not absolute ones. Care should
3062be taken to manually verify functions actually do not ever return before
3063adding the @code{noreturn} attribute, otherwise subtle code generation
3064bugs could be introduced. You will not get a warning for @code{main} in
3065hosted C environments.
3066
3067@item -Wmissing-format-attribute
3068@opindex Wmissing-format-attribute
3069@opindex Wformat
3070Warn about function pointers which might be candidates for @code{format}
3071attributes. Note these are only possible candidates, not absolute ones.
3072GCC will guess that function pointers with @code{format} attributes that
3073are used in assignment, initialization, parameter passing or return
3074statements should have a corresponding @code{format} attribute in the
3075resulting type. I.e.@: the left-hand side of the assignment or
3076initialization, the type of the parameter variable, or the return type
3077of the containing function respectively should also have a @code{format}
3078attribute to avoid the warning.
3079
3080GCC will also warn about function definitions which might be
3081candidates for @code{format} attributes. Again, these are only
3082possible candidates. GCC will guess that @code{format} attributes
3083might be appropriate for any function that calls a function like
3084@code{vprintf} or @code{vscanf}, but this might not always be the
3085case, and some functions for which @code{format} attributes are
3086appropriate may not be detected.
3087
3088@item -Wno-multichar
3089@opindex Wno-multichar
3090@opindex Wmultichar
3091Do not warn if a multicharacter constant (@samp{'FOOF'}) is used.
3092Usually they indicate a typo in the user's code, as they have
3093implementation-defined values, and should not be used in portable code.
3094
3095@item -Wnormalized=<none|id|nfc|nfkc>
3096@opindex Wnormalized
3097@cindex NFC
3098@cindex NFKC
3099@cindex character set, input normalization
3100In ISO C and ISO C++, two identifiers are different if they are
3101different sequences of characters. However, sometimes when characters
3102outside the basic ASCII character set are used, you can have two
3103different character sequences that look the same. To avoid confusion,
3104the ISO 10646 standard sets out some @dfn{normalization rules} which
3105when applied ensure that two sequences that look the same are turned into
3106the same sequence. GCC can warn you if you are using identifiers which
3107have not been normalized; this option controls that warning.
3108
3109There are four levels of warning that GCC supports. The default is
3110@option{-Wnormalized=nfc}, which warns about any identifier which is
3111not in the ISO 10646 ``C'' normalized form, @dfn{NFC}. NFC is the
3112recommended form for most uses.
3113
3114Unfortunately, there are some characters which ISO C and ISO C++ allow
3115in identifiers that when turned into NFC aren't allowable as
3116identifiers. That is, there's no way to use these symbols in portable
3117ISO C or C++ and have all your identifiers in NFC.
3118@option{-Wnormalized=id} suppresses the warning for these characters.
3119It is hoped that future versions of the standards involved will correct
3120this, which is why this option is not the default.
3121
3122You can switch the warning off for all characters by writing
3123@option{-Wnormalized=none}. You would only want to do this if you
3124were using some other normalization scheme (like ``D''), because
3125otherwise you can easily create bugs that are literally impossible to see.
3126
3127Some characters in ISO 10646 have distinct meanings but look identical
3128in some fonts or display methodologies, especially once formatting has
3129been applied. For instance @code{\u207F}, ``SUPERSCRIPT LATIN SMALL
3130LETTER N'', will display just like a regular @code{n} which has been
3131placed in a superscript. ISO 10646 defines the @dfn{NFKC}
3132normalization scheme to convert all these into a standard form as
3133well, and GCC will warn if your code is not in NFKC if you use
3134@option{-Wnormalized=nfkc}. This warning is comparable to warning
3135about every identifier that contains the letter O because it might be
3136confused with the digit 0, and so is not the default, but may be
3137useful as a local coding convention if the programming environment is
3138unable to be fixed to display these characters distinctly.
3139
3140@item -Wno-deprecated-declarations
3141@opindex Wno-deprecated-declarations
3142Do not warn about uses of functions (@pxref{Function Attributes}),
3143variables (@pxref{Variable Attributes}), and types (@pxref{Type
3144Attributes}) marked as deprecated by using the @code{deprecated}
3145attribute.
3146
3147@item -Wno-overflow
3148@opindex Wno-overflow
3149Do not warn about compile-time overflow in constant expressions.
3150
3151@item -Woverride-init
3152@opindex Woverride-init
3153@opindex W
3154@opindex Wextra
3155Warn if an initialized field without side effects is overridden when
3156using designated initializers (@pxref{Designated Inits, , Designated
3157Initializers}).
3158
3159This warning is included in @option{-Wextra}. To get other
3160@option{-Wextra} warnings without this one, use @samp{-Wextra
3161-Wno-override-init}.
3162
3163@item -Wpacked
3164@opindex Wpacked
3165Warn if a structure is given the packed attribute, but the packed
3166attribute has no effect on the layout or size of the structure.
3167Such structures may be mis-aligned for little benefit. For
3168instance, in this code, the variable @code{f.x} in @code{struct bar}
3169will be misaligned even though @code{struct bar} does not itself
3170have the packed attribute:
3171
3172@smallexample
3173@group
3174struct foo @{
3175 int x;
3176 char a, b, c, d;
3177@} __attribute__((packed));
3178struct bar @{
3179 char z;
3180 struct foo f;
3181@};
3182@end group
3183@end smallexample
3184
3185@item -Wpadded
3186@opindex Wpadded
3187Warn if padding is included in a structure, either to align an element
3188of the structure or to align the whole structure. Sometimes when this
3189happens it is possible to rearrange the fields of the structure to
3190reduce the padding and so make the structure smaller.
3191
3192@item -Wredundant-decls
3193@opindex Wredundant-decls
3194Warn if anything is declared more than once in the same scope, even in
3195cases where multiple declaration is valid and changes nothing.
3196
3197@item -Wnested-externs @r{(C only)}
3198@opindex Wnested-externs
3199Warn if an @code{extern} declaration is encountered within a function.
3200
3201@item -Wunreachable-code
3202@opindex Wunreachable-code
3203Warn if the compiler detects that code will never be executed.
3204
3205This option is intended to warn when the compiler detects that at
3206least a whole line of source code will never be executed, because
3207some condition is never satisfied or because it is after a
3208procedure that never returns.
3209
3210It is possible for this option to produce a warning even though there
3211are circumstances under which part of the affected line can be executed,
3212so care should be taken when removing apparently-unreachable code.
3213
3214For instance, when a function is inlined, a warning may mean that the
3215line is unreachable in only one inlined copy of the function.
3216
3217This option is not made part of @option{-Wall} because in a debugging
3218version of a program there is often substantial code which checks
3219correct functioning of the program and is, hopefully, unreachable
3220because the program does work. Another common use of unreachable
3221code is to provide behavior which is selectable at compile-time.
3222
3223@item -Winline
3224@opindex Winline
3225Warn if a function can not be inlined and it was declared as inline.
3226Even with this option, the compiler will not warn about failures to
3227inline functions declared in system headers.
3228
3229The compiler uses a variety of heuristics to determine whether or not
3230to inline a function. For example, the compiler takes into account
3231the size of the function being inlined and the amount of inlining
3232that has already been done in the current function. Therefore,
3233seemingly insignificant changes in the source program can cause the
3234warnings produced by @option{-Winline} to appear or disappear.
3235
3236@item -Wno-invalid-offsetof @r{(C++ only)}
3237@opindex Wno-invalid-offsetof
3238Suppress warnings from applying the @samp{offsetof} macro to a non-POD
3239type. According to the 1998 ISO C++ standard, applying @samp{offsetof}
3240to a non-POD type is undefined. In existing C++ implementations,
3241however, @samp{offsetof} typically gives meaningful results even when
3242applied to certain kinds of non-POD types. (Such as a simple
3243@samp{struct} that fails to be a POD type only by virtue of having a
3244constructor.) This flag is for users who are aware that they are
3245writing nonportable code and who have deliberately chosen to ignore the
3246warning about it.
3247
3248The restrictions on @samp{offsetof} may be relaxed in a future version
3249of the C++ standard.
3250
3251@item -Wno-int-to-pointer-cast @r{(C only)}
3252@opindex Wno-int-to-pointer-cast
3253Suppress warnings from casts to pointer type of an integer of a
3254different size.
3255
3256@item -Wno-pointer-to-int-cast @r{(C only)}
3257@opindex Wno-pointer-to-int-cast
3258Suppress warnings from casts from a pointer to an integer type of a
3259different size.
3260
3261@item -Winvalid-pch
3262@opindex Winvalid-pch
3263Warn if a precompiled header (@pxref{Precompiled Headers}) is found in
3264the search path but can't be used.
3265
3266@item -Wlong-long
3267@opindex Wlong-long
3268@opindex Wno-long-long
3269Warn if @samp{long long} type is used. This is default. To inhibit
3270the warning messages, use @option{-Wno-long-long}. Flags
3271@option{-Wlong-long} and @option{-Wno-long-long} are taken into account
3272only when @option{-pedantic} flag is used.
3273
3274@item -Wvariadic-macros
3275@opindex Wvariadic-macros
3276@opindex Wno-variadic-macros
3277Warn if variadic macros are used in pedantic ISO C90 mode, or the GNU
3278alternate syntax when in pedantic ISO C99 mode. This is default.
3279To inhibit the warning messages, use @option{-Wno-variadic-macros}.
3280
3281@item -Wvla
3282@opindex Wvla
3283@opindex Wno-vla
3284Warn if variable length array is used in the code.
3285@option{-Wno-vla} will prevent the @option{-pedantic} warning of
3286the variable length array.
3287
3288@item -Wvolatile-register-var
3289@opindex Wvolatile-register-var
3290@opindex Wno-volatile-register-var
3291Warn if a register variable is declared volatile. The volatile
3292modifier does not inhibit all optimizations that may eliminate reads
3293and/or writes to register variables.
3294
3295@item -Wdisabled-optimization
3296@opindex Wdisabled-optimization
3297Warn if a requested optimization pass is disabled. This warning does
3298not generally indicate that there is anything wrong with your code; it
3299merely indicates that GCC's optimizers were unable to handle the code
3300effectively. Often, the problem is that your code is too big or too
3301complex; GCC will refuse to optimize programs when the optimization
3302itself is likely to take inordinate amounts of time.
3303
3304@item -Wpointer-sign
3305@opindex Wpointer-sign
3306@opindex Wno-pointer-sign
3307Warn for pointer argument passing or assignment with different signedness.
3308This option is only supported for C. It is implied by @option{-Wall}
3309and by @option{-pedantic}, which can be disabled with
3310@option{-Wno-pointer-sign}.
3311
3312@item -Werror
3313@opindex Werror
3314Make all warnings into errors.
3315
3316@item -Werror=
3317@opindex Werror=
3318Make the specified warning into an errors. The specifier for a
3319warning is appended, for example @option{-Werror=switch} turns the
3320warnings controlled by @option{-Wswitch} into errors. This switch
3321takes a negative form, to be used to negate @option{-Werror} for
3322specific warnings, for example @option{-Wno-error=switch} makes
3323@option{-Wswitch} warnings not be errors, even when @option{-Werror}
3324is in effect. You can use the @option{-fdiagnostics-show-option}
3325option to have each controllable warning amended with the option which
3326controls it, to determine what to use with this option.
3327
3328Note that specifying @option{-Werror=}@var{foo} automatically implies
3329@option{-W}@var{foo}. However, @option{-Wno-error=}@var{foo} does not
3330imply anything.
3331
3332@item -Wstack-protector
3333@opindex Wstack-protector
3334This option is only active when @option{-fstack-protector} is active. It
3335warns about functions that will not be protected against stack smashing.
3336
3337@item -Woverlength-strings
3338@opindex Woverlength-strings
3339Warn about string constants which are longer than the ``minimum
3340maximum'' length specified in the C standard. Modern compilers
3341generally allow string constants which are much longer than the
3342standard's minimum limit, but very portable programs should avoid
3343using longer strings.
3344
3345The limit applies @emph{after} string constant concatenation, and does
3346not count the trailing NUL@. In C89, the limit was 509 characters; in
3347C99, it was raised to 4095. C++98 does not specify a normative
3348minimum maximum, so we do not diagnose overlength strings in C++@.
3349
3350This option is implied by @option{-pedantic}, and can be disabled with
3351@option{-Wno-overlength-strings}.
3352@end table
3353
3354@node Debugging Options
3355@section Options for Debugging Your Program or GCC
3356@cindex options, debugging
3357@cindex debugging information options
3358
3359GCC has various special options that are used for debugging
3360either your program or GCC:
3361
3362@table @gcctabopt
3363@item -g
3364@opindex g
3365Produce debugging information in the operating system's native format
3366(stabs, COFF, XCOFF, or DWARF 2)@. GDB can work with this debugging
3367information.
3368
3369On most systems that use stabs format, @option{-g} enables use of extra
3370debugging information that only GDB can use; this extra information
3371makes debugging work better in GDB but will probably make other debuggers
3372crash or
3373refuse to read the program. If you want to control for certain whether
3374to generate the extra information, use @option{-gstabs+}, @option{-gstabs},
3375@option{-gxcoff+}, @option{-gxcoff}, or @option{-gvms} (see below).
3376
3377GCC allows you to use @option{-g} with
3378@option{-O}. The shortcuts taken by optimized code may occasionally
3379produce surprising results: some variables you declared may not exist
3380at all; flow of control may briefly move where you did not expect it;
3381some statements may not be executed because they compute constant
3382results or their values were already at hand; some statements may
3383execute in different places because they were moved out of loops.
3384
3385Nevertheless it proves possible to debug optimized output. This makes
3386it reasonable to use the optimizer for programs that might have bugs.
3387
3388The following options are useful when GCC is generated with the
3389capability for more than one debugging format.
3390
3391@item -ggdb
3392@opindex ggdb
3393Produce debugging information for use by GDB@. This means to use the
3394most expressive format available (DWARF 2, stabs, or the native format
3395if neither of those are supported), including GDB extensions if at all
3396possible.
3397
3398@item -gstabs
3399@opindex gstabs
3400Produce debugging information in stabs format (if that is supported),
3401without GDB extensions. This is the format used by DBX on most BSD
3402systems. On MIPS, Alpha and System V Release 4 systems this option
3403produces stabs debugging output which is not understood by DBX or SDB@.
3404On System V Release 4 systems this option requires the GNU assembler.
3405
3406@item -feliminate-unused-debug-symbols
3407@opindex feliminate-unused-debug-symbols
3408Produce debugging information in stabs format (if that is supported),
3409for only symbols that are actually used.
3410
3411@item -femit-class-debug-always
3412Instead of emitting debugging information for a C++ class in only one
3413object file, emit it in all object files using the class. This option
3414should be used only with debuggers that are unable to handle the way GCC
3415normally emits debugging information for classes because using this
3416option will increase the size of debugging information by as much as a
3417factor of two.
3418
3419@item -gstabs+
3420@opindex gstabs+
3421Produce debugging information in stabs format (if that is supported),
3422using GNU extensions understood only by the GNU debugger (GDB)@. The
3423use of these extensions is likely to make other debuggers crash or
3424refuse to read the program.
3425
3426@item -gcoff
3427@opindex gcoff
3428Produce debugging information in COFF format (if that is supported).
3429This is the format used by SDB on most System V systems prior to
3430System V Release 4.
3431
3432@item -gxcoff
3433@opindex gxcoff
3434Produce debugging information in XCOFF format (if that is supported).
3435This is the format used by the DBX debugger on IBM RS/6000 systems.
3436
3437@item -gxcoff+
3438@opindex gxcoff+
3439Produce debugging information in XCOFF format (if that is supported),
3440using GNU extensions understood only by the GNU debugger (GDB)@. The
3441use of these extensions is likely to make other debuggers crash or
3442refuse to read the program, and may cause assemblers other than the GNU
3443assembler (GAS) to fail with an error.
3444
3445@item -gdwarf-2
3446@opindex gdwarf-2
3447Produce debugging information in DWARF version 2 format (if that is
3448supported). This is the format used by DBX on IRIX 6. With this
3449option, GCC uses features of DWARF version 3 when they are useful;
3450version 3 is upward compatible with version 2, but may still cause
3451problems for older debuggers.
3452
3453@item -gvms
3454@opindex gvms
3455Produce debugging information in VMS debug format (if that is
3456supported). This is the format used by DEBUG on VMS systems.
3457
3458@item -g@var{level}
3459@itemx -ggdb@var{level}
3460@itemx -gstabs@var{level}
3461@itemx -gcoff@var{level}
3462@itemx -gxcoff@var{level}
3463@itemx -gvms@var{level}
3464Request debugging information and also use @var{level} to specify how
3465much information. The default level is 2.
3466
3467Level 1 produces minimal information, enough for making backtraces in
3468parts of the program that you don't plan to debug. This includes
3469descriptions of functions and external variables, but no information
3470about local variables and no line numbers.
3471
3472Level 3 includes extra information, such as all the macro definitions
3473present in the program. Some debuggers support macro expansion when
3474you use @option{-g3}.
3475
3476@option{-gdwarf-2} does not accept a concatenated debug level, because
3477GCC used to support an option @option{-gdwarf} that meant to generate
3478debug information in version 1 of the DWARF format (which is very
3479different from version 2), and it would have been too confusing. That
3480debug format is long obsolete, but the option cannot be changed now.
3481Instead use an additional @option{-g@var{level}} option to change the
3482debug level for DWARF2.
3483
3484@item -feliminate-dwarf2-dups
3485@opindex feliminate-dwarf2-dups
3486Compress DWARF2 debugging information by eliminating duplicated
3487information about each symbol. This option only makes sense when
3488generating DWARF2 debugging information with @option{-gdwarf-2}.
3489
3490@item -femit-struct-debug-baseonly
3491Emit debug information for struct-like types
3492only when the base name of the compilation source file
3493matches the base name of file in which the struct was defined.
3494
3495This option substantially reduces the size of debugging information,
3496but at significant potential loss in type information to the debugger.
3497See @option{-femit-struct-debug-reduced} for a less aggressive option.
3498See @option{-femit-struct-debug-detailed} for more detailed control.
3499
3500This option works only with DWARF 2.
3501
3502@item -femit-struct-debug-reduced
3503Emit debug information for struct-like types
3504only when the base name of the compilation source file
3505matches the base name of file in which the type was defined,
3506unless the struct is a template or defined in a system header.
3507
3508This option significantly reduces the size of debugging information,
3509with some potential loss in type information to the debugger.
3510See @option{-femit-struct-debug-baseonly} for a more aggressive option.
3511See @option{-femit-struct-debug-detailed} for more detailed control.
3512
3513This option works only with DWARF 2.
3514
3515@item -femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]}
3516Specify the struct-like types
3517for which the compiler will generate debug information.
3518The intent is to reduce duplicate struct debug information
3519between different object files within the same program.
3520
3521This option is a detailed version of
3522@option{-femit-struct-debug-reduced} and @option{-femit-struct-debug-baseonly},
3523which will serve for most needs.
3524
3525A specification has the syntax
3526[@samp{dir:}|@samp{ind:}][@samp{ord:}|@samp{gen:}](@samp{any}|@samp{sys}|@samp{base}|@samp{none})
3527
3528The optional first word limits the specification to
3529structs that are used directly (@samp{dir:}) or used indirectly (@samp{ind:}).
3530A struct type is used directly when it is the type of a variable, member.
3531Indirect uses arise through pointers to structs.
3532That is, when use of an incomplete struct would be legal, the use is indirect.
3533An example is
3534@samp{struct one direct; struct two * indirect;}.
3535
3536The optional second word limits the specification to
3537ordinary structs (@samp{ord:}) or generic structs (@samp{gen:}).
3538Generic structs are a bit complicated to explain.
3539For C++, these are non-explicit specializations of template classes,
3540or non-template classes within the above.
3541Other programming languages have generics,
3542but @samp{-femit-struct-debug-detailed} does not yet implement them.
3543
3544The third word specifies the source files for those
3545structs for which the compiler will emit debug information.
3546The values @samp{none} and @samp{any} have the normal meaning.
3547The value @samp{base} means that
3548the base of name of the file in which the type declaration appears
3549must match the base of the name of the main compilation file.
3550In practice, this means that
3551types declared in @file{foo.c} and @file{foo.h} will have debug information,
3552but types declared in other header will not.
3553The value @samp{sys} means those types satisfying @samp{base}
3554or declared in system or compiler headers.
3555
3556You may need to experiment to determine the best settings for your application.
3557
3558The default is @samp{-femit-struct-debug-detailed=all}.
3559
3560This option works only with DWARF 2.
3561
3562@cindex @command{prof}
3563@item -p
3564@opindex p
3565Generate extra code to write profile information suitable for the
3566analysis program @command{prof}. You must use this option when compiling
3567the source files you want data about, and you must also use it when
3568linking.
3569
3570@cindex @command{gprof}
3571@item -pg
3572@opindex pg
3573Generate extra code to write profile information suitable for the
3574analysis program @command{gprof}. You must use this option when compiling
3575the source files you want data about, and you must also use it when
3576linking.
3577
3578@item -Q
3579@opindex Q
3580Makes the compiler print out each function name as it is compiled, and
3581print some statistics about each pass when it finishes.
3582
3583@item -ftime-report
3584@opindex ftime-report
3585Makes the compiler print some statistics about the time consumed by each
3586pass when it finishes.
3587
3588@item -fmem-report
3589@opindex fmem-report
3590Makes the compiler print some statistics about permanent memory
3591allocation when it finishes.
3592
3593@item -fprofile-arcs
3594@opindex fprofile-arcs
3595Add code so that program flow @dfn{arcs} are instrumented. During
3596execution the program records how many times each branch and call is
3597executed and how many times it is taken or returns. When the compiled
3598program exits it saves this data to a file called
3599@file{@var{auxname}.gcda} for each source file. The data may be used for
3600profile-directed optimizations (@option{-fbranch-probabilities}), or for
3601test coverage analysis (@option{-ftest-coverage}). Each object file's
3602@var{auxname} is generated from the name of the output file, if
3603explicitly specified and it is not the final executable, otherwise it is
3604the basename of the source file. In both cases any suffix is removed
3605(e.g.@: @file{foo.gcda} for input file @file{dir/foo.c}, or
3606@file{dir/foo.gcda} for output file specified as @option{-o dir/foo.o}).
3607@xref{Cross-profiling}.
3608
3609@cindex @command{gcov}
3610@item --coverage
3611@opindex coverage
3612
3613This option is used to compile and link code instrumented for coverage
3614analysis. The option is a synonym for @option{-fprofile-arcs}
3615@option{-ftest-coverage} (when compiling) and @option{-lgcov} (when
3616linking). See the documentation for those options for more details.
3617
3618@itemize
3619
3620@item
3621Compile the source files with @option{-fprofile-arcs} plus optimization
3622and code generation options. For test coverage analysis, use the
3623additional @option{-ftest-coverage} option. You do not need to profile
3624every source file in a program.
3625
3626@item
3627Link your object files with @option{-lgcov} or @option{-fprofile-arcs}
3628(the latter implies the former).
3629
3630@item
3631Run the program on a representative workload to generate the arc profile
3632information. This may be repeated any number of times. You can run
3633concurrent instances of your program, and provided that the file system
3634supports locking, the data files will be correctly updated. Also
3635@code{fork} calls are detected and correctly handled (double counting
3636will not happen).
3637
3638@item
3639For profile-directed optimizations, compile the source files again with
3640the same optimization and code generation options plus
3641@option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that
3642Control Optimization}).
3643
3644@item
3645For test coverage analysis, use @command{gcov} to produce human readable
3646information from the @file{.gcno} and @file{.gcda} files. Refer to the
3647@command{gcov} documentation for further information.
3648
3649@end itemize
3650
3651With @option{-fprofile-arcs}, for each function of your program GCC
3652creates a program flow graph, then finds a spanning tree for the graph.
3653Only arcs that are not on the spanning tree have to be instrumented: the
3654compiler adds code to count the number of times that these arcs are
3655executed. When an arc is the only exit or only entrance to a block, the
3656instrumentation code can be added to the block; otherwise, a new basic
3657block must be created to hold the instrumentation code.
3658
3659@need 2000
3660@item -ftest-coverage
3661@opindex ftest-coverage
3662Produce a notes file that the @command{gcov} code-coverage utility
3663(@pxref{Gcov,, @command{gcov}---a Test Coverage Program}) can use to
3664show program coverage. Each source file's note file is called
3665@file{@var{auxname}.gcno}. Refer to the @option{-fprofile-arcs} option
3666above for a description of @var{auxname} and instructions on how to
3667generate test coverage data. Coverage data will match the source files
3668more closely, if you do not optimize.
3669
3670@item -d@var{letters}
3671@item -fdump-rtl-@var{pass}
3672@opindex d
3673Says to make debugging dumps during compilation at times specified by
3674@var{letters}. This is used for debugging the RTL-based passes of the
3675compiler. The file names for most of the dumps are made by appending a
3676pass number and a word to the @var{dumpname}. @var{dumpname} is generated
3677from the name of the output file, if explicitly specified and it is not
3678an executable, otherwise it is the basename of the source file.
3679
3680Most debug dumps can be enabled either passing a letter to the @option{-d}
3681option, or with a long @option{-fdump-rtl} switch; here are the possible
3682letters for use in @var{letters} and @var{pass}, and their meanings:
3683
3684@table @gcctabopt
3685@item -dA
3686@opindex dA
3687Annotate the assembler output with miscellaneous debugging information.
3688
3689@item -dB
3690@itemx -fdump-rtl-bbro
3691@opindex dB
3692@opindex fdump-rtl-bbro
3693Dump after block reordering, to @file{@var{file}.148r.bbro}.
3694
3695@item -dc
3696@itemx -fdump-rtl-combine
3697@opindex dc
3698@opindex fdump-rtl-combine
3699Dump after instruction combination, to the file @file{@var{file}.129r.combine}.
3700
3701@item -dC
3702@itemx -fdump-rtl-ce1
3703@itemx -fdump-rtl-ce2
3704@opindex dC
3705@opindex fdump-rtl-ce1
3706@opindex fdump-rtl-ce2
3707@option{-dC} and @option{-fdump-rtl-ce1} enable dumping after the
3708first if conversion, to the file @file{@var{file}.117r.ce1}. @option{-dC}
3709and @option{-fdump-rtl-ce2} enable dumping after the second if
3710conversion, to the file @file{@var{file}.130r.ce2}.
3711
3712@item -dd
3713@itemx -fdump-rtl-btl
3714@itemx -fdump-rtl-dbr
3715@opindex dd
3716@opindex fdump-rtl-btl
3717@opindex fdump-rtl-dbr
3718@option{-dd} and @option{-fdump-rtl-btl} enable dumping after branch
3719target load optimization, to @file{@var{file}.31.btl}. @option{-dd}
3720and @option{-fdump-rtl-dbr} enable dumping after delayed branch
3721scheduling, to @file{@var{file}.36.dbr}.
3722
3723@item -dD
3724@opindex dD
3725Dump all macro definitions, at the end of preprocessing, in addition to
3726normal output.
3727
3728@item -dE
3729@itemx -fdump-rtl-ce3
3730@opindex dE
3731@opindex fdump-rtl-ce3
3732Dump after the third if conversion, to @file{@var{file}.146r.ce3}.
3733
3734@item -df
3735@itemx -fdump-rtl-cfg
3736@itemx -fdump-rtl-life
3737@opindex df
3738@opindex fdump-rtl-cfg
3739@opindex fdump-rtl-life
3740@option{-df} and @option{-fdump-rtl-cfg} enable dumping after control
3741and data flow analysis, to @file{@var{file}.116r.cfg}. @option{-df}
3742and @option{-fdump-rtl-cfg} enable dumping dump after life analysis,
3743to @file{@var{file}.128r.life1} and @file{@var{file}.135r.life2}.
3744
3745@item -dg
3746@itemx -fdump-rtl-greg
3747@opindex dg
3748@opindex fdump-rtl-greg
3749Dump after global register allocation, to @file{@var{file}.139r.greg}.
3750
3751@item -dG
3752@itemx -fdump-rtl-gcse
3753@itemx -fdump-rtl-bypass
3754@opindex dG
3755@opindex fdump-rtl-gcse
3756@opindex fdump-rtl-bypass
3757@option{-dG} and @option{-fdump-rtl-gcse} enable dumping after GCSE, to
3758@file{@var{file}.114r.gcse}. @option{-dG} and @option{-fdump-rtl-bypass}
3759enable dumping after jump bypassing and control flow optimizations, to
3760@file{@var{file}.115r.bypass}.
3761
3762@item -dh
3763@itemx -fdump-rtl-eh
3764@opindex dh
3765@opindex fdump-rtl-eh
3766Dump after finalization of EH handling code, to @file{@var{file}.02.eh}.
3767
3768@item -di
3769@itemx -fdump-rtl-sibling
3770@opindex di
3771@opindex fdump-rtl-sibling
3772Dump after sibling call optimizations, to @file{@var{file}.106r.sibling}.
3773
3774@item -dj
3775@itemx -fdump-rtl-jump
3776@opindex dj
3777@opindex fdump-rtl-jump
3778Dump after the first jump optimization, to @file{@var{file}.112r.jump}.
3779
3780@item -dk
3781@itemx -fdump-rtl-stack
3782@opindex dk
3783@opindex fdump-rtl-stack
3784Dump after conversion from registers to stack, to @file{@var{file}.152r.stack}.
3785
3786@item -dl
3787@itemx -fdump-rtl-lreg
3788@opindex dl
3789@opindex fdump-rtl-lreg
3790Dump after local register allocation, to @file{@var{file}.138r.lreg}.
3791
3792@item -dL
3793@itemx -fdump-rtl-loop2
3794@opindex dL
3795@opindex fdump-rtl-loop2
3796@option{-dL} and @option{-fdump-rtl-loop2} enable dumping after the
3797loop optimization pass, to @file{@var{file}.119r.loop2},
3798@file{@var{file}.120r.loop2_init},
3799@file{@var{file}.121r.loop2_invariant}, and
3800@file{@var{file}.125r.loop2_done}.
3801
3802@item -dm
3803@itemx -fdump-rtl-sms
3804@opindex dm
3805@opindex fdump-rtl-sms
3806Dump after modulo scheduling, to @file{@var{file}.136r.sms}.
3807
3808@item -dM
3809@itemx -fdump-rtl-mach
3810@opindex dM
3811@opindex fdump-rtl-mach
3812Dump after performing the machine dependent reorganization pass, to
3813@file{@var{file}.155r.mach}.
3814
3815@item -dn
3816@itemx -fdump-rtl-rnreg
3817@opindex dn
3818@opindex fdump-rtl-rnreg
3819Dump after register renumbering, to @file{@var{file}.147r.rnreg}.
3820
3821@item -dN
3822@itemx -fdump-rtl-regmove
3823@opindex dN
3824@opindex fdump-rtl-regmove
3825Dump after the register move pass, to @file{@var{file}.132r.regmove}.
3826
3827@item -do
3828@itemx -fdump-rtl-postreload
3829@opindex do
3830@opindex fdump-rtl-postreload
3831Dump after post-reload optimizations, to @file{@var{file}.24.postreload}.
3832
3833@item -dr
3834@itemx -fdump-rtl-expand
3835@opindex dr
3836@opindex fdump-rtl-expand
3837Dump after RTL generation, to @file{@var{file}.104r.expand}.
3838
3839@item -dR
3840@itemx -fdump-rtl-sched2
3841@opindex dR
3842@opindex fdump-rtl-sched2
3843Dump after the second scheduling pass, to @file{@var{file}.150r.sched2}.
3844
3845@item -ds
3846@itemx -fdump-rtl-cse
3847@opindex ds
3848@opindex fdump-rtl-cse
3849Dump after CSE (including the jump optimization that sometimes follows
3850CSE), to @file{@var{file}.113r.cse}.
3851
3852@item -dS
3853@itemx -fdump-rtl-sched
3854@opindex dS
3855@opindex fdump-rtl-sched
3856Dump after the first scheduling pass, to @file{@var{file}.21.sched}.
3857
3858@item -dt
3859@itemx -fdump-rtl-cse2
3860@opindex dt
3861@opindex fdump-rtl-cse2
3862Dump after the second CSE pass (including the jump optimization that
3863sometimes follows CSE), to @file{@var{file}.127r.cse2}.
3864
3865@item -dT
3866@itemx -fdump-rtl-tracer
3867@opindex dT
3868@opindex fdump-rtl-tracer
3869Dump after running tracer, to @file{@var{file}.118r.tracer}.
3870
3871@item -dV
3872@itemx -fdump-rtl-vpt
3873@itemx -fdump-rtl-vartrack
3874@opindex dV
3875@opindex fdump-rtl-vpt
3876@opindex fdump-rtl-vartrack
3877@option{-dV} and @option{-fdump-rtl-vpt} enable dumping after the value
3878profile transformations, to @file{@var{file}.10.vpt}. @option{-dV}
3879and @option{-fdump-rtl-vartrack} enable dumping after variable tracking,
3880to @file{@var{file}.154r.vartrack}.
3881
3882@item -dw
3883@itemx -fdump-rtl-flow2
3884@opindex dw
3885@opindex fdump-rtl-flow2
3886Dump after the second flow pass, to @file{@var{file}.142r.flow2}.
3887
3888@item -dz
3889@itemx -fdump-rtl-peephole2
3890@opindex dz
3891@opindex fdump-rtl-peephole2
3892Dump after the peephole pass, to @file{@var{file}.145r.peephole2}.
3893
3894@item -dZ
3895@itemx -fdump-rtl-web
3896@opindex dZ
3897@opindex fdump-rtl-web
3898Dump after live range splitting, to @file{@var{file}.126r.web}.
3899
3900@item -da
3901@itemx -fdump-rtl-all
3902@opindex da
3903@opindex fdump-rtl-all
3904Produce all the dumps listed above.
3905
3906@item -dH
3907@opindex dH
3908Produce a core dump whenever an error occurs.
3909
3910@item -dm
3911@opindex dm
3912Print statistics on memory usage, at the end of the run, to
3913standard error.
3914
3915@item -dp
3916@opindex dp
3917Annotate the assembler output with a comment indicating which
3918pattern and alternative was used. The length of each instruction is
3919also printed.
3920
3921@item -dP
3922@opindex dP
3923Dump the RTL in the assembler output as a comment before each instruction.
3924Also turns on @option{-dp} annotation.
3925
3926@item -dv
3927@opindex dv
3928For each of the other indicated dump files (either with @option{-d} or
3929@option{-fdump-rtl-@var{pass}}), dump a representation of the control flow
3930graph suitable for viewing with VCG to @file{@var{file}.@var{pass}.vcg}.
3931
3932@item -dx
3933@opindex dx
3934Just generate RTL for a function instead of compiling it. Usually used
3935with @samp{r} (@option{-fdump-rtl-expand}).
3936
3937@item -dy
3938@opindex dy
3939Dump debugging information during parsing, to standard error.
3940@end table
3941
3942@item -fdump-noaddr
3943@opindex fdump-noaddr
3944When doing debugging dumps (see @option{-d} option above), suppress
3945address output. This makes it more feasible to use diff on debugging
3946dumps for compiler invocations with different compiler binaries and/or
3947different text / bss / data / heap / stack / dso start locations.
3948
3949@item -fdump-unnumbered
3950@opindex fdump-unnumbered
3951When doing debugging dumps (see @option{-d} option above), suppress instruction
3952numbers, line number note and address output. This makes it more feasible to
3953use diff on debugging dumps for compiler invocations with different
3954options, in particular with and without @option{-g}.
3955
3956@item -fdump-translation-unit @r{(C++ only)}
3957@itemx -fdump-translation-unit-@var{options} @r{(C++ only)}
3958@opindex fdump-translation-unit
3959Dump a representation of the tree structure for the entire translation
3960unit to a file. The file name is made by appending @file{.tu} to the
3961source file name. If the @samp{-@var{options}} form is used, @var{options}
3962controls the details of the dump as described for the
3963@option{-fdump-tree} options.
3964
3965@item -fdump-class-hierarchy @r{(C++ only)}
3966@itemx -fdump-class-hierarchy-@var{options} @r{(C++ only)}
3967@opindex fdump-class-hierarchy
3968Dump a representation of each class's hierarchy and virtual function
3969table layout to a file. The file name is made by appending @file{.class}
3970to the source file name. If the @samp{-@var{options}} form is used,
3971@var{options} controls the details of the dump as described for the
3972@option{-fdump-tree} options.
3973
3974@item -fdump-ipa-@var{switch}
3975@opindex fdump-ipa
3976Control the dumping at various stages of inter-procedural analysis
3977language tree to a file. The file name is generated by appending a switch
3978specific suffix to the source file name. The following dumps are possible:
3979
3980@table @samp
3981@item all
3982Enables all inter-procedural analysis dumps; currently the only produced
3983dump is the @samp{cgraph} dump.
3984
3985@item cgraph
3986Dumps information about call-graph optimization, unused function removal,
3987and inlining decisions.
3988@end table
3989
3990@item -fdump-tree-@var{switch}
3991@itemx -fdump-tree-@var{switch}-@var{options}
3992@opindex fdump-tree
3993Control the dumping at various stages of processing the intermediate
3994language tree to a file. The file name is generated by appending a switch
3995specific suffix to the source file name. If the @samp{-@var{options}}
3996form is used, @var{options} is a list of @samp{-} separated options that
3997control the details of the dump. Not all options are applicable to all
3998dumps, those which are not meaningful will be ignored. The following
3999options are available
4000
4001@table @samp
4002@item address
4003Print the address of each node. Usually this is not meaningful as it
4004changes according to the environment and source file. Its primary use
4005is for tying up a dump file with a debug environment.
4006@item slim
4007Inhibit dumping of members of a scope or body of a function merely
4008because that scope has been reached. Only dump such items when they
4009are directly reachable by some other path. When dumping pretty-printed
4010trees, this option inhibits dumping the bodies of control structures.
4011@item raw
4012Print a raw representation of the tree. By default, trees are
4013pretty-printed into a C-like representation.
4014@item details
4015Enable more detailed dumps (not honored by every dump option).
4016@item stats
4017Enable dumping various statistics about the pass (not honored by every dump
4018option).
4019@item blocks
4020Enable showing basic block boundaries (disabled in raw dumps).
4021@item vops
4022Enable showing virtual operands for every statement.
4023@item lineno
4024Enable showing line numbers for statements.
4025@item uid
4026Enable showing the unique ID (@code{DECL_UID}) for each variable.
4027@item all
4028Turn on all options, except @option{raw}, @option{slim} and @option{lineno}.
4029@end table
4030
4031The following tree dumps are possible:
4032@table @samp
4033
4034@item original
4035Dump before any tree based optimization, to @file{@var{file}.original}.
4036
4037@item optimized
4038Dump after all tree based optimization, to @file{@var{file}.optimized}.
4039
4040@item inlined
4041Dump after function inlining, to @file{@var{file}.inlined}.
4042
4043@item gimple
4044@opindex fdump-tree-gimple
4045Dump each function before and after the gimplification pass to a file. The
4046file name is made by appending @file{.gimple} to the source file name.
4047
4048@item cfg
4049@opindex fdump-tree-cfg
4050Dump the control flow graph of each function to a file. The file name is
4051made by appending @file{.cfg} to the source file name.
4052
4053@item vcg
4054@opindex fdump-tree-vcg
4055Dump the control flow graph of each function to a file in VCG format. The
4056file name is made by appending @file{.vcg} to the source file name. Note
4057that if the file contains more than one function, the generated file cannot
4058be used directly by VCG@. You will need to cut and paste each function's
4059graph into its own separate file first.
4060
4061@item ch
4062@opindex fdump-tree-ch
4063Dump each function after copying loop headers. The file name is made by
4064appending @file{.ch} to the source file name.
4065
4066@item ssa
4067@opindex fdump-tree-ssa
4068Dump SSA related information to a file. The file name is made by appending
4069@file{.ssa} to the source file name.
4070
4071@item salias
4072@opindex fdump-tree-salias
4073Dump structure aliasing variable information to a file. This file name
4074is made by appending @file{.salias} to the source file name.
4075
4076@item alias
4077@opindex fdump-tree-alias
4078Dump aliasing information for each function. The file name is made by
4079appending @file{.alias} to the source file name.
4080
4081@item ccp
4082@opindex fdump-tree-ccp
4083Dump each function after CCP@. The file name is made by appending
4084@file{.ccp} to the source file name.
4085
4086@item storeccp
4087@opindex fdump-tree-storeccp
4088Dump each function after STORE-CCP. The file name is made by appending
4089@file{.storeccp} to the source file name.
4090
4091@item pre
4092@opindex fdump-tree-pre
4093Dump trees after partial redundancy elimination. The file name is made
4094by appending @file{.pre} to the source file name.
4095
4096@item fre
4097@opindex fdump-tree-fre
4098Dump trees after full redundancy elimination. The file name is made
4099by appending @file{.fre} to the source file name.
4100
4101@item copyprop
4102@opindex fdump-tree-copyprop
4103Dump trees after copy propagation. The file name is made
4104by appending @file{.copyprop} to the source file name.
4105
4106@item store_copyprop
4107@opindex fdump-tree-store_copyprop
4108Dump trees after store copy-propagation. The file name is made
4109by appending @file{.store_copyprop} to the source file name.
4110
4111@item dce
4112@opindex fdump-tree-dce
4113Dump each function after dead code elimination. The file name is made by
4114appending @file{.dce} to the source file name.
4115
4116@item mudflap
4117@opindex fdump-tree-mudflap
4118Dump each function after adding mudflap instrumentation. The file name is
4119made by appending @file{.mudflap} to the source file name.
4120
4121@item sra
4122@opindex fdump-tree-sra
4123Dump each function after performing scalar replacement of aggregates. The
4124file name is made by appending @file{.sra} to the source file name.
4125
4126@item sink
4127@opindex fdump-tree-sink
4128Dump each function after performing code sinking. The file name is made
4129by appending @file{.sink} to the source file name.
4130
4131@item dom
4132@opindex fdump-tree-dom
4133Dump each function after applying dominator tree optimizations. The file
4134name is made by appending @file{.dom} to the source file name.
4135
4136@item dse
4137@opindex fdump-tree-dse
4138Dump each function after applying dead store elimination. The file
4139name is made by appending @file{.dse} to the source file name.
4140
4141@item phiopt
4142@opindex fdump-tree-phiopt
4143Dump each function after optimizing PHI nodes into straightline code. The file
4144name is made by appending @file{.phiopt} to the source file name.
4145
4146@item forwprop
4147@opindex fdump-tree-forwprop
4148Dump each function after forward propagating single use variables. The file
4149name is made by appending @file{.forwprop} to the source file name.
4150
4151@item copyrename
4152@opindex fdump-tree-copyrename
4153Dump each function after applying the copy rename optimization. The file
4154name is made by appending @file{.copyrename} to the source file name.
4155
4156@item nrv
4157@opindex fdump-tree-nrv
4158Dump each function after applying the named return value optimization on
4159generic trees. The file name is made by appending @file{.nrv} to the source
4160file name.
4161
4162@item vect
4163@opindex fdump-tree-vect
4164Dump each function after applying vectorization of loops. The file name is
4165made by appending @file{.vect} to the source file name.
4166
4167@item vrp
4168@opindex fdump-tree-vrp
4169Dump each function after Value Range Propagation (VRP). The file name
4170is made by appending @file{.vrp} to the source file name.
4171
4172@item all
4173@opindex fdump-tree-all
4174Enable all the available tree dumps with the flags provided in this option.
4175@end table
4176
4177@item -ftree-vectorizer-verbose=@var{n}
4178@opindex ftree-vectorizer-verbose
4179This option controls the amount of debugging output the vectorizer prints.
4180This information is written to standard error, unless
4181@option{-fdump-tree-all} or @option{-fdump-tree-vect} is specified,
4182in which case it is output to the usual dump listing file, @file{.vect}.
4183For @var{n}=0 no diagnostic information is reported.
4184If @var{n}=1 the vectorizer reports each loop that got vectorized,
4185and the total number of loops that got vectorized.
4186If @var{n}=2 the vectorizer also reports non-vectorized loops that passed
4187the first analysis phase (vect_analyze_loop_form) - i.e. countable,
4188inner-most, single-bb, single-entry/exit loops. This is the same verbosity
4189level that @option{-fdump-tree-vect-stats} uses.
4190Higher verbosity levels mean either more information dumped for each
4191reported loop, or same amount of information reported for more loops:
4192If @var{n}=3, alignment related information is added to the reports.
4193If @var{n}=4, data-references related information (e.g. memory dependences,
4194memory access-patterns) is added to the reports.
4195If @var{n}=5, the vectorizer reports also non-vectorized inner-most loops
4196that did not pass the first analysis phase (i.e. may not be countable, or
4197may have complicated control-flow).
4198If @var{n}=6, the vectorizer reports also non-vectorized nested loops.
4199For @var{n}=7, all the information the vectorizer generates during its
4200analysis and transformation is reported. This is the same verbosity level
4201that @option{-fdump-tree-vect-details} uses.
4202
4203@item -frandom-seed=@var{string}
4204@opindex frandom-string
4205This option provides a seed that GCC uses when it would otherwise use
4206random numbers. It is used to generate certain symbol names
4207that have to be different in every compiled file. It is also used to
4208place unique stamps in coverage data files and the object files that
4209produce them. You can use the @option{-frandom-seed} option to produce
4210reproducibly identical object files.
4211
4212The @var{string} should be different for every file you compile.
4213
4214@item -fsched-verbose=@var{n}
4215@opindex fsched-verbose
4216On targets that use instruction scheduling, this option controls the
4217amount of debugging output the scheduler prints. This information is
4218written to standard error, unless @option{-dS} or @option{-dR} is
4219specified, in which case it is output to the usual dump
4220listing file, @file{.sched} or @file{.sched2} respectively. However
4221for @var{n} greater than nine, the output is always printed to standard
4222error.
4223
4224For @var{n} greater than zero, @option{-fsched-verbose} outputs the
4225same information as @option{-dRS}. For @var{n} greater than one, it
4226also output basic block probabilities, detailed ready list information
4227and unit/insn info. For @var{n} greater than two, it includes RTL
4228at abort point, control-flow and regions info. And for @var{n} over
4229four, @option{-fsched-verbose} also includes dependence info.
4230
4231@item -save-temps
4232@opindex save-temps
4233Store the usual ``temporary'' intermediate files permanently; place them
4234in the current directory and name them based on the source file. Thus,
4235compiling @file{foo.c} with @samp{-c -save-temps} would produce files
4236@file{foo.i} and @file{foo.s}, as well as @file{foo.o}. This creates a
4237preprocessed @file{foo.i} output file even though the compiler now
4238normally uses an integrated preprocessor.
4239
4240When used in combination with the @option{-x} command line option,
4241@option{-save-temps} is sensible enough to avoid over writing an
4242input source file with the same extension as an intermediate file.
4243The corresponding intermediate file may be obtained by renaming the
4244source file before using @option{-save-temps}.
4245
4246@item -time
4247@opindex time
4248Report the CPU time taken by each subprocess in the compilation
4249sequence. For C source files, this is the compiler proper and assembler
4250(plus the linker if linking is done). The output looks like this:
4251
4252@smallexample
4253# cc1 0.12 0.01
4254# as 0.00 0.01
4255@end smallexample
4256
4257The first number on each line is the ``user time'', that is time spent
4258executing the program itself. The second number is ``system time'',
4259time spent executing operating system routines on behalf of the program.
4260Both numbers are in seconds.
4261
4262@item -fvar-tracking
4263@opindex fvar-tracking
4264Run variable tracking pass. It computes where variables are stored at each
4265position in code. Better debugging information is then generated
4266(if the debugging information format supports this information).
4267
4268It is enabled by default when compiling with optimization (@option{-Os},
4269@option{-O}, @option{-O2}, ...), debugging information (@option{-g}) and
4270the debug info format supports it.
4271
4272@item -print-file-name=@var{library}
4273@opindex print-file-name
4274Print the full absolute name of the library file @var{library} that
4275would be used when linking---and don't do anything else. With this
4276option, GCC does not compile or link anything; it just prints the
4277file name.
4278
4279@item -print-multi-directory
4280@opindex print-multi-directory
4281Print the directory name corresponding to the multilib selected by any
4282other switches present in the command line. This directory is supposed
4283to exist in @env{GCC_EXEC_PREFIX}.
4284
4285@item -print-multi-lib
4286@opindex print-multi-lib
4287Print the mapping from multilib directory names to compiler switches
4288that enable them. The directory name is separated from the switches by
4289@samp{;}, and each switch starts with an @samp{@@} instead of the
4290@samp{-}, without spaces between multiple switches. This is supposed to
4291ease shell-processing.
4292
4293@item -print-prog-name=@var{program}
4294@opindex print-prog-name
4295Like @option{-print-file-name}, but searches for a program such as @samp{cpp}.
4296
4297@item -print-libgcc-file-name
4298@opindex print-libgcc-file-name
4299Same as @option{-print-file-name=libgcc.a}.
4300
4301This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs}
4302but you do want to link with @file{libgcc.a}. You can do
4303
4304@smallexample
4305gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
4306@end smallexample
4307
4308@item -print-search-dirs
4309@opindex print-search-dirs
4310Print the name of the configured installation directory and a list of
4311program and library directories @command{gcc} will search---and don't do anything else.
4312
4313This is useful when @command{gcc} prints the error message
4314@samp{installation problem, cannot exec cpp0: No such file or directory}.
4315To resolve this you either need to put @file{cpp0} and the other compiler
4316components where @command{gcc} expects to find them, or you can set the environment
4317variable @env{GCC_EXEC_PREFIX} to the directory where you installed them.
4318Don't forget the trailing @samp{/}.
4319@xref{Environment Variables}.
4320
4321@item -dumpmachine
4322@opindex dumpmachine
4323Print the compiler's target machine (for example,
4324@samp{i686-pc-linux-gnu})---and don't do anything else.
4325
4326@item -dumpversion
4327@opindex dumpversion
4328Print the compiler version (for example, @samp{3.0})---and don't do
4329anything else.
4330
4331@item -dumpspecs
4332@opindex dumpspecs
4333Print the compiler's built-in specs---and don't do anything else. (This
4334is used when GCC itself is being built.) @xref{Spec Files}.
4335
4336@item -feliminate-unused-debug-types
4337@opindex feliminate-unused-debug-types
4338Normally, when producing DWARF2 output, GCC will emit debugging
4339information for all types declared in a compilation
4340unit, regardless of whether or not they are actually used
4341in that compilation unit. Sometimes this is useful, such as
4342if, in the debugger, you want to cast a value to a type that is
4343not actually used in your program (but is declared). More often,
4344however, this results in a significant amount of wasted space.
4345With this option, GCC will avoid producing debug symbol output
4346for types that are nowhere used in the source file being compiled.
4347@end table
4348
4349@node Optimize Options
4350@section Options That Control Optimization
4351@cindex optimize options
4352@cindex options, optimization
4353
4354These options control various sorts of optimizations.
4355
4356Without any optimization option, the compiler's goal is to reduce the
4357cost of compilation and to make debugging produce the expected
4358results. Statements are independent: if you stop the program with a
4359breakpoint between statements, you can then assign a new value to any
4360variable or change the program counter to any other statement in the
4361function and get exactly the results you would expect from the source
4362code.
4363
4364Turning on optimization flags makes the compiler attempt to improve
4365the performance and/or code size at the expense of compilation time
4366and possibly the ability to debug the program.
4367
4368The compiler performs optimization based on the knowledge it has of
4369the program. Optimization levels @option{-O} and above, in
4370particular, enable @emph{unit-at-a-time} mode, which allows the
4371compiler to consider information gained from later functions in
4372the file when compiling a function. Compiling multiple files at
4373once to a single output file in @emph{unit-at-a-time} mode allows
4374the compiler to use information gained from all of the files when
4375compiling each of them.
4376
4377Not all optimizations are controlled directly by a flag. Only
4378optimizations that have a flag are listed.
4379
4380@table @gcctabopt
4381@item -O
4382@itemx -O1
4383@opindex O
4384@opindex O1
4385Optimize. Optimizing compilation takes somewhat more time, and a lot
4386more memory for a large function.
4387
4388With @option{-O}, the compiler tries to reduce code size and execution
4389time, without performing any optimizations that take a great deal of
4390compilation time.
4391
4392@option{-O} turns on the following optimization flags:
4393@gccoptlist{-fdefer-pop @gol
4394-fdelayed-branch @gol
4395-fguess-branch-probability @gol
4396-fcprop-registers @gol
4397-fif-conversion @gol
4398-fif-conversion2 @gol
4399-ftree-ccp @gol
4400-ftree-dce @gol
4401-ftree-dominator-opts @gol
4402-ftree-dse @gol
4403-ftree-ter @gol
4404-ftree-lrs @gol
4405-ftree-sra @gol
4406-ftree-copyrename @gol
4407-ftree-fre @gol
4408-ftree-ch @gol
4409-funit-at-a-time @gol
4410-fmerge-constants}
4411
4412@option{-O} also turns on @option{-fomit-frame-pointer} on machines
4413where doing so does not interfere with debugging.
4414
4415@item -O2
4416@opindex O2
4417Optimize even more. GCC performs nearly all supported optimizations
4418that do not involve a space-speed tradeoff. The compiler does not
4419perform loop unrolling or function inlining when you specify @option{-O2}.
4420As compared to @option{-O}, this option increases both compilation time
4421and the performance of the generated code.
4422
4423@option{-O2} turns on all optimization flags specified by @option{-O}. It
4424also turns on the following optimization flags:
4425@gccoptlist{-fthread-jumps @gol
4426-fcrossjumping @gol
4427-foptimize-sibling-calls @gol
4428-fcse-follow-jumps -fcse-skip-blocks @gol
4429-fgcse -fgcse-lm @gol
4430-fexpensive-optimizations @gol
4431-frerun-cse-after-loop @gol
4432-fcaller-saves @gol
4433-fpeephole2 @gol
4434-fschedule-insns -fschedule-insns2 @gol
4435-fsched-interblock -fsched-spec @gol
4436-fregmove @gol
4437-fstrict-aliasing -fstrict-overflow @gol
4438-fdelete-null-pointer-checks @gol
4439-freorder-blocks -freorder-functions @gol
4440-falign-functions -falign-jumps @gol
4441-falign-loops -falign-labels @gol
4442-ftree-vrp @gol
4443-ftree-pre}
4444
4445Please note the warning under @option{-fgcse} about
4446invoking @option{-O2} on programs that use computed gotos.
4447
4448@option{-O2} doesn't turn on @option{-ftree-vrp} for the Ada compiler.
4449This option must be explicitly specified on the command line to be
4450enabled for the Ada compiler.
4451
4452@item -O3
4453@opindex O3
4454Optimize yet more. @option{-O3} turns on all optimizations specified by
4455@option{-O2} and also turns on the @option{-finline-functions},
4456@option{-funswitch-loops} and @option{-fgcse-after-reload} options.
4457
4458@item -O0
4459@opindex O0
4460Do not optimize. This is the default.
4461
4462@item -Os
4463@opindex Os
4464Optimize for size. @option{-Os} enables all @option{-O2} optimizations that
4465do not typically increase code size. It also performs further
4466optimizations designed to reduce code size.
4467
4468@option{-Os} disables the following optimization flags:
4469@gccoptlist{-falign-functions -falign-jumps -falign-loops @gol
4470-falign-labels -freorder-blocks -freorder-blocks-and-partition @gol
4471-fprefetch-loop-arrays -ftree-vect-loop-version}
4472
4473If you use multiple @option{-O} options, with or without level numbers,
4474the last such option is the one that is effective.
4475@end table
4476
4477Options of the form @option{-f@var{flag}} specify machine-independent
4478flags. Most flags have both positive and negative forms; the negative
4479form of @option{-ffoo} would be @option{-fno-foo}. In the table
4480below, only one of the forms is listed---the one you typically will
4481use. You can figure out the other form by either removing @samp{no-}
4482or adding it.
4483
4484The following options control specific optimizations. They are either
4485activated by @option{-O} options or are related to ones that are. You
4486can use the following flags in the rare cases when ``fine-tuning'' of
4487optimizations to be performed is desired.
4488
4489@table @gcctabopt
4490@item -fno-default-inline
4491@opindex fno-default-inline
4492Do not make member functions inline by default merely because they are
4493defined inside the class scope (C++ only). Otherwise, when you specify
4494@w{@option{-O}}, member functions defined inside class scope are compiled
4495inline by default; i.e., you don't need to add @samp{inline} in front of
4496the member function name.
4497
4498@item -fno-defer-pop
4499@opindex fno-defer-pop
4500Always pop the arguments to each function call as soon as that function
4501returns. For machines which must pop arguments after a function call,
4502the compiler normally lets arguments accumulate on the stack for several
4503function calls and pops them all at once.
4504
4505Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4506
4507@item -fforce-mem
4508@opindex fforce-mem
4509Force memory operands to be copied into registers before doing
4510arithmetic on them. This produces better code by making all memory
4511references potential common subexpressions. When they are not common
4512subexpressions, instruction combination should eliminate the separate
4513register-load. This option is now a nop and will be removed in 4.3.
4514
4515@item -fforce-addr
4516@opindex fforce-addr
4517Force memory address constants to be copied into registers before
4518doing arithmetic on them.
4519
4520@item -fomit-frame-pointer
4521@opindex fomit-frame-pointer
4522Don't keep the frame pointer in a register for functions that
4523don't need one. This avoids the instructions to save, set up and
4524restore frame pointers; it also makes an extra register available
4525in many functions. @strong{It also makes debugging impossible on
4526some machines.}
4527
4528On some machines, such as the VAX, this flag has no effect, because
4529the standard calling sequence automatically handles the frame pointer
4530and nothing is saved by pretending it doesn't exist. The
4531machine-description macro @code{FRAME_POINTER_REQUIRED} controls
4532whether a target machine supports this flag. @xref{Registers,,Register
4533Usage, gccint, GNU Compiler Collection (GCC) Internals}.
4534
4535Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4536
4537@item -foptimize-sibling-calls
4538@opindex foptimize-sibling-calls
4539Optimize sibling and tail recursive calls.
4540
4541Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4542
4543@item -fno-inline
4544@opindex fno-inline
4545Don't pay attention to the @code{inline} keyword. Normally this option
4546is used to keep the compiler from expanding any functions inline.
4547Note that if you are not optimizing, no functions can be expanded inline.
4548
4549@item -finline-functions
4550@opindex finline-functions
4551Integrate all simple functions into their callers. The compiler
4552heuristically decides which functions are simple enough to be worth
4553integrating in this way.
4554
4555If all calls to a given function are integrated, and the function is
4556declared @code{static}, then the function is normally not output as
4557assembler code in its own right.
4558
4559Enabled at level @option{-O3}.
4560
4561@item -finline-functions-called-once
4562@opindex finline-functions-called-once
4563Consider all @code{static} functions called once for inlining into their
4564caller even if they are not marked @code{inline}. If a call to a given
4565function is integrated, then the function is not output as assembler code
4566in its own right.
4567
4568Enabled if @option{-funit-at-a-time} is enabled.
4569
4570@item -fearly-inlining
4571@opindex fearly-inlining
4572Inline functions marked by @code{always_inline} and functions whose body seems
4573smaller than the function call overhead early before doing
4574@option{-fprofile-generate} instrumentation and real inlining pass. Doing so
4575makes profiling significantly cheaper and usually inlining faster on programs
4576having large chains of nested wrapper functions.
4577
4578Enabled by default.
4579
4580@item -finline-limit=@var{n}
4581@opindex finline-limit
4582By default, GCC limits the size of functions that can be inlined. This flag
4583allows the control of this limit for functions that are explicitly marked as
4584inline (i.e., marked with the inline keyword or defined within the class
4585definition in c++). @var{n} is the size of functions that can be inlined in
4586number of pseudo instructions (not counting parameter handling). The default
4587value of @var{n} is 600.
4588Increasing this value can result in more inlined code at
4589the cost of compilation time and memory consumption. Decreasing usually makes
4590the compilation faster and less code will be inlined (which presumably
4591means slower programs). This option is particularly useful for programs that
4592use inlining heavily such as those based on recursive templates with C++.
4593
4594Inlining is actually controlled by a number of parameters, which may be
4595specified individually by using @option{--param @var{name}=@var{value}}.
4596The @option{-finline-limit=@var{n}} option sets some of these parameters
4597as follows:
4598
4599@table @gcctabopt
4600@item max-inline-insns-single
4601 is set to @var{n}/2.
4602@item max-inline-insns-auto
4603 is set to @var{n}/2.
4604@item min-inline-insns
4605 is set to 130 or @var{n}/4, whichever is smaller.
4606@item max-inline-insns-rtl
4607 is set to @var{n}.
4608@end table
4609
4610See below for a documentation of the individual
4611parameters controlling inlining.
4612
4613@emph{Note:} pseudo instruction represents, in this particular context, an
4614abstract measurement of function's size. In no way does it represent a count
4615of assembly instructions and as such its exact meaning might change from one
4616release to an another.
4617
4618@item -fkeep-inline-functions
4619@opindex fkeep-inline-functions
4620In C, emit @code{static} functions that are declared @code{inline}
4621into the object file, even if the function has been inlined into all
4622of its callers. This switch does not affect functions using the
4623@code{extern inline} extension in GNU C@. In C++, emit any and all
4624inline functions into the object file.
4625
4626@item -fkeep-static-consts
4627@opindex fkeep-static-consts
4628Emit variables declared @code{static const} when optimization isn't turned
4629on, even if the variables aren't referenced.
4630
4631GCC enables this option by default. If you want to force the compiler to
4632check if the variable was referenced, regardless of whether or not
4633optimization is turned on, use the @option{-fno-keep-static-consts} option.
4634
4635@item -fmerge-constants
4636Attempt to merge identical constants (string constants and floating point
4637constants) across compilation units.
4638
4639This option is the default for optimized compilation if the assembler and
4640linker support it. Use @option{-fno-merge-constants} to inhibit this
4641behavior.
4642
4643Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4644
4645@item -fmerge-all-constants
4646Attempt to merge identical constants and identical variables.
4647
4648This option implies @option{-fmerge-constants}. In addition to
4649@option{-fmerge-constants} this considers e.g.@: even constant initialized
4650arrays or initialized constant variables with integral or floating point
4651types. Languages like C or C++ require each non-automatic variable to
4652have distinct location, so using this option will result in non-conforming
4653behavior.
4654
4655@item -fmodulo-sched
4656@opindex fmodulo-sched
4657Perform swing modulo scheduling immediately before the first scheduling
4658pass. This pass looks at innermost loops and reorders their
4659instructions by overlapping different iterations.
4660
4661@item -fno-branch-count-reg
4662@opindex fno-branch-count-reg
4663Do not use ``decrement and branch'' instructions on a count register,
4664but instead generate a sequence of instructions that decrement a
4665register, compare it against zero, then branch based upon the result.
4666This option is only meaningful on architectures that support such
4667instructions, which include x86, PowerPC, IA-64 and S/390.
4668
4669The default is @option{-fbranch-count-reg}.
4670
4671@item -fno-function-cse
4672@opindex fno-function-cse
4673Do not put function addresses in registers; make each instruction that
4674calls a constant function contain the function's address explicitly.
4675
4676This option results in less efficient code, but some strange hacks
4677that alter the assembler output may be confused by the optimizations
4678performed when this option is not used.
4679
4680The default is @option{-ffunction-cse}
4681
4682@item -fno-zero-initialized-in-bss
4683@opindex fno-zero-initialized-in-bss
4684If the target supports a BSS section, GCC by default puts variables that
4685are initialized to zero into BSS@. This can save space in the resulting
4686code.
4687
4688This option turns off this behavior because some programs explicitly
4689rely on variables going to the data section. E.g., so that the
4690resulting executable can find the beginning of that section and/or make
4691assumptions based on that.
4692
4693The default is @option{-fzero-initialized-in-bss}.
4694
4695@item -fbounds-check
4696@opindex fbounds-check
4697For front-ends that support it, generate additional code to check that
4698indices used to access arrays are within the declared range. This is
4699currently only supported by the Java and Fortran front-ends, where
4700this option defaults to true and false respectively.
4701
4702@item -fmudflap -fmudflapth -fmudflapir
4703@opindex fmudflap
4704@opindex fmudflapth
4705@opindex fmudflapir
4706@cindex bounds checking
4707@cindex mudflap
4708For front-ends that support it (C and C++), instrument all risky
4709pointer/array dereferencing operations, some standard library
4710string/heap functions, and some other associated constructs with
4711range/validity tests. Modules so instrumented should be immune to
4712buffer overflows, invalid heap use, and some other classes of C/C++
4713programming errors. The instrumentation relies on a separate runtime
4714library (@file{libmudflap}), which will be linked into a program if
4715@option{-fmudflap} is given at link time. Run-time behavior of the
4716instrumented program is controlled by the @env{MUDFLAP_OPTIONS}
4717environment variable. See @code{env MUDFLAP_OPTIONS=-help a.out}
4718for its options.
4719
4720Use @option{-fmudflapth} instead of @option{-fmudflap} to compile and to
4721link if your program is multi-threaded. Use @option{-fmudflapir}, in
4722addition to @option{-fmudflap} or @option{-fmudflapth}, if
4723instrumentation should ignore pointer reads. This produces less
4724instrumentation (and therefore faster execution) and still provides
4725some protection against outright memory corrupting writes, but allows
4726erroneously read data to propagate within a program.
4727
4728@item -fthread-jumps
4729@opindex fthread-jumps
4730Perform optimizations where we check to see if a jump branches to a
4731location where another comparison subsumed by the first is found. If
4732so, the first branch is redirected to either the destination of the
4733second branch or a point immediately following it, depending on whether
4734the condition is known to be true or false.
4735
4736Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4737
4738@item -fcse-follow-jumps
4739@opindex fcse-follow-jumps
4740In common subexpression elimination, scan through jump instructions
4741when the target of the jump is not reached by any other path. For
4742example, when CSE encounters an @code{if} statement with an
4743@code{else} clause, CSE will follow the jump when the condition
4744tested is false.
4745
4746Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4747
4748@item -fcse-skip-blocks
4749@opindex fcse-skip-blocks
4750This is similar to @option{-fcse-follow-jumps}, but causes CSE to
4751follow jumps which conditionally skip over blocks. When CSE
4752encounters a simple @code{if} statement with no else clause,
4753@option{-fcse-skip-blocks} causes CSE to follow the jump around the
4754body of the @code{if}.
4755
4756Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4757
4758@item -frerun-cse-after-loop
4759@opindex frerun-cse-after-loop
4760Re-run common subexpression elimination after loop optimizations has been
4761performed.
4762
4763Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4764
4765@item -fgcse
4766@opindex fgcse
4767Perform a global common subexpression elimination pass.
4768This pass also performs global constant and copy propagation.
4769
4770@emph{Note:} When compiling a program using computed gotos, a GCC
4771extension, you may get better runtime performance if you disable
4772the global common subexpression elimination pass by adding
4773@option{-fno-gcse} to the command line.
4774
4775Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4776
4777@item -fgcse-lm
4778@opindex fgcse-lm
4779When @option{-fgcse-lm} is enabled, global common subexpression elimination will
4780attempt to move loads which are only killed by stores into themselves. This
4781allows a loop containing a load/store sequence to be changed to a load outside
4782the loop, and a copy/store within the loop.
4783
4784Enabled by default when gcse is enabled.
4785
4786@item -fgcse-sm
4787@opindex fgcse-sm
4788When @option{-fgcse-sm} is enabled, a store motion pass is run after
4789global common subexpression elimination. This pass will attempt to move
4790stores out of loops. When used in conjunction with @option{-fgcse-lm},
4791loops containing a load/store sequence can be changed to a load before
4792the loop and a store after the loop.
4793
4794Not enabled at any optimization level.
4795
4796@item -fgcse-las
4797@opindex fgcse-las
4798When @option{-fgcse-las} is enabled, the global common subexpression
4799elimination pass eliminates redundant loads that come after stores to the
4800same memory location (both partial and full redundancies).
4801
4802Not enabled at any optimization level.
4803
4804@item -fgcse-after-reload
4805@opindex fgcse-after-reload
4806When @option{-fgcse-after-reload} is enabled, a redundant load elimination
4807pass is performed after reload. The purpose of this pass is to cleanup
4808redundant spilling.
4809
4810@item -funsafe-loop-optimizations
4811@opindex funsafe-loop-optimizations
4812If given, the loop optimizer will assume that loop indices do not
4813overflow, and that the loops with nontrivial exit condition are not
4814infinite. This enables a wider range of loop optimizations even if
4815the loop optimizer itself cannot prove that these assumptions are valid.
4816Using @option{-Wunsafe-loop-optimizations}, the compiler will warn you
4817if it finds this kind of loop.
4818
4819@item -fcrossjumping
4820@opindex crossjumping
4821Perform cross-jumping transformation. This transformation unifies equivalent code and save code size. The
4822resulting code may or may not perform better than without cross-jumping.
4823
4824Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4825
4826@item -fif-conversion
4827@opindex if-conversion
4828Attempt to transform conditional jumps into branch-less equivalents. This
4829include use of conditional moves, min, max, set flags and abs instructions, and
4830some tricks doable by standard arithmetics. The use of conditional execution
4831on chips where it is available is controlled by @code{if-conversion2}.
4832
4833Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4834
4835@item -fif-conversion2
4836@opindex if-conversion2
4837Use conditional execution (where available) to transform conditional jumps into
4838branch-less equivalents.
4839
4840Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4841
4842@item -fdelete-null-pointer-checks
4843@opindex fdelete-null-pointer-checks
4844Use global dataflow analysis to identify and eliminate useless checks
4845for null pointers. The compiler assumes that dereferencing a null
4846pointer would have halted the program. If a pointer is checked after
4847it has already been dereferenced, it cannot be null.
4848
4849In some environments, this assumption is not true, and programs can
4850safely dereference null pointers. Use
4851@option{-fno-delete-null-pointer-checks} to disable this optimization
4852for programs which depend on that behavior.
4853
4854Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4855
4856@item -fexpensive-optimizations
4857@opindex fexpensive-optimizations
4858Perform a number of minor optimizations that are relatively expensive.
4859
4860Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4861
4862@item -foptimize-register-move
4863@itemx -fregmove
4864@opindex foptimize-register-move
4865@opindex fregmove
4866Attempt to reassign register numbers in move instructions and as
4867operands of other simple instructions in order to maximize the amount of
4868register tying. This is especially helpful on machines with two-operand
4869instructions.
4870
4871Note @option{-fregmove} and @option{-foptimize-register-move} are the same
4872optimization.
4873
4874Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4875
4876@item -fdelayed-branch
4877@opindex fdelayed-branch
4878If supported for the target machine, attempt to reorder instructions
4879to exploit instruction slots available after delayed branch
4880instructions.
4881
4882Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4883
4884@item -fschedule-insns
4885@opindex fschedule-insns
4886If supported for the target machine, attempt to reorder instructions to
4887eliminate execution stalls due to required data being unavailable. This
4888helps machines that have slow floating point or memory load instructions
4889by allowing other instructions to be issued until the result of the load
4890or floating point instruction is required.
4891
4892Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4893
4894@item -fschedule-insns2
4895@opindex fschedule-insns2
4896Similar to @option{-fschedule-insns}, but requests an additional pass of
4897instruction scheduling after register allocation has been done. This is
4898especially useful on machines with a relatively small number of
4899registers and where memory load instructions take more than one cycle.
4900
4901Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4902
4903@item -fno-sched-interblock
4904@opindex fno-sched-interblock
4905Don't schedule instructions across basic blocks. This is normally
4906enabled by default when scheduling before register allocation, i.e.@:
4907with @option{-fschedule-insns} or at @option{-O2} or higher.
4908
4909@item -fno-sched-spec
4910@opindex fno-sched-spec
4911Don't allow speculative motion of non-load instructions. This is normally
4912enabled by default when scheduling before register allocation, i.e.@:
4913with @option{-fschedule-insns} or at @option{-O2} or higher.
4914
4915@item -fsched-spec-load
4916@opindex fsched-spec-load
4917Allow speculative motion of some load instructions. This only makes
4918sense when scheduling before register allocation, i.e.@: with
4919@option{-fschedule-insns} or at @option{-O2} or higher.
4920
4921@item -fsched-spec-load-dangerous
4922@opindex fsched-spec-load-dangerous
4923Allow speculative motion of more load instructions. This only makes
4924sense when scheduling before register allocation, i.e.@: with
4925@option{-fschedule-insns} or at @option{-O2} or higher.
4926
4927@item -fsched-stalled-insns=@var{n}
4928@opindex fsched-stalled-insns
4929Define how many insns (if any) can be moved prematurely from the queue
4930of stalled insns into the ready list, during the second scheduling pass.
4931
4932@item -fsched-stalled-insns-dep=@var{n}
4933@opindex fsched-stalled-insns-dep
4934Define how many insn groups (cycles) will be examined for a dependency
4935on a stalled insn that is candidate for premature removal from the queue
4936of stalled insns. Has an effect only during the second scheduling pass,
4937and only if @option{-fsched-stalled-insns} is used and its value is not zero.
4938
4939@item -fsched2-use-superblocks
4940@opindex fsched2-use-superblocks
4941When scheduling after register allocation, do use superblock scheduling
4942algorithm. Superblock scheduling allows motion across basic block boundaries
4943resulting on faster schedules. This option is experimental, as not all machine
4944descriptions used by GCC model the CPU closely enough to avoid unreliable
4945results from the algorithm.
4946
4947This only makes sense when scheduling after register allocation, i.e.@: with
4948@option{-fschedule-insns2} or at @option{-O2} or higher.
4949
4950@item -fsched2-use-traces
4951@opindex fsched2-use-traces
4952Use @option{-fsched2-use-superblocks} algorithm when scheduling after register
4953allocation and additionally perform code duplication in order to increase the
4954size of superblocks using tracer pass. See @option{-ftracer} for details on
4955trace formation.
4956
4957This mode should produce faster but significantly longer programs. Also
4958without @option{-fbranch-probabilities} the traces constructed may not
4959match the reality and hurt the performance. This only makes
4960sense when scheduling after register allocation, i.e.@: with
4961@option{-fschedule-insns2} or at @option{-O2} or higher.
4962
4963@item -fsee
4964@opindex fsee
4965Eliminates redundant extension instructions and move the non redundant
4966ones to optimal placement using LCM.
4967
4968@item -freschedule-modulo-scheduled-loops
4969@opindex fscheduling-in-modulo-scheduled-loops
4970The modulo scheduling comes before the traditional scheduling, if a loop was modulo scheduled
4971we may want to prevent the later scheduling passes from changing its schedule, we use this
4972option to control that.
4973
4974@item -fcaller-saves
4975@opindex fcaller-saves
4976Enable values to be allocated in registers that will be clobbered by
4977function calls, by emitting extra instructions to save and restore the
4978registers around such calls. Such allocation is done only when it
4979seems to result in better code than would otherwise be produced.
4980
4981This option is always enabled by default on certain machines, usually
4982those which have no call-preserved registers to use instead.
4983
4984Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4985
4986@item -ftree-pre
4987Perform Partial Redundancy Elimination (PRE) on trees. This flag is
4988enabled by default at @option{-O2} and @option{-O3}.
4989
4990@item -ftree-fre
4991Perform Full Redundancy Elimination (FRE) on trees. The difference
4992between FRE and PRE is that FRE only considers expressions
4993that are computed on all paths leading to the redundant computation.
4994This analysis faster than PRE, though it exposes fewer redundancies.
4995This flag is enabled by default at @option{-O} and higher.
4996
4997@item -ftree-copy-prop
4998Perform copy propagation on trees. This pass eliminates unnecessary
4999copy operations. This flag is enabled by default at @option{-O} and
5000higher.
5001
5002@item -ftree-store-copy-prop
5003Perform copy propagation of memory loads and stores. This pass
5004eliminates unnecessary copy operations in memory references
5005(structures, global variables, arrays, etc). This flag is enabled by
5006default at @option{-O2} and higher.
5007
5008@item -ftree-salias
5009Perform structural alias analysis on trees. This flag
5010is enabled by default at @option{-O} and higher.
5011
5012@item -fipa-pta
5013Perform interprocedural pointer analysis.
5014
5015@item -ftree-sink
5016Perform forward store motion on trees. This flag is
5017enabled by default at @option{-O} and higher.
5018
5019@item -ftree-ccp
5020Perform sparse conditional constant propagation (CCP) on trees. This
5021pass only operates on local scalar variables and is enabled by default
5022at @option{-O} and higher.
5023
5024@item -ftree-store-ccp
5025Perform sparse conditional constant propagation (CCP) on trees. This
5026pass operates on both local scalar variables and memory stores and
5027loads (global variables, structures, arrays, etc). This flag is
5028enabled by default at @option{-O2} and higher.
5029
5030@item -ftree-dce
5031Perform dead code elimination (DCE) on trees. This flag is enabled by
5032default at @option{-O} and higher.
5033
5034@item -ftree-dominator-opts
5035Perform a variety of simple scalar cleanups (constant/copy
5036propagation, redundancy elimination, range propagation and expression
5037simplification) based on a dominator tree traversal. This also
5038performs jump threading (to reduce jumps to jumps). This flag is
5039enabled by default at @option{-O} and higher.
5040
5041@item -ftree-ch
5042Perform loop header copying on trees. This is beneficial since it increases
5043effectiveness of code motion optimizations. It also saves one jump. This flag
5044is enabled by default at @option{-O} and higher. It is not enabled
5045for @option{-Os}, since it usually increases code size.
5046
5047@item -ftree-loop-optimize
5048Perform loop optimizations on trees. This flag is enabled by default
5049at @option{-O} and higher.
5050
5051@item -ftree-loop-linear
5052Perform linear loop transformations on tree. This flag can improve cache
5053performance and allow further loop optimizations to take place.
5054
5055@item -ftree-loop-im
5056Perform loop invariant motion on trees. This pass moves only invariants that
5057would be hard to handle at RTL level (function calls, operations that expand to
5058nontrivial sequences of insns). With @option{-funswitch-loops} it also moves
5059operands of conditions that are invariant out of the loop, so that we can use
5060just trivial invariantness analysis in loop unswitching. The pass also includes
5061store motion.
5062
5063@item -ftree-loop-ivcanon
5064Create a canonical counter for number of iterations in the loop for that
5065determining number of iterations requires complicated analysis. Later
5066optimizations then may determine the number easily. Useful especially
5067in connection with unrolling.
5068
5069@item -fivopts
5070Perform induction variable optimizations (strength reduction, induction
5071variable merging and induction variable elimination) on trees.
5072
5073@item -ftree-sra
5074Perform scalar replacement of aggregates. This pass replaces structure
5075references with scalars to prevent committing structures to memory too
5076early. This flag is enabled by default at @option{-O} and higher.
5077
5078@item -ftree-copyrename
5079Perform copy renaming on trees. This pass attempts to rename compiler
5080temporaries to other variables at copy locations, usually resulting in
5081variable names which more closely resemble the original variables. This flag
5082is enabled by default at @option{-O} and higher.
5083
5084@item -ftree-ter
5085Perform temporary expression replacement during the SSA->normal phase. Single
5086use/single def temporaries are replaced at their use location with their
5087defining expression. This results in non-GIMPLE code, but gives the expanders
5088much more complex trees to work on resulting in better RTL generation. This is
5089enabled by default at @option{-O} and higher.
5090
5091@item -ftree-lrs
5092Perform live range splitting during the SSA->normal phase. Distinct live
5093ranges of a variable are split into unique variables, allowing for better
5094optimization later. This is enabled by default at @option{-O} and higher.
5095
5096@item -ftree-vectorize
5097Perform loop vectorization on trees.
5098
5099@item -ftree-vect-loop-version
5100@opindex ftree-vect-loop-version
5101Perform loop versioning when doing loop vectorization on trees. When a loop
5102appears to be vectorizable except that data alignment or data dependence cannot
5103be determined at compile time then vectorized and non-vectorized versions of
5104the loop are generated along with runtime checks for alignment or dependence
5105to control which version is executed. This option is enabled by default
5106except at level @option{-Os} where it is disabled.
5107
5108@item -ftree-vrp
5109Perform Value Range Propagation on trees. This is similar to the
5110constant propagation pass, but instead of values, ranges of values are
5111propagated. This allows the optimizers to remove unnecessary range
5112checks like array bound checks and null pointer checks. This is
5113enabled by default at @option{-O2} and higher. Null pointer check
5114elimination is only done if @option{-fdelete-null-pointer-checks} is
5115enabled.
5116
5117@item -ftracer
5118@opindex ftracer
5119Perform tail duplication to enlarge superblock size. This transformation
5120simplifies the control flow of the function allowing other optimizations to do
5121better job.
5122
5123@item -funroll-loops
5124@opindex funroll-loops
5125Unroll loops whose number of iterations can be determined at compile
5126time or upon entry to the loop. @option{-funroll-loops} implies
5127@option{-frerun-cse-after-loop}. This option makes code larger,
5128and may or may not make it run faster.
5129
5130@item -funroll-all-loops
5131@opindex funroll-all-loops
5132Unroll all loops, even if their number of iterations is uncertain when
5133the loop is entered. This usually makes programs run more slowly.
5134@option{-funroll-all-loops} implies the same options as
5135@option{-funroll-loops},
5136
5137@item -fsplit-ivs-in-unroller
5138@opindex fsplit-ivs-in-unroller
5139Enables expressing of values of induction variables in later iterations
5140of the unrolled loop using the value in the first iteration. This breaks
5141long dependency chains, thus improving efficiency of the scheduling passes.
5142
5143Combination of @option{-fweb} and CSE is often sufficient to obtain the
5144same effect. However in cases the loop body is more complicated than
5145a single basic block, this is not reliable. It also does not work at all
5146on some of the architectures due to restrictions in the CSE pass.
5147
5148This optimization is enabled by default.
5149
5150@item -fvariable-expansion-in-unroller
5151@opindex fvariable-expansion-in-unroller
5152With this option, the compiler will create multiple copies of some
5153local variables when unrolling a loop which can result in superior code.
5154
5155@item -fprefetch-loop-arrays
5156@opindex fprefetch-loop-arrays
5157If supported by the target machine, generate instructions to prefetch
5158memory to improve the performance of loops that access large arrays.
5159
5160This option may generate better or worse code; results are highly
5161dependent on the structure of loops within the source code.
5162
5163Disabled at level @option{-Os}.
5164
5165@item -fno-peephole
5166@itemx -fno-peephole2
5167@opindex fno-peephole
5168@opindex fno-peephole2
5169Disable any machine-specific peephole optimizations. The difference
5170between @option{-fno-peephole} and @option{-fno-peephole2} is in how they
5171are implemented in the compiler; some targets use one, some use the
5172other, a few use both.
5173
5174@option{-fpeephole} is enabled by default.
5175@option{-fpeephole2} enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5176
5177@item -fno-guess-branch-probability
5178@opindex fno-guess-branch-probability
5179Do not guess branch probabilities using heuristics.
5180
5181GCC will use heuristics to guess branch probabilities if they are
5182not provided by profiling feedback (@option{-fprofile-arcs}). These
5183heuristics are based on the control flow graph. If some branch probabilities
5184are specified by @samp{__builtin_expect}, then the heuristics will be
5185used to guess branch probabilities for the rest of the control flow graph,
5186taking the @samp{__builtin_expect} info into account. The interactions
5187between the heuristics and @samp{__builtin_expect} can be complex, and in
5188some cases, it may be useful to disable the heuristics so that the effects
5189of @samp{__builtin_expect} are easier to understand.
5190
5191The default is @option{-fguess-branch-probability} at levels
5192@option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5193
5194@item -freorder-blocks
5195@opindex freorder-blocks
5196Reorder basic blocks in the compiled function in order to reduce number of
5197taken branches and improve code locality.
5198
5199Enabled at levels @option{-O2}, @option{-O3}.
5200
5201@item -freorder-blocks-and-partition
5202@opindex freorder-blocks-and-partition
5203In addition to reordering basic blocks in the compiled function, in order
5204to reduce number of taken branches, partitions hot and cold basic blocks
5205into separate sections of the assembly and .o files, to improve
5206paging and cache locality performance.
5207
5208This optimization is automatically turned off in the presence of
5209exception handling, for linkonce sections, for functions with a user-defined
5210section attribute and on any architecture that does not support named
5211sections.
5212
5213@item -freorder-functions
5214@opindex freorder-functions
5215Reorder functions in the object file in order to
5216improve code locality. This is implemented by using special
5217subsections @code{.text.hot} for most frequently executed functions and
5218@code{.text.unlikely} for unlikely executed functions. Reordering is done by
5219the linker so object file format must support named sections and linker must
5220place them in a reasonable way.
5221
5222Also profile feedback must be available in to make this option effective. See
5223@option{-fprofile-arcs} for details.
5224
5225Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5226
5227@item -fstrict-aliasing
5228@opindex fstrict-aliasing
5229Allows the compiler to assume the strictest aliasing rules applicable to
5230the language being compiled. For C (and C++), this activates
5231optimizations based on the type of expressions. In particular, an
5232object of one type is assumed never to reside at the same address as an
5233object of a different type, unless the types are almost the same. For
5234example, an @code{unsigned int} can alias an @code{int}, but not a
5235@code{void*} or a @code{double}. A character type may alias any other
5236type.
5237
5238Pay special attention to code like this:
5239@smallexample
5240union a_union @{
5241 int i;
5242 double d;
5243@};
5244
5245int f() @{
5246 a_union t;
5247 t.d = 3.0;
5248 return t.i;
5249@}
5250@end smallexample
5251The practice of reading from a different union member than the one most
5252recently written to (called ``type-punning'') is common. Even with
5253@option{-fstrict-aliasing}, type-punning is allowed, provided the memory
5254is accessed through the union type. So, the code above will work as
5255expected. However, this code might not:
5256@smallexample
5257int f() @{
5258 a_union t;
5259 int* ip;
5260 t.d = 3.0;
5261 ip = &t.i;
5262 return *ip;
5263@}
5264@end smallexample
5265
5266Every language that wishes to perform language-specific alias analysis
5267should define a function that computes, given an @code{tree}
5268node, an alias set for the node. Nodes in different alias sets are not
5269allowed to alias. For an example, see the C front-end function
5270@code{c_get_alias_set}.
5271
5272Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5273
5274@item -fstrict-overflow
5275@opindex fstrict-overflow
5276Allow the compiler to assume strict signed overflow rules, depending
5277on the language being compiled. For C (and C++) this means that
5278overflow when doing arithmetic with signed numbers is undefined, which
5279means that the compiler may assume that it will not happen. This
5280permits various optimizations. For example, the compiler will assume
5281that an expression like @code{i + 10 > i} will always be true for
5282signed @code{i}. This assumption is only valid if signed overflow is
5283undefined, as the expression is false if @code{i + 10} overflows when
5284using twos complement arithmetic. When this option is in effect any
5285attempt to determine whether an operation on signed numbers will
5286overflow must be written carefully to not actually involve overflow.
5287
5288See also the @option{-fwrapv} option. Using @option{-fwrapv} means
5289that signed overflow is fully defined: it wraps. When
5290@option{-fwrapv} is used, there is no difference between
5291@option{-fstrict-overflow} and @option{-fno-strict-overflow}. With
5292@option{-fwrapv} certain types of overflow are permitted. For
5293example, if the compiler gets an overflow when doing arithmetic on
5294constants, the overflowed value can still be used with
5295@option{-fwrapv}, but not otherwise.
5296
5297The @option{-fstrict-overflow} option is enabled at levels
5298@option{-O2}, @option{-O3}, @option{-Os}.
5299
5300@item -falign-functions
5301@itemx -falign-functions=@var{n}
5302@opindex falign-functions
5303Align the start of functions to the next power-of-two greater than
5304@var{n}, skipping up to @var{n} bytes. For instance,
5305@option{-falign-functions=32} aligns functions to the next 32-byte
5306boundary, but @option{-falign-functions=24} would align to the next
530732-byte boundary only if this can be done by skipping 23 bytes or less.
5308
5309@option{-fno-align-functions} and @option{-falign-functions=1} are
5310equivalent and mean that functions will not be aligned.
5311
5312Some assemblers only support this flag when @var{n} is a power of two;
5313in that case, it is rounded up.
5314
5315If @var{n} is not specified or is zero, use a machine-dependent default.
5316
5317Enabled at levels @option{-O2}, @option{-O3}.
5318
5319@item -falign-labels
5320@itemx -falign-labels=@var{n}
5321@opindex falign-labels
5322Align all branch targets to a power-of-two boundary, skipping up to
5323@var{n} bytes like @option{-falign-functions}. This option can easily
5324make code slower, because it must insert dummy operations for when the
5325branch target is reached in the usual flow of the code.
5326
5327@option{-fno-align-labels} and @option{-falign-labels=1} are
5328equivalent and mean that labels will not be aligned.
5329
5330If @option{-falign-loops} or @option{-falign-jumps} are applicable and
5331are greater than this value, then their values are used instead.
5332
5333If @var{n} is not specified or is zero, use a machine-dependent default
5334which is very likely to be @samp{1}, meaning no alignment.
5335
5336Enabled at levels @option{-O2}, @option{-O3}.
5337
5338@item -falign-loops
5339@itemx -falign-loops=@var{n}
5340@opindex falign-loops
5341Align loops to a power-of-two boundary, skipping up to @var{n} bytes
5342like @option{-falign-functions}. The hope is that the loop will be
5343executed many times, which will make up for any execution of the dummy
5344operations.
5345
5346@option{-fno-align-loops} and @option{-falign-loops=1} are
5347equivalent and mean that loops will not be aligned.
5348
5349If @var{n} is not specified or is zero, use a machine-dependent default.
5350
5351Enabled at levels @option{-O2}, @option{-O3}.
5352
5353@item -falign-jumps
5354@itemx -falign-jumps=@var{n}
5355@opindex falign-jumps
5356Align branch targets to a power-of-two boundary, for branch targets
5357where the targets can only be reached by jumping, skipping up to @var{n}
5358bytes like @option{-falign-functions}. In this case, no dummy operations
5359need be executed.
5360
5361@option{-fno-align-jumps} and @option{-falign-jumps=1} are
5362equivalent and mean that loops will not be aligned.
5363
5364If @var{n} is not specified or is zero, use a machine-dependent default.
5365
5366Enabled at levels @option{-O2}, @option{-O3}.
5367
5368@item -funit-at-a-time
5369@opindex funit-at-a-time
5370Parse the whole compilation unit before starting to produce code.
5371This allows some extra optimizations to take place but consumes
5372more memory (in general). There are some compatibility issues
5373with @emph{unit-at-a-time} mode:
5374@itemize @bullet
5375@item
5376enabling @emph{unit-at-a-time} mode may change the order
5377in which functions, variables, and top-level @code{asm} statements
5378are emitted, and will likely break code relying on some particular
5379ordering. The majority of such top-level @code{asm} statements,
5380though, can be replaced by @code{section} attributes. The
5381@option{fno-toplevel-reorder} option may be used to keep the ordering
5382used in the input file, at the cost of some optimizations.
5383
5384@item
5385@emph{unit-at-a-time} mode removes unreferenced static variables
5386and functions. This may result in undefined references
5387when an @code{asm} statement refers directly to variables or functions
5388that are otherwise unused. In that case either the variable/function
5389shall be listed as an operand of the @code{asm} statement operand or,
5390in the case of top-level @code{asm} statements the attribute @code{used}
5391shall be used on the declaration.
5392
5393@item
5394Static functions now can use non-standard passing conventions that
5395may break @code{asm} statements calling functions directly. Again,
5396attribute @code{used} will prevent this behavior.
5397@end itemize
5398
5399As a temporary workaround, @option{-fno-unit-at-a-time} can be used,
5400but this scheme may not be supported by future releases of GCC@.
5401
5402Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5403
5404@item -fno-toplevel-reorder
5405Do not reorder top-level functions, variables, and @code{asm}
5406statements. Output them in the same order that they appear in the
5407input file. When this option is used, unreferenced static variables
5408will not be removed. This option is intended to support existing code
5409which relies on a particular ordering. For new code, it is better to
5410use attributes.
5411
5412@item -fweb
5413@opindex fweb
5414Constructs webs as commonly used for register allocation purposes and assign
5415each web individual pseudo register. This allows the register allocation pass
5416to operate on pseudos directly, but also strengthens several other optimization
5417passes, such as CSE, loop optimizer and trivial dead code remover. It can,
5418however, make debugging impossible, since variables will no longer stay in a
5419``home register''.
5420
5421Enabled by default with @option{-funroll-loops}.
5422
5423@item -fwhole-program
5424@opindex fwhole-program
5425Assume that the current compilation unit represents whole program being
5426compiled. All public functions and variables with the exception of @code{main}
5427and those merged by attribute @code{externally_visible} become static functions
5428and in a affect gets more aggressively optimized by interprocedural optimizers.
5429While this option is equivalent to proper use of @code{static} keyword for
5430programs consisting of single file, in combination with option
5431@option{--combine} this flag can be used to compile most of smaller scale C
5432programs since the functions and variables become local for the whole combined
5433compilation unit, not for the single source file itself.
5434
5435
5436@item -fno-cprop-registers
5437@opindex fno-cprop-registers
5438After register allocation and post-register allocation instruction splitting,
5439we perform a copy-propagation pass to try to reduce scheduling dependencies
5440and occasionally eliminate the copy.
5441
5442Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5443
5444@item -fprofile-generate
5445@opindex fprofile-generate
5446
5447Enable options usually used for instrumenting application to produce
5448profile useful for later recompilation with profile feedback based
5449optimization. You must use @option{-fprofile-generate} both when
5450compiling and when linking your program.
5451
5452The following options are enabled: @code{-fprofile-arcs}, @code{-fprofile-values}, @code{-fvpt}.
5453
5454@item -fprofile-use
5455@opindex fprofile-use
5456Enable profile feedback directed optimizations, and optimizations
5457generally profitable only with profile feedback available.
5458
5459The following options are enabled: @code{-fbranch-probabilities}, @code{-fvpt},
5460@code{-funroll-loops}, @code{-fpeel-loops}, @code{-ftracer}
5461
5462@end table
5463
5464The following options control compiler behavior regarding floating
5465point arithmetic. These options trade off between speed and
5466correctness. All must be specifically enabled.
5467
5468@table @gcctabopt
5469@item -ffloat-store
5470@opindex ffloat-store
5471Do not store floating point variables in registers, and inhibit other
5472options that might change whether a floating point value is taken from a
5473register or memory.
5474
5475@cindex floating point precision
5476This option prevents undesirable excess precision on machines such as
5477the 68000 where the floating registers (of the 68881) keep more
5478precision than a @code{double} is supposed to have. Similarly for the
5479x86 architecture. For most programs, the excess precision does only
5480good, but a few programs rely on the precise definition of IEEE floating
5481point. Use @option{-ffloat-store} for such programs, after modifying
5482them to store all pertinent intermediate computations into variables.
5483
5484@item -ffast-math
5485@opindex ffast-math
5486Sets @option{-fno-math-errno}, @option{-funsafe-math-optimizations}, @*
5487@option{-fno-trapping-math}, @option{-ffinite-math-only},
5488@option{-fno-rounding-math}, @option{-fno-signaling-nans}
5489and @option{fcx-limited-range}.
5490
5491This option causes the preprocessor macro @code{__FAST_MATH__} to be defined.
5492
5493This option should never be turned on by any @option{-O} option since
5494it can result in incorrect output for programs which depend on
5495an exact implementation of IEEE or ISO rules/specifications for
5496math functions.
5497
5498@item -fno-math-errno
5499@opindex fno-math-errno
5500Do not set ERRNO after calling math functions that are executed
5501with a single instruction, e.g., sqrt. A program that relies on
5502IEEE exceptions for math error handling may want to use this flag
5503for speed while maintaining IEEE arithmetic compatibility.
5504
5505This option should never be turned on by any @option{-O} option since
5506it can result in incorrect output for programs which depend on
5507an exact implementation of IEEE or ISO rules/specifications for
5508math functions.
5509
5510The default is @option{-fmath-errno}.
5511
5512On Darwin and FreeBSD systems, the math library never sets @code{errno}.
5513There is therefore
5514no reason for the compiler to consider the possibility that it might,
5515and @option{-fno-math-errno} is the default.
5516
5517@item -funsafe-math-optimizations
5518@opindex funsafe-math-optimizations
5519Allow optimizations for floating-point arithmetic that (a) assume
5520that arguments and results are valid and (b) may violate IEEE or
5521ANSI standards. When used at link-time, it may include libraries
5522or startup files that change the default FPU control word or other
5523similar optimizations.
5524
5525This option should never be turned on by any @option{-O} option since
5526it can result in incorrect output for programs which depend on
5527an exact implementation of IEEE or ISO rules/specifications for
5528math functions.
5529
5530The default is @option{-fno-unsafe-math-optimizations}.
5531
5532@item -ffinite-math-only
5533@opindex ffinite-math-only
5534Allow optimizations for floating-point arithmetic that assume
5535that arguments and results are not NaNs or +-Infs.
5536
5537This option should never be turned on by any @option{-O} option since
5538it can result in incorrect output for programs which depend on
5539an exact implementation of IEEE or ISO rules/specifications.
5540
5541The default is @option{-fno-finite-math-only}.
5542
5543@item -fno-trapping-math
5544@opindex fno-trapping-math
5545Compile code assuming that floating-point operations cannot generate
5546user-visible traps. These traps include division by zero, overflow,
5547underflow, inexact result and invalid operation. This option implies
5548@option{-fno-signaling-nans}. Setting this option may allow faster
5549code if one relies on ``non-stop'' IEEE arithmetic, for example.
5550
5551This option should never be turned on by any @option{-O} option since
5552it can result in incorrect output for programs which depend on
5553an exact implementation of IEEE or ISO rules/specifications for
5554math functions.
5555
5556The default is @option{-ftrapping-math}.
5557
5558@item -frounding-math
5559@opindex frounding-math
5560Disable transformations and optimizations that assume default floating
5561point rounding behavior. This is round-to-zero for all floating point
5562to integer conversions, and round-to-nearest for all other arithmetic
5563truncations. This option should be specified for programs that change
5564the FP rounding mode dynamically, or that may be executed with a
5565non-default rounding mode. This option disables constant folding of
5566floating point expressions at compile-time (which may be affected by
5567rounding mode) and arithmetic transformations that are unsafe in the
5568presence of sign-dependent rounding modes.
5569
5570The default is @option{-fno-rounding-math}.
5571
5572This option is experimental and does not currently guarantee to
5573disable all GCC optimizations that are affected by rounding mode.
5574Future versions of GCC may provide finer control of this setting
5575using C99's @code{FENV_ACCESS} pragma. This command line option
5576will be used to specify the default state for @code{FENV_ACCESS}.
5577
5578@item -frtl-abstract-sequences
5579@opindex frtl-abstract-sequences
5580It is a size optimization method. This option is to find identical
5581sequences of code, which can be turned into pseudo-procedures and
5582then replace all occurrences with calls to the newly created
5583subroutine. It is kind of an opposite of @option{-finline-functions}.
5584This optimization runs at RTL level.
5585
5586@item -fsignaling-nans
5587@opindex fsignaling-nans
5588Compile code assuming that IEEE signaling NaNs may generate user-visible
5589traps during floating-point operations. Setting this option disables
5590optimizations that may change the number of exceptions visible with
5591signaling NaNs. This option implies @option{-ftrapping-math}.
5592
5593This option causes the preprocessor macro @code{__SUPPORT_SNAN__} to
5594be defined.
5595
5596The default is @option{-fno-signaling-nans}.
5597
5598This option is experimental and does not currently guarantee to
5599disable all GCC optimizations that affect signaling NaN behavior.
5600
5601@item -fsingle-precision-constant
5602@opindex fsingle-precision-constant
5603Treat floating point constant as single precision constant instead of
5604implicitly converting it to double precision constant.
5605
5606@item -fcx-limited-range
5607@itemx -fno-cx-limited-range
5608@opindex fcx-limited-range
5609@opindex fno-cx-limited-range
5610When enabled, this option states that a range reduction step is not
5611needed when performing complex division. The default is
5612@option{-fno-cx-limited-range}, but is enabled by @option{-ffast-math}.
5613
5614This option controls the default setting of the ISO C99
5615@code{CX_LIMITED_RANGE} pragma. Nevertheless, the option applies to
5616all languages.
5617
5618@end table
5619
5620The following options control optimizations that may improve
5621performance, but are not enabled by any @option{-O} options. This
5622section includes experimental options that may produce broken code.
5623
5624@table @gcctabopt
5625@item -fbranch-probabilities
5626@opindex fbranch-probabilities
5627After running a program compiled with @option{-fprofile-arcs}
5628(@pxref{Debugging Options,, Options for Debugging Your Program or
5629@command{gcc}}), you can compile it a second time using
5630@option{-fbranch-probabilities}, to improve optimizations based on
5631the number of times each branch was taken. When the program
5632compiled with @option{-fprofile-arcs} exits it saves arc execution
5633counts to a file called @file{@var{sourcename}.gcda} for each source
5634file The information in this data file is very dependent on the
5635structure of the generated code, so you must use the same source code
5636and the same optimization options for both compilations.
5637
5638With @option{-fbranch-probabilities}, GCC puts a
5639@samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}.
5640These can be used to improve optimization. Currently, they are only
5641used in one place: in @file{reorg.c}, instead of guessing which path a
5642branch is mostly to take, the @samp{REG_BR_PROB} values are used to
5643exactly determine which path is taken more often.
5644
5645@item -fprofile-values
5646@opindex fprofile-values
5647If combined with @option{-fprofile-arcs}, it adds code so that some
5648data about values of expressions in the program is gathered.
5649
5650With @option{-fbranch-probabilities}, it reads back the data gathered
5651from profiling values of expressions and adds @samp{REG_VALUE_PROFILE}
5652notes to instructions for their later usage in optimizations.
5653
5654Enabled with @option{-fprofile-generate} and @option{-fprofile-use}.
5655
5656@item -fvpt
5657@opindex fvpt
5658If combined with @option{-fprofile-arcs}, it instructs the compiler to add
5659a code to gather information about values of expressions.
5660
5661With @option{-fbranch-probabilities}, it reads back the data gathered
5662and actually performs the optimizations based on them.
5663Currently the optimizations include specialization of division operation
5664using the knowledge about the value of the denominator.
5665
5666@item -frename-registers
5667@opindex frename-registers
5668Attempt to avoid false dependencies in scheduled code by making use
5669of registers left over after register allocation. This optimization
5670will most benefit processors with lots of registers. Depending on the
5671debug information format adopted by the target, however, it can
5672make debugging impossible, since variables will no longer stay in
5673a ``home register''.
5674
5675Enabled by default with @option{-funroll-loops}.
5676
5677@item -ftracer
5678@opindex ftracer
5679Perform tail duplication to enlarge superblock size. This transformation
5680simplifies the control flow of the function allowing other optimizations to do
5681better job.
5682
5683Enabled with @option{-fprofile-use}.
5684
5685@item -funroll-loops
5686@opindex funroll-loops
5687Unroll loops whose number of iterations can be determined at compile time or
5688upon entry to the loop. @option{-funroll-loops} implies
5689@option{-frerun-cse-after-loop}, @option{-fweb} and @option{-frename-registers}.
5690It also turns on complete loop peeling (i.e.@: complete removal of loops with
5691small constant number of iterations). This option makes code larger, and may
5692or may not make it run faster.
5693
5694Enabled with @option{-fprofile-use}.
5695
5696@item -funroll-all-loops
5697@opindex funroll-all-loops
5698Unroll all loops, even if their number of iterations is uncertain when
5699the loop is entered. This usually makes programs run more slowly.
5700@option{-funroll-all-loops} implies the same options as
5701@option{-funroll-loops}.
5702
5703@item -fpeel-loops
5704@opindex fpeel-loops
5705Peels the loops for that there is enough information that they do not
5706roll much (from profile feedback). It also turns on complete loop peeling
5707(i.e.@: complete removal of loops with small constant number of iterations).
5708
5709Enabled with @option{-fprofile-use}.
5710
5711@item -fmove-loop-invariants
5712@opindex fmove-loop-invariants
5713Enables the loop invariant motion pass in the RTL loop optimizer. Enabled
5714at level @option{-O1}
5715
5716@item -funswitch-loops
5717@opindex funswitch-loops
5718Move branches with loop invariant conditions out of the loop, with duplicates
5719of the loop on both branches (modified according to result of the condition).
5720
5721@item -ffunction-sections
5722@itemx -fdata-sections
5723@opindex ffunction-sections
5724@opindex fdata-sections
5725Place each function or data item into its own section in the output
5726file if the target supports arbitrary sections. The name of the
5727function or the name of the data item determines the section's name
5728in the output file.
5729
5730Use these options on systems where the linker can perform optimizations
5731to improve locality of reference in the instruction space. Most systems
5732using the ELF object format and SPARC processors running Solaris 2 have
5733linkers with such optimizations. AIX may have these optimizations in
5734the future.
5735
5736Only use these options when there are significant benefits from doing
5737so. When you specify these options, the assembler and linker will
5738create larger object and executable files and will also be slower.
5739You will not be able to use @code{gprof} on all systems if you
5740specify this option and you may have problems with debugging if
5741you specify both this option and @option{-g}.
5742
5743@item -fbranch-target-load-optimize
5744@opindex fbranch-target-load-optimize
5745Perform branch target register load optimization before prologue / epilogue
5746threading.
5747The use of target registers can typically be exposed only during reload,
5748thus hoisting loads out of loops and doing inter-block scheduling needs
5749a separate optimization pass.
5750
5751@item -fbranch-target-load-optimize2
5752@opindex fbranch-target-load-optimize2
5753Perform branch target register load optimization after prologue / epilogue
5754threading.
5755
5756@item -fbtr-bb-exclusive
5757@opindex fbtr-bb-exclusive
5758When performing branch target register load optimization, don't reuse
5759branch target registers in within any basic block.
5760
5761@item -fstack-protector
5762Emit extra code to check for buffer overflows, such as stack smashing
5763attacks. This is done by adding a guard variable to functions with
5764vulnerable objects. This includes functions that call alloca, and
5765functions with buffers larger than 8 bytes. The guards are initialized
5766when a function is entered and then checked when the function exits.
5767If a guard check fails, an error message is printed and the program exits.
5768
5769@item -fstack-protector-all
5770Like @option{-fstack-protector} except that all functions are protected.
5771
5772@item -fsection-anchors
5773@opindex fsection-anchors
5774Try to reduce the number of symbolic address calculations by using
5775shared ``anchor'' symbols to address nearby objects. This transformation
5776can help to reduce the number of GOT entries and GOT accesses on some
5777targets.
5778
5779For example, the implementation of the following function @code{foo}:
5780
5781@smallexample
5782static int a, b, c;
5783int foo (void) @{ return a + b + c; @}
5784@end smallexample
5785
5786would usually calculate the addresses of all three variables, but if you
5787compile it with @option{-fsection-anchors}, it will access the variables
5788from a common anchor point instead. The effect is similar to the
5789following pseudocode (which isn't valid C):
5790
5791@smallexample
5792int foo (void)
5793@{
5794 register int *xr = &x;
5795 return xr[&a - &x] + xr[&b - &x] + xr[&c - &x];
5796@}
5797@end smallexample
5798
5799Not all targets support this option.
5800
5801@item --param @var{name}=@var{value}
5802@opindex param
5803In some places, GCC uses various constants to control the amount of
5804optimization that is done. For example, GCC will not inline functions
5805that contain more that a certain number of instructions. You can
5806control some of these constants on the command-line using the
5807@option{--param} option.
5808
5809The names of specific parameters, and the meaning of the values, are
5810tied to the internals of the compiler, and are subject to change
5811without notice in future releases.
5812
5813In each case, the @var{value} is an integer. The allowable choices for
5814@var{name} are given in the following table:
5815
5816@table @gcctabopt
5817@item salias-max-implicit-fields
5818The maximum number of fields in a variable without direct
5819structure accesses for which structure aliasing will consider trying
5820to track each field. The default is 5
5821
5822@item salias-max-array-elements
5823The maximum number of elements an array can have and its elements
5824still be tracked individually by structure aliasing. The default is 4
5825
5826@item sra-max-structure-size
5827The maximum structure size, in bytes, at which the scalar replacement
5828of aggregates (SRA) optimization will perform block copies. The
5829default value, 0, implies that GCC will select the most appropriate
5830size itself.
5831
5832@item sra-field-structure-ratio
5833The threshold ratio (as a percentage) between instantiated fields and
5834the complete structure size. We say that if the ratio of the number
5835of bytes in instantiated fields to the number of bytes in the complete
5836structure exceeds this parameter, then block copies are not used. The
5837default is 75.
5838
5839@item max-crossjump-edges
5840The maximum number of incoming edges to consider for crossjumping.
5841The algorithm used by @option{-fcrossjumping} is @math{O(N^2)} in
5842the number of edges incoming to each block. Increasing values mean
5843more aggressive optimization, making the compile time increase with
5844probably small improvement in executable size.
5845
5846@item min-crossjump-insns
5847The minimum number of instructions which must be matched at the end
5848of two blocks before crossjumping will be performed on them. This
5849value is ignored in the case where all instructions in the block being
5850crossjumped from are matched. The default value is 5.
5851
5852@item max-grow-copy-bb-insns
5853The maximum code size expansion factor when copying basic blocks
5854instead of jumping. The expansion is relative to a jump instruction.
5855The default value is 8.
5856
5857@item max-goto-duplication-insns
5858The maximum number of instructions to duplicate to a block that jumps
5859to a computed goto. To avoid @math{O(N^2)} behavior in a number of
5860passes, GCC factors computed gotos early in the compilation process,
5861and unfactors them as late as possible. Only computed jumps at the
5862end of a basic blocks with no more than max-goto-duplication-insns are
5863unfactored. The default value is 8.
5864
5865@item max-delay-slot-insn-search
5866The maximum number of instructions to consider when looking for an
5867instruction to fill a delay slot. If more than this arbitrary number of
5868instructions is searched, the time savings from filling the delay slot
5869will be minimal so stop searching. Increasing values mean more
5870aggressive optimization, making the compile time increase with probably
5871small improvement in executable run time.
5872
5873@item max-delay-slot-live-search
5874When trying to fill delay slots, the maximum number of instructions to
5875consider when searching for a block with valid live register
5876information. Increasing this arbitrarily chosen value means more
5877aggressive optimization, increasing the compile time. This parameter
5878should be removed when the delay slot code is rewritten to maintain the
5879control-flow graph.
5880
5881@item max-gcse-memory
5882The approximate maximum amount of memory that will be allocated in
5883order to perform the global common subexpression elimination
5884optimization. If more memory than specified is required, the
5885optimization will not be done.
5886
5887@item max-gcse-passes
5888The maximum number of passes of GCSE to run. The default is 1.
5889
5890@item max-pending-list-length
5891The maximum number of pending dependencies scheduling will allow
5892before flushing the current state and starting over. Large functions
5893with few branches or calls can create excessively large lists which
5894needlessly consume memory and resources.
5895
5896@item max-inline-insns-single
5897Several parameters control the tree inliner used in gcc.
5898This number sets the maximum number of instructions (counted in GCC's
5899internal representation) in a single function that the tree inliner
5900will consider for inlining. This only affects functions declared
5901inline and methods implemented in a class declaration (C++).
5902The default value is 450.
5903
5904@item max-inline-insns-auto
5905When you use @option{-finline-functions} (included in @option{-O3}),
5906a lot of functions that would otherwise not be considered for inlining
5907by the compiler will be investigated. To those functions, a different
5908(more restrictive) limit compared to functions declared inline can
5909be applied.
5910The default value is 90.
5911
5912@item large-function-insns
5913The limit specifying really large functions. For functions larger than this
5914limit after inlining inlining is constrained by
5915@option{--param large-function-growth}. This parameter is useful primarily
5916to avoid extreme compilation time caused by non-linear algorithms used by the
5917backend.
5918This parameter is ignored when @option{-funit-at-a-time} is not used.
5919The default value is 2700.
5920
5921@item large-function-growth
5922Specifies maximal growth of large function caused by inlining in percents.
5923This parameter is ignored when @option{-funit-at-a-time} is not used.
5924The default value is 100 which limits large function growth to 2.0 times
5925the original size.
5926
5927@item large-unit-insns
5928The limit specifying large translation unit. Growth caused by inlining of
5929units larger than this limit is limited by @option{--param inline-unit-growth}.
5930For small units this might be too tight (consider unit consisting of function A
5931that is inline and B that just calls A three time. If B is small relative to
5932A, the growth of unit is 300\% and yet such inlining is very sane. For very
5933large units consisting of small inlininable functions however the overall unit
5934growth limit is needed to avoid exponential explosion of code size. Thus for
5935smaller units, the size is increased to @option{--param large-unit-insns}
5936before applying @option{--param inline-unit-growth}. The default is 10000
5937
5938@item inline-unit-growth
5939Specifies maximal overall growth of the compilation unit caused by inlining.
5940This parameter is ignored when @option{-funit-at-a-time} is not used.
5941The default value is 50 which limits unit growth to 1.5 times the original
5942size.
5943
5944@item max-inline-insns-recursive
5945@itemx max-inline-insns-recursive-auto
5946Specifies maximum number of instructions out-of-line copy of self recursive inline
5947function can grow into by performing recursive inlining.
5948
5949For functions declared inline @option{--param max-inline-insns-recursive} is
5950taken into account. For function not declared inline, recursive inlining
5951happens only when @option{-finline-functions} (included in @option{-O3}) is
5952enabled and @option{--param max-inline-insns-recursive-auto} is used. The
5953default value is 450.
5954
5955@item max-inline-recursive-depth
5956@itemx max-inline-recursive-depth-auto
5957Specifies maximum recursion depth used by the recursive inlining.
5958
5959For functions declared inline @option{--param max-inline-recursive-depth} is
5960taken into account. For function not declared inline, recursive inlining
5961happens only when @option{-finline-functions} (included in @option{-O3}) is
5962enabled and @option{--param max-inline-recursive-depth-auto} is used. The
5963default value is 450.
5964
5965@item min-inline-recursive-probability
5966Recursive inlining is profitable only for function having deep recursion
5967in average and can hurt for function having little recursion depth by
5968increasing the prologue size or complexity of function body to other
5969optimizers.
5970
5971When profile feedback is available (see @option{-fprofile-generate}) the actual
5972recursion depth can be guessed from probability that function will recurse via
5973given call expression. This parameter limits inlining only to call expression
5974whose probability exceeds given threshold (in percents). The default value is
597510.
5976
5977@item inline-call-cost
5978Specify cost of call instruction relative to simple arithmetics operations
5979(having cost of 1). Increasing this cost disqualifies inlining of non-leaf
5980functions and at the same time increases size of leaf function that is believed to
5981reduce function size by being inlined. In effect it increases amount of
5982inlining for code having large abstraction penalty (many functions that just
5983pass the arguments to other functions) and decrease inlining for code with low
5984abstraction penalty. The default value is 16.
5985
5986@item max-unrolled-insns
5987The maximum number of instructions that a loop should have if that loop
5988is unrolled, and if the loop is unrolled, it determines how many times
5989the loop code is unrolled.
5990
5991@item max-average-unrolled-insns
5992The maximum number of instructions biased by probabilities of their execution
5993that a loop should have if that loop is unrolled, and if the loop is unrolled,
5994it determines how many times the loop code is unrolled.
5995
5996@item max-unroll-times
5997The maximum number of unrollings of a single loop.
5998
5999@item max-peeled-insns
6000The maximum number of instructions that a loop should have if that loop
6001is peeled, and if the loop is peeled, it determines how many times
6002the loop code is peeled.
6003
6004@item max-peel-times
6005The maximum number of peelings of a single loop.
6006
6007@item max-completely-peeled-insns
6008The maximum number of insns of a completely peeled loop.
6009
6010@item max-completely-peel-times
6011The maximum number of iterations of a loop to be suitable for complete peeling.
6012
6013@item max-unswitch-insns
6014The maximum number of insns of an unswitched loop.
6015
6016@item max-unswitch-level
6017The maximum number of branches unswitched in a single loop.
6018
6019@item lim-expensive
6020The minimum cost of an expensive expression in the loop invariant motion.
6021
6022@item iv-consider-all-candidates-bound
6023Bound on number of candidates for induction variables below that
6024all candidates are considered for each use in induction variable
6025optimizations. Only the most relevant candidates are considered
6026if there are more candidates, to avoid quadratic time complexity.
6027
6028@item iv-max-considered-uses
6029The induction variable optimizations give up on loops that contain more
6030induction variable uses.
6031
6032@item iv-always-prune-cand-set-bound
6033If number of candidates in the set is smaller than this value,
6034we always try to remove unnecessary ivs from the set during its
6035optimization when a new iv is added to the set.
6036
6037@item scev-max-expr-size
6038Bound on size of expressions used in the scalar evolutions analyzer.
6039Large expressions slow the analyzer.
6040
6041@item vect-max-version-checks
6042The maximum number of runtime checks that can be performed when doing
6043loop versioning in the vectorizer. See option ftree-vect-loop-version
6044for more information.
6045
6046@item max-iterations-to-track
6047
6048The maximum number of iterations of a loop the brute force algorithm
6049for analysis of # of iterations of the loop tries to evaluate.
6050
6051@item hot-bb-count-fraction
6052Select fraction of the maximal count of repetitions of basic block in program
6053given basic block needs to have to be considered hot.
6054
6055@item hot-bb-frequency-fraction
6056Select fraction of the maximal frequency of executions of basic block in
6057function given basic block needs to have to be considered hot
6058
6059@item max-predicted-iterations
6060The maximum number of loop iterations we predict statically. This is useful
6061in cases where function contain single loop with known bound and other loop
6062with unknown. We predict the known number of iterations correctly, while
6063the unknown number of iterations average to roughly 10. This means that the
6064loop without bounds would appear artificially cold relative to the other one.
6065
6066@item tracer-dynamic-coverage
6067@itemx tracer-dynamic-coverage-feedback
6068
6069This value is used to limit superblock formation once the given percentage of
6070executed instructions is covered. This limits unnecessary code size
6071expansion.
6072
6073The @option{tracer-dynamic-coverage-feedback} is used only when profile
6074feedback is available. The real profiles (as opposed to statically estimated
6075ones) are much less balanced allowing the threshold to be larger value.
6076
6077@item tracer-max-code-growth
6078Stop tail duplication once code growth has reached given percentage. This is
6079rather hokey argument, as most of the duplicates will be eliminated later in
6080cross jumping, so it may be set to much higher values than is the desired code
6081growth.
6082
6083@item tracer-min-branch-ratio
6084
6085Stop reverse growth when the reverse probability of best edge is less than this
6086threshold (in percent).
6087
6088@item tracer-min-branch-ratio
6089@itemx tracer-min-branch-ratio-feedback
6090
6091Stop forward growth if the best edge do have probability lower than this
6092threshold.
6093
6094Similarly to @option{tracer-dynamic-coverage} two values are present, one for
6095compilation for profile feedback and one for compilation without. The value
6096for compilation with profile feedback needs to be more conservative (higher) in
6097order to make tracer effective.
6098
6099@item max-cse-path-length
6100
6101Maximum number of basic blocks on path that cse considers. The default is 10.
6102
6103@item max-cse-insns
6104The maximum instructions CSE process before flushing. The default is 1000.
6105
6106@item global-var-threshold
6107
6108Counts the number of function calls (@var{n}) and the number of
6109call-clobbered variables (@var{v}). If @var{n}x@var{v} is larger than this limit, a
6110single artificial variable will be created to represent all the
6111call-clobbered variables at function call sites. This artificial
6112variable will then be made to alias every call-clobbered variable.
6113(done as @code{int * size_t} on the host machine; beware overflow).
6114
6115@item max-aliased-vops
6116
6117Maximum number of virtual operands allowed to represent aliases
6118before triggering the alias grouping heuristic. Alias grouping
6119reduces compile times and memory consumption needed for aliasing at
6120the expense of precision loss in alias information.
6121
6122@item ggc-min-expand
6123
6124GCC uses a garbage collector to manage its own memory allocation. This
6125parameter specifies the minimum percentage by which the garbage
6126collector's heap should be allowed to expand between collections.
6127Tuning this may improve compilation speed; it has no effect on code
6128generation.
6129
6130The default is 30% + 70% * (RAM/1GB) with an upper bound of 100% when
6131RAM >= 1GB@. If @code{getrlimit} is available, the notion of "RAM" is
6132the smallest of actual RAM and @code{RLIMIT_DATA} or @code{RLIMIT_AS}. If
6133GCC is not able to calculate RAM on a particular platform, the lower
6134bound of 30% is used. Setting this parameter and
6135@option{ggc-min-heapsize} to zero causes a full collection to occur at
6136every opportunity. This is extremely slow, but can be useful for
6137debugging.
6138
6139@item ggc-min-heapsize
6140
6141Minimum size of the garbage collector's heap before it begins bothering
6142to collect garbage. The first collection occurs after the heap expands
6143by @option{ggc-min-expand}% beyond @option{ggc-min-heapsize}. Again,
6144tuning this may improve compilation speed, and has no effect on code
6145generation.
6146
6147The default is the smaller of RAM/8, RLIMIT_RSS, or a limit which
6148tries to ensure that RLIMIT_DATA or RLIMIT_AS are not exceeded, but
6149with a lower bound of 4096 (four megabytes) and an upper bound of
6150131072 (128 megabytes). If GCC is not able to calculate RAM on a
6151particular platform, the lower bound is used. Setting this parameter
6152very large effectively disables garbage collection. Setting this
6153parameter and @option{ggc-min-expand} to zero causes a full collection
6154to occur at every opportunity.
6155
6156@item max-reload-search-insns
6157The maximum number of instruction reload should look backward for equivalent
6158register. Increasing values mean more aggressive optimization, making the
6159compile time increase with probably slightly better performance. The default
6160value is 100.
6161
6162@item max-cselib-memory-locations
6163The maximum number of memory locations cselib should take into account.
6164Increasing values mean more aggressive optimization, making the compile time
6165increase with probably slightly better performance. The default value is 500.
6166
6167@item max-flow-memory-locations
6168Similar as @option{max-cselib-memory-locations} but for dataflow liveness.
6169The default value is 100.
6170
6171@item reorder-blocks-duplicate
6172@itemx reorder-blocks-duplicate-feedback
6173
6174Used by basic block reordering pass to decide whether to use unconditional
6175branch or duplicate the code on its destination. Code is duplicated when its
6176estimated size is smaller than this value multiplied by the estimated size of
6177unconditional jump in the hot spots of the program.
6178
6179The @option{reorder-block-duplicate-feedback} is used only when profile
6180feedback is available and may be set to higher values than
6181@option{reorder-block-duplicate} since information about the hot spots is more
6182accurate.
6183
6184@item max-sched-ready-insns
6185The maximum number of instructions ready to be issued the scheduler should
6186consider at any given time during the first scheduling pass. Increasing
6187values mean more thorough searches, making the compilation time increase
6188with probably little benefit. The default value is 100.
6189
6190@item max-sched-region-blocks
6191The maximum number of blocks in a region to be considered for
6192interblock scheduling. The default value is 10.
6193
6194@item max-sched-region-insns
6195The maximum number of insns in a region to be considered for
6196interblock scheduling. The default value is 100.
6197
6198@item min-spec-prob
6199The minimum probability (in percents) of reaching a source block
6200for interblock speculative scheduling. The default value is 40.
6201
6202@item max-sched-extend-regions-iters
6203The maximum number of iterations through CFG to extend regions.
62040 - disable region extension,
6205N - do at most N iterations.
6206The default value is 0.
6207
6208@item max-sched-insn-conflict-delay
6209The maximum conflict delay for an insn to be considered for speculative motion.
6210The default value is 3.
6211
6212@item sched-spec-prob-cutoff
6213The minimal probability of speculation success (in percents), so that
6214speculative insn will be scheduled.
6215The default value is 40.
6216
6217@item max-last-value-rtl
6218
6219The maximum size measured as number of RTLs that can be recorded in an expression
6220in combiner for a pseudo register as last known value of that register. The default
6221is 10000.
6222
6223@item integer-share-limit
6224Small integer constants can use a shared data structure, reducing the
6225compiler's memory usage and increasing its speed. This sets the maximum
6226value of a shared integer constant's. The default value is 256.
6227
6228@item min-virtual-mappings
6229Specifies the minimum number of virtual mappings in the incremental
6230SSA updater that should be registered to trigger the virtual mappings
6231heuristic defined by virtual-mappings-ratio. The default value is
6232100.
6233
6234@item virtual-mappings-ratio
6235If the number of virtual mappings is virtual-mappings-ratio bigger
6236than the number of virtual symbols to be updated, then the incremental
6237SSA updater switches to a full update for those symbols. The default
6238ratio is 3.
6239
6240@item ssp-buffer-size
6241The minimum size of buffers (i.e. arrays) that will receive stack smashing
6242protection when @option{-fstack-protection} is used.
6243
6244@item max-jump-thread-duplication-stmts
6245Maximum number of statements allowed in a block that needs to be
6246duplicated when threading jumps.
6247
6248@item max-fields-for-field-sensitive
6249Maximum number of fields in a structure we will treat in
6250a field sensitive manner during pointer analysis.
6251
6252@end table
6253@end table
6254
6255@node Preprocessor Options
6256@section Options Controlling the Preprocessor
6257@cindex preprocessor options
6258@cindex options, preprocessor
6259
6260These options control the C preprocessor, which is run on each C source
6261file before actual compilation.
6262
6263If you use the @option{-E} option, nothing is done except preprocessing.
6264Some of these options make sense only together with @option{-E} because
6265they cause the preprocessor output to be unsuitable for actual
6266compilation.
6267
6268@table @gcctabopt
6269@opindex Wp
6270You can use @option{-Wp,@var{option}} to bypass the compiler driver
6271and pass @var{option} directly through to the preprocessor. If
6272@var{option} contains commas, it is split into multiple options at the
6273commas. However, many options are modified, translated or interpreted
6274by the compiler driver before being passed to the preprocessor, and
6275@option{-Wp} forcibly bypasses this phase. The preprocessor's direct
6276interface is undocumented and subject to change, so whenever possible
6277you should avoid using @option{-Wp} and let the driver handle the
6278options instead.
6279
6280@item -Xpreprocessor @var{option}
6281@opindex preprocessor
6282Pass @var{option} as an option to the preprocessor. You can use this to
6283supply system-specific preprocessor options which GCC does not know how to
6284recognize.
6285
6286If you want to pass an option that takes an argument, you must use
6287@option{-Xpreprocessor} twice, once for the option and once for the argument.
6288@end table
6289
6290@include cppopts.texi
6291
6292@node Assembler Options
6293@section Passing Options to the Assembler
6294
6295@c prevent bad page break with this line
6296You can pass options to the assembler.
6297
6298@table @gcctabopt
6299@item -Wa,@var{option}
6300@opindex Wa
6301Pass @var{option} as an option to the assembler. If @var{option}
6302contains commas, it is split into multiple options at the commas.
6303
6304@item -Xassembler @var{option}
6305@opindex Xassembler
6306Pass @var{option} as an option to the assembler. You can use this to
6307supply system-specific assembler options which GCC does not know how to
6308recognize.
6309
6310If you want to pass an option that takes an argument, you must use
6311@option{-Xassembler} twice, once for the option and once for the argument.
6312
6313@end table
6314
6315@node Link Options
6316@section Options for Linking
6317@cindex link options
6318@cindex options, linking
6319
6320These options come into play when the compiler links object files into
6321an executable output file. They are meaningless if the compiler is
6322not doing a link step.
6323
6324@table @gcctabopt
6325@cindex file names
6326@item @var{object-file-name}
6327A file name that does not end in a special recognized suffix is
6328considered to name an object file or library. (Object files are
6329distinguished from libraries by the linker according to the file
6330contents.) If linking is done, these object files are used as input
6331to the linker.
6332
6333@item -c
6334@itemx -S
6335@itemx -E
6336@opindex c
6337@opindex S
6338@opindex E
6339If any of these options is used, then the linker is not run, and
6340object file names should not be used as arguments. @xref{Overall
6341Options}.
6342
6343@cindex Libraries
6344@item -l@var{library}
6345@itemx -l @var{library}
6346@opindex l
6347Search the library named @var{library} when linking. (The second
6348alternative with the library as a separate argument is only for
6349POSIX compliance and is not recommended.)
6350
6351It makes a difference where in the command you write this option; the
6352linker searches and processes libraries and object files in the order they
6353are specified. Thus, @samp{foo.o -lz bar.o} searches library @samp{z}
6354after file @file{foo.o} but before @file{bar.o}. If @file{bar.o} refers
6355to functions in @samp{z}, those functions may not be loaded.
6356
6357The linker searches a standard list of directories for the library,
6358which is actually a file named @file{lib@var{library}.a}. The linker
6359then uses this file as if it had been specified precisely by name.
6360
6361The directories searched include several standard system directories
6362plus any that you specify with @option{-L}.
6363
6364Normally the files found this way are library files---archive files
6365whose members are object files. The linker handles an archive file by
6366scanning through it for members which define symbols that have so far
6367been referenced but not defined. But if the file that is found is an
6368ordinary object file, it is linked in the usual fashion. The only
6369difference between using an @option{-l} option and specifying a file name
6370is that @option{-l} surrounds @var{library} with @samp{lib} and @samp{.a}
6371and searches several directories.
6372
6373@item -nostartfiles
6374@opindex nostartfiles
6375Do not use the standard system startup files when linking.
6376The standard system libraries are used normally, unless @option{-nostdlib}
6377or @option{-nodefaultlibs} is used.
6378
6379@item -nodefaultlibs
6380@opindex nodefaultlibs
6381Do not use the standard system libraries when linking.
6382Only the libraries you specify will be passed to the linker.
6383The standard startup files are used normally, unless @option{-nostartfiles}
6384is used. The compiler may generate calls to @code{memcmp},
6385@code{memset}, @code{memcpy} and @code{memmove}.
6386These entries are usually resolved by entries in
6387libc. These entry points should be supplied through some other
6388mechanism when this option is specified.
6389
6390@item -nostdlib
6391@opindex nostdlib
6392Do not use the standard system startup files or libraries when linking.
6393No startup files and only the libraries you specify will be passed to
6394the linker. The compiler may generate calls to @code{memcmp}, @code{memset},
6395@code{memcpy} and @code{memmove}.
6396These entries are usually resolved by entries in
6397libc. These entry points should be supplied through some other
6398mechanism when this option is specified.
6399
6400@cindex @option{-lgcc}, use with @option{-nostdlib}
6401@cindex @option{-nostdlib} and unresolved references
6402@cindex unresolved references and @option{-nostdlib}
6403@cindex @option{-lgcc}, use with @option{-nodefaultlibs}
6404@cindex @option{-nodefaultlibs} and unresolved references
6405@cindex unresolved references and @option{-nodefaultlibs}
6406One of the standard libraries bypassed by @option{-nostdlib} and
6407@option{-nodefaultlibs} is @file{libgcc.a}, a library of internal subroutines
6408that GCC uses to overcome shortcomings of particular machines, or special
6409needs for some languages.
6410(@xref{Interface,,Interfacing to GCC Output,gccint,GNU Compiler
6411Collection (GCC) Internals},
6412for more discussion of @file{libgcc.a}.)
6413In most cases, you need @file{libgcc.a} even when you want to avoid
6414other standard libraries. In other words, when you specify @option{-nostdlib}
6415or @option{-nodefaultlibs} you should usually specify @option{-lgcc} as well.
6416This ensures that you have no unresolved references to internal GCC
6417library subroutines. (For example, @samp{__main}, used to ensure C++
6418constructors will be called; @pxref{Collect2,,@code{collect2}, gccint,
6419GNU Compiler Collection (GCC) Internals}.)
6420
6421@item -pie
6422@opindex pie
6423Produce a position independent executable on targets which support it.
6424For predictable results, you must also specify the same set of options
6425that were used to generate code (@option{-fpie}, @option{-fPIE},
6426or model suboptions) when you specify this option.
6427
6428@item -rdynamic
6429@opindex rdynamic
6430Pass the flag @option{-export-dynamic} to the ELF linker, on targets
6431that support it. This instructs the linker to add all symbols, not
6432only used ones, to the dynamic symbol table. This option is needed
6433for some uses of @code{dlopen} or to allow obtaining backtraces
6434from within a program.
6435
6436@item -s
6437@opindex s
6438Remove all symbol table and relocation information from the executable.
6439
6440@item -static
6441@opindex static
6442On systems that support dynamic linking, this prevents linking with the shared
6443libraries. On other systems, this option has no effect.
6444
6445@item -shared
6446@opindex shared
6447Produce a shared object which can then be linked with other objects to
6448form an executable. Not all systems support this option. For predictable
6449results, you must also specify the same set of options that were used to
6450generate code (@option{-fpic}, @option{-fPIC}, or model suboptions)
6451when you specify this option.@footnote{On some systems, @samp{gcc -shared}
6452needs to build supplementary stub code for constructors to work. On
6453multi-libbed systems, @samp{gcc -shared} must select the correct support
6454libraries to link against. Failing to supply the correct flags may lead
6455to subtle defects. Supplying them in cases where they are not necessary
6456is innocuous.}
6457
6458@item -shared-libgcc
6459@itemx -static-libgcc
6460@opindex shared-libgcc
6461@opindex static-libgcc
6462On systems that provide @file{libgcc} as a shared library, these options
6463force the use of either the shared or static version respectively.
6464If no shared version of @file{libgcc} was built when the compiler was
6465configured, these options have no effect.
6466
6467There are several situations in which an application should use the
6468shared @file{libgcc} instead of the static version. The most common
6469of these is when the application wishes to throw and catch exceptions
6470across different shared libraries. In that case, each of the libraries
6471as well as the application itself should use the shared @file{libgcc}.
6472
6473Therefore, the G++ and GCJ drivers automatically add
6474@option{-shared-libgcc} whenever you build a shared library or a main
6475executable, because C++ and Java programs typically use exceptions, so
6476this is the right thing to do.
6477
6478If, instead, you use the GCC driver to create shared libraries, you may
6479find that they will not always be linked with the shared @file{libgcc}.
6480If GCC finds, at its configuration time, that you have a non-GNU linker
6481or a GNU linker that does not support option @option{--eh-frame-hdr},
6482it will link the shared version of @file{libgcc} into shared libraries
6483by default. Otherwise, it will take advantage of the linker and optimize
6484away the linking with the shared version of @file{libgcc}, linking with
6485the static version of libgcc by default. This allows exceptions to
6486propagate through such shared libraries, without incurring relocation
6487costs at library load time.
6488
6489However, if a library or main executable is supposed to throw or catch
6490exceptions, you must link it using the G++ or GCJ driver, as appropriate
6491for the languages used in the program, or using the option
6492@option{-shared-libgcc}, such that it is linked with the shared
6493@file{libgcc}.
6494
6495@item -symbolic
6496@opindex symbolic
6497Bind references to global symbols when building a shared object. Warn
6498about any unresolved references (unless overridden by the link editor
6499option @samp{-Xlinker -z -Xlinker defs}). Only a few systems support
6500this option.
6501
6502@item -Xlinker @var{option}
6503@opindex Xlinker
6504Pass @var{option} as an option to the linker. You can use this to
6505supply system-specific linker options which GCC does not know how to
6506recognize.
6507
6508If you want to pass an option that takes an argument, you must use
6509@option{-Xlinker} twice, once for the option and once for the argument.
6510For example, to pass @option{-assert definitions}, you must write
6511@samp{-Xlinker -assert -Xlinker definitions}. It does not work to write
6512@option{-Xlinker "-assert definitions"}, because this passes the entire
6513string as a single argument, which is not what the linker expects.
6514
6515@item -Wl,@var{option}
6516@opindex Wl
6517Pass @var{option} as an option to the linker. If @var{option} contains
6518commas, it is split into multiple options at the commas.
6519
6520@item -u @var{symbol}
6521@opindex u
6522Pretend the symbol @var{symbol} is undefined, to force linking of
6523library modules to define it. You can use @option{-u} multiple times with
6524different symbols to force loading of additional library modules.
6525@end table
6526
6527@node Directory Options
6528@section Options for Directory Search
6529@cindex directory options
6530@cindex options, directory search
6531@cindex search path
6532
6533These options specify directories to search for header files, for
6534libraries and for parts of the compiler:
6535
6536@table @gcctabopt
6537@item -I@var{dir}
6538@opindex I
6539Add the directory @var{dir} to the head of the list of directories to be
6540searched for header files. This can be used to override a system header
6541file, substituting your own version, since these directories are
6542searched before the system header file directories. However, you should
6543not use this option to add directories that contain vendor-supplied
6544system header files (use @option{-isystem} for that). If you use more than
6545one @option{-I} option, the directories are scanned in left-to-right
6546order; the standard system directories come after.
6547
6548If a standard system include directory, or a directory specified with
6549@option{-isystem}, is also specified with @option{-I}, the @option{-I}
6550option will be ignored. The directory will still be searched but as a
6551system directory at its normal position in the system include chain.
6552This is to ensure that GCC's procedure to fix buggy system headers and
6553the ordering for the include_next directive are not inadvertently changed.
6554If you really need to change the search order for system directories,
6555use the @option{-nostdinc} and/or @option{-isystem} options.
6556
6557@item -iquote@var{dir}
6558@opindex iquote
6559Add the directory @var{dir} to the head of the list of directories to
6560be searched for header files only for the case of @samp{#include
6561"@var{file}"}; they are not searched for @samp{#include <@var{file}>},
6562otherwise just like @option{-I}.
6563
6564@item -L@var{dir}
6565@opindex L
6566Add directory @var{dir} to the list of directories to be searched
6567for @option{-l}.
6568
6569@item -B@var{prefix}
6570@opindex B
6571This option specifies where to find the executables, libraries,
6572include files, and data files of the compiler itself.
6573
6574The compiler driver program runs one or more of the subprograms
6575@file{cpp}, @file{cc1}, @file{as} and @file{ld}. It tries
6576@var{prefix} as a prefix for each program it tries to run, both with and
6577without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}).
6578
6579For each subprogram to be run, the compiler driver first tries the
6580@option{-B} prefix, if any. If that name is not found, or if @option{-B}
6581was not specified, the driver tries two standard prefixes, which are
6582@file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc/}. If neither of
6583those results in a file name that is found, the unmodified program
6584name is searched for using the directories specified in your
6585@env{PATH} environment variable.
6586
6587The compiler will check to see if the path provided by the @option{-B}
6588refers to a directory, and if necessary it will add a directory
6589separator character at the end of the path.
6590
6591@option{-B} prefixes that effectively specify directory names also apply
6592to libraries in the linker, because the compiler translates these
6593options into @option{-L} options for the linker. They also apply to
6594includes files in the preprocessor, because the compiler translates these
6595options into @option{-isystem} options for the preprocessor. In this case,
6596the compiler appends @samp{include} to the prefix.
6597
6598The run-time support file @file{libgcc.a} can also be searched for using
6599the @option{-B} prefix, if needed. If it is not found there, the two
6600standard prefixes above are tried, and that is all. The file is left
6601out of the link if it is not found by those means.
6602
6603Another way to specify a prefix much like the @option{-B} prefix is to use
6604the environment variable @env{GCC_EXEC_PREFIX}. @xref{Environment
6605Variables}.
6606
6607As a special kludge, if the path provided by @option{-B} is
6608@file{[dir/]stage@var{N}/}, where @var{N} is a number in the range 0 to
66099, then it will be replaced by @file{[dir/]include}. This is to help
6610with boot-strapping the compiler.
6611
6612@item -specs=@var{file}
6613@opindex specs
6614Process @var{file} after the compiler reads in the standard @file{specs}
6615file, in order to override the defaults that the @file{gcc} driver
6616program uses when determining what switches to pass to @file{cc1},
6617@file{cc1plus}, @file{as}, @file{ld}, etc. More than one
6618@option{-specs=@var{file}} can be specified on the command line, and they
6619are processed in order, from left to right.
6620
6621@item --sysroot=@var{dir}
6622@opindex sysroot
6623Use @var{dir} as the logical root directory for headers and libraries.
6624For example, if the compiler would normally search for headers in
6625@file{/usr/include} and libraries in @file{/usr/lib}, it will instead
6626search @file{@var{dir}/usr/include} and @file{@var{dir}/usr/lib}.
6627
6628If you use both this option and the @option{-isysroot} option, then
6629the @option{--sysroot} option will apply to libraries, but the
6630@option{-isysroot} option will apply to header files.
6631
6632The GNU linker (beginning with version 2.16) has the necessary support
6633for this option. If your linker does not support this option, the
6634header file aspect of @option{--sysroot} will still work, but the
6635library aspect will not.
6636
6637@item -I-
6638@opindex I-
6639This option has been deprecated. Please use @option{-iquote} instead for
6640@option{-I} directories before the @option{-I-} and remove the @option{-I-}.
6641Any directories you specify with @option{-I} options before the @option{-I-}
6642option are searched only for the case of @samp{#include "@var{file}"};
6643they are not searched for @samp{#include <@var{file}>}.
6644
6645If additional directories are specified with @option{-I} options after
6646the @option{-I-}, these directories are searched for all @samp{#include}
6647directives. (Ordinarily @emph{all} @option{-I} directories are used
6648this way.)
6649
6650In addition, the @option{-I-} option inhibits the use of the current
6651directory (where the current input file came from) as the first search
6652directory for @samp{#include "@var{file}"}. There is no way to
6653override this effect of @option{-I-}. With @option{-I.} you can specify
6654searching the directory which was current when the compiler was
6655invoked. That is not exactly the same as what the preprocessor does
6656by default, but it is often satisfactory.
6657
6658@option{-I-} does not inhibit the use of the standard system directories
6659for header files. Thus, @option{-I-} and @option{-nostdinc} are
6660independent.
6661@end table
6662
6663@c man end
6664
6665@node Spec Files
6666@section Specifying subprocesses and the switches to pass to them
6667@cindex Spec Files
6668
6669@command{gcc} is a driver program. It performs its job by invoking a
6670sequence of other programs to do the work of compiling, assembling and
6671linking. GCC interprets its command-line parameters and uses these to
6672deduce which programs it should invoke, and which command-line options
6673it ought to place on their command lines. This behavior is controlled
6674by @dfn{spec strings}. In most cases there is one spec string for each
6675program that GCC can invoke, but a few programs have multiple spec
6676strings to control their behavior. The spec strings built into GCC can
6677be overridden by using the @option{-specs=} command-line switch to specify
6678a spec file.
6679
6680@dfn{Spec files} are plaintext files that are used to construct spec
6681strings. They consist of a sequence of directives separated by blank
6682lines. The type of directive is determined by the first non-whitespace
6683character on the line and it can be one of the following:
6684
6685@table @code
6686@item %@var{command}
6687Issues a @var{command} to the spec file processor. The commands that can
6688appear here are:
6689
6690@table @code
6691@item %include <@var{file}>
6692@cindex %include
6693Search for @var{file} and insert its text at the current point in the
6694specs file.
6695
6696@item %include_noerr <@var{file}>
6697@cindex %include_noerr
6698Just like @samp{%include}, but do not generate an error message if the include
6699file cannot be found.
6700
6701@item %rename @var{old_name} @var{new_name}
6702@cindex %rename
6703Rename the spec string @var{old_name} to @var{new_name}.
6704
6705@end table
6706
6707@item *[@var{spec_name}]:
6708This tells the compiler to create, override or delete the named spec
6709string. All lines after this directive up to the next directive or
6710blank line are considered to be the text for the spec string. If this
6711results in an empty string then the spec will be deleted. (Or, if the
6712spec did not exist, then nothing will happened.) Otherwise, if the spec
6713does not currently exist a new spec will be created. If the spec does
6714exist then its contents will be overridden by the text of this
6715directive, unless the first character of that text is the @samp{+}
6716character, in which case the text will be appended to the spec.
6717
6718@item [@var{suffix}]:
6719Creates a new @samp{[@var{suffix}] spec} pair. All lines after this directive
6720and up to the next directive or blank line are considered to make up the
6721spec string for the indicated suffix. When the compiler encounters an
6722input file with the named suffix, it will processes the spec string in
6723order to work out how to compile that file. For example:
6724
6725@smallexample
6726.ZZ:
6727z-compile -input %i
6728@end smallexample
6729
6730This says that any input file whose name ends in @samp{.ZZ} should be
6731passed to the program @samp{z-compile}, which should be invoked with the
6732command-line switch @option{-input} and with the result of performing the
6733@samp{%i} substitution. (See below.)
6734
6735As an alternative to providing a spec string, the text that follows a
6736suffix directive can be one of the following:
6737
6738@table @code
6739@item @@@var{language}
6740This says that the suffix is an alias for a known @var{language}. This is
6741similar to using the @option{-x} command-line switch to GCC to specify a
6742language explicitly. For example:
6743
6744@smallexample
6745.ZZ:
6746@@c++
6747@end smallexample
6748
6749Says that .ZZ files are, in fact, C++ source files.
6750
6751@item #@var{name}
6752This causes an error messages saying:
6753
6754@smallexample
6755@var{name} compiler not installed on this system.
6756@end smallexample
6757@end table
6758
6759GCC already has an extensive list of suffixes built into it.
6760This directive will add an entry to the end of the list of suffixes, but
6761since the list is searched from the end backwards, it is effectively
6762possible to override earlier entries using this technique.
6763
6764@end table
6765
6766GCC has the following spec strings built into it. Spec files can
6767override these strings or create their own. Note that individual
6768targets can also add their own spec strings to this list.
6769
6770@smallexample
6771asm Options to pass to the assembler
6772asm_final Options to pass to the assembler post-processor
6773cpp Options to pass to the C preprocessor
6774cc1 Options to pass to the C compiler
6775cc1plus Options to pass to the C++ compiler
6776endfile Object files to include at the end of the link
6777link Options to pass to the linker
6778lib Libraries to include on the command line to the linker
6779libgcc Decides which GCC support library to pass to the linker
6780linker Sets the name of the linker
6781predefines Defines to be passed to the C preprocessor
6782signed_char Defines to pass to CPP to say whether @code{char} is signed
6783 by default
6784startfile Object files to include at the start of the link
6785@end smallexample
6786
6787Here is a small example of a spec file:
6788
6789@smallexample
6790%rename lib old_lib
6791
6792*lib:
6793--start-group -lgcc -lc -leval1 --end-group %(old_lib)
6794@end smallexample
6795
6796This example renames the spec called @samp{lib} to @samp{old_lib} and
6797then overrides the previous definition of @samp{lib} with a new one.
6798The new definition adds in some extra command-line options before
6799including the text of the old definition.
6800
6801@dfn{Spec strings} are a list of command-line options to be passed to their
6802corresponding program. In addition, the spec strings can contain
6803@samp{%}-prefixed sequences to substitute variable text or to
6804conditionally insert text into the command line. Using these constructs
6805it is possible to generate quite complex command lines.
6806
6807Here is a table of all defined @samp{%}-sequences for spec
6808strings. Note that spaces are not generated automatically around the
6809results of expanding these sequences. Therefore you can concatenate them
6810together or combine them with constant text in a single argument.
6811
6812@table @code
6813@item %%
6814Substitute one @samp{%} into the program name or argument.
6815
6816@item %i
6817Substitute the name of the input file being processed.
6818
6819@item %b
6820Substitute the basename of the input file being processed.
6821This is the substring up to (and not including) the last period
6822and not including the directory.
6823
6824@item %B
6825This is the same as @samp{%b}, but include the file suffix (text after
6826the last period).
6827
6828@item %d
6829Marks the argument containing or following the @samp{%d} as a
6830temporary file name, so that that file will be deleted if GCC exits
6831successfully. Unlike @samp{%g}, this contributes no text to the
6832argument.
6833
6834@item %g@var{suffix}
6835Substitute a file name that has suffix @var{suffix} and is chosen
6836once per compilation, and mark the argument in the same way as
6837@samp{%d}. To reduce exposure to denial-of-service attacks, the file
6838name is now chosen in a way that is hard to predict even when previously
6839chosen file names are known. For example, @samp{%g.s @dots{} %g.o @dots{} %g.s}
6840might turn into @samp{ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s}. @var{suffix} matches
6841the regexp @samp{[.A-Za-z]*} or the special string @samp{%O}, which is
6842treated exactly as if @samp{%O} had been preprocessed. Previously, @samp{%g}
6843was simply substituted with a file name chosen once per compilation,
6844without regard to any appended suffix (which was therefore treated
6845just like ordinary text), making such attacks more likely to succeed.
6846
6847@item %u@var{suffix}
6848Like @samp{%g}, but generates a new temporary file name even if
6849@samp{%u@var{suffix}} was already seen.
6850
6851@item %U@var{suffix}
6852Substitutes the last file name generated with @samp{%u@var{suffix}}, generating a
6853new one if there is no such last file name. In the absence of any
6854@samp{%u@var{suffix}}, this is just like @samp{%g@var{suffix}}, except they don't share
6855the same suffix @emph{space}, so @samp{%g.s @dots{} %U.s @dots{} %g.s @dots{} %U.s}
6856would involve the generation of two distinct file names, one
6857for each @samp{%g.s} and another for each @samp{%U.s}. Previously, @samp{%U} was
6858simply substituted with a file name chosen for the previous @samp{%u},
6859without regard to any appended suffix.
6860
6861@item %j@var{suffix}
6862Substitutes the name of the @code{HOST_BIT_BUCKET}, if any, and if it is
6863writable, and if save-temps is off; otherwise, substitute the name
6864of a temporary file, just like @samp{%u}. This temporary file is not
6865meant for communication between processes, but rather as a junk
6866disposal mechanism.
6867
6868@item %|@var{suffix}
6869@itemx %m@var{suffix}
6870Like @samp{%g}, except if @option{-pipe} is in effect. In that case
6871@samp{%|} substitutes a single dash and @samp{%m} substitutes nothing at
6872all. These are the two most common ways to instruct a program that it
6873should read from standard input or write to standard output. If you
6874need something more elaborate you can use an @samp{%@{pipe:@code{X}@}}
6875construct: see for example @file{f/lang-specs.h}.
6876
6877@item %.@var{SUFFIX}
6878Substitutes @var{.SUFFIX} for the suffixes of a matched switch's args
6879when it is subsequently output with @samp{%*}. @var{SUFFIX} is
6880terminated by the next space or %.
6881
6882@item %w
6883Marks the argument containing or following the @samp{%w} as the
6884designated output file of this compilation. This puts the argument
6885into the sequence of arguments that @samp{%o} will substitute later.
6886
6887@item %o
6888Substitutes the names of all the output files, with spaces
6889automatically placed around them. You should write spaces
6890around the @samp{%o} as well or the results are undefined.
6891@samp{%o} is for use in the specs for running the linker.
6892Input files whose names have no recognized suffix are not compiled
6893at all, but they are included among the output files, so they will
6894be linked.
6895
6896@item %O
6897Substitutes the suffix for object files. Note that this is
6898handled specially when it immediately follows @samp{%g, %u, or %U},
6899because of the need for those to form complete file names. The
6900handling is such that @samp{%O} is treated exactly as if it had already
6901been substituted, except that @samp{%g, %u, and %U} do not currently
6902support additional @var{suffix} characters following @samp{%O} as they would
6903following, for example, @samp{.o}.
6904
6905@item %p
6906Substitutes the standard macro predefinitions for the
6907current target machine. Use this when running @code{cpp}.
6908
6909@item %P
6910Like @samp{%p}, but puts @samp{__} before and after the name of each
6911predefined macro, except for macros that start with @samp{__} or with
6912@samp{_@var{L}}, where @var{L} is an uppercase letter. This is for ISO
6913C@.
6914
6915@item %I
6916Substitute any of @option{-iprefix} (made from @env{GCC_EXEC_PREFIX}),
6917@option{-isysroot} (made from @env{TARGET_SYSTEM_ROOT}),
6918@option{-isystem} (made from @env{COMPILER_PATH} and @option{-B} options)
6919and @option{-imultilib} as necessary.
6920
6921@item %s
6922Current argument is the name of a library or startup file of some sort.
6923Search for that file in a standard list of directories and substitute
6924the full name found.
6925
6926@item %e@var{str}
6927Print @var{str} as an error message. @var{str} is terminated by a newline.
6928Use this when inconsistent options are detected.
6929
6930@item %(@var{name})
6931Substitute the contents of spec string @var{name} at this point.
6932
6933@item %[@var{name}]
6934Like @samp{%(@dots{})} but put @samp{__} around @option{-D} arguments.
6935
6936@item %x@{@var{option}@}
6937Accumulate an option for @samp{%X}.
6938
6939@item %X
6940Output the accumulated linker options specified by @option{-Wl} or a @samp{%x}
6941spec string.
6942
6943@item %Y
6944Output the accumulated assembler options specified by @option{-Wa}.
6945
6946@item %Z
6947Output the accumulated preprocessor options specified by @option{-Wp}.
6948
6949@item %a
6950Process the @code{asm} spec. This is used to compute the
6951switches to be passed to the assembler.
6952
6953@item %A
6954Process the @code{asm_final} spec. This is a spec string for
6955passing switches to an assembler post-processor, if such a program is
6956needed.
6957
6958@item %l
6959Process the @code{link} spec. This is the spec for computing the
6960command line passed to the linker. Typically it will make use of the
6961@samp{%L %G %S %D and %E} sequences.
6962
6963@item %D
6964Dump out a @option{-L} option for each directory that GCC believes might
6965contain startup files. If the target supports multilibs then the
6966current multilib directory will be prepended to each of these paths.
6967
6968@item %L
6969Process the @code{lib} spec. This is a spec string for deciding which
6970libraries should be included on the command line to the linker.
6971
6972@item %G
6973Process the @code{libgcc} spec. This is a spec string for deciding
6974which GCC support library should be included on the command line to the linker.
6975
6976@item %S
6977Process the @code{startfile} spec. This is a spec for deciding which
6978object files should be the first ones passed to the linker. Typically
6979this might be a file named @file{crt0.o}.
6980
6981@item %E
6982Process the @code{endfile} spec. This is a spec string that specifies
6983the last object files that will be passed to the linker.
6984
6985@item %C
6986Process the @code{cpp} spec. This is used to construct the arguments
6987to be passed to the C preprocessor.
6988
6989@item %1
6990Process the @code{cc1} spec. This is used to construct the options to be
6991passed to the actual C compiler (@samp{cc1}).
6992
6993@item %2
6994Process the @code{cc1plus} spec. This is used to construct the options to be
6995passed to the actual C++ compiler (@samp{cc1plus}).
6996
6997@item %*
6998Substitute the variable part of a matched option. See below.
6999Note that each comma in the substituted string is replaced by
7000a single space.
7001
7002@item %<@code{S}
7003Remove all occurrences of @code{-S} from the command line. Note---this
7004command is position dependent. @samp{%} commands in the spec string
7005before this one will see @code{-S}, @samp{%} commands in the spec string
7006after this one will not.
7007
7008@item %:@var{function}(@var{args})
7009Call the named function @var{function}, passing it @var{args}.
7010@var{args} is first processed as a nested spec string, then split
7011into an argument vector in the usual fashion. The function returns
7012a string which is processed as if it had appeared literally as part
7013of the current spec.
7014
7015The following built-in spec functions are provided:
7016
7017@table @code
7018@item @code{if-exists}
7019The @code{if-exists} spec function takes one argument, an absolute
7020pathname to a file. If the file exists, @code{if-exists} returns the
7021pathname. Here is a small example of its usage:
7022
7023@smallexample
7024*startfile:
7025crt0%O%s %:if-exists(crti%O%s) crtbegin%O%s
7026@end smallexample
7027
7028@item @code{if-exists-else}
7029The @code{if-exists-else} spec function is similar to the @code{if-exists}
7030spec function, except that it takes two arguments. The first argument is
7031an absolute pathname to a file. If the file exists, @code{if-exists-else}
7032returns the pathname. If it does not exist, it returns the second argument.
7033This way, @code{if-exists-else} can be used to select one file or another,
7034based on the existence of the first. Here is a small example of its usage:
7035
7036@smallexample
7037*startfile:
7038crt0%O%s %:if-exists(crti%O%s) \
7039%:if-exists-else(crtbeginT%O%s crtbegin%O%s)
7040@end smallexample
7041
7042@item @code{replace-outfile}
7043The @code{replace-outfile} spec function takes two arguments. It looks for the
7044first argument in the outfiles array and replaces it with the second argument. Here
7045is a small example of its usage:
7046
7047@smallexample
7048%@{static|static-libgcc|static-libstdc++:%:replace-outfile(-lstdc++ \
7049libstdc++.a%s)@}
7050
7051@end smallexample
7052
7053@end table
7054
7055@item %@{@code{S}@}
7056Substitutes the @code{-S} switch, if that switch was given to GCC@.
7057If that switch was not specified, this substitutes nothing. Note that
7058the leading dash is omitted when specifying this option, and it is
7059automatically inserted if the substitution is performed. Thus the spec
7060string @samp{%@{foo@}} would match the command-line option @option{-foo}
7061and would output the command line option @option{-foo}.
7062
7063@item %W@{@code{S}@}
7064Like %@{@code{S}@} but mark last argument supplied within as a file to be
7065deleted on failure.
7066
7067@item %@{@code{S}*@}
7068Substitutes all the switches specified to GCC whose names start
7069with @code{-S}, but which also take an argument. This is used for
7070switches like @option{-o}, @option{-D}, @option{-I}, etc.
7071GCC considers @option{-o foo} as being
7072one switch whose names starts with @samp{o}. %@{o*@} would substitute this
7073text, including the space. Thus two arguments would be generated.
7074
7075@item %@{@code{S}*&@code{T}*@}
7076Like %@{@code{S}*@}, but preserve order of @code{S} and @code{T} options
7077(the order of @code{S} and @code{T} in the spec is not significant).
7078There can be any number of ampersand-separated variables; for each the
7079wild card is optional. Useful for CPP as @samp{%@{D*&U*&A*@}}.
7080
7081@item %@{@code{S}:@code{X}@}
7082Substitutes @code{X}, if the @samp{-S} switch was given to GCC@.
7083
7084@item %@{!@code{S}:@code{X}@}
7085Substitutes @code{X}, if the @samp{-S} switch was @emph{not} given to GCC@.
7086
7087@item %@{@code{S}*:@code{X}@}
7088Substitutes @code{X} if one or more switches whose names start with
7089@code{-S} are specified to GCC@. Normally @code{X} is substituted only
7090once, no matter how many such switches appeared. However, if @code{%*}
7091appears somewhere in @code{X}, then @code{X} will be substituted once
7092for each matching switch, with the @code{%*} replaced by the part of
7093that switch that matched the @code{*}.
7094
7095@item %@{.@code{S}:@code{X}@}
7096Substitutes @code{X}, if processing a file with suffix @code{S}.
7097
7098@item %@{!.@code{S}:@code{X}@}
7099Substitutes @code{X}, if @emph{not} processing a file with suffix @code{S}.
7100
7101@item %@{@code{S}|@code{P}:@code{X}@}
7102Substitutes @code{X} if either @code{-S} or @code{-P} was given to GCC@.
7103This may be combined with @samp{!}, @samp{.}, and @code{*} sequences as well,
7104although they have a stronger binding than the @samp{|}. If @code{%*}
7105appears in @code{X}, all of the alternatives must be starred, and only
7106the first matching alternative is substituted.
7107
7108For example, a spec string like this:
7109
7110@smallexample
7111%@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@}
7112@end smallexample
7113
7114will output the following command-line options from the following input
7115command-line options:
7116
7117@smallexample
7118fred.c -foo -baz
7119jim.d -bar -boggle
7120-d fred.c -foo -baz -boggle
7121-d jim.d -bar -baz -boggle
7122@end smallexample
7123
7124@item %@{S:X; T:Y; :D@}
7125
7126If @code{S} was given to GCC, substitutes @code{X}; else if @code{T} was
7127given to GCC, substitutes @code{Y}; else substitutes @code{D}. There can
7128be as many clauses as you need. This may be combined with @code{.},
7129@code{!}, @code{|}, and @code{*} as needed.
7130
7131
7132@end table
7133
7134The conditional text @code{X} in a %@{@code{S}:@code{X}@} or similar
7135construct may contain other nested @samp{%} constructs or spaces, or
7136even newlines. They are processed as usual, as described above.
7137Trailing white space in @code{X} is ignored. White space may also
7138appear anywhere on the left side of the colon in these constructs,
7139except between @code{.} or @code{*} and the corresponding word.
7140
7141The @option{-O}, @option{-f}, @option{-m}, and @option{-W} switches are
7142handled specifically in these constructs. If another value of
7143@option{-O} or the negated form of a @option{-f}, @option{-m}, or
7144@option{-W} switch is found later in the command line, the earlier
7145switch value is ignored, except with @{@code{S}*@} where @code{S} is
7146just one letter, which passes all matching options.
7147
7148The character @samp{|} at the beginning of the predicate text is used to
7149indicate that a command should be piped to the following command, but
7150only if @option{-pipe} is specified.
7151
7152It is built into GCC which switches take arguments and which do not.
7153(You might think it would be useful to generalize this to allow each
7154compiler's spec to say which switches take arguments. But this cannot
7155be done in a consistent fashion. GCC cannot even decide which input
7156files have been specified without knowing which switches take arguments,
7157and it must know which input files to compile in order to tell which
7158compilers to run).
7159
7160GCC also knows implicitly that arguments starting in @option{-l} are to be
7161treated as compiler output files, and passed to the linker in their
7162proper position among the other output files.
7163
7164@c man begin OPTIONS
7165
7166@node Target Options
7167@section Specifying Target Machine and Compiler Version
7168@cindex target options
7169@cindex cross compiling
7170@cindex specifying machine version
7171@cindex specifying compiler version and target machine
7172@cindex compiler version, specifying
7173@cindex target machine, specifying
7174
7175The usual way to run GCC is to run the executable called @file{gcc}, or
7176@file{<machine>-gcc} when cross-compiling, or
7177@file{<machine>-gcc-<version>} to run a version other than the one that
7178was installed last. Sometimes this is inconvenient, so GCC provides
7179options that will switch to another cross-compiler or version.
7180
7181@table @gcctabopt
7182@item -b @var{machine}
7183@opindex b
7184The argument @var{machine} specifies the target machine for compilation.
7185
7186The value to use for @var{machine} is the same as was specified as the
7187machine type when configuring GCC as a cross-compiler. For
7188example, if a cross-compiler was configured with @samp{configure
7189arm-elf}, meaning to compile for an arm processor with elf binaries,
7190then you would specify @option{-b arm-elf} to run that cross compiler.
7191Because there are other options beginning with @option{-b}, the
7192configuration must contain a hyphen.
7193
7194@item -V @var{version}
7195@opindex V
7196The argument @var{version} specifies which version of GCC to run.
7197This is useful when multiple versions are installed. For example,
7198@var{version} might be @samp{4.0}, meaning to run GCC version 4.0.
7199@end table
7200
7201The @option{-V} and @option{-b} options work by running the
7202@file{<machine>-gcc-<version>} executable, so there's no real reason to
7203use them if you can just run that directly.
7204
7205@node Submodel Options
7206@section Hardware Models and Configurations
7207@cindex submodel options
7208@cindex specifying hardware config
7209@cindex hardware models and configurations, specifying
7210@cindex machine dependent options
7211
7212Earlier we discussed the standard option @option{-b} which chooses among
7213different installed compilers for completely different target
7214machines, such as VAX vs.@: 68000 vs.@: 80386.
7215
7216In addition, each of these target machine types can have its own
7217special options, starting with @samp{-m}, to choose among various
7218hardware models or configurations---for example, 68010 vs 68020,
7219floating coprocessor or none. A single installed version of the
7220compiler can compile for any model or configuration, according to the
7221options specified.
7222
7223Some configurations of the compiler also support additional special
7224options, usually for compatibility with other compilers on the same
7225platform.
7226
7227@c This list is ordered alphanumerically by subsection name.
7228@c It should be the same order and spelling as these options are listed
7229@c in Machine Dependent Options
7230
7231@menu
7232* ARC Options::
7233* ARM Options::
7234* AVR Options::
7235* Blackfin Options::
7236* CRIS Options::
7237* CRX Options::
7238* Darwin Options::
7239* DEC Alpha Options::
7240* DEC Alpha/VMS Options::
7241* FRV Options::
7242* GNU/Linux Options::
7243* H8/300 Options::
7244* HPPA Options::
7245* i386 and x86-64 Options::
7246* IA-64 Options::
7247* M32C Options::
7248* M32R/D Options::
7249* M680x0 Options::
7250* M68hc1x Options::
7251* MCore Options::
7252* MIPS Options::
7253* MMIX Options::
7254* MN10300 Options::
7255* MT Options::
7256* PDP-11 Options::
7257* PowerPC Options::
7258* RS/6000 and PowerPC Options::
7259* S/390 and zSeries Options::
7260* Score Options::
7261* SH Options::
7262* SPARC Options::
7263* System V Options::
7264* TMS320C3x/C4x Options::
7265* V850 Options::
7266* VAX Options::
7267* x86-64 Options::
7268* Xstormy16 Options::
7269* Xtensa Options::
7270* zSeries Options::
7271@end menu
7272
7273@node ARC Options
7274@subsection ARC Options
7275@cindex ARC Options
7276
7277These options are defined for ARC implementations:
7278
7279@table @gcctabopt
7280@item -EL
7281@opindex EL
7282Compile code for little endian mode. This is the default.
7283
7284@item -EB
7285@opindex EB
7286Compile code for big endian mode.
7287
7288@item -mmangle-cpu
7289@opindex mmangle-cpu
7290Prepend the name of the cpu to all public symbol names.
7291In multiple-processor systems, there are many ARC variants with different
7292instruction and register set characteristics. This flag prevents code
7293compiled for one cpu to be linked with code compiled for another.
7294No facility exists for handling variants that are ``almost identical''.
7295This is an all or nothing option.
7296
7297@item -mcpu=@var{cpu}
7298@opindex mcpu
7299Compile code for ARC variant @var{cpu}.
7300Which variants are supported depend on the configuration.
7301All variants support @option{-mcpu=base}, this is the default.
7302
7303@item -mtext=@var{text-section}
7304@itemx -mdata=@var{data-section}
7305@itemx -mrodata=@var{readonly-data-section}
7306@opindex mtext
7307@opindex mdata
7308@opindex mrodata
7309Put functions, data, and readonly data in @var{text-section},
7310@var{data-section}, and @var{readonly-data-section} respectively
7311by default. This can be overridden with the @code{section} attribute.
7312@xref{Variable Attributes}.
7313
7314@end table
7315
7316@node ARM Options
7317@subsection ARM Options
7318@cindex ARM options
7319
7320These @samp{-m} options are defined for Advanced RISC Machines (ARM)
7321architectures:
7322
7323@table @gcctabopt
7324@item -mabi=@var{name}
7325@opindex mabi
7326Generate code for the specified ABI@. Permissible values are: @samp{apcs-gnu},
7327@samp{atpcs}, @samp{aapcs}, @samp{aapcs-linux} and @samp{iwmmxt}.
7328
7329@item -mapcs-frame
7330@opindex mapcs-frame
7331Generate a stack frame that is compliant with the ARM Procedure Call
7332Standard for all functions, even if this is not strictly necessary for
7333correct execution of the code. Specifying @option{-fomit-frame-pointer}
7334with this option will cause the stack frames not to be generated for
7335leaf functions. The default is @option{-mno-apcs-frame}.
7336
7337@item -mapcs
7338@opindex mapcs
7339This is a synonym for @option{-mapcs-frame}.
7340
7341@ignore
7342@c not currently implemented
7343@item -mapcs-stack-check
7344@opindex mapcs-stack-check
7345Generate code to check the amount of stack space available upon entry to
7346every function (that actually uses some stack space). If there is
7347insufficient space available then either the function
7348@samp{__rt_stkovf_split_small} or @samp{__rt_stkovf_split_big} will be
7349called, depending upon the amount of stack space required. The run time
7350system is required to provide these functions. The default is
7351@option{-mno-apcs-stack-check}, since this produces smaller code.
7352
7353@c not currently implemented
7354@item -mapcs-float
7355@opindex mapcs-float
7356Pass floating point arguments using the float point registers. This is
7357one of the variants of the APCS@. This option is recommended if the
7358target hardware has a floating point unit or if a lot of floating point
7359arithmetic is going to be performed by the code. The default is
7360@option{-mno-apcs-float}, since integer only code is slightly increased in
7361size if @option{-mapcs-float} is used.
7362
7363@c not currently implemented
7364@item -mapcs-reentrant
7365@opindex mapcs-reentrant
7366Generate reentrant, position independent code. The default is
7367@option{-mno-apcs-reentrant}.
7368@end ignore
7369
7370@item -mthumb-interwork
7371@opindex mthumb-interwork
7372Generate code which supports calling between the ARM and Thumb
7373instruction sets. Without this option the two instruction sets cannot
7374be reliably used inside one program. The default is
7375@option{-mno-thumb-interwork}, since slightly larger code is generated
7376when @option{-mthumb-interwork} is specified.
7377
7378@item -mno-sched-prolog
7379@opindex mno-sched-prolog
7380Prevent the reordering of instructions in the function prolog, or the
7381merging of those instruction with the instructions in the function's
7382body. This means that all functions will start with a recognizable set
7383of instructions (or in fact one of a choice from a small set of
7384different function prologues), and this information can be used to
7385locate the start if functions inside an executable piece of code. The
7386default is @option{-msched-prolog}.
7387
7388@item -mhard-float
7389@opindex mhard-float
7390Generate output containing floating point instructions. This is the
7391default.
7392
7393@item -msoft-float
7394@opindex msoft-float
7395Generate output containing library calls for floating point.
7396@strong{Warning:} the requisite libraries are not available for all ARM
7397targets. Normally the facilities of the machine's usual C compiler are
7398used, but this cannot be done directly in cross-compilation. You must make
7399your own arrangements to provide suitable library functions for
7400cross-compilation.
7401
7402@option{-msoft-float} changes the calling convention in the output file;
7403therefore, it is only useful if you compile @emph{all} of a program with
7404this option. In particular, you need to compile @file{libgcc.a}, the
7405library that comes with GCC, with @option{-msoft-float} in order for
7406this to work.
7407
7408@item -mfloat-abi=@var{name}
7409@opindex mfloat-abi
7410Specifies which ABI to use for floating point values. Permissible values
7411are: @samp{soft}, @samp{softfp} and @samp{hard}.
7412
7413@samp{soft} and @samp{hard} are equivalent to @option{-msoft-float}
7414and @option{-mhard-float} respectively. @samp{softfp} allows the generation
7415of floating point instructions, but still uses the soft-float calling
7416conventions.
7417
7418@item -mlittle-endian
7419@opindex mlittle-endian
7420Generate code for a processor running in little-endian mode. This is
7421the default for all standard configurations.
7422
7423@item -mbig-endian
7424@opindex mbig-endian
7425Generate code for a processor running in big-endian mode; the default is
7426to compile code for a little-endian processor.
7427
7428@item -mwords-little-endian
7429@opindex mwords-little-endian
7430This option only applies when generating code for big-endian processors.
7431Generate code for a little-endian word order but a big-endian byte
7432order. That is, a byte order of the form @samp{32107654}. Note: this
7433option should only be used if you require compatibility with code for
7434big-endian ARM processors generated by versions of the compiler prior to
74352.8.
7436
7437@item -mcpu=@var{name}
7438@opindex mcpu
7439This specifies the name of the target ARM processor. GCC uses this name
7440to determine what kind of instructions it can emit when generating
7441assembly code. Permissible names are: @samp{arm2}, @samp{arm250},
7442@samp{arm3}, @samp{arm6}, @samp{arm60}, @samp{arm600}, @samp{arm610},
7443@samp{arm620}, @samp{arm7}, @samp{arm7m}, @samp{arm7d}, @samp{arm7dm},
7444@samp{arm7di}, @samp{arm7dmi}, @samp{arm70}, @samp{arm700},
7445@samp{arm700i}, @samp{arm710}, @samp{arm710c}, @samp{arm7100},
7446@samp{arm7500}, @samp{arm7500fe}, @samp{arm7tdmi}, @samp{arm7tdmi-s},
7447@samp{arm8}, @samp{strongarm}, @samp{strongarm110}, @samp{strongarm1100},
7448@samp{arm8}, @samp{arm810}, @samp{arm9}, @samp{arm9e}, @samp{arm920},
7449@samp{arm920t}, @samp{arm922t}, @samp{arm946e-s}, @samp{arm966e-s},
7450@samp{arm968e-s}, @samp{arm926ej-s}, @samp{arm940t}, @samp{arm9tdmi},
7451@samp{arm10tdmi}, @samp{arm1020t}, @samp{arm1026ej-s},
7452@samp{arm10e}, @samp{arm1020e}, @samp{arm1022e},
7453@samp{arm1136j-s}, @samp{arm1136jf-s}, @samp{mpcore}, @samp{mpcorenovfp},
7454@samp{arm1176jz-s}, @samp{arm1176jzf-s}, @samp{xscale}, @samp{iwmmxt},
7455@samp{ep9312}.
7456
7457@itemx -mtune=@var{name}
7458@opindex mtune
7459This option is very similar to the @option{-mcpu=} option, except that
7460instead of specifying the actual target processor type, and hence
7461restricting which instructions can be used, it specifies that GCC should
7462tune the performance of the code as if the target were of the type
7463specified in this option, but still choosing the instructions that it
7464will generate based on the cpu specified by a @option{-mcpu=} option.
7465For some ARM implementations better performance can be obtained by using
7466this option.
7467
7468@item -march=@var{name}
7469@opindex march
7470This specifies the name of the target ARM architecture. GCC uses this
7471name to determine what kind of instructions it can emit when generating
7472assembly code. This option can be used in conjunction with or instead
7473of the @option{-mcpu=} option. Permissible names are: @samp{armv2},
7474@samp{armv2a}, @samp{armv3}, @samp{armv3m}, @samp{armv4}, @samp{armv4t},
7475@samp{armv5}, @samp{armv5t}, @samp{armv5te}, @samp{armv6}, @samp{armv6j},
7476@samp{iwmmxt}, @samp{ep9312}.
7477
7478@item -mfpu=@var{name}
7479@itemx -mfpe=@var{number}
7480@itemx -mfp=@var{number}
7481@opindex mfpu
7482@opindex mfpe
7483@opindex mfp
7484This specifies what floating point hardware (or hardware emulation) is
7485available on the target. Permissible names are: @samp{fpa}, @samp{fpe2},
7486@samp{fpe3}, @samp{maverick}, @samp{vfp}. @option{-mfp} and @option{-mfpe}
7487are synonyms for @option{-mfpu}=@samp{fpe}@var{number}, for compatibility
7488with older versions of GCC@.
7489
7490If @option{-msoft-float} is specified this specifies the format of
7491floating point values.
7492
7493@item -mstructure-size-boundary=@var{n}
7494@opindex mstructure-size-boundary
7495The size of all structures and unions will be rounded up to a multiple
7496of the number of bits set by this option. Permissible values are 8, 32
7497and 64. The default value varies for different toolchains. For the COFF
7498targeted toolchain the default value is 8. A value of 64 is only allowed
7499if the underlying ABI supports it.
7500
7501Specifying the larger number can produce faster, more efficient code, but
7502can also increase the size of the program. Different values are potentially
7503incompatible. Code compiled with one value cannot necessarily expect to
7504work with code or libraries compiled with another value, if they exchange
7505information using structures or unions.
7506
7507@item -mabort-on-noreturn
7508@opindex mabort-on-noreturn
7509Generate a call to the function @code{abort} at the end of a
7510@code{noreturn} function. It will be executed if the function tries to
7511return.
7512
7513@item -mlong-calls
7514@itemx -mno-long-calls
7515@opindex mlong-calls
7516@opindex mno-long-calls
7517Tells the compiler to perform function calls by first loading the
7518address of the function into a register and then performing a subroutine
7519call on this register. This switch is needed if the target function
7520will lie outside of the 64 megabyte addressing range of the offset based
7521version of subroutine call instruction.
7522
7523Even if this switch is enabled, not all function calls will be turned
7524into long calls. The heuristic is that static functions, functions
7525which have the @samp{short-call} attribute, functions that are inside
7526the scope of a @samp{#pragma no_long_calls} directive and functions whose
7527definitions have already been compiled within the current compilation
7528unit, will not be turned into long calls. The exception to this rule is
7529that weak function definitions, functions with the @samp{long-call}
7530attribute or the @samp{section} attribute, and functions that are within
7531the scope of a @samp{#pragma long_calls} directive, will always be
7532turned into long calls.
7533
7534This feature is not enabled by default. Specifying
7535@option{-mno-long-calls} will restore the default behavior, as will
7536placing the function calls within the scope of a @samp{#pragma
7537long_calls_off} directive. Note these switches have no effect on how
7538the compiler generates code to handle function calls via function
7539pointers.
7540
7541@item -mnop-fun-dllimport
7542@opindex mnop-fun-dllimport
7543Disable support for the @code{dllimport} attribute.
7544
7545@item -msingle-pic-base
7546@opindex msingle-pic-base
7547Treat the register used for PIC addressing as read-only, rather than
7548loading it in the prologue for each function. The run-time system is
7549responsible for initializing this register with an appropriate value
7550before execution begins.
7551
7552@item -mpic-register=@var{reg}
7553@opindex mpic-register
7554Specify the register to be used for PIC addressing. The default is R10
7555unless stack-checking is enabled, when R9 is used.
7556
7557@item -mcirrus-fix-invalid-insns
7558@opindex mcirrus-fix-invalid-insns
7559@opindex mno-cirrus-fix-invalid-insns
7560Insert NOPs into the instruction stream to in order to work around
7561problems with invalid Maverick instruction combinations. This option
7562is only valid if the @option{-mcpu=ep9312} option has been used to
7563enable generation of instructions for the Cirrus Maverick floating
7564point co-processor. This option is not enabled by default, since the
7565problem is only present in older Maverick implementations. The default
7566can be re-enabled by use of the @option{-mno-cirrus-fix-invalid-insns}
7567switch.
7568
7569@item -mpoke-function-name
7570@opindex mpoke-function-name
7571Write the name of each function into the text section, directly
7572preceding the function prologue. The generated code is similar to this:
7573
7574@smallexample
7575 t0
7576 .ascii "arm_poke_function_name", 0
7577 .align
7578 t1
7579 .word 0xff000000 + (t1 - t0)
7580 arm_poke_function_name
7581 mov ip, sp
7582 stmfd sp!, @{fp, ip, lr, pc@}
7583 sub fp, ip, #4
7584@end smallexample
7585
7586When performing a stack backtrace, code can inspect the value of
7587@code{pc} stored at @code{fp + 0}. If the trace function then looks at
7588location @code{pc - 12} and the top 8 bits are set, then we know that
7589there is a function name embedded immediately preceding this location
7590and has length @code{((pc[-3]) & 0xff000000)}.
7591
7592@item -mthumb
7593@opindex mthumb
7594Generate code for the 16-bit Thumb instruction set. The default is to
7595use the 32-bit ARM instruction set.
7596
7597@item -mtpcs-frame
7598@opindex mtpcs-frame
7599Generate a stack frame that is compliant with the Thumb Procedure Call
7600Standard for all non-leaf functions. (A leaf function is one that does
7601not call any other functions.) The default is @option{-mno-tpcs-frame}.
7602
7603@item -mtpcs-leaf-frame
7604@opindex mtpcs-leaf-frame
7605Generate a stack frame that is compliant with the Thumb Procedure Call
7606Standard for all leaf functions. (A leaf function is one that does
7607not call any other functions.) The default is @option{-mno-apcs-leaf-frame}.
7608
7609@item -mcallee-super-interworking
7610@opindex mcallee-super-interworking
7611Gives all externally visible functions in the file being compiled an ARM
7612instruction set header which switches to Thumb mode before executing the
7613rest of the function. This allows these functions to be called from
7614non-interworking code.
7615
7616@item -mcaller-super-interworking
7617@opindex mcaller-super-interworking
7618Allows calls via function pointers (including virtual functions) to
7619execute correctly regardless of whether the target code has been
7620compiled for interworking or not. There is a small overhead in the cost
7621of executing a function pointer if this option is enabled.
7622
7623@item -mtp=@var{name}
7624@opindex mtp
7625Specify the access model for the thread local storage pointer. The valid
7626models are @option{soft}, which generates calls to @code{__aeabi_read_tp},
7627@option{cp15}, which fetches the thread pointer from @code{cp15} directly
7628(supported in the arm6k architecture), and @option{auto}, which uses the
7629best available method for the selected processor. The default setting is
7630@option{auto}.
7631
7632@end table
7633
7634@node AVR Options
7635@subsection AVR Options
7636@cindex AVR Options
7637
7638These options are defined for AVR implementations:
7639
7640@table @gcctabopt
7641@item -mmcu=@var{mcu}
7642@opindex mmcu
7643Specify ATMEL AVR instruction set or MCU type.
7644
7645Instruction set avr1 is for the minimal AVR core, not supported by the C
7646compiler, only for assembler programs (MCU types: at90s1200, attiny10,
7647attiny11, attiny12, attiny15, attiny28).
7648
7649Instruction set avr2 (default) is for the classic AVR core with up to
76508K program memory space (MCU types: at90s2313, at90s2323, attiny22,
7651at90s2333, at90s2343, at90s4414, at90s4433, at90s4434, at90s8515,
7652at90c8534, at90s8535).
7653
7654Instruction set avr3 is for the classic AVR core with up to 128K program
7655memory space (MCU types: atmega103, atmega603, at43usb320, at76c711).
7656
7657Instruction set avr4 is for the enhanced AVR core with up to 8K program
7658memory space (MCU types: atmega8, atmega83, atmega85).
7659
7660Instruction set avr5 is for the enhanced AVR core with up to 128K program
7661memory space (MCU types: atmega16, atmega161, atmega163, atmega32, atmega323,
7662atmega64, atmega128, at43usb355, at94k).
7663
7664@item -msize
7665@opindex msize
7666Output instruction sizes to the asm file.
7667
7668@item -minit-stack=@var{N}
7669@opindex minit-stack
7670Specify the initial stack address, which may be a symbol or numeric value,
7671@samp{__stack} is the default.
7672
7673@item -mno-interrupts
7674@opindex mno-interrupts
7675Generated code is not compatible with hardware interrupts.
7676Code size will be smaller.
7677
7678@item -mcall-prologues
7679@opindex mcall-prologues
7680Functions prologues/epilogues expanded as call to appropriate
7681subroutines. Code size will be smaller.
7682
7683@item -mno-tablejump
7684@opindex mno-tablejump
7685Do not generate tablejump insns which sometimes increase code size.
7686
7687@item -mtiny-stack
7688@opindex mtiny-stack
7689Change only the low 8 bits of the stack pointer.
7690
7691@item -mint8
7692@opindex mint8
7693Assume int to be 8 bit integer. This affects the sizes of all types: A
7694char will be 1 byte, an int will be 1 byte, an long will be 2 bytes
7695and long long will be 4 bytes. Please note that this option does not
7696comply to the C standards, but it will provide you with smaller code
7697size.
7698@end table
7699
7700@node Blackfin Options
7701@subsection Blackfin Options
7702@cindex Blackfin Options
7703
7704@table @gcctabopt
7705@item -momit-leaf-frame-pointer
7706@opindex momit-leaf-frame-pointer
7707Don't keep the frame pointer in a register for leaf functions. This
7708avoids the instructions to save, set up and restore frame pointers and
7709makes an extra register available in leaf functions. The option
7710@option{-fomit-frame-pointer} removes the frame pointer for all functions
7711which might make debugging harder.
7712
7713@item -mspecld-anomaly
7714@opindex mspecld-anomaly
7715When enabled, the compiler will ensure that the generated code does not
7716contain speculative loads after jump instructions. This option is enabled
7717by default.
7718
7719@item -mno-specld-anomaly
7720@opindex mno-specld-anomaly
7721Don't generate extra code to prevent speculative loads from occurring.
7722
7723@item -mcsync-anomaly
7724@opindex mcsync-anomaly
7725When enabled, the compiler will ensure that the generated code does not
7726contain CSYNC or SSYNC instructions too soon after conditional branches.
7727This option is enabled by default.
7728
7729@item -mno-csync-anomaly
7730@opindex mno-csync-anomaly
7731Don't generate extra code to prevent CSYNC or SSYNC instructions from
7732occurring too soon after a conditional branch.
7733
7734@item -mlow-64k
7735@opindex mlow-64k
7736When enabled, the compiler is free to take advantage of the knowledge that
7737the entire program fits into the low 64k of memory.
7738
7739@item -mno-low-64k
7740@opindex mno-low-64k
7741Assume that the program is arbitrarily large. This is the default.
7742
7743@item -mid-shared-library
7744@opindex mid-shared-library
7745Generate code that supports shared libraries via the library ID method.
7746This allows for execute in place and shared libraries in an environment
7747without virtual memory management. This option implies @option{-fPIC}.
7748
7749@item -mno-id-shared-library
7750@opindex mno-id-shared-library
7751Generate code that doesn't assume ID based shared libraries are being used.
7752This is the default.
7753
7754@item -mshared-library-id=n
7755@opindex mshared-library-id
7756Specified the identification number of the ID based shared library being
7757compiled. Specifying a value of 0 will generate more compact code, specifying
7758other values will force the allocation of that number to the current
7759library but is no more space or time efficient than omitting this option.
7760
7761@item -mlong-calls
7762@itemx -mno-long-calls
7763@opindex mlong-calls
7764@opindex mno-long-calls
7765Tells the compiler to perform function calls by first loading the
7766address of the function into a register and then performing a subroutine
7767call on this register. This switch is needed if the target function
7768will lie outside of the 24 bit addressing range of the offset based
7769version of subroutine call instruction.
7770
7771This feature is not enabled by default. Specifying
7772@option{-mno-long-calls} will restore the default behavior. Note these
7773switches have no effect on how the compiler generates code to handle
7774function calls via function pointers.
7775@end table
7776
7777@node CRIS Options
7778@subsection CRIS Options
7779@cindex CRIS Options
7780
7781These options are defined specifically for the CRIS ports.
7782
7783@table @gcctabopt
7784@item -march=@var{architecture-type}
7785@itemx -mcpu=@var{architecture-type}
7786@opindex march
7787@opindex mcpu
7788Generate code for the specified architecture. The choices for
7789@var{architecture-type} are @samp{v3}, @samp{v8} and @samp{v10} for
7790respectively ETRAX@w{ }4, ETRAX@w{ }100, and ETRAX@w{ }100@w{ }LX@.
7791Default is @samp{v0} except for cris-axis-linux-gnu, where the default is
7792@samp{v10}.
7793
7794@item -mtune=@var{architecture-type}
7795@opindex mtune
7796Tune to @var{architecture-type} everything applicable about the generated
7797code, except for the ABI and the set of available instructions. The
7798choices for @var{architecture-type} are the same as for
7799@option{-march=@var{architecture-type}}.
7800
7801@item -mmax-stack-frame=@var{n}
7802@opindex mmax-stack-frame
7803Warn when the stack frame of a function exceeds @var{n} bytes.
7804
7805@item -melinux-stacksize=@var{n}
7806@opindex melinux-stacksize
7807Only available with the @samp{cris-axis-aout} target. Arranges for
7808indications in the program to the kernel loader that the stack of the
7809program should be set to @var{n} bytes.
7810
7811@item -metrax4
7812@itemx -metrax100
7813@opindex metrax4
7814@opindex metrax100
7815The options @option{-metrax4} and @option{-metrax100} are synonyms for
7816@option{-march=v3} and @option{-march=v8} respectively.
7817
7818@item -mmul-bug-workaround
7819@itemx -mno-mul-bug-workaround
7820@opindex mmul-bug-workaround
7821@opindex mno-mul-bug-workaround
7822Work around a bug in the @code{muls} and @code{mulu} instructions for CPU
7823models where it applies. This option is active by default.
7824
7825@item -mpdebug
7826@opindex mpdebug
7827Enable CRIS-specific verbose debug-related information in the assembly
7828code. This option also has the effect to turn off the @samp{#NO_APP}
7829formatted-code indicator to the assembler at the beginning of the
7830assembly file.
7831
7832@item -mcc-init
7833@opindex mcc-init
7834Do not use condition-code results from previous instruction; always emit
7835compare and test instructions before use of condition codes.
7836
7837@item -mno-side-effects
7838@opindex mno-side-effects
7839Do not emit instructions with side-effects in addressing modes other than
7840post-increment.
7841
7842@item -mstack-align
7843@itemx -mno-stack-align
7844@itemx -mdata-align
7845@itemx -mno-data-align
7846@itemx -mconst-align
7847@itemx -mno-const-align
7848@opindex mstack-align
7849@opindex mno-stack-align
7850@opindex mdata-align
7851@opindex mno-data-align
7852@opindex mconst-align
7853@opindex mno-const-align
7854These options (no-options) arranges (eliminate arrangements) for the
7855stack-frame, individual data and constants to be aligned for the maximum
7856single data access size for the chosen CPU model. The default is to
7857arrange for 32-bit alignment. ABI details such as structure layout are
7858not affected by these options.
7859
7860@item -m32-bit
7861@itemx -m16-bit
7862@itemx -m8-bit
7863@opindex m32-bit
7864@opindex m16-bit
7865@opindex m8-bit
7866Similar to the stack- data- and const-align options above, these options
7867arrange for stack-frame, writable data and constants to all be 32-bit,
786816-bit or 8-bit aligned. The default is 32-bit alignment.
7869
7870@item -mno-prologue-epilogue
7871@itemx -mprologue-epilogue
7872@opindex mno-prologue-epilogue
7873@opindex mprologue-epilogue
7874With @option{-mno-prologue-epilogue}, the normal function prologue and
7875epilogue that sets up the stack-frame are omitted and no return
7876instructions or return sequences are generated in the code. Use this
7877option only together with visual inspection of the compiled code: no
7878warnings or errors are generated when call-saved registers must be saved,
7879or storage for local variable needs to be allocated.
7880
7881@item -mno-gotplt
7882@itemx -mgotplt
7883@opindex mno-gotplt
7884@opindex mgotplt
7885With @option{-fpic} and @option{-fPIC}, don't generate (do generate)
7886instruction sequences that load addresses for functions from the PLT part
7887of the GOT rather than (traditional on other architectures) calls to the
7888PLT@. The default is @option{-mgotplt}.
7889
7890@item -maout
7891@opindex maout
7892Legacy no-op option only recognized with the cris-axis-aout target.
7893
7894@item -melf
7895@opindex melf
7896Legacy no-op option only recognized with the cris-axis-elf and
7897cris-axis-linux-gnu targets.
7898
7899@item -melinux
7900@opindex melinux
7901Only recognized with the cris-axis-aout target, where it selects a
7902GNU/linux-like multilib, include files and instruction set for
7903@option{-march=v8}.
7904
7905@item -mlinux
7906@opindex mlinux
7907Legacy no-op option only recognized with the cris-axis-linux-gnu target.
7908
7909@item -sim
7910@opindex sim
7911This option, recognized for the cris-axis-aout and cris-axis-elf arranges
7912to link with input-output functions from a simulator library. Code,
7913initialized data and zero-initialized data are allocated consecutively.
7914
7915@item -sim2
7916@opindex sim2
7917Like @option{-sim}, but pass linker options to locate initialized data at
79180x40000000 and zero-initialized data at 0x80000000.
7919@end table
7920
7921@node CRX Options
7922@subsection CRX Options
7923@cindex CRX Options
7924
7925These options are defined specifically for the CRX ports.
7926
7927@table @gcctabopt
7928
7929@item -mmac
7930@opindex mmac
7931Enable the use of multiply-accumulate instructions. Disabled by default.
7932
7933@item -mpush-args
7934@opindex mpush-args
7935Push instructions will be used to pass outgoing arguments when functions
7936are called. Enabled by default.
7937@end table
7938
7939@node Darwin Options
7940@subsection Darwin Options
7941@cindex Darwin options
7942
7943These options are defined for all architectures running the Darwin operating
7944system.
7945
7946FSF GCC on Darwin does not create ``fat'' object files; it will create
7947an object file for the single architecture that it was built to
7948target. Apple's GCC on Darwin does create ``fat'' files if multiple
7949@option{-arch} options are used; it does so by running the compiler or
7950linker multiple times and joining the results together with
7951@file{lipo}.
7952
7953The subtype of the file created (like @samp{ppc7400} or @samp{ppc970} or
7954@samp{i686}) is determined by the flags that specify the ISA
7955that GCC is targetting, like @option{-mcpu} or @option{-march}. The
7956@option{-force_cpusubtype_ALL} option can be used to override this.
7957
7958The Darwin tools vary in their behavior when presented with an ISA
7959mismatch. The assembler, @file{as}, will only permit instructions to
7960be used that are valid for the subtype of the file it is generating,
7961so you cannot put 64-bit instructions in an @samp{ppc750} object file.
7962The linker for shared libraries, @file{/usr/bin/libtool}, will fail
7963and print an error if asked to create a shared library with a less
7964restrictive subtype than its input files (for instance, trying to put
7965a @samp{ppc970} object file in a @samp{ppc7400} library). The linker
7966for executables, @file{ld}, will quietly give the executable the most
7967restrictive subtype of any of its input files.
7968
7969@table @gcctabopt
7970@item -F@var{dir}
7971@opindex F
7972Add the framework directory @var{dir} to the head of the list of
7973directories to be searched for header files. These directories are
7974interleaved with those specified by @option{-I} options and are
7975scanned in a left-to-right order.
7976
7977A framework directory is a directory with frameworks in it. A
7978framework is a directory with a @samp{"Headers"} and/or
7979@samp{"PrivateHeaders"} directory contained directly in it that ends
7980in @samp{".framework"}. The name of a framework is the name of this
7981directory excluding the @samp{".framework"}. Headers associated with
7982the framework are found in one of those two directories, with
7983@samp{"Headers"} being searched first. A subframework is a framework
7984directory that is in a framework's @samp{"Frameworks"} directory.
7985Includes of subframework headers can only appear in a header of a
7986framework that contains the subframework, or in a sibling subframework
7987header. Two subframeworks are siblings if they occur in the same
7988framework. A subframework should not have the same name as a
7989framework, a warning will be issued if this is violated. Currently a
7990subframework cannot have subframeworks, in the future, the mechanism
7991may be extended to support this. The standard frameworks can be found
7992in @samp{"/System/Library/Frameworks"} and
7993@samp{"/Library/Frameworks"}. An example include looks like
7994@code{#include <Framework/header.h>}, where @samp{Framework} denotes
7995the name of the framework and header.h is found in the
7996@samp{"PrivateHeaders"} or @samp{"Headers"} directory.
7997
7998@item -gused
7999@opindex gused
8000Emit debugging information for symbols that are used. For STABS
8001debugging format, this enables @option{-feliminate-unused-debug-symbols}.
8002This is by default ON@.
8003
8004@item -gfull
8005@opindex gfull
8006Emit debugging information for all symbols and types.
8007
8008@item -mmacosx-version-min=@var{version}
8009The earliest version of MacOS X that this executable will run on
8010is @var{version}. Typical values of @var{version} include @code{10.1},
8011@code{10.2}, and @code{10.3.9}.
8012
8013The default for this option is to make choices that seem to be most
8014useful.
8015
8016@item -mkernel
8017@opindex mkernel
8018Enable kernel development mode. The @option{-mkernel} option sets
8019@option{-static}, @option{-fno-common}, @option{-fno-cxa-atexit},
8020@option{-fno-exceptions}, @option{-fno-non-call-exceptions},
8021@option{-fapple-kext}, @option{-fno-weak} and @option{-fno-rtti} where
8022applicable. This mode also sets @option{-mno-altivec},
8023@option{-msoft-float}, @option{-fno-builtin} and
8024@option{-mlong-branch} for PowerPC targets.
8025
8026@item -mone-byte-bool
8027@opindex mone-byte-bool
8028Override the defaults for @samp{bool} so that @samp{sizeof(bool)==1}.
8029By default @samp{sizeof(bool)} is @samp{4} when compiling for
8030Darwin/PowerPC and @samp{1} when compiling for Darwin/x86, so this
8031option has no effect on x86.
8032
8033@strong{Warning:} The @option{-mone-byte-bool} switch causes GCC
8034to generate code that is not binary compatible with code generated
8035without that switch. Using this switch may require recompiling all
8036other modules in a program, including system libraries. Use this
8037switch to conform to a non-default data model.
8038
8039@item -mfix-and-continue
8040@itemx -ffix-and-continue
8041@itemx -findirect-data
8042@opindex mfix-and-continue
8043@opindex ffix-and-continue
8044@opindex findirect-data
8045Generate code suitable for fast turn around development. Needed to
8046enable gdb to dynamically load @code{.o} files into already running
8047programs. @option{-findirect-data} and @option{-ffix-and-continue}
8048are provided for backwards compatibility.
8049
8050@item -all_load
8051@opindex all_load
8052Loads all members of static archive libraries.
8053See man ld(1) for more information.
8054
8055@item -arch_errors_fatal
8056@opindex arch_errors_fatal
8057Cause the errors having to do with files that have the wrong architecture
8058to be fatal.
8059
8060@item -bind_at_load
8061@opindex bind_at_load
8062Causes the output file to be marked such that the dynamic linker will
8063bind all undefined references when the file is loaded or launched.
8064
8065@item -bundle
8066@opindex bundle
8067Produce a Mach-o bundle format file.
8068See man ld(1) for more information.
8069
8070@item -bundle_loader @var{executable}
8071@opindex bundle_loader
8072This option specifies the @var{executable} that will be loading the build
8073output file being linked. See man ld(1) for more information.
8074
8075@item -dynamiclib
8076@opindex dynamiclib
8077When passed this option, GCC will produce a dynamic library instead of
8078an executable when linking, using the Darwin @file{libtool} command.
8079
8080@item -force_cpusubtype_ALL
8081@opindex force_cpusubtype_ALL
8082This causes GCC's output file to have the @var{ALL} subtype, instead of
8083one controlled by the @option{-mcpu} or @option{-march} option.
8084
8085@item -allowable_client @var{client_name}
8086@itemx -client_name
8087@itemx -compatibility_version
8088@itemx -current_version
8089@itemx -dead_strip
8090@itemx -dependency-file
8091@itemx -dylib_file
8092@itemx -dylinker_install_name
8093@itemx -dynamic
8094@itemx -exported_symbols_list
8095@itemx -filelist
8096@itemx -flat_namespace
8097@itemx -force_flat_namespace
8098@itemx -headerpad_max_install_names
8099@itemx -image_base
8100@itemx -init
8101@itemx -install_name
8102@itemx -keep_private_externs
8103@itemx -multi_module
8104@itemx -multiply_defined
8105@itemx -multiply_defined_unused
8106@itemx -noall_load
8107@itemx -no_dead_strip_inits_and_terms
8108@itemx -nofixprebinding
8109@itemx -nomultidefs
8110@itemx -noprebind
8111@itemx -noseglinkedit
8112@itemx -pagezero_size
8113@itemx -prebind
8114@itemx -prebind_all_twolevel_modules
8115@itemx -private_bundle
8116@itemx -read_only_relocs
8117@itemx -sectalign
8118@itemx -sectobjectsymbols
8119@itemx -whyload
8120@itemx -seg1addr
8121@itemx -sectcreate
8122@itemx -sectobjectsymbols
8123@itemx -sectorder
8124@itemx -segaddr
8125@itemx -segs_read_only_addr
8126@itemx -segs_read_write_addr
8127@itemx -seg_addr_table
8128@itemx -seg_addr_table_filename
8129@itemx -seglinkedit
8130@itemx -segprot
8131@itemx -segs_read_only_addr
8132@itemx -segs_read_write_addr
8133@itemx -single_module
8134@itemx -static
8135@itemx -sub_library
8136@itemx -sub_umbrella
8137@itemx -twolevel_namespace
8138@itemx -umbrella
8139@itemx -undefined
8140@itemx -unexported_symbols_list
8141@itemx -weak_reference_mismatches
8142@itemx -whatsloaded
8143
8144@opindex allowable_client
8145@opindex client_name
8146@opindex compatibility_version
8147@opindex current_version
8148@opindex dead_strip
8149@opindex dependency-file
8150@opindex dylib_file
8151@opindex dylinker_install_name
8152@opindex dynamic
8153@opindex exported_symbols_list
8154@opindex filelist
8155@opindex flat_namespace
8156@opindex force_flat_namespace
8157@opindex headerpad_max_install_names
8158@opindex image_base
8159@opindex init
8160@opindex install_name
8161@opindex keep_private_externs
8162@opindex multi_module
8163@opindex multiply_defined
8164@opindex multiply_defined_unused
8165@opindex noall_load
8166@opindex no_dead_strip_inits_and_terms
8167@opindex nofixprebinding
8168@opindex nomultidefs
8169@opindex noprebind
8170@opindex noseglinkedit
8171@opindex pagezero_size
8172@opindex prebind
8173@opindex prebind_all_twolevel_modules
8174@opindex private_bundle
8175@opindex read_only_relocs
8176@opindex sectalign
8177@opindex sectobjectsymbols
8178@opindex whyload
8179@opindex seg1addr
8180@opindex sectcreate
8181@opindex sectobjectsymbols
8182@opindex sectorder
8183@opindex segaddr
8184@opindex segs_read_only_addr
8185@opindex segs_read_write_addr
8186@opindex seg_addr_table
8187@opindex seg_addr_table_filename
8188@opindex seglinkedit
8189@opindex segprot
8190@opindex segs_read_only_addr
8191@opindex segs_read_write_addr
8192@opindex single_module
8193@opindex static
8194@opindex sub_library
8195@opindex sub_umbrella
8196@opindex twolevel_namespace
8197@opindex umbrella
8198@opindex undefined
8199@opindex unexported_symbols_list
8200@opindex weak_reference_mismatches
8201@opindex whatsloaded
8202
8203These options are passed to the Darwin linker. The Darwin linker man page
8204describes them in detail.
8205@end table
8206
8207@node DEC Alpha Options
8208@subsection DEC Alpha Options
8209
8210These @samp{-m} options are defined for the DEC Alpha implementations:
8211
8212@table @gcctabopt
8213@item -mno-soft-float
8214@itemx -msoft-float
8215@opindex mno-soft-float
8216@opindex msoft-float
8217Use (do not use) the hardware floating-point instructions for
8218floating-point operations. When @option{-msoft-float} is specified,
8219functions in @file{libgcc.a} will be used to perform floating-point
8220operations. Unless they are replaced by routines that emulate the
8221floating-point operations, or compiled in such a way as to call such
8222emulations routines, these routines will issue floating-point
8223operations. If you are compiling for an Alpha without floating-point
8224operations, you must ensure that the library is built so as not to call
8225them.
8226
8227Note that Alpha implementations without floating-point operations are
8228required to have floating-point registers.
8229
8230@item -mfp-reg
8231@itemx -mno-fp-regs
8232@opindex mfp-reg
8233@opindex mno-fp-regs
8234Generate code that uses (does not use) the floating-point register set.
8235@option{-mno-fp-regs} implies @option{-msoft-float}. If the floating-point
8236register set is not used, floating point operands are passed in integer
8237registers as if they were integers and floating-point results are passed
8238in @code{$0} instead of @code{$f0}. This is a non-standard calling sequence,
8239so any function with a floating-point argument or return value called by code
8240compiled with @option{-mno-fp-regs} must also be compiled with that
8241option.
8242
8243A typical use of this option is building a kernel that does not use,
8244and hence need not save and restore, any floating-point registers.
8245
8246@item -mieee
8247@opindex mieee
8248The Alpha architecture implements floating-point hardware optimized for
8249maximum performance. It is mostly compliant with the IEEE floating
8250point standard. However, for full compliance, software assistance is
8251required. This option generates code fully IEEE compliant code
8252@emph{except} that the @var{inexact-flag} is not maintained (see below).
8253If this option is turned on, the preprocessor macro @code{_IEEE_FP} is
8254defined during compilation. The resulting code is less efficient but is
8255able to correctly support denormalized numbers and exceptional IEEE
8256values such as not-a-number and plus/minus infinity. Other Alpha
8257compilers call this option @option{-ieee_with_no_inexact}.
8258
8259@item -mieee-with-inexact
8260@opindex mieee-with-inexact
8261This is like @option{-mieee} except the generated code also maintains
8262the IEEE @var{inexact-flag}. Turning on this option causes the
8263generated code to implement fully-compliant IEEE math. In addition to
8264@code{_IEEE_FP}, @code{_IEEE_FP_EXACT} is defined as a preprocessor
8265macro. On some Alpha implementations the resulting code may execute
8266significantly slower than the code generated by default. Since there is
8267very little code that depends on the @var{inexact-flag}, you should
8268normally not specify this option. Other Alpha compilers call this
8269option @option{-ieee_with_inexact}.
8270
8271@item -mfp-trap-mode=@var{trap-mode}
8272@opindex mfp-trap-mode
8273This option controls what floating-point related traps are enabled.
8274Other Alpha compilers call this option @option{-fptm @var{trap-mode}}.
8275The trap mode can be set to one of four values:
8276
8277@table @samp
8278@item n
8279This is the default (normal) setting. The only traps that are enabled
8280are the ones that cannot be disabled in software (e.g., division by zero
8281trap).
8282
8283@item u
8284In addition to the traps enabled by @samp{n}, underflow traps are enabled
8285as well.
8286
8287@item su
8288Like @samp{u}, but the instructions are marked to be safe for software
8289completion (see Alpha architecture manual for details).
8290
8291@item sui
8292Like @samp{su}, but inexact traps are enabled as well.
8293@end table
8294
8295@item -mfp-rounding-mode=@var{rounding-mode}
8296@opindex mfp-rounding-mode
8297Selects the IEEE rounding mode. Other Alpha compilers call this option
8298@option{-fprm @var{rounding-mode}}. The @var{rounding-mode} can be one
8299of:
8300
8301@table @samp
8302@item n
8303Normal IEEE rounding mode. Floating point numbers are rounded towards
8304the nearest machine number or towards the even machine number in case
8305of a tie.
8306
8307@item m
8308Round towards minus infinity.
8309
8310@item c
8311Chopped rounding mode. Floating point numbers are rounded towards zero.
8312
8313@item d
8314Dynamic rounding mode. A field in the floating point control register
8315(@var{fpcr}, see Alpha architecture reference manual) controls the
8316rounding mode in effect. The C library initializes this register for
8317rounding towards plus infinity. Thus, unless your program modifies the
8318@var{fpcr}, @samp{d} corresponds to round towards plus infinity.
8319@end table
8320
8321@item -mtrap-precision=@var{trap-precision}
8322@opindex mtrap-precision
8323In the Alpha architecture, floating point traps are imprecise. This
8324means without software assistance it is impossible to recover from a
8325floating trap and program execution normally needs to be terminated.
8326GCC can generate code that can assist operating system trap handlers
8327in determining the exact location that caused a floating point trap.
8328Depending on the requirements of an application, different levels of
8329precisions can be selected:
8330
8331@table @samp
8332@item p
8333Program precision. This option is the default and means a trap handler
8334can only identify which program caused a floating point exception.
8335
8336@item f
8337Function precision. The trap handler can determine the function that
8338caused a floating point exception.
8339
8340@item i
8341Instruction precision. The trap handler can determine the exact
8342instruction that caused a floating point exception.
8343@end table
8344
8345Other Alpha compilers provide the equivalent options called
8346@option{-scope_safe} and @option{-resumption_safe}.
8347
8348@item -mieee-conformant
8349@opindex mieee-conformant
8350This option marks the generated code as IEEE conformant. You must not
8351use this option unless you also specify @option{-mtrap-precision=i} and either
8352@option{-mfp-trap-mode=su} or @option{-mfp-trap-mode=sui}. Its only effect
8353is to emit the line @samp{.eflag 48} in the function prologue of the
8354generated assembly file. Under DEC Unix, this has the effect that
8355IEEE-conformant math library routines will be linked in.
8356
8357@item -mbuild-constants
8358@opindex mbuild-constants
8359Normally GCC examines a 32- or 64-bit integer constant to
8360see if it can construct it from smaller constants in two or three
8361instructions. If it cannot, it will output the constant as a literal and
8362generate code to load it from the data segment at runtime.
8363
8364Use this option to require GCC to construct @emph{all} integer constants
8365using code, even if it takes more instructions (the maximum is six).
8366
8367You would typically use this option to build a shared library dynamic
8368loader. Itself a shared library, it must relocate itself in memory
8369before it can find the variables and constants in its own data segment.
8370
8371@item -malpha-as
8372@itemx -mgas
8373@opindex malpha-as
8374@opindex mgas
8375Select whether to generate code to be assembled by the vendor-supplied
8376assembler (@option{-malpha-as}) or by the GNU assembler @option{-mgas}.
8377
8378@item -mbwx
8379@itemx -mno-bwx
8380@itemx -mcix
8381@itemx -mno-cix
8382@itemx -mfix
8383@itemx -mno-fix
8384@itemx -mmax
8385@itemx -mno-max
8386@opindex mbwx
8387@opindex mno-bwx
8388@opindex mcix
8389@opindex mno-cix
8390@opindex mfix
8391@opindex mno-fix
8392@opindex mmax
8393@opindex mno-max
8394Indicate whether GCC should generate code to use the optional BWX,
8395CIX, FIX and MAX instruction sets. The default is to use the instruction
8396sets supported by the CPU type specified via @option{-mcpu=} option or that
8397of the CPU on which GCC was built if none was specified.
8398
8399@item -mfloat-vax
8400@itemx -mfloat-ieee
8401@opindex mfloat-vax
8402@opindex mfloat-ieee
8403Generate code that uses (does not use) VAX F and G floating point
8404arithmetic instead of IEEE single and double precision.
8405
8406@item -mexplicit-relocs
8407@itemx -mno-explicit-relocs
8408@opindex mexplicit-relocs
8409@opindex mno-explicit-relocs
8410Older Alpha assemblers provided no way to generate symbol relocations
8411except via assembler macros. Use of these macros does not allow
8412optimal instruction scheduling. GNU binutils as of version 2.12
8413supports a new syntax that allows the compiler to explicitly mark
8414which relocations should apply to which instructions. This option
8415is mostly useful for debugging, as GCC detects the capabilities of
8416the assembler when it is built and sets the default accordingly.
8417
8418@item -msmall-data
8419@itemx -mlarge-data
8420@opindex msmall-data
8421@opindex mlarge-data
8422When @option{-mexplicit-relocs} is in effect, static data is
8423accessed via @dfn{gp-relative} relocations. When @option{-msmall-data}
8424is used, objects 8 bytes long or smaller are placed in a @dfn{small data area}
8425(the @code{.sdata} and @code{.sbss} sections) and are accessed via
842616-bit relocations off of the @code{$gp} register. This limits the
8427size of the small data area to 64KB, but allows the variables to be
8428directly accessed via a single instruction.
8429
8430The default is @option{-mlarge-data}. With this option the data area
8431is limited to just below 2GB@. Programs that require more than 2GB of
8432data must use @code{malloc} or @code{mmap} to allocate the data in the
8433heap instead of in the program's data segment.
8434
8435When generating code for shared libraries, @option{-fpic} implies
8436@option{-msmall-data} and @option{-fPIC} implies @option{-mlarge-data}.
8437
8438@item -msmall-text
8439@itemx -mlarge-text
8440@opindex msmall-text
8441@opindex mlarge-text
8442When @option{-msmall-text} is used, the compiler assumes that the
8443code of the entire program (or shared library) fits in 4MB, and is
8444thus reachable with a branch instruction. When @option{-msmall-data}
8445is used, the compiler can assume that all local symbols share the
8446same @code{$gp} value, and thus reduce the number of instructions
8447required for a function call from 4 to 1.
8448
8449The default is @option{-mlarge-text}.
8450
8451@item -mcpu=@var{cpu_type}
8452@opindex mcpu
8453Set the instruction set and instruction scheduling parameters for
8454machine type @var{cpu_type}. You can specify either the @samp{EV}
8455style name or the corresponding chip number. GCC supports scheduling
8456parameters for the EV4, EV5 and EV6 family of processors and will
8457choose the default values for the instruction set from the processor
8458you specify. If you do not specify a processor type, GCC will default
8459to the processor on which the compiler was built.
8460
8461Supported values for @var{cpu_type} are
8462
8463@table @samp
8464@item ev4
8465@itemx ev45
8466@itemx 21064
8467Schedules as an EV4 and has no instruction set extensions.
8468
8469@item ev5
8470@itemx 21164
8471Schedules as an EV5 and has no instruction set extensions.
8472
8473@item ev56
8474@itemx 21164a
8475Schedules as an EV5 and supports the BWX extension.
8476
8477@item pca56
8478@itemx 21164pc
8479@itemx 21164PC
8480Schedules as an EV5 and supports the BWX and MAX extensions.
8481
8482@item ev6
8483@itemx 21264
8484Schedules as an EV6 and supports the BWX, FIX, and MAX extensions.
8485
8486@item ev67
8487@itemx 21264a
8488Schedules as an EV6 and supports the BWX, CIX, FIX, and MAX extensions.
8489@end table
8490
8491@item -mtune=@var{cpu_type}
8492@opindex mtune
8493Set only the instruction scheduling parameters for machine type
8494@var{cpu_type}. The instruction set is not changed.
8495
8496@item -mmemory-latency=@var{time}
8497@opindex mmemory-latency
8498Sets the latency the scheduler should assume for typical memory
8499references as seen by the application. This number is highly
8500dependent on the memory access patterns used by the application
8501and the size of the external cache on the machine.
8502
8503Valid options for @var{time} are
8504
8505@table @samp
8506@item @var{number}
8507A decimal number representing clock cycles.
8508
8509@item L1
8510@itemx L2
8511@itemx L3
8512@itemx main
8513The compiler contains estimates of the number of clock cycles for
8514``typical'' EV4 & EV5 hardware for the Level 1, 2 & 3 caches
8515(also called Dcache, Scache, and Bcache), as well as to main memory.
8516Note that L3 is only valid for EV5.
8517
8518@end table
8519@end table
8520
8521@node DEC Alpha/VMS Options
8522@subsection DEC Alpha/VMS Options
8523
8524These @samp{-m} options are defined for the DEC Alpha/VMS implementations:
8525
8526@table @gcctabopt
8527@item -mvms-return-codes
8528@opindex mvms-return-codes
8529Return VMS condition codes from main. The default is to return POSIX
8530style condition (e.g.@ error) codes.
8531@end table
8532
8533@node FRV Options
8534@subsection FRV Options
8535@cindex FRV Options
8536
8537@table @gcctabopt
8538@item -mgpr-32
8539@opindex mgpr-32
8540
8541Only use the first 32 general purpose registers.
8542
8543@item -mgpr-64
8544@opindex mgpr-64
8545
8546Use all 64 general purpose registers.
8547
8548@item -mfpr-32
8549@opindex mfpr-32
8550
8551Use only the first 32 floating point registers.
8552
8553@item -mfpr-64
8554@opindex mfpr-64
8555
8556Use all 64 floating point registers
8557
8558@item -mhard-float
8559@opindex mhard-float
8560
8561Use hardware instructions for floating point operations.
8562
8563@item -msoft-float
8564@opindex msoft-float
8565
8566Use library routines for floating point operations.
8567
8568@item -malloc-cc
8569@opindex malloc-cc
8570
8571Dynamically allocate condition code registers.
8572
8573@item -mfixed-cc
8574@opindex mfixed-cc
8575
8576Do not try to dynamically allocate condition code registers, only
8577use @code{icc0} and @code{fcc0}.
8578
8579@item -mdword
8580@opindex mdword
8581
8582Change ABI to use double word insns.
8583
8584@item -mno-dword
8585@opindex mno-dword
8586
8587Do not use double word instructions.
8588
8589@item -mdouble
8590@opindex mdouble
8591
8592Use floating point double instructions.
8593
8594@item -mno-double
8595@opindex mno-double
8596
8597Do not use floating point double instructions.
8598
8599@item -mmedia
8600@opindex mmedia
8601
8602Use media instructions.
8603
8604@item -mno-media
8605@opindex mno-media
8606
8607Do not use media instructions.
8608
8609@item -mmuladd
8610@opindex mmuladd
8611
8612Use multiply and add/subtract instructions.
8613
8614@item -mno-muladd
8615@opindex mno-muladd
8616
8617Do not use multiply and add/subtract instructions.
8618
8619@item -mfdpic
8620@opindex mfdpic
8621
8622Select the FDPIC ABI, that uses function descriptors to represent
8623pointers to functions. Without any PIC/PIE-related options, it
8624implies @option{-fPIE}. With @option{-fpic} or @option{-fpie}, it
8625assumes GOT entries and small data are within a 12-bit range from the
8626GOT base address; with @option{-fPIC} or @option{-fPIE}, GOT offsets
8627are computed with 32 bits.
8628
8629@item -minline-plt
8630@opindex minline-plt
8631
8632Enable inlining of PLT entries in function calls to functions that are
8633not known to bind locally. It has no effect without @option{-mfdpic}.
8634It's enabled by default if optimizing for speed and compiling for
8635shared libraries (i.e., @option{-fPIC} or @option{-fpic}), or when an
8636optimization option such as @option{-O3} or above is present in the
8637command line.
8638
8639@item -mTLS
8640@opindex TLS
8641
8642Assume a large TLS segment when generating thread-local code.
8643
8644@item -mtls
8645@opindex tls
8646
8647Do not assume a large TLS segment when generating thread-local code.
8648
8649@item -mgprel-ro
8650@opindex mgprel-ro
8651
8652Enable the use of @code{GPREL} relocations in the FDPIC ABI for data
8653that is known to be in read-only sections. It's enabled by default,
8654except for @option{-fpic} or @option{-fpie}: even though it may help
8655make the global offset table smaller, it trades 1 instruction for 4.
8656With @option{-fPIC} or @option{-fPIE}, it trades 3 instructions for 4,
8657one of which may be shared by multiple symbols, and it avoids the need
8658for a GOT entry for the referenced symbol, so it's more likely to be a
8659win. If it is not, @option{-mno-gprel-ro} can be used to disable it.
8660
8661@item -multilib-library-pic
8662@opindex multilib-library-pic
8663
8664Link with the (library, not FD) pic libraries. It's implied by
8665@option{-mlibrary-pic}, as well as by @option{-fPIC} and
8666@option{-fpic} without @option{-mfdpic}. You should never have to use
8667it explicitly.
8668
8669@item -mlinked-fp
8670@opindex mlinked-fp
8671
8672Follow the EABI requirement of always creating a frame pointer whenever
8673a stack frame is allocated. This option is enabled by default and can
8674be disabled with @option{-mno-linked-fp}.
8675
8676@item -mlong-calls
8677@opindex mlong-calls
8678
8679Use indirect addressing to call functions outside the current
8680compilation unit. This allows the functions to be placed anywhere
8681within the 32-bit address space.
8682
8683@item -malign-labels
8684@opindex malign-labels
8685
8686Try to align labels to an 8-byte boundary by inserting nops into the
8687previous packet. This option only has an effect when VLIW packing
8688is enabled. It doesn't create new packets; it merely adds nops to
8689existing ones.
8690
8691@item -mlibrary-pic
8692@opindex mlibrary-pic
8693
8694Generate position-independent EABI code.
8695
8696@item -macc-4
8697@opindex macc-4
8698
8699Use only the first four media accumulator registers.
8700
8701@item -macc-8
8702@opindex macc-8
8703
8704Use all eight media accumulator registers.
8705
8706@item -mpack
8707@opindex mpack
8708
8709Pack VLIW instructions.
8710
8711@item -mno-pack
8712@opindex mno-pack
8713
8714Do not pack VLIW instructions.
8715
8716@item -mno-eflags
8717@opindex mno-eflags
8718
8719Do not mark ABI switches in e_flags.
8720
8721@item -mcond-move
8722@opindex mcond-move
8723
8724Enable the use of conditional-move instructions (default).
8725
8726This switch is mainly for debugging the compiler and will likely be removed
8727in a future version.
8728
8729@item -mno-cond-move
8730@opindex mno-cond-move
8731
8732Disable the use of conditional-move instructions.
8733
8734This switch is mainly for debugging the compiler and will likely be removed
8735in a future version.
8736
8737@item -mscc
8738@opindex mscc
8739
8740Enable the use of conditional set instructions (default).
8741
8742This switch is mainly for debugging the compiler and will likely be removed
8743in a future version.
8744
8745@item -mno-scc
8746@opindex mno-scc
8747
8748Disable the use of conditional set instructions.
8749
8750This switch is mainly for debugging the compiler and will likely be removed
8751in a future version.
8752
8753@item -mcond-exec
8754@opindex mcond-exec
8755
8756Enable the use of conditional execution (default).
8757
8758This switch is mainly for debugging the compiler and will likely be removed
8759in a future version.
8760
8761@item -mno-cond-exec
8762@opindex mno-cond-exec
8763
8764Disable the use of conditional execution.
8765
8766This switch is mainly for debugging the compiler and will likely be removed
8767in a future version.
8768
8769@item -mvliw-branch
8770@opindex mvliw-branch
8771
8772Run a pass to pack branches into VLIW instructions (default).
8773
8774This switch is mainly for debugging the compiler and will likely be removed
8775in a future version.
8776
8777@item -mno-vliw-branch
8778@opindex mno-vliw-branch
8779
8780Do not run a pass to pack branches into VLIW instructions.
8781
8782This switch is mainly for debugging the compiler and will likely be removed
8783in a future version.
8784
8785@item -mmulti-cond-exec
8786@opindex mmulti-cond-exec
8787
8788Enable optimization of @code{&&} and @code{||} in conditional execution
8789(default).
8790
8791This switch is mainly for debugging the compiler and will likely be removed
8792in a future version.
8793
8794@item -mno-multi-cond-exec
8795@opindex mno-multi-cond-exec
8796
8797Disable optimization of @code{&&} and @code{||} in conditional execution.
8798
8799This switch is mainly for debugging the compiler and will likely be removed
8800in a future version.
8801
8802@item -mnested-cond-exec
8803@opindex mnested-cond-exec
8804
8805Enable nested conditional execution optimizations (default).
8806
8807This switch is mainly for debugging the compiler and will likely be removed
8808in a future version.
8809
8810@item -mno-nested-cond-exec
8811@opindex mno-nested-cond-exec
8812
8813Disable nested conditional execution optimizations.
8814
8815This switch is mainly for debugging the compiler and will likely be removed
8816in a future version.
8817
8818@item -moptimize-membar
8819@opindex moptimize-membar
8820
8821This switch removes redundant @code{membar} instructions from the
8822compiler generated code. It is enabled by default.
8823
8824@item -mno-optimize-membar
8825@opindex mno-optimize-membar
8826
8827This switch disables the automatic removal of redundant @code{membar}
8828instructions from the generated code.
8829
8830@item -mtomcat-stats
8831@opindex mtomcat-stats
8832
8833Cause gas to print out tomcat statistics.
8834
8835@item -mcpu=@var{cpu}
8836@opindex mcpu
8837
8838Select the processor type for which to generate code. Possible values are
8839@samp{frv}, @samp{fr550}, @samp{tomcat}, @samp{fr500}, @samp{fr450},
8840@samp{fr405}, @samp{fr400}, @samp{fr300} and @samp{simple}.
8841
8842@end table
8843
8844@node GNU/Linux Options
8845@subsection GNU/Linux Options
8846
8847These @samp{-m} options are defined for GNU/Linux targets:
8848
8849@table @gcctabopt
8850@item -mglibc
8851@opindex mglibc
8852Use the GNU C library instead of uClibc. This is the default except
8853on @samp{*-*-linux-*uclibc*} targets.
8854
8855@item -muclibc
8856@opindex muclibc
8857Use uClibc instead of the GNU C library. This is the default on
8858@samp{*-*-linux-*uclibc*} targets.
8859@end table
8860
8861@node H8/300 Options
8862@subsection H8/300 Options
8863
8864These @samp{-m} options are defined for the H8/300 implementations:
8865
8866@table @gcctabopt
8867@item -mrelax
8868@opindex mrelax
8869Shorten some address references at link time, when possible; uses the
8870linker option @option{-relax}. @xref{H8/300,, @code{ld} and the H8/300,
8871ld, Using ld}, for a fuller description.
8872
8873@item -mh
8874@opindex mh
8875Generate code for the H8/300H@.
8876
8877@item -ms
8878@opindex ms
8879Generate code for the H8S@.
8880
8881@item -mn
8882@opindex mn
8883Generate code for the H8S and H8/300H in the normal mode. This switch
8884must be used either with @option{-mh} or @option{-ms}.
8885
8886@item -ms2600
8887@opindex ms2600
8888Generate code for the H8S/2600. This switch must be used with @option{-ms}.
8889
8890@item -mint32
8891@opindex mint32
8892Make @code{int} data 32 bits by default.
8893
8894@item -malign-300
8895@opindex malign-300
8896On the H8/300H and H8S, use the same alignment rules as for the H8/300.
8897The default for the H8/300H and H8S is to align longs and floats on 4
8898byte boundaries.
8899@option{-malign-300} causes them to be aligned on 2 byte boundaries.
8900This option has no effect on the H8/300.
8901@end table
8902
8903@node HPPA Options
8904@subsection HPPA Options
8905@cindex HPPA Options
8906
8907These @samp{-m} options are defined for the HPPA family of computers:
8908
8909@table @gcctabopt
8910@item -march=@var{architecture-type}
8911@opindex march
8912Generate code for the specified architecture. The choices for
8913@var{architecture-type} are @samp{1.0} for PA 1.0, @samp{1.1} for PA
89141.1, and @samp{2.0} for PA 2.0 processors. Refer to
8915@file{/usr/lib/sched.models} on an HP-UX system to determine the proper
8916architecture option for your machine. Code compiled for lower numbered
8917architectures will run on higher numbered architectures, but not the
8918other way around.
8919
8920@item -mpa-risc-1-0
8921@itemx -mpa-risc-1-1
8922@itemx -mpa-risc-2-0
8923@opindex mpa-risc-1-0
8924@opindex mpa-risc-1-1
8925@opindex mpa-risc-2-0
8926Synonyms for @option{-march=1.0}, @option{-march=1.1}, and @option{-march=2.0} respectively.
8927
8928@item -mbig-switch
8929@opindex mbig-switch
8930Generate code suitable for big switch tables. Use this option only if
8931the assembler/linker complain about out of range branches within a switch
8932table.
8933
8934@item -mjump-in-delay
8935@opindex mjump-in-delay
8936Fill delay slots of function calls with unconditional jump instructions
8937by modifying the return pointer for the function call to be the target
8938of the conditional jump.
8939
8940@item -mdisable-fpregs
8941@opindex mdisable-fpregs
8942Prevent floating point registers from being used in any manner. This is
8943necessary for compiling kernels which perform lazy context switching of
8944floating point registers. If you use this option and attempt to perform
8945floating point operations, the compiler will abort.
8946
8947@item -mdisable-indexing
8948@opindex mdisable-indexing
8949Prevent the compiler from using indexing address modes. This avoids some
8950rather obscure problems when compiling MIG generated code under MACH@.
8951
8952@item -mno-space-regs
8953@opindex mno-space-regs
8954Generate code that assumes the target has no space registers. This allows
8955GCC to generate faster indirect calls and use unscaled index address modes.
8956
8957Such code is suitable for level 0 PA systems and kernels.
8958
8959@item -mfast-indirect-calls
8960@opindex mfast-indirect-calls
8961Generate code that assumes calls never cross space boundaries. This
8962allows GCC to emit code which performs faster indirect calls.
8963
8964This option will not work in the presence of shared libraries or nested
8965functions.
8966
8967@item -mfixed-range=@var{register-range}
8968@opindex mfixed-range
8969Generate code treating the given register range as fixed registers.
8970A fixed register is one that the register allocator can not use. This is
8971useful when compiling kernel code. A register range is specified as
8972two registers separated by a dash. Multiple register ranges can be
8973specified separated by a comma.
8974
8975@item -mlong-load-store
8976@opindex mlong-load-store
8977Generate 3-instruction load and store sequences as sometimes required by
8978the HP-UX 10 linker. This is equivalent to the @samp{+k} option to
8979the HP compilers.
8980
8981@item -mportable-runtime
8982@opindex mportable-runtime
8983Use the portable calling conventions proposed by HP for ELF systems.
8984
8985@item -mgas
8986@opindex mgas
8987Enable the use of assembler directives only GAS understands.
8988
8989@item -mschedule=@var{cpu-type}
8990@opindex mschedule
8991Schedule code according to the constraints for the machine type
8992@var{cpu-type}. The choices for @var{cpu-type} are @samp{700}
8993@samp{7100}, @samp{7100LC}, @samp{7200}, @samp{7300} and @samp{8000}. Refer
8994to @file{/usr/lib/sched.models} on an HP-UX system to determine the
8995proper scheduling option for your machine. The default scheduling is
8996@samp{8000}.
8997
8998@item -mlinker-opt
8999@opindex mlinker-opt
9000Enable the optimization pass in the HP-UX linker. Note this makes symbolic
9001debugging impossible. It also triggers a bug in the HP-UX 8 and HP-UX 9
9002linkers in which they give bogus error messages when linking some programs.
9003
9004@item -msoft-float
9005@opindex msoft-float
9006Generate output containing library calls for floating point.
9007@strong{Warning:} the requisite libraries are not available for all HPPA
9008targets. Normally the facilities of the machine's usual C compiler are
9009used, but this cannot be done directly in cross-compilation. You must make
9010your own arrangements to provide suitable library functions for
9011cross-compilation. The embedded target @samp{hppa1.1-*-pro}
9012does provide software floating point support.
9013
9014@option{-msoft-float} changes the calling convention in the output file;
9015therefore, it is only useful if you compile @emph{all} of a program with
9016this option. In particular, you need to compile @file{libgcc.a}, the
9017library that comes with GCC, with @option{-msoft-float} in order for
9018this to work.
9019
9020@item -msio
9021@opindex msio
9022Generate the predefine, @code{_SIO}, for server IO@. The default is
9023@option{-mwsio}. This generates the predefines, @code{__hp9000s700},
9024@code{__hp9000s700__} and @code{_WSIO}, for workstation IO@. These
9025options are available under HP-UX and HI-UX@.
9026
9027@item -mgnu-ld
9028@opindex gnu-ld
9029Use GNU ld specific options. This passes @option{-shared} to ld when
9030building a shared library. It is the default when GCC is configured,
9031explicitly or implicitly, with the GNU linker. This option does not
9032have any affect on which ld is called, it only changes what parameters
9033are passed to that ld. The ld that is called is determined by the
9034@option{--with-ld} configure option, GCC's program search path, and
9035finally by the user's @env{PATH}. The linker used by GCC can be printed
9036using @samp{which `gcc -print-prog-name=ld`}. This option is only available
9037on the 64 bit HP-UX GCC, i.e. configured with @samp{hppa*64*-*-hpux*}.
9038
9039@item -mhp-ld
9040@opindex hp-ld
9041Use HP ld specific options. This passes @option{-b} to ld when building
9042a shared library and passes @option{+Accept TypeMismatch} to ld on all
9043links. It is the default when GCC is configured, explicitly or
9044implicitly, with the HP linker. This option does not have any affect on
9045which ld is called, it only changes what parameters are passed to that
9046ld. The ld that is called is determined by the @option{--with-ld}
9047configure option, GCC's program search path, and finally by the user's
9048@env{PATH}. The linker used by GCC can be printed using @samp{which
9049`gcc -print-prog-name=ld`}. This option is only available on the 64 bit
9050HP-UX GCC, i.e. configured with @samp{hppa*64*-*-hpux*}.
9051
9052@item -mlong-calls
9053@opindex mno-long-calls
9054Generate code that uses long call sequences. This ensures that a call
9055is always able to reach linker generated stubs. The default is to generate
9056long calls only when the distance from the call site to the beginning
9057of the function or translation unit, as the case may be, exceeds a
9058predefined limit set by the branch type being used. The limits for
9059normal calls are 7,600,000 and 240,000 bytes, respectively for the
9060PA 2.0 and PA 1.X architectures. Sibcalls are always limited at
9061240,000 bytes.
9062
9063Distances are measured from the beginning of functions when using the
9064@option{-ffunction-sections} option, or when using the @option{-mgas}
9065and @option{-mno-portable-runtime} options together under HP-UX with
9066the SOM linker.
9067
9068It is normally not desirable to use this option as it will degrade
9069performance. However, it may be useful in large applications,
9070particularly when partial linking is used to build the application.
9071
9072The types of long calls used depends on the capabilities of the
9073assembler and linker, and the type of code being generated. The
9074impact on systems that support long absolute calls, and long pic
9075symbol-difference or pc-relative calls should be relatively small.
9076However, an indirect call is used on 32-bit ELF systems in pic code
9077and it is quite long.
9078
9079@item -munix=@var{unix-std}
9080@opindex march
9081Generate compiler predefines and select a startfile for the specified
9082UNIX standard. The choices for @var{unix-std} are @samp{93}, @samp{95}
9083and @samp{98}. @samp{93} is supported on all HP-UX versions. @samp{95}
9084is available on HP-UX 10.10 and later. @samp{98} is available on HP-UX
908511.11 and later. The default values are @samp{93} for HP-UX 10.00,
9086@samp{95} for HP-UX 10.10 though to 11.00, and @samp{98} for HP-UX 11.11
9087and later.
9088
9089@option{-munix=93} provides the same predefines as GCC 3.3 and 3.4.
9090@option{-munix=95} provides additional predefines for @code{XOPEN_UNIX}
9091and @code{_XOPEN_SOURCE_EXTENDED}, and the startfile @file{unix95.o}.
9092@option{-munix=98} provides additional predefines for @code{_XOPEN_UNIX},
9093@code{_XOPEN_SOURCE_EXTENDED}, @code{_INCLUDE__STDC_A1_SOURCE} and
9094@code{_INCLUDE_XOPEN_SOURCE_500}, and the startfile @file{unix98.o}.
9095
9096It is @emph{important} to note that this option changes the interfaces
9097for various library routines. It also affects the operational behavior
9098of the C library. Thus, @emph{extreme} care is needed in using this
9099option.
9100
9101Library code that is intended to operate with more than one UNIX
9102standard must test, set and restore the variable @var{__xpg4_extended_mask}
9103as appropriate. Most GNU software doesn't provide this capability.
9104
9105@item -nolibdld
9106@opindex nolibdld
9107Suppress the generation of link options to search libdld.sl when the
9108@option{-static} option is specified on HP-UX 10 and later.
9109
9110@item -static
9111@opindex static
9112The HP-UX implementation of setlocale in libc has a dependency on
9113libdld.sl. There isn't an archive version of libdld.sl. Thus,
9114when the @option{-static} option is specified, special link options
9115are needed to resolve this dependency.
9116
9117On HP-UX 10 and later, the GCC driver adds the necessary options to
9118link with libdld.sl when the @option{-static} option is specified.
9119This causes the resulting binary to be dynamic. On the 64-bit port,
9120the linkers generate dynamic binaries by default in any case. The
9121@option{-nolibdld} option can be used to prevent the GCC driver from
9122adding these link options.
9123
9124@item -threads
9125@opindex threads
9126Add support for multithreading with the @dfn{dce thread} library
9127under HP-UX@. This option sets flags for both the preprocessor and
9128linker.
9129@end table
9130
9131@node i386 and x86-64 Options
9132@subsection Intel 386 and AMD x86-64 Options
9133@cindex i386 Options
9134@cindex x86-64 Options
9135@cindex Intel 386 Options
9136@cindex AMD x86-64 Options
9137
9138These @samp{-m} options are defined for the i386 and x86-64 family of
9139computers:
9140
9141@table @gcctabopt
9142@item -mtune=@var{cpu-type}
9143@opindex mtune
9144Tune to @var{cpu-type} everything applicable about the generated code, except
9145for the ABI and the set of available instructions. The choices for
9146@var{cpu-type} are:
9147@table @emph
9148@item generic
9149Produce code optimized for the most common IA32/AMD64/EM64T processors.
9150If you know the CPU on which your code will run, then you should use
9151the corresponding @option{-mtune} option instead of
9152@option{-mtune=generic}. But, if you do not know exactly what CPU users
9153of your application will have, then you should use this option.
9154
9155As new processors are deployed in the marketplace, the behavior of this
9156option will change. Therefore, if you upgrade to a newer version of
9157GCC, the code generated option will change to reflect the processors
9158that were most common when that version of GCC was released.
9159
9160There is no @option{-march=generic} option because @option{-march}
9161indicates the instruction set the compiler can use, and there is no
9162generic instruction set applicable to all processors. In contrast,
9163@option{-mtune} indicates the processor (or, in this case, collection of
9164processors) for which the code is optimized.
9165@item native
9166This selects the CPU to tune for at compilation time by determining
9167the processor type of the compiling machine. Using @option{-mtune=native}
9168will produce code optimized for the local machine under the constraints
9169of the selected instruction set. Using @option{-march=native} will
9170enable all instruction subsets supported by the local machine (hence
9171the result might not run on different machines).
9172@item i386
9173Original Intel's i386 CPU@.
9174@item i486
9175Intel's i486 CPU@. (No scheduling is implemented for this chip.)
9176@item i586, pentium
9177Intel Pentium CPU with no MMX support.
9178@item pentium-mmx
9179Intel PentiumMMX CPU based on Pentium core with MMX instruction set support.
9180@item pentiumpro
9181Intel PentiumPro CPU@.
9182@item i686
9183Same as @code{generic}, but when used as @code{march} option, PentiumPro
9184instruction set will be used, so the code will run on all i686 family chips.
9185@item pentium2
9186Intel Pentium2 CPU based on PentiumPro core with MMX instruction set support.
9187@item pentium3, pentium3m
9188Intel Pentium3 CPU based on PentiumPro core with MMX and SSE instruction set
9189support.
9190@item pentium-m
9191Low power version of Intel Pentium3 CPU with MMX, SSE and SSE2 instruction set
9192support. Used by Centrino notebooks.
9193@item pentium4, pentium4m
9194Intel Pentium4 CPU with MMX, SSE and SSE2 instruction set support.
9195@item prescott
9196Improved version of Intel Pentium4 CPU with MMX, SSE, SSE2 and SSE3 instruction
9197set support.
9198@item nocona
9199Improved version of Intel Pentium4 CPU with 64-bit extensions, MMX, SSE,
9200SSE2 and SSE3 instruction set support.
9201@item core2
9202Intel Core2 CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3 and SSSE3
9203instruction set support.
9204@item k6
9205AMD K6 CPU with MMX instruction set support.
9206@item k6-2, k6-3
9207Improved versions of AMD K6 CPU with MMX and 3dNOW! instruction set support.
9208@item athlon, athlon-tbird
9209AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW! and SSE prefetch instructions
9210support.
9211@item athlon-4, athlon-xp, athlon-mp
9212Improved AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW! and full SSE
9213instruction set support.
9214@item k8, opteron, athlon64, athlon-fx
9215AMD K8 core based CPUs with x86-64 instruction set support. (This supersets
9216MMX, SSE, SSE2, 3dNOW!, enhanced 3dNOW! and 64-bit instruction set extensions.)
9217@item k8-sse3, opteron-sse3, athlon64-sse3
9218Improved versions of k8, opteron and athlon64 with SSE3 instruction set support.
9219@item amdfam10, barcelona
9220AMD Family 10h core based CPUs with x86-64 instruction set support. (This
9221supersets MMX, SSE, SSE2, SSE3, SSE4A, 3dNOW!, enhanced 3dNOW!, ABM and 64-bit
9222instruction set extensions.)
9223@item winchip-c6
9224IDT Winchip C6 CPU, dealt in same way as i486 with additional MMX instruction
9225set support.
9226@item winchip2
9227IDT Winchip2 CPU, dealt in same way as i486 with additional MMX and 3dNOW!
9228instruction set support.
9229@item c3
9230Via C3 CPU with MMX and 3dNOW! instruction set support. (No scheduling is
9231implemented for this chip.)
9232@item c3-2
9233Via C3-2 CPU with MMX and SSE instruction set support. (No scheduling is
9234implemented for this chip.)
9235@item geode
9236Embedded AMD CPU with MMX and 3dNOW! instruction set support.
9237@end table
9238
9239While picking a specific @var{cpu-type} will schedule things appropriately
9240for that particular chip, the compiler will not generate any code that
9241does not run on the i386 without the @option{-march=@var{cpu-type}} option
9242being used.
9243
9244@item -march=@var{cpu-type}
9245@opindex march
9246Generate instructions for the machine type @var{cpu-type}. The choices
9247for @var{cpu-type} are the same as for @option{-mtune}. Moreover,
9248specifying @option{-march=@var{cpu-type}} implies @option{-mtune=@var{cpu-type}}.
9249
9250@item -mcpu=@var{cpu-type}
9251@opindex mcpu
9252A deprecated synonym for @option{-mtune}.
9253
9254@item -m386
9255@itemx -m486
9256@itemx -mpentium
9257@itemx -mpentiumpro
9258@opindex m386
9259@opindex m486
9260@opindex mpentium
9261@opindex mpentiumpro
9262These options are synonyms for @option{-mtune=i386}, @option{-mtune=i486},
9263@option{-mtune=pentium}, and @option{-mtune=pentiumpro} respectively.
9264These synonyms are deprecated.
9265
9266@item -mfpmath=@var{unit}
9267@opindex march
9268Generate floating point arithmetics for selected unit @var{unit}. The choices
9269for @var{unit} are:
9270
9271@table @samp
9272@item 387
9273Use the standard 387 floating point coprocessor present majority of chips and
9274emulated otherwise. Code compiled with this option will run almost everywhere.
9275The temporary results are computed in 80bit precision instead of precision
9276specified by the type resulting in slightly different results compared to most
9277of other chips. See @option{-ffloat-store} for more detailed description.
9278
9279This is the default choice for i386 compiler.
9280
9281@item sse
9282Use scalar floating point instructions present in the SSE instruction set.
9283This instruction set is supported by Pentium3 and newer chips, in the AMD line
9284by Athlon-4, Athlon-xp and Athlon-mp chips. The earlier version of SSE
9285instruction set supports only single precision arithmetics, thus the double and
9286extended precision arithmetics is still done using 387. Later version, present
9287only in Pentium4 and the future AMD x86-64 chips supports double precision
9288arithmetics too.
9289
9290For the i386 compiler, you need to use @option{-march=@var{cpu-type}}, @option{-msse}
9291or @option{-msse2} switches to enable SSE extensions and make this option
9292effective. For the x86-64 compiler, these extensions are enabled by default.
9293
9294The resulting code should be considerably faster in the majority of cases and avoid
9295the numerical instability problems of 387 code, but may break some existing
9296code that expects temporaries to be 80bit.
9297
9298This is the default choice for the x86-64 compiler.
9299
9300@item sse,387
9301Attempt to utilize both instruction sets at once. This effectively double the
9302amount of available registers and on chips with separate execution units for
9303387 and SSE the execution resources too. Use this option with care, as it is
9304still experimental, because the GCC register allocator does not model separate
9305functional units well resulting in instable performance.
9306@end table
9307
9308@item -masm=@var{dialect}
9309@opindex masm=@var{dialect}
9310Output asm instructions using selected @var{dialect}. Supported
9311choices are @samp{intel} or @samp{att} (the default one). Darwin does
9312not support @samp{intel}.
9313
9314@item -mieee-fp
9315@itemx -mno-ieee-fp
9316@opindex mieee-fp
9317@opindex mno-ieee-fp
9318Control whether or not the compiler uses IEEE floating point
9319comparisons. These handle correctly the case where the result of a
9320comparison is unordered.
9321
9322@item -msoft-float
9323@opindex msoft-float
9324Generate output containing library calls for floating point.
9325@strong{Warning:} the requisite libraries are not part of GCC@.
9326Normally the facilities of the machine's usual C compiler are used, but
9327this can't be done directly in cross-compilation. You must make your
9328own arrangements to provide suitable library functions for
9329cross-compilation.
9330
9331On machines where a function returns floating point results in the 80387
9332register stack, some floating point opcodes may be emitted even if
9333@option{-msoft-float} is used.
9334
9335@item -mno-fp-ret-in-387
9336@opindex mno-fp-ret-in-387
9337Do not use the FPU registers for return values of functions.
9338
9339The usual calling convention has functions return values of types
9340@code{float} and @code{double} in an FPU register, even if there
9341is no FPU@. The idea is that the operating system should emulate
9342an FPU@.
9343
9344The option @option{-mno-fp-ret-in-387} causes such values to be returned
9345in ordinary CPU registers instead.
9346
9347@item -mno-fancy-math-387
9348@opindex mno-fancy-math-387
9349Some 387 emulators do not support the @code{sin}, @code{cos} and
9350@code{sqrt} instructions for the 387. Specify this option to avoid
9351generating those instructions. This option is the default on
9352OpenBSD and NetBSD@. This option is overridden when @option{-march}
9353indicates that the target cpu will always have an FPU and so the
9354instruction will not need emulation. As of revision 2.6.1, these
9355instructions are not generated unless you also use the
9356@option{-funsafe-math-optimizations} switch.
9357
9358@item -malign-double
9359@itemx -mno-align-double
9360@opindex malign-double
9361@opindex mno-align-double
9362Control whether GCC aligns @code{double}, @code{long double}, and
9363@code{long long} variables on a two word boundary or a one word
9364boundary. Aligning @code{double} variables on a two word boundary will
9365produce code that runs somewhat faster on a @samp{Pentium} at the
9366expense of more memory.
9367
9368On x86-64, @option{-malign-double} is enabled by default.
9369
9370@strong{Warning:} if you use the @option{-malign-double} switch,
9371structures containing the above types will be aligned differently than
9372the published application binary interface specifications for the 386
9373and will not be binary compatible with structures in code compiled
9374without that switch.
9375
9376@item -m96bit-long-double
9377@itemx -m128bit-long-double
9378@opindex m96bit-long-double
9379@opindex m128bit-long-double
9380These switches control the size of @code{long double} type. The i386
9381application binary interface specifies the size to be 96 bits,
9382so @option{-m96bit-long-double} is the default in 32 bit mode.
9383
9384Modern architectures (Pentium and newer) would prefer @code{long double}
9385to be aligned to an 8 or 16 byte boundary. In arrays or structures
9386conforming to the ABI, this would not be possible. So specifying a
9387@option{-m128bit-long-double} will align @code{long double}
9388to a 16 byte boundary by padding the @code{long double} with an additional
938932 bit zero.
9390
9391In the x86-64 compiler, @option{-m128bit-long-double} is the default choice as
9392its ABI specifies that @code{long double} is to be aligned on 16 byte boundary.
9393
9394Notice that neither of these options enable any extra precision over the x87
9395standard of 80 bits for a @code{long double}.
9396
9397@strong{Warning:} if you override the default value for your target ABI, the
9398structures and arrays containing @code{long double} variables will change
9399their size as well as function calling convention for function taking
9400@code{long double} will be modified. Hence they will not be binary
9401compatible with arrays or structures in code compiled without that switch.
9402
9403@item -mmlarge-data-threshold=@var{number}
9404@opindex mlarge-data-threshold=@var{number}
9405When @option{-mcmodel=medium} is specified, the data greater than
9406@var{threshold} are placed in large data section. This value must be the
9407same across all object linked into the binary and defaults to 65535.
9408
9409@item -msvr3-shlib
9410@itemx -mno-svr3-shlib
9411@opindex msvr3-shlib
9412@opindex mno-svr3-shlib
9413Control whether GCC places uninitialized local variables into the
9414@code{bss} or @code{data} segments. @option{-msvr3-shlib} places them
9415into @code{bss}. These options are meaningful only on System V Release 3.
9416
9417@item -mrtd
9418@opindex mrtd
9419Use a different function-calling convention, in which functions that
9420take a fixed number of arguments return with the @code{ret} @var{num}
9421instruction, which pops their arguments while returning. This saves one
9422instruction in the caller since there is no need to pop the arguments
9423there.
9424
9425You can specify that an individual function is called with this calling
9426sequence with the function attribute @samp{stdcall}. You can also
9427override the @option{-mrtd} option by using the function attribute
9428@samp{cdecl}. @xref{Function Attributes}.
9429
9430@strong{Warning:} this calling convention is incompatible with the one
9431normally used on Unix, so you cannot use it if you need to call
9432libraries compiled with the Unix compiler.
9433
9434Also, you must provide function prototypes for all functions that
9435take variable numbers of arguments (including @code{printf});
9436otherwise incorrect code will be generated for calls to those
9437functions.
9438
9439In addition, seriously incorrect code will result if you call a
9440function with too many arguments. (Normally, extra arguments are
9441harmlessly ignored.)
9442
9443@item -mregparm=@var{num}
9444@opindex mregparm
9445Control how many registers are used to pass integer arguments. By
9446default, no registers are used to pass arguments, and at most 3
9447registers can be used. You can control this behavior for a specific
9448function by using the function attribute @samp{regparm}.
9449@xref{Function Attributes}.
9450
9451@strong{Warning:} if you use this switch, and
9452@var{num} is nonzero, then you must build all modules with the same
9453value, including any libraries. This includes the system libraries and
9454startup modules.
9455
9456@item -msseregparm
9457@opindex msseregparm
9458Use SSE register passing conventions for float and double arguments
9459and return values. You can control this behavior for a specific
9460function by using the function attribute @samp{sseregparm}.
9461@xref{Function Attributes}.
9462
9463@strong{Warning:} if you use this switch then you must build all
9464modules with the same value, including any libraries. This includes
9465the system libraries and startup modules.
9466
9467@item -mstackrealign
9468@opindex mstackrealign
9469Realign the stack at entry. On the Intel x86, the
9470@option{-mstackrealign} option will generate an alternate prologue and
9471epilogue that realigns the runtime stack. This supports mixing legacy
9472codes that keep a 4-byte aligned stack with modern codes that keep a
947316-byte stack for SSE compatibility. The alternate prologue and
9474epilogue are slower and bigger than the regular ones, and the
9475alternate prologue requires an extra scratch register; this lowers the
9476number of registers available if used in conjunction with the
9477@code{regparm} attribute. The @option{-mstackrealign} option is
9478incompatible with the nested function prologue; this is considered a
9479hard error. See also the attribute @code{force_align_arg_pointer},
9480applicable to individual functions.
9481
9482@item -mpreferred-stack-boundary=@var{num}
9483@opindex mpreferred-stack-boundary
9484Attempt to keep the stack boundary aligned to a 2 raised to @var{num}
9485byte boundary. If @option{-mpreferred-stack-boundary} is not specified,
9486the default is 4 (16 bytes or 128 bits).
9487
9488On Pentium and PentiumPro, @code{double} and @code{long double} values
9489should be aligned to an 8 byte boundary (see @option{-malign-double}) or
9490suffer significant run time performance penalties. On Pentium III, the
9491Streaming SIMD Extension (SSE) data type @code{__m128} may not work
9492properly if it is not 16 byte aligned.
9493
9494To ensure proper alignment of this values on the stack, the stack boundary
9495must be as aligned as that required by any value stored on the stack.
9496Further, every function must be generated such that it keeps the stack
9497aligned. Thus calling a function compiled with a higher preferred
9498stack boundary from a function compiled with a lower preferred stack
9499boundary will most likely misalign the stack. It is recommended that
9500libraries that use callbacks always use the default setting.
9501
9502This extra alignment does consume extra stack space, and generally
9503increases code size. Code that is sensitive to stack space usage, such
9504as embedded systems and operating system kernels, may want to reduce the
9505preferred alignment to @option{-mpreferred-stack-boundary=2}.
9506
9507@item -mmmx
9508@itemx -mno-mmx
9509@item -msse
9510@itemx -mno-sse
9511@item -msse2
9512@itemx -mno-sse2
9513@item -msse3
9514@itemx -mno-sse3
9515@item -mssse3
9516@itemx -mno-ssse3
9517@item -msse4a
9518@item -mno-sse4a
9519@item -m3dnow
9520@itemx -mno-3dnow
9521@item -mpopcnt
9522@itemx -mno-popcnt
9523@item -mabm
9524@itemx -mno-abm
9525@item -maes
9526@itemx -mno-aes
9527@opindex mmmx
9528@opindex mno-mmx
9529@opindex msse
9530@opindex mno-sse
9531@opindex m3dnow
9532@opindex mno-3dnow
9533These switches enable or disable the use of instructions in the MMX,
9534SSE, SSE2, SSE3, SSSE3, SSE4A, ABM, AES or 3DNow! extended
9535instruction sets. These extensions are also available as built-in
9536functions: see @ref{X86 Built-in Functions}, for details of the functions
9537enabled and disabled by these switches.
9538
9539To have SSE/SSE2 instructions generated automatically from floating-point
9540code (as opposed to 387 instructions), see @option{-mfpmath=sse}.
9541
9542These options will enable GCC to use these extended instructions in
9543generated code, even without @option{-mfpmath=sse}. Applications which
9544perform runtime CPU detection must compile separate files for each
9545supported architecture, using the appropriate flags. In particular,
9546the file containing the CPU detection code should be compiled without
9547these options.
9548
9549@item -mpush-args
9550@itemx -mno-push-args
9551@opindex mpush-args
9552@opindex mno-push-args
9553Use PUSH operations to store outgoing parameters. This method is shorter
9554and usually equally fast as method using SUB/MOV operations and is enabled
9555by default. In some cases disabling it may improve performance because of
9556improved scheduling and reduced dependencies.
9557
9558@item -maccumulate-outgoing-args
9559@opindex maccumulate-outgoing-args
9560If enabled, the maximum amount of space required for outgoing arguments will be
9561computed in the function prologue. This is faster on most modern CPUs
9562because of reduced dependencies, improved scheduling and reduced stack usage
9563when preferred stack boundary is not equal to 2. The drawback is a notable
9564increase in code size. This switch implies @option{-mno-push-args}.
9565
9566@item -mthreads
9567@opindex mthreads
9568Support thread-safe exception handling on @samp{Mingw32}. Code that relies
9569on thread-safe exception handling must compile and link all code with the
9570@option{-mthreads} option. When compiling, @option{-mthreads} defines
9571@option{-D_MT}; when linking, it links in a special thread helper library
9572@option{-lmingwthrd} which cleans up per thread exception handling data.
9573
9574@item -mno-align-stringops
9575@opindex mno-align-stringops
9576Do not align destination of inlined string operations. This switch reduces
9577code size and improves performance in case the destination is already aligned,
9578but GCC doesn't know about it.
9579
9580@item -minline-all-stringops
9581@opindex minline-all-stringops
9582By default GCC inlines string operations only when destination is known to be
9583aligned at least to 4 byte boundary. This enables more inlining, increase code
9584size, but may improve performance of code that depends on fast memcpy, strlen
9585and memset for short lengths.
9586
9587@item -momit-leaf-frame-pointer
9588@opindex momit-leaf-frame-pointer
9589Don't keep the frame pointer in a register for leaf functions. This
9590avoids the instructions to save, set up and restore frame pointers and
9591makes an extra register available in leaf functions. The option
9592@option{-fomit-frame-pointer} removes the frame pointer for all functions
9593which might make debugging harder.
9594
9595@item -mtls-direct-seg-refs
9596@itemx -mno-tls-direct-seg-refs
9597@opindex mtls-direct-seg-refs
9598Controls whether TLS variables may be accessed with offsets from the
9599TLS segment register (@code{%gs} for 32-bit, @code{%fs} for 64-bit),
9600or whether the thread base pointer must be added. Whether or not this
9601is legal depends on the operating system, and whether it maps the
9602segment to cover the entire TLS area.
9603
9604For systems that use GNU libc, the default is on.
9605@end table
9606
9607These @samp{-m} switches are supported in addition to the above
9608on AMD x86-64 processors in 64-bit environments.
9609
9610@table @gcctabopt
9611@item -m32
9612@itemx -m64
9613@opindex m32
9614@opindex m64
9615Generate code for a 32-bit or 64-bit environment.
9616The 32-bit environment sets int, long and pointer to 32 bits and
9617generates code that runs on any i386 system.
9618The 64-bit environment sets int to 32 bits and long and pointer
9619to 64 bits and generates code for AMD's x86-64 architecture. For
9620darwin only the -m64 option turns off the @option{-fno-pic} and
9621@option{-mdynamic-no-pic} options.
9622
9623@item -mno-red-zone
9624@opindex no-red-zone
9625Do not use a so called red zone for x86-64 code. The red zone is mandated
9626by the x86-64 ABI, it is a 128-byte area beyond the location of the
9627stack pointer that will not be modified by signal or interrupt handlers
9628and therefore can be used for temporary data without adjusting the stack
9629pointer. The flag @option{-mno-red-zone} disables this red zone.
9630
9631@item -mcmodel=small
9632@opindex mcmodel=small
9633Generate code for the small code model: the program and its symbols must
9634be linked in the lower 2 GB of the address space. Pointers are 64 bits.
9635Programs can be statically or dynamically linked. This is the default
9636code model.
9637
9638@item -mcmodel=kernel
9639@opindex mcmodel=kernel
9640Generate code for the kernel code model. The kernel runs in the
9641negative 2 GB of the address space.
9642This model has to be used for Linux kernel code.
9643
9644@item -mcmodel=medium
9645@opindex mcmodel=medium
9646Generate code for the medium model: The program is linked in the lower 2
9647GB of the address space but symbols can be located anywhere in the
9648address space. Programs can be statically or dynamically linked, but
9649building of shared libraries are not supported with the medium model.
9650
9651@item -mcmodel=large
9652@opindex mcmodel=large
9653Generate code for the large model: This model makes no assumptions
9654about addresses and sizes of sections. Currently GCC does not implement
9655this model.
9656@end table
9657
9658@node IA-64 Options
9659@subsection IA-64 Options
9660@cindex IA-64 Options
9661
9662These are the @samp{-m} options defined for the Intel IA-64 architecture.
9663
9664@table @gcctabopt
9665@item -mbig-endian
9666@opindex mbig-endian
9667Generate code for a big endian target. This is the default for HP-UX@.
9668
9669@item -mlittle-endian
9670@opindex mlittle-endian
9671Generate code for a little endian target. This is the default for AIX5
9672and GNU/Linux.
9673
9674@item -mgnu-as
9675@itemx -mno-gnu-as
9676@opindex mgnu-as
9677@opindex mno-gnu-as
9678Generate (or don't) code for the GNU assembler. This is the default.
9679@c Also, this is the default if the configure option @option{--with-gnu-as}
9680@c is used.
9681
9682@item -mgnu-ld
9683@itemx -mno-gnu-ld
9684@opindex mgnu-ld
9685@opindex mno-gnu-ld
9686Generate (or don't) code for the GNU linker. This is the default.
9687@c Also, this is the default if the configure option @option{--with-gnu-ld}
9688@c is used.
9689
9690@item -mno-pic
9691@opindex mno-pic
9692Generate code that does not use a global pointer register. The result
9693is not position independent code, and violates the IA-64 ABI@.
9694
9695@item -mvolatile-asm-stop
9696@itemx -mno-volatile-asm-stop
9697@opindex mvolatile-asm-stop
9698@opindex mno-volatile-asm-stop
9699Generate (or don't) a stop bit immediately before and after volatile asm
9700statements.
9701
9702@item -mregister-names
9703@itemx -mno-register-names
9704@opindex mregister-names
9705@opindex mno-register-names
9706Generate (or don't) @samp{in}, @samp{loc}, and @samp{out} register names for
9707the stacked registers. This may make assembler output more readable.
9708
9709@item -mno-sdata
9710@itemx -msdata
9711@opindex mno-sdata
9712@opindex msdata
9713Disable (or enable) optimizations that use the small data section. This may
9714be useful for working around optimizer bugs.
9715
9716@item -mconstant-gp
9717@opindex mconstant-gp
9718Generate code that uses a single constant global pointer value. This is
9719useful when compiling kernel code.
9720
9721@item -mauto-pic
9722@opindex mauto-pic
9723Generate code that is self-relocatable. This implies @option{-mconstant-gp}.
9724This is useful when compiling firmware code.
9725
9726@item -minline-float-divide-min-latency
9727@opindex minline-float-divide-min-latency
9728Generate code for inline divides of floating point values
9729using the minimum latency algorithm.
9730
9731@item -minline-float-divide-max-throughput
9732@opindex minline-float-divide-max-throughput
9733Generate code for inline divides of floating point values
9734using the maximum throughput algorithm.
9735
9736@item -minline-int-divide-min-latency
9737@opindex minline-int-divide-min-latency
9738Generate code for inline divides of integer values
9739using the minimum latency algorithm.
9740
9741@item -minline-int-divide-max-throughput
9742@opindex minline-int-divide-max-throughput
9743Generate code for inline divides of integer values
9744using the maximum throughput algorithm.
9745
9746@item -minline-sqrt-min-latency
9747@opindex minline-sqrt-min-latency
9748Generate code for inline square roots
9749using the minimum latency algorithm.
9750
9751@item -minline-sqrt-max-throughput
9752@opindex minline-sqrt-max-throughput
9753Generate code for inline square roots
9754using the maximum throughput algorithm.
9755
9756@item -mno-dwarf2-asm
9757@itemx -mdwarf2-asm
9758@opindex mno-dwarf2-asm
9759@opindex mdwarf2-asm
9760Don't (or do) generate assembler code for the DWARF2 line number debugging
9761info. This may be useful when not using the GNU assembler.
9762
9763@item -mearly-stop-bits
9764@itemx -mno-early-stop-bits
9765@opindex mearly-stop-bits
9766@opindex mno-early-stop-bits
9767Allow stop bits to be placed earlier than immediately preceding the
9768instruction that triggered the stop bit. This can improve instruction
9769scheduling, but does not always do so.
9770
9771@item -mfixed-range=@var{register-range}
9772@opindex mfixed-range
9773Generate code treating the given register range as fixed registers.
9774A fixed register is one that the register allocator can not use. This is
9775useful when compiling kernel code. A register range is specified as
9776two registers separated by a dash. Multiple register ranges can be
9777specified separated by a comma.
9778
9779@item -mtls-size=@var{tls-size}
9780@opindex mtls-size
9781Specify bit size of immediate TLS offsets. Valid values are 14, 22, and
978264.
9783
9784@item -mtune=@var{cpu-type}
9785@opindex mtune
9786Tune the instruction scheduling for a particular CPU, Valid values are
9787itanium, itanium1, merced, itanium2, and mckinley.
9788
9789@item -mt
9790@itemx -pthread
9791@opindex mt
9792@opindex pthread
9793Add support for multithreading using the POSIX threads library. This
9794option sets flags for both the preprocessor and linker. It does
9795not affect the thread safety of object code produced by the compiler or
9796that of libraries supplied with it. These are HP-UX specific flags.
9797
9798@item -milp32
9799@itemx -mlp64
9800@opindex milp32
9801@opindex mlp64
9802Generate code for a 32-bit or 64-bit environment.
9803The 32-bit environment sets int, long and pointer to 32 bits.
9804The 64-bit environment sets int to 32 bits and long and pointer
9805to 64 bits. These are HP-UX specific flags.
9806
9807@item -mno-sched-br-data-spec
9808@itemx -msched-br-data-spec
9809@opindex mno-sched-br-data-spec
9810@opindex msched-br-data-spec
9811(Dis/En)able data speculative scheduling before reload.
9812This will result in generation of the ld.a instructions and
9813the corresponding check instructions (ld.c / chk.a).
9814The default is 'disable'.
9815
9816@item -msched-ar-data-spec
9817@itemx -mno-sched-ar-data-spec
9818@opindex msched-ar-data-spec
9819@opindex mno-sched-ar-data-spec
9820(En/Dis)able data speculative scheduling after reload.
9821This will result in generation of the ld.a instructions and
9822the corresponding check instructions (ld.c / chk.a).
9823The default is 'enable'.
9824
9825@item -mno-sched-control-spec
9826@itemx -msched-control-spec
9827@opindex mno-sched-control-spec
9828@opindex msched-control-spec
9829(Dis/En)able control speculative scheduling. This feature is
9830available only during region scheduling (i.e. before reload).
9831This will result in generation of the ld.s instructions and
9832the corresponding check instructions chk.s .
9833The default is 'disable'.
9834
9835@item -msched-br-in-data-spec
9836@itemx -mno-sched-br-in-data-spec
9837@opindex msched-br-in-data-spec
9838@opindex mno-sched-br-in-data-spec
9839(En/Dis)able speculative scheduling of the instructions that
9840are dependent on the data speculative loads before reload.
9841This is effective only with @option{-msched-br-data-spec} enabled.
9842The default is 'enable'.
9843
9844@item -msched-ar-in-data-spec
9845@itemx -mno-sched-ar-in-data-spec
9846@opindex msched-ar-in-data-spec
9847@opindex mno-sched-ar-in-data-spec
9848(En/Dis)able speculative scheduling of the instructions that
9849are dependent on the data speculative loads after reload.
9850This is effective only with @option{-msched-ar-data-spec} enabled.
9851The default is 'enable'.
9852
9853@item -msched-in-control-spec
9854@itemx -mno-sched-in-control-spec
9855@opindex msched-in-control-spec
9856@opindex mno-sched-in-control-spec
9857(En/Dis)able speculative scheduling of the instructions that
9858are dependent on the control speculative loads.
9859This is effective only with @option{-msched-control-spec} enabled.
9860The default is 'enable'.
9861
9862@item -msched-ldc
9863@itemx -mno-sched-ldc
9864@opindex msched-ldc
9865@opindex mno-sched-ldc
9866(En/Dis)able use of simple data speculation checks ld.c .
9867If disabled, only chk.a instructions will be emitted to check
9868data speculative loads.
9869The default is 'enable'.
9870
9871@item -mno-sched-control-ldc
9872@itemx -msched-control-ldc
9873@opindex mno-sched-control-ldc
9874@opindex msched-control-ldc
9875(Dis/En)able use of ld.c instructions to check control speculative loads.
9876If enabled, in case of control speculative load with no speculatively
9877scheduled dependent instructions this load will be emitted as ld.sa and
9878ld.c will be used to check it.
9879The default is 'disable'.
9880
9881@item -mno-sched-spec-verbose
9882@itemx -msched-spec-verbose
9883@opindex mno-sched-spec-verbose
9884@opindex msched-spec-verbose
9885(Dis/En)able printing of the information about speculative motions.
9886
9887@item -mno-sched-prefer-non-data-spec-insns
9888@itemx -msched-prefer-non-data-spec-insns
9889@opindex mno-sched-prefer-non-data-spec-insns
9890@opindex msched-prefer-non-data-spec-insns
9891If enabled, data speculative instructions will be chosen for schedule
9892only if there are no other choices at the moment. This will make
9893the use of the data speculation much more conservative.
9894The default is 'disable'.
9895
9896@item -mno-sched-prefer-non-control-spec-insns
9897@itemx -msched-prefer-non-control-spec-insns
9898@opindex mno-sched-prefer-non-control-spec-insns
9899@opindex msched-prefer-non-control-spec-insns
9900If enabled, control speculative instructions will be chosen for schedule
9901only if there are no other choices at the moment. This will make
9902the use of the control speculation much more conservative.
9903The default is 'disable'.
9904
9905@item -mno-sched-count-spec-in-critical-path
9906@itemx -msched-count-spec-in-critical-path
9907@opindex mno-sched-count-spec-in-critical-path
9908@opindex msched-count-spec-in-critical-path
9909If enabled, speculative dependencies will be considered during
9910computation of the instructions priorities. This will make the use of the
9911speculation a bit more conservative.
9912The default is 'disable'.
9913
9914@end table
9915
9916@node M32C Options
9917@subsection M32C Options
9918@cindex M32C options
9919
9920@table @gcctabopt
9921@item -mcpu=@var{name}
9922@opindex mcpu=
9923Select the CPU for which code is generated. @var{name} may be one of
9924@samp{r8c} for the R8C/Tiny series, @samp{m16c} for the M16C (up to
9925/60) series, @samp{m32cm} for the M16C/80 series, or @samp{m32c} for
9926the M32C/80 series.
9927
9928@item -msim
9929@opindex msim
9930Specifies that the program will be run on the simulator. This causes
9931an alternate runtime library to be linked in which supports, for
9932example, file I/O. You must not use this option when generating
9933programs that will run on real hardware; you must provide your own
9934runtime library for whatever I/O functions are needed.
9935
9936@item -memregs=@var{number}
9937@opindex memregs=
9938Specifies the number of memory-based pseudo-registers GCC will use
9939during code generation. These pseudo-registers will be used like real
9940registers, so there is a tradeoff between GCC's ability to fit the
9941code into available registers, and the performance penalty of using
9942memory instead of registers. Note that all modules in a program must
9943be compiled with the same value for this option. Because of that, you
9944must not use this option with the default runtime libraries gcc
9945builds.
9946
9947@end table
9948
9949@node M32R/D Options
9950@subsection M32R/D Options
9951@cindex M32R/D options
9952
9953These @option{-m} options are defined for Renesas M32R/D architectures:
9954
9955@table @gcctabopt
9956@item -m32r2
9957@opindex m32r2
9958Generate code for the M32R/2@.
9959
9960@item -m32rx
9961@opindex m32rx
9962Generate code for the M32R/X@.
9963
9964@item -m32r
9965@opindex m32r
9966Generate code for the M32R@. This is the default.
9967
9968@item -mmodel=small
9969@opindex mmodel=small
9970Assume all objects live in the lower 16MB of memory (so that their addresses
9971can be loaded with the @code{ld24} instruction), and assume all subroutines
9972are reachable with the @code{bl} instruction.
9973This is the default.
9974
9975The addressability of a particular object can be set with the
9976@code{model} attribute.
9977
9978@item -mmodel=medium
9979@opindex mmodel=medium
9980Assume objects may be anywhere in the 32-bit address space (the compiler
9981will generate @code{seth/add3} instructions to load their addresses), and
9982assume all subroutines are reachable with the @code{bl} instruction.
9983
9984@item -mmodel=large
9985@opindex mmodel=large
9986Assume objects may be anywhere in the 32-bit address space (the compiler
9987will generate @code{seth/add3} instructions to load their addresses), and
9988assume subroutines may not be reachable with the @code{bl} instruction
9989(the compiler will generate the much slower @code{seth/add3/jl}
9990instruction sequence).
9991
9992@item -msdata=none
9993@opindex msdata=none
9994Disable use of the small data area. Variables will be put into
9995one of @samp{.data}, @samp{bss}, or @samp{.rodata} (unless the
9996@code{section} attribute has been specified).
9997This is the default.
9998
9999The small data area consists of sections @samp{.sdata} and @samp{.sbss}.
10000Objects may be explicitly put in the small data area with the
10001@code{section} attribute using one of these sections.
10002
10003@item -msdata=sdata
10004@opindex msdata=sdata
10005Put small global and static data in the small data area, but do not
10006generate special code to reference them.
10007
10008@item -msdata=use
10009@opindex msdata=use
10010Put small global and static data in the small data area, and generate
10011special instructions to reference them.
10012
10013@item -G @var{num}
10014@opindex G
10015@cindex smaller data references
10016Put global and static objects less than or equal to @var{num} bytes
10017into the small data or bss sections instead of the normal data or bss
10018sections. The default value of @var{num} is 8.
10019The @option{-msdata} option must be set to one of @samp{sdata} or @samp{use}
10020for this option to have any effect.
10021
10022All modules should be compiled with the same @option{-G @var{num}} value.
10023Compiling with different values of @var{num} may or may not work; if it
10024doesn't the linker will give an error message---incorrect code will not be
10025generated.
10026
10027@item -mdebug
10028@opindex mdebug
10029Makes the M32R specific code in the compiler display some statistics
10030that might help in debugging programs.
10031
10032@item -malign-loops
10033@opindex malign-loops
10034Align all loops to a 32-byte boundary.
10035
10036@item -mno-align-loops
10037@opindex mno-align-loops
10038Do not enforce a 32-byte alignment for loops. This is the default.
10039
10040@item -missue-rate=@var{number}
10041@opindex missue-rate=@var{number}
10042Issue @var{number} instructions per cycle. @var{number} can only be 1
10043or 2.
10044
10045@item -mbranch-cost=@var{number}
10046@opindex mbranch-cost=@var{number}
10047@var{number} can only be 1 or 2. If it is 1 then branches will be
10048preferred over conditional code, if it is 2, then the opposite will
10049apply.
10050
10051@item -mflush-trap=@var{number}
10052@opindex mflush-trap=@var{number}
10053Specifies the trap number to use to flush the cache. The default is
1005412. Valid numbers are between 0 and 15 inclusive.
10055
10056@item -mno-flush-trap
10057@opindex mno-flush-trap
10058Specifies that the cache cannot be flushed by using a trap.
10059
10060@item -mflush-func=@var{name}
10061@opindex mflush-func=@var{name}
10062Specifies the name of the operating system function to call to flush
10063the cache. The default is @emph{_flush_cache}, but a function call
10064will only be used if a trap is not available.
10065
10066@item -mno-flush-func
10067@opindex mno-flush-func
10068Indicates that there is no OS function for flushing the cache.
10069
10070@end table
10071
10072@node M680x0 Options
10073@subsection M680x0 Options
10074@cindex M680x0 options
10075
10076These are the @samp{-m} options defined for the 68000 series. The default
10077values for these options depends on which style of 68000 was selected when
10078the compiler was configured; the defaults for the most common choices are
10079given below.
10080
10081@table @gcctabopt
10082@item -m68000
10083@itemx -mc68000
10084@opindex m68000
10085@opindex mc68000
10086Generate output for a 68000. This is the default
10087when the compiler is configured for 68000-based systems.
10088
10089Use this option for microcontrollers with a 68000 or EC000 core,
10090including the 68008, 68302, 68306, 68307, 68322, 68328 and 68356.
10091
10092@item -m68020
10093@itemx -mc68020
10094@opindex m68020
10095@opindex mc68020
10096Generate output for a 68020. This is the default
10097when the compiler is configured for 68020-based systems.
10098
10099@item -m68881
10100@opindex m68881
10101Generate output containing 68881 instructions for floating point.
10102This is the default for most 68020 systems unless @option{--nfp} was
10103specified when the compiler was configured.
10104
10105@item -m68030
10106@opindex m68030
10107Generate output for a 68030. This is the default when the compiler is
10108configured for 68030-based systems.
10109
10110@item -m68040
10111@opindex m68040
10112Generate output for a 68040. This is the default when the compiler is
10113configured for 68040-based systems.
10114
10115This option inhibits the use of 68881/68882 instructions that have to be
10116emulated by software on the 68040. Use this option if your 68040 does not
10117have code to emulate those instructions.
10118
10119@item -m68060
10120@opindex m68060
10121Generate output for a 68060. This is the default when the compiler is
10122configured for 68060-based systems.
10123
10124This option inhibits the use of 68020 and 68881/68882 instructions that
10125have to be emulated by software on the 68060. Use this option if your 68060
10126does not have code to emulate those instructions.
10127
10128@item -mcpu32
10129@opindex mcpu32
10130Generate output for a CPU32. This is the default
10131when the compiler is configured for CPU32-based systems.
10132
10133Use this option for microcontrollers with a
10134CPU32 or CPU32+ core, including the 68330, 68331, 68332, 68333, 68334,
1013568336, 68340, 68341, 68349 and 68360.
10136
10137@item -m5200
10138@opindex m5200
10139Generate output for a 520X ``coldfire'' family cpu. This is the default
10140when the compiler is configured for 520X-based systems.
10141
10142Use this option for microcontroller with a 5200 core, including
10143the MCF5202, MCF5203, MCF5204 and MCF5202.
10144
10145@item -mcfv4e
10146@opindex mcfv4e
10147Generate output for a ColdFire V4e family cpu (e.g.@: 547x/548x).
10148This includes use of hardware floating point instructions.
10149
10150@item -m68020-40
10151@opindex m68020-40
10152Generate output for a 68040, without using any of the new instructions.
10153This results in code which can run relatively efficiently on either a
1015468020/68881 or a 68030 or a 68040. The generated code does use the
1015568881 instructions that are emulated on the 68040.
10156
10157@item -m68020-60
10158@opindex m68020-60
10159Generate output for a 68060, without using any of the new instructions.
10160This results in code which can run relatively efficiently on either a
1016168020/68881 or a 68030 or a 68040. The generated code does use the
1016268881 instructions that are emulated on the 68060.
10163
10164@item -msoft-float
10165@opindex msoft-float
10166Generate output containing library calls for floating point.
10167@strong{Warning:} the requisite libraries are not available for all m68k
10168targets. Normally the facilities of the machine's usual C compiler are
10169used, but this can't be done directly in cross-compilation. You must
10170make your own arrangements to provide suitable library functions for
10171cross-compilation. The embedded targets @samp{m68k-*-aout} and
10172@samp{m68k-*-coff} do provide software floating point support.
10173
10174@item -mshort
10175@opindex mshort
10176Consider type @code{int} to be 16 bits wide, like @code{short int}.
10177Additionally, parameters passed on the stack are also aligned to a
1017816-bit boundary even on targets whose API mandates promotion to 32-bit.
10179
10180@item -mnobitfield
10181@opindex mnobitfield
10182Do not use the bit-field instructions. The @option{-m68000}, @option{-mcpu32}
10183and @option{-m5200} options imply @w{@option{-mnobitfield}}.
10184
10185@item -mbitfield
10186@opindex mbitfield
10187Do use the bit-field instructions. The @option{-m68020} option implies
10188@option{-mbitfield}. This is the default if you use a configuration
10189designed for a 68020.
10190
10191@item -mrtd
10192@opindex mrtd
10193Use a different function-calling convention, in which functions
10194that take a fixed number of arguments return with the @code{rtd}
10195instruction, which pops their arguments while returning. This
10196saves one instruction in the caller since there is no need to pop
10197the arguments there.
10198
10199This calling convention is incompatible with the one normally
10200used on Unix, so you cannot use it if you need to call libraries
10201compiled with the Unix compiler.
10202
10203Also, you must provide function prototypes for all functions that
10204take variable numbers of arguments (including @code{printf});
10205otherwise incorrect code will be generated for calls to those
10206functions.
10207
10208In addition, seriously incorrect code will result if you call a
10209function with too many arguments. (Normally, extra arguments are
10210harmlessly ignored.)
10211
10212The @code{rtd} instruction is supported by the 68010, 68020, 68030,
1021368040, 68060 and CPU32 processors, but not by the 68000 or 5200.
10214
10215@item -malign-int
10216@itemx -mno-align-int
10217@opindex malign-int
10218@opindex mno-align-int
10219Control whether GCC aligns @code{int}, @code{long}, @code{long long},
10220@code{float}, @code{double}, and @code{long double} variables on a 32-bit
10221boundary (@option{-malign-int}) or a 16-bit boundary (@option{-mno-align-int}).
10222Aligning variables on 32-bit boundaries produces code that runs somewhat
10223faster on processors with 32-bit busses at the expense of more memory.
10224
10225@strong{Warning:} if you use the @option{-malign-int} switch, GCC will
10226align structures containing the above types differently than
10227most published application binary interface specifications for the m68k.
10228
10229@item -mpcrel
10230@opindex mpcrel
10231Use the pc-relative addressing mode of the 68000 directly, instead of
10232using a global offset table. At present, this option implies @option{-fpic},
10233allowing at most a 16-bit offset for pc-relative addressing. @option{-fPIC} is
10234not presently supported with @option{-mpcrel}, though this could be supported for
1023568020 and higher processors.
10236
10237@item -mno-strict-align
10238@itemx -mstrict-align
10239@opindex mno-strict-align
10240@opindex mstrict-align
10241Do not (do) assume that unaligned memory references will be handled by
10242the system.
10243
10244@item -msep-data
10245Generate code that allows the data segment to be located in a different
10246area of memory from the text segment. This allows for execute in place in
10247an environment without virtual memory management. This option implies
10248@option{-fPIC}.
10249
10250@item -mno-sep-data
10251Generate code that assumes that the data segment follows the text segment.
10252This is the default.
10253
10254@item -mid-shared-library
10255Generate code that supports shared libraries via the library ID method.
10256This allows for execute in place and shared libraries in an environment
10257without virtual memory management. This option implies @option{-fPIC}.
10258
10259@item -mno-id-shared-library
10260Generate code that doesn't assume ID based shared libraries are being used.
10261This is the default.
10262
10263@item -mshared-library-id=n
10264Specified the identification number of the ID based shared library being
10265compiled. Specifying a value of 0 will generate more compact code, specifying
10266other values will force the allocation of that number to the current
10267library but is no more space or time efficient than omitting this option.
10268
10269@end table
10270
10271@node M68hc1x Options
10272@subsection M68hc1x Options
10273@cindex M68hc1x options
10274
10275These are the @samp{-m} options defined for the 68hc11 and 68hc12
10276microcontrollers. The default values for these options depends on
10277which style of microcontroller was selected when the compiler was configured;
10278the defaults for the most common choices are given below.
10279
10280@table @gcctabopt
10281@item -m6811
10282@itemx -m68hc11
10283@opindex m6811
10284@opindex m68hc11
10285Generate output for a 68HC11. This is the default
10286when the compiler is configured for 68HC11-based systems.
10287
10288@item -m6812
10289@itemx -m68hc12
10290@opindex m6812
10291@opindex m68hc12
10292Generate output for a 68HC12. This is the default
10293when the compiler is configured for 68HC12-based systems.
10294
10295@item -m68S12
10296@itemx -m68hcs12
10297@opindex m68S12
10298@opindex m68hcs12
10299Generate output for a 68HCS12.
10300
10301@item -mauto-incdec
10302@opindex mauto-incdec
10303Enable the use of 68HC12 pre and post auto-increment and auto-decrement
10304addressing modes.
10305
10306@item -minmax
10307@itemx -nominmax
10308@opindex minmax
10309@opindex mnominmax
10310Enable the use of 68HC12 min and max instructions.
10311
10312@item -mlong-calls
10313@itemx -mno-long-calls
10314@opindex mlong-calls
10315@opindex mno-long-calls
10316Treat all calls as being far away (near). If calls are assumed to be
10317far away, the compiler will use the @code{call} instruction to
10318call a function and the @code{rtc} instruction for returning.
10319
10320@item -mshort
10321@opindex mshort
10322Consider type @code{int} to be 16 bits wide, like @code{short int}.
10323
10324@item -msoft-reg-count=@var{count}
10325@opindex msoft-reg-count
10326Specify the number of pseudo-soft registers which are used for the
10327code generation. The maximum number is 32. Using more pseudo-soft
10328register may or may not result in better code depending on the program.
10329The default is 4 for 68HC11 and 2 for 68HC12.
10330
10331@end table
10332
10333@node MCore Options
10334@subsection MCore Options
10335@cindex MCore options
10336
10337These are the @samp{-m} options defined for the Motorola M*Core
10338processors.
10339
10340@table @gcctabopt
10341
10342@item -mhardlit
10343@itemx -mno-hardlit
10344@opindex mhardlit
10345@opindex mno-hardlit
10346Inline constants into the code stream if it can be done in two
10347instructions or less.
10348
10349@item -mdiv
10350@itemx -mno-div
10351@opindex mdiv
10352@opindex mno-div
10353Use the divide instruction. (Enabled by default).
10354
10355@item -mrelax-immediate
10356@itemx -mno-relax-immediate
10357@opindex mrelax-immediate
10358@opindex mno-relax-immediate
10359Allow arbitrary sized immediates in bit operations.
10360
10361@item -mwide-bitfields
10362@itemx -mno-wide-bitfields
10363@opindex mwide-bitfields
10364@opindex mno-wide-bitfields
10365Always treat bit-fields as int-sized.
10366
10367@item -m4byte-functions
10368@itemx -mno-4byte-functions
10369@opindex m4byte-functions
10370@opindex mno-4byte-functions
10371Force all functions to be aligned to a four byte boundary.
10372
10373@item -mcallgraph-data
10374@itemx -mno-callgraph-data
10375@opindex mcallgraph-data
10376@opindex mno-callgraph-data
10377Emit callgraph information.
10378
10379@item -mslow-bytes
10380@itemx -mno-slow-bytes
10381@opindex mslow-bytes
10382@opindex mno-slow-bytes
10383Prefer word access when reading byte quantities.
10384
10385@item -mlittle-endian
10386@itemx -mbig-endian
10387@opindex mlittle-endian
10388@opindex mbig-endian
10389Generate code for a little endian target.
10390
10391@item -m210
10392@itemx -m340
10393@opindex m210
10394@opindex m340
10395Generate code for the 210 processor.
10396@end table
10397
10398@node MIPS Options
10399@subsection MIPS Options
10400@cindex MIPS options
10401
10402@table @gcctabopt
10403
10404@item -EB
10405@opindex EB
10406Generate big-endian code.
10407
10408@item -EL
10409@opindex EL
10410Generate little-endian code. This is the default for @samp{mips*el-*-*}
10411configurations.
10412
10413@item -march=@var{arch}
10414@opindex march
10415Generate code that will run on @var{arch}, which can be the name of a
10416generic MIPS ISA, or the name of a particular processor.
10417The ISA names are:
10418@samp{mips1}, @samp{mips2}, @samp{mips3}, @samp{mips4},
10419@samp{mips32}, @samp{mips32r2}, and @samp{mips64}.
10420The processor names are:
10421@samp{4kc}, @samp{4km}, @samp{4kp},
10422@samp{5kc}, @samp{5kf},
10423@samp{20kc},
10424@samp{24k}, @samp{24kc}, @samp{24kf}, @samp{24kx},
10425@samp{m4k},
10426@samp{orion},
10427@samp{r2000}, @samp{r3000}, @samp{r3900}, @samp{r4000}, @samp{r4400},
10428@samp{r4600}, @samp{r4650}, @samp{r6000}, @samp{r8000},
10429@samp{rm7000}, @samp{rm9000},
10430@samp{sb1},
10431@samp{sr71000},
10432@samp{vr4100}, @samp{vr4111}, @samp{vr4120}, @samp{vr4130}, @samp{vr4300},
10433@samp{vr5000}, @samp{vr5400} and @samp{vr5500}.
10434The special value @samp{from-abi} selects the
10435most compatible architecture for the selected ABI (that is,
10436@samp{mips1} for 32-bit ABIs and @samp{mips3} for 64-bit ABIs)@.
10437
10438In processor names, a final @samp{000} can be abbreviated as @samp{k}
10439(for example, @samp{-march=r2k}). Prefixes are optional, and
10440@samp{vr} may be written @samp{r}.
10441
10442GCC defines two macros based on the value of this option. The first
10443is @samp{_MIPS_ARCH}, which gives the name of target architecture, as
10444a string. The second has the form @samp{_MIPS_ARCH_@var{foo}},
10445where @var{foo} is the capitalized value of @samp{_MIPS_ARCH}@.
10446For example, @samp{-march=r2000} will set @samp{_MIPS_ARCH}
10447to @samp{"r2000"} and define the macro @samp{_MIPS_ARCH_R2000}.
10448
10449Note that the @samp{_MIPS_ARCH} macro uses the processor names given
10450above. In other words, it will have the full prefix and will not
10451abbreviate @samp{000} as @samp{k}. In the case of @samp{from-abi},
10452the macro names the resolved architecture (either @samp{"mips1"} or
10453@samp{"mips3"}). It names the default architecture when no
10454@option{-march} option is given.
10455
10456@item -mtune=@var{arch}
10457@opindex mtune
10458Optimize for @var{arch}. Among other things, this option controls
10459the way instructions are scheduled, and the perceived cost of arithmetic
10460operations. The list of @var{arch} values is the same as for
10461@option{-march}.
10462
10463When this option is not used, GCC will optimize for the processor
10464specified by @option{-march}. By using @option{-march} and
10465@option{-mtune} together, it is possible to generate code that will
10466run on a family of processors, but optimize the code for one
10467particular member of that family.
10468
10469@samp{-mtune} defines the macros @samp{_MIPS_TUNE} and
10470@samp{_MIPS_TUNE_@var{foo}}, which work in the same way as the
10471@samp{-march} ones described above.
10472
10473@item -mips1
10474@opindex mips1
10475Equivalent to @samp{-march=mips1}.
10476
10477@item -mips2
10478@opindex mips2
10479Equivalent to @samp{-march=mips2}.
10480
10481@item -mips3
10482@opindex mips3
10483Equivalent to @samp{-march=mips3}.
10484
10485@item -mips4
10486@opindex mips4
10487Equivalent to @samp{-march=mips4}.
10488
10489@item -mips32
10490@opindex mips32
10491Equivalent to @samp{-march=mips32}.
10492
10493@item -mips32r2
10494@opindex mips32r2
10495Equivalent to @samp{-march=mips32r2}.
10496
10497@item -mips64
10498@opindex mips64
10499Equivalent to @samp{-march=mips64}.
10500
10501@item -mips16
10502@itemx -mno-mips16
10503@opindex mips16
10504@opindex mno-mips16
10505Generate (do not generate) MIPS16 code. If GCC is targetting a
10506MIPS32 or MIPS64 architecture, it will make use of the MIPS16e ASE@.
10507
10508@item -mabi=32
10509@itemx -mabi=o64
10510@itemx -mabi=n32
10511@itemx -mabi=64
10512@itemx -mabi=eabi
10513@opindex mabi=32
10514@opindex mabi=o64
10515@opindex mabi=n32
10516@opindex mabi=64
10517@opindex mabi=eabi
10518Generate code for the given ABI@.
10519
10520Note that the EABI has a 32-bit and a 64-bit variant. GCC normally
10521generates 64-bit code when you select a 64-bit architecture, but you
10522can use @option{-mgp32} to get 32-bit code instead.
10523
10524For information about the O64 ABI, see
10525@w{@uref{http://gcc.gnu.org/projects/mipso64-abi.html}}.
10526
10527@item -mabicalls
10528@itemx -mno-abicalls
10529@opindex mabicalls
10530@opindex mno-abicalls
10531Generate (do not generate) code that is suitable for SVR4-style
10532dynamic objects. @option{-mabicalls} is the default for SVR4-based
10533systems.
10534
10535@item -mshared
10536@itemx -mno-shared
10537Generate (do not generate) code that is fully position-independent,
10538and that can therefore be linked into shared libraries. This option
10539only affects @option{-mabicalls}.
10540
10541All @option{-mabicalls} code has traditionally been position-independent,
10542regardless of options like @option{-fPIC} and @option{-fpic}. However,
10543as an extension, the GNU toolchain allows executables to use absolute
10544accesses for locally-binding symbols. It can also use shorter GP
10545initialization sequences and generate direct calls to locally-defined
10546functions. This mode is selected by @option{-mno-shared}.
10547
10548@option{-mno-shared} depends on binutils 2.16 or higher and generates
10549objects that can only be linked by the GNU linker. However, the option
10550does not affect the ABI of the final executable; it only affects the ABI
10551of relocatable objects. Using @option{-mno-shared} will generally make
10552executables both smaller and quicker.
10553
10554@option{-mshared} is the default.
10555
10556@item -mxgot
10557@itemx -mno-xgot
10558@opindex mxgot
10559@opindex mno-xgot
10560Lift (do not lift) the usual restrictions on the size of the global
10561offset table.
10562
10563GCC normally uses a single instruction to load values from the GOT@.
10564While this is relatively efficient, it will only work if the GOT
10565is smaller than about 64k. Anything larger will cause the linker
10566to report an error such as:
10567
10568@cindex relocation truncated to fit (MIPS)
10569@smallexample
10570relocation truncated to fit: R_MIPS_GOT16 foobar
10571@end smallexample
10572
10573If this happens, you should recompile your code with @option{-mxgot}.
10574It should then work with very large GOTs, although it will also be
10575less efficient, since it will take three instructions to fetch the
10576value of a global symbol.
10577
10578Note that some linkers can create multiple GOTs. If you have such a
10579linker, you should only need to use @option{-mxgot} when a single object
10580file accesses more than 64k's worth of GOT entries. Very few do.
10581
10582These options have no effect unless GCC is generating position
10583independent code.
10584
10585@item -mgp32
10586@opindex mgp32
10587Assume that general-purpose registers are 32 bits wide.
10588
10589@item -mgp64
10590@opindex mgp64
10591Assume that general-purpose registers are 64 bits wide.
10592
10593@item -mfp32
10594@opindex mfp32
10595Assume that floating-point registers are 32 bits wide.
10596
10597@item -mfp64
10598@opindex mfp64
10599Assume that floating-point registers are 64 bits wide.
10600
10601@item -mhard-float
10602@opindex mhard-float
10603Use floating-point coprocessor instructions.
10604
10605@item -msoft-float
10606@opindex msoft-float
10607Do not use floating-point coprocessor instructions. Implement
10608floating-point calculations using library calls instead.
10609
10610@item -msingle-float
10611@opindex msingle-float
10612Assume that the floating-point coprocessor only supports single-precision
10613operations.
10614
10615@itemx -mdouble-float
10616@opindex mdouble-float
10617Assume that the floating-point coprocessor supports double-precision
10618operations. This is the default.
10619
10620@itemx -mdsp
10621@itemx -mno-dsp
10622@opindex mdsp
10623@opindex mno-dsp
10624Use (do not use) the MIPS DSP ASE. @xref{MIPS DSP Built-in Functions}.
10625
10626@itemx -mpaired-single
10627@itemx -mno-paired-single
10628@opindex mpaired-single
10629@opindex mno-paired-single
10630Use (do not use) paired-single floating-point instructions.
10631@xref{MIPS Paired-Single Support}. This option can only be used
10632when generating 64-bit code and requires hardware floating-point
10633support to be enabled.
10634
10635@itemx -mips3d
10636@itemx -mno-mips3d
10637@opindex mips3d
10638@opindex mno-mips3d
10639Use (do not use) the MIPS-3D ASE@. @xref{MIPS-3D Built-in Functions}.
10640The option @option{-mips3d} implies @option{-mpaired-single}.
10641
10642@item -mlong64
10643@opindex mlong64
10644Force @code{long} types to be 64 bits wide. See @option{-mlong32} for
10645an explanation of the default and the way that the pointer size is
10646determined.
10647
10648@item -mlong32
10649@opindex mlong32
10650Force @code{long}, @code{int}, and pointer types to be 32 bits wide.
10651
10652The default size of @code{int}s, @code{long}s and pointers depends on
10653the ABI@. All the supported ABIs use 32-bit @code{int}s. The n64 ABI
10654uses 64-bit @code{long}s, as does the 64-bit EABI; the others use
1065532-bit @code{long}s. Pointers are the same size as @code{long}s,
10656or the same size as integer registers, whichever is smaller.
10657
10658@item -msym32
10659@itemx -mno-sym32
10660@opindex msym32
10661@opindex mno-sym32
10662Assume (do not assume) that all symbols have 32-bit values, regardless
10663of the selected ABI@. This option is useful in combination with
10664@option{-mabi=64} and @option{-mno-abicalls} because it allows GCC
10665to generate shorter and faster references to symbolic addresses.
10666
10667@item -G @var{num}
10668@opindex G
10669@cindex smaller data references (MIPS)
10670@cindex gp-relative references (MIPS)
10671Put global and static items less than or equal to @var{num} bytes into
10672the small data or bss section instead of the normal data or bss section.
10673This allows the data to be accessed using a single instruction.
10674
10675All modules should be compiled with the same @option{-G @var{num}}
10676value.
10677
10678@item -membedded-data
10679@itemx -mno-embedded-data
10680@opindex membedded-data
10681@opindex mno-embedded-data
10682Allocate variables to the read-only data section first if possible, then
10683next in the small data section if possible, otherwise in data. This gives
10684slightly slower code than the default, but reduces the amount of RAM required
10685when executing, and thus may be preferred for some embedded systems.
10686
10687@item -muninit-const-in-rodata
10688@itemx -mno-uninit-const-in-rodata
10689@opindex muninit-const-in-rodata
10690@opindex mno-uninit-const-in-rodata
10691Put uninitialized @code{const} variables in the read-only data section.
10692This option is only meaningful in conjunction with @option{-membedded-data}.
10693
10694@item -msplit-addresses
10695@itemx -mno-split-addresses
10696@opindex msplit-addresses
10697@opindex mno-split-addresses
10698Enable (disable) use of the @code{%hi()} and @code{%lo()} assembler
10699relocation operators. This option has been superseded by
10700@option{-mexplicit-relocs} but is retained for backwards compatibility.
10701
10702@item -mexplicit-relocs
10703@itemx -mno-explicit-relocs
10704@opindex mexplicit-relocs
10705@opindex mno-explicit-relocs
10706Use (do not use) assembler relocation operators when dealing with symbolic
10707addresses. The alternative, selected by @option{-mno-explicit-relocs},
10708is to use assembler macros instead.
10709
10710@option{-mexplicit-relocs} is the default if GCC was configured
10711to use an assembler that supports relocation operators.
10712
10713@item -mcheck-zero-division
10714@itemx -mno-check-zero-division
10715@opindex mcheck-zero-division
10716@opindex mno-check-zero-division
10717Trap (do not trap) on integer division by zero. The default is
10718@option{-mcheck-zero-division}.
10719
10720@item -mdivide-traps
10721@itemx -mdivide-breaks
10722@opindex mdivide-traps
10723@opindex mdivide-breaks
10724MIPS systems check for division by zero by generating either a
10725conditional trap or a break instruction. Using traps results in
10726smaller code, but is only supported on MIPS II and later. Also, some
10727versions of the Linux kernel have a bug that prevents trap from
10728generating the proper signal (@code{SIGFPE}). Use @option{-mdivide-traps} to
10729allow conditional traps on architectures that support them and
10730@option{-mdivide-breaks} to force the use of breaks.
10731
10732The default is usually @option{-mdivide-traps}, but this can be
10733overridden at configure time using @option{--with-divide=breaks}.
10734Divide-by-zero checks can be completely disabled using
10735@option{-mno-check-zero-division}.
10736
10737@item -mmemcpy
10738@itemx -mno-memcpy
10739@opindex mmemcpy
10740@opindex mno-memcpy
10741Force (do not force) the use of @code{memcpy()} for non-trivial block
10742moves. The default is @option{-mno-memcpy}, which allows GCC to inline
10743most constant-sized copies.
10744
10745@item -mlong-calls
10746@itemx -mno-long-calls
10747@opindex mlong-calls
10748@opindex mno-long-calls
10749Disable (do not disable) use of the @code{jal} instruction. Calling
10750functions using @code{jal} is more efficient but requires the caller
10751and callee to be in the same 256 megabyte segment.
10752
10753This option has no effect on abicalls code. The default is
10754@option{-mno-long-calls}.
10755
10756@item -mmad
10757@itemx -mno-mad
10758@opindex mmad
10759@opindex mno-mad
10760Enable (disable) use of the @code{mad}, @code{madu} and @code{mul}
10761instructions, as provided by the R4650 ISA@.
10762
10763@item -mfused-madd
10764@itemx -mno-fused-madd
10765@opindex mfused-madd
10766@opindex mno-fused-madd
10767Enable (disable) use of the floating point multiply-accumulate
10768instructions, when they are available. The default is
10769@option{-mfused-madd}.
10770
10771When multiply-accumulate instructions are used, the intermediate
10772product is calculated to infinite precision and is not subject to
10773the FCSR Flush to Zero bit. This may be undesirable in some
10774circumstances.
10775
10776@item -nocpp
10777@opindex nocpp
10778Tell the MIPS assembler to not run its preprocessor over user
10779assembler files (with a @samp{.s} suffix) when assembling them.
10780
10781@item -mfix-r4000
10782@itemx -mno-fix-r4000
10783@opindex mfix-r4000
10784@opindex mno-fix-r4000
10785Work around certain R4000 CPU errata:
10786@itemize @minus
10787@item
10788A double-word or a variable shift may give an incorrect result if executed
10789immediately after starting an integer division.
10790@item
10791A double-word or a variable shift may give an incorrect result if executed
10792while an integer multiplication is in progress.
10793@item
10794An integer division may give an incorrect result if started in a delay slot
10795of a taken branch or a jump.
10796@end itemize
10797
10798@item -mfix-r4400
10799@itemx -mno-fix-r4400
10800@opindex mfix-r4400
10801@opindex mno-fix-r4400
10802Work around certain R4400 CPU errata:
10803@itemize @minus
10804@item
10805A double-word or a variable shift may give an incorrect result if executed
10806immediately after starting an integer division.
10807@end itemize
10808
10809@item -mfix-vr4120
10810@itemx -mno-fix-vr4120
10811@opindex mfix-vr4120
10812Work around certain VR4120 errata:
10813@itemize @minus
10814@item
10815@code{dmultu} does not always produce the correct result.
10816@item
10817@code{div} and @code{ddiv} do not always produce the correct result if one
10818of the operands is negative.
10819@end itemize
10820The workarounds for the division errata rely on special functions in
10821@file{libgcc.a}. At present, these functions are only provided by
10822the @code{mips64vr*-elf} configurations.
10823
10824Other VR4120 errata require a nop to be inserted between certain pairs of
10825instructions. These errata are handled by the assembler, not by GCC itself.
10826
10827@item -mfix-vr4130
10828@opindex mfix-vr4130
10829Work around the VR4130 @code{mflo}/@code{mfhi} errata. The
10830workarounds are implemented by the assembler rather than by GCC,
10831although GCC will avoid using @code{mflo} and @code{mfhi} if the
10832VR4130 @code{macc}, @code{macchi}, @code{dmacc} and @code{dmacchi}
10833instructions are available instead.
10834
10835@item -mfix-sb1
10836@itemx -mno-fix-sb1
10837@opindex mfix-sb1
10838Work around certain SB-1 CPU core errata.
10839(This flag currently works around the SB-1 revision 2
10840``F1'' and ``F2'' floating point errata.)
10841
10842@item -mflush-func=@var{func}
10843@itemx -mno-flush-func
10844@opindex mflush-func
10845Specifies the function to call to flush the I and D caches, or to not
10846call any such function. If called, the function must take the same
10847arguments as the common @code{_flush_func()}, that is, the address of the
10848memory range for which the cache is being flushed, the size of the
10849memory range, and the number 3 (to flush both caches). The default
10850depends on the target GCC was configured for, but commonly is either
10851@samp{_flush_func} or @samp{__cpu_flush}.
10852
10853@item -mbranch-likely
10854@itemx -mno-branch-likely
10855@opindex mbranch-likely
10856@opindex mno-branch-likely
10857Enable or disable use of Branch Likely instructions, regardless of the
10858default for the selected architecture. By default, Branch Likely
10859instructions may be generated if they are supported by the selected
10860architecture. An exception is for the MIPS32 and MIPS64 architectures
10861and processors which implement those architectures; for those, Branch
10862Likely instructions will not be generated by default because the MIPS32
10863and MIPS64 architectures specifically deprecate their use.
10864
10865@item -mfp-exceptions
10866@itemx -mno-fp-exceptions
10867@opindex mfp-exceptions
10868Specifies whether FP exceptions are enabled. This affects how we schedule
10869FP instructions for some processors. The default is that FP exceptions are
10870enabled.
10871
10872For instance, on the SB-1, if FP exceptions are disabled, and we are emitting
1087364-bit code, then we can use both FP pipes. Otherwise, we can only use one
10874FP pipe.
10875
10876@item -mvr4130-align
10877@itemx -mno-vr4130-align
10878@opindex mvr4130-align
10879The VR4130 pipeline is two-way superscalar, but can only issue two
10880instructions together if the first one is 8-byte aligned. When this
10881option is enabled, GCC will align pairs of instructions that it
10882thinks should execute in parallel.
10883
10884This option only has an effect when optimizing for the VR4130.
10885It normally makes code faster, but at the expense of making it bigger.
10886It is enabled by default at optimization level @option{-O3}.
10887@end table
10888
10889@node MMIX Options
10890@subsection MMIX Options
10891@cindex MMIX Options
10892
10893These options are defined for the MMIX:
10894
10895@table @gcctabopt
10896@item -mlibfuncs
10897@itemx -mno-libfuncs
10898@opindex mlibfuncs
10899@opindex mno-libfuncs
10900Specify that intrinsic library functions are being compiled, passing all
10901values in registers, no matter the size.
10902
10903@item -mepsilon
10904@itemx -mno-epsilon
10905@opindex mepsilon
10906@opindex mno-epsilon
10907Generate floating-point comparison instructions that compare with respect
10908to the @code{rE} epsilon register.
10909
10910@item -mabi=mmixware
10911@itemx -mabi=gnu
10912@opindex mabi-mmixware
10913@opindex mabi=gnu
10914Generate code that passes function parameters and return values that (in
10915the called function) are seen as registers @code{$0} and up, as opposed to
10916the GNU ABI which uses global registers @code{$231} and up.
10917
10918@item -mzero-extend
10919@itemx -mno-zero-extend
10920@opindex mzero-extend
10921@opindex mno-zero-extend
10922When reading data from memory in sizes shorter than 64 bits, use (do not
10923use) zero-extending load instructions by default, rather than
10924sign-extending ones.
10925
10926@item -mknuthdiv
10927@itemx -mno-knuthdiv
10928@opindex mknuthdiv
10929@opindex mno-knuthdiv
10930Make the result of a division yielding a remainder have the same sign as
10931the divisor. With the default, @option{-mno-knuthdiv}, the sign of the
10932remainder follows the sign of the dividend. Both methods are
10933arithmetically valid, the latter being almost exclusively used.
10934
10935@item -mtoplevel-symbols
10936@itemx -mno-toplevel-symbols
10937@opindex mtoplevel-symbols
10938@opindex mno-toplevel-symbols
10939Prepend (do not prepend) a @samp{:} to all global symbols, so the assembly
10940code can be used with the @code{PREFIX} assembly directive.
10941
10942@item -melf
10943@opindex melf
10944Generate an executable in the ELF format, rather than the default
10945@samp{mmo} format used by the @command{mmix} simulator.
10946
10947@item -mbranch-predict
10948@itemx -mno-branch-predict
10949@opindex mbranch-predict
10950@opindex mno-branch-predict
10951Use (do not use) the probable-branch instructions, when static branch
10952prediction indicates a probable branch.
10953
10954@item -mbase-addresses
10955@itemx -mno-base-addresses
10956@opindex mbase-addresses
10957@opindex mno-base-addresses
10958Generate (do not generate) code that uses @emph{base addresses}. Using a
10959base address automatically generates a request (handled by the assembler
10960and the linker) for a constant to be set up in a global register. The
10961register is used for one or more base address requests within the range 0
10962to 255 from the value held in the register. The generally leads to short
10963and fast code, but the number of different data items that can be
10964addressed is limited. This means that a program that uses lots of static
10965data may require @option{-mno-base-addresses}.
10966
10967@item -msingle-exit
10968@itemx -mno-single-exit
10969@opindex msingle-exit
10970@opindex mno-single-exit
10971Force (do not force) generated code to have a single exit point in each
10972function.
10973@end table
10974
10975@node MN10300 Options
10976@subsection MN10300 Options
10977@cindex MN10300 options
10978
10979These @option{-m} options are defined for Matsushita MN10300 architectures:
10980
10981@table @gcctabopt
10982@item -mmult-bug
10983@opindex mmult-bug
10984Generate code to avoid bugs in the multiply instructions for the MN10300
10985processors. This is the default.
10986
10987@item -mno-mult-bug
10988@opindex mno-mult-bug
10989Do not generate code to avoid bugs in the multiply instructions for the
10990MN10300 processors.
10991
10992@item -mam33
10993@opindex mam33
10994Generate code which uses features specific to the AM33 processor.
10995
10996@item -mno-am33
10997@opindex mno-am33
10998Do not generate code which uses features specific to the AM33 processor. This
10999is the default.
11000
11001@item -mreturn-pointer-on-d0
11002@opindex mreturn-pointer-on-d0
11003When generating a function which returns a pointer, return the pointer
11004in both @code{a0} and @code{d0}. Otherwise, the pointer is returned
11005only in a0, and attempts to call such functions without a prototype
11006would result in errors. Note that this option is on by default; use
11007@option{-mno-return-pointer-on-d0} to disable it.
11008
11009@item -mno-crt0
11010@opindex mno-crt0
11011Do not link in the C run-time initialization object file.
11012
11013@item -mrelax
11014@opindex mrelax
11015Indicate to the linker that it should perform a relaxation optimization pass
11016to shorten branches, calls and absolute memory addresses. This option only
11017has an effect when used on the command line for the final link step.
11018
11019This option makes symbolic debugging impossible.
11020@end table
11021
11022@node MT Options
11023@subsection MT Options
11024@cindex MT options
11025
11026These @option{-m} options are defined for Morpho MT architectures:
11027
11028@table @gcctabopt
11029
11030@item -march=@var{cpu-type}
11031@opindex march
11032Generate code that will run on @var{cpu-type}, which is the name of a system
11033representing a certain processor type. Possible values for
11034@var{cpu-type} are @samp{ms1-64-001}, @samp{ms1-16-002},
11035@samp{ms1-16-003} and @samp{ms2}.
11036
11037When this option is not used, the default is @option{-march=ms1-16-002}.
11038
11039@item -mbacc
11040@opindex mbacc
11041Use byte loads and stores when generating code.
11042
11043@item -mno-bacc
11044@opindex mno-bacc
11045Do not use byte loads and stores when generating code.
11046
11047@item -msim
11048@opindex msim
11049Use simulator runtime
11050
11051@item -mno-crt0
11052@opindex mno-crt0
11053Do not link in the C run-time initialization object file
11054@file{crti.o}. Other run-time initialization and termination files
11055such as @file{startup.o} and @file{exit.o} are still included on the
11056linker command line.
11057
11058@end table
11059
11060@node PDP-11 Options
11061@subsection PDP-11 Options
11062@cindex PDP-11 Options
11063
11064These options are defined for the PDP-11:
11065
11066@table @gcctabopt
11067@item -mfpu
11068@opindex mfpu
11069Use hardware FPP floating point. This is the default. (FIS floating
11070point on the PDP-11/40 is not supported.)
11071
11072@item -msoft-float
11073@opindex msoft-float
11074Do not use hardware floating point.
11075
11076@item -mac0
11077@opindex mac0
11078Return floating-point results in ac0 (fr0 in Unix assembler syntax).
11079
11080@item -mno-ac0
11081@opindex mno-ac0
11082Return floating-point results in memory. This is the default.
11083
11084@item -m40
11085@opindex m40
11086Generate code for a PDP-11/40.
11087
11088@item -m45
11089@opindex m45
11090Generate code for a PDP-11/45. This is the default.
11091
11092@item -m10
11093@opindex m10
11094Generate code for a PDP-11/10.
11095
11096@item -mbcopy-builtin
11097@opindex bcopy-builtin
11098Use inline @code{movmemhi} patterns for copying memory. This is the
11099default.
11100
11101@item -mbcopy
11102@opindex mbcopy
11103Do not use inline @code{movmemhi} patterns for copying memory.
11104
11105@item -mint16
11106@itemx -mno-int32
11107@opindex mint16
11108@opindex mno-int32
11109Use 16-bit @code{int}. This is the default.
11110
11111@item -mint32
11112@itemx -mno-int16
11113@opindex mint32
11114@opindex mno-int16
11115Use 32-bit @code{int}.
11116
11117@item -mfloat64
11118@itemx -mno-float32
11119@opindex mfloat64
11120@opindex mno-float32
11121Use 64-bit @code{float}. This is the default.
11122
11123@item -mfloat32
11124@itemx -mno-float64
11125@opindex mfloat32
11126@opindex mno-float64
11127Use 32-bit @code{float}.
11128
11129@item -mabshi
11130@opindex mabshi
11131Use @code{abshi2} pattern. This is the default.
11132
11133@item -mno-abshi
11134@opindex mno-abshi
11135Do not use @code{abshi2} pattern.
11136
11137@item -mbranch-expensive
11138@opindex mbranch-expensive
11139Pretend that branches are expensive. This is for experimenting with
11140code generation only.
11141
11142@item -mbranch-cheap
11143@opindex mbranch-cheap
11144Do not pretend that branches are expensive. This is the default.
11145
11146@item -msplit
11147@opindex msplit
11148Generate code for a system with split I&D@.
11149
11150@item -mno-split
11151@opindex mno-split
11152Generate code for a system without split I&D@. This is the default.
11153
11154@item -munix-asm
11155@opindex munix-asm
11156Use Unix assembler syntax. This is the default when configured for
11157@samp{pdp11-*-bsd}.
11158
11159@item -mdec-asm
11160@opindex mdec-asm
11161Use DEC assembler syntax. This is the default when configured for any
11162PDP-11 target other than @samp{pdp11-*-bsd}.
11163@end table
11164
11165@node PowerPC Options
11166@subsection PowerPC Options
11167@cindex PowerPC options
11168
11169These are listed under @xref{RS/6000 and PowerPC Options}.
11170
11171@node RS/6000 and PowerPC Options
11172@subsection IBM RS/6000 and PowerPC Options
11173@cindex RS/6000 and PowerPC Options
11174@cindex IBM RS/6000 and PowerPC Options
11175
11176These @samp{-m} options are defined for the IBM RS/6000 and PowerPC:
11177@table @gcctabopt
11178@item -mpower
11179@itemx -mno-power
11180@itemx -mpower2
11181@itemx -mno-power2
11182@itemx -mpowerpc
11183@itemx -mno-powerpc
11184@itemx -mpowerpc-gpopt
11185@itemx -mno-powerpc-gpopt
11186@itemx -mpowerpc-gfxopt
11187@itemx -mno-powerpc-gfxopt
11188@itemx -mpowerpc64
11189@itemx -mno-powerpc64
11190@itemx -mmfcrf
11191@itemx -mno-mfcrf
11192@itemx -mpopcntb
11193@itemx -mno-popcntb
11194@itemx -mfprnd
11195@itemx -mno-fprnd
11196@opindex mpower
11197@opindex mno-power
11198@opindex mpower2
11199@opindex mno-power2
11200@opindex mpowerpc
11201@opindex mno-powerpc
11202@opindex mpowerpc-gpopt
11203@opindex mno-powerpc-gpopt
11204@opindex mpowerpc-gfxopt
11205@opindex mno-powerpc-gfxopt
11206@opindex mpowerpc64
11207@opindex mno-powerpc64
11208@opindex mmfcrf
11209@opindex mno-mfcrf
11210@opindex mpopcntb
11211@opindex mno-popcntb
11212@opindex mfprnd
11213@opindex mno-fprnd
11214GCC supports two related instruction set architectures for the
11215RS/6000 and PowerPC@. The @dfn{POWER} instruction set are those
11216instructions supported by the @samp{rios} chip set used in the original
11217RS/6000 systems and the @dfn{PowerPC} instruction set is the
11218architecture of the Freescale MPC5xx, MPC6xx, MPC8xx microprocessors, and
11219the IBM 4xx, 6xx, and follow-on microprocessors.
11220
11221Neither architecture is a subset of the other. However there is a
11222large common subset of instructions supported by both. An MQ
11223register is included in processors supporting the POWER architecture.
11224
11225You use these options to specify which instructions are available on the
11226processor you are using. The default value of these options is
11227determined when configuring GCC@. Specifying the
11228@option{-mcpu=@var{cpu_type}} overrides the specification of these
11229options. We recommend you use the @option{-mcpu=@var{cpu_type}} option
11230rather than the options listed above.
11231
11232The @option{-mpower} option allows GCC to generate instructions that
11233are found only in the POWER architecture and to use the MQ register.
11234Specifying @option{-mpower2} implies @option{-power} and also allows GCC
11235to generate instructions that are present in the POWER2 architecture but
11236not the original POWER architecture.
11237
11238The @option{-mpowerpc} option allows GCC to generate instructions that
11239are found only in the 32-bit subset of the PowerPC architecture.
11240Specifying @option{-mpowerpc-gpopt} implies @option{-mpowerpc} and also allows
11241GCC to use the optional PowerPC architecture instructions in the
11242General Purpose group, including floating-point square root. Specifying
11243@option{-mpowerpc-gfxopt} implies @option{-mpowerpc} and also allows GCC to
11244use the optional PowerPC architecture instructions in the Graphics
11245group, including floating-point select.
11246
11247The @option{-mmfcrf} option allows GCC to generate the move from
11248condition register field instruction implemented on the POWER4
11249processor and other processors that support the PowerPC V2.01
11250architecture.
11251The @option{-mpopcntb} option allows GCC to generate the popcount and
11252double precision FP reciprocal estimate instruction implemented on the
11253POWER5 processor and other processors that support the PowerPC V2.02
11254architecture.
11255The @option{-mfprnd} option allows GCC to generate the FP round to
11256integer instructions implemented on the POWER5+ processor and other
11257processors that support the PowerPC V2.03 architecture.
11258
11259The @option{-mpowerpc64} option allows GCC to generate the additional
1126064-bit instructions that are found in the full PowerPC64 architecture
11261and to treat GPRs as 64-bit, doubleword quantities. GCC defaults to
11262@option{-mno-powerpc64}.
11263
11264If you specify both @option{-mno-power} and @option{-mno-powerpc}, GCC
11265will use only the instructions in the common subset of both
11266architectures plus some special AIX common-mode calls, and will not use
11267the MQ register. Specifying both @option{-mpower} and @option{-mpowerpc}
11268permits GCC to use any instruction from either architecture and to
11269allow use of the MQ register; specify this for the Motorola MPC601.
11270
11271@item -mnew-mnemonics
11272@itemx -mold-mnemonics
11273@opindex mnew-mnemonics
11274@opindex mold-mnemonics
11275Select which mnemonics to use in the generated assembler code. With
11276@option{-mnew-mnemonics}, GCC uses the assembler mnemonics defined for
11277the PowerPC architecture. With @option{-mold-mnemonics} it uses the
11278assembler mnemonics defined for the POWER architecture. Instructions
11279defined in only one architecture have only one mnemonic; GCC uses that
11280mnemonic irrespective of which of these options is specified.
11281
11282GCC defaults to the mnemonics appropriate for the architecture in
11283use. Specifying @option{-mcpu=@var{cpu_type}} sometimes overrides the
11284value of these option. Unless you are building a cross-compiler, you
11285should normally not specify either @option{-mnew-mnemonics} or
11286@option{-mold-mnemonics}, but should instead accept the default.
11287
11288@item -mcpu=@var{cpu_type}
11289@opindex mcpu
11290Set architecture type, register usage, choice of mnemonics, and
11291instruction scheduling parameters for machine type @var{cpu_type}.
11292Supported values for @var{cpu_type} are @samp{401}, @samp{403},
11293@samp{405}, @samp{405fp}, @samp{440}, @samp{440fp}, @samp{505},
11294@samp{601}, @samp{602}, @samp{603}, @samp{603e}, @samp{604},
11295@samp{604e}, @samp{620}, @samp{630}, @samp{740}, @samp{7400},
11296@samp{7450}, @samp{750}, @samp{801}, @samp{821}, @samp{823},
11297@samp{860}, @samp{970}, @samp{8540}, @samp{ec603e}, @samp{G3},
11298@samp{G4}, @samp{G5}, @samp{power}, @samp{power2}, @samp{power3},
11299@samp{power4}, @samp{power5}, @samp{power5+}, @samp{power6},
11300@samp{common}, @samp{powerpc}, @samp{powerpc64},
11301@samp{rios}, @samp{rios1}, @samp{rios2}, @samp{rsc}, and @samp{rs64}.
11302
11303@option{-mcpu=common} selects a completely generic processor. Code
11304generated under this option will run on any POWER or PowerPC processor.
11305GCC will use only the instructions in the common subset of both
11306architectures, and will not use the MQ register. GCC assumes a generic
11307processor model for scheduling purposes.
11308
11309@option{-mcpu=power}, @option{-mcpu=power2}, @option{-mcpu=powerpc}, and
11310@option{-mcpu=powerpc64} specify generic POWER, POWER2, pure 32-bit
11311PowerPC (i.e., not MPC601), and 64-bit PowerPC architecture machine
11312types, with an appropriate, generic processor model assumed for
11313scheduling purposes.
11314
11315The other options specify a specific processor. Code generated under
11316those options will run best on that processor, and may not run at all on
11317others.
11318
11319The @option{-mcpu} options automatically enable or disable the
11320following options: @option{-maltivec}, @option{-mfprnd},
11321@option{-mhard-float}, @option{-mmfcrf}, @option{-mmultiple},
11322@option{-mnew-mnemonics}, @option{-mpopcntb}, @option{-mpower},
11323@option{-mpower2}, @option{-mpowerpc64}, @option{-mpowerpc-gpopt},
11324@option{-mpowerpc-gfxopt}, @option{-mstring}, @option{-mmulhw}, @option{-mdlmzb}.
11325The particular options
11326set for any particular CPU will vary between compiler versions,
11327depending on what setting seems to produce optimal code for that CPU;
11328it doesn't necessarily reflect the actual hardware's capabilities. If
11329you wish to set an individual option to a particular value, you may
11330specify it after the @option{-mcpu} option, like @samp{-mcpu=970
11331-mno-altivec}.
11332
11333On AIX, the @option{-maltivec} and @option{-mpowerpc64} options are
11334not enabled or disabled by the @option{-mcpu} option at present because
11335AIX does not have full support for these options. You may still
11336enable or disable them individually if you're sure it'll work in your
11337environment.
11338
11339@item -mtune=@var{cpu_type}
11340@opindex mtune
11341Set the instruction scheduling parameters for machine type
11342@var{cpu_type}, but do not set the architecture type, register usage, or
11343choice of mnemonics, as @option{-mcpu=@var{cpu_type}} would. The same
11344values for @var{cpu_type} are used for @option{-mtune} as for
11345@option{-mcpu}. If both are specified, the code generated will use the
11346architecture, registers, and mnemonics set by @option{-mcpu}, but the
11347scheduling parameters set by @option{-mtune}.
11348
11349@item -mswdiv
11350@itemx -mno-swdiv
11351@opindex mswdiv
11352@opindex mno-swdiv
11353Generate code to compute division as reciprocal estimate and iterative
11354refinement, creating opportunities for increased throughput. This
11355feature requires: optional PowerPC Graphics instruction set for single
11356precision and FRE instruction for double precision, assuming divides
11357cannot generate user-visible traps, and the domain values not include
11358Infinities, denormals or zero denominator.
11359
11360@item -maltivec
11361@itemx -mno-altivec
11362@opindex maltivec
11363@opindex mno-altivec
11364Generate code that uses (does not use) AltiVec instructions, and also
11365enable the use of built-in functions that allow more direct access to
11366the AltiVec instruction set. You may also need to set
11367@option{-mabi=altivec} to adjust the current ABI with AltiVec ABI
11368enhancements.
11369
11370@item -mvrsave
11371@item -mno-vrsave
11372@opindex mvrsave
11373@opindex mno-vrsave
11374Generate VRSAVE instructions when generating AltiVec code.
11375
11376@item -msecure-plt
11377@opindex msecure-plt
11378Generate code that allows ld and ld.so to build executables and shared
11379libraries with non-exec .plt and .got sections. This is a PowerPC
1138032-bit SYSV ABI option.
11381
11382@item -mbss-plt
11383@opindex mbss-plt
11384Generate code that uses a BSS .plt section that ld.so fills in, and
11385requires .plt and .got sections that are both writable and executable.
11386This is a PowerPC 32-bit SYSV ABI option.
11387
11388@item -misel
11389@itemx -mno-isel
11390@opindex misel
11391@opindex mno-isel
11392This switch enables or disables the generation of ISEL instructions.
11393
11394@item -misel=@var{yes/no}
11395This switch has been deprecated. Use @option{-misel} and
11396@option{-mno-isel} instead.
11397
11398@item -mspe
11399@itemx -mno-spe
11400@opindex mspe
11401@opindex mno-spe
11402This switch enables or disables the generation of SPE simd
11403instructions.
11404
11405@item -mspe=@var{yes/no}
11406This option has been deprecated. Use @option{-mspe} and
11407@option{-mno-spe} instead.
11408
11409@item -mfloat-gprs=@var{yes/single/double/no}
11410@itemx -mfloat-gprs
11411@opindex mfloat-gprs
11412This switch enables or disables the generation of floating point
11413operations on the general purpose registers for architectures that
11414support it.
11415
11416The argument @var{yes} or @var{single} enables the use of
11417single-precision floating point operations.
11418
11419The argument @var{double} enables the use of single and
11420double-precision floating point operations.
11421
11422The argument @var{no} disables floating point operations on the
11423general purpose registers.
11424
11425This option is currently only available on the MPC854x.
11426
11427@item -m32
11428@itemx -m64
11429@opindex m32
11430@opindex m64
11431Generate code for 32-bit or 64-bit environments of Darwin and SVR4
11432targets (including GNU/Linux). The 32-bit environment sets int, long
11433and pointer to 32 bits and generates code that runs on any PowerPC
11434variant. The 64-bit environment sets int to 32 bits and long and
11435pointer to 64 bits, and generates code for PowerPC64, as for
11436@option{-mpowerpc64}.
11437
11438@item -mfull-toc
11439@itemx -mno-fp-in-toc
11440@itemx -mno-sum-in-toc
11441@itemx -mminimal-toc
11442@opindex mfull-toc
11443@opindex mno-fp-in-toc
11444@opindex mno-sum-in-toc
11445@opindex mminimal-toc
11446Modify generation of the TOC (Table Of Contents), which is created for
11447every executable file. The @option{-mfull-toc} option is selected by
11448default. In that case, GCC will allocate at least one TOC entry for
11449each unique non-automatic variable reference in your program. GCC
11450will also place floating-point constants in the TOC@. However, only
1145116,384 entries are available in the TOC@.
11452
11453If you receive a linker error message that saying you have overflowed
11454the available TOC space, you can reduce the amount of TOC space used
11455with the @option{-mno-fp-in-toc} and @option{-mno-sum-in-toc} options.
11456@option{-mno-fp-in-toc} prevents GCC from putting floating-point
11457constants in the TOC and @option{-mno-sum-in-toc} forces GCC to
11458generate code to calculate the sum of an address and a constant at
11459run-time instead of putting that sum into the TOC@. You may specify one
11460or both of these options. Each causes GCC to produce very slightly
11461slower and larger code at the expense of conserving TOC space.
11462
11463If you still run out of space in the TOC even when you specify both of
11464these options, specify @option{-mminimal-toc} instead. This option causes
11465GCC to make only one TOC entry for every file. When you specify this
11466option, GCC will produce code that is slower and larger but which
11467uses extremely little TOC space. You may wish to use this option
11468only on files that contain less frequently executed code.
11469
11470@item -maix64
11471@itemx -maix32
11472@opindex maix64
11473@opindex maix32
11474Enable 64-bit AIX ABI and calling convention: 64-bit pointers, 64-bit
11475@code{long} type, and the infrastructure needed to support them.
11476Specifying @option{-maix64} implies @option{-mpowerpc64} and
11477@option{-mpowerpc}, while @option{-maix32} disables the 64-bit ABI and
11478implies @option{-mno-powerpc64}. GCC defaults to @option{-maix32}.
11479
11480@item -mxl-compat
11481@itemx -mno-xl-compat
11482@opindex mxl-compat
11483@opindex mno-xl-compat
11484Produce code that conforms more closely to IBM XL compiler semantics
11485when using AIX-compatible ABI. Pass floating-point arguments to
11486prototyped functions beyond the register save area (RSA) on the stack
11487in addition to argument FPRs. Do not assume that most significant
11488double in 128-bit long double value is properly rounded when comparing
11489values and converting to double. Use XL symbol names for long double
11490support routines.
11491
11492The AIX calling convention was extended but not initially documented to
11493handle an obscure K&R C case of calling a function that takes the
11494address of its arguments with fewer arguments than declared. IBM XL
11495compilers access floating point arguments which do not fit in the
11496RSA from the stack when a subroutine is compiled without
11497optimization. Because always storing floating-point arguments on the
11498stack is inefficient and rarely needed, this option is not enabled by
11499default and only is necessary when calling subroutines compiled by IBM
11500XL compilers without optimization.
11501
11502@item -mpe
11503@opindex mpe
11504Support @dfn{IBM RS/6000 SP} @dfn{Parallel Environment} (PE)@. Link an
11505application written to use message passing with special startup code to
11506enable the application to run. The system must have PE installed in the
11507standard location (@file{/usr/lpp/ppe.poe/}), or the @file{specs} file
11508must be overridden with the @option{-specs=} option to specify the
11509appropriate directory location. The Parallel Environment does not
11510support threads, so the @option{-mpe} option and the @option{-pthread}
11511option are incompatible.
11512
11513@item -malign-natural
11514@itemx -malign-power
11515@opindex malign-natural
11516@opindex malign-power
11517On AIX, 32-bit Darwin, and 64-bit PowerPC GNU/Linux, the option
11518@option{-malign-natural} overrides the ABI-defined alignment of larger
11519types, such as floating-point doubles, on their natural size-based boundary.
11520The option @option{-malign-power} instructs GCC to follow the ABI-specified
11521alignment rules. GCC defaults to the standard alignment defined in the ABI@.
11522
11523On 64-bit Darwin, natural alignment is the default, and @option{-malign-power}
11524is not supported.
11525
11526@item -msoft-float
11527@itemx -mhard-float
11528@opindex msoft-float
11529@opindex mhard-float
11530Generate code that does not use (uses) the floating-point register set.
11531Software floating point emulation is provided if you use the
11532@option{-msoft-float} option, and pass the option to GCC when linking.
11533
11534@item -mmultiple
11535@itemx -mno-multiple
11536@opindex mmultiple
11537@opindex mno-multiple
11538Generate code that uses (does not use) the load multiple word
11539instructions and the store multiple word instructions. These
11540instructions are generated by default on POWER systems, and not
11541generated on PowerPC systems. Do not use @option{-mmultiple} on little
11542endian PowerPC systems, since those instructions do not work when the
11543processor is in little endian mode. The exceptions are PPC740 and
11544PPC750 which permit the instructions usage in little endian mode.
11545
11546@item -mstring
11547@itemx -mno-string
11548@opindex mstring
11549@opindex mno-string
11550Generate code that uses (does not use) the load string instructions
11551and the store string word instructions to save multiple registers and
11552do small block moves. These instructions are generated by default on
11553POWER systems, and not generated on PowerPC systems. Do not use
11554@option{-mstring} on little endian PowerPC systems, since those
11555instructions do not work when the processor is in little endian mode.
11556The exceptions are PPC740 and PPC750 which permit the instructions
11557usage in little endian mode.
11558
11559@item -mupdate
11560@itemx -mno-update
11561@opindex mupdate
11562@opindex mno-update
11563Generate code that uses (does not use) the load or store instructions
11564that update the base register to the address of the calculated memory
11565location. These instructions are generated by default. If you use
11566@option{-mno-update}, there is a small window between the time that the
11567stack pointer is updated and the address of the previous frame is
11568stored, which means code that walks the stack frame across interrupts or
11569signals may get corrupted data.
11570
11571@item -mfused-madd
11572@itemx -mno-fused-madd
11573@opindex mfused-madd
11574@opindex mno-fused-madd
11575Generate code that uses (does not use) the floating point multiply and
11576accumulate instructions. These instructions are generated by default if
11577hardware floating is used.
11578
11579@item -mmulhw
11580@itemx -mno-mulhw
11581@opindex mmulhw
11582@opindex mno-mulhw
11583Generate code that uses (does not use) the half-word multiply and
11584multiply-accumulate instructions on the IBM 405 and 440 processors.
11585These instructions are generated by default when targetting those
11586processors.
11587
11588@item -mdlmzb
11589@itemx -mno-dlmzb
11590@opindex mdlmzb
11591@opindex mno-dlmzb
11592Generate code that uses (does not use) the string-search @samp{dlmzb}
11593instruction on the IBM 405 and 440 processors. This instruction is
11594generated by default when targetting those processors.
11595
11596@item -mno-bit-align
11597@itemx -mbit-align
11598@opindex mno-bit-align
11599@opindex mbit-align
11600On System V.4 and embedded PowerPC systems do not (do) force structures
11601and unions that contain bit-fields to be aligned to the base type of the
11602bit-field.
11603
11604For example, by default a structure containing nothing but 8
11605@code{unsigned} bit-fields of length 1 would be aligned to a 4 byte
11606boundary and have a size of 4 bytes. By using @option{-mno-bit-align},
11607the structure would be aligned to a 1 byte boundary and be one byte in
11608size.
11609
11610@item -mno-strict-align
11611@itemx -mstrict-align
11612@opindex mno-strict-align
11613@opindex mstrict-align
11614On System V.4 and embedded PowerPC systems do not (do) assume that
11615unaligned memory references will be handled by the system.
11616
11617@item -mrelocatable
11618@itemx -mno-relocatable
11619@opindex mrelocatable
11620@opindex mno-relocatable
11621On embedded PowerPC systems generate code that allows (does not allow)
11622the program to be relocated to a different address at runtime. If you
11623use @option{-mrelocatable} on any module, all objects linked together must
11624be compiled with @option{-mrelocatable} or @option{-mrelocatable-lib}.
11625
11626@item -mrelocatable-lib
11627@itemx -mno-relocatable-lib
11628@opindex mrelocatable-lib
11629@opindex mno-relocatable-lib
11630On embedded PowerPC systems generate code that allows (does not allow)
11631the program to be relocated to a different address at runtime. Modules
11632compiled with @option{-mrelocatable-lib} can be linked with either modules
11633compiled without @option{-mrelocatable} and @option{-mrelocatable-lib} or
11634with modules compiled with the @option{-mrelocatable} options.
11635
11636@item -mno-toc
11637@itemx -mtoc
11638@opindex mno-toc
11639@opindex mtoc
11640On System V.4 and embedded PowerPC systems do not (do) assume that
11641register 2 contains a pointer to a global area pointing to the addresses
11642used in the program.
11643
11644@item -mlittle
11645@itemx -mlittle-endian
11646@opindex mlittle
11647@opindex mlittle-endian
11648On System V.4 and embedded PowerPC systems compile code for the
11649processor in little endian mode. The @option{-mlittle-endian} option is
11650the same as @option{-mlittle}.
11651
11652@item -mbig
11653@itemx -mbig-endian
11654@opindex mbig
11655@opindex mbig-endian
11656On System V.4 and embedded PowerPC systems compile code for the
11657processor in big endian mode. The @option{-mbig-endian} option is
11658the same as @option{-mbig}.
11659
11660@item -mdynamic-no-pic
11661@opindex mdynamic-no-pic
11662On Darwin and Mac OS X systems, compile code so that it is not
11663relocatable, but that its external references are relocatable. The
11664resulting code is suitable for applications, but not shared
11665libraries.
11666
11667@item -mprioritize-restricted-insns=@var{priority}
11668@opindex mprioritize-restricted-insns
11669This option controls the priority that is assigned to
11670dispatch-slot restricted instructions during the second scheduling
11671pass. The argument @var{priority} takes the value @var{0/1/2} to assign
11672@var{no/highest/second-highest} priority to dispatch slot restricted
11673instructions.
11674
11675@item -msched-costly-dep=@var{dependence_type}
11676@opindex msched-costly-dep
11677This option controls which dependences are considered costly
11678by the target during instruction scheduling. The argument
11679@var{dependence_type} takes one of the following values:
11680@var{no}: no dependence is costly,
11681@var{all}: all dependences are costly,
11682@var{true_store_to_load}: a true dependence from store to load is costly,
11683@var{store_to_load}: any dependence from store to load is costly,
11684@var{number}: any dependence which latency >= @var{number} is costly.
11685
11686@item -minsert-sched-nops=@var{scheme}
11687@opindex minsert-sched-nops
11688This option controls which nop insertion scheme will be used during
11689the second scheduling pass. The argument @var{scheme} takes one of the
11690following values:
11691@var{no}: Don't insert nops.
11692@var{pad}: Pad with nops any dispatch group which has vacant issue slots,
11693according to the scheduler's grouping.
11694@var{regroup_exact}: Insert nops to force costly dependent insns into
11695separate groups. Insert exactly as many nops as needed to force an insn
11696to a new group, according to the estimated processor grouping.
11697@var{number}: Insert nops to force costly dependent insns into
11698separate groups. Insert @var{number} nops to force an insn to a new group.
11699
11700@item -mcall-sysv
11701@opindex mcall-sysv
11702On System V.4 and embedded PowerPC systems compile code using calling
11703conventions that adheres to the March 1995 draft of the System V
11704Application Binary Interface, PowerPC processor supplement. This is the
11705default unless you configured GCC using @samp{powerpc-*-eabiaix}.
11706
11707@item -mcall-sysv-eabi
11708@opindex mcall-sysv-eabi
11709Specify both @option{-mcall-sysv} and @option{-meabi} options.
11710
11711@item -mcall-sysv-noeabi
11712@opindex mcall-sysv-noeabi
11713Specify both @option{-mcall-sysv} and @option{-mno-eabi} options.
11714
11715@item -mcall-solaris
11716@opindex mcall-solaris
11717On System V.4 and embedded PowerPC systems compile code for the Solaris
11718operating system.
11719
11720@item -mcall-linux
11721@opindex mcall-linux
11722On System V.4 and embedded PowerPC systems compile code for the
11723Linux-based GNU system.
11724
11725@item -mcall-gnu
11726@opindex mcall-gnu
11727On System V.4 and embedded PowerPC systems compile code for the
11728Hurd-based GNU system.
11729
11730@item -mcall-netbsd
11731@opindex mcall-netbsd
11732On System V.4 and embedded PowerPC systems compile code for the
11733NetBSD operating system.
11734
11735@item -maix-struct-return
11736@opindex maix-struct-return
11737Return all structures in memory (as specified by the AIX ABI)@.
11738
11739@item -msvr4-struct-return
11740@opindex msvr4-struct-return
11741Return structures smaller than 8 bytes in registers (as specified by the
11742SVR4 ABI)@.
11743
11744@item -mabi=@var{abi-type}
11745@opindex mabi
11746Extend the current ABI with a particular extension, or remove such extension.
11747Valid values are @var{altivec}, @var{no-altivec}, @var{spe},
11748@var{no-spe}, @var{ibmlongdouble}, @var{ieeelongdouble}@.
11749
11750@item -mabi=spe
11751@opindex mabi=spe
11752Extend the current ABI with SPE ABI extensions. This does not change
11753the default ABI, instead it adds the SPE ABI extensions to the current
11754ABI@.
11755
11756@item -mabi=no-spe
11757@opindex mabi=no-spe
11758Disable Booke SPE ABI extensions for the current ABI@.
11759
11760@item -mabi=ibmlongdouble
11761@opindex mabi=ibmlongdouble
11762Change the current ABI to use IBM extended precision long double.
11763This is a PowerPC 32-bit SYSV ABI option.
11764
11765@item -mabi=ieeelongdouble
11766@opindex mabi=ieeelongdouble
11767Change the current ABI to use IEEE extended precision long double.
11768This is a PowerPC 32-bit Linux ABI option.
11769
11770@item -mprototype
11771@itemx -mno-prototype
11772@opindex mprototype
11773@opindex mno-prototype
11774On System V.4 and embedded PowerPC systems assume that all calls to
11775variable argument functions are properly prototyped. Otherwise, the
11776compiler must insert an instruction before every non prototyped call to
11777set or clear bit 6 of the condition code register (@var{CR}) to
11778indicate whether floating point values were passed in the floating point
11779registers in case the function takes a variable arguments. With
11780@option{-mprototype}, only calls to prototyped variable argument functions
11781will set or clear the bit.
11782
11783@item -msim
11784@opindex msim
11785On embedded PowerPC systems, assume that the startup module is called
11786@file{sim-crt0.o} and that the standard C libraries are @file{libsim.a} and
11787@file{libc.a}. This is the default for @samp{powerpc-*-eabisim}.
11788configurations.
11789
11790@item -mmvme
11791@opindex mmvme
11792On embedded PowerPC systems, assume that the startup module is called
11793@file{crt0.o} and the standard C libraries are @file{libmvme.a} and
11794@file{libc.a}.
11795
11796@item -mads
11797@opindex mads
11798On embedded PowerPC systems, assume that the startup module is called
11799@file{crt0.o} and the standard C libraries are @file{libads.a} and
11800@file{libc.a}.
11801
11802@item -myellowknife
11803@opindex myellowknife
11804On embedded PowerPC systems, assume that the startup module is called
11805@file{crt0.o} and the standard C libraries are @file{libyk.a} and
11806@file{libc.a}.
11807
11808@item -mvxworks
11809@opindex mvxworks
11810On System V.4 and embedded PowerPC systems, specify that you are
11811compiling for a VxWorks system.
11812
11813@item -mwindiss
11814@opindex mwindiss
11815Specify that you are compiling for the WindISS simulation environment.
11816
11817@item -memb
11818@opindex memb
11819On embedded PowerPC systems, set the @var{PPC_EMB} bit in the ELF flags
11820header to indicate that @samp{eabi} extended relocations are used.
11821
11822@item -meabi
11823@itemx -mno-eabi
11824@opindex meabi
11825@opindex mno-eabi
11826On System V.4 and embedded PowerPC systems do (do not) adhere to the
11827Embedded Applications Binary Interface (eabi) which is a set of
11828modifications to the System V.4 specifications. Selecting @option{-meabi}
11829means that the stack is aligned to an 8 byte boundary, a function
11830@code{__eabi} is called to from @code{main} to set up the eabi
11831environment, and the @option{-msdata} option can use both @code{r2} and
11832@code{r13} to point to two separate small data areas. Selecting
11833@option{-mno-eabi} means that the stack is aligned to a 16 byte boundary,
11834do not call an initialization function from @code{main}, and the
11835@option{-msdata} option will only use @code{r13} to point to a single
11836small data area. The @option{-meabi} option is on by default if you
11837configured GCC using one of the @samp{powerpc*-*-eabi*} options.
11838
11839@item -msdata=eabi
11840@opindex msdata=eabi
11841On System V.4 and embedded PowerPC systems, put small initialized
11842@code{const} global and static data in the @samp{.sdata2} section, which
11843is pointed to by register @code{r2}. Put small initialized
11844non-@code{const} global and static data in the @samp{.sdata} section,
11845which is pointed to by register @code{r13}. Put small uninitialized
11846global and static data in the @samp{.sbss} section, which is adjacent to
11847the @samp{.sdata} section. The @option{-msdata=eabi} option is
11848incompatible with the @option{-mrelocatable} option. The
11849@option{-msdata=eabi} option also sets the @option{-memb} option.
11850
11851@item -msdata=sysv
11852@opindex msdata=sysv
11853On System V.4 and embedded PowerPC systems, put small global and static
11854data in the @samp{.sdata} section, which is pointed to by register
11855@code{r13}. Put small uninitialized global and static data in the
11856@samp{.sbss} section, which is adjacent to the @samp{.sdata} section.
11857The @option{-msdata=sysv} option is incompatible with the
11858@option{-mrelocatable} option.
11859
11860@item -msdata=default
11861@itemx -msdata
11862@opindex msdata=default
11863@opindex msdata
11864On System V.4 and embedded PowerPC systems, if @option{-meabi} is used,
11865compile code the same as @option{-msdata=eabi}, otherwise compile code the
11866same as @option{-msdata=sysv}.
11867
11868@item -msdata-data
11869@opindex msdata-data
11870On System V.4 and embedded PowerPC systems, put small global
11871data in the @samp{.sdata} section. Put small uninitialized global
11872data in the @samp{.sbss} section. Do not use register @code{r13}
11873to address small data however. This is the default behavior unless
11874other @option{-msdata} options are used.
11875
11876@item -msdata=none
11877@itemx -mno-sdata
11878@opindex msdata=none
11879@opindex mno-sdata
11880On embedded PowerPC systems, put all initialized global and static data
11881in the @samp{.data} section, and all uninitialized data in the
11882@samp{.bss} section.
11883
11884@item -G @var{num}
11885@opindex G
11886@cindex smaller data references (PowerPC)
11887@cindex .sdata/.sdata2 references (PowerPC)
11888On embedded PowerPC systems, put global and static items less than or
11889equal to @var{num} bytes into the small data or bss sections instead of
11890the normal data or bss section. By default, @var{num} is 8. The
11891@option{-G @var{num}} switch is also passed to the linker.
11892All modules should be compiled with the same @option{-G @var{num}} value.
11893
11894@item -mregnames
11895@itemx -mno-regnames
11896@opindex mregnames
11897@opindex mno-regnames
11898On System V.4 and embedded PowerPC systems do (do not) emit register
11899names in the assembly language output using symbolic forms.
11900
11901@item -mlongcall
11902@itemx -mno-longcall
11903@opindex mlongcall
11904@opindex mno-longcall
11905By default assume that all calls are far away so that a longer more
11906expensive calling sequence is required. This is required for calls
11907further than 32 megabytes (33,554,432 bytes) from the current location.
11908A short call will be generated if the compiler knows
11909the call cannot be that far away. This setting can be overridden by
11910the @code{shortcall} function attribute, or by @code{#pragma
11911longcall(0)}.
11912
11913Some linkers are capable of detecting out-of-range calls and generating
11914glue code on the fly. On these systems, long calls are unnecessary and
11915generate slower code. As of this writing, the AIX linker can do this,
11916as can the GNU linker for PowerPC/64. It is planned to add this feature
11917to the GNU linker for 32-bit PowerPC systems as well.
11918
11919On Darwin/PPC systems, @code{#pragma longcall} will generate ``jbsr
11920callee, L42'', plus a ``branch island'' (glue code). The two target
11921addresses represent the callee and the ``branch island''. The
11922Darwin/PPC linker will prefer the first address and generate a ``bl
11923callee'' if the PPC ``bl'' instruction will reach the callee directly;
11924otherwise, the linker will generate ``bl L42'' to call the ``branch
11925island''. The ``branch island'' is appended to the body of the
11926calling function; it computes the full 32-bit address of the callee
11927and jumps to it.
11928
11929On Mach-O (Darwin) systems, this option directs the compiler emit to
11930the glue for every direct call, and the Darwin linker decides whether
11931to use or discard it.
11932
11933In the future, we may cause GCC to ignore all longcall specifications
11934when the linker is known to generate glue.
11935
11936@item -pthread
11937@opindex pthread
11938Adds support for multithreading with the @dfn{pthreads} library.
11939This option sets flags for both the preprocessor and linker.
11940
11941@end table
11942
11943@node S/390 and zSeries Options
11944@subsection S/390 and zSeries Options
11945@cindex S/390 and zSeries Options
11946
11947These are the @samp{-m} options defined for the S/390 and zSeries architecture.
11948
11949@table @gcctabopt
11950@item -mhard-float
11951@itemx -msoft-float
11952@opindex mhard-float
11953@opindex msoft-float
11954Use (do not use) the hardware floating-point instructions and registers
11955for floating-point operations. When @option{-msoft-float} is specified,
11956functions in @file{libgcc.a} will be used to perform floating-point
11957operations. When @option{-mhard-float} is specified, the compiler
11958generates IEEE floating-point instructions. This is the default.
11959
11960@item -mlong-double-64
11961@itemx -mlong-double-128
11962@opindex mlong-double-64
11963@opindex mlong-double-128
11964These switches control the size of @code{long double} type. A size
11965of 64bit makes the @code{long double} type equivalent to the @code{double}
11966type. This is the default.
11967
11968@item -mbackchain
11969@itemx -mno-backchain
11970@opindex mbackchain
11971@opindex mno-backchain
11972Store (do not store) the address of the caller's frame as backchain pointer
11973into the callee's stack frame.
11974A backchain may be needed to allow debugging using tools that do not understand
11975DWARF-2 call frame information.
11976When @option{-mno-packed-stack} is in effect, the backchain pointer is stored
11977at the bottom of the stack frame; when @option{-mpacked-stack} is in effect,
11978the backchain is placed into the topmost word of the 96/160 byte register
11979save area.
11980
11981In general, code compiled with @option{-mbackchain} is call-compatible with
11982code compiled with @option{-mmo-backchain}; however, use of the backchain
11983for debugging purposes usually requires that the whole binary is built with
11984@option{-mbackchain}. Note that the combination of @option{-mbackchain},
11985@option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
11986to build a linux kernel use @option{-msoft-float}.
11987
11988The default is to not maintain the backchain.
11989
11990@item -mpacked-stack
11991@item -mno-packed-stack
11992@opindex mpacked-stack
11993@opindex mno-packed-stack
11994Use (do not use) the packed stack layout. When @option{-mno-packed-stack} is
11995specified, the compiler uses the all fields of the 96/160 byte register save
11996area only for their default purpose; unused fields still take up stack space.
11997When @option{-mpacked-stack} is specified, register save slots are densely
11998packed at the top of the register save area; unused space is reused for other
11999purposes, allowing for more efficient use of the available stack space.
12000However, when @option{-mbackchain} is also in effect, the topmost word of
12001the save area is always used to store the backchain, and the return address
12002register is always saved two words below the backchain.
12003
12004As long as the stack frame backchain is not used, code generated with
12005@option{-mpacked-stack} is call-compatible with code generated with
12006@option{-mno-packed-stack}. Note that some non-FSF releases of GCC 2.95 for
12007S/390 or zSeries generated code that uses the stack frame backchain at run
12008time, not just for debugging purposes. Such code is not call-compatible
12009with code compiled with @option{-mpacked-stack}. Also, note that the
12010combination of @option{-mbackchain},
12011@option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
12012to build a linux kernel use @option{-msoft-float}.
12013
12014The default is to not use the packed stack layout.
12015
12016@item -msmall-exec
12017@itemx -mno-small-exec
12018@opindex msmall-exec
12019@opindex mno-small-exec
12020Generate (or do not generate) code using the @code{bras} instruction
12021to do subroutine calls.
12022This only works reliably if the total executable size does not
12023exceed 64k. The default is to use the @code{basr} instruction instead,
12024which does not have this limitation.
12025
12026@item -m64
12027@itemx -m31
12028@opindex m64
12029@opindex m31
12030When @option{-m31} is specified, generate code compliant to the
12031GNU/Linux for S/390 ABI@. When @option{-m64} is specified, generate
12032code compliant to the GNU/Linux for zSeries ABI@. This allows GCC in
12033particular to generate 64-bit instructions. For the @samp{s390}
12034targets, the default is @option{-m31}, while the @samp{s390x}
12035targets default to @option{-m64}.
12036
12037@item -mzarch
12038@itemx -mesa
12039@opindex mzarch
12040@opindex mesa
12041When @option{-mzarch} is specified, generate code using the
12042instructions available on z/Architecture.
12043When @option{-mesa} is specified, generate code using the
12044instructions available on ESA/390. Note that @option{-mesa} is
12045not possible with @option{-m64}.
12046When generating code compliant to the GNU/Linux for S/390 ABI,
12047the default is @option{-mesa}. When generating code compliant
12048to the GNU/Linux for zSeries ABI, the default is @option{-mzarch}.
12049
12050@item -mmvcle
12051@itemx -mno-mvcle
12052@opindex mmvcle
12053@opindex mno-mvcle
12054Generate (or do not generate) code using the @code{mvcle} instruction
12055to perform block moves. When @option{-mno-mvcle} is specified,
12056use a @code{mvc} loop instead. This is the default unless optimizing for
12057size.
12058
12059@item -mdebug
12060@itemx -mno-debug
12061@opindex mdebug
12062@opindex mno-debug
12063Print (or do not print) additional debug information when compiling.
12064The default is to not print debug information.
12065
12066@item -march=@var{cpu-type}
12067@opindex march
12068Generate code that will run on @var{cpu-type}, which is the name of a system
12069representing a certain processor type. Possible values for
12070@var{cpu-type} are @samp{g5}, @samp{g6}, @samp{z900}, and @samp{z990}.
12071When generating code using the instructions available on z/Architecture,
12072the default is @option{-march=z900}. Otherwise, the default is
12073@option{-march=g5}.
12074
12075@item -mtune=@var{cpu-type}
12076@opindex mtune
12077Tune to @var{cpu-type} everything applicable about the generated code,
12078except for the ABI and the set of available instructions.
12079The list of @var{cpu-type} values is the same as for @option{-march}.
12080The default is the value used for @option{-march}.
12081
12082@item -mtpf-trace
12083@itemx -mno-tpf-trace
12084@opindex mtpf-trace
12085@opindex mno-tpf-trace
12086Generate code that adds (does not add) in TPF OS specific branches to trace
12087routines in the operating system. This option is off by default, even
12088when compiling for the TPF OS@.
12089
12090@item -mfused-madd
12091@itemx -mno-fused-madd
12092@opindex mfused-madd
12093@opindex mno-fused-madd
12094Generate code that uses (does not use) the floating point multiply and
12095accumulate instructions. These instructions are generated by default if
12096hardware floating point is used.
12097
12098@item -mwarn-framesize=@var{framesize}
12099@opindex mwarn-framesize
12100Emit a warning if the current function exceeds the given frame size. Because
12101this is a compile time check it doesn't need to be a real problem when the program
12102runs. It is intended to identify functions which most probably cause
12103a stack overflow. It is useful to be used in an environment with limited stack
12104size e.g.@: the linux kernel.
12105
12106@item -mwarn-dynamicstack
12107@opindex mwarn-dynamicstack
12108Emit a warning if the function calls alloca or uses dynamically
12109sized arrays. This is generally a bad idea with a limited stack size.
12110
12111@item -mstack-guard=@var{stack-guard}
12112@item -mstack-size=@var{stack-size}
12113@opindex mstack-guard
12114@opindex mstack-size
12115These arguments always have to be used in conjunction. If they are present the s390
12116back end emits additional instructions in the function prologue which trigger a trap
12117if the stack size is @var{stack-guard} bytes above the @var{stack-size}
12118(remember that the stack on s390 grows downward). These options are intended to
12119be used to help debugging stack overflow problems. The additionally emitted code
12120causes only little overhead and hence can also be used in production like systems
12121without greater performance degradation. The given values have to be exact
12122powers of 2 and @var{stack-size} has to be greater than @var{stack-guard} without
12123exceeding 64k.
12124In order to be efficient the extra code makes the assumption that the stack starts
12125at an address aligned to the value given by @var{stack-size}.
12126@end table
12127
12128@node Score Options
12129@subsection Score Options
12130@cindex Score Options
12131
12132These options are defined for Score implementations:
12133
12134@table @gcctabopt
12135@item -meb
12136@opindex meb
12137Compile code for big endian mode. This is the default.
12138
12139@item -mel
12140@opindex mel
12141Compile code for little endian mode.
12142
12143@item -mnhwloop
12144@opindex mnhwloop
12145Disable generate bcnz instruction.
12146
12147@item -muls
12148@opindex muls
12149Enable generate unaligned load and store instruction.
12150
12151@item -mmac
12152@opindex mmac
12153Enable the use of multiply-accumulate instructions. Disabled by default.
12154
12155@item -mscore5
12156@opindex mscore5
12157Specify the SCORE5 as the target architecture.
12158
12159@item -mscore5u
12160@opindex mscore5u
12161Specify the SCORE5U of the target architecture.
12162
12163@item -mscore7
12164@opindex mscore7
12165Specify the SCORE7 as the target architecture. This is the default.
12166
12167@item -mscore7d
12168@opindex mscore7d
12169Specify the SCORE7D as the target architecture.
12170@end table
12171
12172@node SH Options
12173@subsection SH Options
12174
12175These @samp{-m} options are defined for the SH implementations:
12176
12177@table @gcctabopt
12178@item -m1
12179@opindex m1
12180Generate code for the SH1.
12181
12182@item -m2
12183@opindex m2
12184Generate code for the SH2.
12185
12186@item -m2e
12187Generate code for the SH2e.
12188
12189@item -m3
12190@opindex m3
12191Generate code for the SH3.
12192
12193@item -m3e
12194@opindex m3e
12195Generate code for the SH3e.
12196
12197@item -m4-nofpu
12198@opindex m4-nofpu
12199Generate code for the SH4 without a floating-point unit.
12200
12201@item -m4-single-only
12202@opindex m4-single-only
12203Generate code for the SH4 with a floating-point unit that only
12204supports single-precision arithmetic.
12205
12206@item -m4-single
12207@opindex m4-single
12208Generate code for the SH4 assuming the floating-point unit is in
12209single-precision mode by default.
12210
12211@item -m4
12212@opindex m4
12213Generate code for the SH4.
12214
12215@item -m4a-nofpu
12216@opindex m4a-nofpu
12217Generate code for the SH4al-dsp, or for a SH4a in such a way that the
12218floating-point unit is not used.
12219
12220@item -m4a-single-only
12221@opindex m4a-single-only
12222Generate code for the SH4a, in such a way that no double-precision
12223floating point operations are used.
12224
12225@item -m4a-single
12226@opindex m4a-single
12227Generate code for the SH4a assuming the floating-point unit is in
12228single-precision mode by default.
12229
12230@item -m4a
12231@opindex m4a
12232Generate code for the SH4a.
12233
12234@item -m4al
12235@opindex m4al
12236Same as @option{-m4a-nofpu}, except that it implicitly passes
12237@option{-dsp} to the assembler. GCC doesn't generate any DSP
12238instructions at the moment.
12239
12240@item -mb
12241@opindex mb
12242Compile code for the processor in big endian mode.
12243
12244@item -ml
12245@opindex ml
12246Compile code for the processor in little endian mode.
12247
12248@item -mdalign
12249@opindex mdalign
12250Align doubles at 64-bit boundaries. Note that this changes the calling
12251conventions, and thus some functions from the standard C library will
12252not work unless you recompile it first with @option{-mdalign}.
12253
12254@item -mrelax
12255@opindex mrelax
12256Shorten some address references at link time, when possible; uses the
12257linker option @option{-relax}.
12258
12259@item -mbigtable
12260@opindex mbigtable
12261Use 32-bit offsets in @code{switch} tables. The default is to use
1226216-bit offsets.
12263
12264@item -mfmovd
12265@opindex mfmovd
12266Enable the use of the instruction @code{fmovd}.
12267
12268@item -mhitachi
12269@opindex mhitachi
12270Comply with the calling conventions defined by Renesas.
12271
12272@item -mrenesas
12273@opindex mhitachi
12274Comply with the calling conventions defined by Renesas.
12275
12276@item -mno-renesas
12277@opindex mhitachi
12278Comply with the calling conventions defined for GCC before the Renesas
12279conventions were available. This option is the default for all
12280targets of the SH toolchain except for @samp{sh-symbianelf}.
12281
12282@item -mnomacsave
12283@opindex mnomacsave
12284Mark the @code{MAC} register as call-clobbered, even if
12285@option{-mhitachi} is given.
12286
12287@item -mieee
12288@opindex mieee
12289Increase IEEE-compliance of floating-point code.
12290At the moment, this is equivalent to @option{-fno-finite-math-only}.
12291When generating 16 bit SH opcodes, getting IEEE-conforming results for
12292comparisons of NANs / infinities incurs extra overhead in every
12293floating point comparison, therefore the default is set to
12294@option{-ffinite-math-only}.
12295
12296@item -misize
12297@opindex misize
12298Dump instruction size and location in the assembly code.
12299
12300@item -mpadstruct
12301@opindex mpadstruct
12302This option is deprecated. It pads structures to multiple of 4 bytes,
12303which is incompatible with the SH ABI@.
12304
12305@item -mspace
12306@opindex mspace
12307Optimize for space instead of speed. Implied by @option{-Os}.
12308
12309@item -mprefergot
12310@opindex mprefergot
12311When generating position-independent code, emit function calls using
12312the Global Offset Table instead of the Procedure Linkage Table.
12313
12314@item -musermode
12315@opindex musermode
12316Generate a library function call to invalidate instruction cache
12317entries, after fixing up a trampoline. This library function call
12318doesn't assume it can write to the whole memory address space. This
12319is the default when the target is @code{sh-*-linux*}.
12320
12321@item -multcost=@var{number}
12322@opindex multcost=@var{number}
12323Set the cost to assume for a multiply insn.
12324
12325@item -mdiv=@var{strategy}
12326@opindex mdiv=@var{strategy}
12327Set the division strategy to use for SHmedia code. @var{strategy} must be
12328one of: call, call2, fp, inv, inv:minlat, inv20u, inv20l, inv:call,
12329inv:call2, inv:fp .
12330"fp" performs the operation in floating point. This has a very high latency,
12331but needs only a few instructions, so it might be a good choice if
12332your code has enough easily exploitable ILP to allow the compiler to
12333schedule the floating point instructions together with other instructions.
12334Division by zero causes a floating point exception.
12335"inv" uses integer operations to calculate the inverse of the divisor,
12336and then multiplies the dividend with the inverse. This strategy allows
12337cse and hoisting of the inverse calculation. Division by zero calculates
12338an unspecified result, but does not trap.
12339"inv:minlat" is a variant of "inv" where if no cse / hoisting opportunities
12340have been found, or if the entire operation has been hoisted to the same
12341place, the last stages of the inverse calculation are intertwined with the
12342final multiply to reduce the overall latency, at the expense of using a few
12343more instructions, and thus offering fewer scheduling opportunities with
12344other code.
12345"call" calls a library function that usually implements the inv:minlat
12346strategy.
12347This gives high code density for m5-*media-nofpu compilations.
12348"call2" uses a different entry point of the same library function, where it
12349assumes that a pointer to a lookup table has already been set up, which
12350exposes the pointer load to cse / code hoisting optimizations.
12351"inv:call", "inv:call2" and "inv:fp" all use the "inv" algorithm for initial
12352code generation, but if the code stays unoptimized, revert to the "call",
12353"call2", or "fp" strategies, respectively. Note that the
12354potentially-trapping side effect of division by zero is carried by a
12355separate instruction, so it is possible that all the integer instructions
12356are hoisted out, but the marker for the side effect stays where it is.
12357A recombination to fp operations or a call is not possible in that case.
12358"inv20u" and "inv20l" are variants of the "inv:minlat" strategy. In the case
12359that the inverse calculation was nor separated from the multiply, they speed
12360up division where the dividend fits into 20 bits (plus sign where applicable),
12361by inserting a test to skip a number of operations in this case; this test
12362slows down the case of larger dividends. inv20u assumes the case of a such
12363a small dividend to be unlikely, and inv20l assumes it to be likely.
12364
12365@item -mdivsi3_libfunc=@var{name}
12366@opindex mdivsi3_libfunc=@var{name}
12367Set the name of the library function used for 32 bit signed division to
12368@var{name}. This only affect the name used in the call and inv:call
12369division strategies, and the compiler will still expect the same
12370sets of input/output/clobbered registers as if this option was not present.
12371
12372@item -madjust-unroll
12373@opindex madjust-unroll
12374Throttle unrolling to avoid thrashing target registers.
12375This option only has an effect if the gcc code base supports the
12376TARGET_ADJUST_UNROLL_MAX target hook.
12377
12378@item -mindexed-addressing
12379@opindex mindexed-addressing
12380Enable the use of the indexed addressing mode for SHmedia32/SHcompact.
12381This is only safe if the hardware and/or OS implement 32 bit wrap-around
12382semantics for the indexed addressing mode. The architecture allows the
12383implementation of processors with 64 bit MMU, which the OS could use to
12384get 32 bit addressing, but since no current hardware implementation supports
12385this or any other way to make the indexed addressing mode safe to use in
12386the 32 bit ABI, the default is -mno-indexed-addressing.
12387
12388@item -mgettrcost=@var{number}
12389@opindex mgettrcost=@var{number}
12390Set the cost assumed for the gettr instruction to @var{number}.
12391The default is 2 if @option{-mpt-fixed} is in effect, 100 otherwise.
12392
12393@item -mpt-fixed
12394@opindex mpt-fixed
12395Assume pt* instructions won't trap. This will generally generate better
12396scheduled code, but is unsafe on current hardware. The current architecture
12397definition says that ptabs and ptrel trap when the target anded with 3 is 3.
12398This has the unintentional effect of making it unsafe to schedule ptabs /
12399ptrel before a branch, or hoist it out of a loop. For example,
12400__do_global_ctors, a part of libgcc that runs constructors at program
12401startup, calls functions in a list which is delimited by -1. With the
12402-mpt-fixed option, the ptabs will be done before testing against -1.
12403That means that all the constructors will be run a bit quicker, but when
12404the loop comes to the end of the list, the program crashes because ptabs
12405loads -1 into a target register. Since this option is unsafe for any
12406hardware implementing the current architecture specification, the default
12407is -mno-pt-fixed. Unless the user specifies a specific cost with
12408@option{-mgettrcost}, -mno-pt-fixed also implies @option{-mgettrcost=100};
12409this deters register allocation using target registers for storing
12410ordinary integers.
12411
12412@item -minvalid-symbols
12413@opindex minvalid-symbols
12414Assume symbols might be invalid. Ordinary function symbols generated by
12415the compiler will always be valid to load with movi/shori/ptabs or
12416movi/shori/ptrel, but with assembler and/or linker tricks it is possible
12417to generate symbols that will cause ptabs / ptrel to trap.
12418This option is only meaningful when @option{-mno-pt-fixed} is in effect.
12419It will then prevent cross-basic-block cse, hoisting and most scheduling
12420of symbol loads. The default is @option{-mno-invalid-symbols}.
12421@end table
12422
12423@node SPARC Options
12424@subsection SPARC Options
12425@cindex SPARC options
12426
12427These @samp{-m} options are supported on the SPARC:
12428
12429@table @gcctabopt
12430@item -mno-app-regs
12431@itemx -mapp-regs
12432@opindex mno-app-regs
12433@opindex mapp-regs
12434Specify @option{-mapp-regs} to generate output using the global registers
124352 through 4, which the SPARC SVR4 ABI reserves for applications. This
12436is the default.
12437
12438To be fully SVR4 ABI compliant at the cost of some performance loss,
12439specify @option{-mno-app-regs}. You should compile libraries and system
12440software with this option.
12441
12442@item -mfpu
12443@itemx -mhard-float
12444@opindex mfpu
12445@opindex mhard-float
12446Generate output containing floating point instructions. This is the
12447default.
12448
12449@item -mno-fpu
12450@itemx -msoft-float
12451@opindex mno-fpu
12452@opindex msoft-float
12453Generate output containing library calls for floating point.
12454@strong{Warning:} the requisite libraries are not available for all SPARC
12455targets. Normally the facilities of the machine's usual C compiler are
12456used, but this cannot be done directly in cross-compilation. You must make
12457your own arrangements to provide suitable library functions for
12458cross-compilation. The embedded targets @samp{sparc-*-aout} and
12459@samp{sparclite-*-*} do provide software floating point support.
12460
12461@option{-msoft-float} changes the calling convention in the output file;
12462therefore, it is only useful if you compile @emph{all} of a program with
12463this option. In particular, you need to compile @file{libgcc.a}, the
12464library that comes with GCC, with @option{-msoft-float} in order for
12465this to work.
12466
12467@item -mhard-quad-float
12468@opindex mhard-quad-float
12469Generate output containing quad-word (long double) floating point
12470instructions.
12471
12472@item -msoft-quad-float
12473@opindex msoft-quad-float
12474Generate output containing library calls for quad-word (long double)
12475floating point instructions. The functions called are those specified
12476in the SPARC ABI@. This is the default.
12477
12478As of this writing, there are no SPARC implementations that have hardware
12479support for the quad-word floating point instructions. They all invoke
12480a trap handler for one of these instructions, and then the trap handler
12481emulates the effect of the instruction. Because of the trap handler overhead,
12482this is much slower than calling the ABI library routines. Thus the
12483@option{-msoft-quad-float} option is the default.
12484
12485@item -mno-unaligned-doubles
12486@itemx -munaligned-doubles
12487@opindex mno-unaligned-doubles
12488@opindex munaligned-doubles
12489Assume that doubles have 8 byte alignment. This is the default.
12490
12491With @option{-munaligned-doubles}, GCC assumes that doubles have 8 byte
12492alignment only if they are contained in another type, or if they have an
12493absolute address. Otherwise, it assumes they have 4 byte alignment.
12494Specifying this option avoids some rare compatibility problems with code
12495generated by other compilers. It is not the default because it results
12496in a performance loss, especially for floating point code.
12497
12498@item -mno-faster-structs
12499@itemx -mfaster-structs
12500@opindex mno-faster-structs
12501@opindex mfaster-structs
12502With @option{-mfaster-structs}, the compiler assumes that structures
12503should have 8 byte alignment. This enables the use of pairs of
12504@code{ldd} and @code{std} instructions for copies in structure
12505assignment, in place of twice as many @code{ld} and @code{st} pairs.
12506However, the use of this changed alignment directly violates the SPARC
12507ABI@. Thus, it's intended only for use on targets where the developer
12508acknowledges that their resulting code will not be directly in line with
12509the rules of the ABI@.
12510
12511@item -mimpure-text
12512@opindex mimpure-text
12513@option{-mimpure-text}, used in addition to @option{-shared}, tells
12514the compiler to not pass @option{-z text} to the linker when linking a
12515shared object. Using this option, you can link position-dependent
12516code into a shared object.
12517
12518@option{-mimpure-text} suppresses the ``relocations remain against
12519allocatable but non-writable sections'' linker error message.
12520However, the necessary relocations will trigger copy-on-write, and the
12521shared object is not actually shared across processes. Instead of
12522using @option{-mimpure-text}, you should compile all source code with
12523@option{-fpic} or @option{-fPIC}.
12524
12525This option is only available on SunOS and Solaris.
12526
12527@item -mcpu=@var{cpu_type}
12528@opindex mcpu
12529Set the instruction set, register set, and instruction scheduling parameters
12530for machine type @var{cpu_type}. Supported values for @var{cpu_type} are
12531@samp{v7}, @samp{cypress}, @samp{v8}, @samp{supersparc}, @samp{sparclite},
12532@samp{f930}, @samp{f934}, @samp{hypersparc}, @samp{sparclite86x},
12533@samp{sparclet}, @samp{tsc701}, @samp{v9}, @samp{ultrasparc},
12534@samp{ultrasparc3}, and @samp{niagara}.
12535
12536Default instruction scheduling parameters are used for values that select
12537an architecture and not an implementation. These are @samp{v7}, @samp{v8},
12538@samp{sparclite}, @samp{sparclet}, @samp{v9}.
12539
12540Here is a list of each supported architecture and their supported
12541implementations.
12542
12543@smallexample
12544 v7: cypress
12545 v8: supersparc, hypersparc
12546 sparclite: f930, f934, sparclite86x
12547 sparclet: tsc701
12548 v9: ultrasparc, ultrasparc3, niagara
12549@end smallexample
12550
12551By default (unless configured otherwise), GCC generates code for the V7
12552variant of the SPARC architecture. With @option{-mcpu=cypress}, the compiler
12553additionally optimizes it for the Cypress CY7C602 chip, as used in the
12554SPARCStation/SPARCServer 3xx series. This is also appropriate for the older
12555SPARCStation 1, 2, IPX etc.
12556
12557With @option{-mcpu=v8}, GCC generates code for the V8 variant of the SPARC
12558architecture. The only difference from V7 code is that the compiler emits
12559the integer multiply and integer divide instructions which exist in SPARC-V8
12560but not in SPARC-V7. With @option{-mcpu=supersparc}, the compiler additionally
12561optimizes it for the SuperSPARC chip, as used in the SPARCStation 10, 1000 and
125622000 series.
12563
12564With @option{-mcpu=sparclite}, GCC generates code for the SPARClite variant of
12565the SPARC architecture. This adds the integer multiply, integer divide step
12566and scan (@code{ffs}) instructions which exist in SPARClite but not in SPARC-V7.
12567With @option{-mcpu=f930}, the compiler additionally optimizes it for the
12568Fujitsu MB86930 chip, which is the original SPARClite, with no FPU@. With
12569@option{-mcpu=f934}, the compiler additionally optimizes it for the Fujitsu
12570MB86934 chip, which is the more recent SPARClite with FPU@.
12571
12572With @option{-mcpu=sparclet}, GCC generates code for the SPARClet variant of
12573the SPARC architecture. This adds the integer multiply, multiply/accumulate,
12574integer divide step and scan (@code{ffs}) instructions which exist in SPARClet
12575but not in SPARC-V7. With @option{-mcpu=tsc701}, the compiler additionally
12576optimizes it for the TEMIC SPARClet chip.
12577
12578With @option{-mcpu=v9}, GCC generates code for the V9 variant of the SPARC
12579architecture. This adds 64-bit integer and floating-point move instructions,
125803 additional floating-point condition code registers and conditional move
12581instructions. With @option{-mcpu=ultrasparc}, the compiler additionally
12582optimizes it for the Sun UltraSPARC I/II/IIi chips. With
12583@option{-mcpu=ultrasparc3}, the compiler additionally optimizes it for the
12584Sun UltraSPARC III/III+/IIIi/IIIi+/IV/IV+ chips. With
12585@option{-mcpu=niagara}, the compiler additionally optimizes it for
12586Sun UltraSPARC T1 chips.
12587
12588@item -mtune=@var{cpu_type}
12589@opindex mtune
12590Set the instruction scheduling parameters for machine type
12591@var{cpu_type}, but do not set the instruction set or register set that the
12592option @option{-mcpu=@var{cpu_type}} would.
12593
12594The same values for @option{-mcpu=@var{cpu_type}} can be used for
12595@option{-mtune=@var{cpu_type}}, but the only useful values are those
12596that select a particular cpu implementation. Those are @samp{cypress},
12597@samp{supersparc}, @samp{hypersparc}, @samp{f930}, @samp{f934},
12598@samp{sparclite86x}, @samp{tsc701}, @samp{ultrasparc},
12599@samp{ultrasparc3}, and @samp{niagara}.
12600
12601@item -mv8plus
12602@itemx -mno-v8plus
12603@opindex mv8plus
12604@opindex mno-v8plus
12605With @option{-mv8plus}, GCC generates code for the SPARC-V8+ ABI@. The
12606difference from the V8 ABI is that the global and out registers are
12607considered 64-bit wide. This is enabled by default on Solaris in 32-bit
12608mode for all SPARC-V9 processors.
12609
12610@item -mvis
12611@itemx -mno-vis
12612@opindex mvis
12613@opindex mno-vis
12614With @option{-mvis}, GCC generates code that takes advantage of the UltraSPARC
12615Visual Instruction Set extensions. The default is @option{-mno-vis}.
12616@end table
12617
12618These @samp{-m} options are supported in addition to the above
12619on SPARC-V9 processors in 64-bit environments:
12620
12621@table @gcctabopt
12622@item -mlittle-endian
12623@opindex mlittle-endian
12624Generate code for a processor running in little-endian mode. It is only
12625available for a few configurations and most notably not on Solaris and Linux.
12626
12627@item -m32
12628@itemx -m64
12629@opindex m32
12630@opindex m64
12631Generate code for a 32-bit or 64-bit environment.
12632The 32-bit environment sets int, long and pointer to 32 bits.
12633The 64-bit environment sets int to 32 bits and long and pointer
12634to 64 bits.
12635
12636@item -mcmodel=medlow
12637@opindex mcmodel=medlow
12638Generate code for the Medium/Low code model: 64-bit addresses, programs
12639must be linked in the low 32 bits of memory. Programs can be statically
12640or dynamically linked.
12641
12642@item -mcmodel=medmid
12643@opindex mcmodel=medmid
12644Generate code for the Medium/Middle code model: 64-bit addresses, programs
12645must be linked in the low 44 bits of memory, the text and data segments must
12646be less than 2GB in size and the data segment must be located within 2GB of
12647the text segment.
12648
12649@item -mcmodel=medany
12650@opindex mcmodel=medany
12651Generate code for the Medium/Anywhere code model: 64-bit addresses, programs
12652may be linked anywhere in memory, the text and data segments must be less
12653than 2GB in size and the data segment must be located within 2GB of the
12654text segment.
12655
12656@item -mcmodel=embmedany
12657@opindex mcmodel=embmedany
12658Generate code for the Medium/Anywhere code model for embedded systems:
1265964-bit addresses, the text and data segments must be less than 2GB in
12660size, both starting anywhere in memory (determined at link time). The
12661global register %g4 points to the base of the data segment. Programs
12662are statically linked and PIC is not supported.
12663
12664@item -mstack-bias
12665@itemx -mno-stack-bias
12666@opindex mstack-bias
12667@opindex mno-stack-bias
12668With @option{-mstack-bias}, GCC assumes that the stack pointer, and
12669frame pointer if present, are offset by @minus{}2047 which must be added back
12670when making stack frame references. This is the default in 64-bit mode.
12671Otherwise, assume no such offset is present.
12672@end table
12673
12674These switches are supported in addition to the above on Solaris:
12675
12676@table @gcctabopt
12677@item -threads
12678@opindex threads
12679Add support for multithreading using the Solaris threads library. This
12680option sets flags for both the preprocessor and linker. This option does
12681not affect the thread safety of object code produced by the compiler or
12682that of libraries supplied with it.
12683
12684@item -pthreads
12685@opindex pthreads
12686Add support for multithreading using the POSIX threads library. This
12687option sets flags for both the preprocessor and linker. This option does
12688not affect the thread safety of object code produced by the compiler or
12689that of libraries supplied with it.
12690
12691@item -pthread
12692@opindex pthread
12693This is a synonym for @option{-pthreads}.
12694@end table
12695
12696@node System V Options
12697@subsection Options for System V
12698
12699These additional options are available on System V Release 4 for
12700compatibility with other compilers on those systems:
12701
12702@table @gcctabopt
12703@item -G
12704@opindex G
12705Create a shared object.
12706It is recommended that @option{-symbolic} or @option{-shared} be used instead.
12707
12708@item -Qy
12709@opindex Qy
12710Identify the versions of each tool used by the compiler, in a
12711@code{.ident} assembler directive in the output.
12712
12713@item -Qn
12714@opindex Qn
12715Refrain from adding @code{.ident} directives to the output file (this is
12716the default).
12717
12718@item -YP,@var{dirs}
12719@opindex YP
12720Search the directories @var{dirs}, and no others, for libraries
12721specified with @option{-l}.
12722
12723@item -Ym,@var{dir}
12724@opindex Ym
12725Look in the directory @var{dir} to find the M4 preprocessor.
12726The assembler uses this option.
12727@c This is supposed to go with a -Yd for predefined M4 macro files, but
12728@c the generic assembler that comes with Solaris takes just -Ym.
12729@end table
12730
12731@node TMS320C3x/C4x Options
12732@subsection TMS320C3x/C4x Options
12733@cindex TMS320C3x/C4x Options
12734
12735These @samp{-m} options are defined for TMS320C3x/C4x implementations:
12736
12737@table @gcctabopt
12738
12739@item -mcpu=@var{cpu_type}
12740@opindex mcpu
12741Set the instruction set, register set, and instruction scheduling
12742parameters for machine type @var{cpu_type}. Supported values for
12743@var{cpu_type} are @samp{c30}, @samp{c31}, @samp{c32}, @samp{c40}, and
12744@samp{c44}. The default is @samp{c40} to generate code for the
12745TMS320C40.
12746
12747@item -mbig-memory
12748@itemx -mbig
12749@itemx -msmall-memory
12750@itemx -msmall
12751@opindex mbig-memory
12752@opindex mbig
12753@opindex msmall-memory
12754@opindex msmall
12755Generates code for the big or small memory model. The small memory
12756model assumed that all data fits into one 64K word page. At run-time
12757the data page (DP) register must be set to point to the 64K page
12758containing the .bss and .data program sections. The big memory model is
12759the default and requires reloading of the DP register for every direct
12760memory access.
12761
12762@item -mbk
12763@itemx -mno-bk
12764@opindex mbk
12765@opindex mno-bk
12766Allow (disallow) allocation of general integer operands into the block
12767count register BK@.
12768
12769@item -mdb
12770@itemx -mno-db
12771@opindex mdb
12772@opindex mno-db
12773Enable (disable) generation of code using decrement and branch,
12774DBcond(D), instructions. This is enabled by default for the C4x. To be
12775on the safe side, this is disabled for the C3x, since the maximum
12776iteration count on the C3x is @math{2^{23} + 1} (but who iterates loops more than
12777@math{2^{23}} times on the C3x?). Note that GCC will try to reverse a loop so
12778that it can utilize the decrement and branch instruction, but will give
12779up if there is more than one memory reference in the loop. Thus a loop
12780where the loop counter is decremented can generate slightly more
12781efficient code, in cases where the RPTB instruction cannot be utilized.
12782
12783@item -mdp-isr-reload
12784@itemx -mparanoid
12785@opindex mdp-isr-reload
12786@opindex mparanoid
12787Force the DP register to be saved on entry to an interrupt service
12788routine (ISR), reloaded to point to the data section, and restored on
12789exit from the ISR@. This should not be required unless someone has
12790violated the small memory model by modifying the DP register, say within
12791an object library.
12792
12793@item -mmpyi
12794@itemx -mno-mpyi
12795@opindex mmpyi
12796@opindex mno-mpyi
12797For the C3x use the 24-bit MPYI instruction for integer multiplies
12798instead of a library call to guarantee 32-bit results. Note that if one
12799of the operands is a constant, then the multiplication will be performed
12800using shifts and adds. If the @option{-mmpyi} option is not specified for the C3x,
12801then squaring operations are performed inline instead of a library call.
12802
12803@item -mfast-fix
12804@itemx -mno-fast-fix
12805@opindex mfast-fix
12806@opindex mno-fast-fix
12807The C3x/C4x FIX instruction to convert a floating point value to an
12808integer value chooses the nearest integer less than or equal to the
12809floating point value rather than to the nearest integer. Thus if the
12810floating point number is negative, the result will be incorrectly
12811truncated an additional code is necessary to detect and correct this
12812case. This option can be used to disable generation of the additional
12813code required to correct the result.
12814
12815@item -mrptb
12816@itemx -mno-rptb
12817@opindex mrptb
12818@opindex mno-rptb
12819Enable (disable) generation of repeat block sequences using the RPTB
12820instruction for zero overhead looping. The RPTB construct is only used
12821for innermost loops that do not call functions or jump across the loop
12822boundaries. There is no advantage having nested RPTB loops due to the
12823overhead required to save and restore the RC, RS, and RE registers.
12824This is enabled by default with @option{-O2}.
12825
12826@item -mrpts=@var{count}
12827@itemx -mno-rpts
12828@opindex mrpts
12829@opindex mno-rpts
12830Enable (disable) the use of the single instruction repeat instruction
12831RPTS@. If a repeat block contains a single instruction, and the loop
12832count can be guaranteed to be less than the value @var{count}, GCC will
12833emit a RPTS instruction instead of a RPTB@. If no value is specified,
12834then a RPTS will be emitted even if the loop count cannot be determined
12835at compile time. Note that the repeated instruction following RPTS does
12836not have to be reloaded from memory each iteration, thus freeing up the
12837CPU buses for operands. However, since interrupts are blocked by this
12838instruction, it is disabled by default.
12839
12840@item -mloop-unsigned
12841@itemx -mno-loop-unsigned
12842@opindex mloop-unsigned
12843@opindex mno-loop-unsigned
12844The maximum iteration count when using RPTS and RPTB (and DB on the C40)
12845is @math{2^{31} + 1} since these instructions test if the iteration count is
12846negative to terminate the loop. If the iteration count is unsigned
12847there is a possibility than the @math{2^{31} + 1} maximum iteration count may be
12848exceeded. This switch allows an unsigned iteration count.
12849
12850@item -mti
12851@opindex mti
12852Try to emit an assembler syntax that the TI assembler (asm30) is happy
12853with. This also enforces compatibility with the API employed by the TI
12854C3x C compiler. For example, long doubles are passed as structures
12855rather than in floating point registers.
12856
12857@item -mregparm
12858@itemx -mmemparm
12859@opindex mregparm
12860@opindex mmemparm
12861Generate code that uses registers (stack) for passing arguments to functions.
12862By default, arguments are passed in registers where possible rather
12863than by pushing arguments on to the stack.
12864
12865@item -mparallel-insns
12866@itemx -mno-parallel-insns
12867@opindex mparallel-insns
12868@opindex mno-parallel-insns
12869Allow the generation of parallel instructions. This is enabled by
12870default with @option{-O2}.
12871
12872@item -mparallel-mpy
12873@itemx -mno-parallel-mpy
12874@opindex mparallel-mpy
12875@opindex mno-parallel-mpy
12876Allow the generation of MPY||ADD and MPY||SUB parallel instructions,
12877provided @option{-mparallel-insns} is also specified. These instructions have
12878tight register constraints which can pessimize the code generation
12879of large functions.
12880
12881@end table
12882
12883@node V850 Options
12884@subsection V850 Options
12885@cindex V850 Options
12886
12887These @samp{-m} options are defined for V850 implementations:
12888
12889@table @gcctabopt
12890@item -mlong-calls
12891@itemx -mno-long-calls
12892@opindex mlong-calls
12893@opindex mno-long-calls
12894Treat all calls as being far away (near). If calls are assumed to be
12895far away, the compiler will always load the functions address up into a
12896register, and call indirect through the pointer.
12897
12898@item -mno-ep
12899@itemx -mep
12900@opindex mno-ep
12901@opindex mep
12902Do not optimize (do optimize) basic blocks that use the same index
12903pointer 4 or more times to copy pointer into the @code{ep} register, and
12904use the shorter @code{sld} and @code{sst} instructions. The @option{-mep}
12905option is on by default if you optimize.
12906
12907@item -mno-prolog-function
12908@itemx -mprolog-function
12909@opindex mno-prolog-function
12910@opindex mprolog-function
12911Do not use (do use) external functions to save and restore registers
12912at the prologue and epilogue of a function. The external functions
12913are slower, but use less code space if more than one function saves
12914the same number of registers. The @option{-mprolog-function} option
12915is on by default if you optimize.
12916
12917@item -mspace
12918@opindex mspace
12919Try to make the code as small as possible. At present, this just turns
12920on the @option{-mep} and @option{-mprolog-function} options.
12921
12922@item -mtda=@var{n}
12923@opindex mtda
12924Put static or global variables whose size is @var{n} bytes or less into
12925the tiny data area that register @code{ep} points to. The tiny data
12926area can hold up to 256 bytes in total (128 bytes for byte references).
12927
12928@item -msda=@var{n}
12929@opindex msda
12930Put static or global variables whose size is @var{n} bytes or less into
12931the small data area that register @code{gp} points to. The small data
12932area can hold up to 64 kilobytes.
12933
12934@item -mzda=@var{n}
12935@opindex mzda
12936Put static or global variables whose size is @var{n} bytes or less into
12937the first 32 kilobytes of memory.
12938
12939@item -mv850
12940@opindex mv850
12941Specify that the target processor is the V850.
12942
12943@item -mbig-switch
12944@opindex mbig-switch
12945Generate code suitable for big switch tables. Use this option only if
12946the assembler/linker complain about out of range branches within a switch
12947table.
12948
12949@item -mapp-regs
12950@opindex mapp-regs
12951This option will cause r2 and r5 to be used in the code generated by
12952the compiler. This setting is the default.
12953
12954@item -mno-app-regs
12955@opindex mno-app-regs
12956This option will cause r2 and r5 to be treated as fixed registers.
12957
12958@item -mv850e1
12959@opindex mv850e1
12960Specify that the target processor is the V850E1. The preprocessor
12961constants @samp{__v850e1__} and @samp{__v850e__} will be defined if
12962this option is used.
12963
12964@item -mv850e
12965@opindex mv850e
12966Specify that the target processor is the V850E@. The preprocessor
12967constant @samp{__v850e__} will be defined if this option is used.
12968
12969If neither @option{-mv850} nor @option{-mv850e} nor @option{-mv850e1}
12970are defined then a default target processor will be chosen and the
12971relevant @samp{__v850*__} preprocessor constant will be defined.
12972
12973The preprocessor constants @samp{__v850} and @samp{__v851__} are always
12974defined, regardless of which processor variant is the target.
12975
12976@item -mdisable-callt
12977@opindex mdisable-callt
12978This option will suppress generation of the CALLT instruction for the
12979v850e and v850e1 flavors of the v850 architecture. The default is
12980@option{-mno-disable-callt} which allows the CALLT instruction to be used.
12981
12982@end table
12983
12984@node VAX Options
12985@subsection VAX Options
12986@cindex VAX options
12987
12988These @samp{-m} options are defined for the VAX:
12989
12990@table @gcctabopt
12991@item -munix
12992@opindex munix
12993Do not output certain jump instructions (@code{aobleq} and so on)
12994that the Unix assembler for the VAX cannot handle across long
12995ranges.
12996
12997@item -mgnu
12998@opindex mgnu
12999Do output those jump instructions, on the assumption that you
13000will assemble with the GNU assembler.
13001
13002@item -mg
13003@opindex mg
13004Output code for g-format floating point numbers instead of d-format.
13005@end table
13006
13007@node x86-64 Options
13008@subsection x86-64 Options
13009@cindex x86-64 options
13010
13011These are listed under @xref{i386 and x86-64 Options}.
13012
13013@node Xstormy16 Options
13014@subsection Xstormy16 Options
13015@cindex Xstormy16 Options
13016
13017These options are defined for Xstormy16:
13018
13019@table @gcctabopt
13020@item -msim
13021@opindex msim
13022Choose startup files and linker script suitable for the simulator.
13023@end table
13024
13025@node Xtensa Options
13026@subsection Xtensa Options
13027@cindex Xtensa Options
13028
13029These options are supported for Xtensa targets:
13030
13031@table @gcctabopt
13032@item -mconst16
13033@itemx -mno-const16
13034@opindex mconst16
13035@opindex mno-const16
13036Enable or disable use of @code{CONST16} instructions for loading
13037constant values. The @code{CONST16} instruction is currently not a
13038standard option from Tensilica. When enabled, @code{CONST16}
13039instructions are always used in place of the standard @code{L32R}
13040instructions. The use of @code{CONST16} is enabled by default only if
13041the @code{L32R} instruction is not available.
13042
13043@item -mfused-madd
13044@itemx -mno-fused-madd
13045@opindex mfused-madd
13046@opindex mno-fused-madd
13047Enable or disable use of fused multiply/add and multiply/subtract
13048instructions in the floating-point option. This has no effect if the
13049floating-point option is not also enabled. Disabling fused multiply/add
13050and multiply/subtract instructions forces the compiler to use separate
13051instructions for the multiply and add/subtract operations. This may be
13052desirable in some cases where strict IEEE 754-compliant results are
13053required: the fused multiply add/subtract instructions do not round the
13054intermediate result, thereby producing results with @emph{more} bits of
13055precision than specified by the IEEE standard. Disabling fused multiply
13056add/subtract instructions also ensures that the program output is not
13057sensitive to the compiler's ability to combine multiply and add/subtract
13058operations.
13059
13060@item -mtext-section-literals
13061@itemx -mno-text-section-literals
13062@opindex mtext-section-literals
13063@opindex mno-text-section-literals
13064Control the treatment of literal pools. The default is
13065@option{-mno-text-section-literals}, which places literals in a separate
13066section in the output file. This allows the literal pool to be placed
13067in a data RAM/ROM, and it also allows the linker to combine literal
13068pools from separate object files to remove redundant literals and
13069improve code size. With @option{-mtext-section-literals}, the literals
13070are interspersed in the text section in order to keep them as close as
13071possible to their references. This may be necessary for large assembly
13072files.
13073
13074@item -mtarget-align
13075@itemx -mno-target-align
13076@opindex mtarget-align
13077@opindex mno-target-align
13078When this option is enabled, GCC instructs the assembler to
13079automatically align instructions to reduce branch penalties at the
13080expense of some code density. The assembler attempts to widen density
13081instructions to align branch targets and the instructions following call
13082instructions. If there are not enough preceding safe density
13083instructions to align a target, no widening will be performed. The
13084default is @option{-mtarget-align}. These options do not affect the
13085treatment of auto-aligned instructions like @code{LOOP}, which the
13086assembler will always align, either by widening density instructions or
13087by inserting no-op instructions.
13088
13089@item -mlongcalls
13090@itemx -mno-longcalls
13091@opindex mlongcalls
13092@opindex mno-longcalls
13093When this option is enabled, GCC instructs the assembler to translate
13094direct calls to indirect calls unless it can determine that the target
13095of a direct call is in the range allowed by the call instruction. This
13096translation typically occurs for calls to functions in other source
13097files. Specifically, the assembler translates a direct @code{CALL}
13098instruction into an @code{L32R} followed by a @code{CALLX} instruction.
13099The default is @option{-mno-longcalls}. This option should be used in
13100programs where the call target can potentially be out of range. This
13101option is implemented in the assembler, not the compiler, so the
13102assembly code generated by GCC will still show direct call
13103instructions---look at the disassembled object code to see the actual
13104instructions. Note that the assembler will use an indirect call for
13105every cross-file call, not just those that really will be out of range.
13106@end table
13107
13108@node zSeries Options
13109@subsection zSeries Options
13110@cindex zSeries options
13111
13112These are listed under @xref{S/390 and zSeries Options}.
13113
13114@node Code Gen Options
13115@section Options for Code Generation Conventions
13116@cindex code generation conventions
13117@cindex options, code generation
13118@cindex run-time options
13119
13120These machine-independent options control the interface conventions
13121used in code generation.
13122
13123Most of them have both positive and negative forms; the negative form
13124of @option{-ffoo} would be @option{-fno-foo}. In the table below, only
13125one of the forms is listed---the one which is not the default. You
13126can figure out the other form by either removing @samp{no-} or adding
13127it.
13128
13129@table @gcctabopt
13130@item -fbounds-check
13131@opindex fbounds-check
13132For front-ends that support it, generate additional code to check that
13133indices used to access arrays are within the declared range. This is
13134currently only supported by the Java and Fortran front-ends, where
13135this option defaults to true and false respectively.
13136
13137@item -ftrapv
13138@opindex ftrapv
13139This option generates traps for signed overflow on addition, subtraction,
13140multiplication operations.
13141
13142@item -fwrapv
13143@opindex fwrapv
13144This option instructs the compiler to assume that signed arithmetic
13145overflow of addition, subtraction and multiplication wraps around
13146using twos-complement representation. This flag enables some optimizations
13147and disables others. This option is enabled by default for the Java
13148front-end, as required by the Java language specification.
13149
13150@item -fexceptions
13151@opindex fexceptions
13152Enable exception handling. Generates extra code needed to propagate
13153exceptions. For some targets, this implies GCC will generate frame
13154unwind information for all functions, which can produce significant data
13155size overhead, although it does not affect execution. If you do not
13156specify this option, GCC will enable it by default for languages like
13157C++ which normally require exception handling, and disable it for
13158languages like C that do not normally require it. However, you may need
13159to enable this option when compiling C code that needs to interoperate
13160properly with exception handlers written in C++. You may also wish to
13161disable this option if you are compiling older C++ programs that don't
13162use exception handling.
13163
13164@item -fnon-call-exceptions
13165@opindex fnon-call-exceptions
13166Generate code that allows trapping instructions to throw exceptions.
13167Note that this requires platform-specific runtime support that does
13168not exist everywhere. Moreover, it only allows @emph{trapping}
13169instructions to throw exceptions, i.e.@: memory references or floating
13170point instructions. It does not allow exceptions to be thrown from
13171arbitrary signal handlers such as @code{SIGALRM}.
13172
13173@item -funwind-tables
13174@opindex funwind-tables
13175Similar to @option{-fexceptions}, except that it will just generate any needed
13176static data, but will not affect the generated code in any other way.
13177You will normally not enable this option; instead, a language processor
13178that needs this handling would enable it on your behalf.
13179
13180@item -fasynchronous-unwind-tables
13181@opindex fasynchronous-unwind-tables
13182Generate unwind table in dwarf2 format, if supported by target machine. The
13183table is exact at each instruction boundary, so it can be used for stack
13184unwinding from asynchronous events (such as debugger or garbage collector).
13185
13186@item -fpcc-struct-return
13187@opindex fpcc-struct-return
13188Return ``short'' @code{struct} and @code{union} values in memory like
13189longer ones, rather than in registers. This convention is less
13190efficient, but it has the advantage of allowing intercallability between
13191GCC-compiled files and files compiled with other compilers, particularly
13192the Portable C Compiler (pcc).
13193
13194The precise convention for returning structures in memory depends
13195on the target configuration macros.
13196
13197Short structures and unions are those whose size and alignment match
13198that of some integer type.
13199
13200@strong{Warning:} code compiled with the @option{-fpcc-struct-return}
13201switch is not binary compatible with code compiled with the
13202@option{-freg-struct-return} switch.
13203Use it to conform to a non-default application binary interface.
13204
13205@item -freg-struct-return
13206@opindex freg-struct-return
13207Return @code{struct} and @code{union} values in registers when possible.
13208This is more efficient for small structures than
13209@option{-fpcc-struct-return}.
13210
13211If you specify neither @option{-fpcc-struct-return} nor
13212@option{-freg-struct-return}, GCC defaults to whichever convention is
13213standard for the target. If there is no standard convention, GCC
13214defaults to @option{-fpcc-struct-return}, except on targets where GCC is
13215the principal compiler. In those cases, we can choose the standard, and
13216we chose the more efficient register return alternative.
13217
13218@strong{Warning:} code compiled with the @option{-freg-struct-return}
13219switch is not binary compatible with code compiled with the
13220@option{-fpcc-struct-return} switch.
13221Use it to conform to a non-default application binary interface.
13222
13223@item -fshort-enums
13224@opindex fshort-enums
13225Allocate to an @code{enum} type only as many bytes as it needs for the
13226declared range of possible values. Specifically, the @code{enum} type
13227will be equivalent to the smallest integer type which has enough room.
13228
13229@strong{Warning:} the @option{-fshort-enums} switch causes GCC to generate
13230code that is not binary compatible with code generated without that switch.
13231Use it to conform to a non-default application binary interface.
13232
13233@item -fshort-double
13234@opindex fshort-double
13235Use the same size for @code{double} as for @code{float}.
13236
13237@strong{Warning:} the @option{-fshort-double} switch causes GCC to generate
13238code that is not binary compatible with code generated without that switch.
13239Use it to conform to a non-default application binary interface.
13240
13241@item -fshort-wchar
13242@opindex fshort-wchar
13243Override the underlying type for @samp{wchar_t} to be @samp{short
13244unsigned int} instead of the default for the target. This option is
13245useful for building programs to run under WINE@.
13246
13247@strong{Warning:} the @option{-fshort-wchar} switch causes GCC to generate
13248code that is not binary compatible with code generated without that switch.
13249Use it to conform to a non-default application binary interface.
13250
13251@item -fno-common
13252@opindex fno-common
13253In C, allocate even uninitialized global variables in the data section of the
13254object file, rather than generating them as common blocks. This has the
13255effect that if the same variable is declared (without @code{extern}) in
13256two different compilations, you will get an error when you link them.
13257The only reason this might be useful is if you wish to verify that the
13258program will work on other systems which always work this way.
13259
13260@item -fno-ident
13261@opindex fno-ident
13262Ignore the @samp{#ident} directive.
13263
13264@item -finhibit-size-directive
13265@opindex finhibit-size-directive
13266Don't output a @code{.size} assembler directive, or anything else that
13267would cause trouble if the function is split in the middle, and the
13268two halves are placed at locations far apart in memory. This option is
13269used when compiling @file{crtstuff.c}; you should not need to use it
13270for anything else.
13271
13272@item -fverbose-asm
13273@opindex fverbose-asm
13274Put extra commentary information in the generated assembly code to
13275make it more readable. This option is generally only of use to those
13276who actually need to read the generated assembly code (perhaps while
13277debugging the compiler itself).
13278
13279@option{-fno-verbose-asm}, the default, causes the
13280extra information to be omitted and is useful when comparing two assembler
13281files.
13282
13283@item -fpic
13284@opindex fpic
13285@cindex global offset table
13286@cindex PIC
13287Generate position-independent code (PIC) suitable for use in a shared
13288library, if supported for the target machine. Such code accesses all
13289constant addresses through a global offset table (GOT)@. The dynamic
13290loader resolves the GOT entries when the program starts (the dynamic
13291loader is not part of GCC; it is part of the operating system). If
13292the GOT size for the linked executable exceeds a machine-specific
13293maximum size, you get an error message from the linker indicating that
13294@option{-fpic} does not work; in that case, recompile with @option{-fPIC}
13295instead. (These maximums are 8k on the SPARC and 32k
13296on the m68k and RS/6000. The 386 has no such limit.)
13297
13298Position-independent code requires special support, and therefore works
13299only on certain machines. For the 386, GCC supports PIC for System V
13300but not for the Sun 386i. Code generated for the IBM RS/6000 is always
13301position-independent.
13302
13303When this flag is set, the macros @code{__pic__} and @code{__PIC__}
13304are defined to 1.
13305
13306@item -fPIC
13307@opindex fPIC
13308If supported for the target machine, emit position-independent code,
13309suitable for dynamic linking and avoiding any limit on the size of the
13310global offset table. This option makes a difference on the m68k,
13311PowerPC and SPARC@.
13312
13313Position-independent code requires special support, and therefore works
13314only on certain machines.
13315
13316When this flag is set, the macros @code{__pic__} and @code{__PIC__}
13317are defined to 2.
13318
13319@item -fpie
13320@itemx -fPIE
13321@opindex fpie
13322@opindex fPIE
13323These options are similar to @option{-fpic} and @option{-fPIC}, but
13324generated position independent code can be only linked into executables.
13325Usually these options are used when @option{-pie} GCC option will be
13326used during linking.
13327
13328@item -fno-jump-tables
13329@opindex fno-jump-tables
13330Do not use jump tables for switch statements even where it would be
13331more efficient than other code generation strategies. This option is
13332of use in conjunction with @option{-fpic} or @option{-fPIC} for
13333building code which forms part of a dynamic linker and cannot
13334reference the address of a jump table. On some targets, jump tables
13335do not require a GOT and this option is not needed.
13336
13337@item -ffixed-@var{reg}
13338@opindex ffixed
13339Treat the register named @var{reg} as a fixed register; generated code
13340should never refer to it (except perhaps as a stack pointer, frame
13341pointer or in some other fixed role).
13342
13343@var{reg} must be the name of a register. The register names accepted
13344are machine-specific and are defined in the @code{REGISTER_NAMES}
13345macro in the machine description macro file.
13346
13347This flag does not have a negative form, because it specifies a
13348three-way choice.
13349
13350@item -fcall-used-@var{reg}
13351@opindex fcall-used
13352Treat the register named @var{reg} as an allocable register that is
13353clobbered by function calls. It may be allocated for temporaries or
13354variables that do not live across a call. Functions compiled this way
13355will not save and restore the register @var{reg}.
13356
13357It is an error to used this flag with the frame pointer or stack pointer.
13358Use of this flag for other registers that have fixed pervasive roles in
13359the machine's execution model will produce disastrous results.
13360
13361This flag does not have a negative form, because it specifies a
13362three-way choice.
13363
13364@item -fcall-saved-@var{reg}
13365@opindex fcall-saved
13366Treat the register named @var{reg} as an allocable register saved by
13367functions. It may be allocated even for temporaries or variables that
13368live across a call. Functions compiled this way will save and restore
13369the register @var{reg} if they use it.
13370
13371It is an error to used this flag with the frame pointer or stack pointer.
13372Use of this flag for other registers that have fixed pervasive roles in
13373the machine's execution model will produce disastrous results.
13374
13375A different sort of disaster will result from the use of this flag for
13376a register in which function values may be returned.
13377
13378This flag does not have a negative form, because it specifies a
13379three-way choice.
13380
13381@item -fpack-struct[=@var{n}]
13382@opindex fpack-struct
13383Without a value specified, pack all structure members together without
13384holes. When a value is specified (which must be a small power of two), pack
13385structure members according to this value, representing the maximum
13386alignment (that is, objects with default alignment requirements larger than
13387this will be output potentially unaligned at the next fitting location.
13388
13389@strong{Warning:} the @option{-fpack-struct} switch causes GCC to generate
13390code that is not binary compatible with code generated without that switch.
13391Additionally, it makes the code suboptimal.
13392Use it to conform to a non-default application binary interface.
13393
13394@item -finstrument-functions
13395@opindex finstrument-functions
13396Generate instrumentation calls for entry and exit to functions. Just
13397after function entry and just before function exit, the following
13398profiling functions will be called with the address of the current
13399function and its call site. (On some platforms,
13400@code{__builtin_return_address} does not work beyond the current
13401function, so the call site information may not be available to the
13402profiling functions otherwise.)
13403
13404@smallexample
13405void __cyg_profile_func_enter (void *this_fn,
13406 void *call_site);
13407void __cyg_profile_func_exit (void *this_fn,
13408 void *call_site);
13409@end smallexample
13410
13411The first argument is the address of the start of the current function,
13412which may be looked up exactly in the symbol table.
13413
13414This instrumentation is also done for functions expanded inline in other
13415functions. The profiling calls will indicate where, conceptually, the
13416inline function is entered and exited. This means that addressable
13417versions of such functions must be available. If all your uses of a
13418function are expanded inline, this may mean an additional expansion of
13419code size. If you use @samp{extern inline} in your C code, an
13420addressable version of such functions must be provided. (This is
13421normally the case anyways, but if you get lucky and the optimizer always
13422expands the functions inline, you might have gotten away without
13423providing static copies.)
13424
13425A function may be given the attribute @code{no_instrument_function}, in
13426which case this instrumentation will not be done. This can be used, for
13427example, for the profiling functions listed above, high-priority
13428interrupt routines, and any functions from which the profiling functions
13429cannot safely be called (perhaps signal handlers, if the profiling
13430routines generate output or allocate memory).
13431
13432@item -finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{}
13433@opindex finstrument-functions-exclude-file-list
13434
13435Set the list of functions that are excluded from instrumentation (see
13436the description of @code{-finstrument-functions}). If the file that
13437contains a function definition matches with one of @var{file}, then
13438that function is not instrumented. The match is done on substrings:
13439if the @var{file} parameter is a substring of the file name, it is
13440considered to be a match.
13441
13442For example,
13443@code{-finstrument-functions-exclude-file-list=/bits/stl,include/sys}
13444will exclude any inline function defined in files whose pathnames
13445contain @code{/bits/stl} or @code{include/sys}.
13446
13447If, for some reason, you want to include letter @code{','} in one of
13448@var{sym}, write @code{'\,'}. For example,
13449@code{-finstrument-functions-exclude-file-list='\,\,tmp'}
13450(note the single quote surrounding the option).
13451
13452@item -finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{}
13453@opindex finstrument-functions-exclude-function-list
13454
13455This is similar to @code{-finstrument-functions-exclude-file-list},
13456but this option sets the list of function names to be excluded from
13457instrumentation. The function name to be matched is its user-visible
13458name, such as @code{vector<int> blah(const vector<int> &)}, not the
13459internal mangled name (e.g., @code{_Z4blahRSt6vectorIiSaIiEE}). The
13460match is done on substrings: if the @var{sym} parameter is a substring
13461of the function name, it is considered to be a match.
13462
13463@item -fstack-check
13464@opindex fstack-check
13465Generate code to verify that you do not go beyond the boundary of the
13466stack. You should specify this flag if you are running in an
13467environment with multiple threads, but only rarely need to specify it in
13468a single-threaded environment since stack overflow is automatically
13469detected on nearly all systems if there is only one stack.
13470
13471Note that this switch does not actually cause checking to be done; the
13472operating system must do that. The switch causes generation of code
13473to ensure that the operating system sees the stack being extended.
13474
13475@item -fstack-limit-register=@var{reg}
13476@itemx -fstack-limit-symbol=@var{sym}
13477@itemx -fno-stack-limit
13478@opindex fstack-limit-register
13479@opindex fstack-limit-symbol
13480@opindex fno-stack-limit
13481Generate code to ensure that the stack does not grow beyond a certain value,
13482either the value of a register or the address of a symbol. If the stack
13483would grow beyond the value, a signal is raised. For most targets,
13484the signal is raised before the stack overruns the boundary, so
13485it is possible to catch the signal without taking special precautions.
13486
13487For instance, if the stack starts at absolute address @samp{0x80000000}
13488and grows downwards, you can use the flags
13489@option{-fstack-limit-symbol=__stack_limit} and
13490@option{-Wl,--defsym,__stack_limit=0x7ffe0000} to enforce a stack limit
13491of 128KB@. Note that this may only work with the GNU linker.
13492
13493@cindex aliasing of parameters
13494@cindex parameters, aliased
13495@item -fargument-alias
13496@itemx -fargument-noalias
13497@itemx -fargument-noalias-global
13498@itemx -fargument-noalias-anything
13499@opindex fargument-alias
13500@opindex fargument-noalias
13501@opindex fargument-noalias-global
13502@opindex fargument-noalias-anything
13503Specify the possible relationships among parameters and between
13504parameters and global data.
13505
13506@option{-fargument-alias} specifies that arguments (parameters) may
13507alias each other and may alias global storage.@*
13508@option{-fargument-noalias} specifies that arguments do not alias
13509each other, but may alias global storage.@*
13510@option{-fargument-noalias-global} specifies that arguments do not
13511alias each other and do not alias global storage.
13512@option{-fargument-noalias-anything} specifies that arguments do not
13513alias any other storage.
13514
13515Each language will automatically use whatever option is required by
13516the language standard. You should not need to use these options yourself.
13517
13518@item -fleading-underscore
13519@opindex fleading-underscore
13520This option and its counterpart, @option{-fno-leading-underscore}, forcibly
13521change the way C symbols are represented in the object file. One use
13522is to help link with legacy assembly code.
13523
13524@strong{Warning:} the @option{-fleading-underscore} switch causes GCC to
13525generate code that is not binary compatible with code generated without that
13526switch. Use it to conform to a non-default application binary interface.
13527Not all targets provide complete support for this switch.
13528
13529@item -ftls-model=@var{model}
13530Alter the thread-local storage model to be used (@pxref{Thread-Local}).
13531The @var{model} argument should be one of @code{global-dynamic},
13532@code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
13533
13534The default without @option{-fpic} is @code{initial-exec}; with
13535@option{-fpic} the default is @code{global-dynamic}.
13536
13537@item -fvisibility=@var{default|internal|hidden|protected}
13538@opindex fvisibility
13539Set the default ELF image symbol visibility to the specified option---all
13540symbols will be marked with this unless overridden within the code.
13541Using this feature can very substantially improve linking and
13542load times of shared object libraries, produce more optimized
13543code, provide near-perfect API export and prevent symbol clashes.
13544It is @strong{strongly} recommended that you use this in any shared objects
13545you distribute.
13546
13547Despite the nomenclature, @code{default} always means public ie;
13548available to be linked against from outside the shared object.
13549@code{protected} and @code{internal} are pretty useless in real-world
13550usage so the only other commonly used option will be @code{hidden}.
13551The default if @option{-fvisibility} isn't specified is
13552@code{default}, i.e., make every
13553symbol public---this causes the same behavior as previous versions of
13554GCC@.
13555
13556A good explanation of the benefits offered by ensuring ELF
13557symbols have the correct visibility is given by ``How To Write
13558Shared Libraries'' by Ulrich Drepper (which can be found at
13559@w{@uref{http://people.redhat.com/~drepper/}})---however a superior
13560solution made possible by this option to marking things hidden when
13561the default is public is to make the default hidden and mark things
13562public. This is the norm with DLL's on Windows and with @option{-fvisibility=hidden}
13563and @code{__attribute__ ((visibility("default")))} instead of
13564@code{__declspec(dllexport)} you get almost identical semantics with
13565identical syntax. This is a great boon to those working with
13566cross-platform projects.
13567
13568For those adding visibility support to existing code, you may find
13569@samp{#pragma GCC visibility} of use. This works by you enclosing
13570the declarations you wish to set visibility for with (for example)
13571@samp{#pragma GCC visibility push(hidden)} and
13572@samp{#pragma GCC visibility pop}.
13573Bear in mind that symbol visibility should be viewed @strong{as
13574part of the API interface contract} and thus all new code should
13575always specify visibility when it is not the default ie; declarations
13576only for use within the local DSO should @strong{always} be marked explicitly
13577as hidden as so to avoid PLT indirection overheads---making this
13578abundantly clear also aids readability and self-documentation of the code.
13579Note that due to ISO C++ specification requirements, operator new and
13580operator delete must always be of default visibility.
13581
13582Be aware that headers from outside your project, in particular system
13583headers and headers from any other library you use, may not be
13584expecting to be compiled with visibility other than the default. You
13585may need to explicitly say @samp{#pragma GCC visibility push(default)}
13586before including any such headers.
13587
13588@samp{extern} declarations are not affected by @samp{-fvisibility}, so
13589a lot of code can be recompiled with @samp{-fvisibility=hidden} with
13590no modifications. However, this means that calls to @samp{extern}
13591functions with no explicit visibility will use the PLT, so it is more
13592effective to use @samp{__attribute ((visibility))} and/or
13593@samp{#pragma GCC visibility} to tell the compiler which @samp{extern}
13594declarations should be treated as hidden.
13595
13596Note that @samp{-fvisibility} does affect C++ vague linkage
13597entities. This means that, for instance, an exception class that will
13598be thrown between DSOs must be explicitly marked with default
13599visibility so that the @samp{type_info} nodes will be unified between
13600the DSOs.
13601
13602An overview of these techniques, their benefits and how to use them
13603is at @w{@uref{http://gcc.gnu.org/wiki/Visibility}}.
13604
13605@end table
13606
13607@c man end
13608
13609@node Environment Variables
13610@section Environment Variables Affecting GCC
13611@cindex environment variables
13612
13613@c man begin ENVIRONMENT
13614This section describes several environment variables that affect how GCC
13615operates. Some of them work by specifying directories or prefixes to use
13616when searching for various kinds of files. Some are used to specify other
13617aspects of the compilation environment.
13618
13619Note that you can also specify places to search using options such as
13620@option{-B}, @option{-I} and @option{-L} (@pxref{Directory Options}). These
13621take precedence over places specified using environment variables, which
13622in turn take precedence over those specified by the configuration of GCC@.
13623@xref{Driver,, Controlling the Compilation Driver @file{gcc}, gccint,
13624GNU Compiler Collection (GCC) Internals}.
13625
13626@table @env
13627@item LANG
13628@itemx LC_CTYPE
13629@c @itemx LC_COLLATE
13630@itemx LC_MESSAGES
13631@c @itemx LC_MONETARY
13632@c @itemx LC_NUMERIC
13633@c @itemx LC_TIME
13634@itemx LC_ALL
13635@findex LANG
13636@findex LC_CTYPE
13637@c @findex LC_COLLATE
13638@findex LC_MESSAGES
13639@c @findex LC_MONETARY
13640@c @findex LC_NUMERIC
13641@c @findex LC_TIME
13642@findex LC_ALL
13643@cindex locale
13644These environment variables control the way that GCC uses
13645localization information that allow GCC to work with different
13646national conventions. GCC inspects the locale categories
13647@env{LC_CTYPE} and @env{LC_MESSAGES} if it has been configured to do
13648so. These locale categories can be set to any value supported by your
13649installation. A typical value is @samp{en_GB.UTF-8} for English in the United
13650Kingdom encoded in UTF-8.
13651
13652The @env{LC_CTYPE} environment variable specifies character
13653classification. GCC uses it to determine the character boundaries in
13654a string; this is needed for some multibyte encodings that contain quote
13655and escape characters that would otherwise be interpreted as a string
13656end or escape.
13657
13658The @env{LC_MESSAGES} environment variable specifies the language to
13659use in diagnostic messages.
13660
13661If the @env{LC_ALL} environment variable is set, it overrides the value
13662of @env{LC_CTYPE} and @env{LC_MESSAGES}; otherwise, @env{LC_CTYPE}
13663and @env{LC_MESSAGES} default to the value of the @env{LANG}
13664environment variable. If none of these variables are set, GCC
13665defaults to traditional C English behavior.
13666
13667@item TMPDIR
13668@findex TMPDIR
13669If @env{TMPDIR} is set, it specifies the directory to use for temporary
13670files. GCC uses temporary files to hold the output of one stage of
13671compilation which is to be used as input to the next stage: for example,
13672the output of the preprocessor, which is the input to the compiler
13673proper.
13674
13675@item GCC_EXEC_PREFIX
13676@findex GCC_EXEC_PREFIX
13677If @env{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the
13678names of the subprograms executed by the compiler. No slash is added
13679when this prefix is combined with the name of a subprogram, but you can
13680specify a prefix that ends with a slash if you wish.
13681
13682If @env{GCC_EXEC_PREFIX} is not set, GCC will attempt to figure out
13683an appropriate prefix to use based on the pathname it was invoked with.
13684
13685If GCC cannot find the subprogram using the specified prefix, it
13686tries looking in the usual places for the subprogram.
13687
13688The default value of @env{GCC_EXEC_PREFIX} is
13689@file{@var{prefix}/lib/gcc/} where @var{prefix} is the value
13690of @code{prefix} when you ran the @file{configure} script.
13691
13692Other prefixes specified with @option{-B} take precedence over this prefix.
13693
13694This prefix is also used for finding files such as @file{crt0.o} that are
13695used for linking.
13696
13697In addition, the prefix is used in an unusual way in finding the
13698directories to search for header files. For each of the standard
13699directories whose name normally begins with @samp{/usr/local/lib/gcc}
13700(more precisely, with the value of @env{GCC_INCLUDE_DIR}), GCC tries
13701replacing that beginning with the specified prefix to produce an
13702alternate directory name. Thus, with @option{-Bfoo/}, GCC will search
13703@file{foo/bar} where it would normally search @file{/usr/local/lib/bar}.
13704These alternate directories are searched first; the standard directories
13705come next.
13706
13707@item COMPILER_PATH
13708@findex COMPILER_PATH
13709The value of @env{COMPILER_PATH} is a colon-separated list of
13710directories, much like @env{PATH}. GCC tries the directories thus
13711specified when searching for subprograms, if it can't find the
13712subprograms using @env{GCC_EXEC_PREFIX}.
13713
13714@item LIBRARY_PATH
13715@findex LIBRARY_PATH
13716The value of @env{LIBRARY_PATH} is a colon-separated list of
13717directories, much like @env{PATH}. When configured as a native compiler,
13718GCC tries the directories thus specified when searching for special
13719linker files, if it can't find them using @env{GCC_EXEC_PREFIX}. Linking
13720using GCC also uses these directories when searching for ordinary
13721libraries for the @option{-l} option (but directories specified with
13722@option{-L} come first).
13723
13724@item LANG
13725@findex LANG
13726@cindex locale definition
13727This variable is used to pass locale information to the compiler. One way in
13728which this information is used is to determine the character set to be used
13729when character literals, string literals and comments are parsed in C and C++.
13730When the compiler is configured to allow multibyte characters,
13731the following values for @env{LANG} are recognized:
13732
13733@table @samp
13734@item C-JIS
13735Recognize JIS characters.
13736@item C-SJIS
13737Recognize SJIS characters.
13738@item C-EUCJP
13739Recognize EUCJP characters.
13740@end table
13741
13742If @env{LANG} is not defined, or if it has some other value, then the
13743compiler will use mblen and mbtowc as defined by the default locale to
13744recognize and translate multibyte characters.
13745@end table
13746
13747@noindent
13748Some additional environments variables affect the behavior of the
13749preprocessor.
13750
13751@include cppenv.texi
13752
13753@c man end
13754
13755@node Precompiled Headers
13756@section Using Precompiled Headers
13757@cindex precompiled headers
13758@cindex speed of compilation
13759
13760Often large projects have many header files that are included in every
13761source file. The time the compiler takes to process these header files
13762over and over again can account for nearly all of the time required to
13763build the project. To make builds faster, GCC allows users to
13764`precompile' a header file; then, if builds can use the precompiled
13765header file they will be much faster.
13766
13767To create a precompiled header file, simply compile it as you would any
13768other file, if necessary using the @option{-x} option to make the driver
13769treat it as a C or C++ header file. You will probably want to use a
13770tool like @command{make} to keep the precompiled header up-to-date when
13771the headers it contains change.
13772
13773A precompiled header file will be searched for when @code{#include} is
13774seen in the compilation. As it searches for the included file
13775(@pxref{Search Path,,Search Path,cpp,The C Preprocessor}) the
13776compiler looks for a precompiled header in each directory just before it
13777looks for the include file in that directory. The name searched for is
13778the name specified in the @code{#include} with @samp{.gch} appended. If
13779the precompiled header file can't be used, it is ignored.
13780
13781For instance, if you have @code{#include "all.h"}, and you have
13782@file{all.h.gch} in the same directory as @file{all.h}, then the
13783precompiled header file will be used if possible, and the original
13784header will be used otherwise.
13785
13786Alternatively, you might decide to put the precompiled header file in a
13787directory and use @option{-I} to ensure that directory is searched
13788before (or instead of) the directory containing the original header.
13789Then, if you want to check that the precompiled header file is always
13790used, you can put a file of the same name as the original header in this
13791directory containing an @code{#error} command.
13792
13793This also works with @option{-include}. So yet another way to use
13794precompiled headers, good for projects not designed with precompiled
13795header files in mind, is to simply take most of the header files used by
13796a project, include them from another header file, precompile that header
13797file, and @option{-include} the precompiled header. If the header files
13798have guards against multiple inclusion, they will be skipped because
13799they've already been included (in the precompiled header).
13800
13801If you need to precompile the same header file for different
13802languages, targets, or compiler options, you can instead make a
13803@emph{directory} named like @file{all.h.gch}, and put each precompiled
13804header in the directory, perhaps using @option{-o}. It doesn't matter
13805what you call the files in the directory, every precompiled header in
13806the directory will be considered. The first precompiled header
13807encountered in the directory that is valid for this compilation will
13808be used; they're searched in no particular order.
13809
13810There are many other possibilities, limited only by your imagination,
13811good sense, and the constraints of your build system.
13812
13813A precompiled header file can be used only when these conditions apply:
13814
13815@itemize
13816@item
13817Only one precompiled header can be used in a particular compilation.
13818
13819@item
13820A precompiled header can't be used once the first C token is seen. You
13821can have preprocessor directives before a precompiled header; you can
13822even include a precompiled header from inside another header, so long as
13823there are no C tokens before the @code{#include}.
13824
13825@item
13826The precompiled header file must be produced for the same language as
13827the current compilation. You can't use a C precompiled header for a C++
13828compilation.
13829
13830@item
13831The precompiled header file must have been produced by the same compiler
13832binary as the current compilation is using.
13833
13834@item
13835Any macros defined before the precompiled header is included must
13836either be defined in the same way as when the precompiled header was
13837generated, or must not affect the precompiled header, which usually
13838means that they don't appear in the precompiled header at all.
13839
13840The @option{-D} option is one way to define a macro before a
13841precompiled header is included; using a @code{#define} can also do it.
13842There are also some options that define macros implicitly, like
13843@option{-O} and @option{-Wdeprecated}; the same rule applies to macros
13844defined this way.
13845
13846@item If debugging information is output when using the precompiled
13847header, using @option{-g} or similar, the same kind of debugging information
13848must have been output when building the precompiled header. However,
13849a precompiled header built using @option{-g} can be used in a compilation
13850when no debugging information is being output.
13851
13852@item The same @option{-m} options must generally be used when building
13853and using the precompiled header. @xref{Submodel Options},
13854for any cases where this rule is relaxed.
13855
13856@item Each of the following options must be the same when building and using
13857the precompiled header:
13858
13859@gccoptlist{-fexceptions -funit-at-a-time}
13860
13861@item
13862Some other command-line options starting with @option{-f},
13863@option{-p}, or @option{-O} must be defined in the same way as when
13864the precompiled header was generated. At present, it's not clear
13865which options are safe to change and which are not; the safest choice
13866is to use exactly the same options when generating and using the
13867precompiled header. The following are known to be safe:
13868
13869@gccoptlist{-fmessage-length= -fpreprocessed
13870-fsched-interblock -fsched-spec -fsched-spec-load -fsched-spec-load-dangerous
13871-fsched-verbose=<number> -fschedule-insns -fvisibility=
13872-pedantic-errors}
13873
13874@end itemize
13875
13876For all of these except the last, the compiler will automatically
13877ignore the precompiled header if the conditions aren't met. If you
13878find an option combination that doesn't work and doesn't cause the
13879precompiled header to be ignored, please consider filing a bug report,
13880see @ref{Bugs}.
13881
13882If you do use differing options when generating and using the
13883precompiled header, the actual behavior will be a mixture of the
13884behavior for the options. For instance, if you use @option{-g} to
13885generate the precompiled header but not when using it, you may or may
13886not get debugging information for routines in the precompiled header.
13887
13888@node Running Protoize
13889@section Running Protoize
13890
13891The program @code{protoize} is an optional part of GCC@. You can use
13892it to add prototypes to a program, thus converting the program to ISO
13893C in one respect. The companion program @code{unprotoize} does the
13894reverse: it removes argument types from any prototypes that are found.
13895
13896When you run these programs, you must specify a set of source files as
13897command line arguments. The conversion programs start out by compiling
13898these files to see what functions they define. The information gathered
13899about a file @var{foo} is saved in a file named @file{@var{foo}.X}.
13900
13901After scanning comes actual conversion. The specified files are all
13902eligible to be converted; any files they include (whether sources or
13903just headers) are eligible as well.
13904
13905But not all the eligible files are converted. By default,
13906@code{protoize} and @code{unprotoize} convert only source and header
13907files in the current directory. You can specify additional directories
13908whose files should be converted with the @option{-d @var{directory}}
13909option. You can also specify particular files to exclude with the
13910@option{-x @var{file}} option. A file is converted if it is eligible, its
13911directory name matches one of the specified directory names, and its
13912name within the directory has not been excluded.
13913
13914Basic conversion with @code{protoize} consists of rewriting most
13915function definitions and function declarations to specify the types of
13916the arguments. The only ones not rewritten are those for varargs
13917functions.
13918
13919@code{protoize} optionally inserts prototype declarations at the
13920beginning of the source file, to make them available for any calls that
13921precede the function's definition. Or it can insert prototype
13922declarations with block scope in the blocks where undeclared functions
13923are called.
13924
13925Basic conversion with @code{unprotoize} consists of rewriting most
13926function declarations to remove any argument types, and rewriting
13927function definitions to the old-style pre-ISO form.
13928
13929Both conversion programs print a warning for any function declaration or
13930definition that they can't convert. You can suppress these warnings
13931with @option{-q}.
13932
13933The output from @code{protoize} or @code{unprotoize} replaces the
13934original source file. The original file is renamed to a name ending
13935with @samp{.save} (for DOS, the saved filename ends in @samp{.sav}
13936without the original @samp{.c} suffix). If the @samp{.save} (@samp{.sav}
13937for DOS) file already exists, then the source file is simply discarded.
13938
13939@code{protoize} and @code{unprotoize} both depend on GCC itself to
13940scan the program and collect information about the functions it uses.
13941So neither of these programs will work until GCC is installed.
13942
13943Here is a table of the options you can use with @code{protoize} and
13944@code{unprotoize}. Each option works with both programs unless
13945otherwise stated.
13946
13947@table @code
13948@item -B @var{directory}
13949Look for the file @file{SYSCALLS.c.X} in @var{directory}, instead of the
13950usual directory (normally @file{/usr/local/lib}). This file contains
13951prototype information about standard system functions. This option
13952applies only to @code{protoize}.
13953
13954@item -c @var{compilation-options}
13955Use @var{compilation-options} as the options when running @command{gcc} to
13956produce the @samp{.X} files. The special option @option{-aux-info} is
13957always passed in addition, to tell @command{gcc} to write a @samp{.X} file.
13958
13959Note that the compilation options must be given as a single argument to
13960@code{protoize} or @code{unprotoize}. If you want to specify several
13961@command{gcc} options, you must quote the entire set of compilation options
13962to make them a single word in the shell.
13963
13964There are certain @command{gcc} arguments that you cannot use, because they
13965would produce the wrong kind of output. These include @option{-g},
13966@option{-O}, @option{-c}, @option{-S}, and @option{-o} If you include these in
13967the @var{compilation-options}, they are ignored.
13968
13969@item -C
13970Rename files to end in @samp{.C} (@samp{.cc} for DOS-based file
13971systems) instead of @samp{.c}. This is convenient if you are converting
13972a C program to C++. This option applies only to @code{protoize}.
13973
13974@item -g
13975Add explicit global declarations. This means inserting explicit
13976declarations at the beginning of each source file for each function
13977that is called in the file and was not declared. These declarations
13978precede the first function definition that contains a call to an
13979undeclared function. This option applies only to @code{protoize}.
13980
13981@item -i @var{string}
13982Indent old-style parameter declarations with the string @var{string}.
13983This option applies only to @code{protoize}.
13984
13985@code{unprotoize} converts prototyped function definitions to old-style
13986function definitions, where the arguments are declared between the
13987argument list and the initial @samp{@{}. By default, @code{unprotoize}
13988uses five spaces as the indentation. If you want to indent with just
13989one space instead, use @option{-i " "}.
13990
13991@item -k
13992Keep the @samp{.X} files. Normally, they are deleted after conversion
13993is finished.
13994
13995@item -l
13996Add explicit local declarations. @code{protoize} with @option{-l} inserts
13997a prototype declaration for each function in each block which calls the
13998function without any declaration. This option applies only to
13999@code{protoize}.
14000
14001@item -n
14002Make no real changes. This mode just prints information about the conversions
14003that would have been done without @option{-n}.
14004
14005@item -N
14006Make no @samp{.save} files. The original files are simply deleted.
14007Use this option with caution.
14008
14009@item -p @var{program}
14010Use the program @var{program} as the compiler. Normally, the name
14011@file{gcc} is used.
14012
14013@item -q
14014Work quietly. Most warnings are suppressed.
14015
14016@item -v
14017Print the version number, just like @option{-v} for @command{gcc}.
14018@end table
14019
14020If you need special compiler options to compile one of your program's
14021source files, then you should generate that file's @samp{.X} file
14022specially, by running @command{gcc} on that source file with the
14023appropriate options and the option @option{-aux-info}. Then run
14024@code{protoize} on the entire set of files. @code{protoize} will use
14025the existing @samp{.X} file because it is newer than the source file.
14026For example:
14027
14028@smallexample
14029gcc -Dfoo=bar file1.c -aux-info file1.X
14030protoize *.c
14031@end smallexample
14032
14033@noindent
14034You need to include the special files along with the rest in the
14035@code{protoize} command, even though their @samp{.X} files already
14036exist, because otherwise they won't get converted.
14037
14038@xref{Protoize Caveats}, for more information on how to use
14039@code{protoize} successfully.
14040
|