1625@item -fno-weak
1626@opindex fno-weak
1627Do not use weak symbol support, even if it is provided by the linker.
1628By default, G++ will use weak symbols if they are available. This
1629option exists only for testing, and should not be used by end-users;
1630it will result in inferior code and has no benefits. This option may
1631be removed in a future release of G++.
1632
1633@item -nostdinc++
1634@opindex nostdinc++
1635Do not search for header files in the standard directories specific to
1636C++, but do still search the other standard directories. (This option
1637is used when building the C++ library.)
1638@end table
1639
1640In addition, these optimization, warning, and code generation options
1641have meanings only for C++ programs:
1642
1643@table @gcctabopt
1644@item -fno-default-inline
1645@opindex fno-default-inline
1646Do not assume @samp{inline} for functions defined inside a class scope.
1647@xref{Optimize Options,,Options That Control Optimization}. Note that these
1648functions will have linkage like inline functions; they just won't be
1649inlined by default.
1650
1651@item -Wabi @r{(C++ only)}
1652@opindex Wabi
1653Warn when G++ generates code that is probably not compatible with the
1654vendor-neutral C++ ABI@. Although an effort has been made to warn about
1655all such cases, there are probably some cases that are not warned about,
1656even though G++ is generating incompatible code. There may also be
1657cases where warnings are emitted even though the code that is generated
1658will be compatible.
1659
1660You should rewrite your code to avoid these warnings if you are
1661concerned about the fact that code generated by G++ may not be binary
1662compatible with code generated by other compilers.
1663
1664The known incompatibilities at this point include:
1665
1666@itemize @bullet
1667
1668@item
1669Incorrect handling of tail-padding for bit-fields. G++ may attempt to
1670pack data into the same byte as a base class. For example:
1671
1672@smallexample
1673struct A @{ virtual void f(); int f1 : 1; @};
1674struct B : public A @{ int f2 : 1; @};
1675@end smallexample
1676
1677@noindent
1678In this case, G++ will place @code{B::f2} into the same byte
1679as@code{A::f1}; other compilers will not. You can avoid this problem
1680by explicitly padding @code{A} so that its size is a multiple of the
1681byte size on your platform; that will cause G++ and other compilers to
1682layout @code{B} identically.
1683
1684@item
1685Incorrect handling of tail-padding for virtual bases. G++ does not use
1686tail padding when laying out virtual bases. For example:
1687
1688@smallexample
1689struct A @{ virtual void f(); char c1; @};
1690struct B @{ B(); char c2; @};
1691struct C : public A, public virtual B @{@};
1692@end smallexample
1693
1694@noindent
1695In this case, G++ will not place @code{B} into the tail-padding for
1696@code{A}; other compilers will. You can avoid this problem by
1697explicitly padding @code{A} so that its size is a multiple of its
1698alignment (ignoring virtual base classes); that will cause G++ and other
1699compilers to layout @code{C} identically.
1700
1701@item
1702Incorrect handling of bit-fields with declared widths greater than that
1703of their underlying types, when the bit-fields appear in a union. For
1704example:
1705
1706@smallexample
1707union U @{ int i : 4096; @};
1708@end smallexample
1709
1710@noindent
1711Assuming that an @code{int} does not have 4096 bits, G++ will make the
1712union too small by the number of bits in an @code{int}.
1713
1714@item
1715Empty classes can be placed at incorrect offsets. For example:
1716
1717@smallexample
1718struct A @{@};
1719
1720struct B @{
1721 A a;
1722 virtual void f ();
1723@};
1724
1725struct C : public B, public A @{@};
1726@end smallexample
1727
1728@noindent
1729G++ will place the @code{A} base class of @code{C} at a nonzero offset;
1730it should be placed at offset zero. G++ mistakenly believes that the
1731@code{A} data member of @code{B} is already at offset zero.
1732
1733@item
1734Names of template functions whose types involve @code{typename} or
1735template template parameters can be mangled incorrectly.
1736
1737@smallexample
1738template <typename Q>
1739void f(typename Q::X) @{@}
1740
1741template <template <typename> class Q>
1742void f(typename Q<int>::X) @{@}
1743@end smallexample
1744
1745@noindent
1746Instantiations of these templates may be mangled incorrectly.
1747
1748@end itemize
1749
1750@item -Wctor-dtor-privacy @r{(C++ only)}
1751@opindex Wctor-dtor-privacy
1752Warn when a class seems unusable because all the constructors or
1753destructors in that class are private, and it has neither friends nor
1754public static member functions.
1755
1756@item -Wnon-virtual-dtor @r{(C++ only)}
1757@opindex Wnon-virtual-dtor
1758Warn when a class appears to be polymorphic, thereby requiring a virtual
1759destructor, yet it declares a non-virtual one. This warning is also
1760enabled if -Weffc++ is specified.
1761
1762@item -Wreorder @r{(C++ only)}
1763@opindex Wreorder
1764@cindex reordering, warning
1765@cindex warning for reordering of member initializers
1766Warn when the order of member initializers given in the code does not
1767match the order in which they must be executed. For instance:
1768
1769@smallexample
1770struct A @{
1771 int i;
1772 int j;
1773 A(): j (0), i (1) @{ @}
1774@};
1775@end smallexample
1776
1777The compiler will rearrange the member initializers for @samp{i}
1778and @samp{j} to match the declaration order of the members, emitting
1779a warning to that effect. This warning is enabled by @option{-Wall}.
1780@end table
1781
1782The following @option{-W@dots{}} options are not affected by @option{-Wall}.
1783
1784@table @gcctabopt
1785@item -Weffc++ @r{(C++ only)}
1786@opindex Weffc++
1787Warn about violations of the following style guidelines from Scott Meyers'
1788@cite{Effective C++} book:
1789
1790@itemize @bullet
1791@item
1792Item 11: Define a copy constructor and an assignment operator for classes
1793with dynamically allocated memory.
1794
1795@item
1796Item 12: Prefer initialization to assignment in constructors.
1797
1798@item
1799Item 14: Make destructors virtual in base classes.
1800
1801@item
1802Item 15: Have @code{operator=} return a reference to @code{*this}.
1803
1804@item
1805Item 23: Don't try to return a reference when you must return an object.
1806
1807@end itemize
1808
1809Also warn about violations of the following style guidelines from
1810Scott Meyers' @cite{More Effective C++} book:
1811
1812@itemize @bullet
1813@item
1814Item 6: Distinguish between prefix and postfix forms of increment and
1815decrement operators.
1816
1817@item
1818Item 7: Never overload @code{&&}, @code{||}, or @code{,}.
1819
1820@end itemize
1821
1822When selecting this option, be aware that the standard library
1823headers do not obey all of these guidelines; use @samp{grep -v}
1824to filter out those warnings.
1825
1826@item -Wno-deprecated @r{(C++ only)}
1827@opindex Wno-deprecated
1828Do not warn about usage of deprecated features. @xref{Deprecated Features}.
1829
1830@item -Wstrict-null-sentinel @r{(C++ only)}
1831@opindex Wstrict-null-sentinel
1832Warn also about the use of an uncasted @code{NULL} as sentinel. When
1833compiling only with GCC this is a valid sentinel, as @code{NULL} is defined
1834to @code{__null}. Although it is a null pointer constant not a null pointer,
1835it is guaranteed to of the same size as a pointer. But this use is
1836not portable across different compilers.
1837
1838@item -Wno-non-template-friend @r{(C++ only)}
1839@opindex Wno-non-template-friend
1840Disable warnings when non-templatized friend functions are declared
1841within a template. Since the advent of explicit template specification
1842support in G++, if the name of the friend is an unqualified-id (i.e.,
1843@samp{friend foo(int)}), the C++ language specification demands that the
1844friend declare or define an ordinary, nontemplate function. (Section
184514.5.3). Before G++ implemented explicit specification, unqualified-ids
1846could be interpreted as a particular specialization of a templatized
1847function. Because this non-conforming behavior is no longer the default
1848behavior for G++, @option{-Wnon-template-friend} allows the compiler to
1849check existing code for potential trouble spots and is on by default.
1850This new compiler behavior can be turned off with
1851@option{-Wno-non-template-friend} which keeps the conformant compiler code
1852but disables the helpful warning.
1853
1854@item -Wold-style-cast @r{(C++ only)}
1855@opindex Wold-style-cast
1856Warn if an old-style (C-style) cast to a non-void type is used within
1857a C++ program. The new-style casts (@samp{dynamic_cast},
1858@samp{static_cast}, @samp{reinterpret_cast}, and @samp{const_cast}) are
1859less vulnerable to unintended effects and much easier to search for.
1860
1861@item -Woverloaded-virtual @r{(C++ only)}
1862@opindex Woverloaded-virtual
1863@cindex overloaded virtual fn, warning
1864@cindex warning for overloaded virtual fn
1865Warn when a function declaration hides virtual functions from a
1866base class. For example, in:
1867
1868@smallexample
1869struct A @{
1870 virtual void f();
1871@};
1872
1873struct B: public A @{
1874 void f(int);
1875@};
1876@end smallexample
1877
1878the @code{A} class version of @code{f} is hidden in @code{B}, and code
1879like:
1880
1881@smallexample
1882B* b;
1883b->f();
1884@end smallexample
1885
1886will fail to compile.
1887
1888@item -Wno-pmf-conversions @r{(C++ only)}
1889@opindex Wno-pmf-conversions
1890Disable the diagnostic for converting a bound pointer to member function
1891to a plain pointer.
1892
1893@item -Wsign-promo @r{(C++ only)}
1894@opindex Wsign-promo
1895Warn when overload resolution chooses a promotion from unsigned or
1896enumerated type to a signed type, over a conversion to an unsigned type of
1897the same size. Previous versions of G++ would try to preserve
1898unsignedness, but the standard mandates the current behavior.
1899
1900@smallexample
1901struct A @{
1902 operator int ();
1903 A& operator = (int);
1904@};
1905
1906main ()
1907@{
1908 A a,b;
1909 a = b;
1910@}
1911@end smallexample
1912
1913In this example, G++ will synthesize a default @samp{A& operator =
1914(const A&);}, while cfront will use the user-defined @samp{operator =}.
1915@end table
1916
1917@node Language Independent Options
1918@section Options to Control Diagnostic Messages Formatting
1919@cindex options to control diagnostics formatting
1920@cindex diagnostic messages
1921@cindex message formatting
1922
1923Traditionally, diagnostic messages have been formatted irrespective of
1924the output device's aspect (e.g.@: its width, @dots{}). The options described
1925below can be used to control the diagnostic messages formatting
1926algorithm, e.g.@: how many characters per line, how often source location
1927information should be reported. Right now, only the C++ front end can
1928honor these options. However it is expected, in the near future, that
1929the remaining front ends would be able to digest them correctly.
1930
1931@table @gcctabopt
1932@item -fmessage-length=@var{n}
1933@opindex fmessage-length
1934Try to format error messages so that they fit on lines of about @var{n}
1935characters. The default is 72 characters for @command{g++} and 0 for the rest of
1936the front ends supported by GCC@. If @var{n} is zero, then no
1937line-wrapping will be done; each error message will appear on a single
1938line.
1939
1940@opindex fdiagnostics-show-location
1941@item -fdiagnostics-show-location=once
1942Only meaningful in line-wrapping mode. Instructs the diagnostic messages
1943reporter to emit @emph{once} source location information; that is, in
1944case the message is too long to fit on a single physical line and has to
1945be wrapped, the source location won't be emitted (as prefix) again,
1946over and over, in subsequent continuation lines. This is the default
1947behavior.
1948
1949@item -fdiagnostics-show-location=every-line
1950Only meaningful in line-wrapping mode. Instructs the diagnostic
1951messages reporter to emit the same source location information (as
1952prefix) for physical lines that result from the process of breaking
1953a message which is too long to fit on a single line.
1954
1955@item -fdiagnostics-show-option
1956@opindex fdiagnostics-show-option
1957This option instructs the diagnostic machinery to add text to each
1958diagnostic emitted, which indicates which command line option directly
1959controls that diagnostic, when such an option is known to the
1960diagnostic machinery.
1961
1962@end table
1963
1964@node Warning Options
1965@section Options to Request or Suppress Warnings
1966@cindex options to control warnings
1967@cindex warning messages
1968@cindex messages, warning
1969@cindex suppressing warnings
1970
1971Warnings are diagnostic messages that report constructions which
1972are not inherently erroneous but which are risky or suggest there
1973may have been an error.
1974
1975You can request many specific warnings with options beginning @samp{-W},
1976for example @option{-Wimplicit} to request warnings on implicit
1977declarations. Each of these specific warning options also has a
1978negative form beginning @samp{-Wno-} to turn off warnings;
1979for example, @option{-Wno-implicit}. This manual lists only one of the
1980two forms, whichever is not the default.
1981
1982The following options control the amount and kinds of warnings produced
1983by GCC; for further, language-specific options also refer to
1984@ref{C++ Dialect Options}.
1985
1986@table @gcctabopt
1987@cindex syntax checking
1988@item -fsyntax-only
1989@opindex fsyntax-only
1990Check the code for syntax errors, but don't do anything beyond that.
1991
1992@item -pedantic
1993@opindex pedantic
1994Issue all the warnings demanded by strict ISO C and ISO C++;
1995reject all programs that use forbidden extensions, and some other
1996programs that do not follow ISO C and ISO C++. For ISO C, follows the
1997version of the ISO C standard specified by any @option{-std} option used.
1998
1999Valid ISO C and ISO C++ programs should compile properly with or without
2000this option (though a rare few will require @option{-ansi} or a
2001@option{-std} option specifying the required version of ISO C)@. However,
2002without this option, certain GNU extensions and traditional C and C++
2003features are supported as well. With this option, they are rejected.
2004
2005@option{-pedantic} does not cause warning messages for use of the
2006alternate keywords whose names begin and end with @samp{__}. Pedantic
2007warnings are also disabled in the expression that follows
2008@code{__extension__}. However, only system header files should use
2009these escape routes; application programs should avoid them.
2010@xref{Alternate Keywords}.
2011
2012Some users try to use @option{-pedantic} to check programs for strict ISO
2013C conformance. They soon find that it does not do quite what they want:
2014it finds some non-ISO practices, but not all---only those for which
2015ISO C @emph{requires} a diagnostic, and some others for which
2016diagnostics have been added.
2017
2018A feature to report any failure to conform to ISO C might be useful in
2019some instances, but would require considerable additional work and would
2020be quite different from @option{-pedantic}. We don't have plans to
2021support such a feature in the near future.
2022
2023Where the standard specified with @option{-std} represents a GNU
2024extended dialect of C, such as @samp{gnu89} or @samp{gnu99}, there is a
2025corresponding @dfn{base standard}, the version of ISO C on which the GNU
2026extended dialect is based. Warnings from @option{-pedantic} are given
2027where they are required by the base standard. (It would not make sense
2028for such warnings to be given only for features not in the specified GNU
2029C dialect, since by definition the GNU dialects of C include all
2030features the compiler supports with the given option, and there would be
2031nothing to warn about.)
2032
2033@item -pedantic-errors
2034@opindex pedantic-errors
2035Like @option{-pedantic}, except that errors are produced rather than
2036warnings.
2037
2038@item -w
2039@opindex w
2040Inhibit all warning messages.
2041
2042@item -Wno-import
2043@opindex Wno-import
2044Inhibit warning messages about the use of @samp{#import}.
2045
2046@c APPLE LOCAL begin -Wnewline-eof 2001-08-23 --sts **
2047@item -Wnewline-eof
2048@opindex Wnewline-eof
2049Warn about files missing a newline at the end of the file. (Apple compatible)
2050@c APPLE LOCAL end -Wnewline-eof 2001-08-23 --sts **
2051
2052@item -Wchar-subscripts
2053@opindex Wchar-subscripts
2054Warn if an array subscript has type @code{char}. This is a common cause
2055of error, as programmers often forget that this type is signed on some
2056machines.
2057This warning is enabled by @option{-Wall}.
2058
2059@item -Wcomment
2060@opindex Wcomment
2061Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
2062comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
2063This warning is enabled by @option{-Wall}.
2064
2065@item -Wfatal-errors
2066@opindex Wfatal-errors
2067This option causes the compiler to abort compilation on the first error
2068occurred rather than trying to keep going and printing further error
2069messages.
2070
2071@item -Wformat
2072@opindex Wformat
2073@opindex ffreestanding
2074@opindex fno-builtin
2075Check calls to @code{printf} and @code{scanf}, etc., to make sure that
2076the arguments supplied have types appropriate to the format string
2077specified, and that the conversions specified in the format string make
2078sense. This includes standard functions, and others specified by format
2079attributes (@pxref{Function Attributes}), in the @code{printf},
2080@code{scanf}, @code{strftime} and @code{strfmon} (an X/Open extension,
2081not in the C standard) families (or other target-specific families).
2082Which functions are checked without format attributes having been
2083specified depends on the standard version selected, and such checks of
2084functions without the attribute specified are disabled by
2085@option{-ffreestanding} or @option{-fno-builtin}.
2086
2087The formats are checked against the format features supported by GNU
2088libc version 2.2. These include all ISO C90 and C99 features, as well
2089as features from the Single Unix Specification and some BSD and GNU
2090extensions. Other library implementations may not support all these
2091features; GCC does not support warning about features that go beyond a
2092particular library's limitations. However, if @option{-pedantic} is used
2093with @option{-Wformat}, warnings will be given about format features not
2094in the selected standard version (but not for @code{strfmon} formats,
2095since those are not in any version of the C standard). @xref{C Dialect
2096Options,,Options Controlling C Dialect}.
2097
2098Since @option{-Wformat} also checks for null format arguments for
2099several functions, @option{-Wformat} also implies @option{-Wnonnull}.
2100
2101@option{-Wformat} is included in @option{-Wall}. For more control over some
2102aspects of format checking, the options @option{-Wformat-y2k},
2103@option{-Wno-format-extra-args}, @option{-Wno-format-zero-length},
2104@option{-Wformat-nonliteral}, @option{-Wformat-security}, and
2105@option{-Wformat=2} are available, but are not included in @option{-Wall}.
2106
2107@item -Wformat-y2k
2108@opindex Wformat-y2k
2109If @option{-Wformat} is specified, also warn about @code{strftime}
2110formats which may yield only a two-digit year.
2111
2112@item -Wno-format-extra-args
2113@opindex Wno-format-extra-args
2114If @option{-Wformat} is specified, do not warn about excess arguments to a
2115@code{printf} or @code{scanf} format function. The C standard specifies
2116that such arguments are ignored.
2117
2118Where the unused arguments lie between used arguments that are
2119specified with @samp{$} operand number specifications, normally
2120warnings are still given, since the implementation could not know what
2121type to pass to @code{va_arg} to skip the unused arguments. However,
2122in the case of @code{scanf} formats, this option will suppress the
2123warning if the unused arguments are all pointers, since the Single
2124Unix Specification says that such unused arguments are allowed.
2125
2126@item -Wno-format-zero-length
2127@opindex Wno-format-zero-length
2128If @option{-Wformat} is specified, do not warn about zero-length formats.
2129The C standard specifies that zero-length formats are allowed.
2130
2131@item -Wformat-nonliteral
2132@opindex Wformat-nonliteral
2133If @option{-Wformat} is specified, also warn if the format string is not a
2134string literal and so cannot be checked, unless the format function
2135takes its format arguments as a @code{va_list}.
2136
2137@item -Wformat-security
2138@opindex Wformat-security
2139If @option{-Wformat} is specified, also warn about uses of format
2140functions that represent possible security problems. At present, this
2141warns about calls to @code{printf} and @code{scanf} functions where the
2142format string is not a string literal and there are no format arguments,
2143as in @code{printf (foo);}. This may be a security hole if the format
2144string came from untrusted input and contains @samp{%n}. (This is
2145currently a subset of what @option{-Wformat-nonliteral} warns about, but
2146in future warnings may be added to @option{-Wformat-security} that are not
2147included in @option{-Wformat-nonliteral}.)
2148
2149@item -Wformat=2
2150@opindex Wformat=2
2151Enable @option{-Wformat} plus format checks not included in
2152@option{-Wformat}. Currently equivalent to @samp{-Wformat
2153-Wformat-nonliteral -Wformat-security -Wformat-y2k}.
2154
2155@item -Wnonnull
2156@opindex Wnonnull
2157Warn about passing a null pointer for arguments marked as
2158requiring a non-null value by the @code{nonnull} function attribute.
2159
2160@option{-Wnonnull} is included in @option{-Wall} and @option{-Wformat}. It
2161can be disabled with the @option{-Wno-nonnull} option.
2162
2163@item -Winit-self @r{(C and C++ only)}
2164@opindex Winit-self
2165Warn about uninitialized variables which are initialized with themselves.
2166Note this option can only be used with the @option{-Wuninitialized} option,
2167which in turn only works with @option{-O1} and above.
2168
2169For example, GCC will warn about @code{i} being uninitialized in the
2170following snippet only when @option{-Winit-self} has been specified:
2171@smallexample
2172@group
2173int f()
2174@{
2175 int i = i;
2176 return i;
2177@}
2178@end group
2179@end smallexample
2180
2181@item -Wimplicit-int
2182@opindex Wimplicit-int
2183Warn when a declaration does not specify a type.
2184This warning is enabled by @option{-Wall}.
2185
2186@item -Wimplicit-function-declaration
2187@itemx -Werror-implicit-function-declaration
2188@opindex Wimplicit-function-declaration
2189@opindex Werror-implicit-function-declaration
2190Give a warning (or error) whenever a function is used before being
2191declared. The form @option{-Wno-error-implicit-function-declaration}
2192is not supported.
2193This warning is enabled by @option{-Wall} (as a warning, not an error).
2194
2195@item -Wimplicit
2196@opindex Wimplicit
2197Same as @option{-Wimplicit-int} and @option{-Wimplicit-function-declaration}.
2198This warning is enabled by @option{-Wall}.
2199
2200@item -Wmain
2201@opindex Wmain
2202Warn if the type of @samp{main} is suspicious. @samp{main} should be a
2203function with external linkage, returning int, taking either zero
2204arguments, two, or three arguments of appropriate types.
2205This warning is enabled by @option{-Wall}.
2206
2207@item -Wmissing-braces
2208@opindex Wmissing-braces
2209Warn if an aggregate or union initializer is not fully bracketed. In
2210the following example, the initializer for @samp{a} is not fully
2211bracketed, but that for @samp{b} is fully bracketed.
2212
2213@smallexample
2214int a[2][2] = @{ 0, 1, 2, 3 @};
2215int b[2][2] = @{ @{ 0, 1 @}, @{ 2, 3 @} @};
2216@end smallexample
2217
2218This warning is enabled by @option{-Wall}.
2219
2220@item -Wmissing-include-dirs @r{(C and C++ only)}
2221@opindex Wmissing-include-dirs
2222Warn if a user-supplied include directory does not exist.
2223
2224@item -Wparentheses
2225@opindex Wparentheses
2226Warn if parentheses are omitted in certain contexts, such
2227as when there is an assignment in a context where a truth value
2228is expected, or when operators are nested whose precedence people
2229often get confused about.
2230
2231Also warn if a comparison like @samp{x<=y<=z} appears; this is
2232equivalent to @samp{(x<=y ? 1 : 0) <= z}, which is a different
2233interpretation from that of ordinary mathematical notation.
2234
2235Also warn about constructions where there may be confusion to which
2236@code{if} statement an @code{else} branch belongs. Here is an example of
2237such a case:
2238
2239@smallexample
2240@group
2241@{
2242 if (a)
2243 if (b)
2244 foo ();
2245 else
2246 bar ();
2247@}
2248@end group
2249@end smallexample
2250
2251In C/C++, every @code{else} branch belongs to the innermost possible
2252@code{if} statement, which in this example is @code{if (b)}. This is
2253often not what the programmer expected, as illustrated in the above
2254example by indentation the programmer chose. When there is the
2255potential for this confusion, GCC will issue a warning when this flag
2256is specified. To eliminate the warning, add explicit braces around
2257the innermost @code{if} statement so there is no way the @code{else}
2258could belong to the enclosing @code{if}. The resulting code would
2259look like this:
2260
2261@smallexample
2262@group
2263@{
2264 if (a)
2265 @{
2266 if (b)
2267 foo ();
2268 else
2269 bar ();
2270 @}
2271@}
2272@end group
2273@end smallexample
2274
2275This warning is enabled by @option{-Wall}.
2276
2277@item -Wsequence-point
2278@opindex Wsequence-point
2279Warn about code that may have undefined semantics because of violations
2280of sequence point rules in the C and C++ standards.
2281
2282The C and C++ standards defines the order in which expressions in a C/C++
2283program are evaluated in terms of @dfn{sequence points}, which represent
2284a partial ordering between the execution of parts of the program: those
2285executed before the sequence point, and those executed after it. These
2286occur after the evaluation of a full expression (one which is not part
2287of a larger expression), after the evaluation of the first operand of a
2288@code{&&}, @code{||}, @code{? :} or @code{,} (comma) operator, before a
2289function is called (but after the evaluation of its arguments and the
2290expression denoting the called function), and in certain other places.
2291Other than as expressed by the sequence point rules, the order of
2292evaluation of subexpressions of an expression is not specified. All
2293these rules describe only a partial order rather than a total order,
2294since, for example, if two functions are called within one expression
2295with no sequence point between them, the order in which the functions
2296are called is not specified. However, the standards committee have
2297ruled that function calls do not overlap.
2298
2299It is not specified when between sequence points modifications to the
2300values of objects take effect. Programs whose behavior depends on this
2301have undefined behavior; the C and C++ standards specify that ``Between
2302the previous and next sequence point an object shall have its stored
2303value modified at most once by the evaluation of an expression.
2304Furthermore, the prior value shall be read only to determine the value
2305to be stored.''. If a program breaks these rules, the results on any
2306particular implementation are entirely unpredictable.
2307
2308Examples of code with undefined behavior are @code{a = a++;}, @code{a[n]
2309= b[n++]} and @code{a[i++] = i;}. Some more complicated cases are not
2310diagnosed by this option, and it may give an occasional false positive
2311result, but in general it has been found fairly effective at detecting
2312this sort of problem in programs.
2313
2314The standard is worded confusingly, therefore there is some debate
2315over the precise meaning of the sequence point rules in subtle cases.
2316Links to discussions of the problem, including proposed formal
2317definitions, may be found on the GCC readings page, at
2318@w{@uref{http://gcc.gnu.org/readings.html}}.
2319
2320This warning is enabled by @option{-Wall} for C and C++.
2321
2322@item -Wreturn-type
2323@opindex Wreturn-type
2324Warn whenever a function is defined with a return-type that defaults to
2325@code{int}. Also warn about any @code{return} statement with no
2326return-value in a function whose return-type is not @code{void}.
2327
2328For C, also warn if the return type of a function has a type qualifier
2329such as @code{const}. Such a type qualifier has no effect, since the
2330value returned by a function is not an lvalue. ISO C prohibits
2331qualified @code{void} return types on function definitions, so such
2332return types always receive a warning even without this option.
2333
2334For C++, a function without return type always produces a diagnostic
2335message, even when @option{-Wno-return-type} is specified. The only
2336exceptions are @samp{main} and functions defined in system headers.
2337
2338This warning is enabled by @option{-Wall}.
2339
2340@item -Wswitch
2341@opindex Wswitch
2342Warn whenever a @code{switch} statement has an index of enumerated type
2343and lacks a @code{case} for one or more of the named codes of that
2344enumeration. (The presence of a @code{default} label prevents this
2345warning.) @code{case} labels outside the enumeration range also
2346provoke warnings when this option is used.
2347This warning is enabled by @option{-Wall}.
2348
2349@item -Wswitch-default
2350@opindex Wswitch-switch
2351Warn whenever a @code{switch} statement does not have a @code{default}
2352case.
2353
2354@item -Wswitch-enum
2355@opindex Wswitch-enum
2356Warn whenever a @code{switch} statement has an index of enumerated type
2357and lacks a @code{case} for one or more of the named codes of that
2358enumeration. @code{case} labels outside the enumeration range also
2359provoke warnings when this option is used.
2360
2361@item -Wtrigraphs
2362@opindex Wtrigraphs
2363Warn if any trigraphs are encountered that might change the meaning of
2364the program (trigraphs within comments are not warned about).
2365This warning is enabled by @option{-Wall}.
2366
2367@item -Wunused-function
2368@opindex Wunused-function
2369Warn whenever a static function is declared but not defined or a
2370non-inline static function is unused.
2371This warning is enabled by @option{-Wall}.
2372
2373@item -Wunused-label
2374@opindex Wunused-label
2375Warn whenever a label is declared but not used.
2376This warning is enabled by @option{-Wall}.
2377
2378To suppress this warning use the @samp{unused} attribute
2379(@pxref{Variable Attributes}).
2380
2381@item -Wunused-parameter
2382@opindex Wunused-parameter
2383Warn whenever a function parameter is unused aside from its declaration.
2384
2385To suppress this warning use the @samp{unused} attribute
2386(@pxref{Variable Attributes}).
2387
2388@item -Wunused-variable
2389@opindex Wunused-variable
2390Warn whenever a local variable or non-constant static variable is unused
2391aside from its declaration.
2392This warning is enabled by @option{-Wall}.
2393
2394To suppress this warning use the @samp{unused} attribute
2395(@pxref{Variable Attributes}).
2396
2397@item -Wunused-value
2398@opindex Wunused-value
2399Warn whenever a statement computes a result that is explicitly not used.
2400This warning is enabled by @option{-Wall}.
2401
2402To suppress this warning cast the expression to @samp{void}.
2403
2404@item -Wunused
2405@opindex Wunused
2406All the above @option{-Wunused} options combined.
2407
2408In order to get a warning about an unused function parameter, you must
2409either specify @samp{-Wextra -Wunused} (note that @samp{-Wall} implies
2410@samp{-Wunused}), or separately specify @option{-Wunused-parameter}.
2411
2412@item -Wuninitialized
2413@opindex Wuninitialized
2414Warn if an automatic variable is used without first being initialized or
2415if a variable may be clobbered by a @code{setjmp} call.
2416
2417These warnings are possible only in optimizing compilation,
2418because they require data flow information that is computed only
2419when optimizing. If you do not specify @option{-O}, you will not get
2420these warnings. Instead, GCC will issue a warning about @option{-Wuninitialized}
2421requiring @option{-O}.
2422
2423If you want to warn about code which uses the uninitialized value of the
2424variable in its own initializer, use the @option{-Winit-self} option.
2425
2426These warnings occur for individual uninitialized or clobbered
2427elements of structure, union or array variables as well as for
2428variables which are uninitialized or clobbered as a whole. They do
2429not occur for variables or elements declared @code{volatile}. Because
2430these warnings depend on optimization, the exact variables or elements
2431for which there are warnings will depend on the precise optimization
2432options and version of GCC used.
2433
2434Note that there may be no warning about a variable that is used only
2435to compute a value that itself is never used, because such
2436computations may be deleted by data flow analysis before the warnings
2437are printed.
2438
2439These warnings are made optional because GCC is not smart
2440enough to see all the reasons why the code might be correct
2441despite appearing to have an error. Here is one example of how
2442this can happen:
2443
2444@smallexample
2445@group
2446@{
2447 int x;
2448 switch (y)
2449 @{
2450 case 1: x = 1;
2451 break;
2452 case 2: x = 4;
2453 break;
2454 case 3: x = 5;
2455 @}
2456 foo (x);
2457@}
2458@end group
2459@end smallexample
2460
2461@noindent
2462If the value of @code{y} is always 1, 2 or 3, then @code{x} is
2463always initialized, but GCC doesn't know this. Here is
2464another common case:
2465
2466@smallexample
2467@{
2468 int save_y;
2469 if (change_y) save_y = y, y = new_y;
2470 @dots{}
2471 if (change_y) y = save_y;
2472@}
2473@end smallexample
2474
2475@noindent
2476This has no bug because @code{save_y} is used only if it is set.
2477
2478@cindex @code{longjmp} warnings
2479This option also warns when a non-volatile automatic variable might be
2480changed by a call to @code{longjmp}. These warnings as well are possible
2481only in optimizing compilation.
2482
2483The compiler sees only the calls to @code{setjmp}. It cannot know
2484where @code{longjmp} will be called; in fact, a signal handler could
2485call it at any point in the code. As a result, you may get a warning
2486even when there is in fact no problem because @code{longjmp} cannot
2487in fact be called at the place which would cause a problem.
2488
2489Some spurious warnings can be avoided if you declare all the functions
2490you use that never return as @code{noreturn}. @xref{Function
2491Attributes}.
2492
2493This warning is enabled by @option{-Wall}.
2494
2495@item -Wunknown-pragmas
2496@opindex Wunknown-pragmas
2497@cindex warning for unknown pragmas
2498@cindex unknown pragmas, warning
2499@cindex pragmas, warning of unknown
2500Warn when a #pragma directive is encountered which is not understood by
2501GCC@. If this command line option is used, warnings will even be issued
2502for unknown pragmas in system header files. This is not the case if
2503the warnings were only enabled by the @option{-Wall} command line option.
2504
2505@item -Wno-pragmas
2506@opindex Wno-pragmas
2507@opindex Wpragmas
2508Do not warn about misuses of pragmas, such as incorrect parameters,
2509invalid syntax, or conflicts between pragmas. See also
2510@samp{-Wunknown-pragmas}.
2511
2512@item -Wstrict-aliasing
2513@opindex Wstrict-aliasing
2514This option is only active when @option{-fstrict-aliasing} is active.
2515It warns about code which might break the strict aliasing rules that the
2516compiler is using for optimization. The warning does not catch all
2517cases, but does attempt to catch the more common pitfalls. It is
2518included in @option{-Wall}.
2519It is equivalent to -Wstrict-aliasing=3
2520
2521@item -Wstrict-aliasing=n
2522@opindex Wstrict-aliasing=n
2523This option is only active when @option{-fstrict-aliasing} is active.
2524It warns about code which might break the strict aliasing rules that the
2525compiler is using for optimization.
2526Higher levels correspond to higher accuracy (fewer false positives).
2527Higher levels also correspond to more effort, similar to the way -O works.
2528@option{-Wstrict-aliasing} is equivalent to @option{-Wstrict-aliasing=n},
2529with n=3.
2530
2531Level 1: Most aggressive, quick, least accurate.
2532Possibly useful when higher levels
2533do not warn but -fstrict-aliasing still breaks the code, as it has very few
2534false negatives. However, it has many false positives.
2535Warns for all pointer conversions between possibly incompatible types,
2536even if never dereferenced. Runs in the frontend only.
2537
2538Level 2: Aggressive, quick, not too precise.
2539May still have many false positives (not as many as level 1 though),
2540and few false negatives (but possibly more than level 1).
2541Unlike level 1, it only warns when an address is taken. Warns about
2542incomplete types. Runs in the frontend only.
2543
2544Level 3 (default for @option{-Wstrict-aliasing}):
2545Should have very few false positives and few false
2546negatives. Slightly slower than levels 1 or 2 when optimization is enabled.
2547Takes care of the common punn+dereference pattern in the frontend:
2548@code{*(int*)&some_float}.
2549If optimization is enabled, it also runs in the backend, where it deals
2550with multiple statement cases using flow-sensitive points-to information.
2551Only warns when the converted pointer is dereferenced.
2552Does not warn about incomplete types.
2553
2554@item -Wstrict-overflow
2555@item -Wstrict-overflow=@var{n}
2556@opindex Wstrict-overflow
2557This option is only active when @option{-fstrict-overflow} is active.
2558It warns about cases where the compiler optimizes based on the
2559assumption that signed overflow does not occur. Note that it does not
2560warn about all cases where the code might overflow: it only warns
2561about cases where the compiler implements some optimization. Thus
2562this warning depends on the optimization level.
2563
2564An optimization which assumes that signed overflow does not occur is
2565perfectly safe if the values of the variables involved are such that
2566overflow never does, in fact, occur. Therefore this warning can
2567easily give a false positive: a warning about code which is not
2568actually a problem. To help focus on important issues, several
2569warning levels are defined. No warnings are issued for the use of
2570undefined signed overflow when estimating how many iterations a loop
2571will require, in particular when determining whether a loop will be
2572executed at all.
2573
2574@table @option
2575@item -Wstrict-overflow=1
2576Warn about cases which are both questionable and easy to avoid. For
2577example: @code{x + 1 > x}; with @option{-fstrict-overflow}, the
2578compiler will simplify this to @code{1}. This level of
2579@option{-Wstrict-overflow} is enabled by @option{-Wall}; higher levels
2580are not, and must be explicitly requested.
2581
2582@item -Wstrict-overflow=2
2583Also warn about other cases where a comparison is simplified to a
2584constant. For example: @code{abs (x) >= 0}. This can only be
2585simplified when @option{-fstrict-overflow} is in effect, because
2586@code{abs (INT_MIN)} overflows to @code{INT_MIN}, which is less than
2587zero. @option{-Wstrict-overflow} (with no level) is the same as
2588@option{-Wstrict-overflow=2}.
2589
2590@item -Wstrict-overflow=3
2591Also warn about other cases where a comparison is simplified. For
2592example: @code{x + 1 > 1} will be simplified to @code{x > 0}.
2593
2594@item -Wstrict-overflow=4
2595Also warn about other simplifications not covered by the above cases.
2596For example: @code{(x * 10) / 5} will be simplified to @code{x * 2}.
2597
2598@item -Wstrict-overflow=5
2599Also warn about cases where the compiler reduces the magnitude of a
2600constant involved in a comparison. For example: @code{x + 2 > y} will
2601be simplified to @code{x + 1 >= y}. This is reported only at the
2602highest warning level because this simplification applies to many
2603comparisons, so this warning level will give a very large number of
2604false positives.
2605@end table
2606
2607@item -Wall
2608@opindex Wall
2609All of the above @samp{-W} options combined. This enables all the
2610warnings about constructions that some users consider questionable, and
2611that are easy to avoid (or modify to prevent the warning), even in
2612conjunction with macros. This also enables some language-specific
2613warnings described in @ref{C++ Dialect Options}.
2614@end table
2615
2616The following @option{-W@dots{}} options are not implied by @option{-Wall}.
2617Some of them warn about constructions that users generally do not
2618consider questionable, but which occasionally you might wish to check
2619for; others warn about constructions that are necessary or hard to avoid
2620in some cases, and there is no simple way to modify the code to suppress
2621the warning.
2622
2623@table @gcctabopt
2624@item -Wextra
2625@opindex W
2626@opindex Wextra
2627(This option used to be called @option{-W}. The older name is still
2628supported, but the newer name is more descriptive.) Print extra warning
2629messages for these events:
2630
2631@itemize @bullet
2632@item
2633A function can return either with or without a value. (Falling
2634off the end of the function body is considered returning without
2635a value.) For example, this function would evoke such a
2636warning:
2637
2638@smallexample
2639@group
2640foo (a)
2641@{
2642 if (a > 0)
2643 return a;
2644@}
2645@end group
2646@end smallexample
2647
2648@item
2649An expression-statement or the left-hand side of a comma expression
2650contains no side effects.
2651To suppress the warning, cast the unused expression to void.
2652For example, an expression such as @samp{x[i,j]} will cause a warning,
2653but @samp{x[(void)i,j]} will not.
2654
2655@item
2656An unsigned value is compared against zero with @samp{<} or @samp{>=}.
2657
2658@item
2659Storage-class specifiers like @code{static} are not the first things in
2660a declaration. According to the C Standard, this usage is obsolescent.
2661
2662@item
2663If @option{-Wall} or @option{-Wunused} is also specified, warn about unused
2664arguments.
2665
2666@item
2667A comparison between signed and unsigned values could produce an
2668incorrect result when the signed value is converted to unsigned.
2669(But don't warn if @option{-Wno-sign-compare} is also specified.)
2670
2671@item
2672An aggregate has an initializer which does not initialize all members.
2673This warning can be independently controlled by
2674@option{-Wmissing-field-initializers}.
2675
2676@item
2677An initialized field without side effects is overridden when using
2678designated initializers (@pxref{Designated Inits, , Designated
2679Initializers}). This warning can be independently controlled by
2680@option{-Woverride-init}.
2681
2682@item
2683A function parameter is declared without a type specifier in K&R-style
2684functions:
2685
2686@smallexample
2687void foo(bar) @{ @}
2688@end smallexample
2689
2690@item
2691An empty body occurs in an @samp{if} or @samp{else} statement.
2692
2693@item
2694A pointer is compared against integer zero with @samp{<}, @samp{<=},
2695@samp{>}, or @samp{>=}.
2696
2697@item
2698A variable might be changed by @samp{longjmp} or @samp{vfork}.
2699
2700@item @r{(C++ only)}
2701An enumerator and a non-enumerator both appear in a conditional expression.
2702
2703@item @r{(C++ only)}
2704A non-static reference or non-static @samp{const} member appears in a
2705class without constructors.
2706
2707@item @r{(C++ only)}
2708Ambiguous virtual bases.
2709
2710@item @r{(C++ only)}
2711Subscripting an array which has been declared @samp{register}.
2712
2713@item @r{(C++ only)}
2714Taking the address of a variable which has been declared @samp{register}.
2715
2716@item @r{(C++ only)}
2717A base class is not initialized in a derived class' copy constructor.
2718@end itemize
2719
2720@item -Wno-div-by-zero
2721@opindex Wno-div-by-zero
2722@opindex Wdiv-by-zero
2723Do not warn about compile-time integer division by zero. Floating point
2724division by zero is not warned about, as it can be a legitimate way of
2725obtaining infinities and NaNs.
2726
2727@item -Wsystem-headers
2728@opindex Wsystem-headers
2729@cindex warnings from system headers
2730@cindex system headers, warnings from
2731Print warning messages for constructs found in system header files.
2732Warnings from system headers are normally suppressed, on the assumption
2733that they usually do not indicate real problems and would only make the
2734compiler output harder to read. Using this command line option tells
2735GCC to emit warnings from system headers as if they occurred in user
2736code. However, note that using @option{-Wall} in conjunction with this
2737option will @emph{not} warn about unknown pragmas in system
2738headers---for that, @option{-Wunknown-pragmas} must also be used.
2739
2740@item -Wfloat-equal
2741@opindex Wfloat-equal
2742Warn if floating point values are used in equality comparisons.
2743
2744The idea behind this is that sometimes it is convenient (for the
2745programmer) to consider floating-point values as approximations to
2746infinitely precise real numbers. If you are doing this, then you need
2747to compute (by analyzing the code, or in some other way) the maximum or
2748likely maximum error that the computation introduces, and allow for it
2749when performing comparisons (and when producing output, but that's a
2750different problem). In particular, instead of testing for equality, you
2751would check to see whether the two values have ranges that overlap; and
2752this is done with the relational operators, so equality comparisons are
2753probably mistaken.
2754
2755@item -Wtraditional @r{(C only)}
2756@opindex Wtraditional
2757Warn about certain constructs that behave differently in traditional and
2758ISO C@. Also warn about ISO C constructs that have no traditional C
2759equivalent, and/or problematic constructs which should be avoided.
2760
2761@itemize @bullet
2762@item
2763Macro parameters that appear within string literals in the macro body.
2764In traditional C macro replacement takes place within string literals,
2765but does not in ISO C@.
2766
2767@item
2768In traditional C, some preprocessor directives did not exist.
2769Traditional preprocessors would only consider a line to be a directive
2770if the @samp{#} appeared in column 1 on the line. Therefore
2771@option{-Wtraditional} warns about directives that traditional C
2772understands but would ignore because the @samp{#} does not appear as the
2773first character on the line. It also suggests you hide directives like
2774@samp{#pragma} not understood by traditional C by indenting them. Some
2775traditional implementations would not recognize @samp{#elif}, so it
2776suggests avoiding it altogether.
2777
2778@item
2779A function-like macro that appears without arguments.
2780
2781@item
2782The unary plus operator.
2783
2784@item
2785The @samp{U} integer constant suffix, or the @samp{F} or @samp{L} floating point
2786constant suffixes. (Traditional C does support the @samp{L} suffix on integer
2787constants.) Note, these suffixes appear in macros defined in the system
2788headers of most modern systems, e.g.@: the @samp{_MIN}/@samp{_MAX} macros in @code{<limits.h>}.
2789Use of these macros in user code might normally lead to spurious
2790warnings, however GCC's integrated preprocessor has enough context to
2791avoid warning in these cases.
2792
2793@item
2794A function declared external in one block and then used after the end of
2795the block.
2796
2797@item
2798A @code{switch} statement has an operand of type @code{long}.
2799
2800@item
2801A non-@code{static} function declaration follows a @code{static} one.
2802This construct is not accepted by some traditional C compilers.
2803
2804@item
2805The ISO type of an integer constant has a different width or
2806signedness from its traditional type. This warning is only issued if
2807the base of the constant is ten. I.e.@: hexadecimal or octal values, which
2808typically represent bit patterns, are not warned about.
2809
2810@item
2811Usage of ISO string concatenation is detected.
2812
2813@item
2814Initialization of automatic aggregates.
2815
2816@item
2817Identifier conflicts with labels. Traditional C lacks a separate
2818namespace for labels.
2819
2820@item
2821Initialization of unions. If the initializer is zero, the warning is
2822omitted. This is done under the assumption that the zero initializer in
2823user code appears conditioned on e.g.@: @code{__STDC__} to avoid missing
2824initializer warnings and relies on default initialization to zero in the
2825traditional C case.
2826
2827@item
2828Conversions by prototypes between fixed/floating point values and vice
2829versa. The absence of these prototypes when compiling with traditional
2830C would cause serious problems. This is a subset of the possible
2831conversion warnings, for the full set use @option{-Wconversion}.
2832
2833@item
2834Use of ISO C style function definitions. This warning intentionally is
2835@emph{not} issued for prototype declarations or variadic functions
2836because these ISO C features will appear in your code when using
2837libiberty's traditional C compatibility macros, @code{PARAMS} and
2838@code{VPARAMS}. This warning is also bypassed for nested functions
2839because that feature is already a GCC extension and thus not relevant to
2840traditional C compatibility.
2841@end itemize
2842
2843@item -Wdeclaration-after-statement @r{(C only)}
2844@opindex Wdeclaration-after-statement
2845Warn when a declaration is found after a statement in a block. This
2846construct, known from C++, was introduced with ISO C99 and is by default
2847allowed in GCC@. It is not supported by ISO C90 and was not supported by
2848GCC versions before GCC 3.0. @xref{Mixed Declarations}.
2849
2850@item -Wundef
2851@opindex Wundef
2852Warn if an undefined identifier is evaluated in an @samp{#if} directive.
2853
2854@item -Wno-endif-labels
2855@opindex Wno-endif-labels
2856@opindex Wendif-labels
2857Do not warn whenever an @samp{#else} or an @samp{#endif} are followed by text.
2858
2859@item -Wshadow
2860@opindex Wshadow
2861Warn whenever a local variable shadows another local variable, parameter or
2862global variable or whenever a built-in function is shadowed.
2863
2864@item -Wlarger-than-@var{len}
2865@opindex Wlarger-than
2866Warn whenever an object of larger than @var{len} bytes is defined.
2867
2868@item -Wframe-larger-than-@var{len}
2869@opindex Wframe-larger-than
2870Warn whenever the frame size of a function is larger than @var{len} bytes.
2871
2872@item -Wunsafe-loop-optimizations
2873@opindex Wunsafe-loop-optimizations
2874Warn if the loop cannot be optimized because the compiler could not
2875assume anything on the bounds of the loop indices. With
2876@option{-funsafe-loop-optimizations} warn if the compiler made
2877such assumptions.
2878
2879@item -Wpointer-arith
2880@opindex Wpointer-arith
2881Warn about anything that depends on the ``size of'' a function type or
2882of @code{void}. GNU C assigns these types a size of 1, for
2883convenience in calculations with @code{void *} pointers and pointers
2884to functions.
2885
2886@item -Wbad-function-cast @r{(C only)}
2887@opindex Wbad-function-cast
2888Warn whenever a function call is cast to a non-matching type.
2889For example, warn if @code{int malloc()} is cast to @code{anything *}.
2890
2891@item -Wc++-compat
2892Warn about ISO C constructs that are outside of the common subset of
2893ISO C and ISO C++, e.g.@: request for implicit conversion from
2894@code{void *} to a pointer to non-@code{void} type.
2895
2896@item -Wcast-qual
2897@opindex Wcast-qual
2898Warn whenever a pointer is cast so as to remove a type qualifier from
2899the target type. For example, warn if a @code{const char *} is cast
2900to an ordinary @code{char *}.
2901
2902@item -Wcast-align
2903@opindex Wcast-align
2904Warn whenever a pointer is cast such that the required alignment of the
2905target is increased. For example, warn if a @code{char *} is cast to
2906an @code{int *} on machines where integers can only be accessed at
2907two- or four-byte boundaries.
2908
2909@item -Wwrite-strings
2910@opindex Wwrite-strings
2911When compiling C, give string constants the type @code{const
2912char[@var{length}]} so that
2913copying the address of one into a non-@code{const} @code{char *}
2914pointer will get a warning; when compiling C++, warn about the
2915deprecated conversion from string literals to @code{char *}. This
2916warning, by default, is enabled for C++ programs.
2917These warnings will help you find at
2918compile time code that can try to write into a string constant, but
2919only if you have been very careful about using @code{const} in
2920declarations and prototypes. Otherwise, it will just be a nuisance;
2921this is why we did not make @option{-Wall} request these warnings.
2922
2923@item -Wconversion
2924@opindex Wconversion
2925Warn if a prototype causes a type conversion that is different from what
2926would happen to the same argument in the absence of a prototype. This
2927includes conversions of fixed point to floating and vice versa, and
2928conversions changing the width or signedness of a fixed point argument
2929except when the same as the default promotion.
2930
2931Also, warn if a negative integer constant expression is implicitly
2932converted to an unsigned type. For example, warn about the assignment
2933@code{x = -1} if @code{x} is unsigned. But do not warn about explicit
2934casts like @code{(unsigned) -1}.
2935
2936@item -Wsign-compare
2937@opindex Wsign-compare
2938@cindex warning for comparison of signed and unsigned values
2939@cindex comparison of signed and unsigned values, warning
2940@cindex signed and unsigned values, comparison warning
2941Warn when a comparison between signed and unsigned values could produce
2942an incorrect result when the signed value is converted to unsigned.
2943This warning is also enabled by @option{-Wextra}; to get the other warnings
2944of @option{-Wextra} without this warning, use @samp{-Wextra -Wno-sign-compare}.
2945
2946@item -Waddress
2947@opindex Waddress
2948@opindex Wno-address
2949Warn about suspicious uses of memory addresses. These include using
2950the address of a function in a conditional expression, such as
2951@code{void func(void); if (func)}, and comparisons against the memory
2952address of a string literal, such as @code{if (x == "abc")}. Such
2953uses typically indicate a programmer error: the address of a function
2954always evaluates to true, so their use in a conditional usually
2955indicate that the programmer forgot the parentheses in a function
2956call; and comparisons against string literals result in unspecified
2957behavior and are not portable in C, so they usually indicate that the
2958programmer intended to use @code{strcmp}. This warning is enabled by
2959@option{-Wall}.
2960
2961@item -Waggregate-return
2962@opindex Waggregate-return
2963Warn if any functions that return structures or unions are defined or
2964called. (In languages where you can return an array, this also elicits
2965a warning.)
2966
2967@item -Wno-attributes
2968@opindex Wno-attributes
2969@opindex Wattributes
2970Do not warn if an unexpected @code{__attribute__} is used, such as
2971unrecognized attributes, function attributes applied to variables,
2972etc. This will not stop errors for incorrect use of supported
2973attributes.
2974
2975@item -Wstrict-prototypes @r{(C only)}
2976@opindex Wstrict-prototypes
2977Warn if a function is declared or defined without specifying the
2978argument types. (An old-style function definition is permitted without
2979a warning if preceded by a declaration which specifies the argument
2980types.)
2981
2982@item -Wold-style-definition @r{(C only)}
2983@opindex Wold-style-definition
2984Warn if an old-style function definition is used. A warning is given
2985even if there is a previous prototype.
2986
2987@item -Wmissing-prototypes @r{(C only)}
2988@opindex Wmissing-prototypes
2989Warn if a global function is defined without a previous prototype
2990declaration. This warning is issued even if the definition itself
2991provides a prototype. The aim is to detect global functions that fail
2992to be declared in header files.
2993
2994@item -Wmissing-declarations @r{(C only)}
2995@opindex Wmissing-declarations
2996Warn if a global function is defined without a previous declaration.
2997Do so even if the definition itself provides a prototype.
2998Use this option to detect global functions that are not declared in
2999header files.
3000
3001@item -Wmissing-field-initializers
3002@opindex Wmissing-field-initializers
3003@opindex W
3004@opindex Wextra
3005Warn if a structure's initializer has some fields missing. For
3006example, the following code would cause such a warning, because
3007@code{x.h} is implicitly zero:
3008
3009@smallexample
3010struct s @{ int f, g, h; @};
3011struct s x = @{ 3, 4 @};
3012@end smallexample
3013
3014This option does not warn about designated initializers, so the following
3015modification would not trigger a warning:
3016
3017@smallexample
3018struct s @{ int f, g, h; @};
3019struct s x = @{ .f = 3, .g = 4 @};
3020@end smallexample
3021
3022This warning is included in @option{-Wextra}. To get other @option{-Wextra}
3023warnings without this one, use @samp{-Wextra -Wno-missing-field-initializers}.
3024
3025@item -Wmissing-noreturn
3026@opindex Wmissing-noreturn
3027Warn about functions which might be candidates for attribute @code{noreturn}.
3028Note these are only possible candidates, not absolute ones. Care should
3029be taken to manually verify functions actually do not ever return before
3030adding the @code{noreturn} attribute, otherwise subtle code generation
3031bugs could be introduced. You will not get a warning for @code{main} in
3032hosted C environments.
3033
3034@item -Wmissing-format-attribute
3035@opindex Wmissing-format-attribute
3036@opindex Wformat
3037Warn about function pointers which might be candidates for @code{format}
3038attributes. Note these are only possible candidates, not absolute ones.
3039GCC will guess that function pointers with @code{format} attributes that
3040are used in assignment, initialization, parameter passing or return
3041statements should have a corresponding @code{format} attribute in the
3042resulting type. I.e.@: the left-hand side of the assignment or
3043initialization, the type of the parameter variable, or the return type
3044of the containing function respectively should also have a @code{format}
3045attribute to avoid the warning.
3046
3047GCC will also warn about function definitions which might be
3048candidates for @code{format} attributes. Again, these are only
3049possible candidates. GCC will guess that @code{format} attributes
3050might be appropriate for any function that calls a function like
3051@code{vprintf} or @code{vscanf}, but this might not always be the
3052case, and some functions for which @code{format} attributes are
3053appropriate may not be detected.
3054
3055@item -Wno-multichar
3056@opindex Wno-multichar
3057@opindex Wmultichar
3058Do not warn if a multicharacter constant (@samp{'FOOF'}) is used.
3059Usually they indicate a typo in the user's code, as they have
3060implementation-defined values, and should not be used in portable code.
3061
3062@item -Wnormalized=<none|id|nfc|nfkc>
3063@opindex Wnormalized
3064@cindex NFC
3065@cindex NFKC
3066@cindex character set, input normalization
3067In ISO C and ISO C++, two identifiers are different if they are
3068different sequences of characters. However, sometimes when characters
3069outside the basic ASCII character set are used, you can have two
3070different character sequences that look the same. To avoid confusion,
3071the ISO 10646 standard sets out some @dfn{normalization rules} which
3072when applied ensure that two sequences that look the same are turned into
3073the same sequence. GCC can warn you if you are using identifiers which
3074have not been normalized; this option controls that warning.
3075
3076There are four levels of warning that GCC supports. The default is
3077@option{-Wnormalized=nfc}, which warns about any identifier which is
3078not in the ISO 10646 ``C'' normalized form, @dfn{NFC}. NFC is the
3079recommended form for most uses.
3080
3081Unfortunately, there are some characters which ISO C and ISO C++ allow
3082in identifiers that when turned into NFC aren't allowable as
3083identifiers. That is, there's no way to use these symbols in portable
3084ISO C or C++ and have all your identifiers in NFC.
3085@option{-Wnormalized=id} suppresses the warning for these characters.
3086It is hoped that future versions of the standards involved will correct
3087this, which is why this option is not the default.
3088
3089You can switch the warning off for all characters by writing
3090@option{-Wnormalized=none}. You would only want to do this if you
3091were using some other normalization scheme (like ``D''), because
3092otherwise you can easily create bugs that are literally impossible to see.
3093
3094Some characters in ISO 10646 have distinct meanings but look identical
3095in some fonts or display methodologies, especially once formatting has
3096been applied. For instance @code{\u207F}, ``SUPERSCRIPT LATIN SMALL
3097LETTER N'', will display just like a regular @code{n} which has been
3098placed in a superscript. ISO 10646 defines the @dfn{NFKC}
3099normalization scheme to convert all these into a standard form as
3100well, and GCC will warn if your code is not in NFKC if you use
3101@option{-Wnormalized=nfkc}. This warning is comparable to warning
3102about every identifier that contains the letter O because it might be
3103confused with the digit 0, and so is not the default, but may be
3104useful as a local coding convention if the programming environment is
3105unable to be fixed to display these characters distinctly.
3106
3107@item -Wno-deprecated-declarations
3108@opindex Wno-deprecated-declarations
3109Do not warn about uses of functions (@pxref{Function Attributes}),
3110variables (@pxref{Variable Attributes}), and types (@pxref{Type
3111Attributes}) marked as deprecated by using the @code{deprecated}
3112attribute.
3113
3114@item -Wno-overflow
3115@opindex Wno-overflow
3116Do not warn about compile-time overflow in constant expressions.
3117
3118@item -Woverride-init
3119@opindex Woverride-init
3120@opindex W
3121@opindex Wextra
3122Warn if an initialized field without side effects is overridden when
3123using designated initializers (@pxref{Designated Inits, , Designated
3124Initializers}).
3125
3126This warning is included in @option{-Wextra}. To get other
3127@option{-Wextra} warnings without this one, use @samp{-Wextra
3128-Wno-override-init}.
3129
3130@item -Wpacked
3131@opindex Wpacked
3132Warn if a structure is given the packed attribute, but the packed
3133attribute has no effect on the layout or size of the structure.
3134Such structures may be mis-aligned for little benefit. For
3135instance, in this code, the variable @code{f.x} in @code{struct bar}
3136will be misaligned even though @code{struct bar} does not itself
3137have the packed attribute:
3138
3139@smallexample
3140@group
3141struct foo @{
3142 int x;
3143 char a, b, c, d;
3144@} __attribute__((packed));
3145struct bar @{
3146 char z;
3147 struct foo f;
3148@};
3149@end group
3150@end smallexample
3151
3152@item -Wpadded
3153@opindex Wpadded
3154Warn if padding is included in a structure, either to align an element
3155of the structure or to align the whole structure. Sometimes when this
3156happens it is possible to rearrange the fields of the structure to
3157reduce the padding and so make the structure smaller.
3158
3159@item -Wredundant-decls
3160@opindex Wredundant-decls
3161Warn if anything is declared more than once in the same scope, even in
3162cases where multiple declaration is valid and changes nothing.
3163
3164@item -Wnested-externs @r{(C only)}
3165@opindex Wnested-externs
3166Warn if an @code{extern} declaration is encountered within a function.
3167
3168@item -Wunreachable-code
3169@opindex Wunreachable-code
3170Warn if the compiler detects that code will never be executed.
3171
3172This option is intended to warn when the compiler detects that at
3173least a whole line of source code will never be executed, because
3174some condition is never satisfied or because it is after a
3175procedure that never returns.
3176
3177It is possible for this option to produce a warning even though there
3178are circumstances under which part of the affected line can be executed,
3179so care should be taken when removing apparently-unreachable code.
3180
3181For instance, when a function is inlined, a warning may mean that the
3182line is unreachable in only one inlined copy of the function.
3183
3184This option is not made part of @option{-Wall} because in a debugging
3185version of a program there is often substantial code which checks
3186correct functioning of the program and is, hopefully, unreachable
3187because the program does work. Another common use of unreachable
3188code is to provide behavior which is selectable at compile-time.
3189
3190@item -Winline
3191@opindex Winline
3192Warn if a function can not be inlined and it was declared as inline.
3193Even with this option, the compiler will not warn about failures to
3194inline functions declared in system headers.
3195
3196The compiler uses a variety of heuristics to determine whether or not
3197to inline a function. For example, the compiler takes into account
3198the size of the function being inlined and the amount of inlining
3199that has already been done in the current function. Therefore,
3200seemingly insignificant changes in the source program can cause the
3201warnings produced by @option{-Winline} to appear or disappear.
3202
3203@item -Wno-invalid-offsetof @r{(C++ only)}
3204@opindex Wno-invalid-offsetof
3205Suppress warnings from applying the @samp{offsetof} macro to a non-POD
3206type. According to the 1998 ISO C++ standard, applying @samp{offsetof}
3207to a non-POD type is undefined. In existing C++ implementations,
3208however, @samp{offsetof} typically gives meaningful results even when
3209applied to certain kinds of non-POD types. (Such as a simple
3210@samp{struct} that fails to be a POD type only by virtue of having a
3211constructor.) This flag is for users who are aware that they are
3212writing nonportable code and who have deliberately chosen to ignore the
3213warning about it.
3214
3215The restrictions on @samp{offsetof} may be relaxed in a future version
3216of the C++ standard.
3217
3218@item -Wno-int-to-pointer-cast @r{(C only)}
3219@opindex Wno-int-to-pointer-cast
3220Suppress warnings from casts to pointer type of an integer of a
3221different size.
3222
3223@item -Wno-pointer-to-int-cast @r{(C only)}
3224@opindex Wno-pointer-to-int-cast
3225Suppress warnings from casts from a pointer to an integer type of a
3226different size.
3227
3228@item -Winvalid-pch
3229@opindex Winvalid-pch
3230Warn if a precompiled header (@pxref{Precompiled Headers}) is found in
3231the search path but can't be used.
3232
3233@item -Wlong-long
3234@opindex Wlong-long
3235@opindex Wno-long-long
3236Warn if @samp{long long} type is used. This is default. To inhibit
3237the warning messages, use @option{-Wno-long-long}. Flags
3238@option{-Wlong-long} and @option{-Wno-long-long} are taken into account
3239only when @option{-pedantic} flag is used.
3240
3241@item -Wvariadic-macros
3242@opindex Wvariadic-macros
3243@opindex Wno-variadic-macros
3244Warn if variadic macros are used in pedantic ISO C90 mode, or the GNU
3245alternate syntax when in pedantic ISO C99 mode. This is default.
3246To inhibit the warning messages, use @option{-Wno-variadic-macros}.
3247
3248@item -Wvla
3249@opindex Wvla
3250@opindex Wno-vla
3251Warn if variable length array is used in the code.
3252@option{-Wno-vla} will prevent the @option{-pedantic} warning of
3253the variable length array.
3254
3255@item -Wvolatile-register-var
3256@opindex Wvolatile-register-var
3257@opindex Wno-volatile-register-var
3258Warn if a register variable is declared volatile. The volatile
3259modifier does not inhibit all optimizations that may eliminate reads
3260and/or writes to register variables.
3261
3262@item -Wdisabled-optimization
3263@opindex Wdisabled-optimization
3264Warn if a requested optimization pass is disabled. This warning does
3265not generally indicate that there is anything wrong with your code; it
3266merely indicates that GCC's optimizers were unable to handle the code
3267effectively. Often, the problem is that your code is too big or too
3268complex; GCC will refuse to optimize programs when the optimization
3269itself is likely to take inordinate amounts of time.
3270
3271@item -Wpointer-sign
3272@opindex Wpointer-sign
3273@opindex Wno-pointer-sign
3274Warn for pointer argument passing or assignment with different signedness.
3275This option is only supported for C. It is implied by @option{-Wall}
3276and by @option{-pedantic}, which can be disabled with
3277@option{-Wno-pointer-sign}.
3278
3279@item -Werror
3280@opindex Werror
3281Make all warnings into errors.
3282
3283@item -Werror=
3284@opindex Werror=
3285Make the specified warning into an errors. The specifier for a
3286warning is appended, for example @option{-Werror=switch} turns the
3287warnings controlled by @option{-Wswitch} into errors. This switch
3288takes a negative form, to be used to negate @option{-Werror} for
3289specific warnings, for example @option{-Wno-error=switch} makes
3290@option{-Wswitch} warnings not be errors, even when @option{-Werror}
3291is in effect. You can use the @option{-fdiagnostics-show-option}
3292option to have each controllable warning amended with the option which
3293controls it, to determine what to use with this option.
3294
3295Note that specifying @option{-Werror=}@var{foo} automatically implies
3296@option{-W}@var{foo}. However, @option{-Wno-error=}@var{foo} does not
3297imply anything.
3298
3299@item -Wstack-protector
3300@opindex Wstack-protector
3301This option is only active when @option{-fstack-protector} is active. It
3302warns about functions that will not be protected against stack smashing.
3303
3304@item -Woverlength-strings
3305@opindex Woverlength-strings
3306Warn about string constants which are longer than the ``minimum
3307maximum'' length specified in the C standard. Modern compilers
3308generally allow string constants which are much longer than the
3309standard's minimum limit, but very portable programs should avoid
3310using longer strings.
3311
3312The limit applies @emph{after} string constant concatenation, and does
3313not count the trailing NUL@. In C89, the limit was 509 characters; in
3314C99, it was raised to 4095. C++98 does not specify a normative
3315minimum maximum, so we do not diagnose overlength strings in C++@.
3316
3317This option is implied by @option{-pedantic}, and can be disabled with
3318@option{-Wno-overlength-strings}.
3319@end table
3320
3321@node Debugging Options
3322@section Options for Debugging Your Program or GCC
3323@cindex options, debugging
3324@cindex debugging information options
3325
3326GCC has various special options that are used for debugging
3327either your program or GCC:
3328
3329@table @gcctabopt
3330@item -g
3331@opindex g
3332Produce debugging information in the operating system's native format
3333(stabs, COFF, XCOFF, or DWARF 2)@. GDB can work with this debugging
3334information.
3335
3336On most systems that use stabs format, @option{-g} enables use of extra
3337debugging information that only GDB can use; this extra information
3338makes debugging work better in GDB but will probably make other debuggers
3339crash or
3340refuse to read the program. If you want to control for certain whether
3341to generate the extra information, use @option{-gstabs+}, @option{-gstabs},
3342@option{-gxcoff+}, @option{-gxcoff}, or @option{-gvms} (see below).
3343
3344GCC allows you to use @option{-g} with
3345@option{-O}. The shortcuts taken by optimized code may occasionally
3346produce surprising results: some variables you declared may not exist
3347at all; flow of control may briefly move where you did not expect it;
3348some statements may not be executed because they compute constant
3349results or their values were already at hand; some statements may
3350execute in different places because they were moved out of loops.
3351
3352Nevertheless it proves possible to debug optimized output. This makes
3353it reasonable to use the optimizer for programs that might have bugs.
3354
3355The following options are useful when GCC is generated with the
3356capability for more than one debugging format.
3357
3358@item -ggdb
3359@opindex ggdb
3360Produce debugging information for use by GDB@. This means to use the
3361most expressive format available (DWARF 2, stabs, or the native format
3362if neither of those are supported), including GDB extensions if at all
3363possible.
3364
3365@item -gstabs
3366@opindex gstabs
3367Produce debugging information in stabs format (if that is supported),
3368without GDB extensions. This is the format used by DBX on most BSD
3369systems. On MIPS, Alpha and System V Release 4 systems this option
3370produces stabs debugging output which is not understood by DBX or SDB@.
3371On System V Release 4 systems this option requires the GNU assembler.
3372
3373@item -feliminate-unused-debug-symbols
3374@opindex feliminate-unused-debug-symbols
3375Produce debugging information in stabs format (if that is supported),
3376for only symbols that are actually used.
3377
3378@item -femit-class-debug-always
3379Instead of emitting debugging information for a C++ class in only one
3380object file, emit it in all object files using the class. This option
3381should be used only with debuggers that are unable to handle the way GCC
3382normally emits debugging information for classes because using this
3383option will increase the size of debugging information by as much as a
3384factor of two.
3385
3386@item -gstabs+
3387@opindex gstabs+
3388Produce debugging information in stabs format (if that is supported),
3389using GNU extensions understood only by the GNU debugger (GDB)@. The
3390use of these extensions is likely to make other debuggers crash or
3391refuse to read the program.
3392
3393@item -gcoff
3394@opindex gcoff
3395Produce debugging information in COFF format (if that is supported).
3396This is the format used by SDB on most System V systems prior to
3397System V Release 4.
3398
3399@item -gxcoff
3400@opindex gxcoff
3401Produce debugging information in XCOFF format (if that is supported).
3402This is the format used by the DBX debugger on IBM RS/6000 systems.
3403
3404@item -gxcoff+
3405@opindex gxcoff+
3406Produce debugging information in XCOFF format (if that is supported),
3407using GNU extensions understood only by the GNU debugger (GDB)@. The
3408use of these extensions is likely to make other debuggers crash or
3409refuse to read the program, and may cause assemblers other than the GNU
3410assembler (GAS) to fail with an error.
3411
3412@item -gdwarf-2
3413@opindex gdwarf-2
3414Produce debugging information in DWARF version 2 format (if that is
3415supported). This is the format used by DBX on IRIX 6. With this
3416option, GCC uses features of DWARF version 3 when they are useful;
3417version 3 is upward compatible with version 2, but may still cause
3418problems for older debuggers.
3419
3420@item -gvms
3421@opindex gvms
3422Produce debugging information in VMS debug format (if that is
3423supported). This is the format used by DEBUG on VMS systems.
3424
3425@item -g@var{level}
3426@itemx -ggdb@var{level}
3427@itemx -gstabs@var{level}
3428@itemx -gcoff@var{level}
3429@itemx -gxcoff@var{level}
3430@itemx -gvms@var{level}
3431Request debugging information and also use @var{level} to specify how
3432much information. The default level is 2.
3433
3434Level 1 produces minimal information, enough for making backtraces in
3435parts of the program that you don't plan to debug. This includes
3436descriptions of functions and external variables, but no information
3437about local variables and no line numbers.
3438
3439Level 3 includes extra information, such as all the macro definitions
3440present in the program. Some debuggers support macro expansion when
3441you use @option{-g3}.
3442
3443@option{-gdwarf-2} does not accept a concatenated debug level, because
3444GCC used to support an option @option{-gdwarf} that meant to generate
3445debug information in version 1 of the DWARF format (which is very
3446different from version 2), and it would have been too confusing. That
3447debug format is long obsolete, but the option cannot be changed now.
3448Instead use an additional @option{-g@var{level}} option to change the
3449debug level for DWARF2.
3450
3451@item -feliminate-dwarf2-dups
3452@opindex feliminate-dwarf2-dups
3453Compress DWARF2 debugging information by eliminating duplicated
3454information about each symbol. This option only makes sense when
3455generating DWARF2 debugging information with @option{-gdwarf-2}.
3456
3457@item -femit-struct-debug-baseonly
3458Emit debug information for struct-like types
3459only when the base name of the compilation source file
3460matches the base name of file in which the struct was defined.
3461
3462This option substantially reduces the size of debugging information,
3463but at significant potential loss in type information to the debugger.
3464See @option{-femit-struct-debug-reduced} for a less aggressive option.
3465See @option{-femit-struct-debug-detailed} for more detailed control.
3466
3467This option works only with DWARF 2.
3468
3469@item -femit-struct-debug-reduced
3470Emit debug information for struct-like types
3471only when the base name of the compilation source file
3472matches the base name of file in which the type was defined,
3473unless the struct is a template or defined in a system header.
3474
3475This option significantly reduces the size of debugging information,
3476with some potential loss in type information to the debugger.
3477See @option{-femit-struct-debug-baseonly} for a more aggressive option.
3478See @option{-femit-struct-debug-detailed} for more detailed control.
3479
3480This option works only with DWARF 2.
3481
3482@item -femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]}
3483Specify the struct-like types
3484for which the compiler will generate debug information.
3485The intent is to reduce duplicate struct debug information
3486between different object files within the same program.
3487
3488This option is a detailed version of
3489@option{-femit-struct-debug-reduced} and @option{-femit-struct-debug-baseonly},
3490which will serve for most needs.
3491
3492A specification has the syntax
3493[@samp{dir:}|@samp{ind:}][@samp{ord:}|@samp{gen:}](@samp{any}|@samp{sys}|@samp{base}|@samp{none})
3494
3495The optional first word limits the specification to
3496structs that are used directly (@samp{dir:}) or used indirectly (@samp{ind:}).
3497A struct type is used directly when it is the type of a variable, member.
3498Indirect uses arise through pointers to structs.
3499That is, when use of an incomplete struct would be legal, the use is indirect.
3500An example is
3501@samp{struct one direct; struct two * indirect;}.
3502
3503The optional second word limits the specification to
3504ordinary structs (@samp{ord:}) or generic structs (@samp{gen:}).
3505Generic structs are a bit complicated to explain.
3506For C++, these are non-explicit specializations of template classes,
3507or non-template classes within the above.
3508Other programming languages have generics,
3509but @samp{-femit-struct-debug-detailed} does not yet implement them.
3510
3511The third word specifies the source files for those
3512structs for which the compiler will emit debug information.
3513The values @samp{none} and @samp{any} have the normal meaning.
3514The value @samp{base} means that
3515the base of name of the file in which the type declaration appears
3516must match the base of the name of the main compilation file.
3517In practice, this means that
3518types declared in @file{foo.c} and @file{foo.h} will have debug information,
3519but types declared in other header will not.
3520The value @samp{sys} means those types satisfying @samp{base}
3521or declared in system or compiler headers.
3522
3523You may need to experiment to determine the best settings for your application.
3524
3525The default is @samp{-femit-struct-debug-detailed=all}.
3526
3527This option works only with DWARF 2.
3528
3529@cindex @command{prof}
3530@item -p
3531@opindex p
3532Generate extra code to write profile information suitable for the
3533analysis program @command{prof}. You must use this option when compiling
3534the source files you want data about, and you must also use it when
3535linking.
3536
3537@cindex @command{gprof}
3538@item -pg
3539@opindex pg
3540Generate extra code to write profile information suitable for the
3541analysis program @command{gprof}. You must use this option when compiling
3542the source files you want data about, and you must also use it when
3543linking.
3544
3545@item -Q
3546@opindex Q
3547Makes the compiler print out each function name as it is compiled, and
3548print some statistics about each pass when it finishes.
3549
3550@item -ftime-report
3551@opindex ftime-report
3552Makes the compiler print some statistics about the time consumed by each
3553pass when it finishes.
3554
3555@item -fmem-report
3556@opindex fmem-report
3557Makes the compiler print some statistics about permanent memory
3558allocation when it finishes.
3559
3560@item -fprofile-arcs
3561@opindex fprofile-arcs
3562Add code so that program flow @dfn{arcs} are instrumented. During
3563execution the program records how many times each branch and call is
3564executed and how many times it is taken or returns. When the compiled
3565program exits it saves this data to a file called
3566@file{@var{auxname}.gcda} for each source file. The data may be used for
3567profile-directed optimizations (@option{-fbranch-probabilities}), or for
3568test coverage analysis (@option{-ftest-coverage}). Each object file's
3569@var{auxname} is generated from the name of the output file, if
3570explicitly specified and it is not the final executable, otherwise it is
3571the basename of the source file. In both cases any suffix is removed
3572(e.g.@: @file{foo.gcda} for input file @file{dir/foo.c}, or
3573@file{dir/foo.gcda} for output file specified as @option{-o dir/foo.o}).
3574@xref{Cross-profiling}.
3575
3576@cindex @command{gcov}
3577@item --coverage
3578@opindex coverage
3579
3580This option is used to compile and link code instrumented for coverage
3581analysis. The option is a synonym for @option{-fprofile-arcs}
3582@option{-ftest-coverage} (when compiling) and @option{-lgcov} (when
3583linking). See the documentation for those options for more details.
3584
3585@itemize
3586
3587@item
3588Compile the source files with @option{-fprofile-arcs} plus optimization
3589and code generation options. For test coverage analysis, use the
3590additional @option{-ftest-coverage} option. You do not need to profile
3591every source file in a program.
3592
3593@item
3594Link your object files with @option{-lgcov} or @option{-fprofile-arcs}
3595(the latter implies the former).
3596
3597@item
3598Run the program on a representative workload to generate the arc profile
3599information. This may be repeated any number of times. You can run
3600concurrent instances of your program, and provided that the file system
3601supports locking, the data files will be correctly updated. Also
3602@code{fork} calls are detected and correctly handled (double counting
3603will not happen).
3604
3605@item
3606For profile-directed optimizations, compile the source files again with
3607the same optimization and code generation options plus
3608@option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that
3609Control Optimization}).
3610
3611@item
3612For test coverage analysis, use @command{gcov} to produce human readable
3613information from the @file{.gcno} and @file{.gcda} files. Refer to the
3614@command{gcov} documentation for further information.
3615
3616@end itemize
3617
3618With @option{-fprofile-arcs}, for each function of your program GCC
3619creates a program flow graph, then finds a spanning tree for the graph.
3620Only arcs that are not on the spanning tree have to be instrumented: the
3621compiler adds code to count the number of times that these arcs are
3622executed. When an arc is the only exit or only entrance to a block, the
3623instrumentation code can be added to the block; otherwise, a new basic
3624block must be created to hold the instrumentation code.
3625
3626@need 2000
3627@item -ftest-coverage
3628@opindex ftest-coverage
3629Produce a notes file that the @command{gcov} code-coverage utility
3630(@pxref{Gcov,, @command{gcov}---a Test Coverage Program}) can use to
3631show program coverage. Each source file's note file is called
3632@file{@var{auxname}.gcno}. Refer to the @option{-fprofile-arcs} option
3633above for a description of @var{auxname} and instructions on how to
3634generate test coverage data. Coverage data will match the source files
3635more closely, if you do not optimize.
3636
3637@item -d@var{letters}
3638@item -fdump-rtl-@var{pass}
3639@opindex d
3640Says to make debugging dumps during compilation at times specified by
3641@var{letters}. This is used for debugging the RTL-based passes of the
3642compiler. The file names for most of the dumps are made by appending a
3643pass number and a word to the @var{dumpname}. @var{dumpname} is generated
3644from the name of the output file, if explicitly specified and it is not
3645an executable, otherwise it is the basename of the source file.
3646
3647Most debug dumps can be enabled either passing a letter to the @option{-d}
3648option, or with a long @option{-fdump-rtl} switch; here are the possible
3649letters for use in @var{letters} and @var{pass}, and their meanings:
3650
3651@table @gcctabopt
3652@item -dA
3653@opindex dA
3654Annotate the assembler output with miscellaneous debugging information.
3655
3656@item -dB
3657@itemx -fdump-rtl-bbro
3658@opindex dB
3659@opindex fdump-rtl-bbro
3660Dump after block reordering, to @file{@var{file}.148r.bbro}.
3661
3662@item -dc
3663@itemx -fdump-rtl-combine
3664@opindex dc
3665@opindex fdump-rtl-combine
3666Dump after instruction combination, to the file @file{@var{file}.129r.combine}.
3667
3668@item -dC
3669@itemx -fdump-rtl-ce1
3670@itemx -fdump-rtl-ce2
3671@opindex dC
3672@opindex fdump-rtl-ce1
3673@opindex fdump-rtl-ce2
3674@option{-dC} and @option{-fdump-rtl-ce1} enable dumping after the
3675first if conversion, to the file @file{@var{file}.117r.ce1}. @option{-dC}
3676and @option{-fdump-rtl-ce2} enable dumping after the second if
3677conversion, to the file @file{@var{file}.130r.ce2}.
3678
3679@item -dd
3680@itemx -fdump-rtl-btl
3681@itemx -fdump-rtl-dbr
3682@opindex dd
3683@opindex fdump-rtl-btl
3684@opindex fdump-rtl-dbr
3685@option{-dd} and @option{-fdump-rtl-btl} enable dumping after branch
3686target load optimization, to @file{@var{file}.31.btl}. @option{-dd}
3687and @option{-fdump-rtl-dbr} enable dumping after delayed branch
3688scheduling, to @file{@var{file}.36.dbr}.
3689
3690@item -dD
3691@opindex dD
3692Dump all macro definitions, at the end of preprocessing, in addition to
3693normal output.
3694
3695@item -dE
3696@itemx -fdump-rtl-ce3
3697@opindex dE
3698@opindex fdump-rtl-ce3
3699Dump after the third if conversion, to @file{@var{file}.146r.ce3}.
3700
3701@item -df
3702@itemx -fdump-rtl-cfg
3703@itemx -fdump-rtl-life
3704@opindex df
3705@opindex fdump-rtl-cfg
3706@opindex fdump-rtl-life
3707@option{-df} and @option{-fdump-rtl-cfg} enable dumping after control
3708and data flow analysis, to @file{@var{file}.116r.cfg}. @option{-df}
3709and @option{-fdump-rtl-cfg} enable dumping dump after life analysis,
3710to @file{@var{file}.128r.life1} and @file{@var{file}.135r.life2}.
3711
3712@item -dg
3713@itemx -fdump-rtl-greg
3714@opindex dg
3715@opindex fdump-rtl-greg
3716Dump after global register allocation, to @file{@var{file}.139r.greg}.
3717
3718@item -dG
3719@itemx -fdump-rtl-gcse
3720@itemx -fdump-rtl-bypass
3721@opindex dG
3722@opindex fdump-rtl-gcse
3723@opindex fdump-rtl-bypass
3724@option{-dG} and @option{-fdump-rtl-gcse} enable dumping after GCSE, to
3725@file{@var{file}.114r.gcse}. @option{-dG} and @option{-fdump-rtl-bypass}
3726enable dumping after jump bypassing and control flow optimizations, to
3727@file{@var{file}.115r.bypass}.
3728
3729@item -dh
3730@itemx -fdump-rtl-eh
3731@opindex dh
3732@opindex fdump-rtl-eh
3733Dump after finalization of EH handling code, to @file{@var{file}.02.eh}.
3734
3735@item -di
3736@itemx -fdump-rtl-sibling
3737@opindex di
3738@opindex fdump-rtl-sibling
3739Dump after sibling call optimizations, to @file{@var{file}.106r.sibling}.
3740
3741@item -dj
3742@itemx -fdump-rtl-jump
3743@opindex dj
3744@opindex fdump-rtl-jump
3745Dump after the first jump optimization, to @file{@var{file}.112r.jump}.
3746
3747@item -dk
3748@itemx -fdump-rtl-stack
3749@opindex dk
3750@opindex fdump-rtl-stack
3751Dump after conversion from registers to stack, to @file{@var{file}.152r.stack}.
3752
3753@item -dl
3754@itemx -fdump-rtl-lreg
3755@opindex dl
3756@opindex fdump-rtl-lreg
3757Dump after local register allocation, to @file{@var{file}.138r.lreg}.
3758
3759@item -dL
3760@itemx -fdump-rtl-loop2
3761@opindex dL
3762@opindex fdump-rtl-loop2
3763@option{-dL} and @option{-fdump-rtl-loop2} enable dumping after the
3764loop optimization pass, to @file{@var{file}.119r.loop2},
3765@file{@var{file}.120r.loop2_init},
3766@file{@var{file}.121r.loop2_invariant}, and
3767@file{@var{file}.125r.loop2_done}.
3768
3769@item -dm
3770@itemx -fdump-rtl-sms
3771@opindex dm
3772@opindex fdump-rtl-sms
3773Dump after modulo scheduling, to @file{@var{file}.136r.sms}.
3774
3775@item -dM
3776@itemx -fdump-rtl-mach
3777@opindex dM
3778@opindex fdump-rtl-mach
3779Dump after performing the machine dependent reorganization pass, to
3780@file{@var{file}.155r.mach}.
3781
3782@item -dn
3783@itemx -fdump-rtl-rnreg
3784@opindex dn
3785@opindex fdump-rtl-rnreg
3786Dump after register renumbering, to @file{@var{file}.147r.rnreg}.
3787
3788@item -dN
3789@itemx -fdump-rtl-regmove
3790@opindex dN
3791@opindex fdump-rtl-regmove
3792Dump after the register move pass, to @file{@var{file}.132r.regmove}.
3793
3794@item -do
3795@itemx -fdump-rtl-postreload
3796@opindex do
3797@opindex fdump-rtl-postreload
3798Dump after post-reload optimizations, to @file{@var{file}.24.postreload}.
3799
3800@item -dr
3801@itemx -fdump-rtl-expand
3802@opindex dr
3803@opindex fdump-rtl-expand
3804Dump after RTL generation, to @file{@var{file}.104r.expand}.
3805
3806@item -dR
3807@itemx -fdump-rtl-sched2
3808@opindex dR
3809@opindex fdump-rtl-sched2
3810Dump after the second scheduling pass, to @file{@var{file}.150r.sched2}.
3811
3812@item -ds
3813@itemx -fdump-rtl-cse
3814@opindex ds
3815@opindex fdump-rtl-cse
3816Dump after CSE (including the jump optimization that sometimes follows
3817CSE), to @file{@var{file}.113r.cse}.
3818
3819@item -dS
3820@itemx -fdump-rtl-sched
3821@opindex dS
3822@opindex fdump-rtl-sched
3823Dump after the first scheduling pass, to @file{@var{file}.21.sched}.
3824
3825@item -dt
3826@itemx -fdump-rtl-cse2
3827@opindex dt
3828@opindex fdump-rtl-cse2
3829Dump after the second CSE pass (including the jump optimization that
3830sometimes follows CSE), to @file{@var{file}.127r.cse2}.
3831
3832@item -dT
3833@itemx -fdump-rtl-tracer
3834@opindex dT
3835@opindex fdump-rtl-tracer
3836Dump after running tracer, to @file{@var{file}.118r.tracer}.
3837
3838@item -dV
3839@itemx -fdump-rtl-vpt
3840@itemx -fdump-rtl-vartrack
3841@opindex dV
3842@opindex fdump-rtl-vpt
3843@opindex fdump-rtl-vartrack
3844@option{-dV} and @option{-fdump-rtl-vpt} enable dumping after the value
3845profile transformations, to @file{@var{file}.10.vpt}. @option{-dV}
3846and @option{-fdump-rtl-vartrack} enable dumping after variable tracking,
3847to @file{@var{file}.154r.vartrack}.
3848
3849@item -dw
3850@itemx -fdump-rtl-flow2
3851@opindex dw
3852@opindex fdump-rtl-flow2
3853Dump after the second flow pass, to @file{@var{file}.142r.flow2}.
3854
3855@item -dz
3856@itemx -fdump-rtl-peephole2
3857@opindex dz
3858@opindex fdump-rtl-peephole2
3859Dump after the peephole pass, to @file{@var{file}.145r.peephole2}.
3860
3861@item -dZ
3862@itemx -fdump-rtl-web
3863@opindex dZ
3864@opindex fdump-rtl-web
3865Dump after live range splitting, to @file{@var{file}.126r.web}.
3866
3867@item -da
3868@itemx -fdump-rtl-all
3869@opindex da
3870@opindex fdump-rtl-all
3871Produce all the dumps listed above.
3872
3873@item -dH
3874@opindex dH
3875Produce a core dump whenever an error occurs.
3876
3877@item -dm
3878@opindex dm
3879Print statistics on memory usage, at the end of the run, to
3880standard error.
3881
3882@item -dp
3883@opindex dp
3884Annotate the assembler output with a comment indicating which
3885pattern and alternative was used. The length of each instruction is
3886also printed.
3887
3888@item -dP
3889@opindex dP
3890Dump the RTL in the assembler output as a comment before each instruction.
3891Also turns on @option{-dp} annotation.
3892
3893@item -dv
3894@opindex dv
3895For each of the other indicated dump files (either with @option{-d} or
3896@option{-fdump-rtl-@var{pass}}), dump a representation of the control flow
3897graph suitable for viewing with VCG to @file{@var{file}.@var{pass}.vcg}.
3898
3899@item -dx
3900@opindex dx
3901Just generate RTL for a function instead of compiling it. Usually used
3902with @samp{r} (@option{-fdump-rtl-expand}).
3903
3904@item -dy
3905@opindex dy
3906Dump debugging information during parsing, to standard error.
3907@end table
3908
3909@item -fdump-noaddr
3910@opindex fdump-noaddr
3911When doing debugging dumps (see @option{-d} option above), suppress
3912address output. This makes it more feasible to use diff on debugging
3913dumps for compiler invocations with different compiler binaries and/or
3914different text / bss / data / heap / stack / dso start locations.
3915
3916@item -fdump-unnumbered
3917@opindex fdump-unnumbered
3918When doing debugging dumps (see @option{-d} option above), suppress instruction
3919numbers, line number note and address output. This makes it more feasible to
3920use diff on debugging dumps for compiler invocations with different
3921options, in particular with and without @option{-g}.
3922
3923@item -fdump-translation-unit @r{(C++ only)}
3924@itemx -fdump-translation-unit-@var{options} @r{(C++ only)}
3925@opindex fdump-translation-unit
3926Dump a representation of the tree structure for the entire translation
3927unit to a file. The file name is made by appending @file{.tu} to the
3928source file name. If the @samp{-@var{options}} form is used, @var{options}
3929controls the details of the dump as described for the
3930@option{-fdump-tree} options.
3931
3932@item -fdump-class-hierarchy @r{(C++ only)}
3933@itemx -fdump-class-hierarchy-@var{options} @r{(C++ only)}
3934@opindex fdump-class-hierarchy
3935Dump a representation of each class's hierarchy and virtual function
3936table layout to a file. The file name is made by appending @file{.class}
3937to the source file name. If the @samp{-@var{options}} form is used,
3938@var{options} controls the details of the dump as described for the
3939@option{-fdump-tree} options.
3940
3941@item -fdump-ipa-@var{switch}
3942@opindex fdump-ipa
3943Control the dumping at various stages of inter-procedural analysis
3944language tree to a file. The file name is generated by appending a switch
3945specific suffix to the source file name. The following dumps are possible:
3946
3947@table @samp
3948@item all
3949Enables all inter-procedural analysis dumps; currently the only produced
3950dump is the @samp{cgraph} dump.
3951
3952@item cgraph
3953Dumps information about call-graph optimization, unused function removal,
3954and inlining decisions.
3955@end table
3956
3957@item -fdump-tree-@var{switch}
3958@itemx -fdump-tree-@var{switch}-@var{options}
3959@opindex fdump-tree
3960Control the dumping at various stages of processing the intermediate
3961language tree to a file. The file name is generated by appending a switch
3962specific suffix to the source file name. If the @samp{-@var{options}}
3963form is used, @var{options} is a list of @samp{-} separated options that
3964control the details of the dump. Not all options are applicable to all
3965dumps, those which are not meaningful will be ignored. The following
3966options are available
3967
3968@table @samp
3969@item address
3970Print the address of each node. Usually this is not meaningful as it
3971changes according to the environment and source file. Its primary use
3972is for tying up a dump file with a debug environment.
3973@item slim
3974Inhibit dumping of members of a scope or body of a function merely
3975because that scope has been reached. Only dump such items when they
3976are directly reachable by some other path. When dumping pretty-printed
3977trees, this option inhibits dumping the bodies of control structures.
3978@item raw
3979Print a raw representation of the tree. By default, trees are
3980pretty-printed into a C-like representation.
3981@item details
3982Enable more detailed dumps (not honored by every dump option).
3983@item stats
3984Enable dumping various statistics about the pass (not honored by every dump
3985option).
3986@item blocks
3987Enable showing basic block boundaries (disabled in raw dumps).
3988@item vops
3989Enable showing virtual operands for every statement.
3990@item lineno
3991Enable showing line numbers for statements.
3992@item uid
3993Enable showing the unique ID (@code{DECL_UID}) for each variable.
3994@item all
3995Turn on all options, except @option{raw}, @option{slim} and @option{lineno}.
3996@end table
3997
3998The following tree dumps are possible:
3999@table @samp
4000
4001@item original
4002Dump before any tree based optimization, to @file{@var{file}.original}.
4003
4004@item optimized
4005Dump after all tree based optimization, to @file{@var{file}.optimized}.
4006
4007@item inlined
4008Dump after function inlining, to @file{@var{file}.inlined}.
4009
4010@item gimple
4011@opindex fdump-tree-gimple
4012Dump each function before and after the gimplification pass to a file. The
4013file name is made by appending @file{.gimple} to the source file name.
4014
4015@item cfg
4016@opindex fdump-tree-cfg
4017Dump the control flow graph of each function to a file. The file name is
4018made by appending @file{.cfg} to the source file name.
4019
4020@item vcg
4021@opindex fdump-tree-vcg
4022Dump the control flow graph of each function to a file in VCG format. The
4023file name is made by appending @file{.vcg} to the source file name. Note
4024that if the file contains more than one function, the generated file cannot
4025be used directly by VCG@. You will need to cut and paste each function's
4026graph into its own separate file first.
4027
4028@item ch
4029@opindex fdump-tree-ch
4030Dump each function after copying loop headers. The file name is made by
4031appending @file{.ch} to the source file name.
4032
4033@item ssa
4034@opindex fdump-tree-ssa
4035Dump SSA related information to a file. The file name is made by appending
4036@file{.ssa} to the source file name.
4037
4038@item salias
4039@opindex fdump-tree-salias
4040Dump structure aliasing variable information to a file. This file name
4041is made by appending @file{.salias} to the source file name.
4042
4043@item alias
4044@opindex fdump-tree-alias
4045Dump aliasing information for each function. The file name is made by
4046appending @file{.alias} to the source file name.
4047
4048@item ccp
4049@opindex fdump-tree-ccp
4050Dump each function after CCP@. The file name is made by appending
4051@file{.ccp} to the source file name.
4052
4053@item storeccp
4054@opindex fdump-tree-storeccp
4055Dump each function after STORE-CCP. The file name is made by appending
4056@file{.storeccp} to the source file name.
4057
4058@item pre
4059@opindex fdump-tree-pre
4060Dump trees after partial redundancy elimination. The file name is made
4061by appending @file{.pre} to the source file name.
4062
4063@item fre
4064@opindex fdump-tree-fre
4065Dump trees after full redundancy elimination. The file name is made
4066by appending @file{.fre} to the source file name.
4067
4068@item copyprop
4069@opindex fdump-tree-copyprop
4070Dump trees after copy propagation. The file name is made
4071by appending @file{.copyprop} to the source file name.
4072
4073@item store_copyprop
4074@opindex fdump-tree-store_copyprop
4075Dump trees after store copy-propagation. The file name is made
4076by appending @file{.store_copyprop} to the source file name.
4077
4078@item dce
4079@opindex fdump-tree-dce
4080Dump each function after dead code elimination. The file name is made by
4081appending @file{.dce} to the source file name.
4082
4083@item mudflap
4084@opindex fdump-tree-mudflap
4085Dump each function after adding mudflap instrumentation. The file name is
4086made by appending @file{.mudflap} to the source file name.
4087
4088@item sra
4089@opindex fdump-tree-sra
4090Dump each function after performing scalar replacement of aggregates. The
4091file name is made by appending @file{.sra} to the source file name.
4092
4093@item sink
4094@opindex fdump-tree-sink
4095Dump each function after performing code sinking. The file name is made
4096by appending @file{.sink} to the source file name.
4097
4098@item dom
4099@opindex fdump-tree-dom
4100Dump each function after applying dominator tree optimizations. The file
4101name is made by appending @file{.dom} to the source file name.
4102
4103@item dse
4104@opindex fdump-tree-dse
4105Dump each function after applying dead store elimination. The file
4106name is made by appending @file{.dse} to the source file name.
4107
4108@item phiopt
4109@opindex fdump-tree-phiopt
4110Dump each function after optimizing PHI nodes into straightline code. The file
4111name is made by appending @file{.phiopt} to the source file name.
4112
4113@item forwprop
4114@opindex fdump-tree-forwprop
4115Dump each function after forward propagating single use variables. The file
4116name is made by appending @file{.forwprop} to the source file name.
4117
4118@item copyrename
4119@opindex fdump-tree-copyrename
4120Dump each function after applying the copy rename optimization. The file
4121name is made by appending @file{.copyrename} to the source file name.
4122
4123@item nrv
4124@opindex fdump-tree-nrv
4125Dump each function after applying the named return value optimization on
4126generic trees. The file name is made by appending @file{.nrv} to the source
4127file name.
4128
4129@item vect
4130@opindex fdump-tree-vect
4131Dump each function after applying vectorization of loops. The file name is
4132made by appending @file{.vect} to the source file name.
4133
4134@item vrp
4135@opindex fdump-tree-vrp
4136Dump each function after Value Range Propagation (VRP). The file name
4137is made by appending @file{.vrp} to the source file name.
4138
4139@item all
4140@opindex fdump-tree-all
4141Enable all the available tree dumps with the flags provided in this option.
4142@end table
4143
4144@item -ftree-vectorizer-verbose=@var{n}
4145@opindex ftree-vectorizer-verbose
4146This option controls the amount of debugging output the vectorizer prints.
4147This information is written to standard error, unless
4148@option{-fdump-tree-all} or @option{-fdump-tree-vect} is specified,
4149in which case it is output to the usual dump listing file, @file{.vect}.
4150For @var{n}=0 no diagnostic information is reported.
4151If @var{n}=1 the vectorizer reports each loop that got vectorized,
4152and the total number of loops that got vectorized.
4153If @var{n}=2 the vectorizer also reports non-vectorized loops that passed
4154the first analysis phase (vect_analyze_loop_form) - i.e. countable,
4155inner-most, single-bb, single-entry/exit loops. This is the same verbosity
4156level that @option{-fdump-tree-vect-stats} uses.
4157Higher verbosity levels mean either more information dumped for each
4158reported loop, or same amount of information reported for more loops:
4159If @var{n}=3, alignment related information is added to the reports.
4160If @var{n}=4, data-references related information (e.g. memory dependences,
4161memory access-patterns) is added to the reports.
4162If @var{n}=5, the vectorizer reports also non-vectorized inner-most loops
4163that did not pass the first analysis phase (i.e. may not be countable, or
4164may have complicated control-flow).
4165If @var{n}=6, the vectorizer reports also non-vectorized nested loops.
4166For @var{n}=7, all the information the vectorizer generates during its
4167analysis and transformation is reported. This is the same verbosity level
4168that @option{-fdump-tree-vect-details} uses.
4169
4170@item -frandom-seed=@var{string}
4171@opindex frandom-string
4172This option provides a seed that GCC uses when it would otherwise use
4173random numbers. It is used to generate certain symbol names
4174that have to be different in every compiled file. It is also used to
4175place unique stamps in coverage data files and the object files that
4176produce them. You can use the @option{-frandom-seed} option to produce
4177reproducibly identical object files.
4178
4179The @var{string} should be different for every file you compile.
4180
4181@item -fsched-verbose=@var{n}
4182@opindex fsched-verbose
4183On targets that use instruction scheduling, this option controls the
4184amount of debugging output the scheduler prints. This information is
4185written to standard error, unless @option{-dS} or @option{-dR} is
4186specified, in which case it is output to the usual dump
4187listing file, @file{.sched} or @file{.sched2} respectively. However
4188for @var{n} greater than nine, the output is always printed to standard
4189error.
4190
4191For @var{n} greater than zero, @option{-fsched-verbose} outputs the
4192same information as @option{-dRS}. For @var{n} greater than one, it
4193also output basic block probabilities, detailed ready list information
4194and unit/insn info. For @var{n} greater than two, it includes RTL
4195at abort point, control-flow and regions info. And for @var{n} over
4196four, @option{-fsched-verbose} also includes dependence info.
4197
4198@item -save-temps
4199@opindex save-temps
4200Store the usual ``temporary'' intermediate files permanently; place them
4201in the current directory and name them based on the source file. Thus,
4202compiling @file{foo.c} with @samp{-c -save-temps} would produce files
4203@file{foo.i} and @file{foo.s}, as well as @file{foo.o}. This creates a
4204preprocessed @file{foo.i} output file even though the compiler now
4205normally uses an integrated preprocessor.
4206
4207When used in combination with the @option{-x} command line option,
4208@option{-save-temps} is sensible enough to avoid over writing an
4209input source file with the same extension as an intermediate file.
4210The corresponding intermediate file may be obtained by renaming the
4211source file before using @option{-save-temps}.
4212
4213@item -time
4214@opindex time
4215Report the CPU time taken by each subprocess in the compilation
4216sequence. For C source files, this is the compiler proper and assembler
4217(plus the linker if linking is done). The output looks like this:
4218
4219@smallexample
4220# cc1 0.12 0.01
4221# as 0.00 0.01
4222@end smallexample
4223
4224The first number on each line is the ``user time'', that is time spent
4225executing the program itself. The second number is ``system time'',
4226time spent executing operating system routines on behalf of the program.
4227Both numbers are in seconds.
4228
4229@item -fvar-tracking
4230@opindex fvar-tracking
4231Run variable tracking pass. It computes where variables are stored at each
4232position in code. Better debugging information is then generated
4233(if the debugging information format supports this information).
4234
4235It is enabled by default when compiling with optimization (@option{-Os},
4236@option{-O}, @option{-O2}, ...), debugging information (@option{-g}) and
4237the debug info format supports it.
4238
4239@item -print-file-name=@var{library}
4240@opindex print-file-name
4241Print the full absolute name of the library file @var{library} that
4242would be used when linking---and don't do anything else. With this
4243option, GCC does not compile or link anything; it just prints the
4244file name.
4245
4246@item -print-multi-directory
4247@opindex print-multi-directory
4248Print the directory name corresponding to the multilib selected by any
4249other switches present in the command line. This directory is supposed
4250to exist in @env{GCC_EXEC_PREFIX}.
4251
4252@item -print-multi-lib
4253@opindex print-multi-lib
4254Print the mapping from multilib directory names to compiler switches
4255that enable them. The directory name is separated from the switches by
4256@samp{;}, and each switch starts with an @samp{@@} instead of the
4257@samp{-}, without spaces between multiple switches. This is supposed to
4258ease shell-processing.
4259
4260@item -print-prog-name=@var{program}
4261@opindex print-prog-name
4262Like @option{-print-file-name}, but searches for a program such as @samp{cpp}.
4263
4264@item -print-libgcc-file-name
4265@opindex print-libgcc-file-name
4266Same as @option{-print-file-name=libgcc.a}.
4267
4268This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs}
4269but you do want to link with @file{libgcc.a}. You can do
4270
4271@smallexample
4272gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
4273@end smallexample
4274
4275@item -print-search-dirs
4276@opindex print-search-dirs
4277Print the name of the configured installation directory and a list of
4278program and library directories @command{gcc} will search---and don't do anything else.
4279
4280This is useful when @command{gcc} prints the error message
4281@samp{installation problem, cannot exec cpp0: No such file or directory}.
4282To resolve this you either need to put @file{cpp0} and the other compiler
4283components where @command{gcc} expects to find them, or you can set the environment
4284variable @env{GCC_EXEC_PREFIX} to the directory where you installed them.
4285Don't forget the trailing @samp{/}.
4286@xref{Environment Variables}.
4287
4288@item -dumpmachine
4289@opindex dumpmachine
4290Print the compiler's target machine (for example,
4291@samp{i686-pc-linux-gnu})---and don't do anything else.
4292
4293@item -dumpversion
4294@opindex dumpversion
4295Print the compiler version (for example, @samp{3.0})---and don't do
4296anything else.
4297
4298@item -dumpspecs
4299@opindex dumpspecs
4300Print the compiler's built-in specs---and don't do anything else. (This
4301is used when GCC itself is being built.) @xref{Spec Files}.
4302
4303@item -feliminate-unused-debug-types
4304@opindex feliminate-unused-debug-types
4305Normally, when producing DWARF2 output, GCC will emit debugging
4306information for all types declared in a compilation
4307unit, regardless of whether or not they are actually used
4308in that compilation unit. Sometimes this is useful, such as
4309if, in the debugger, you want to cast a value to a type that is
4310not actually used in your program (but is declared). More often,
4311however, this results in a significant amount of wasted space.
4312With this option, GCC will avoid producing debug symbol output
4313for types that are nowhere used in the source file being compiled.
4314@end table
4315
4316@node Optimize Options
4317@section Options That Control Optimization
4318@cindex optimize options
4319@cindex options, optimization
4320
4321These options control various sorts of optimizations.
4322
4323Without any optimization option, the compiler's goal is to reduce the
4324cost of compilation and to make debugging produce the expected
4325results. Statements are independent: if you stop the program with a
4326breakpoint between statements, you can then assign a new value to any
4327variable or change the program counter to any other statement in the
4328function and get exactly the results you would expect from the source
4329code.
4330
4331Turning on optimization flags makes the compiler attempt to improve
4332the performance and/or code size at the expense of compilation time
4333and possibly the ability to debug the program.
4334
4335The compiler performs optimization based on the knowledge it has of
4336the program. Optimization levels @option{-O} and above, in
4337particular, enable @emph{unit-at-a-time} mode, which allows the
4338compiler to consider information gained from later functions in
4339the file when compiling a function. Compiling multiple files at
4340once to a single output file in @emph{unit-at-a-time} mode allows
4341the compiler to use information gained from all of the files when
4342compiling each of them.
4343
4344Not all optimizations are controlled directly by a flag. Only
4345optimizations that have a flag are listed.
4346
4347@table @gcctabopt
4348@item -O
4349@itemx -O1
4350@opindex O
4351@opindex O1
4352Optimize. Optimizing compilation takes somewhat more time, and a lot
4353more memory for a large function.
4354
4355With @option{-O}, the compiler tries to reduce code size and execution
4356time, without performing any optimizations that take a great deal of
4357compilation time.
4358
4359@option{-O} turns on the following optimization flags:
4360@gccoptlist{-fdefer-pop @gol
4361-fdelayed-branch @gol
4362-fguess-branch-probability @gol
4363-fcprop-registers @gol
4364-fif-conversion @gol
4365-fif-conversion2 @gol
4366-ftree-ccp @gol
4367-ftree-dce @gol
4368-ftree-dominator-opts @gol
4369-ftree-dse @gol
4370-ftree-ter @gol
4371-ftree-lrs @gol
4372-ftree-sra @gol
4373-ftree-copyrename @gol
4374-ftree-fre @gol
4375-ftree-ch @gol
4376-funit-at-a-time @gol
4377-fmerge-constants}
4378
4379@option{-O} also turns on @option{-fomit-frame-pointer} on machines
4380where doing so does not interfere with debugging.
4381
4382@item -O2
4383@opindex O2
4384Optimize even more. GCC performs nearly all supported optimizations
4385that do not involve a space-speed tradeoff. The compiler does not
4386perform loop unrolling or function inlining when you specify @option{-O2}.
4387As compared to @option{-O}, this option increases both compilation time
4388and the performance of the generated code.
4389
4390@option{-O2} turns on all optimization flags specified by @option{-O}. It
4391also turns on the following optimization flags:
4392@gccoptlist{-fthread-jumps @gol
4393-fcrossjumping @gol
4394-foptimize-sibling-calls @gol
4395-fcse-follow-jumps -fcse-skip-blocks @gol
4396-fgcse -fgcse-lm @gol
4397-fexpensive-optimizations @gol
4398-frerun-cse-after-loop @gol
4399-fcaller-saves @gol
4400-fpeephole2 @gol
4401-fschedule-insns -fschedule-insns2 @gol
4402-fsched-interblock -fsched-spec @gol
4403-fregmove @gol
4404-fstrict-aliasing -fstrict-overflow @gol
4405-fdelete-null-pointer-checks @gol
4406-freorder-blocks -freorder-functions @gol
4407-falign-functions -falign-jumps @gol
4408-falign-loops -falign-labels @gol
4409-ftree-vrp @gol
4410-ftree-pre}
4411
4412Please note the warning under @option{-fgcse} about
4413invoking @option{-O2} on programs that use computed gotos.
4414
4415@option{-O2} doesn't turn on @option{-ftree-vrp} for the Ada compiler.
4416This option must be explicitly specified on the command line to be
4417enabled for the Ada compiler.
4418
4419@item -O3
4420@opindex O3
4421Optimize yet more. @option{-O3} turns on all optimizations specified by
4422@option{-O2} and also turns on the @option{-finline-functions},
4423@option{-funswitch-loops} and @option{-fgcse-after-reload} options.
4424
4425@item -O0
4426@opindex O0
4427Do not optimize. This is the default.
4428
4429@item -Os
4430@opindex Os
4431Optimize for size. @option{-Os} enables all @option{-O2} optimizations that
4432do not typically increase code size. It also performs further
4433optimizations designed to reduce code size.
4434
4435@option{-Os} disables the following optimization flags:
4436@gccoptlist{-falign-functions -falign-jumps -falign-loops @gol
4437-falign-labels -freorder-blocks -freorder-blocks-and-partition @gol
4438-fprefetch-loop-arrays -ftree-vect-loop-version}
4439
4440If you use multiple @option{-O} options, with or without level numbers,
4441the last such option is the one that is effective.
4442@end table
4443
4444Options of the form @option{-f@var{flag}} specify machine-independent
4445flags. Most flags have both positive and negative forms; the negative
4446form of @option{-ffoo} would be @option{-fno-foo}. In the table
4447below, only one of the forms is listed---the one you typically will
4448use. You can figure out the other form by either removing @samp{no-}
4449or adding it.
4450
4451The following options control specific optimizations. They are either
4452activated by @option{-O} options or are related to ones that are. You
4453can use the following flags in the rare cases when ``fine-tuning'' of
4454optimizations to be performed is desired.
4455
4456@table @gcctabopt
4457@item -fno-default-inline
4458@opindex fno-default-inline
4459Do not make member functions inline by default merely because they are
4460defined inside the class scope (C++ only). Otherwise, when you specify
4461@w{@option{-O}}, member functions defined inside class scope are compiled
4462inline by default; i.e., you don't need to add @samp{inline} in front of
4463the member function name.
4464
4465@item -fno-defer-pop
4466@opindex fno-defer-pop
4467Always pop the arguments to each function call as soon as that function
4468returns. For machines which must pop arguments after a function call,
4469the compiler normally lets arguments accumulate on the stack for several
4470function calls and pops them all at once.
4471
4472Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4473
4474@item -fforce-mem
4475@opindex fforce-mem
4476Force memory operands to be copied into registers before doing
4477arithmetic on them. This produces better code by making all memory
4478references potential common subexpressions. When they are not common
4479subexpressions, instruction combination should eliminate the separate
4480register-load. This option is now a nop and will be removed in 4.3.
4481
4482@item -fforce-addr
4483@opindex fforce-addr
4484Force memory address constants to be copied into registers before
4485doing arithmetic on them.
4486
4487@item -fomit-frame-pointer
4488@opindex fomit-frame-pointer
4489Don't keep the frame pointer in a register for functions that
4490don't need one. This avoids the instructions to save, set up and
4491restore frame pointers; it also makes an extra register available
4492in many functions. @strong{It also makes debugging impossible on
4493some machines.}
4494
4495On some machines, such as the VAX, this flag has no effect, because
4496the standard calling sequence automatically handles the frame pointer
4497and nothing is saved by pretending it doesn't exist. The
4498machine-description macro @code{FRAME_POINTER_REQUIRED} controls
4499whether a target machine supports this flag. @xref{Registers,,Register
4500Usage, gccint, GNU Compiler Collection (GCC) Internals}.
4501
4502Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4503
4504@item -foptimize-sibling-calls
4505@opindex foptimize-sibling-calls
4506Optimize sibling and tail recursive calls.
4507
4508Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4509
4510@item -fno-inline
4511@opindex fno-inline
4512Don't pay attention to the @code{inline} keyword. Normally this option
4513is used to keep the compiler from expanding any functions inline.
4514Note that if you are not optimizing, no functions can be expanded inline.
4515
4516@item -finline-functions
4517@opindex finline-functions
4518Integrate all simple functions into their callers. The compiler
4519heuristically decides which functions are simple enough to be worth
4520integrating in this way.
4521
4522If all calls to a given function are integrated, and the function is
4523declared @code{static}, then the function is normally not output as
4524assembler code in its own right.
4525
4526Enabled at level @option{-O3}.
4527
4528@item -finline-functions-called-once
4529@opindex finline-functions-called-once
4530Consider all @code{static} functions called once for inlining into their
4531caller even if they are not marked @code{inline}. If a call to a given
4532function is integrated, then the function is not output as assembler code
4533in its own right.
4534
4535Enabled if @option{-funit-at-a-time} is enabled.
4536
4537@item -fearly-inlining
4538@opindex fearly-inlining
4539Inline functions marked by @code{always_inline} and functions whose body seems
4540smaller than the function call overhead early before doing
4541@option{-fprofile-generate} instrumentation and real inlining pass. Doing so
4542makes profiling significantly cheaper and usually inlining faster on programs
4543having large chains of nested wrapper functions.
4544
4545Enabled by default.
4546
4547@item -finline-limit=@var{n}
4548@opindex finline-limit
4549By default, GCC limits the size of functions that can be inlined. This flag
4550allows the control of this limit for functions that are explicitly marked as
4551inline (i.e., marked with the inline keyword or defined within the class
4552definition in c++). @var{n} is the size of functions that can be inlined in
4553number of pseudo instructions (not counting parameter handling). The default
4554value of @var{n} is 600.
4555Increasing this value can result in more inlined code at
4556the cost of compilation time and memory consumption. Decreasing usually makes
4557the compilation faster and less code will be inlined (which presumably
4558means slower programs). This option is particularly useful for programs that
4559use inlining heavily such as those based on recursive templates with C++.
4560
4561Inlining is actually controlled by a number of parameters, which may be
4562specified individually by using @option{--param @var{name}=@var{value}}.
4563The @option{-finline-limit=@var{n}} option sets some of these parameters
4564as follows:
4565
4566@table @gcctabopt
4567@item max-inline-insns-single
4568 is set to @var{n}/2.
4569@item max-inline-insns-auto
4570 is set to @var{n}/2.
4571@item min-inline-insns
4572 is set to 130 or @var{n}/4, whichever is smaller.
4573@item max-inline-insns-rtl
4574 is set to @var{n}.
4575@end table
4576
4577See below for a documentation of the individual
4578parameters controlling inlining.
4579
4580@emph{Note:} pseudo instruction represents, in this particular context, an
4581abstract measurement of function's size. In no way does it represent a count
4582of assembly instructions and as such its exact meaning might change from one
4583release to an another.
4584
4585@item -fkeep-inline-functions
4586@opindex fkeep-inline-functions
4587In C, emit @code{static} functions that are declared @code{inline}
4588into the object file, even if the function has been inlined into all
4589of its callers. This switch does not affect functions using the
4590@code{extern inline} extension in GNU C@. In C++, emit any and all
4591inline functions into the object file.
4592
4593@item -fkeep-static-consts
4594@opindex fkeep-static-consts
4595Emit variables declared @code{static const} when optimization isn't turned
4596on, even if the variables aren't referenced.
4597
4598GCC enables this option by default. If you want to force the compiler to
4599check if the variable was referenced, regardless of whether or not
4600optimization is turned on, use the @option{-fno-keep-static-consts} option.
4601
4602@item -fmerge-constants
4603Attempt to merge identical constants (string constants and floating point
4604constants) across compilation units.
4605
4606This option is the default for optimized compilation if the assembler and
4607linker support it. Use @option{-fno-merge-constants} to inhibit this
4608behavior.
4609
4610Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4611
4612@item -fmerge-all-constants
4613Attempt to merge identical constants and identical variables.
4614
4615This option implies @option{-fmerge-constants}. In addition to
4616@option{-fmerge-constants} this considers e.g.@: even constant initialized
4617arrays or initialized constant variables with integral or floating point
4618types. Languages like C or C++ require each non-automatic variable to
4619have distinct location, so using this option will result in non-conforming
4620behavior.
4621
4622@item -fmodulo-sched
4623@opindex fmodulo-sched
4624Perform swing modulo scheduling immediately before the first scheduling
4625pass. This pass looks at innermost loops and reorders their
4626instructions by overlapping different iterations.
4627
4628@item -fno-branch-count-reg
4629@opindex fno-branch-count-reg
4630Do not use ``decrement and branch'' instructions on a count register,
4631but instead generate a sequence of instructions that decrement a
4632register, compare it against zero, then branch based upon the result.
4633This option is only meaningful on architectures that support such
4634instructions, which include x86, PowerPC, IA-64 and S/390.
4635
4636The default is @option{-fbranch-count-reg}.
4637
4638@item -fno-function-cse
4639@opindex fno-function-cse
4640Do not put function addresses in registers; make each instruction that
4641calls a constant function contain the function's address explicitly.
4642
4643This option results in less efficient code, but some strange hacks
4644that alter the assembler output may be confused by the optimizations
4645performed when this option is not used.
4646
4647The default is @option{-ffunction-cse}
4648
4649@item -fno-zero-initialized-in-bss
4650@opindex fno-zero-initialized-in-bss
4651If the target supports a BSS section, GCC by default puts variables that
4652are initialized to zero into BSS@. This can save space in the resulting
4653code.
4654
4655This option turns off this behavior because some programs explicitly
4656rely on variables going to the data section. E.g., so that the
4657resulting executable can find the beginning of that section and/or make
4658assumptions based on that.
4659
4660The default is @option{-fzero-initialized-in-bss}.
4661
4662@item -fbounds-check
4663@opindex fbounds-check
4664For front-ends that support it, generate additional code to check that
4665indices used to access arrays are within the declared range. This is
4666currently only supported by the Java and Fortran front-ends, where
4667this option defaults to true and false respectively.
4668
4669@item -fmudflap -fmudflapth -fmudflapir
4670@opindex fmudflap
4671@opindex fmudflapth
4672@opindex fmudflapir
4673@cindex bounds checking
4674@cindex mudflap
4675For front-ends that support it (C and C++), instrument all risky
4676pointer/array dereferencing operations, some standard library
4677string/heap functions, and some other associated constructs with
4678range/validity tests. Modules so instrumented should be immune to
4679buffer overflows, invalid heap use, and some other classes of C/C++
4680programming errors. The instrumentation relies on a separate runtime
4681library (@file{libmudflap}), which will be linked into a program if
4682@option{-fmudflap} is given at link time. Run-time behavior of the
4683instrumented program is controlled by the @env{MUDFLAP_OPTIONS}
4684environment variable. See @code{env MUDFLAP_OPTIONS=-help a.out}
4685for its options.
4686
4687Use @option{-fmudflapth} instead of @option{-fmudflap} to compile and to
4688link if your program is multi-threaded. Use @option{-fmudflapir}, in
4689addition to @option{-fmudflap} or @option{-fmudflapth}, if
4690instrumentation should ignore pointer reads. This produces less
4691instrumentation (and therefore faster execution) and still provides
4692some protection against outright memory corrupting writes, but allows
4693erroneously read data to propagate within a program.
4694
4695@item -fthread-jumps
4696@opindex fthread-jumps
4697Perform optimizations where we check to see if a jump branches to a
4698location where another comparison subsumed by the first is found. If
4699so, the first branch is redirected to either the destination of the
4700second branch or a point immediately following it, depending on whether
4701the condition is known to be true or false.
4702
4703Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4704
4705@item -fcse-follow-jumps
4706@opindex fcse-follow-jumps
4707In common subexpression elimination, scan through jump instructions
4708when the target of the jump is not reached by any other path. For
4709example, when CSE encounters an @code{if} statement with an
4710@code{else} clause, CSE will follow the jump when the condition
4711tested is false.
4712
4713Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4714
4715@item -fcse-skip-blocks
4716@opindex fcse-skip-blocks
4717This is similar to @option{-fcse-follow-jumps}, but causes CSE to
4718follow jumps which conditionally skip over blocks. When CSE
4719encounters a simple @code{if} statement with no else clause,
4720@option{-fcse-skip-blocks} causes CSE to follow the jump around the
4721body of the @code{if}.
4722
4723Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4724
4725@item -frerun-cse-after-loop
4726@opindex frerun-cse-after-loop
4727Re-run common subexpression elimination after loop optimizations has been
4728performed.
4729
4730Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4731
4732@item -fgcse
4733@opindex fgcse
4734Perform a global common subexpression elimination pass.
4735This pass also performs global constant and copy propagation.
4736
4737@emph{Note:} When compiling a program using computed gotos, a GCC
4738extension, you may get better runtime performance if you disable
4739the global common subexpression elimination pass by adding
4740@option{-fno-gcse} to the command line.
4741
4742Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4743
4744@item -fgcse-lm
4745@opindex fgcse-lm
4746When @option{-fgcse-lm} is enabled, global common subexpression elimination will
4747attempt to move loads which are only killed by stores into themselves. This
4748allows a loop containing a load/store sequence to be changed to a load outside
4749the loop, and a copy/store within the loop.
4750
4751Enabled by default when gcse is enabled.
4752
4753@item -fgcse-sm
4754@opindex fgcse-sm
4755When @option{-fgcse-sm} is enabled, a store motion pass is run after
4756global common subexpression elimination. This pass will attempt to move
4757stores out of loops. When used in conjunction with @option{-fgcse-lm},
4758loops containing a load/store sequence can be changed to a load before
4759the loop and a store after the loop.
4760
4761Not enabled at any optimization level.
4762
4763@item -fgcse-las
4764@opindex fgcse-las
4765When @option{-fgcse-las} is enabled, the global common subexpression
4766elimination pass eliminates redundant loads that come after stores to the
4767same memory location (both partial and full redundancies).
4768
4769Not enabled at any optimization level.
4770
4771@item -fgcse-after-reload
4772@opindex fgcse-after-reload
4773When @option{-fgcse-after-reload} is enabled, a redundant load elimination
4774pass is performed after reload. The purpose of this pass is to cleanup
4775redundant spilling.
4776
4777@item -funsafe-loop-optimizations
4778@opindex funsafe-loop-optimizations
4779If given, the loop optimizer will assume that loop indices do not
4780overflow, and that the loops with nontrivial exit condition are not
4781infinite. This enables a wider range of loop optimizations even if
4782the loop optimizer itself cannot prove that these assumptions are valid.
4783Using @option{-Wunsafe-loop-optimizations}, the compiler will warn you
4784if it finds this kind of loop.
4785
4786@item -fcrossjumping
4787@opindex crossjumping
4788Perform cross-jumping transformation. This transformation unifies equivalent code and save code size. The
4789resulting code may or may not perform better than without cross-jumping.
4790
4791Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4792
4793@item -fif-conversion
4794@opindex if-conversion
4795Attempt to transform conditional jumps into branch-less equivalents. This
4796include use of conditional moves, min, max, set flags and abs instructions, and
4797some tricks doable by standard arithmetics. The use of conditional execution
4798on chips where it is available is controlled by @code{if-conversion2}.
4799
4800Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4801
4802@item -fif-conversion2
4803@opindex if-conversion2
4804Use conditional execution (where available) to transform conditional jumps into
4805branch-less equivalents.
4806
4807Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4808
4809@item -fdelete-null-pointer-checks
4810@opindex fdelete-null-pointer-checks
4811Use global dataflow analysis to identify and eliminate useless checks
4812for null pointers. The compiler assumes that dereferencing a null
4813pointer would have halted the program. If a pointer is checked after
4814it has already been dereferenced, it cannot be null.
4815
4816In some environments, this assumption is not true, and programs can
4817safely dereference null pointers. Use
4818@option{-fno-delete-null-pointer-checks} to disable this optimization
4819for programs which depend on that behavior.
4820
4821Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4822
4823@item -fexpensive-optimizations
4824@opindex fexpensive-optimizations
4825Perform a number of minor optimizations that are relatively expensive.
4826
4827Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4828
4829@item -foptimize-register-move
4830@itemx -fregmove
4831@opindex foptimize-register-move
4832@opindex fregmove
4833Attempt to reassign register numbers in move instructions and as
4834operands of other simple instructions in order to maximize the amount of
4835register tying. This is especially helpful on machines with two-operand
4836instructions.
4837
4838Note @option{-fregmove} and @option{-foptimize-register-move} are the same
4839optimization.
4840
4841Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4842
4843@item -fdelayed-branch
4844@opindex fdelayed-branch
4845If supported for the target machine, attempt to reorder instructions
4846to exploit instruction slots available after delayed branch
4847instructions.
4848
4849Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4850
4851@item -fschedule-insns
4852@opindex fschedule-insns
4853If supported for the target machine, attempt to reorder instructions to
4854eliminate execution stalls due to required data being unavailable. This
4855helps machines that have slow floating point or memory load instructions
4856by allowing other instructions to be issued until the result of the load
4857or floating point instruction is required.
4858
4859Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4860
4861@item -fschedule-insns2
4862@opindex fschedule-insns2
4863Similar to @option{-fschedule-insns}, but requests an additional pass of
4864instruction scheduling after register allocation has been done. This is
4865especially useful on machines with a relatively small number of
4866registers and where memory load instructions take more than one cycle.
4867
4868Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4869
4870@item -fno-sched-interblock
4871@opindex fno-sched-interblock
4872Don't schedule instructions across basic blocks. This is normally
4873enabled by default when scheduling before register allocation, i.e.@:
4874with @option{-fschedule-insns} or at @option{-O2} or higher.
4875
4876@item -fno-sched-spec
4877@opindex fno-sched-spec
4878Don't allow speculative motion of non-load instructions. This is normally
4879enabled by default when scheduling before register allocation, i.e.@:
4880with @option{-fschedule-insns} or at @option{-O2} or higher.
4881
4882@item -fsched-spec-load
4883@opindex fsched-spec-load
4884Allow speculative motion of some load instructions. This only makes
4885sense when scheduling before register allocation, i.e.@: with
4886@option{-fschedule-insns} or at @option{-O2} or higher.
4887
4888@item -fsched-spec-load-dangerous
4889@opindex fsched-spec-load-dangerous
4890Allow speculative motion of more load instructions. This only makes
4891sense when scheduling before register allocation, i.e.@: with
4892@option{-fschedule-insns} or at @option{-O2} or higher.
4893
4894@item -fsched-stalled-insns=@var{n}
4895@opindex fsched-stalled-insns
4896Define how many insns (if any) can be moved prematurely from the queue
4897of stalled insns into the ready list, during the second scheduling pass.
4898
4899@item -fsched-stalled-insns-dep=@var{n}
4900@opindex fsched-stalled-insns-dep
4901Define how many insn groups (cycles) will be examined for a dependency
4902on a stalled insn that is candidate for premature removal from the queue
4903of stalled insns. Has an effect only during the second scheduling pass,
4904and only if @option{-fsched-stalled-insns} is used and its value is not zero.
4905
4906@item -fsched2-use-superblocks
4907@opindex fsched2-use-superblocks
4908When scheduling after register allocation, do use superblock scheduling
4909algorithm. Superblock scheduling allows motion across basic block boundaries
4910resulting on faster schedules. This option is experimental, as not all machine
4911descriptions used by GCC model the CPU closely enough to avoid unreliable
4912results from the algorithm.
4913
4914This only makes sense when scheduling after register allocation, i.e.@: with
4915@option{-fschedule-insns2} or at @option{-O2} or higher.
4916
4917@item -fsched2-use-traces
4918@opindex fsched2-use-traces
4919Use @option{-fsched2-use-superblocks} algorithm when scheduling after register
4920allocation and additionally perform code duplication in order to increase the
4921size of superblocks using tracer pass. See @option{-ftracer} for details on
4922trace formation.
4923
4924This mode should produce faster but significantly longer programs. Also
4925without @option{-fbranch-probabilities} the traces constructed may not
4926match the reality and hurt the performance. This only makes
4927sense when scheduling after register allocation, i.e.@: with
4928@option{-fschedule-insns2} or at @option{-O2} or higher.
4929
4930@item -fsee
4931@opindex fsee
4932Eliminates redundant extension instructions and move the non redundant
4933ones to optimal placement using LCM.
4934
4935@item -freschedule-modulo-scheduled-loops
4936@opindex fscheduling-in-modulo-scheduled-loops
4937The modulo scheduling comes before the traditional scheduling, if a loop was modulo scheduled
4938we may want to prevent the later scheduling passes from changing its schedule, we use this
4939option to control that.
4940
4941@item -fcaller-saves
4942@opindex fcaller-saves
4943Enable values to be allocated in registers that will be clobbered by
4944function calls, by emitting extra instructions to save and restore the
4945registers around such calls. Such allocation is done only when it
4946seems to result in better code than would otherwise be produced.
4947
4948This option is always enabled by default on certain machines, usually
4949those which have no call-preserved registers to use instead.
4950
4951Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4952
4953@item -ftree-pre
4954Perform Partial Redundancy Elimination (PRE) on trees. This flag is
4955enabled by default at @option{-O2} and @option{-O3}.
4956
4957@item -ftree-fre
4958Perform Full Redundancy Elimination (FRE) on trees. The difference
4959between FRE and PRE is that FRE only considers expressions
4960that are computed on all paths leading to the redundant computation.
4961This analysis faster than PRE, though it exposes fewer redundancies.
4962This flag is enabled by default at @option{-O} and higher.
4963
4964@item -ftree-copy-prop
4965Perform copy propagation on trees. This pass eliminates unnecessary
4966copy operations. This flag is enabled by default at @option{-O} and
4967higher.
4968
4969@item -ftree-store-copy-prop
4970Perform copy propagation of memory loads and stores. This pass
4971eliminates unnecessary copy operations in memory references
4972(structures, global variables, arrays, etc). This flag is enabled by
4973default at @option{-O2} and higher.
4974
4975@item -ftree-salias
4976Perform structural alias analysis on trees. This flag
4977is enabled by default at @option{-O} and higher.
4978
4979@item -fipa-pta
4980Perform interprocedural pointer analysis.
4981
4982@item -ftree-sink
4983Perform forward store motion on trees. This flag is
4984enabled by default at @option{-O} and higher.
4985
4986@item -ftree-ccp
4987Perform sparse conditional constant propagation (CCP) on trees. This
4988pass only operates on local scalar variables and is enabled by default
4989at @option{-O} and higher.
4990
4991@item -ftree-store-ccp
4992Perform sparse conditional constant propagation (CCP) on trees. This
4993pass operates on both local scalar variables and memory stores and
4994loads (global variables, structures, arrays, etc). This flag is
4995enabled by default at @option{-O2} and higher.
4996
4997@item -ftree-dce
4998Perform dead code elimination (DCE) on trees. This flag is enabled by
4999default at @option{-O} and higher.
5000
5001@item -ftree-dominator-opts
5002Perform a variety of simple scalar cleanups (constant/copy
5003propagation, redundancy elimination, range propagation and expression
5004simplification) based on a dominator tree traversal. This also
5005performs jump threading (to reduce jumps to jumps). This flag is
5006enabled by default at @option{-O} and higher.
5007
5008@item -ftree-ch
5009Perform loop header copying on trees. This is beneficial since it increases
5010effectiveness of code motion optimizations. It also saves one jump. This flag
5011is enabled by default at @option{-O} and higher. It is not enabled
5012for @option{-Os}, since it usually increases code size.
5013
5014@item -ftree-loop-optimize
5015Perform loop optimizations on trees. This flag is enabled by default
5016at @option{-O} and higher.
5017
5018@item -ftree-loop-linear
5019Perform linear loop transformations on tree. This flag can improve cache
5020performance and allow further loop optimizations to take place.
5021
5022@item -ftree-loop-im
5023Perform loop invariant motion on trees. This pass moves only invariants that
5024would be hard to handle at RTL level (function calls, operations that expand to
5025nontrivial sequences of insns). With @option{-funswitch-loops} it also moves
5026operands of conditions that are invariant out of the loop, so that we can use
5027just trivial invariantness analysis in loop unswitching. The pass also includes
5028store motion.
5029
5030@item -ftree-loop-ivcanon
5031Create a canonical counter for number of iterations in the loop for that
5032determining number of iterations requires complicated analysis. Later
5033optimizations then may determine the number easily. Useful especially
5034in connection with unrolling.
5035
5036@item -fivopts
5037Perform induction variable optimizations (strength reduction, induction
5038variable merging and induction variable elimination) on trees.
5039
5040@item -ftree-sra
5041Perform scalar replacement of aggregates. This pass replaces structure
5042references with scalars to prevent committing structures to memory too
5043early. This flag is enabled by default at @option{-O} and higher.
5044
5045@item -ftree-copyrename
5046Perform copy renaming on trees. This pass attempts to rename compiler
5047temporaries to other variables at copy locations, usually resulting in
5048variable names which more closely resemble the original variables. This flag
5049is enabled by default at @option{-O} and higher.
5050
5051@item -ftree-ter
5052Perform temporary expression replacement during the SSA->normal phase. Single
5053use/single def temporaries are replaced at their use location with their
5054defining expression. This results in non-GIMPLE code, but gives the expanders
5055much more complex trees to work on resulting in better RTL generation. This is
5056enabled by default at @option{-O} and higher.
5057
5058@item -ftree-lrs
5059Perform live range splitting during the SSA->normal phase. Distinct live
5060ranges of a variable are split into unique variables, allowing for better
5061optimization later. This is enabled by default at @option{-O} and higher.
5062
5063@item -ftree-vectorize
5064Perform loop vectorization on trees.
5065
5066@item -ftree-vect-loop-version
5067@opindex ftree-vect-loop-version
5068Perform loop versioning when doing loop vectorization on trees. When a loop
5069appears to be vectorizable except that data alignment or data dependence cannot
5070be determined at compile time then vectorized and non-vectorized versions of
5071the loop are generated along with runtime checks for alignment or dependence
5072to control which version is executed. This option is enabled by default
5073except at level @option{-Os} where it is disabled.
5074
5075@item -ftree-vrp
5076Perform Value Range Propagation on trees. This is similar to the
5077constant propagation pass, but instead of values, ranges of values are
5078propagated. This allows the optimizers to remove unnecessary range
5079checks like array bound checks and null pointer checks. This is
5080enabled by default at @option{-O2} and higher. Null pointer check
5081elimination is only done if @option{-fdelete-null-pointer-checks} is
5082enabled.
5083
5084@item -ftracer
5085@opindex ftracer
5086Perform tail duplication to enlarge superblock size. This transformation
5087simplifies the control flow of the function allowing other optimizations to do
5088better job.
5089
5090@item -funroll-loops
5091@opindex funroll-loops
5092Unroll loops whose number of iterations can be determined at compile
5093time or upon entry to the loop. @option{-funroll-loops} implies
5094@option{-frerun-cse-after-loop}. This option makes code larger,
5095and may or may not make it run faster.
5096
5097@item -funroll-all-loops
5098@opindex funroll-all-loops
5099Unroll all loops, even if their number of iterations is uncertain when
5100the loop is entered. This usually makes programs run more slowly.
5101@option{-funroll-all-loops} implies the same options as
5102@option{-funroll-loops},
5103
5104@item -fsplit-ivs-in-unroller
5105@opindex fsplit-ivs-in-unroller
5106Enables expressing of values of induction variables in later iterations
5107of the unrolled loop using the value in the first iteration. This breaks
5108long dependency chains, thus improving efficiency of the scheduling passes.
5109
5110Combination of @option{-fweb} and CSE is often sufficient to obtain the
5111same effect. However in cases the loop body is more complicated than
5112a single basic block, this is not reliable. It also does not work at all
5113on some of the architectures due to restrictions in the CSE pass.
5114
5115This optimization is enabled by default.
5116
5117@item -fvariable-expansion-in-unroller
5118@opindex fvariable-expansion-in-unroller
5119With this option, the compiler will create multiple copies of some
5120local variables when unrolling a loop which can result in superior code.
5121
5122@item -fprefetch-loop-arrays
5123@opindex fprefetch-loop-arrays
5124If supported by the target machine, generate instructions to prefetch
5125memory to improve the performance of loops that access large arrays.
5126
5127This option may generate better or worse code; results are highly
5128dependent on the structure of loops within the source code.
5129
5130Disabled at level @option{-Os}.
5131
5132@item -fno-peephole
5133@itemx -fno-peephole2
5134@opindex fno-peephole
5135@opindex fno-peephole2
5136Disable any machine-specific peephole optimizations. The difference
5137between @option{-fno-peephole} and @option{-fno-peephole2} is in how they
5138are implemented in the compiler; some targets use one, some use the
5139other, a few use both.
5140
5141@option{-fpeephole} is enabled by default.
5142@option{-fpeephole2} enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5143
5144@item -fno-guess-branch-probability
5145@opindex fno-guess-branch-probability
5146Do not guess branch probabilities using heuristics.
5147
5148GCC will use heuristics to guess branch probabilities if they are
5149not provided by profiling feedback (@option{-fprofile-arcs}). These
5150heuristics are based on the control flow graph. If some branch probabilities
5151are specified by @samp{__builtin_expect}, then the heuristics will be
5152used to guess branch probabilities for the rest of the control flow graph,
5153taking the @samp{__builtin_expect} info into account. The interactions
5154between the heuristics and @samp{__builtin_expect} can be complex, and in
5155some cases, it may be useful to disable the heuristics so that the effects
5156of @samp{__builtin_expect} are easier to understand.
5157
5158The default is @option{-fguess-branch-probability} at levels
5159@option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5160
5161@item -freorder-blocks
5162@opindex freorder-blocks
5163Reorder basic blocks in the compiled function in order to reduce number of
5164taken branches and improve code locality.
5165
5166Enabled at levels @option{-O2}, @option{-O3}.
5167
5168@item -freorder-blocks-and-partition
5169@opindex freorder-blocks-and-partition
5170In addition to reordering basic blocks in the compiled function, in order
5171to reduce number of taken branches, partitions hot and cold basic blocks
5172into separate sections of the assembly and .o files, to improve
5173paging and cache locality performance.
5174
5175This optimization is automatically turned off in the presence of
5176exception handling, for linkonce sections, for functions with a user-defined
5177section attribute and on any architecture that does not support named
5178sections.
5179
5180@item -freorder-functions
5181@opindex freorder-functions
5182Reorder functions in the object file in order to
5183improve code locality. This is implemented by using special
5184subsections @code{.text.hot} for most frequently executed functions and
5185@code{.text.unlikely} for unlikely executed functions. Reordering is done by
5186the linker so object file format must support named sections and linker must
5187place them in a reasonable way.
5188
5189Also profile feedback must be available in to make this option effective. See
5190@option{-fprofile-arcs} for details.
5191
5192Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5193
5194@item -fstrict-aliasing
5195@opindex fstrict-aliasing
5196Allows the compiler to assume the strictest aliasing rules applicable to
5197the language being compiled. For C (and C++), this activates
5198optimizations based on the type of expressions. In particular, an
5199object of one type is assumed never to reside at the same address as an
5200object of a different type, unless the types are almost the same. For
5201example, an @code{unsigned int} can alias an @code{int}, but not a
5202@code{void*} or a @code{double}. A character type may alias any other
5203type.
5204
5205Pay special attention to code like this:
5206@smallexample
5207union a_union @{
5208 int i;
5209 double d;
5210@};
5211
5212int f() @{
5213 a_union t;
5214 t.d = 3.0;
5215 return t.i;
5216@}
5217@end smallexample
5218The practice of reading from a different union member than the one most
5219recently written to (called ``type-punning'') is common. Even with
5220@option{-fstrict-aliasing}, type-punning is allowed, provided the memory
5221is accessed through the union type. So, the code above will work as
5222expected. However, this code might not:
5223@smallexample
5224int f() @{
5225 a_union t;
5226 int* ip;
5227 t.d = 3.0;
5228 ip = &t.i;
5229 return *ip;
5230@}
5231@end smallexample
5232
5233Every language that wishes to perform language-specific alias analysis
5234should define a function that computes, given an @code{tree}
5235node, an alias set for the node. Nodes in different alias sets are not
5236allowed to alias. For an example, see the C front-end function
5237@code{c_get_alias_set}.
5238
5239Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5240
5241@item -fstrict-overflow
5242@opindex fstrict-overflow
5243Allow the compiler to assume strict signed overflow rules, depending
5244on the language being compiled. For C (and C++) this means that
5245overflow when doing arithmetic with signed numbers is undefined, which
5246means that the compiler may assume that it will not happen. This
5247permits various optimizations. For example, the compiler will assume
5248that an expression like @code{i + 10 > i} will always be true for
5249signed @code{i}. This assumption is only valid if signed overflow is
5250undefined, as the expression is false if @code{i + 10} overflows when
5251using twos complement arithmetic. When this option is in effect any
5252attempt to determine whether an operation on signed numbers will
5253overflow must be written carefully to not actually involve overflow.
5254
5255See also the @option{-fwrapv} option. Using @option{-fwrapv} means
5256that signed overflow is fully defined: it wraps. When
5257@option{-fwrapv} is used, there is no difference between
5258@option{-fstrict-overflow} and @option{-fno-strict-overflow}. With
5259@option{-fwrapv} certain types of overflow are permitted. For
5260example, if the compiler gets an overflow when doing arithmetic on
5261constants, the overflowed value can still be used with
5262@option{-fwrapv}, but not otherwise.
5263
5264The @option{-fstrict-overflow} option is enabled at levels
5265@option{-O2}, @option{-O3}, @option{-Os}.
5266
5267@item -falign-functions
5268@itemx -falign-functions=@var{n}
5269@opindex falign-functions
5270Align the start of functions to the next power-of-two greater than
5271@var{n}, skipping up to @var{n} bytes. For instance,
5272@option{-falign-functions=32} aligns functions to the next 32-byte
5273boundary, but @option{-falign-functions=24} would align to the next
527432-byte boundary only if this can be done by skipping 23 bytes or less.
5275
5276@option{-fno-align-functions} and @option{-falign-functions=1} are
5277equivalent and mean that functions will not be aligned.
5278
5279Some assemblers only support this flag when @var{n} is a power of two;
5280in that case, it is rounded up.
5281
5282If @var{n} is not specified or is zero, use a machine-dependent default.
5283
5284Enabled at levels @option{-O2}, @option{-O3}.
5285
5286@item -falign-labels
5287@itemx -falign-labels=@var{n}
5288@opindex falign-labels
5289Align all branch targets to a power-of-two boundary, skipping up to
5290@var{n} bytes like @option{-falign-functions}. This option can easily
5291make code slower, because it must insert dummy operations for when the
5292branch target is reached in the usual flow of the code.
5293
5294@option{-fno-align-labels} and @option{-falign-labels=1} are
5295equivalent and mean that labels will not be aligned.
5296
5297If @option{-falign-loops} or @option{-falign-jumps} are applicable and
5298are greater than this value, then their values are used instead.
5299
5300If @var{n} is not specified or is zero, use a machine-dependent default
5301which is very likely to be @samp{1}, meaning no alignment.
5302
5303Enabled at levels @option{-O2}, @option{-O3}.
5304
5305@item -falign-loops
5306@itemx -falign-loops=@var{n}
5307@opindex falign-loops
5308Align loops to a power-of-two boundary, skipping up to @var{n} bytes
5309like @option{-falign-functions}. The hope is that the loop will be
5310executed many times, which will make up for any execution of the dummy
5311operations.
5312
5313@option{-fno-align-loops} and @option{-falign-loops=1} are
5314equivalent and mean that loops will not be aligned.
5315
5316If @var{n} is not specified or is zero, use a machine-dependent default.
5317
5318Enabled at levels @option{-O2}, @option{-O3}.
5319
5320@item -falign-jumps
5321@itemx -falign-jumps=@var{n}
5322@opindex falign-jumps
5323Align branch targets to a power-of-two boundary, for branch targets
5324where the targets can only be reached by jumping, skipping up to @var{n}
5325bytes like @option{-falign-functions}. In this case, no dummy operations
5326need be executed.
5327
5328@option{-fno-align-jumps} and @option{-falign-jumps=1} are
5329equivalent and mean that loops will not be aligned.
5330
5331If @var{n} is not specified or is zero, use a machine-dependent default.
5332
5333Enabled at levels @option{-O2}, @option{-O3}.
5334
5335@item -funit-at-a-time
5336@opindex funit-at-a-time
5337Parse the whole compilation unit before starting to produce code.
5338This allows some extra optimizations to take place but consumes
5339more memory (in general). There are some compatibility issues
5340with @emph{unit-at-a-time} mode:
5341@itemize @bullet
5342@item
5343enabling @emph{unit-at-a-time} mode may change the order
5344in which functions, variables, and top-level @code{asm} statements
5345are emitted, and will likely break code relying on some particular
5346ordering. The majority of such top-level @code{asm} statements,
5347though, can be replaced by @code{section} attributes. The
5348@option{fno-toplevel-reorder} option may be used to keep the ordering
5349used in the input file, at the cost of some optimizations.
5350
5351@item
5352@emph{unit-at-a-time} mode removes unreferenced static variables
5353and functions. This may result in undefined references
5354when an @code{asm} statement refers directly to variables or functions
5355that are otherwise unused. In that case either the variable/function
5356shall be listed as an operand of the @code{asm} statement operand or,
5357in the case of top-level @code{asm} statements the attribute @code{used}
5358shall be used on the declaration.
5359
5360@item
5361Static functions now can use non-standard passing conventions that
5362may break @code{asm} statements calling functions directly. Again,
5363attribute @code{used} will prevent this behavior.
5364@end itemize
5365
5366As a temporary workaround, @option{-fno-unit-at-a-time} can be used,
5367but this scheme may not be supported by future releases of GCC@.
5368
5369Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5370
5371@item -fno-toplevel-reorder
5372Do not reorder top-level functions, variables, and @code{asm}
5373statements. Output them in the same order that they appear in the
5374input file. When this option is used, unreferenced static variables
5375will not be removed. This option is intended to support existing code
5376which relies on a particular ordering. For new code, it is better to
5377use attributes.
5378
5379@item -fweb
5380@opindex fweb
5381Constructs webs as commonly used for register allocation purposes and assign
5382each web individual pseudo register. This allows the register allocation pass
5383to operate on pseudos directly, but also strengthens several other optimization
5384passes, such as CSE, loop optimizer and trivial dead code remover. It can,
5385however, make debugging impossible, since variables will no longer stay in a
5386``home register''.
5387
5388Enabled by default with @option{-funroll-loops}.
5389
5390@item -fwhole-program
5391@opindex fwhole-program
5392Assume that the current compilation unit represents whole program being
5393compiled. All public functions and variables with the exception of @code{main}
5394and those merged by attribute @code{externally_visible} become static functions
5395and in a affect gets more aggressively optimized by interprocedural optimizers.
5396While this option is equivalent to proper use of @code{static} keyword for
5397programs consisting of single file, in combination with option
5398@option{--combine} this flag can be used to compile most of smaller scale C
5399programs since the functions and variables become local for the whole combined
5400compilation unit, not for the single source file itself.
5401
5402
5403@item -fno-cprop-registers
5404@opindex fno-cprop-registers
5405After register allocation and post-register allocation instruction splitting,
5406we perform a copy-propagation pass to try to reduce scheduling dependencies
5407and occasionally eliminate the copy.
5408
5409Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5410
5411@item -fprofile-generate
5412@opindex fprofile-generate
5413
5414Enable options usually used for instrumenting application to produce
5415profile useful for later recompilation with profile feedback based
5416optimization. You must use @option{-fprofile-generate} both when
5417compiling and when linking your program.
5418
5419The following options are enabled: @code{-fprofile-arcs}, @code{-fprofile-values}, @code{-fvpt}.
5420
5421@item -fprofile-use
5422@opindex fprofile-use
5423Enable profile feedback directed optimizations, and optimizations
5424generally profitable only with profile feedback available.
5425
5426The following options are enabled: @code{-fbranch-probabilities}, @code{-fvpt},
5427@code{-funroll-loops}, @code{-fpeel-loops}, @code{-ftracer}
5428
5429@end table
5430
5431The following options control compiler behavior regarding floating
5432point arithmetic. These options trade off between speed and
5433correctness. All must be specifically enabled.
5434
5435@table @gcctabopt
5436@item -ffloat-store
5437@opindex ffloat-store
5438Do not store floating point variables in registers, and inhibit other
5439options that might change whether a floating point value is taken from a
5440register or memory.
5441
5442@cindex floating point precision
5443This option prevents undesirable excess precision on machines such as
5444the 68000 where the floating registers (of the 68881) keep more
5445precision than a @code{double} is supposed to have. Similarly for the
5446x86 architecture. For most programs, the excess precision does only
5447good, but a few programs rely on the precise definition of IEEE floating
5448point. Use @option{-ffloat-store} for such programs, after modifying
5449them to store all pertinent intermediate computations into variables.
5450
5451@item -ffast-math
5452@opindex ffast-math
5453Sets @option{-fno-math-errno}, @option{-funsafe-math-optimizations}, @*
5454@option{-fno-trapping-math}, @option{-ffinite-math-only},
5455@option{-fno-rounding-math}, @option{-fno-signaling-nans}
5456and @option{fcx-limited-range}.
5457
5458This option causes the preprocessor macro @code{__FAST_MATH__} to be defined.
5459
5460This option should never be turned on by any @option{-O} option since
5461it can result in incorrect output for programs which depend on
5462an exact implementation of IEEE or ISO rules/specifications for
5463math functions.
5464
5465@item -fno-math-errno
5466@opindex fno-math-errno
5467Do not set ERRNO after calling math functions that are executed
5468with a single instruction, e.g., sqrt. A program that relies on
5469IEEE exceptions for math error handling may want to use this flag
5470for speed while maintaining IEEE arithmetic compatibility.
5471
5472This option should never be turned on by any @option{-O} option since
5473it can result in incorrect output for programs which depend on
5474an exact implementation of IEEE or ISO rules/specifications for
5475math functions.
5476
5477The default is @option{-fmath-errno}.
5478
5479On Darwin and FreeBSD systems, the math library never sets @code{errno}.
5480There is therefore
5481no reason for the compiler to consider the possibility that it might,
5482and @option{-fno-math-errno} is the default.
5483
5484@item -funsafe-math-optimizations
5485@opindex funsafe-math-optimizations
5486Allow optimizations for floating-point arithmetic that (a) assume
5487that arguments and results are valid and (b) may violate IEEE or
5488ANSI standards. When used at link-time, it may include libraries
5489or startup files that change the default FPU control word or other
5490similar optimizations.
5491
5492This option should never be turned on by any @option{-O} option since
5493it can result in incorrect output for programs which depend on
5494an exact implementation of IEEE or ISO rules/specifications for
5495math functions.
5496
5497The default is @option{-fno-unsafe-math-optimizations}.
5498
5499@item -ffinite-math-only
5500@opindex ffinite-math-only
5501Allow optimizations for floating-point arithmetic that assume
5502that arguments and results are not NaNs or +-Infs.
5503
5504This option should never be turned on by any @option{-O} option since
5505it can result in incorrect output for programs which depend on
5506an exact implementation of IEEE or ISO rules/specifications.
5507
5508The default is @option{-fno-finite-math-only}.
5509
5510@item -fno-trapping-math
5511@opindex fno-trapping-math
5512Compile code assuming that floating-point operations cannot generate
5513user-visible traps. These traps include division by zero, overflow,
5514underflow, inexact result and invalid operation. This option implies
5515@option{-fno-signaling-nans}. Setting this option may allow faster
5516code if one relies on ``non-stop'' IEEE arithmetic, for example.
5517
5518This option should never be turned on by any @option{-O} option since
5519it can result in incorrect output for programs which depend on
5520an exact implementation of IEEE or ISO rules/specifications for
5521math functions.
5522
5523The default is @option{-ftrapping-math}.
5524
5525@item -frounding-math
5526@opindex frounding-math
5527Disable transformations and optimizations that assume default floating
5528point rounding behavior. This is round-to-zero for all floating point
5529to integer conversions, and round-to-nearest for all other arithmetic
5530truncations. This option should be specified for programs that change
5531the FP rounding mode dynamically, or that may be executed with a
5532non-default rounding mode. This option disables constant folding of
5533floating point expressions at compile-time (which may be affected by
5534rounding mode) and arithmetic transformations that are unsafe in the
5535presence of sign-dependent rounding modes.
5536
5537The default is @option{-fno-rounding-math}.
5538
5539This option is experimental and does not currently guarantee to
5540disable all GCC optimizations that are affected by rounding mode.
5541Future versions of GCC may provide finer control of this setting
5542using C99's @code{FENV_ACCESS} pragma. This command line option
5543will be used to specify the default state for @code{FENV_ACCESS}.
5544
5545@item -frtl-abstract-sequences
5546@opindex frtl-abstract-sequences
5547It is a size optimization method. This option is to find identical
5548sequences of code, which can be turned into pseudo-procedures and
5549then replace all occurrences with calls to the newly created
5550subroutine. It is kind of an opposite of @option{-finline-functions}.
5551This optimization runs at RTL level.
5552
5553@item -fsignaling-nans
5554@opindex fsignaling-nans
5555Compile code assuming that IEEE signaling NaNs may generate user-visible
5556traps during floating-point operations. Setting this option disables
5557optimizations that may change the number of exceptions visible with
5558signaling NaNs. This option implies @option{-ftrapping-math}.
5559
5560This option causes the preprocessor macro @code{__SUPPORT_SNAN__} to
5561be defined.
5562
5563The default is @option{-fno-signaling-nans}.
5564
5565This option is experimental and does not currently guarantee to
5566disable all GCC optimizations that affect signaling NaN behavior.
5567
5568@item -fsingle-precision-constant
5569@opindex fsingle-precision-constant
5570Treat floating point constant as single precision constant instead of
5571implicitly converting it to double precision constant.
5572
5573@item -fcx-limited-range
5574@itemx -fno-cx-limited-range
5575@opindex fcx-limited-range
5576@opindex fno-cx-limited-range
5577When enabled, this option states that a range reduction step is not
5578needed when performing complex division. The default is
5579@option{-fno-cx-limited-range}, but is enabled by @option{-ffast-math}.
5580
5581This option controls the default setting of the ISO C99
5582@code{CX_LIMITED_RANGE} pragma. Nevertheless, the option applies to
5583all languages.
5584
5585@end table
5586
5587The following options control optimizations that may improve
5588performance, but are not enabled by any @option{-O} options. This
5589section includes experimental options that may produce broken code.
5590
5591@table @gcctabopt
5592@item -fbranch-probabilities
5593@opindex fbranch-probabilities
5594After running a program compiled with @option{-fprofile-arcs}
5595(@pxref{Debugging Options,, Options for Debugging Your Program or
5596@command{gcc}}), you can compile it a second time using
5597@option{-fbranch-probabilities}, to improve optimizations based on
5598the number of times each branch was taken. When the program
5599compiled with @option{-fprofile-arcs} exits it saves arc execution
5600counts to a file called @file{@var{sourcename}.gcda} for each source
5601file The information in this data file is very dependent on the
5602structure of the generated code, so you must use the same source code
5603and the same optimization options for both compilations.
5604
5605With @option{-fbranch-probabilities}, GCC puts a
5606@samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}.
5607These can be used to improve optimization. Currently, they are only
5608used in one place: in @file{reorg.c}, instead of guessing which path a
5609branch is mostly to take, the @samp{REG_BR_PROB} values are used to
5610exactly determine which path is taken more often.
5611
5612@item -fprofile-values
5613@opindex fprofile-values
5614If combined with @option{-fprofile-arcs}, it adds code so that some
5615data about values of expressions in the program is gathered.
5616
5617With @option{-fbranch-probabilities}, it reads back the data gathered
5618from profiling values of expressions and adds @samp{REG_VALUE_PROFILE}
5619notes to instructions for their later usage in optimizations.
5620
5621Enabled with @option{-fprofile-generate} and @option{-fprofile-use}.
5622
5623@item -fvpt
5624@opindex fvpt
5625If combined with @option{-fprofile-arcs}, it instructs the compiler to add
5626a code to gather information about values of expressions.
5627
5628With @option{-fbranch-probabilities}, it reads back the data gathered
5629and actually performs the optimizations based on them.
5630Currently the optimizations include specialization of division operation
5631using the knowledge about the value of the denominator.
5632
5633@item -frename-registers
5634@opindex frename-registers
5635Attempt to avoid false dependencies in scheduled code by making use
5636of registers left over after register allocation. This optimization
5637will most benefit processors with lots of registers. Depending on the
5638debug information format adopted by the target, however, it can
5639make debugging impossible, since variables will no longer stay in
5640a ``home register''.
5641
5642Enabled by default with @option{-funroll-loops}.
5643
5644@item -ftracer
5645@opindex ftracer
5646Perform tail duplication to enlarge superblock size. This transformation
5647simplifies the control flow of the function allowing other optimizations to do
5648better job.
5649
5650Enabled with @option{-fprofile-use}.
5651
5652@item -funroll-loops
5653@opindex funroll-loops
5654Unroll loops whose number of iterations can be determined at compile time or
5655upon entry to the loop. @option{-funroll-loops} implies
5656@option{-frerun-cse-after-loop}, @option{-fweb} and @option{-frename-registers}.
5657It also turns on complete loop peeling (i.e.@: complete removal of loops with
5658small constant number of iterations). This option makes code larger, and may
5659or may not make it run faster.
5660
5661Enabled with @option{-fprofile-use}.
5662
5663@item -funroll-all-loops
5664@opindex funroll-all-loops
5665Unroll all loops, even if their number of iterations is uncertain when
5666the loop is entered. This usually makes programs run more slowly.
5667@option{-funroll-all-loops} implies the same options as
5668@option{-funroll-loops}.
5669
5670@item -fpeel-loops
5671@opindex fpeel-loops
5672Peels the loops for that there is enough information that they do not
5673roll much (from profile feedback). It also turns on complete loop peeling
5674(i.e.@: complete removal of loops with small constant number of iterations).
5675
5676Enabled with @option{-fprofile-use}.
5677
5678@item -fmove-loop-invariants
5679@opindex fmove-loop-invariants
5680Enables the loop invariant motion pass in the RTL loop optimizer. Enabled
5681at level @option{-O1}
5682
5683@item -funswitch-loops
5684@opindex funswitch-loops
5685Move branches with loop invariant conditions out of the loop, with duplicates
5686of the loop on both branches (modified according to result of the condition).
5687
5688@item -ffunction-sections
5689@itemx -fdata-sections
5690@opindex ffunction-sections
5691@opindex fdata-sections
5692Place each function or data item into its own section in the output
5693file if the target supports arbitrary sections. The name of the
5694function or the name of the data item determines the section's name
5695in the output file.
5696
5697Use these options on systems where the linker can perform optimizations
5698to improve locality of reference in the instruction space. Most systems
5699using the ELF object format and SPARC processors running Solaris 2 have
5700linkers with such optimizations. AIX may have these optimizations in
5701the future.
5702
5703Only use these options when there are significant benefits from doing
5704so. When you specify these options, the assembler and linker will
5705create larger object and executable files and will also be slower.
5706You will not be able to use @code{gprof} on all systems if you
5707specify this option and you may have problems with debugging if
5708you specify both this option and @option{-g}.
5709
5710@item -fbranch-target-load-optimize
5711@opindex fbranch-target-load-optimize
5712Perform branch target register load optimization before prologue / epilogue
5713threading.
5714The use of target registers can typically be exposed only during reload,
5715thus hoisting loads out of loops and doing inter-block scheduling needs
5716a separate optimization pass.
5717
5718@item -fbranch-target-load-optimize2
5719@opindex fbranch-target-load-optimize2
5720Perform branch target register load optimization after prologue / epilogue
5721threading.
5722
5723@item -fbtr-bb-exclusive
5724@opindex fbtr-bb-exclusive
5725When performing branch target register load optimization, don't reuse
5726branch target registers in within any basic block.
5727
5728@item -fstack-protector
5729Emit extra code to check for buffer overflows, such as stack smashing
5730attacks. This is done by adding a guard variable to functions with
5731vulnerable objects. This includes functions that call alloca, and
5732functions with buffers larger than 8 bytes. The guards are initialized
5733when a function is entered and then checked when the function exits.
5734If a guard check fails, an error message is printed and the program exits.
5735
5736@item -fstack-protector-all
5737Like @option{-fstack-protector} except that all functions are protected.
5738
5739@item -fsection-anchors
5740@opindex fsection-anchors
5741Try to reduce the number of symbolic address calculations by using
5742shared ``anchor'' symbols to address nearby objects. This transformation
5743can help to reduce the number of GOT entries and GOT accesses on some
5744targets.
5745
5746For example, the implementation of the following function @code{foo}:
5747
5748@smallexample
5749static int a, b, c;
5750int foo (void) @{ return a + b + c; @}
5751@end smallexample
5752
5753would usually calculate the addresses of all three variables, but if you
5754compile it with @option{-fsection-anchors}, it will access the variables
5755from a common anchor point instead. The effect is similar to the
5756following pseudocode (which isn't valid C):
5757
5758@smallexample
5759int foo (void)
5760@{
5761 register int *xr = &x;
5762 return xr[&a - &x] + xr[&b - &x] + xr[&c - &x];
5763@}
5764@end smallexample
5765
5766Not all targets support this option.
5767
5768@item --param @var{name}=@var{value}
5769@opindex param
5770In some places, GCC uses various constants to control the amount of
5771optimization that is done. For example, GCC will not inline functions
5772that contain more that a certain number of instructions. You can
5773control some of these constants on the command-line using the
5774@option{--param} option.
5775
5776The names of specific parameters, and the meaning of the values, are
5777tied to the internals of the compiler, and are subject to change
5778without notice in future releases.
5779
5780In each case, the @var{value} is an integer. The allowable choices for
5781@var{name} are given in the following table:
5782
5783@table @gcctabopt
5784@item salias-max-implicit-fields
5785The maximum number of fields in a variable without direct
5786structure accesses for which structure aliasing will consider trying
5787to track each field. The default is 5
5788
5789@item salias-max-array-elements
5790The maximum number of elements an array can have and its elements
5791still be tracked individually by structure aliasing. The default is 4
5792
5793@item sra-max-structure-size
5794The maximum structure size, in bytes, at which the scalar replacement
5795of aggregates (SRA) optimization will perform block copies. The
5796default value, 0, implies that GCC will select the most appropriate
5797size itself.
5798
5799@item sra-field-structure-ratio
5800The threshold ratio (as a percentage) between instantiated fields and
5801the complete structure size. We say that if the ratio of the number
5802of bytes in instantiated fields to the number of bytes in the complete
5803structure exceeds this parameter, then block copies are not used. The
5804default is 75.
5805
5806@item max-crossjump-edges
5807The maximum number of incoming edges to consider for crossjumping.
5808The algorithm used by @option{-fcrossjumping} is @math{O(N^2)} in
5809the number of edges incoming to each block. Increasing values mean
5810more aggressive optimization, making the compile time increase with
5811probably small improvement in executable size.
5812
5813@item min-crossjump-insns
5814The minimum number of instructions which must be matched at the end
5815of two blocks before crossjumping will be performed on them. This
5816value is ignored in the case where all instructions in the block being
5817crossjumped from are matched. The default value is 5.
5818
5819@item max-grow-copy-bb-insns
5820The maximum code size expansion factor when copying basic blocks
5821instead of jumping. The expansion is relative to a jump instruction.
5822The default value is 8.
5823
5824@item max-goto-duplication-insns
5825The maximum number of instructions to duplicate to a block that jumps
5826to a computed goto. To avoid @math{O(N^2)} behavior in a number of
5827passes, GCC factors computed gotos early in the compilation process,
5828and unfactors them as late as possible. Only computed jumps at the
5829end of a basic blocks with no more than max-goto-duplication-insns are
5830unfactored. The default value is 8.
5831
5832@item max-delay-slot-insn-search
5833The maximum number of instructions to consider when looking for an
5834instruction to fill a delay slot. If more than this arbitrary number of
5835instructions is searched, the time savings from filling the delay slot
5836will be minimal so stop searching. Increasing values mean more
5837aggressive optimization, making the compile time increase with probably
5838small improvement in executable run time.
5839
5840@item max-delay-slot-live-search
5841When trying to fill delay slots, the maximum number of instructions to
5842consider when searching for a block with valid live register
5843information. Increasing this arbitrarily chosen value means more
5844aggressive optimization, increasing the compile time. This parameter
5845should be removed when the delay slot code is rewritten to maintain the
5846control-flow graph.
5847
5848@item max-gcse-memory
5849The approximate maximum amount of memory that will be allocated in
5850order to perform the global common subexpression elimination
5851optimization. If more memory than specified is required, the
5852optimization will not be done.
5853
5854@item max-gcse-passes
5855The maximum number of passes of GCSE to run. The default is 1.
5856
5857@item max-pending-list-length
5858The maximum number of pending dependencies scheduling will allow
5859before flushing the current state and starting over. Large functions
5860with few branches or calls can create excessively large lists which
5861needlessly consume memory and resources.
5862
5863@item max-inline-insns-single
5864Several parameters control the tree inliner used in gcc.
5865This number sets the maximum number of instructions (counted in GCC's
5866internal representation) in a single function that the tree inliner
5867will consider for inlining. This only affects functions declared
5868inline and methods implemented in a class declaration (C++).
5869The default value is 450.
5870
5871@item max-inline-insns-auto
5872When you use @option{-finline-functions} (included in @option{-O3}),
5873a lot of functions that would otherwise not be considered for inlining
5874by the compiler will be investigated. To those functions, a different
5875(more restrictive) limit compared to functions declared inline can
5876be applied.
5877The default value is 90.
5878
5879@item large-function-insns
5880The limit specifying really large functions. For functions larger than this
5881limit after inlining inlining is constrained by
5882@option{--param large-function-growth}. This parameter is useful primarily
5883to avoid extreme compilation time caused by non-linear algorithms used by the
5884backend.
5885This parameter is ignored when @option{-funit-at-a-time} is not used.
5886The default value is 2700.
5887
5888@item large-function-growth
5889Specifies maximal growth of large function caused by inlining in percents.
5890This parameter is ignored when @option{-funit-at-a-time} is not used.
5891The default value is 100 which limits large function growth to 2.0 times
5892the original size.
5893
5894@item large-unit-insns
5895The limit specifying large translation unit. Growth caused by inlining of
5896units larger than this limit is limited by @option{--param inline-unit-growth}.
5897For small units this might be too tight (consider unit consisting of function A
5898that is inline and B that just calls A three time. If B is small relative to
5899A, the growth of unit is 300\% and yet such inlining is very sane. For very
5900large units consisting of small inlininable functions however the overall unit
5901growth limit is needed to avoid exponential explosion of code size. Thus for
5902smaller units, the size is increased to @option{--param large-unit-insns}
5903before applying @option{--param inline-unit-growth}. The default is 10000
5904
5905@item inline-unit-growth
5906Specifies maximal overall growth of the compilation unit caused by inlining.
5907This parameter is ignored when @option{-funit-at-a-time} is not used.
5908The default value is 50 which limits unit growth to 1.5 times the original
5909size.
5910
5911@item max-inline-insns-recursive
5912@itemx max-inline-insns-recursive-auto
5913Specifies maximum number of instructions out-of-line copy of self recursive inline
5914function can grow into by performing recursive inlining.
5915
5916For functions declared inline @option{--param max-inline-insns-recursive} is
5917taken into account. For function not declared inline, recursive inlining
5918happens only when @option{-finline-functions} (included in @option{-O3}) is
5919enabled and @option{--param max-inline-insns-recursive-auto} is used. The
5920default value is 450.
5921
5922@item max-inline-recursive-depth
5923@itemx max-inline-recursive-depth-auto
5924Specifies maximum recursion depth used by the recursive inlining.
5925
5926For functions declared inline @option{--param max-inline-recursive-depth} is
5927taken into account. For function not declared inline, recursive inlining
5928happens only when @option{-finline-functions} (included in @option{-O3}) is
5929enabled and @option{--param max-inline-recursive-depth-auto} is used. The
5930default value is 450.
5931
5932@item min-inline-recursive-probability
5933Recursive inlining is profitable only for function having deep recursion
5934in average and can hurt for function having little recursion depth by
5935increasing the prologue size or complexity of function body to other
5936optimizers.
5937
5938When profile feedback is available (see @option{-fprofile-generate}) the actual
5939recursion depth can be guessed from probability that function will recurse via
5940given call expression. This parameter limits inlining only to call expression
5941whose probability exceeds given threshold (in percents). The default value is
594210.
5943
5944@item inline-call-cost
5945Specify cost of call instruction relative to simple arithmetics operations
5946(having cost of 1). Increasing this cost disqualifies inlining of non-leaf
5947functions and at the same time increases size of leaf function that is believed to
5948reduce function size by being inlined. In effect it increases amount of
5949inlining for code having large abstraction penalty (many functions that just
5950pass the arguments to other functions) and decrease inlining for code with low
5951abstraction penalty. The default value is 16.
5952
5953@item max-unrolled-insns
5954The maximum number of instructions that a loop should have if that loop
5955is unrolled, and if the loop is unrolled, it determines how many times
5956the loop code is unrolled.
5957
5958@item max-average-unrolled-insns
5959The maximum number of instructions biased by probabilities of their execution
5960that a loop should have if that loop is unrolled, and if the loop is unrolled,
5961it determines how many times the loop code is unrolled.
5962
5963@item max-unroll-times
5964The maximum number of unrollings of a single loop.
5965
5966@item max-peeled-insns
5967The maximum number of instructions that a loop should have if that loop
5968is peeled, and if the loop is peeled, it determines how many times
5969the loop code is peeled.
5970
5971@item max-peel-times
5972The maximum number of peelings of a single loop.
5973
5974@item max-completely-peeled-insns
5975The maximum number of insns of a completely peeled loop.
5976
5977@item max-completely-peel-times
5978The maximum number of iterations of a loop to be suitable for complete peeling.
5979
5980@item max-unswitch-insns
5981The maximum number of insns of an unswitched loop.
5982
5983@item max-unswitch-level
5984The maximum number of branches unswitched in a single loop.
5985
5986@item lim-expensive
5987The minimum cost of an expensive expression in the loop invariant motion.
5988
5989@item iv-consider-all-candidates-bound
5990Bound on number of candidates for induction variables below that
5991all candidates are considered for each use in induction variable
5992optimizations. Only the most relevant candidates are considered
5993if there are more candidates, to avoid quadratic time complexity.
5994
5995@item iv-max-considered-uses
5996The induction variable optimizations give up on loops that contain more
5997induction variable uses.
5998
5999@item iv-always-prune-cand-set-bound
6000If number of candidates in the set is smaller than this value,
6001we always try to remove unnecessary ivs from the set during its
6002optimization when a new iv is added to the set.
6003
6004@item scev-max-expr-size
6005Bound on size of expressions used in the scalar evolutions analyzer.
6006Large expressions slow the analyzer.
6007
6008@item vect-max-version-checks
6009The maximum number of runtime checks that can be performed when doing
6010loop versioning in the vectorizer. See option ftree-vect-loop-version
6011for more information.
6012
6013@item max-iterations-to-track
6014
6015The maximum number of iterations of a loop the brute force algorithm
6016for analysis of # of iterations of the loop tries to evaluate.
6017
6018@item hot-bb-count-fraction
6019Select fraction of the maximal count of repetitions of basic block in program
6020given basic block needs to have to be considered hot.
6021
6022@item hot-bb-frequency-fraction
6023Select fraction of the maximal frequency of executions of basic block in
6024function given basic block needs to have to be considered hot
6025
6026@item max-predicted-iterations
6027The maximum number of loop iterations we predict statically. This is useful
6028in cases where function contain single loop with known bound and other loop
6029with unknown. We predict the known number of iterations correctly, while
6030the unknown number of iterations average to roughly 10. This means that the
6031loop without bounds would appear artificially cold relative to the other one.
6032
6033@item tracer-dynamic-coverage
6034@itemx tracer-dynamic-coverage-feedback
6035
6036This value is used to limit superblock formation once the given percentage of
6037executed instructions is covered. This limits unnecessary code size
6038expansion.
6039
6040The @option{tracer-dynamic-coverage-feedback} is used only when profile
6041feedback is available. The real profiles (as opposed to statically estimated
6042ones) are much less balanced allowing the threshold to be larger value.
6043
6044@item tracer-max-code-growth
6045Stop tail duplication once code growth has reached given percentage. This is
6046rather hokey argument, as most of the duplicates will be eliminated later in
6047cross jumping, so it may be set to much higher values than is the desired code
6048growth.
6049
6050@item tracer-min-branch-ratio
6051
6052Stop reverse growth when the reverse probability of best edge is less than this
6053threshold (in percent).
6054
6055@item tracer-min-branch-ratio
6056@itemx tracer-min-branch-ratio-feedback
6057
6058Stop forward growth if the best edge do have probability lower than this
6059threshold.
6060
6061Similarly to @option{tracer-dynamic-coverage} two values are present, one for
6062compilation for profile feedback and one for compilation without. The value
6063for compilation with profile feedback needs to be more conservative (higher) in
6064order to make tracer effective.
6065
6066@item max-cse-path-length
6067
6068Maximum number of basic blocks on path that cse considers. The default is 10.
6069
6070@item max-cse-insns
6071The maximum instructions CSE process before flushing. The default is 1000.
6072
6073@item global-var-threshold
6074
6075Counts the number of function calls (@var{n}) and the number of
6076call-clobbered variables (@var{v}). If @var{n}x@var{v} is larger than this limit, a
6077single artificial variable will be created to represent all the
6078call-clobbered variables at function call sites. This artificial
6079variable will then be made to alias every call-clobbered variable.
6080(done as @code{int * size_t} on the host machine; beware overflow).
6081
6082@item max-aliased-vops
6083
6084Maximum number of virtual operands allowed to represent aliases
6085before triggering the alias grouping heuristic. Alias grouping
6086reduces compile times and memory consumption needed for aliasing at
6087the expense of precision loss in alias information.
6088
6089@item ggc-min-expand
6090
6091GCC uses a garbage collector to manage its own memory allocation. This
6092parameter specifies the minimum percentage by which the garbage
6093collector's heap should be allowed to expand between collections.
6094Tuning this may improve compilation speed; it has no effect on code
6095generation.
6096
6097The default is 30% + 70% * (RAM/1GB) with an upper bound of 100% when
6098RAM >= 1GB@. If @code{getrlimit} is available, the notion of "RAM" is
6099the smallest of actual RAM and @code{RLIMIT_DATA} or @code{RLIMIT_AS}. If
6100GCC is not able to calculate RAM on a particular platform, the lower
6101bound of 30% is used. Setting this parameter and
6102@option{ggc-min-heapsize} to zero causes a full collection to occur at
6103every opportunity. This is extremely slow, but can be useful for
6104debugging.
6105
6106@item ggc-min-heapsize
6107
6108Minimum size of the garbage collector's heap before it begins bothering
6109to collect garbage. The first collection occurs after the heap expands
6110by @option{ggc-min-expand}% beyond @option{ggc-min-heapsize}. Again,
6111tuning this may improve compilation speed, and has no effect on code
6112generation.
6113
6114The default is the smaller of RAM/8, RLIMIT_RSS, or a limit which
6115tries to ensure that RLIMIT_DATA or RLIMIT_AS are not exceeded, but
6116with a lower bound of 4096 (four megabytes) and an upper bound of
6117131072 (128 megabytes). If GCC is not able to calculate RAM on a
6118particular platform, the lower bound is used. Setting this parameter
6119very large effectively disables garbage collection. Setting this
6120parameter and @option{ggc-min-expand} to zero causes a full collection
6121to occur at every opportunity.
6122
6123@item max-reload-search-insns
6124The maximum number of instruction reload should look backward for equivalent
6125register. Increasing values mean more aggressive optimization, making the
6126compile time increase with probably slightly better performance. The default
6127value is 100.
6128
6129@item max-cselib-memory-locations
6130The maximum number of memory locations cselib should take into account.
6131Increasing values mean more aggressive optimization, making the compile time
6132increase with probably slightly better performance. The default value is 500.
6133
6134@item max-flow-memory-locations
6135Similar as @option{max-cselib-memory-locations} but for dataflow liveness.
6136The default value is 100.
6137
6138@item reorder-blocks-duplicate
6139@itemx reorder-blocks-duplicate-feedback
6140
6141Used by basic block reordering pass to decide whether to use unconditional
6142branch or duplicate the code on its destination. Code is duplicated when its
6143estimated size is smaller than this value multiplied by the estimated size of
6144unconditional jump in the hot spots of the program.
6145
6146The @option{reorder-block-duplicate-feedback} is used only when profile
6147feedback is available and may be set to higher values than
6148@option{reorder-block-duplicate} since information about the hot spots is more
6149accurate.
6150
6151@item max-sched-ready-insns
6152The maximum number of instructions ready to be issued the scheduler should
6153consider at any given time during the first scheduling pass. Increasing
6154values mean more thorough searches, making the compilation time increase
6155with probably little benefit. The default value is 100.
6156
6157@item max-sched-region-blocks
6158The maximum number of blocks in a region to be considered for
6159interblock scheduling. The default value is 10.
6160
6161@item max-sched-region-insns
6162The maximum number of insns in a region to be considered for
6163interblock scheduling. The default value is 100.
6164
6165@item min-spec-prob
6166The minimum probability (in percents) of reaching a source block
6167for interblock speculative scheduling. The default value is 40.
6168
6169@item max-sched-extend-regions-iters
6170The maximum number of iterations through CFG to extend regions.
61710 - disable region extension,
6172N - do at most N iterations.
6173The default value is 0.
6174
6175@item max-sched-insn-conflict-delay
6176The maximum conflict delay for an insn to be considered for speculative motion.
6177The default value is 3.
6178
6179@item sched-spec-prob-cutoff
6180The minimal probability of speculation success (in percents), so that
6181speculative insn will be scheduled.
6182The default value is 40.
6183
6184@item max-last-value-rtl
6185
6186The maximum size measured as number of RTLs that can be recorded in an expression
6187in combiner for a pseudo register as last known value of that register. The default
6188is 10000.
6189
6190@item integer-share-limit
6191Small integer constants can use a shared data structure, reducing the
6192compiler's memory usage and increasing its speed. This sets the maximum
6193value of a shared integer constant's. The default value is 256.
6194
6195@item min-virtual-mappings
6196Specifies the minimum number of virtual mappings in the incremental
6197SSA updater that should be registered to trigger the virtual mappings
6198heuristic defined by virtual-mappings-ratio. The default value is
6199100.
6200
6201@item virtual-mappings-ratio
6202If the number of virtual mappings is virtual-mappings-ratio bigger
6203than the number of virtual symbols to be updated, then the incremental
6204SSA updater switches to a full update for those symbols. The default
6205ratio is 3.
6206
6207@item ssp-buffer-size
6208The minimum size of buffers (i.e. arrays) that will receive stack smashing
6209protection when @option{-fstack-protection} is used.
6210
6211@item max-jump-thread-duplication-stmts
6212Maximum number of statements allowed in a block that needs to be
6213duplicated when threading jumps.
6214
6215@item max-fields-for-field-sensitive
6216Maximum number of fields in a structure we will treat in
6217a field sensitive manner during pointer analysis.
6218
6219@end table
6220@end table
6221
6222@node Preprocessor Options
6223@section Options Controlling the Preprocessor
6224@cindex preprocessor options
6225@cindex options, preprocessor
6226
6227These options control the C preprocessor, which is run on each C source
6228file before actual compilation.
6229
6230If you use the @option{-E} option, nothing is done except preprocessing.
6231Some of these options make sense only together with @option{-E} because
6232they cause the preprocessor output to be unsuitable for actual
6233compilation.
6234
6235@table @gcctabopt
6236@opindex Wp
6237You can use @option{-Wp,@var{option}} to bypass the compiler driver
6238and pass @var{option} directly through to the preprocessor. If
6239@var{option} contains commas, it is split into multiple options at the
6240commas. However, many options are modified, translated or interpreted
6241by the compiler driver before being passed to the preprocessor, and
6242@option{-Wp} forcibly bypasses this phase. The preprocessor's direct
6243interface is undocumented and subject to change, so whenever possible
6244you should avoid using @option{-Wp} and let the driver handle the
6245options instead.
6246
6247@item -Xpreprocessor @var{option}
6248@opindex preprocessor
6249Pass @var{option} as an option to the preprocessor. You can use this to
6250supply system-specific preprocessor options which GCC does not know how to
6251recognize.
6252
6253If you want to pass an option that takes an argument, you must use
6254@option{-Xpreprocessor} twice, once for the option and once for the argument.
6255@end table
6256
6257@include cppopts.texi
6258
6259@node Assembler Options
6260@section Passing Options to the Assembler
6261
6262@c prevent bad page break with this line
6263You can pass options to the assembler.
6264
6265@table @gcctabopt
6266@item -Wa,@var{option}
6267@opindex Wa
6268Pass @var{option} as an option to the assembler. If @var{option}
6269contains commas, it is split into multiple options at the commas.
6270
6271@item -Xassembler @var{option}
6272@opindex Xassembler
6273Pass @var{option} as an option to the assembler. You can use this to
6274supply system-specific assembler options which GCC does not know how to
6275recognize.
6276
6277If you want to pass an option that takes an argument, you must use
6278@option{-Xassembler} twice, once for the option and once for the argument.
6279
6280@end table
6281
6282@node Link Options
6283@section Options for Linking
6284@cindex link options
6285@cindex options, linking
6286
6287These options come into play when the compiler links object files into
6288an executable output file. They are meaningless if the compiler is
6289not doing a link step.
6290
6291@table @gcctabopt
6292@cindex file names
6293@item @var{object-file-name}
6294A file name that does not end in a special recognized suffix is
6295considered to name an object file or library. (Object files are
6296distinguished from libraries by the linker according to the file
6297contents.) If linking is done, these object files are used as input
6298to the linker.
6299
6300@item -c
6301@itemx -S
6302@itemx -E
6303@opindex c
6304@opindex S
6305@opindex E
6306If any of these options is used, then the linker is not run, and
6307object file names should not be used as arguments. @xref{Overall
6308Options}.
6309
6310@cindex Libraries
6311@item -l@var{library}
6312@itemx -l @var{library}
6313@opindex l
6314Search the library named @var{library} when linking. (The second
6315alternative with the library as a separate argument is only for
6316POSIX compliance and is not recommended.)
6317
6318It makes a difference where in the command you write this option; the
6319linker searches and processes libraries and object files in the order they
6320are specified. Thus, @samp{foo.o -lz bar.o} searches library @samp{z}
6321after file @file{foo.o} but before @file{bar.o}. If @file{bar.o} refers
6322to functions in @samp{z}, those functions may not be loaded.
6323
6324The linker searches a standard list of directories for the library,
6325which is actually a file named @file{lib@var{library}.a}. The linker
6326then uses this file as if it had been specified precisely by name.
6327
6328The directories searched include several standard system directories
6329plus any that you specify with @option{-L}.
6330
6331Normally the files found this way are library files---archive files
6332whose members are object files. The linker handles an archive file by
6333scanning through it for members which define symbols that have so far
6334been referenced but not defined. But if the file that is found is an
6335ordinary object file, it is linked in the usual fashion. The only
6336difference between using an @option{-l} option and specifying a file name
6337is that @option{-l} surrounds @var{library} with @samp{lib} and @samp{.a}
6338and searches several directories.
6339
6340@item -nostartfiles
6341@opindex nostartfiles
6342Do not use the standard system startup files when linking.
6343The standard system libraries are used normally, unless @option{-nostdlib}
6344or @option{-nodefaultlibs} is used.
6345
6346@item -nodefaultlibs
6347@opindex nodefaultlibs
6348Do not use the standard system libraries when linking.
6349Only the libraries you specify will be passed to the linker.
6350The standard startup files are used normally, unless @option{-nostartfiles}
6351is used. The compiler may generate calls to @code{memcmp},
6352@code{memset}, @code{memcpy} and @code{memmove}.
6353These entries are usually resolved by entries in
6354libc. These entry points should be supplied through some other
6355mechanism when this option is specified.
6356
6357@item -nostdlib
6358@opindex nostdlib
6359Do not use the standard system startup files or libraries when linking.
6360No startup files and only the libraries you specify will be passed to
6361the linker. The compiler may generate calls to @code{memcmp}, @code{memset},
6362@code{memcpy} and @code{memmove}.
6363These entries are usually resolved by entries in
6364libc. These entry points should be supplied through some other
6365mechanism when this option is specified.
6366
6367@cindex @option{-lgcc}, use with @option{-nostdlib}
6368@cindex @option{-nostdlib} and unresolved references
6369@cindex unresolved references and @option{-nostdlib}
6370@cindex @option{-lgcc}, use with @option{-nodefaultlibs}
6371@cindex @option{-nodefaultlibs} and unresolved references
6372@cindex unresolved references and @option{-nodefaultlibs}
6373One of the standard libraries bypassed by @option{-nostdlib} and
6374@option{-nodefaultlibs} is @file{libgcc.a}, a library of internal subroutines
6375that GCC uses to overcome shortcomings of particular machines, or special
6376needs for some languages.
6377(@xref{Interface,,Interfacing to GCC Output,gccint,GNU Compiler
6378Collection (GCC) Internals},
6379for more discussion of @file{libgcc.a}.)
6380In most cases, you need @file{libgcc.a} even when you want to avoid
6381other standard libraries. In other words, when you specify @option{-nostdlib}
6382or @option{-nodefaultlibs} you should usually specify @option{-lgcc} as well.
6383This ensures that you have no unresolved references to internal GCC
6384library subroutines. (For example, @samp{__main}, used to ensure C++
6385constructors will be called; @pxref{Collect2,,@code{collect2}, gccint,
6386GNU Compiler Collection (GCC) Internals}.)
6387
6388@item -pie
6389@opindex pie
6390Produce a position independent executable on targets which support it.
6391For predictable results, you must also specify the same set of options
6392that were used to generate code (@option{-fpie}, @option{-fPIE},
6393or model suboptions) when you specify this option.
6394
6395@item -rdynamic
6396@opindex rdynamic
6397Pass the flag @option{-export-dynamic} to the ELF linker, on targets
6398that support it. This instructs the linker to add all symbols, not
6399only used ones, to the dynamic symbol table. This option is needed
6400for some uses of @code{dlopen} or to allow obtaining backtraces
6401from within a program.
6402
6403@item -s
6404@opindex s
6405Remove all symbol table and relocation information from the executable.
6406
6407@item -static
6408@opindex static
6409On systems that support dynamic linking, this prevents linking with the shared
6410libraries. On other systems, this option has no effect.
6411
6412@item -shared
6413@opindex shared
6414Produce a shared object which can then be linked with other objects to
6415form an executable. Not all systems support this option. For predictable
6416results, you must also specify the same set of options that were used to
6417generate code (@option{-fpic}, @option{-fPIC}, or model suboptions)
6418when you specify this option.@footnote{On some systems, @samp{gcc -shared}
6419needs to build supplementary stub code for constructors to work. On
6420multi-libbed systems, @samp{gcc -shared} must select the correct support
6421libraries to link against. Failing to supply the correct flags may lead
6422to subtle defects. Supplying them in cases where they are not necessary
6423is innocuous.}
6424
6425@item -shared-libgcc
6426@itemx -static-libgcc
6427@opindex shared-libgcc
6428@opindex static-libgcc
6429On systems that provide @file{libgcc} as a shared library, these options
6430force the use of either the shared or static version respectively.
6431If no shared version of @file{libgcc} was built when the compiler was
6432configured, these options have no effect.
6433
6434There are several situations in which an application should use the
6435shared @file{libgcc} instead of the static version. The most common
6436of these is when the application wishes to throw and catch exceptions
6437across different shared libraries. In that case, each of the libraries
6438as well as the application itself should use the shared @file{libgcc}.
6439
6440Therefore, the G++ and GCJ drivers automatically add
6441@option{-shared-libgcc} whenever you build a shared library or a main
6442executable, because C++ and Java programs typically use exceptions, so
6443this is the right thing to do.
6444
6445If, instead, you use the GCC driver to create shared libraries, you may
6446find that they will not always be linked with the shared @file{libgcc}.
6447If GCC finds, at its configuration time, that you have a non-GNU linker
6448or a GNU linker that does not support option @option{--eh-frame-hdr},
6449it will link the shared version of @file{libgcc} into shared libraries
6450by default. Otherwise, it will take advantage of the linker and optimize
6451away the linking with the shared version of @file{libgcc}, linking with
6452the static version of libgcc by default. This allows exceptions to
6453propagate through such shared libraries, without incurring relocation
6454costs at library load time.
6455
6456However, if a library or main executable is supposed to throw or catch
6457exceptions, you must link it using the G++ or GCJ driver, as appropriate
6458for the languages used in the program, or using the option
6459@option{-shared-libgcc}, such that it is linked with the shared
6460@file{libgcc}.
6461
6462@item -symbolic
6463@opindex symbolic
6464Bind references to global symbols when building a shared object. Warn
6465about any unresolved references (unless overridden by the link editor
6466option @samp{-Xlinker -z -Xlinker defs}). Only a few systems support
6467this option.
6468
6469@item -Xlinker @var{option}
6470@opindex Xlinker
6471Pass @var{option} as an option to the linker. You can use this to
6472supply system-specific linker options which GCC does not know how to
6473recognize.
6474
6475If you want to pass an option that takes an argument, you must use
6476@option{-Xlinker} twice, once for the option and once for the argument.
6477For example, to pass @option{-assert definitions}, you must write
6478@samp{-Xlinker -assert -Xlinker definitions}. It does not work to write
6479@option{-Xlinker "-assert definitions"}, because this passes the entire
6480string as a single argument, which is not what the linker expects.
6481
6482@item -Wl,@var{option}
6483@opindex Wl
6484Pass @var{option} as an option to the linker. If @var{option} contains
6485commas, it is split into multiple options at the commas.
6486
6487@item -u @var{symbol}
6488@opindex u
6489Pretend the symbol @var{symbol} is undefined, to force linking of
6490library modules to define it. You can use @option{-u} multiple times with
6491different symbols to force loading of additional library modules.
6492@end table
6493
6494@node Directory Options
6495@section Options for Directory Search
6496@cindex directory options
6497@cindex options, directory search
6498@cindex search path
6499
6500These options specify directories to search for header files, for
6501libraries and for parts of the compiler:
6502
6503@table @gcctabopt
6504@item -I@var{dir}
6505@opindex I
6506Add the directory @var{dir} to the head of the list of directories to be
6507searched for header files. This can be used to override a system header
6508file, substituting your own version, since these directories are
6509searched before the system header file directories. However, you should
6510not use this option to add directories that contain vendor-supplied
6511system header files (use @option{-isystem} for that). If you use more than
6512one @option{-I} option, the directories are scanned in left-to-right
6513order; the standard system directories come after.
6514
6515If a standard system include directory, or a directory specified with
6516@option{-isystem}, is also specified with @option{-I}, the @option{-I}
6517option will be ignored. The directory will still be searched but as a
6518system directory at its normal position in the system include chain.
6519This is to ensure that GCC's procedure to fix buggy system headers and
6520the ordering for the include_next directive are not inadvertently changed.
6521If you really need to change the search order for system directories,
6522use the @option{-nostdinc} and/or @option{-isystem} options.
6523
6524@item -iquote@var{dir}
6525@opindex iquote
6526Add the directory @var{dir} to the head of the list of directories to
6527be searched for header files only for the case of @samp{#include
6528"@var{file}"}; they are not searched for @samp{#include <@var{file}>},
6529otherwise just like @option{-I}.
6530
6531@item -L@var{dir}
6532@opindex L
6533Add directory @var{dir} to the list of directories to be searched
6534for @option{-l}.
6535
6536@item -B@var{prefix}
6537@opindex B
6538This option specifies where to find the executables, libraries,
6539include files, and data files of the compiler itself.
6540
6541The compiler driver program runs one or more of the subprograms
6542@file{cpp}, @file{cc1}, @file{as} and @file{ld}. It tries
6543@var{prefix} as a prefix for each program it tries to run, both with and
6544without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}).
6545
6546For each subprogram to be run, the compiler driver first tries the
6547@option{-B} prefix, if any. If that name is not found, or if @option{-B}
6548was not specified, the driver tries two standard prefixes, which are
6549@file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc/}. If neither of
6550those results in a file name that is found, the unmodified program
6551name is searched for using the directories specified in your
6552@env{PATH} environment variable.
6553
6554The compiler will check to see if the path provided by the @option{-B}
6555refers to a directory, and if necessary it will add a directory
6556separator character at the end of the path.
6557
6558@option{-B} prefixes that effectively specify directory names also apply
6559to libraries in the linker, because the compiler translates these
6560options into @option{-L} options for the linker. They also apply to
6561includes files in the preprocessor, because the compiler translates these
6562options into @option{-isystem} options for the preprocessor. In this case,
6563the compiler appends @samp{include} to the prefix.
6564
6565The run-time support file @file{libgcc.a} can also be searched for using
6566the @option{-B} prefix, if needed. If it is not found there, the two
6567standard prefixes above are tried, and that is all. The file is left
6568out of the link if it is not found by those means.
6569
6570Another way to specify a prefix much like the @option{-B} prefix is to use
6571the environment variable @env{GCC_EXEC_PREFIX}. @xref{Environment
6572Variables}.
6573
6574As a special kludge, if the path provided by @option{-B} is
6575@file{[dir/]stage@var{N}/}, where @var{N} is a number in the range 0 to
65769, then it will be replaced by @file{[dir/]include}. This is to help
6577with boot-strapping the compiler.
6578
6579@item -specs=@var{file}
6580@opindex specs
6581Process @var{file} after the compiler reads in the standard @file{specs}
6582file, in order to override the defaults that the @file{gcc} driver
6583program uses when determining what switches to pass to @file{cc1},
6584@file{cc1plus}, @file{as}, @file{ld}, etc. More than one
6585@option{-specs=@var{file}} can be specified on the command line, and they
6586are processed in order, from left to right.
6587
6588@item --sysroot=@var{dir}
6589@opindex sysroot
6590Use @var{dir} as the logical root directory for headers and libraries.
6591For example, if the compiler would normally search for headers in
6592@file{/usr/include} and libraries in @file{/usr/lib}, it will instead
6593search @file{@var{dir}/usr/include} and @file{@var{dir}/usr/lib}.
6594
6595If you use both this option and the @option{-isysroot} option, then
6596the @option{--sysroot} option will apply to libraries, but the
6597@option{-isysroot} option will apply to header files.
6598
6599The GNU linker (beginning with version 2.16) has the necessary support
6600for this option. If your linker does not support this option, the
6601header file aspect of @option{--sysroot} will still work, but the
6602library aspect will not.
6603
6604@item -I-
6605@opindex I-
6606This option has been deprecated. Please use @option{-iquote} instead for
6607@option{-I} directories before the @option{-I-} and remove the @option{-I-}.
6608Any directories you specify with @option{-I} options before the @option{-I-}
6609option are searched only for the case of @samp{#include "@var{file}"};
6610they are not searched for @samp{#include <@var{file}>}.
6611
6612If additional directories are specified with @option{-I} options after
6613the @option{-I-}, these directories are searched for all @samp{#include}
6614directives. (Ordinarily @emph{all} @option{-I} directories are used
6615this way.)
6616
6617In addition, the @option{-I-} option inhibits the use of the current
6618directory (where the current input file came from) as the first search
6619directory for @samp{#include "@var{file}"}. There is no way to
6620override this effect of @option{-I-}. With @option{-I.} you can specify
6621searching the directory which was current when the compiler was
6622invoked. That is not exactly the same as what the preprocessor does
6623by default, but it is often satisfactory.
6624
6625@option{-I-} does not inhibit the use of the standard system directories
6626for header files. Thus, @option{-I-} and @option{-nostdinc} are
6627independent.
6628@end table
6629
6630@c man end
6631
6632@node Spec Files
6633@section Specifying subprocesses and the switches to pass to them
6634@cindex Spec Files
6635
6636@command{gcc} is a driver program. It performs its job by invoking a
6637sequence of other programs to do the work of compiling, assembling and
6638linking. GCC interprets its command-line parameters and uses these to
6639deduce which programs it should invoke, and which command-line options
6640it ought to place on their command lines. This behavior is controlled
6641by @dfn{spec strings}. In most cases there is one spec string for each
6642program that GCC can invoke, but a few programs have multiple spec
6643strings to control their behavior. The spec strings built into GCC can
6644be overridden by using the @option{-specs=} command-line switch to specify
6645a spec file.
6646
6647@dfn{Spec files} are plaintext files that are used to construct spec
6648strings. They consist of a sequence of directives separated by blank
6649lines. The type of directive is determined by the first non-whitespace
6650character on the line and it can be one of the following:
6651
6652@table @code
6653@item %@var{command}
6654Issues a @var{command} to the spec file processor. The commands that can
6655appear here are:
6656
6657@table @code
6658@item %include <@var{file}>
6659@cindex %include
6660Search for @var{file} and insert its text at the current point in the
6661specs file.
6662
6663@item %include_noerr <@var{file}>
6664@cindex %include_noerr
6665Just like @samp{%include}, but do not generate an error message if the include
6666file cannot be found.
6667
6668@item %rename @var{old_name} @var{new_name}
6669@cindex %rename
6670Rename the spec string @var{old_name} to @var{new_name}.
6671
6672@end table
6673
6674@item *[@var{spec_name}]:
6675This tells the compiler to create, override or delete the named spec
6676string. All lines after this directive up to the next directive or
6677blank line are considered to be the text for the spec string. If this
6678results in an empty string then the spec will be deleted. (Or, if the
6679spec did not exist, then nothing will happened.) Otherwise, if the spec
6680does not currently exist a new spec will be created. If the spec does
6681exist then its contents will be overridden by the text of this
6682directive, unless the first character of that text is the @samp{+}
6683character, in which case the text will be appended to the spec.
6684
6685@item [@var{suffix}]:
6686Creates a new @samp{[@var{suffix}] spec} pair. All lines after this directive
6687and up to the next directive or blank line are considered to make up the
6688spec string for the indicated suffix. When the compiler encounters an
6689input file with the named suffix, it will processes the spec string in
6690order to work out how to compile that file. For example:
6691
6692@smallexample
6693.ZZ:
6694z-compile -input %i
6695@end smallexample
6696
6697This says that any input file whose name ends in @samp{.ZZ} should be
6698passed to the program @samp{z-compile}, which should be invoked with the
6699command-line switch @option{-input} and with the result of performing the
6700@samp{%i} substitution. (See below.)
6701
6702As an alternative to providing a spec string, the text that follows a
6703suffix directive can be one of the following:
6704
6705@table @code
6706@item @@@var{language}
6707This says that the suffix is an alias for a known @var{language}. This is
6708similar to using the @option{-x} command-line switch to GCC to specify a
6709language explicitly. For example:
6710
6711@smallexample
6712.ZZ:
6713@@c++
6714@end smallexample
6715
6716Says that .ZZ files are, in fact, C++ source files.
6717
6718@item #@var{name}
6719This causes an error messages saying:
6720
6721@smallexample
6722@var{name} compiler not installed on this system.
6723@end smallexample
6724@end table
6725
6726GCC already has an extensive list of suffixes built into it.
6727This directive will add an entry to the end of the list of suffixes, but
6728since the list is searched from the end backwards, it is effectively
6729possible to override earlier entries using this technique.
6730
6731@end table
6732
6733GCC has the following spec strings built into it. Spec files can
6734override these strings or create their own. Note that individual
6735targets can also add their own spec strings to this list.
6736
6737@smallexample
6738asm Options to pass to the assembler
6739asm_final Options to pass to the assembler post-processor
6740cpp Options to pass to the C preprocessor
6741cc1 Options to pass to the C compiler
6742cc1plus Options to pass to the C++ compiler
6743endfile Object files to include at the end of the link
6744link Options to pass to the linker
6745lib Libraries to include on the command line to the linker
6746libgcc Decides which GCC support library to pass to the linker
6747linker Sets the name of the linker
6748predefines Defines to be passed to the C preprocessor
6749signed_char Defines to pass to CPP to say whether @code{char} is signed
6750 by default
6751startfile Object files to include at the start of the link
6752@end smallexample
6753
6754Here is a small example of a spec file:
6755
6756@smallexample
6757%rename lib old_lib
6758
6759*lib:
6760--start-group -lgcc -lc -leval1 --end-group %(old_lib)
6761@end smallexample
6762
6763This example renames the spec called @samp{lib} to @samp{old_lib} and
6764then overrides the previous definition of @samp{lib} with a new one.
6765The new definition adds in some extra command-line options before
6766including the text of the old definition.
6767
6768@dfn{Spec strings} are a list of command-line options to be passed to their
6769corresponding program. In addition, the spec strings can contain
6770@samp{%}-prefixed sequences to substitute variable text or to
6771conditionally insert text into the command line. Using these constructs
6772it is possible to generate quite complex command lines.
6773
6774Here is a table of all defined @samp{%}-sequences for spec
6775strings. Note that spaces are not generated automatically around the
6776results of expanding these sequences. Therefore you can concatenate them
6777together or combine them with constant text in a single argument.
6778
6779@table @code
6780@item %%
6781Substitute one @samp{%} into the program name or argument.
6782
6783@item %i
6784Substitute the name of the input file being processed.
6785
6786@item %b
6787Substitute the basename of the input file being processed.
6788This is the substring up to (and not including) the last period
6789and not including the directory.
6790
6791@item %B
6792This is the same as @samp{%b}, but include the file suffix (text after
6793the last period).
6794
6795@item %d
6796Marks the argument containing or following the @samp{%d} as a
6797temporary file name, so that that file will be deleted if GCC exits
6798successfully. Unlike @samp{%g}, this contributes no text to the
6799argument.
6800
6801@item %g@var{suffix}
6802Substitute a file name that has suffix @var{suffix} and is chosen
6803once per compilation, and mark the argument in the same way as
6804@samp{%d}. To reduce exposure to denial-of-service attacks, the file
6805name is now chosen in a way that is hard to predict even when previously
6806chosen file names are known. For example, @samp{%g.s @dots{} %g.o @dots{} %g.s}
6807might turn into @samp{ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s}. @var{suffix} matches
6808the regexp @samp{[.A-Za-z]*} or the special string @samp{%O}, which is
6809treated exactly as if @samp{%O} had been preprocessed. Previously, @samp{%g}
6810was simply substituted with a file name chosen once per compilation,
6811without regard to any appended suffix (which was therefore treated
6812just like ordinary text), making such attacks more likely to succeed.
6813
6814@item %u@var{suffix}
6815Like @samp{%g}, but generates a new temporary file name even if
6816@samp{%u@var{suffix}} was already seen.
6817
6818@item %U@var{suffix}
6819Substitutes the last file name generated with @samp{%u@var{suffix}}, generating a
6820new one if there is no such last file name. In the absence of any
6821@samp{%u@var{suffix}}, this is just like @samp{%g@var{suffix}}, except they don't share
6822the same suffix @emph{space}, so @samp{%g.s @dots{} %U.s @dots{} %g.s @dots{} %U.s}
6823would involve the generation of two distinct file names, one
6824for each @samp{%g.s} and another for each @samp{%U.s}. Previously, @samp{%U} was
6825simply substituted with a file name chosen for the previous @samp{%u},
6826without regard to any appended suffix.
6827
6828@item %j@var{suffix}
6829Substitutes the name of the @code{HOST_BIT_BUCKET}, if any, and if it is
6830writable, and if save-temps is off; otherwise, substitute the name
6831of a temporary file, just like @samp{%u}. This temporary file is not
6832meant for communication between processes, but rather as a junk
6833disposal mechanism.
6834
6835@item %|@var{suffix}
6836@itemx %m@var{suffix}
6837Like @samp{%g}, except if @option{-pipe} is in effect. In that case
6838@samp{%|} substitutes a single dash and @samp{%m} substitutes nothing at
6839all. These are the two most common ways to instruct a program that it
6840should read from standard input or write to standard output. If you
6841need something more elaborate you can use an @samp{%@{pipe:@code{X}@}}
6842construct: see for example @file{f/lang-specs.h}.
6843
6844@item %.@var{SUFFIX}
6845Substitutes @var{.SUFFIX} for the suffixes of a matched switch's args
6846when it is subsequently output with @samp{%*}. @var{SUFFIX} is
6847terminated by the next space or %.
6848
6849@item %w
6850Marks the argument containing or following the @samp{%w} as the
6851designated output file of this compilation. This puts the argument
6852into the sequence of arguments that @samp{%o} will substitute later.
6853
6854@item %o
6855Substitutes the names of all the output files, with spaces
6856automatically placed around them. You should write spaces
6857around the @samp{%o} as well or the results are undefined.
6858@samp{%o} is for use in the specs for running the linker.
6859Input files whose names have no recognized suffix are not compiled
6860at all, but they are included among the output files, so they will
6861be linked.
6862
6863@item %O
6864Substitutes the suffix for object files. Note that this is
6865handled specially when it immediately follows @samp{%g, %u, or %U},
6866because of the need for those to form complete file names. The
6867handling is such that @samp{%O} is treated exactly as if it had already
6868been substituted, except that @samp{%g, %u, and %U} do not currently
6869support additional @var{suffix} characters following @samp{%O} as they would
6870following, for example, @samp{.o}.
6871
6872@item %p
6873Substitutes the standard macro predefinitions for the
6874current target machine. Use this when running @code{cpp}.
6875
6876@item %P
6877Like @samp{%p}, but puts @samp{__} before and after the name of each
6878predefined macro, except for macros that start with @samp{__} or with
6879@samp{_@var{L}}, where @var{L} is an uppercase letter. This is for ISO
6880C@.
6881
6882@item %I
6883Substitute any of @option{-iprefix} (made from @env{GCC_EXEC_PREFIX}),
6884@option{-isysroot} (made from @env{TARGET_SYSTEM_ROOT}),
6885@option{-isystem} (made from @env{COMPILER_PATH} and @option{-B} options)
6886and @option{-imultilib} as necessary.
6887
6888@item %s
6889Current argument is the name of a library or startup file of some sort.
6890Search for that file in a standard list of directories and substitute
6891the full name found.
6892
6893@item %e@var{str}
6894Print @var{str} as an error message. @var{str} is terminated by a newline.
6895Use this when inconsistent options are detected.
6896
6897@item %(@var{name})
6898Substitute the contents of spec string @var{name} at this point.
6899
6900@item %[@var{name}]
6901Like @samp{%(@dots{})} but put @samp{__} around @option{-D} arguments.
6902
6903@item %x@{@var{option}@}
6904Accumulate an option for @samp{%X}.
6905
6906@item %X
6907Output the accumulated linker options specified by @option{-Wl} or a @samp{%x}
6908spec string.
6909
6910@item %Y
6911Output the accumulated assembler options specified by @option{-Wa}.
6912
6913@item %Z
6914Output the accumulated preprocessor options specified by @option{-Wp}.
6915
6916@item %a
6917Process the @code{asm} spec. This is used to compute the
6918switches to be passed to the assembler.
6919
6920@item %A
6921Process the @code{asm_final} spec. This is a spec string for
6922passing switches to an assembler post-processor, if such a program is
6923needed.
6924
6925@item %l
6926Process the @code{link} spec. This is the spec for computing the
6927command line passed to the linker. Typically it will make use of the
6928@samp{%L %G %S %D and %E} sequences.
6929
6930@item %D
6931Dump out a @option{-L} option for each directory that GCC believes might
6932contain startup files. If the target supports multilibs then the
6933current multilib directory will be prepended to each of these paths.
6934
6935@item %L
6936Process the @code{lib} spec. This is a spec string for deciding which
6937libraries should be included on the command line to the linker.
6938
6939@item %G
6940Process the @code{libgcc} spec. This is a spec string for deciding
6941which GCC support library should be included on the command line to the linker.
6942
6943@item %S
6944Process the @code{startfile} spec. This is a spec for deciding which
6945object files should be the first ones passed to the linker. Typically
6946this might be a file named @file{crt0.o}.
6947
6948@item %E
6949Process the @code{endfile} spec. This is a spec string that specifies
6950the last object files that will be passed to the linker.
6951
6952@item %C
6953Process the @code{cpp} spec. This is used to construct the arguments
6954to be passed to the C preprocessor.
6955
6956@item %1
6957Process the @code{cc1} spec. This is used to construct the options to be
6958passed to the actual C compiler (@samp{cc1}).
6959
6960@item %2
6961Process the @code{cc1plus} spec. This is used to construct the options to be
6962passed to the actual C++ compiler (@samp{cc1plus}).
6963
6964@item %*
6965Substitute the variable part of a matched option. See below.
6966Note that each comma in the substituted string is replaced by
6967a single space.
6968
6969@item %<@code{S}
6970Remove all occurrences of @code{-S} from the command line. Note---this
6971command is position dependent. @samp{%} commands in the spec string
6972before this one will see @code{-S}, @samp{%} commands in the spec string
6973after this one will not.
6974
6975@item %:@var{function}(@var{args})
6976Call the named function @var{function}, passing it @var{args}.
6977@var{args} is first processed as a nested spec string, then split
6978into an argument vector in the usual fashion. The function returns
6979a string which is processed as if it had appeared literally as part
6980of the current spec.
6981
6982The following built-in spec functions are provided:
6983
6984@table @code
6985@item @code{if-exists}
6986The @code{if-exists} spec function takes one argument, an absolute
6987pathname to a file. If the file exists, @code{if-exists} returns the
6988pathname. Here is a small example of its usage:
6989
6990@smallexample
6991*startfile:
6992crt0%O%s %:if-exists(crti%O%s) crtbegin%O%s
6993@end smallexample
6994
6995@item @code{if-exists-else}
6996The @code{if-exists-else} spec function is similar to the @code{if-exists}
6997spec function, except that it takes two arguments. The first argument is
6998an absolute pathname to a file. If the file exists, @code{if-exists-else}
6999returns the pathname. If it does not exist, it returns the second argument.
7000This way, @code{if-exists-else} can be used to select one file or another,
7001based on the existence of the first. Here is a small example of its usage:
7002
7003@smallexample
7004*startfile:
7005crt0%O%s %:if-exists(crti%O%s) \
7006%:if-exists-else(crtbeginT%O%s crtbegin%O%s)
7007@end smallexample
7008
7009@item @code{replace-outfile}
7010The @code{replace-outfile} spec function takes two arguments. It looks for the
7011first argument in the outfiles array and replaces it with the second argument. Here
7012is a small example of its usage:
7013
7014@smallexample
7015%@{static|static-libgcc|static-libstdc++:%:replace-outfile(-lstdc++ \
7016libstdc++.a%s)@}
7017
7018@end smallexample
7019
7020@end table
7021
7022@item %@{@code{S}@}
7023Substitutes the @code{-S} switch, if that switch was given to GCC@.
7024If that switch was not specified, this substitutes nothing. Note that
7025the leading dash is omitted when specifying this option, and it is
7026automatically inserted if the substitution is performed. Thus the spec
7027string @samp{%@{foo@}} would match the command-line option @option{-foo}
7028and would output the command line option @option{-foo}.
7029
7030@item %W@{@code{S}@}
7031Like %@{@code{S}@} but mark last argument supplied within as a file to be
7032deleted on failure.
7033
7034@item %@{@code{S}*@}
7035Substitutes all the switches specified to GCC whose names start
7036with @code{-S}, but which also take an argument. This is used for
7037switches like @option{-o}, @option{-D}, @option{-I}, etc.
7038GCC considers @option{-o foo} as being
7039one switch whose names starts with @samp{o}. %@{o*@} would substitute this
7040text, including the space. Thus two arguments would be generated.
7041
7042@item %@{@code{S}*&@code{T}*@}
7043Like %@{@code{S}*@}, but preserve order of @code{S} and @code{T} options
7044(the order of @code{S} and @code{T} in the spec is not significant).
7045There can be any number of ampersand-separated variables; for each the
7046wild card is optional. Useful for CPP as @samp{%@{D*&U*&A*@}}.
7047
7048@item %@{@code{S}:@code{X}@}
7049Substitutes @code{X}, if the @samp{-S} switch was given to GCC@.
7050
7051@item %@{!@code{S}:@code{X}@}
7052Substitutes @code{X}, if the @samp{-S} switch was @emph{not} given to GCC@.
7053
7054@item %@{@code{S}*:@code{X}@}
7055Substitutes @code{X} if one or more switches whose names start with
7056@code{-S} are specified to GCC@. Normally @code{X} is substituted only
7057once, no matter how many such switches appeared. However, if @code{%*}
7058appears somewhere in @code{X}, then @code{X} will be substituted once
7059for each matching switch, with the @code{%*} replaced by the part of
7060that switch that matched the @code{*}.
7061
7062@item %@{.@code{S}:@code{X}@}
7063Substitutes @code{X}, if processing a file with suffix @code{S}.
7064
7065@item %@{!.@code{S}:@code{X}@}
7066Substitutes @code{X}, if @emph{not} processing a file with suffix @code{S}.
7067
7068@item %@{@code{S}|@code{P}:@code{X}@}
7069Substitutes @code{X} if either @code{-S} or @code{-P} was given to GCC@.
7070This may be combined with @samp{!}, @samp{.}, and @code{*} sequences as well,
7071although they have a stronger binding than the @samp{|}. If @code{%*}
7072appears in @code{X}, all of the alternatives must be starred, and only
7073the first matching alternative is substituted.
7074
7075For example, a spec string like this:
7076
7077@smallexample
7078%@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@}
7079@end smallexample
7080
7081will output the following command-line options from the following input
7082command-line options:
7083
7084@smallexample
7085fred.c -foo -baz
7086jim.d -bar -boggle
7087-d fred.c -foo -baz -boggle
7088-d jim.d -bar -baz -boggle
7089@end smallexample
7090
7091@item %@{S:X; T:Y; :D@}
7092
7093If @code{S} was given to GCC, substitutes @code{X}; else if @code{T} was
7094given to GCC, substitutes @code{Y}; else substitutes @code{D}. There can
7095be as many clauses as you need. This may be combined with @code{.},
7096@code{!}, @code{|}, and @code{*} as needed.
7097
7098
7099@end table
7100
7101The conditional text @code{X} in a %@{@code{S}:@code{X}@} or similar
7102construct may contain other nested @samp{%} constructs or spaces, or
7103even newlines. They are processed as usual, as described above.
7104Trailing white space in @code{X} is ignored. White space may also
7105appear anywhere on the left side of the colon in these constructs,
7106except between @code{.} or @code{*} and the corresponding word.
7107
7108The @option{-O}, @option{-f}, @option{-m}, and @option{-W} switches are
7109handled specifically in these constructs. If another value of
7110@option{-O} or the negated form of a @option{-f}, @option{-m}, or
7111@option{-W} switch is found later in the command line, the earlier
7112switch value is ignored, except with @{@code{S}*@} where @code{S} is
7113just one letter, which passes all matching options.
7114
7115The character @samp{|} at the beginning of the predicate text is used to
7116indicate that a command should be piped to the following command, but
7117only if @option{-pipe} is specified.
7118
7119It is built into GCC which switches take arguments and which do not.
7120(You might think it would be useful to generalize this to allow each
7121compiler's spec to say which switches take arguments. But this cannot
7122be done in a consistent fashion. GCC cannot even decide which input
7123files have been specified without knowing which switches take arguments,
7124and it must know which input files to compile in order to tell which
7125compilers to run).
7126
7127GCC also knows implicitly that arguments starting in @option{-l} are to be
7128treated as compiler output files, and passed to the linker in their
7129proper position among the other output files.
7130
7131@c man begin OPTIONS
7132
7133@node Target Options
7134@section Specifying Target Machine and Compiler Version
7135@cindex target options
7136@cindex cross compiling
7137@cindex specifying machine version
7138@cindex specifying compiler version and target machine
7139@cindex compiler version, specifying
7140@cindex target machine, specifying
7141
7142The usual way to run GCC is to run the executable called @file{gcc}, or
7143@file{<machine>-gcc} when cross-compiling, or
7144@file{<machine>-gcc-<version>} to run a version other than the one that
7145was installed last. Sometimes this is inconvenient, so GCC provides
7146options that will switch to another cross-compiler or version.
7147
7148@table @gcctabopt
7149@item -b @var{machine}
7150@opindex b
7151The argument @var{machine} specifies the target machine for compilation.
7152
7153The value to use for @var{machine} is the same as was specified as the
7154machine type when configuring GCC as a cross-compiler. For
7155example, if a cross-compiler was configured with @samp{configure
7156arm-elf}, meaning to compile for an arm processor with elf binaries,
7157then you would specify @option{-b arm-elf} to run that cross compiler.
7158Because there are other options beginning with @option{-b}, the
7159configuration must contain a hyphen.
7160
7161@item -V @var{version}
7162@opindex V
7163The argument @var{version} specifies which version of GCC to run.
7164This is useful when multiple versions are installed. For example,
7165@var{version} might be @samp{4.0}, meaning to run GCC version 4.0.
7166@end table
7167
7168The @option{-V} and @option{-b} options work by running the
7169@file{<machine>-gcc-<version>} executable, so there's no real reason to
7170use them if you can just run that directly.
7171
7172@node Submodel Options
7173@section Hardware Models and Configurations
7174@cindex submodel options
7175@cindex specifying hardware config
7176@cindex hardware models and configurations, specifying
7177@cindex machine dependent options
7178
7179Earlier we discussed the standard option @option{-b} which chooses among
7180different installed compilers for completely different target
7181machines, such as VAX vs.@: 68000 vs.@: 80386.
7182
7183In addition, each of these target machine types can have its own
7184special options, starting with @samp{-m}, to choose among various
7185hardware models or configurations---for example, 68010 vs 68020,
7186floating coprocessor or none. A single installed version of the
7187compiler can compile for any model or configuration, according to the
7188options specified.
7189
7190Some configurations of the compiler also support additional special
7191options, usually for compatibility with other compilers on the same
7192platform.
7193
7194@c This list is ordered alphanumerically by subsection name.
7195@c It should be the same order and spelling as these options are listed
7196@c in Machine Dependent Options
7197
7198@menu
7199* ARC Options::
7200* ARM Options::
7201* AVR Options::
7202* Blackfin Options::
7203* CRIS Options::
7204* CRX Options::
7205* Darwin Options::
7206* DEC Alpha Options::
7207* DEC Alpha/VMS Options::
7208* FRV Options::
7209* GNU/Linux Options::
7210* H8/300 Options::
7211* HPPA Options::
7212* i386 and x86-64 Options::
7213* IA-64 Options::
7214* M32C Options::
7215* M32R/D Options::
7216* M680x0 Options::
7217* M68hc1x Options::
7218* MCore Options::
7219* MIPS Options::
7220* MMIX Options::
7221* MN10300 Options::
7222* MT Options::
7223* PDP-11 Options::
7224* PowerPC Options::
7225* RS/6000 and PowerPC Options::
7226* S/390 and zSeries Options::
7227* Score Options::
7228* SH Options::
7229* SPARC Options::
7230* System V Options::
7231* TMS320C3x/C4x Options::
7232* V850 Options::
7233* VAX Options::
7234* x86-64 Options::
7235* Xstormy16 Options::
7236* Xtensa Options::
7237* zSeries Options::
7238@end menu
7239
7240@node ARC Options
7241@subsection ARC Options
7242@cindex ARC Options
7243
7244These options are defined for ARC implementations:
7245
7246@table @gcctabopt
7247@item -EL
7248@opindex EL
7249Compile code for little endian mode. This is the default.
7250
7251@item -EB
7252@opindex EB
7253Compile code for big endian mode.
7254
7255@item -mmangle-cpu
7256@opindex mmangle-cpu
7257Prepend the name of the cpu to all public symbol names.
7258In multiple-processor systems, there are many ARC variants with different
7259instruction and register set characteristics. This flag prevents code
7260compiled for one cpu to be linked with code compiled for another.
7261No facility exists for handling variants that are ``almost identical''.
7262This is an all or nothing option.
7263
7264@item -mcpu=@var{cpu}
7265@opindex mcpu
7266Compile code for ARC variant @var{cpu}.
7267Which variants are supported depend on the configuration.
7268All variants support @option{-mcpu=base}, this is the default.
7269
7270@item -mtext=@var{text-section}
7271@itemx -mdata=@var{data-section}
7272@itemx -mrodata=@var{readonly-data-section}
7273@opindex mtext
7274@opindex mdata
7275@opindex mrodata
7276Put functions, data, and readonly data in @var{text-section},
7277@var{data-section}, and @var{readonly-data-section} respectively
7278by default. This can be overridden with the @code{section} attribute.
7279@xref{Variable Attributes}.
7280
7281@end table
7282
7283@node ARM Options
7284@subsection ARM Options
7285@cindex ARM options
7286
7287These @samp{-m} options are defined for Advanced RISC Machines (ARM)
7288architectures:
7289
7290@table @gcctabopt
7291@item -mabi=@var{name}
7292@opindex mabi
7293Generate code for the specified ABI@. Permissible values are: @samp{apcs-gnu},
7294@samp{atpcs}, @samp{aapcs}, @samp{aapcs-linux} and @samp{iwmmxt}.
7295
7296@item -mapcs-frame
7297@opindex mapcs-frame
7298Generate a stack frame that is compliant with the ARM Procedure Call
7299Standard for all functions, even if this is not strictly necessary for
7300correct execution of the code. Specifying @option{-fomit-frame-pointer}
7301with this option will cause the stack frames not to be generated for
7302leaf functions. The default is @option{-mno-apcs-frame}.
7303
7304@item -mapcs
7305@opindex mapcs
7306This is a synonym for @option{-mapcs-frame}.
7307
7308@ignore
7309@c not currently implemented
7310@item -mapcs-stack-check
7311@opindex mapcs-stack-check
7312Generate code to check the amount of stack space available upon entry to
7313every function (that actually uses some stack space). If there is
7314insufficient space available then either the function
7315@samp{__rt_stkovf_split_small} or @samp{__rt_stkovf_split_big} will be
7316called, depending upon the amount of stack space required. The run time
7317system is required to provide these functions. The default is
7318@option{-mno-apcs-stack-check}, since this produces smaller code.
7319
7320@c not currently implemented
7321@item -mapcs-float
7322@opindex mapcs-float
7323Pass floating point arguments using the float point registers. This is
7324one of the variants of the APCS@. This option is recommended if the
7325target hardware has a floating point unit or if a lot of floating point
7326arithmetic is going to be performed by the code. The default is
7327@option{-mno-apcs-float}, since integer only code is slightly increased in
7328size if @option{-mapcs-float} is used.
7329
7330@c not currently implemented
7331@item -mapcs-reentrant
7332@opindex mapcs-reentrant
7333Generate reentrant, position independent code. The default is
7334@option{-mno-apcs-reentrant}.
7335@end ignore
7336
7337@item -mthumb-interwork
7338@opindex mthumb-interwork
7339Generate code which supports calling between the ARM and Thumb
7340instruction sets. Without this option the two instruction sets cannot
7341be reliably used inside one program. The default is
7342@option{-mno-thumb-interwork}, since slightly larger code is generated
7343when @option{-mthumb-interwork} is specified.
7344
7345@item -mno-sched-prolog
7346@opindex mno-sched-prolog
7347Prevent the reordering of instructions in the function prolog, or the
7348merging of those instruction with the instructions in the function's
7349body. This means that all functions will start with a recognizable set
7350of instructions (or in fact one of a choice from a small set of
7351different function prologues), and this information can be used to
7352locate the start if functions inside an executable piece of code. The
7353default is @option{-msched-prolog}.
7354
7355@item -mhard-float
7356@opindex mhard-float
7357Generate output containing floating point instructions. This is the
7358default.
7359
7360@item -msoft-float
7361@opindex msoft-float
7362Generate output containing library calls for floating point.
7363@strong{Warning:} the requisite libraries are not available for all ARM
7364targets. Normally the facilities of the machine's usual C compiler are
7365used, but this cannot be done directly in cross-compilation. You must make
7366your own arrangements to provide suitable library functions for
7367cross-compilation.
7368
7369@option{-msoft-float} changes the calling convention in the output file;
7370therefore, it is only useful if you compile @emph{all} of a program with
7371this option. In particular, you need to compile @file{libgcc.a}, the
7372library that comes with GCC, with @option{-msoft-float} in order for
7373this to work.
7374
7375@item -mfloat-abi=@var{name}
7376@opindex mfloat-abi
7377Specifies which ABI to use for floating point values. Permissible values
7378are: @samp{soft}, @samp{softfp} and @samp{hard}.
7379
7380@samp{soft} and @samp{hard} are equivalent to @option{-msoft-float}
7381and @option{-mhard-float} respectively. @samp{softfp} allows the generation
7382of floating point instructions, but still uses the soft-float calling
7383conventions.
7384
7385@item -mlittle-endian
7386@opindex mlittle-endian
7387Generate code for a processor running in little-endian mode. This is
7388the default for all standard configurations.
7389
7390@item -mbig-endian
7391@opindex mbig-endian
7392Generate code for a processor running in big-endian mode; the default is
7393to compile code for a little-endian processor.
7394
7395@item -mwords-little-endian
7396@opindex mwords-little-endian
7397This option only applies when generating code for big-endian processors.
7398Generate code for a little-endian word order but a big-endian byte
7399order. That is, a byte order of the form @samp{32107654}. Note: this
7400option should only be used if you require compatibility with code for
7401big-endian ARM processors generated by versions of the compiler prior to
74022.8.
7403
7404@item -mcpu=@var{name}
7405@opindex mcpu
7406This specifies the name of the target ARM processor. GCC uses this name
7407to determine what kind of instructions it can emit when generating
7408assembly code. Permissible names are: @samp{arm2}, @samp{arm250},
7409@samp{arm3}, @samp{arm6}, @samp{arm60}, @samp{arm600}, @samp{arm610},
7410@samp{arm620}, @samp{arm7}, @samp{arm7m}, @samp{arm7d}, @samp{arm7dm},
7411@samp{arm7di}, @samp{arm7dmi}, @samp{arm70}, @samp{arm700},
7412@samp{arm700i}, @samp{arm710}, @samp{arm710c}, @samp{arm7100},
7413@samp{arm7500}, @samp{arm7500fe}, @samp{arm7tdmi}, @samp{arm7tdmi-s},
7414@samp{arm8}, @samp{strongarm}, @samp{strongarm110}, @samp{strongarm1100},
7415@samp{arm8}, @samp{arm810}, @samp{arm9}, @samp{arm9e}, @samp{arm920},
7416@samp{arm920t}, @samp{arm922t}, @samp{arm946e-s}, @samp{arm966e-s},
7417@samp{arm968e-s}, @samp{arm926ej-s}, @samp{arm940t}, @samp{arm9tdmi},
7418@samp{arm10tdmi}, @samp{arm1020t}, @samp{arm1026ej-s},
7419@samp{arm10e}, @samp{arm1020e}, @samp{arm1022e},
7420@samp{arm1136j-s}, @samp{arm1136jf-s}, @samp{mpcore}, @samp{mpcorenovfp},
7421@samp{arm1176jz-s}, @samp{arm1176jzf-s}, @samp{xscale}, @samp{iwmmxt},
7422@samp{ep9312}.
7423
7424@itemx -mtune=@var{name}
7425@opindex mtune
7426This option is very similar to the @option{-mcpu=} option, except that
7427instead of specifying the actual target processor type, and hence
7428restricting which instructions can be used, it specifies that GCC should
7429tune the performance of the code as if the target were of the type
7430specified in this option, but still choosing the instructions that it
7431will generate based on the cpu specified by a @option{-mcpu=} option.
7432For some ARM implementations better performance can be obtained by using
7433this option.
7434
7435@item -march=@var{name}
7436@opindex march
7437This specifies the name of the target ARM architecture. GCC uses this
7438name to determine what kind of instructions it can emit when generating
7439assembly code. This option can be used in conjunction with or instead
7440of the @option{-mcpu=} option. Permissible names are: @samp{armv2},
7441@samp{armv2a}, @samp{armv3}, @samp{armv3m}, @samp{armv4}, @samp{armv4t},
7442@samp{armv5}, @samp{armv5t}, @samp{armv5te}, @samp{armv6}, @samp{armv6j},
7443@samp{iwmmxt}, @samp{ep9312}.
7444
7445@item -mfpu=@var{name}
7446@itemx -mfpe=@var{number}
7447@itemx -mfp=@var{number}
7448@opindex mfpu
7449@opindex mfpe
7450@opindex mfp
7451This specifies what floating point hardware (or hardware emulation) is
7452available on the target. Permissible names are: @samp{fpa}, @samp{fpe2},
7453@samp{fpe3}, @samp{maverick}, @samp{vfp}. @option{-mfp} and @option{-mfpe}
7454are synonyms for @option{-mfpu}=@samp{fpe}@var{number}, for compatibility
7455with older versions of GCC@.
7456
7457If @option{-msoft-float} is specified this specifies the format of
7458floating point values.
7459
7460@item -mstructure-size-boundary=@var{n}
7461@opindex mstructure-size-boundary
7462The size of all structures and unions will be rounded up to a multiple
7463of the number of bits set by this option. Permissible values are 8, 32
7464and 64. The default value varies for different toolchains. For the COFF
7465targeted toolchain the default value is 8. A value of 64 is only allowed
7466if the underlying ABI supports it.
7467
7468Specifying the larger number can produce faster, more efficient code, but
7469can also increase the size of the program. Different values are potentially
7470incompatible. Code compiled with one value cannot necessarily expect to
7471work with code or libraries compiled with another value, if they exchange
7472information using structures or unions.
7473
7474@item -mabort-on-noreturn
7475@opindex mabort-on-noreturn
7476Generate a call to the function @code{abort} at the end of a
7477@code{noreturn} function. It will be executed if the function tries to
7478return.
7479
7480@item -mlong-calls
7481@itemx -mno-long-calls
7482@opindex mlong-calls
7483@opindex mno-long-calls
7484Tells the compiler to perform function calls by first loading the
7485address of the function into a register and then performing a subroutine
7486call on this register. This switch is needed if the target function
7487will lie outside of the 64 megabyte addressing range of the offset based
7488version of subroutine call instruction.
7489
7490Even if this switch is enabled, not all function calls will be turned
7491into long calls. The heuristic is that static functions, functions
7492which have the @samp{short-call} attribute, functions that are inside
7493the scope of a @samp{#pragma no_long_calls} directive and functions whose
7494definitions have already been compiled within the current compilation
7495unit, will not be turned into long calls. The exception to this rule is
7496that weak function definitions, functions with the @samp{long-call}
7497attribute or the @samp{section} attribute, and functions that are within
7498the scope of a @samp{#pragma long_calls} directive, will always be
7499turned into long calls.
7500
7501This feature is not enabled by default. Specifying
7502@option{-mno-long-calls} will restore the default behavior, as will
7503placing the function calls within the scope of a @samp{#pragma
7504long_calls_off} directive. Note these switches have no effect on how
7505the compiler generates code to handle function calls via function
7506pointers.
7507
7508@item -mnop-fun-dllimport
7509@opindex mnop-fun-dllimport
7510Disable support for the @code{dllimport} attribute.
7511
7512@item -msingle-pic-base
7513@opindex msingle-pic-base
7514Treat the register used for PIC addressing as read-only, rather than
7515loading it in the prologue for each function. The run-time system is
7516responsible for initializing this register with an appropriate value
7517before execution begins.
7518
7519@item -mpic-register=@var{reg}
7520@opindex mpic-register
7521Specify the register to be used for PIC addressing. The default is R10
7522unless stack-checking is enabled, when R9 is used.
7523
7524@item -mcirrus-fix-invalid-insns
7525@opindex mcirrus-fix-invalid-insns
7526@opindex mno-cirrus-fix-invalid-insns
7527Insert NOPs into the instruction stream to in order to work around
7528problems with invalid Maverick instruction combinations. This option
7529is only valid if the @option{-mcpu=ep9312} option has been used to
7530enable generation of instructions for the Cirrus Maverick floating
7531point co-processor. This option is not enabled by default, since the
7532problem is only present in older Maverick implementations. The default
7533can be re-enabled by use of the @option{-mno-cirrus-fix-invalid-insns}
7534switch.
7535
7536@item -mpoke-function-name
7537@opindex mpoke-function-name
7538Write the name of each function into the text section, directly
7539preceding the function prologue. The generated code is similar to this:
7540
7541@smallexample
7542 t0
7543 .ascii "arm_poke_function_name", 0
7544 .align
7545 t1
7546 .word 0xff000000 + (t1 - t0)
7547 arm_poke_function_name
7548 mov ip, sp
7549 stmfd sp!, @{fp, ip, lr, pc@}
7550 sub fp, ip, #4
7551@end smallexample
7552
7553When performing a stack backtrace, code can inspect the value of
7554@code{pc} stored at @code{fp + 0}. If the trace function then looks at
7555location @code{pc - 12} and the top 8 bits are set, then we know that
7556there is a function name embedded immediately preceding this location
7557and has length @code{((pc[-3]) & 0xff000000)}.
7558
7559@item -mthumb
7560@opindex mthumb
7561Generate code for the 16-bit Thumb instruction set. The default is to
7562use the 32-bit ARM instruction set.
7563
7564@item -mtpcs-frame
7565@opindex mtpcs-frame
7566Generate a stack frame that is compliant with the Thumb Procedure Call
7567Standard for all non-leaf functions. (A leaf function is one that does
7568not call any other functions.) The default is @option{-mno-tpcs-frame}.
7569
7570@item -mtpcs-leaf-frame
7571@opindex mtpcs-leaf-frame
7572Generate a stack frame that is compliant with the Thumb Procedure Call
7573Standard for all leaf functions. (A leaf function is one that does
7574not call any other functions.) The default is @option{-mno-apcs-leaf-frame}.
7575
7576@item -mcallee-super-interworking
7577@opindex mcallee-super-interworking
7578Gives all externally visible functions in the file being compiled an ARM
7579instruction set header which switches to Thumb mode before executing the
7580rest of the function. This allows these functions to be called from
7581non-interworking code.
7582
7583@item -mcaller-super-interworking
7584@opindex mcaller-super-interworking
7585Allows calls via function pointers (including virtual functions) to
7586execute correctly regardless of whether the target code has been
7587compiled for interworking or not. There is a small overhead in the cost
7588of executing a function pointer if this option is enabled.
7589
7590@item -mtp=@var{name}
7591@opindex mtp
7592Specify the access model for the thread local storage pointer. The valid
7593models are @option{soft}, which generates calls to @code{__aeabi_read_tp},
7594@option{cp15}, which fetches the thread pointer from @code{cp15} directly
7595(supported in the arm6k architecture), and @option{auto}, which uses the
7596best available method for the selected processor. The default setting is
7597@option{auto}.
7598
7599@end table
7600
7601@node AVR Options
7602@subsection AVR Options
7603@cindex AVR Options
7604
7605These options are defined for AVR implementations:
7606
7607@table @gcctabopt
7608@item -mmcu=@var{mcu}
7609@opindex mmcu
7610Specify ATMEL AVR instruction set or MCU type.
7611
7612Instruction set avr1 is for the minimal AVR core, not supported by the C
7613compiler, only for assembler programs (MCU types: at90s1200, attiny10,
7614attiny11, attiny12, attiny15, attiny28).
7615
7616Instruction set avr2 (default) is for the classic AVR core with up to
76178K program memory space (MCU types: at90s2313, at90s2323, attiny22,
7618at90s2333, at90s2343, at90s4414, at90s4433, at90s4434, at90s8515,
7619at90c8534, at90s8535).
7620
7621Instruction set avr3 is for the classic AVR core with up to 128K program
7622memory space (MCU types: atmega103, atmega603, at43usb320, at76c711).
7623
7624Instruction set avr4 is for the enhanced AVR core with up to 8K program
7625memory space (MCU types: atmega8, atmega83, atmega85).
7626
7627Instruction set avr5 is for the enhanced AVR core with up to 128K program
7628memory space (MCU types: atmega16, atmega161, atmega163, atmega32, atmega323,
7629atmega64, atmega128, at43usb355, at94k).
7630
7631@item -msize
7632@opindex msize
7633Output instruction sizes to the asm file.
7634
7635@item -minit-stack=@var{N}
7636@opindex minit-stack
7637Specify the initial stack address, which may be a symbol or numeric value,
7638@samp{__stack} is the default.
7639
7640@item -mno-interrupts
7641@opindex mno-interrupts
7642Generated code is not compatible with hardware interrupts.
7643Code size will be smaller.
7644
7645@item -mcall-prologues
7646@opindex mcall-prologues
7647Functions prologues/epilogues expanded as call to appropriate
7648subroutines. Code size will be smaller.
7649
7650@item -mno-tablejump
7651@opindex mno-tablejump
7652Do not generate tablejump insns which sometimes increase code size.
7653
7654@item -mtiny-stack
7655@opindex mtiny-stack
7656Change only the low 8 bits of the stack pointer.
7657
7658@item -mint8
7659@opindex mint8
7660Assume int to be 8 bit integer. This affects the sizes of all types: A
7661char will be 1 byte, an int will be 1 byte, an long will be 2 bytes
7662and long long will be 4 bytes. Please note that this option does not
7663comply to the C standards, but it will provide you with smaller code
7664size.
7665@end table
7666
7667@node Blackfin Options
7668@subsection Blackfin Options
7669@cindex Blackfin Options
7670
7671@table @gcctabopt
7672@item -momit-leaf-frame-pointer
7673@opindex momit-leaf-frame-pointer
7674Don't keep the frame pointer in a register for leaf functions. This
7675avoids the instructions to save, set up and restore frame pointers and
7676makes an extra register available in leaf functions. The option
7677@option{-fomit-frame-pointer} removes the frame pointer for all functions
7678which might make debugging harder.
7679
7680@item -mspecld-anomaly
7681@opindex mspecld-anomaly
7682When enabled, the compiler will ensure that the generated code does not
7683contain speculative loads after jump instructions. This option is enabled
7684by default.
7685
7686@item -mno-specld-anomaly
7687@opindex mno-specld-anomaly
7688Don't generate extra code to prevent speculative loads from occurring.
7689
7690@item -mcsync-anomaly
7691@opindex mcsync-anomaly
7692When enabled, the compiler will ensure that the generated code does not
7693contain CSYNC or SSYNC instructions too soon after conditional branches.
7694This option is enabled by default.
7695
7696@item -mno-csync-anomaly
7697@opindex mno-csync-anomaly
7698Don't generate extra code to prevent CSYNC or SSYNC instructions from
7699occurring too soon after a conditional branch.
7700
7701@item -mlow-64k
7702@opindex mlow-64k
7703When enabled, the compiler is free to take advantage of the knowledge that
7704the entire program fits into the low 64k of memory.
7705
7706@item -mno-low-64k
7707@opindex mno-low-64k
7708Assume that the program is arbitrarily large. This is the default.
7709
7710@item -mid-shared-library
7711@opindex mid-shared-library
7712Generate code that supports shared libraries via the library ID method.
7713This allows for execute in place and shared libraries in an environment
7714without virtual memory management. This option implies @option{-fPIC}.
7715
7716@item -mno-id-shared-library
7717@opindex mno-id-shared-library
7718Generate code that doesn't assume ID based shared libraries are being used.
7719This is the default.
7720
7721@item -mshared-library-id=n
7722@opindex mshared-library-id
7723Specified the identification number of the ID based shared library being
7724compiled. Specifying a value of 0 will generate more compact code, specifying
7725other values will force the allocation of that number to the current
7726library but is no more space or time efficient than omitting this option.
7727
7728@item -mlong-calls
7729@itemx -mno-long-calls
7730@opindex mlong-calls
7731@opindex mno-long-calls
7732Tells the compiler to perform function calls by first loading the
7733address of the function into a register and then performing a subroutine
7734call on this register. This switch is needed if the target function
7735will lie outside of the 24 bit addressing range of the offset based
7736version of subroutine call instruction.
7737
7738This feature is not enabled by default. Specifying
7739@option{-mno-long-calls} will restore the default behavior. Note these
7740switches have no effect on how the compiler generates code to handle
7741function calls via function pointers.
7742@end table
7743
7744@node CRIS Options
7745@subsection CRIS Options
7746@cindex CRIS Options
7747
7748These options are defined specifically for the CRIS ports.
7749
7750@table @gcctabopt
7751@item -march=@var{architecture-type}
7752@itemx -mcpu=@var{architecture-type}
7753@opindex march
7754@opindex mcpu
7755Generate code for the specified architecture. The choices for
7756@var{architecture-type} are @samp{v3}, @samp{v8} and @samp{v10} for
7757respectively ETRAX@w{ }4, ETRAX@w{ }100, and ETRAX@w{ }100@w{ }LX@.
7758Default is @samp{v0} except for cris-axis-linux-gnu, where the default is
7759@samp{v10}.
7760
7761@item -mtune=@var{architecture-type}
7762@opindex mtune
7763Tune to @var{architecture-type} everything applicable about the generated
7764code, except for the ABI and the set of available instructions. The
7765choices for @var{architecture-type} are the same as for
7766@option{-march=@var{architecture-type}}.
7767
7768@item -mmax-stack-frame=@var{n}
7769@opindex mmax-stack-frame
7770Warn when the stack frame of a function exceeds @var{n} bytes.
7771
7772@item -melinux-stacksize=@var{n}
7773@opindex melinux-stacksize
7774Only available with the @samp{cris-axis-aout} target. Arranges for
7775indications in the program to the kernel loader that the stack of the
7776program should be set to @var{n} bytes.
7777
7778@item -metrax4
7779@itemx -metrax100
7780@opindex metrax4
7781@opindex metrax100
7782The options @option{-metrax4} and @option{-metrax100} are synonyms for
7783@option{-march=v3} and @option{-march=v8} respectively.
7784
7785@item -mmul-bug-workaround
7786@itemx -mno-mul-bug-workaround
7787@opindex mmul-bug-workaround
7788@opindex mno-mul-bug-workaround
7789Work around a bug in the @code{muls} and @code{mulu} instructions for CPU
7790models where it applies. This option is active by default.
7791
7792@item -mpdebug
7793@opindex mpdebug
7794Enable CRIS-specific verbose debug-related information in the assembly
7795code. This option also has the effect to turn off the @samp{#NO_APP}
7796formatted-code indicator to the assembler at the beginning of the
7797assembly file.
7798
7799@item -mcc-init
7800@opindex mcc-init
7801Do not use condition-code results from previous instruction; always emit
7802compare and test instructions before use of condition codes.
7803
7804@item -mno-side-effects
7805@opindex mno-side-effects
7806Do not emit instructions with side-effects in addressing modes other than
7807post-increment.
7808
7809@item -mstack-align
7810@itemx -mno-stack-align
7811@itemx -mdata-align
7812@itemx -mno-data-align
7813@itemx -mconst-align
7814@itemx -mno-const-align
7815@opindex mstack-align
7816@opindex mno-stack-align
7817@opindex mdata-align
7818@opindex mno-data-align
7819@opindex mconst-align
7820@opindex mno-const-align
7821These options (no-options) arranges (eliminate arrangements) for the
7822stack-frame, individual data and constants to be aligned for the maximum
7823single data access size for the chosen CPU model. The default is to
7824arrange for 32-bit alignment. ABI details such as structure layout are
7825not affected by these options.
7826
7827@item -m32-bit
7828@itemx -m16-bit
7829@itemx -m8-bit
7830@opindex m32-bit
7831@opindex m16-bit
7832@opindex m8-bit
7833Similar to the stack- data- and const-align options above, these options
7834arrange for stack-frame, writable data and constants to all be 32-bit,
783516-bit or 8-bit aligned. The default is 32-bit alignment.
7836
7837@item -mno-prologue-epilogue
7838@itemx -mprologue-epilogue
7839@opindex mno-prologue-epilogue
7840@opindex mprologue-epilogue
7841With @option{-mno-prologue-epilogue}, the normal function prologue and
7842epilogue that sets up the stack-frame are omitted and no return
7843instructions or return sequences are generated in the code. Use this
7844option only together with visual inspection of the compiled code: no
7845warnings or errors are generated when call-saved registers must be saved,
7846or storage for local variable needs to be allocated.
7847
7848@item -mno-gotplt
7849@itemx -mgotplt
7850@opindex mno-gotplt
7851@opindex mgotplt
7852With @option{-fpic} and @option{-fPIC}, don't generate (do generate)
7853instruction sequences that load addresses for functions from the PLT part
7854of the GOT rather than (traditional on other architectures) calls to the
7855PLT@. The default is @option{-mgotplt}.
7856
7857@item -maout
7858@opindex maout
7859Legacy no-op option only recognized with the cris-axis-aout target.
7860
7861@item -melf
7862@opindex melf
7863Legacy no-op option only recognized with the cris-axis-elf and
7864cris-axis-linux-gnu targets.
7865
7866@item -melinux
7867@opindex melinux
7868Only recognized with the cris-axis-aout target, where it selects a
7869GNU/linux-like multilib, include files and instruction set for
7870@option{-march=v8}.
7871
7872@item -mlinux
7873@opindex mlinux
7874Legacy no-op option only recognized with the cris-axis-linux-gnu target.
7875
7876@item -sim
7877@opindex sim
7878This option, recognized for the cris-axis-aout and cris-axis-elf arranges
7879to link with input-output functions from a simulator library. Code,
7880initialized data and zero-initialized data are allocated consecutively.
7881
7882@item -sim2
7883@opindex sim2
7884Like @option{-sim}, but pass linker options to locate initialized data at
78850x40000000 and zero-initialized data at 0x80000000.
7886@end table
7887
7888@node CRX Options
7889@subsection CRX Options
7890@cindex CRX Options
7891
7892These options are defined specifically for the CRX ports.
7893
7894@table @gcctabopt
7895
7896@item -mmac
7897@opindex mmac
7898Enable the use of multiply-accumulate instructions. Disabled by default.
7899
7900@item -mpush-args
7901@opindex mpush-args
7902Push instructions will be used to pass outgoing arguments when functions
7903are called. Enabled by default.
7904@end table
7905
7906@node Darwin Options
7907@subsection Darwin Options
7908@cindex Darwin options
7909
7910These options are defined for all architectures running the Darwin operating
7911system.
7912
7913FSF GCC on Darwin does not create ``fat'' object files; it will create
7914an object file for the single architecture that it was built to
7915target. Apple's GCC on Darwin does create ``fat'' files if multiple
7916@option{-arch} options are used; it does so by running the compiler or
7917linker multiple times and joining the results together with
7918@file{lipo}.
7919
7920The subtype of the file created (like @samp{ppc7400} or @samp{ppc970} or
7921@samp{i686}) is determined by the flags that specify the ISA
7922that GCC is targetting, like @option{-mcpu} or @option{-march}. The
7923@option{-force_cpusubtype_ALL} option can be used to override this.
7924
7925The Darwin tools vary in their behavior when presented with an ISA
7926mismatch. The assembler, @file{as}, will only permit instructions to
7927be used that are valid for the subtype of the file it is generating,
7928so you cannot put 64-bit instructions in an @samp{ppc750} object file.
7929The linker for shared libraries, @file{/usr/bin/libtool}, will fail
7930and print an error if asked to create a shared library with a less
7931restrictive subtype than its input files (for instance, trying to put
7932a @samp{ppc970} object file in a @samp{ppc7400} library). The linker
7933for executables, @file{ld}, will quietly give the executable the most
7934restrictive subtype of any of its input files.
7935
7936@table @gcctabopt
7937@item -F@var{dir}
7938@opindex F
7939Add the framework directory @var{dir} to the head of the list of
7940directories to be searched for header files. These directories are
7941interleaved with those specified by @option{-I} options and are
7942scanned in a left-to-right order.
7943
7944A framework directory is a directory with frameworks in it. A
7945framework is a directory with a @samp{"Headers"} and/or
7946@samp{"PrivateHeaders"} directory contained directly in it that ends
7947in @samp{".framework"}. The name of a framework is the name of this
7948directory excluding the @samp{".framework"}. Headers associated with
7949the framework are found in one of those two directories, with
7950@samp{"Headers"} being searched first. A subframework is a framework
7951directory that is in a framework's @samp{"Frameworks"} directory.
7952Includes of subframework headers can only appear in a header of a
7953framework that contains the subframework, or in a sibling subframework
7954header. Two subframeworks are siblings if they occur in the same
7955framework. A subframework should not have the same name as a
7956framework, a warning will be issued if this is violated. Currently a
7957subframework cannot have subframeworks, in the future, the mechanism
7958may be extended to support this. The standard frameworks can be found
7959in @samp{"/System/Library/Frameworks"} and
7960@samp{"/Library/Frameworks"}. An example include looks like
7961@code{#include <Framework/header.h>}, where @samp{Framework} denotes
7962the name of the framework and header.h is found in the
7963@samp{"PrivateHeaders"} or @samp{"Headers"} directory.
7964
7965@item -gused
7966@opindex gused
7967Emit debugging information for symbols that are used. For STABS
7968debugging format, this enables @option{-feliminate-unused-debug-symbols}.
7969This is by default ON@.
7970
7971@item -gfull
7972@opindex gfull
7973Emit debugging information for all symbols and types.
7974
7975@item -mmacosx-version-min=@var{version}
7976The earliest version of MacOS X that this executable will run on
7977is @var{version}. Typical values of @var{version} include @code{10.1},
7978@code{10.2}, and @code{10.3.9}.
7979
7980The default for this option is to make choices that seem to be most
7981useful.
7982
7983@item -mkernel
7984@opindex mkernel
7985Enable kernel development mode. The @option{-mkernel} option sets
7986@option{-static}, @option{-fno-common}, @option{-fno-cxa-atexit},
7987@option{-fno-exceptions}, @option{-fno-non-call-exceptions},
7988@option{-fapple-kext}, @option{-fno-weak} and @option{-fno-rtti} where
7989applicable. This mode also sets @option{-mno-altivec},
7990@option{-msoft-float}, @option{-fno-builtin} and
7991@option{-mlong-branch} for PowerPC targets.
7992
7993@item -mone-byte-bool
7994@opindex mone-byte-bool
7995Override the defaults for @samp{bool} so that @samp{sizeof(bool)==1}.
7996By default @samp{sizeof(bool)} is @samp{4} when compiling for
7997Darwin/PowerPC and @samp{1} when compiling for Darwin/x86, so this
7998option has no effect on x86.
7999
8000@strong{Warning:} The @option{-mone-byte-bool} switch causes GCC
8001to generate code that is not binary compatible with code generated
8002without that switch. Using this switch may require recompiling all
8003other modules in a program, including system libraries. Use this
8004switch to conform to a non-default data model.
8005
8006@item -mfix-and-continue
8007@itemx -ffix-and-continue
8008@itemx -findirect-data
8009@opindex mfix-and-continue
8010@opindex ffix-and-continue
8011@opindex findirect-data
8012Generate code suitable for fast turn around development. Needed to
8013enable gdb to dynamically load @code{.o} files into already running
8014programs. @option{-findirect-data} and @option{-ffix-and-continue}
8015are provided for backwards compatibility.
8016
8017@item -all_load
8018@opindex all_load
8019Loads all members of static archive libraries.
8020See man ld(1) for more information.
8021
8022@item -arch_errors_fatal
8023@opindex arch_errors_fatal
8024Cause the errors having to do with files that have the wrong architecture
8025to be fatal.
8026
8027@item -bind_at_load
8028@opindex bind_at_load
8029Causes the output file to be marked such that the dynamic linker will
8030bind all undefined references when the file is loaded or launched.
8031
8032@item -bundle
8033@opindex bundle
8034Produce a Mach-o bundle format file.
8035See man ld(1) for more information.
8036
8037@item -bundle_loader @var{executable}
8038@opindex bundle_loader
8039This option specifies the @var{executable} that will be loading the build
8040output file being linked. See man ld(1) for more information.
8041
8042@item -dynamiclib
8043@opindex dynamiclib
8044When passed this option, GCC will produce a dynamic library instead of
8045an executable when linking, using the Darwin @file{libtool} command.
8046
8047@item -force_cpusubtype_ALL
8048@opindex force_cpusubtype_ALL
8049This causes GCC's output file to have the @var{ALL} subtype, instead of
8050one controlled by the @option{-mcpu} or @option{-march} option.
8051
8052@item -allowable_client @var{client_name}
8053@itemx -client_name
8054@itemx -compatibility_version
8055@itemx -current_version
8056@itemx -dead_strip
8057@itemx -dependency-file
8058@itemx -dylib_file
8059@itemx -dylinker_install_name
8060@itemx -dynamic
8061@itemx -exported_symbols_list
8062@itemx -filelist
8063@itemx -flat_namespace
8064@itemx -force_flat_namespace
8065@itemx -headerpad_max_install_names
8066@itemx -image_base
8067@itemx -init
8068@itemx -install_name
8069@itemx -keep_private_externs
8070@itemx -multi_module
8071@itemx -multiply_defined
8072@itemx -multiply_defined_unused
8073@itemx -noall_load
8074@itemx -no_dead_strip_inits_and_terms
8075@itemx -nofixprebinding
8076@itemx -nomultidefs
8077@itemx -noprebind
8078@itemx -noseglinkedit
8079@itemx -pagezero_size
8080@itemx -prebind
8081@itemx -prebind_all_twolevel_modules
8082@itemx -private_bundle
8083@itemx -read_only_relocs
8084@itemx -sectalign
8085@itemx -sectobjectsymbols
8086@itemx -whyload
8087@itemx -seg1addr
8088@itemx -sectcreate
8089@itemx -sectobjectsymbols
8090@itemx -sectorder
8091@itemx -segaddr
8092@itemx -segs_read_only_addr
8093@itemx -segs_read_write_addr
8094@itemx -seg_addr_table
8095@itemx -seg_addr_table_filename
8096@itemx -seglinkedit
8097@itemx -segprot
8098@itemx -segs_read_only_addr
8099@itemx -segs_read_write_addr
8100@itemx -single_module
8101@itemx -static
8102@itemx -sub_library
8103@itemx -sub_umbrella
8104@itemx -twolevel_namespace
8105@itemx -umbrella
8106@itemx -undefined
8107@itemx -unexported_symbols_list
8108@itemx -weak_reference_mismatches
8109@itemx -whatsloaded
8110
8111@opindex allowable_client
8112@opindex client_name
8113@opindex compatibility_version
8114@opindex current_version
8115@opindex dead_strip
8116@opindex dependency-file
8117@opindex dylib_file
8118@opindex dylinker_install_name
8119@opindex dynamic
8120@opindex exported_symbols_list
8121@opindex filelist
8122@opindex flat_namespace
8123@opindex force_flat_namespace
8124@opindex headerpad_max_install_names
8125@opindex image_base
8126@opindex init
8127@opindex install_name
8128@opindex keep_private_externs
8129@opindex multi_module
8130@opindex multiply_defined
8131@opindex multiply_defined_unused
8132@opindex noall_load
8133@opindex no_dead_strip_inits_and_terms
8134@opindex nofixprebinding
8135@opindex nomultidefs
8136@opindex noprebind
8137@opindex noseglinkedit
8138@opindex pagezero_size
8139@opindex prebind
8140@opindex prebind_all_twolevel_modules
8141@opindex private_bundle
8142@opindex read_only_relocs
8143@opindex sectalign
8144@opindex sectobjectsymbols
8145@opindex whyload
8146@opindex seg1addr
8147@opindex sectcreate
8148@opindex sectobjectsymbols
8149@opindex sectorder
8150@opindex segaddr
8151@opindex segs_read_only_addr
8152@opindex segs_read_write_addr
8153@opindex seg_addr_table
8154@opindex seg_addr_table_filename
8155@opindex seglinkedit
8156@opindex segprot
8157@opindex segs_read_only_addr
8158@opindex segs_read_write_addr
8159@opindex single_module
8160@opindex static
8161@opindex sub_library
8162@opindex sub_umbrella
8163@opindex twolevel_namespace
8164@opindex umbrella
8165@opindex undefined
8166@opindex unexported_symbols_list
8167@opindex weak_reference_mismatches
8168@opindex whatsloaded
8169
8170These options are passed to the Darwin linker. The Darwin linker man page
8171describes them in detail.
8172@end table
8173
8174@node DEC Alpha Options
8175@subsection DEC Alpha Options
8176
8177These @samp{-m} options are defined for the DEC Alpha implementations:
8178
8179@table @gcctabopt
8180@item -mno-soft-float
8181@itemx -msoft-float
8182@opindex mno-soft-float
8183@opindex msoft-float
8184Use (do not use) the hardware floating-point instructions for
8185floating-point operations. When @option{-msoft-float} is specified,
8186functions in @file{libgcc.a} will be used to perform floating-point
8187operations. Unless they are replaced by routines that emulate the
8188floating-point operations, or compiled in such a way as to call such
8189emulations routines, these routines will issue floating-point
8190operations. If you are compiling for an Alpha without floating-point
8191operations, you must ensure that the library is built so as not to call
8192them.
8193
8194Note that Alpha implementations without floating-point operations are
8195required to have floating-point registers.
8196
8197@item -mfp-reg
8198@itemx -mno-fp-regs
8199@opindex mfp-reg
8200@opindex mno-fp-regs
8201Generate code that uses (does not use) the floating-point register set.
8202@option{-mno-fp-regs} implies @option{-msoft-float}. If the floating-point
8203register set is not used, floating point operands are passed in integer
8204registers as if they were integers and floating-point results are passed
8205in @code{$0} instead of @code{$f0}. This is a non-standard calling sequence,
8206so any function with a floating-point argument or return value called by code
8207compiled with @option{-mno-fp-regs} must also be compiled with that
8208option.
8209
8210A typical use of this option is building a kernel that does not use,
8211and hence need not save and restore, any floating-point registers.
8212
8213@item -mieee
8214@opindex mieee
8215The Alpha architecture implements floating-point hardware optimized for
8216maximum performance. It is mostly compliant with the IEEE floating
8217point standard. However, for full compliance, software assistance is
8218required. This option generates code fully IEEE compliant code
8219@emph{except} that the @var{inexact-flag} is not maintained (see below).
8220If this option is turned on, the preprocessor macro @code{_IEEE_FP} is
8221defined during compilation. The resulting code is less efficient but is
8222able to correctly support denormalized numbers and exceptional IEEE
8223values such as not-a-number and plus/minus infinity. Other Alpha
8224compilers call this option @option{-ieee_with_no_inexact}.
8225
8226@item -mieee-with-inexact
8227@opindex mieee-with-inexact
8228This is like @option{-mieee} except the generated code also maintains
8229the IEEE @var{inexact-flag}. Turning on this option causes the
8230generated code to implement fully-compliant IEEE math. In addition to
8231@code{_IEEE_FP}, @code{_IEEE_FP_EXACT} is defined as a preprocessor
8232macro. On some Alpha implementations the resulting code may execute
8233significantly slower than the code generated by default. Since there is
8234very little code that depends on the @var{inexact-flag}, you should
8235normally not specify this option. Other Alpha compilers call this
8236option @option{-ieee_with_inexact}.
8237
8238@item -mfp-trap-mode=@var{trap-mode}
8239@opindex mfp-trap-mode
8240This option controls what floating-point related traps are enabled.
8241Other Alpha compilers call this option @option{-fptm @var{trap-mode}}.
8242The trap mode can be set to one of four values:
8243
8244@table @samp
8245@item n
8246This is the default (normal) setting. The only traps that are enabled
8247are the ones that cannot be disabled in software (e.g., division by zero
8248trap).
8249
8250@item u
8251In addition to the traps enabled by @samp{n}, underflow traps are enabled
8252as well.
8253
8254@item su
8255Like @samp{u}, but the instructions are marked to be safe for software
8256completion (see Alpha architecture manual for details).
8257
8258@item sui
8259Like @samp{su}, but inexact traps are enabled as well.
8260@end table
8261
8262@item -mfp-rounding-mode=@var{rounding-mode}
8263@opindex mfp-rounding-mode
8264Selects the IEEE rounding mode. Other Alpha compilers call this option
8265@option{-fprm @var{rounding-mode}}. The @var{rounding-mode} can be one
8266of:
8267
8268@table @samp
8269@item n
8270Normal IEEE rounding mode. Floating point numbers are rounded towards
8271the nearest machine number or towards the even machine number in case
8272of a tie.
8273
8274@item m
8275Round towards minus infinity.
8276
8277@item c
8278Chopped rounding mode. Floating point numbers are rounded towards zero.
8279
8280@item d
8281Dynamic rounding mode. A field in the floating point control register
8282(@var{fpcr}, see Alpha architecture reference manual) controls the
8283rounding mode in effect. The C library initializes this register for
8284rounding towards plus infinity. Thus, unless your program modifies the
8285@var{fpcr}, @samp{d} corresponds to round towards plus infinity.
8286@end table
8287
8288@item -mtrap-precision=@var{trap-precision}
8289@opindex mtrap-precision
8290In the Alpha architecture, floating point traps are imprecise. This
8291means without software assistance it is impossible to recover from a
8292floating trap and program execution normally needs to be terminated.
8293GCC can generate code that can assist operating system trap handlers
8294in determining the exact location that caused a floating point trap.
8295Depending on the requirements of an application, different levels of
8296precisions can be selected:
8297
8298@table @samp
8299@item p
8300Program precision. This option is the default and means a trap handler
8301can only identify which program caused a floating point exception.
8302
8303@item f
8304Function precision. The trap handler can determine the function that
8305caused a floating point exception.
8306
8307@item i
8308Instruction precision. The trap handler can determine the exact
8309instruction that caused a floating point exception.
8310@end table
8311
8312Other Alpha compilers provide the equivalent options called
8313@option{-scope_safe} and @option{-resumption_safe}.
8314
8315@item -mieee-conformant
8316@opindex mieee-conformant
8317This option marks the generated code as IEEE conformant. You must not
8318use this option unless you also specify @option{-mtrap-precision=i} and either
8319@option{-mfp-trap-mode=su} or @option{-mfp-trap-mode=sui}. Its only effect
8320is to emit the line @samp{.eflag 48} in the function prologue of the
8321generated assembly file. Under DEC Unix, this has the effect that
8322IEEE-conformant math library routines will be linked in.
8323
8324@item -mbuild-constants
8325@opindex mbuild-constants
8326Normally GCC examines a 32- or 64-bit integer constant to
8327see if it can construct it from smaller constants in two or three
8328instructions. If it cannot, it will output the constant as a literal and
8329generate code to load it from the data segment at runtime.
8330
8331Use this option to require GCC to construct @emph{all} integer constants
8332using code, even if it takes more instructions (the maximum is six).
8333
8334You would typically use this option to build a shared library dynamic
8335loader. Itself a shared library, it must relocate itself in memory
8336before it can find the variables and constants in its own data segment.
8337
8338@item -malpha-as
8339@itemx -mgas
8340@opindex malpha-as
8341@opindex mgas
8342Select whether to generate code to be assembled by the vendor-supplied
8343assembler (@option{-malpha-as}) or by the GNU assembler @option{-mgas}.
8344
8345@item -mbwx
8346@itemx -mno-bwx
8347@itemx -mcix
8348@itemx -mno-cix
8349@itemx -mfix
8350@itemx -mno-fix
8351@itemx -mmax
8352@itemx -mno-max
8353@opindex mbwx
8354@opindex mno-bwx
8355@opindex mcix
8356@opindex mno-cix
8357@opindex mfix
8358@opindex mno-fix
8359@opindex mmax
8360@opindex mno-max
8361Indicate whether GCC should generate code to use the optional BWX,
8362CIX, FIX and MAX instruction sets. The default is to use the instruction
8363sets supported by the CPU type specified via @option{-mcpu=} option or that
8364of the CPU on which GCC was built if none was specified.
8365
8366@item -mfloat-vax
8367@itemx -mfloat-ieee
8368@opindex mfloat-vax
8369@opindex mfloat-ieee
8370Generate code that uses (does not use) VAX F and G floating point
8371arithmetic instead of IEEE single and double precision.
8372
8373@item -mexplicit-relocs
8374@itemx -mno-explicit-relocs
8375@opindex mexplicit-relocs
8376@opindex mno-explicit-relocs
8377Older Alpha assemblers provided no way to generate symbol relocations
8378except via assembler macros. Use of these macros does not allow
8379optimal instruction scheduling. GNU binutils as of version 2.12
8380supports a new syntax that allows the compiler to explicitly mark
8381which relocations should apply to which instructions. This option
8382is mostly useful for debugging, as GCC detects the capabilities of
8383the assembler when it is built and sets the default accordingly.
8384
8385@item -msmall-data
8386@itemx -mlarge-data
8387@opindex msmall-data
8388@opindex mlarge-data
8389When @option{-mexplicit-relocs} is in effect, static data is
8390accessed via @dfn{gp-relative} relocations. When @option{-msmall-data}
8391is used, objects 8 bytes long or smaller are placed in a @dfn{small data area}
8392(the @code{.sdata} and @code{.sbss} sections) and are accessed via
839316-bit relocations off of the @code{$gp} register. This limits the
8394size of the small data area to 64KB, but allows the variables to be
8395directly accessed via a single instruction.
8396
8397The default is @option{-mlarge-data}. With this option the data area
8398is limited to just below 2GB@. Programs that require more than 2GB of
8399data must use @code{malloc} or @code{mmap} to allocate the data in the
8400heap instead of in the program's data segment.
8401
8402When generating code for shared libraries, @option{-fpic} implies
8403@option{-msmall-data} and @option{-fPIC} implies @option{-mlarge-data}.
8404
8405@item -msmall-text
8406@itemx -mlarge-text
8407@opindex msmall-text
8408@opindex mlarge-text
8409When @option{-msmall-text} is used, the compiler assumes that the
8410code of the entire program (or shared library) fits in 4MB, and is
8411thus reachable with a branch instruction. When @option{-msmall-data}
8412is used, the compiler can assume that all local symbols share the
8413same @code{$gp} value, and thus reduce the number of instructions
8414required for a function call from 4 to 1.
8415
8416The default is @option{-mlarge-text}.
8417
8418@item -mcpu=@var{cpu_type}
8419@opindex mcpu
8420Set the instruction set and instruction scheduling parameters for
8421machine type @var{cpu_type}. You can specify either the @samp{EV}
8422style name or the corresponding chip number. GCC supports scheduling
8423parameters for the EV4, EV5 and EV6 family of processors and will
8424choose the default values for the instruction set from the processor
8425you specify. If you do not specify a processor type, GCC will default
8426to the processor on which the compiler was built.
8427
8428Supported values for @var{cpu_type} are
8429
8430@table @samp
8431@item ev4
8432@itemx ev45
8433@itemx 21064
8434Schedules as an EV4 and has no instruction set extensions.
8435
8436@item ev5
8437@itemx 21164
8438Schedules as an EV5 and has no instruction set extensions.
8439
8440@item ev56
8441@itemx 21164a
8442Schedules as an EV5 and supports the BWX extension.
8443
8444@item pca56
8445@itemx 21164pc
8446@itemx 21164PC
8447Schedules as an EV5 and supports the BWX and MAX extensions.
8448
8449@item ev6
8450@itemx 21264
8451Schedules as an EV6 and supports the BWX, FIX, and MAX extensions.
8452
8453@item ev67
8454@itemx 21264a
8455Schedules as an EV6 and supports the BWX, CIX, FIX, and MAX extensions.
8456@end table
8457
8458@item -mtune=@var{cpu_type}
8459@opindex mtune
8460Set only the instruction scheduling parameters for machine type
8461@var{cpu_type}. The instruction set is not changed.
8462
8463@item -mmemory-latency=@var{time}
8464@opindex mmemory-latency
8465Sets the latency the scheduler should assume for typical memory
8466references as seen by the application. This number is highly
8467dependent on the memory access patterns used by the application
8468and the size of the external cache on the machine.
8469
8470Valid options for @var{time} are
8471
8472@table @samp
8473@item @var{number}
8474A decimal number representing clock cycles.
8475
8476@item L1
8477@itemx L2
8478@itemx L3
8479@itemx main
8480The compiler contains estimates of the number of clock cycles for
8481``typical'' EV4 & EV5 hardware for the Level 1, 2 & 3 caches
8482(also called Dcache, Scache, and Bcache), as well as to main memory.
8483Note that L3 is only valid for EV5.
8484
8485@end table
8486@end table
8487
8488@node DEC Alpha/VMS Options
8489@subsection DEC Alpha/VMS Options
8490
8491These @samp{-m} options are defined for the DEC Alpha/VMS implementations:
8492
8493@table @gcctabopt
8494@item -mvms-return-codes
8495@opindex mvms-return-codes
8496Return VMS condition codes from main. The default is to return POSIX
8497style condition (e.g.@ error) codes.
8498@end table
8499
8500@node FRV Options
8501@subsection FRV Options
8502@cindex FRV Options
8503
8504@table @gcctabopt
8505@item -mgpr-32
8506@opindex mgpr-32
8507
8508Only use the first 32 general purpose registers.
8509
8510@item -mgpr-64
8511@opindex mgpr-64
8512
8513Use all 64 general purpose registers.
8514
8515@item -mfpr-32
8516@opindex mfpr-32
8517
8518Use only the first 32 floating point registers.
8519
8520@item -mfpr-64
8521@opindex mfpr-64
8522
8523Use all 64 floating point registers
8524
8525@item -mhard-float
8526@opindex mhard-float
8527
8528Use hardware instructions for floating point operations.
8529
8530@item -msoft-float
8531@opindex msoft-float
8532
8533Use library routines for floating point operations.
8534
8535@item -malloc-cc
8536@opindex malloc-cc
8537
8538Dynamically allocate condition code registers.
8539
8540@item -mfixed-cc
8541@opindex mfixed-cc
8542
8543Do not try to dynamically allocate condition code registers, only
8544use @code{icc0} and @code{fcc0}.
8545
8546@item -mdword
8547@opindex mdword
8548
8549Change ABI to use double word insns.
8550
8551@item -mno-dword
8552@opindex mno-dword
8553
8554Do not use double word instructions.
8555
8556@item -mdouble
8557@opindex mdouble
8558
8559Use floating point double instructions.
8560
8561@item -mno-double
8562@opindex mno-double
8563
8564Do not use floating point double instructions.
8565
8566@item -mmedia
8567@opindex mmedia
8568
8569Use media instructions.
8570
8571@item -mno-media
8572@opindex mno-media
8573
8574Do not use media instructions.
8575
8576@item -mmuladd
8577@opindex mmuladd
8578
8579Use multiply and add/subtract instructions.
8580
8581@item -mno-muladd
8582@opindex mno-muladd
8583
8584Do not use multiply and add/subtract instructions.
8585
8586@item -mfdpic
8587@opindex mfdpic
8588
8589Select the FDPIC ABI, that uses function descriptors to represent
8590pointers to functions. Without any PIC/PIE-related options, it
8591implies @option{-fPIE}. With @option{-fpic} or @option{-fpie}, it
8592assumes GOT entries and small data are within a 12-bit range from the
8593GOT base address; with @option{-fPIC} or @option{-fPIE}, GOT offsets
8594are computed with 32 bits.
8595
8596@item -minline-plt
8597@opindex minline-plt
8598
8599Enable inlining of PLT entries in function calls to functions that are
8600not known to bind locally. It has no effect without @option{-mfdpic}.
8601It's enabled by default if optimizing for speed and compiling for
8602shared libraries (i.e., @option{-fPIC} or @option{-fpic}), or when an
8603optimization option such as @option{-O3} or above is present in the
8604command line.
8605
8606@item -mTLS
8607@opindex TLS
8608
8609Assume a large TLS segment when generating thread-local code.
8610
8611@item -mtls
8612@opindex tls
8613
8614Do not assume a large TLS segment when generating thread-local code.
8615
8616@item -mgprel-ro
8617@opindex mgprel-ro
8618
8619Enable the use of @code{GPREL} relocations in the FDPIC ABI for data
8620that is known to be in read-only sections. It's enabled by default,
8621except for @option{-fpic} or @option{-fpie}: even though it may help
8622make the global offset table smaller, it trades 1 instruction for 4.
8623With @option{-fPIC} or @option{-fPIE}, it trades 3 instructions for 4,
8624one of which may be shared by multiple symbols, and it avoids the need
8625for a GOT entry for the referenced symbol, so it's more likely to be a
8626win. If it is not, @option{-mno-gprel-ro} can be used to disable it.
8627
8628@item -multilib-library-pic
8629@opindex multilib-library-pic
8630
8631Link with the (library, not FD) pic libraries. It's implied by
8632@option{-mlibrary-pic}, as well as by @option{-fPIC} and
8633@option{-fpic} without @option{-mfdpic}. You should never have to use
8634it explicitly.
8635
8636@item -mlinked-fp
8637@opindex mlinked-fp
8638
8639Follow the EABI requirement of always creating a frame pointer whenever
8640a stack frame is allocated. This option is enabled by default and can
8641be disabled with @option{-mno-linked-fp}.
8642
8643@item -mlong-calls
8644@opindex mlong-calls
8645
8646Use indirect addressing to call functions outside the current
8647compilation unit. This allows the functions to be placed anywhere
8648within the 32-bit address space.
8649
8650@item -malign-labels
8651@opindex malign-labels
8652
8653Try to align labels to an 8-byte boundary by inserting nops into the
8654previous packet. This option only has an effect when VLIW packing
8655is enabled. It doesn't create new packets; it merely adds nops to
8656existing ones.
8657
8658@item -mlibrary-pic
8659@opindex mlibrary-pic
8660
8661Generate position-independent EABI code.
8662
8663@item -macc-4
8664@opindex macc-4
8665
8666Use only the first four media accumulator registers.
8667
8668@item -macc-8
8669@opindex macc-8
8670
8671Use all eight media accumulator registers.
8672
8673@item -mpack
8674@opindex mpack
8675
8676Pack VLIW instructions.
8677
8678@item -mno-pack
8679@opindex mno-pack
8680
8681Do not pack VLIW instructions.
8682
8683@item -mno-eflags
8684@opindex mno-eflags
8685
8686Do not mark ABI switches in e_flags.
8687
8688@item -mcond-move
8689@opindex mcond-move
8690
8691Enable the use of conditional-move instructions (default).
8692
8693This switch is mainly for debugging the compiler and will likely be removed
8694in a future version.
8695
8696@item -mno-cond-move
8697@opindex mno-cond-move
8698
8699Disable the use of conditional-move instructions.
8700
8701This switch is mainly for debugging the compiler and will likely be removed
8702in a future version.
8703
8704@item -mscc
8705@opindex mscc
8706
8707Enable the use of conditional set instructions (default).
8708
8709This switch is mainly for debugging the compiler and will likely be removed
8710in a future version.
8711
8712@item -mno-scc
8713@opindex mno-scc
8714
8715Disable the use of conditional set instructions.
8716
8717This switch is mainly for debugging the compiler and will likely be removed
8718in a future version.
8719
8720@item -mcond-exec
8721@opindex mcond-exec
8722
8723Enable the use of conditional execution (default).
8724
8725This switch is mainly for debugging the compiler and will likely be removed
8726in a future version.
8727
8728@item -mno-cond-exec
8729@opindex mno-cond-exec
8730
8731Disable the use of conditional execution.
8732
8733This switch is mainly for debugging the compiler and will likely be removed
8734in a future version.
8735
8736@item -mvliw-branch
8737@opindex mvliw-branch
8738
8739Run a pass to pack branches into VLIW instructions (default).
8740
8741This switch is mainly for debugging the compiler and will likely be removed
8742in a future version.
8743
8744@item -mno-vliw-branch
8745@opindex mno-vliw-branch
8746
8747Do not run a pass to pack branches into VLIW instructions.
8748
8749This switch is mainly for debugging the compiler and will likely be removed
8750in a future version.
8751
8752@item -mmulti-cond-exec
8753@opindex mmulti-cond-exec
8754
8755Enable optimization of @code{&&} and @code{||} in conditional execution
8756(default).
8757
8758This switch is mainly for debugging the compiler and will likely be removed
8759in a future version.
8760
8761@item -mno-multi-cond-exec
8762@opindex mno-multi-cond-exec
8763
8764Disable optimization of @code{&&} and @code{||} in conditional execution.
8765
8766This switch is mainly for debugging the compiler and will likely be removed
8767in a future version.
8768
8769@item -mnested-cond-exec
8770@opindex mnested-cond-exec
8771
8772Enable nested conditional execution optimizations (default).
8773
8774This switch is mainly for debugging the compiler and will likely be removed
8775in a future version.
8776
8777@item -mno-nested-cond-exec
8778@opindex mno-nested-cond-exec
8779
8780Disable nested conditional execution optimizations.
8781
8782This switch is mainly for debugging the compiler and will likely be removed
8783in a future version.
8784
8785@item -moptimize-membar
8786@opindex moptimize-membar
8787
8788This switch removes redundant @code{membar} instructions from the
8789compiler generated code. It is enabled by default.
8790
8791@item -mno-optimize-membar
8792@opindex mno-optimize-membar
8793
8794This switch disables the automatic removal of redundant @code{membar}
8795instructions from the generated code.
8796
8797@item -mtomcat-stats
8798@opindex mtomcat-stats
8799
8800Cause gas to print out tomcat statistics.
8801
8802@item -mcpu=@var{cpu}
8803@opindex mcpu
8804
8805Select the processor type for which to generate code. Possible values are
8806@samp{frv}, @samp{fr550}, @samp{tomcat}, @samp{fr500}, @samp{fr450},
8807@samp{fr405}, @samp{fr400}, @samp{fr300} and @samp{simple}.
8808
8809@end table
8810
8811@node GNU/Linux Options
8812@subsection GNU/Linux Options
8813
8814These @samp{-m} options are defined for GNU/Linux targets:
8815
8816@table @gcctabopt
8817@item -mglibc
8818@opindex mglibc
8819Use the GNU C library instead of uClibc. This is the default except
8820on @samp{*-*-linux-*uclibc*} targets.
8821
8822@item -muclibc
8823@opindex muclibc
8824Use uClibc instead of the GNU C library. This is the default on
8825@samp{*-*-linux-*uclibc*} targets.
8826@end table
8827
8828@node H8/300 Options
8829@subsection H8/300 Options
8830
8831These @samp{-m} options are defined for the H8/300 implementations:
8832
8833@table @gcctabopt
8834@item -mrelax
8835@opindex mrelax
8836Shorten some address references at link time, when possible; uses the
8837linker option @option{-relax}. @xref{H8/300,, @code{ld} and the H8/300,
8838ld, Using ld}, for a fuller description.
8839
8840@item -mh
8841@opindex mh
8842Generate code for the H8/300H@.
8843
8844@item -ms
8845@opindex ms
8846Generate code for the H8S@.
8847
8848@item -mn
8849@opindex mn
8850Generate code for the H8S and H8/300H in the normal mode. This switch
8851must be used either with @option{-mh} or @option{-ms}.
8852
8853@item -ms2600
8854@opindex ms2600
8855Generate code for the H8S/2600. This switch must be used with @option{-ms}.
8856
8857@item -mint32
8858@opindex mint32
8859Make @code{int} data 32 bits by default.
8860
8861@item -malign-300
8862@opindex malign-300
8863On the H8/300H and H8S, use the same alignment rules as for the H8/300.
8864The default for the H8/300H and H8S is to align longs and floats on 4
8865byte boundaries.
8866@option{-malign-300} causes them to be aligned on 2 byte boundaries.
8867This option has no effect on the H8/300.
8868@end table
8869
8870@node HPPA Options
8871@subsection HPPA Options
8872@cindex HPPA Options
8873
8874These @samp{-m} options are defined for the HPPA family of computers:
8875
8876@table @gcctabopt
8877@item -march=@var{architecture-type}
8878@opindex march
8879Generate code for the specified architecture. The choices for
8880@var{architecture-type} are @samp{1.0} for PA 1.0, @samp{1.1} for PA
88811.1, and @samp{2.0} for PA 2.0 processors. Refer to
8882@file{/usr/lib/sched.models} on an HP-UX system to determine the proper
8883architecture option for your machine. Code compiled for lower numbered
8884architectures will run on higher numbered architectures, but not the
8885other way around.
8886
8887@item -mpa-risc-1-0
8888@itemx -mpa-risc-1-1
8889@itemx -mpa-risc-2-0
8890@opindex mpa-risc-1-0
8891@opindex mpa-risc-1-1
8892@opindex mpa-risc-2-0
8893Synonyms for @option{-march=1.0}, @option{-march=1.1}, and @option{-march=2.0} respectively.
8894
8895@item -mbig-switch
8896@opindex mbig-switch
8897Generate code suitable for big switch tables. Use this option only if
8898the assembler/linker complain about out of range branches within a switch
8899table.
8900
8901@item -mjump-in-delay
8902@opindex mjump-in-delay
8903Fill delay slots of function calls with unconditional jump instructions
8904by modifying the return pointer for the function call to be the target
8905of the conditional jump.
8906
8907@item -mdisable-fpregs
8908@opindex mdisable-fpregs
8909Prevent floating point registers from being used in any manner. This is
8910necessary for compiling kernels which perform lazy context switching of
8911floating point registers. If you use this option and attempt to perform
8912floating point operations, the compiler will abort.
8913
8914@item -mdisable-indexing
8915@opindex mdisable-indexing
8916Prevent the compiler from using indexing address modes. This avoids some
8917rather obscure problems when compiling MIG generated code under MACH@.
8918
8919@item -mno-space-regs
8920@opindex mno-space-regs
8921Generate code that assumes the target has no space registers. This allows
8922GCC to generate faster indirect calls and use unscaled index address modes.
8923
8924Such code is suitable for level 0 PA systems and kernels.
8925
8926@item -mfast-indirect-calls
8927@opindex mfast-indirect-calls
8928Generate code that assumes calls never cross space boundaries. This
8929allows GCC to emit code which performs faster indirect calls.
8930
8931This option will not work in the presence of shared libraries or nested
8932functions.
8933
8934@item -mfixed-range=@var{register-range}
8935@opindex mfixed-range
8936Generate code treating the given register range as fixed registers.
8937A fixed register is one that the register allocator can not use. This is
8938useful when compiling kernel code. A register range is specified as
8939two registers separated by a dash. Multiple register ranges can be
8940specified separated by a comma.
8941
8942@item -mlong-load-store
8943@opindex mlong-load-store
8944Generate 3-instruction load and store sequences as sometimes required by
8945the HP-UX 10 linker. This is equivalent to the @samp{+k} option to
8946the HP compilers.
8947
8948@item -mportable-runtime
8949@opindex mportable-runtime
8950Use the portable calling conventions proposed by HP for ELF systems.
8951
8952@item -mgas
8953@opindex mgas
8954Enable the use of assembler directives only GAS understands.
8955
8956@item -mschedule=@var{cpu-type}
8957@opindex mschedule
8958Schedule code according to the constraints for the machine type
8959@var{cpu-type}. The choices for @var{cpu-type} are @samp{700}
8960@samp{7100}, @samp{7100LC}, @samp{7200}, @samp{7300} and @samp{8000}. Refer
8961to @file{/usr/lib/sched.models} on an HP-UX system to determine the
8962proper scheduling option for your machine. The default scheduling is
8963@samp{8000}.
8964
8965@item -mlinker-opt
8966@opindex mlinker-opt
8967Enable the optimization pass in the HP-UX linker. Note this makes symbolic
8968debugging impossible. It also triggers a bug in the HP-UX 8 and HP-UX 9
8969linkers in which they give bogus error messages when linking some programs.
8970
8971@item -msoft-float
8972@opindex msoft-float
8973Generate output containing library calls for floating point.
8974@strong{Warning:} the requisite libraries are not available for all HPPA
8975targets. Normally the facilities of the machine's usual C compiler are
8976used, but this cannot be done directly in cross-compilation. You must make
8977your own arrangements to provide suitable library functions for
8978cross-compilation. The embedded target @samp{hppa1.1-*-pro}
8979does provide software floating point support.
8980
8981@option{-msoft-float} changes the calling convention in the output file;
8982therefore, it is only useful if you compile @emph{all} of a program with
8983this option. In particular, you need to compile @file{libgcc.a}, the
8984library that comes with GCC, with @option{-msoft-float} in order for
8985this to work.
8986
8987@item -msio
8988@opindex msio
8989Generate the predefine, @code{_SIO}, for server IO@. The default is
8990@option{-mwsio}. This generates the predefines, @code{__hp9000s700},
8991@code{__hp9000s700__} and @code{_WSIO}, for workstation IO@. These
8992options are available under HP-UX and HI-UX@.
8993
8994@item -mgnu-ld
8995@opindex gnu-ld
8996Use GNU ld specific options. This passes @option{-shared} to ld when
8997building a shared library. It is the default when GCC is configured,
8998explicitly or implicitly, with the GNU linker. This option does not
8999have any affect on which ld is called, it only changes what parameters
9000are passed to that ld. The ld that is called is determined by the
9001@option{--with-ld} configure option, GCC's program search path, and
9002finally by the user's @env{PATH}. The linker used by GCC can be printed
9003using @samp{which `gcc -print-prog-name=ld`}. This option is only available
9004on the 64 bit HP-UX GCC, i.e. configured with @samp{hppa*64*-*-hpux*}.
9005
9006@item -mhp-ld
9007@opindex hp-ld
9008Use HP ld specific options. This passes @option{-b} to ld when building
9009a shared library and passes @option{+Accept TypeMismatch} to ld on all
9010links. It is the default when GCC is configured, explicitly or
9011implicitly, with the HP linker. This option does not have any affect on
9012which ld is called, it only changes what parameters are passed to that
9013ld. The ld that is called is determined by the @option{--with-ld}
9014configure option, GCC's program search path, and finally by the user's
9015@env{PATH}. The linker used by GCC can be printed using @samp{which
9016`gcc -print-prog-name=ld`}. This option is only available on the 64 bit
9017HP-UX GCC, i.e. configured with @samp{hppa*64*-*-hpux*}.
9018
9019@item -mlong-calls
9020@opindex mno-long-calls
9021Generate code that uses long call sequences. This ensures that a call
9022is always able to reach linker generated stubs. The default is to generate
9023long calls only when the distance from the call site to the beginning
9024of the function or translation unit, as the case may be, exceeds a
9025predefined limit set by the branch type being used. The limits for
9026normal calls are 7,600,000 and 240,000 bytes, respectively for the
9027PA 2.0 and PA 1.X architectures. Sibcalls are always limited at
9028240,000 bytes.
9029
9030Distances are measured from the beginning of functions when using the
9031@option{-ffunction-sections} option, or when using the @option{-mgas}
9032and @option{-mno-portable-runtime} options together under HP-UX with
9033the SOM linker.
9034
9035It is normally not desirable to use this option as it will degrade
9036performance. However, it may be useful in large applications,
9037particularly when partial linking is used to build the application.
9038
9039The types of long calls used depends on the capabilities of the
9040assembler and linker, and the type of code being generated. The
9041impact on systems that support long absolute calls, and long pic
9042symbol-difference or pc-relative calls should be relatively small.
9043However, an indirect call is used on 32-bit ELF systems in pic code
9044and it is quite long.
9045
9046@item -munix=@var{unix-std}
9047@opindex march
9048Generate compiler predefines and select a startfile for the specified
9049UNIX standard. The choices for @var{unix-std} are @samp{93}, @samp{95}
9050and @samp{98}. @samp{93} is supported on all HP-UX versions. @samp{95}
9051is available on HP-UX 10.10 and later. @samp{98} is available on HP-UX
905211.11 and later. The default values are @samp{93} for HP-UX 10.00,
9053@samp{95} for HP-UX 10.10 though to 11.00, and @samp{98} for HP-UX 11.11
9054and later.
9055
9056@option{-munix=93} provides the same predefines as GCC 3.3 and 3.4.
9057@option{-munix=95} provides additional predefines for @code{XOPEN_UNIX}
9058and @code{_XOPEN_SOURCE_EXTENDED}, and the startfile @file{unix95.o}.
9059@option{-munix=98} provides additional predefines for @code{_XOPEN_UNIX},
9060@code{_XOPEN_SOURCE_EXTENDED}, @code{_INCLUDE__STDC_A1_SOURCE} and
9061@code{_INCLUDE_XOPEN_SOURCE_500}, and the startfile @file{unix98.o}.
9062
9063It is @emph{important} to note that this option changes the interfaces
9064for various library routines. It also affects the operational behavior
9065of the C library. Thus, @emph{extreme} care is needed in using this
9066option.
9067
9068Library code that is intended to operate with more than one UNIX
9069standard must test, set and restore the variable @var{__xpg4_extended_mask}
9070as appropriate. Most GNU software doesn't provide this capability.
9071
9072@item -nolibdld
9073@opindex nolibdld
9074Suppress the generation of link options to search libdld.sl when the
9075@option{-static} option is specified on HP-UX 10 and later.
9076
9077@item -static
9078@opindex static
9079The HP-UX implementation of setlocale in libc has a dependency on
9080libdld.sl. There isn't an archive version of libdld.sl. Thus,
9081when the @option{-static} option is specified, special link options
9082are needed to resolve this dependency.
9083
9084On HP-UX 10 and later, the GCC driver adds the necessary options to
9085link with libdld.sl when the @option{-static} option is specified.
9086This causes the resulting binary to be dynamic. On the 64-bit port,
9087the linkers generate dynamic binaries by default in any case. The
9088@option{-nolibdld} option can be used to prevent the GCC driver from
9089adding these link options.
9090
9091@item -threads
9092@opindex threads
9093Add support for multithreading with the @dfn{dce thread} library
9094under HP-UX@. This option sets flags for both the preprocessor and
9095linker.
9096@end table
9097
9098@node i386 and x86-64 Options
9099@subsection Intel 386 and AMD x86-64 Options
9100@cindex i386 Options
9101@cindex x86-64 Options
9102@cindex Intel 386 Options
9103@cindex AMD x86-64 Options
9104
9105These @samp{-m} options are defined for the i386 and x86-64 family of
9106computers:
9107
9108@table @gcctabopt
9109@item -mtune=@var{cpu-type}
9110@opindex mtune
9111Tune to @var{cpu-type} everything applicable about the generated code, except
9112for the ABI and the set of available instructions. The choices for
9113@var{cpu-type} are:
9114@table @emph
9115@item generic
9116Produce code optimized for the most common IA32/AMD64/EM64T processors.
9117If you know the CPU on which your code will run, then you should use
9118the corresponding @option{-mtune} option instead of
9119@option{-mtune=generic}. But, if you do not know exactly what CPU users
9120of your application will have, then you should use this option.
9121
9122As new processors are deployed in the marketplace, the behavior of this
9123option will change. Therefore, if you upgrade to a newer version of
9124GCC, the code generated option will change to reflect the processors
9125that were most common when that version of GCC was released.
9126
9127There is no @option{-march=generic} option because @option{-march}
9128indicates the instruction set the compiler can use, and there is no
9129generic instruction set applicable to all processors. In contrast,
9130@option{-mtune} indicates the processor (or, in this case, collection of
9131processors) for which the code is optimized.
9132@item native
9133This selects the CPU to tune for at compilation time by determining
9134the processor type of the compiling machine. Using @option{-mtune=native}
9135will produce code optimized for the local machine under the constraints
9136of the selected instruction set. Using @option{-march=native} will
9137enable all instruction subsets supported by the local machine (hence
9138the result might not run on different machines).
9139@item i386
9140Original Intel's i386 CPU@.
9141@item i486
9142Intel's i486 CPU@. (No scheduling is implemented for this chip.)
9143@item i586, pentium
9144Intel Pentium CPU with no MMX support.
9145@item pentium-mmx
9146Intel PentiumMMX CPU based on Pentium core with MMX instruction set support.
9147@item pentiumpro
9148Intel PentiumPro CPU@.
9149@item i686
9150Same as @code{generic}, but when used as @code{march} option, PentiumPro
9151instruction set will be used, so the code will run on all i686 family chips.
9152@item pentium2
9153Intel Pentium2 CPU based on PentiumPro core with MMX instruction set support.
9154@item pentium3, pentium3m
9155Intel Pentium3 CPU based on PentiumPro core with MMX and SSE instruction set
9156support.
9157@item pentium-m
9158Low power version of Intel Pentium3 CPU with MMX, SSE and SSE2 instruction set
9159support. Used by Centrino notebooks.
9160@item pentium4, pentium4m
9161Intel Pentium4 CPU with MMX, SSE and SSE2 instruction set support.
9162@item prescott
9163Improved version of Intel Pentium4 CPU with MMX, SSE, SSE2 and SSE3 instruction
9164set support.
9165@item nocona
9166Improved version of Intel Pentium4 CPU with 64-bit extensions, MMX, SSE,
9167SSE2 and SSE3 instruction set support.
9168@item core2
9169Intel Core2 CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3 and SSSE3
9170instruction set support.
9171@item k6
9172AMD K6 CPU with MMX instruction set support.
9173@item k6-2, k6-3
9174Improved versions of AMD K6 CPU with MMX and 3dNOW! instruction set support.
9175@item athlon, athlon-tbird
9176AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW! and SSE prefetch instructions
9177support.
9178@item athlon-4, athlon-xp, athlon-mp
9179Improved AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW! and full SSE
9180instruction set support.
9181@item k8, opteron, athlon64, athlon-fx
9182AMD K8 core based CPUs with x86-64 instruction set support. (This supersets
9183MMX, SSE, SSE2, 3dNOW!, enhanced 3dNOW! and 64-bit instruction set extensions.)
9184@item k8-sse3, opteron-sse3, athlon64-sse3
9185Improved versions of k8, opteron and athlon64 with SSE3 instruction set support.
9186@item amdfam10, barcelona
9187AMD Family 10h core based CPUs with x86-64 instruction set support. (This
9188supersets MMX, SSE, SSE2, SSE3, SSE4A, 3dNOW!, enhanced 3dNOW!, ABM and 64-bit
9189instruction set extensions.)
9190@item winchip-c6
9191IDT Winchip C6 CPU, dealt in same way as i486 with additional MMX instruction
9192set support.
9193@item winchip2
9194IDT Winchip2 CPU, dealt in same way as i486 with additional MMX and 3dNOW!
9195instruction set support.
9196@item c3
9197Via C3 CPU with MMX and 3dNOW! instruction set support. (No scheduling is
9198implemented for this chip.)
9199@item c3-2
9200Via C3-2 CPU with MMX and SSE instruction set support. (No scheduling is
9201implemented for this chip.)
9202@item geode
9203Embedded AMD CPU with MMX and 3dNOW! instruction set support.
9204@end table
9205
9206While picking a specific @var{cpu-type} will schedule things appropriately
9207for that particular chip, the compiler will not generate any code that
9208does not run on the i386 without the @option{-march=@var{cpu-type}} option
9209being used.
9210
9211@item -march=@var{cpu-type}
9212@opindex march
9213Generate instructions for the machine type @var{cpu-type}. The choices
9214for @var{cpu-type} are the same as for @option{-mtune}. Moreover,
9215specifying @option{-march=@var{cpu-type}} implies @option{-mtune=@var{cpu-type}}.
9216
9217@item -mcpu=@var{cpu-type}
9218@opindex mcpu
9219A deprecated synonym for @option{-mtune}.
9220
9221@item -m386
9222@itemx -m486
9223@itemx -mpentium
9224@itemx -mpentiumpro
9225@opindex m386
9226@opindex m486
9227@opindex mpentium
9228@opindex mpentiumpro
9229These options are synonyms for @option{-mtune=i386}, @option{-mtune=i486},
9230@option{-mtune=pentium}, and @option{-mtune=pentiumpro} respectively.
9231These synonyms are deprecated.
9232
9233@item -mfpmath=@var{unit}
9234@opindex march
9235Generate floating point arithmetics for selected unit @var{unit}. The choices
9236for @var{unit} are:
9237
9238@table @samp
9239@item 387
9240Use the standard 387 floating point coprocessor present majority of chips and
9241emulated otherwise. Code compiled with this option will run almost everywhere.
9242The temporary results are computed in 80bit precision instead of precision
9243specified by the type resulting in slightly different results compared to most
9244of other chips. See @option{-ffloat-store} for more detailed description.
9245
9246This is the default choice for i386 compiler.
9247
9248@item sse
9249Use scalar floating point instructions present in the SSE instruction set.
9250This instruction set is supported by Pentium3 and newer chips, in the AMD line
9251by Athlon-4, Athlon-xp and Athlon-mp chips. The earlier version of SSE
9252instruction set supports only single precision arithmetics, thus the double and
9253extended precision arithmetics is still done using 387. Later version, present
9254only in Pentium4 and the future AMD x86-64 chips supports double precision
9255arithmetics too.
9256
9257For the i386 compiler, you need to use @option{-march=@var{cpu-type}}, @option{-msse}
9258or @option{-msse2} switches to enable SSE extensions and make this option
9259effective. For the x86-64 compiler, these extensions are enabled by default.
9260
9261The resulting code should be considerably faster in the majority of cases and avoid
9262the numerical instability problems of 387 code, but may break some existing
9263code that expects temporaries to be 80bit.
9264
9265This is the default choice for the x86-64 compiler.
9266
9267@item sse,387
9268Attempt to utilize both instruction sets at once. This effectively double the
9269amount of available registers and on chips with separate execution units for
9270387 and SSE the execution resources too. Use this option with care, as it is
9271still experimental, because the GCC register allocator does not model separate
9272functional units well resulting in instable performance.
9273@end table
9274
9275@item -masm=@var{dialect}
9276@opindex masm=@var{dialect}
9277Output asm instructions using selected @var{dialect}. Supported
9278choices are @samp{intel} or @samp{att} (the default one). Darwin does
9279not support @samp{intel}.
9280
9281@item -mieee-fp
9282@itemx -mno-ieee-fp
9283@opindex mieee-fp
9284@opindex mno-ieee-fp
9285Control whether or not the compiler uses IEEE floating point
9286comparisons. These handle correctly the case where the result of a
9287comparison is unordered.
9288
9289@item -msoft-float
9290@opindex msoft-float
9291Generate output containing library calls for floating point.
9292@strong{Warning:} the requisite libraries are not part of GCC@.
9293Normally the facilities of the machine's usual C compiler are used, but
9294this can't be done directly in cross-compilation. You must make your
9295own arrangements to provide suitable library functions for
9296cross-compilation.
9297
9298On machines where a function returns floating point results in the 80387
9299register stack, some floating point opcodes may be emitted even if
9300@option{-msoft-float} is used.
9301
9302@item -mno-fp-ret-in-387
9303@opindex mno-fp-ret-in-387
9304Do not use the FPU registers for return values of functions.
9305
9306The usual calling convention has functions return values of types
9307@code{float} and @code{double} in an FPU register, even if there
9308is no FPU@. The idea is that the operating system should emulate
9309an FPU@.
9310
9311The option @option{-mno-fp-ret-in-387} causes such values to be returned
9312in ordinary CPU registers instead.
9313
9314@item -mno-fancy-math-387
9315@opindex mno-fancy-math-387
9316Some 387 emulators do not support the @code{sin}, @code{cos} and
9317@code{sqrt} instructions for the 387. Specify this option to avoid
9318generating those instructions. This option is the default on
9319OpenBSD and NetBSD@. This option is overridden when @option{-march}
9320indicates that the target cpu will always have an FPU and so the
9321instruction will not need emulation. As of revision 2.6.1, these
9322instructions are not generated unless you also use the
9323@option{-funsafe-math-optimizations} switch.
9324
9325@item -malign-double
9326@itemx -mno-align-double
9327@opindex malign-double
9328@opindex mno-align-double
9329Control whether GCC aligns @code{double}, @code{long double}, and
9330@code{long long} variables on a two word boundary or a one word
9331boundary. Aligning @code{double} variables on a two word boundary will
9332produce code that runs somewhat faster on a @samp{Pentium} at the
9333expense of more memory.
9334
9335On x86-64, @option{-malign-double} is enabled by default.
9336
9337@strong{Warning:} if you use the @option{-malign-double} switch,
9338structures containing the above types will be aligned differently than
9339the published application binary interface specifications for the 386
9340and will not be binary compatible with structures in code compiled
9341without that switch.
9342
9343@item -m96bit-long-double
9344@itemx -m128bit-long-double
9345@opindex m96bit-long-double
9346@opindex m128bit-long-double
9347These switches control the size of @code{long double} type. The i386
9348application binary interface specifies the size to be 96 bits,
9349so @option{-m96bit-long-double} is the default in 32 bit mode.
9350
9351Modern architectures (Pentium and newer) would prefer @code{long double}
9352to be aligned to an 8 or 16 byte boundary. In arrays or structures
9353conforming to the ABI, this would not be possible. So specifying a
9354@option{-m128bit-long-double} will align @code{long double}
9355to a 16 byte boundary by padding the @code{long double} with an additional
935632 bit zero.
9357
9358In the x86-64 compiler, @option{-m128bit-long-double} is the default choice as
9359its ABI specifies that @code{long double} is to be aligned on 16 byte boundary.
9360
9361Notice that neither of these options enable any extra precision over the x87
9362standard of 80 bits for a @code{long double}.
9363
9364@strong{Warning:} if you override the default value for your target ABI, the
9365structures and arrays containing @code{long double} variables will change
9366their size as well as function calling convention for function taking
9367@code{long double} will be modified. Hence they will not be binary
9368compatible with arrays or structures in code compiled without that switch.
9369
9370@item -mmlarge-data-threshold=@var{number}
9371@opindex mlarge-data-threshold=@var{number}
9372When @option{-mcmodel=medium} is specified, the data greater than
9373@var{threshold} are placed in large data section. This value must be the
9374same across all object linked into the binary and defaults to 65535.
9375
9376@item -msvr3-shlib
9377@itemx -mno-svr3-shlib
9378@opindex msvr3-shlib
9379@opindex mno-svr3-shlib
9380Control whether GCC places uninitialized local variables into the
9381@code{bss} or @code{data} segments. @option{-msvr3-shlib} places them
9382into @code{bss}. These options are meaningful only on System V Release 3.
9383
9384@item -mrtd
9385@opindex mrtd
9386Use a different function-calling convention, in which functions that
9387take a fixed number of arguments return with the @code{ret} @var{num}
9388instruction, which pops their arguments while returning. This saves one
9389instruction in the caller since there is no need to pop the arguments
9390there.
9391
9392You can specify that an individual function is called with this calling
9393sequence with the function attribute @samp{stdcall}. You can also
9394override the @option{-mrtd} option by using the function attribute
9395@samp{cdecl}. @xref{Function Attributes}.
9396
9397@strong{Warning:} this calling convention is incompatible with the one
9398normally used on Unix, so you cannot use it if you need to call
9399libraries compiled with the Unix compiler.
9400
9401Also, you must provide function prototypes for all functions that
9402take variable numbers of arguments (including @code{printf});
9403otherwise incorrect code will be generated for calls to those
9404functions.
9405
9406In addition, seriously incorrect code will result if you call a
9407function with too many arguments. (Normally, extra arguments are
9408harmlessly ignored.)
9409
9410@item -mregparm=@var{num}
9411@opindex mregparm
9412Control how many registers are used to pass integer arguments. By
9413default, no registers are used to pass arguments, and at most 3
9414registers can be used. You can control this behavior for a specific
9415function by using the function attribute @samp{regparm}.
9416@xref{Function Attributes}.
9417
9418@strong{Warning:} if you use this switch, and
9419@var{num} is nonzero, then you must build all modules with the same
9420value, including any libraries. This includes the system libraries and
9421startup modules.
9422
9423@item -msseregparm
9424@opindex msseregparm
9425Use SSE register passing conventions for float and double arguments
9426and return values. You can control this behavior for a specific
9427function by using the function attribute @samp{sseregparm}.
9428@xref{Function Attributes}.
9429
9430@strong{Warning:} if you use this switch then you must build all
9431modules with the same value, including any libraries. This includes
9432the system libraries and startup modules.
9433
9434@item -mstackrealign
9435@opindex mstackrealign
9436Realign the stack at entry. On the Intel x86, the
9437@option{-mstackrealign} option will generate an alternate prologue and
9438epilogue that realigns the runtime stack. This supports mixing legacy
9439codes that keep a 4-byte aligned stack with modern codes that keep a
944016-byte stack for SSE compatibility. The alternate prologue and
9441epilogue are slower and bigger than the regular ones, and the
9442alternate prologue requires an extra scratch register; this lowers the
9443number of registers available if used in conjunction with the
9444@code{regparm} attribute. The @option{-mstackrealign} option is
9445incompatible with the nested function prologue; this is considered a
9446hard error. See also the attribute @code{force_align_arg_pointer},
9447applicable to individual functions.
9448
9449@item -mpreferred-stack-boundary=@var{num}
9450@opindex mpreferred-stack-boundary
9451Attempt to keep the stack boundary aligned to a 2 raised to @var{num}
9452byte boundary. If @option{-mpreferred-stack-boundary} is not specified,
9453the default is 4 (16 bytes or 128 bits).
9454
9455On Pentium and PentiumPro, @code{double} and @code{long double} values
9456should be aligned to an 8 byte boundary (see @option{-malign-double}) or
9457suffer significant run time performance penalties. On Pentium III, the
9458Streaming SIMD Extension (SSE) data type @code{__m128} may not work
9459properly if it is not 16 byte aligned.
9460
9461To ensure proper alignment of this values on the stack, the stack boundary
9462must be as aligned as that required by any value stored on the stack.
9463Further, every function must be generated such that it keeps the stack
9464aligned. Thus calling a function compiled with a higher preferred
9465stack boundary from a function compiled with a lower preferred stack
9466boundary will most likely misalign the stack. It is recommended that
9467libraries that use callbacks always use the default setting.
9468
9469This extra alignment does consume extra stack space, and generally
9470increases code size. Code that is sensitive to stack space usage, such
9471as embedded systems and operating system kernels, may want to reduce the
9472preferred alignment to @option{-mpreferred-stack-boundary=2}.
9473
9474@item -mmmx
9475@itemx -mno-mmx
9476@item -msse
9477@itemx -mno-sse
9478@item -msse2
9479@itemx -mno-sse2
9480@item -msse3
9481@itemx -mno-sse3
9482@item -mssse3
9483@itemx -mno-ssse3
9484@item -msse4a
9485@item -mno-sse4a
9486@item -m3dnow
9487@itemx -mno-3dnow
9488@item -mpopcnt
9489@itemx -mno-popcnt
9490@item -mabm
9491@itemx -mno-abm
9492@item -maes
9493@itemx -mno-aes
9494@opindex mmmx
9495@opindex mno-mmx
9496@opindex msse
9497@opindex mno-sse
9498@opindex m3dnow
9499@opindex mno-3dnow
9500These switches enable or disable the use of instructions in the MMX,
9501SSE, SSE2, SSE3, SSSE3, SSE4A, ABM, AES or 3DNow! extended
9502instruction sets. These extensions are also available as built-in
9503functions: see @ref{X86 Built-in Functions}, for details of the functions
9504enabled and disabled by these switches.
9505
9506To have SSE/SSE2 instructions generated automatically from floating-point
9507code (as opposed to 387 instructions), see @option{-mfpmath=sse}.
9508
9509These options will enable GCC to use these extended instructions in
9510generated code, even without @option{-mfpmath=sse}. Applications which
9511perform runtime CPU detection must compile separate files for each
9512supported architecture, using the appropriate flags. In particular,
9513the file containing the CPU detection code should be compiled without
9514these options.
9515
9516@item -mpush-args
9517@itemx -mno-push-args
9518@opindex mpush-args
9519@opindex mno-push-args
9520Use PUSH operations to store outgoing parameters. This method is shorter
9521and usually equally fast as method using SUB/MOV operations and is enabled
9522by default. In some cases disabling it may improve performance because of
9523improved scheduling and reduced dependencies.
9524
9525@item -maccumulate-outgoing-args
9526@opindex maccumulate-outgoing-args
9527If enabled, the maximum amount of space required for outgoing arguments will be
9528computed in the function prologue. This is faster on most modern CPUs
9529because of reduced dependencies, improved scheduling and reduced stack usage
9530when preferred stack boundary is not equal to 2. The drawback is a notable
9531increase in code size. This switch implies @option{-mno-push-args}.
9532
9533@item -mthreads
9534@opindex mthreads
9535Support thread-safe exception handling on @samp{Mingw32}. Code that relies
9536on thread-safe exception handling must compile and link all code with the
9537@option{-mthreads} option. When compiling, @option{-mthreads} defines
9538@option{-D_MT}; when linking, it links in a special thread helper library
9539@option{-lmingwthrd} which cleans up per thread exception handling data.
9540
9541@item -mno-align-stringops
9542@opindex mno-align-stringops
9543Do not align destination of inlined string operations. This switch reduces
9544code size and improves performance in case the destination is already aligned,
9545but GCC doesn't know about it.
9546
9547@item -minline-all-stringops
9548@opindex minline-all-stringops
9549By default GCC inlines string operations only when destination is known to be
9550aligned at least to 4 byte boundary. This enables more inlining, increase code
9551size, but may improve performance of code that depends on fast memcpy, strlen
9552and memset for short lengths.
9553
9554@item -momit-leaf-frame-pointer
9555@opindex momit-leaf-frame-pointer
9556Don't keep the frame pointer in a register for leaf functions. This
9557avoids the instructions to save, set up and restore frame pointers and
9558makes an extra register available in leaf functions. The option
9559@option{-fomit-frame-pointer} removes the frame pointer for all functions
9560which might make debugging harder.
9561
9562@item -mtls-direct-seg-refs
9563@itemx -mno-tls-direct-seg-refs
9564@opindex mtls-direct-seg-refs
9565Controls whether TLS variables may be accessed with offsets from the
9566TLS segment register (@code{%gs} for 32-bit, @code{%fs} for 64-bit),
9567or whether the thread base pointer must be added. Whether or not this
9568is legal depends on the operating system, and whether it maps the
9569segment to cover the entire TLS area.
9570
9571For systems that use GNU libc, the default is on.
9572@end table
9573
9574These @samp{-m} switches are supported in addition to the above
9575on AMD x86-64 processors in 64-bit environments.
9576
9577@table @gcctabopt
9578@item -m32
9579@itemx -m64
9580@opindex m32
9581@opindex m64
9582Generate code for a 32-bit or 64-bit environment.
9583The 32-bit environment sets int, long and pointer to 32 bits and
9584generates code that runs on any i386 system.
9585The 64-bit environment sets int to 32 bits and long and pointer
9586to 64 bits and generates code for AMD's x86-64 architecture. For
9587darwin only the -m64 option turns off the @option{-fno-pic} and
9588@option{-mdynamic-no-pic} options.
9589
9590@item -mno-red-zone
9591@opindex no-red-zone
9592Do not use a so called red zone for x86-64 code. The red zone is mandated
9593by the x86-64 ABI, it is a 128-byte area beyond the location of the
9594stack pointer that will not be modified by signal or interrupt handlers
9595and therefore can be used for temporary data without adjusting the stack
9596pointer. The flag @option{-mno-red-zone} disables this red zone.
9597
9598@item -mcmodel=small
9599@opindex mcmodel=small
9600Generate code for the small code model: the program and its symbols must
9601be linked in the lower 2 GB of the address space. Pointers are 64 bits.
9602Programs can be statically or dynamically linked. This is the default
9603code model.
9604
9605@item -mcmodel=kernel
9606@opindex mcmodel=kernel
9607Generate code for the kernel code model. The kernel runs in the
9608negative 2 GB of the address space.
9609This model has to be used for Linux kernel code.
9610
9611@item -mcmodel=medium
9612@opindex mcmodel=medium
9613Generate code for the medium model: The program is linked in the lower 2
9614GB of the address space but symbols can be located anywhere in the
9615address space. Programs can be statically or dynamically linked, but
9616building of shared libraries are not supported with the medium model.
9617
9618@item -mcmodel=large
9619@opindex mcmodel=large
9620Generate code for the large model: This model makes no assumptions
9621about addresses and sizes of sections. Currently GCC does not implement
9622this model.
9623@end table
9624
9625@node IA-64 Options
9626@subsection IA-64 Options
9627@cindex IA-64 Options
9628
9629These are the @samp{-m} options defined for the Intel IA-64 architecture.
9630
9631@table @gcctabopt
9632@item -mbig-endian
9633@opindex mbig-endian
9634Generate code for a big endian target. This is the default for HP-UX@.
9635
9636@item -mlittle-endian
9637@opindex mlittle-endian
9638Generate code for a little endian target. This is the default for AIX5
9639and GNU/Linux.
9640
9641@item -mgnu-as
9642@itemx -mno-gnu-as
9643@opindex mgnu-as
9644@opindex mno-gnu-as
9645Generate (or don't) code for the GNU assembler. This is the default.
9646@c Also, this is the default if the configure option @option{--with-gnu-as}
9647@c is used.
9648
9649@item -mgnu-ld
9650@itemx -mno-gnu-ld
9651@opindex mgnu-ld
9652@opindex mno-gnu-ld
9653Generate (or don't) code for the GNU linker. This is the default.
9654@c Also, this is the default if the configure option @option{--with-gnu-ld}
9655@c is used.
9656
9657@item -mno-pic
9658@opindex mno-pic
9659Generate code that does not use a global pointer register. The result
9660is not position independent code, and violates the IA-64 ABI@.
9661
9662@item -mvolatile-asm-stop
9663@itemx -mno-volatile-asm-stop
9664@opindex mvolatile-asm-stop
9665@opindex mno-volatile-asm-stop
9666Generate (or don't) a stop bit immediately before and after volatile asm
9667statements.
9668
9669@item -mregister-names
9670@itemx -mno-register-names
9671@opindex mregister-names
9672@opindex mno-register-names
9673Generate (or don't) @samp{in}, @samp{loc}, and @samp{out} register names for
9674the stacked registers. This may make assembler output more readable.
9675
9676@item -mno-sdata
9677@itemx -msdata
9678@opindex mno-sdata
9679@opindex msdata
9680Disable (or enable) optimizations that use the small data section. This may
9681be useful for working around optimizer bugs.
9682
9683@item -mconstant-gp
9684@opindex mconstant-gp
9685Generate code that uses a single constant global pointer value. This is
9686useful when compiling kernel code.
9687
9688@item -mauto-pic
9689@opindex mauto-pic
9690Generate code that is self-relocatable. This implies @option{-mconstant-gp}.
9691This is useful when compiling firmware code.
9692
9693@item -minline-float-divide-min-latency
9694@opindex minline-float-divide-min-latency
9695Generate code for inline divides of floating point values
9696using the minimum latency algorithm.
9697
9698@item -minline-float-divide-max-throughput
9699@opindex minline-float-divide-max-throughput
9700Generate code for inline divides of floating point values
9701using the maximum throughput algorithm.
9702
9703@item -minline-int-divide-min-latency
9704@opindex minline-int-divide-min-latency
9705Generate code for inline divides of integer values
9706using the minimum latency algorithm.
9707
9708@item -minline-int-divide-max-throughput
9709@opindex minline-int-divide-max-throughput
9710Generate code for inline divides of integer values
9711using the maximum throughput algorithm.
9712
9713@item -minline-sqrt-min-latency
9714@opindex minline-sqrt-min-latency
9715Generate code for inline square roots
9716using the minimum latency algorithm.
9717
9718@item -minline-sqrt-max-throughput
9719@opindex minline-sqrt-max-throughput
9720Generate code for inline square roots
9721using the maximum throughput algorithm.
9722
9723@item -mno-dwarf2-asm
9724@itemx -mdwarf2-asm
9725@opindex mno-dwarf2-asm
9726@opindex mdwarf2-asm
9727Don't (or do) generate assembler code for the DWARF2 line number debugging
9728info. This may be useful when not using the GNU assembler.
9729
9730@item -mearly-stop-bits
9731@itemx -mno-early-stop-bits
9732@opindex mearly-stop-bits
9733@opindex mno-early-stop-bits
9734Allow stop bits to be placed earlier than immediately preceding the
9735instruction that triggered the stop bit. This can improve instruction
9736scheduling, but does not always do so.
9737
9738@item -mfixed-range=@var{register-range}
9739@opindex mfixed-range
9740Generate code treating the given register range as fixed registers.
9741A fixed register is one that the register allocator can not use. This is
9742useful when compiling kernel code. A register range is specified as
9743two registers separated by a dash. Multiple register ranges can be
9744specified separated by a comma.
9745
9746@item -mtls-size=@var{tls-size}
9747@opindex mtls-size
9748Specify bit size of immediate TLS offsets. Valid values are 14, 22, and
974964.
9750
9751@item -mtune=@var{cpu-type}
9752@opindex mtune
9753Tune the instruction scheduling for a particular CPU, Valid values are
9754itanium, itanium1, merced, itanium2, and mckinley.
9755
9756@item -mt
9757@itemx -pthread
9758@opindex mt
9759@opindex pthread
9760Add support for multithreading using the POSIX threads library. This
9761option sets flags for both the preprocessor and linker. It does
9762not affect the thread safety of object code produced by the compiler or
9763that of libraries supplied with it. These are HP-UX specific flags.
9764
9765@item -milp32
9766@itemx -mlp64
9767@opindex milp32
9768@opindex mlp64
9769Generate code for a 32-bit or 64-bit environment.
9770The 32-bit environment sets int, long and pointer to 32 bits.
9771The 64-bit environment sets int to 32 bits and long and pointer
9772to 64 bits. These are HP-UX specific flags.
9773
9774@item -mno-sched-br-data-spec
9775@itemx -msched-br-data-spec
9776@opindex mno-sched-br-data-spec
9777@opindex msched-br-data-spec
9778(Dis/En)able data speculative scheduling before reload.
9779This will result in generation of the ld.a instructions and
9780the corresponding check instructions (ld.c / chk.a).
9781The default is 'disable'.
9782
9783@item -msched-ar-data-spec
9784@itemx -mno-sched-ar-data-spec
9785@opindex msched-ar-data-spec
9786@opindex mno-sched-ar-data-spec
9787(En/Dis)able data speculative scheduling after reload.
9788This will result in generation of the ld.a instructions and
9789the corresponding check instructions (ld.c / chk.a).
9790The default is 'enable'.
9791
9792@item -mno-sched-control-spec
9793@itemx -msched-control-spec
9794@opindex mno-sched-control-spec
9795@opindex msched-control-spec
9796(Dis/En)able control speculative scheduling. This feature is
9797available only during region scheduling (i.e. before reload).
9798This will result in generation of the ld.s instructions and
9799the corresponding check instructions chk.s .
9800The default is 'disable'.
9801
9802@item -msched-br-in-data-spec
9803@itemx -mno-sched-br-in-data-spec
9804@opindex msched-br-in-data-spec
9805@opindex mno-sched-br-in-data-spec
9806(En/Dis)able speculative scheduling of the instructions that
9807are dependent on the data speculative loads before reload.
9808This is effective only with @option{-msched-br-data-spec} enabled.
9809The default is 'enable'.
9810
9811@item -msched-ar-in-data-spec
9812@itemx -mno-sched-ar-in-data-spec
9813@opindex msched-ar-in-data-spec
9814@opindex mno-sched-ar-in-data-spec
9815(En/Dis)able speculative scheduling of the instructions that
9816are dependent on the data speculative loads after reload.
9817This is effective only with @option{-msched-ar-data-spec} enabled.
9818The default is 'enable'.
9819
9820@item -msched-in-control-spec
9821@itemx -mno-sched-in-control-spec
9822@opindex msched-in-control-spec
9823@opindex mno-sched-in-control-spec
9824(En/Dis)able speculative scheduling of the instructions that
9825are dependent on the control speculative loads.
9826This is effective only with @option{-msched-control-spec} enabled.
9827The default is 'enable'.
9828
9829@item -msched-ldc
9830@itemx -mno-sched-ldc
9831@opindex msched-ldc
9832@opindex mno-sched-ldc
9833(En/Dis)able use of simple data speculation checks ld.c .
9834If disabled, only chk.a instructions will be emitted to check
9835data speculative loads.
9836The default is 'enable'.
9837
9838@item -mno-sched-control-ldc
9839@itemx -msched-control-ldc
9840@opindex mno-sched-control-ldc
9841@opindex msched-control-ldc
9842(Dis/En)able use of ld.c instructions to check control speculative loads.
9843If enabled, in case of control speculative load with no speculatively
9844scheduled dependent instructions this load will be emitted as ld.sa and
9845ld.c will be used to check it.
9846The default is 'disable'.
9847
9848@item -mno-sched-spec-verbose
9849@itemx -msched-spec-verbose
9850@opindex mno-sched-spec-verbose
9851@opindex msched-spec-verbose
9852(Dis/En)able printing of the information about speculative motions.
9853
9854@item -mno-sched-prefer-non-data-spec-insns
9855@itemx -msched-prefer-non-data-spec-insns
9856@opindex mno-sched-prefer-non-data-spec-insns
9857@opindex msched-prefer-non-data-spec-insns
9858If enabled, data speculative instructions will be chosen for schedule
9859only if there are no other choices at the moment. This will make
9860the use of the data speculation much more conservative.
9861The default is 'disable'.
9862
9863@item -mno-sched-prefer-non-control-spec-insns
9864@itemx -msched-prefer-non-control-spec-insns
9865@opindex mno-sched-prefer-non-control-spec-insns
9866@opindex msched-prefer-non-control-spec-insns
9867If enabled, control speculative instructions will be chosen for schedule
9868only if there are no other choices at the moment. This will make
9869the use of the control speculation much more conservative.
9870The default is 'disable'.
9871
9872@item -mno-sched-count-spec-in-critical-path
9873@itemx -msched-count-spec-in-critical-path
9874@opindex mno-sched-count-spec-in-critical-path
9875@opindex msched-count-spec-in-critical-path
9876If enabled, speculative dependencies will be considered during
9877computation of the instructions priorities. This will make the use of the
9878speculation a bit more conservative.
9879The default is 'disable'.
9880
9881@end table
9882
9883@node M32C Options
9884@subsection M32C Options
9885@cindex M32C options
9886
9887@table @gcctabopt
9888@item -mcpu=@var{name}
9889@opindex mcpu=
9890Select the CPU for which code is generated. @var{name} may be one of
9891@samp{r8c} for the R8C/Tiny series, @samp{m16c} for the M16C (up to
9892/60) series, @samp{m32cm} for the M16C/80 series, or @samp{m32c} for
9893the M32C/80 series.
9894
9895@item -msim
9896@opindex msim
9897Specifies that the program will be run on the simulator. This causes
9898an alternate runtime library to be linked in which supports, for
9899example, file I/O. You must not use this option when generating
9900programs that will run on real hardware; you must provide your own
9901runtime library for whatever I/O functions are needed.
9902
9903@item -memregs=@var{number}
9904@opindex memregs=
9905Specifies the number of memory-based pseudo-registers GCC will use
9906during code generation. These pseudo-registers will be used like real
9907registers, so there is a tradeoff between GCC's ability to fit the
9908code into available registers, and the performance penalty of using
9909memory instead of registers. Note that all modules in a program must
9910be compiled with the same value for this option. Because of that, you
9911must not use this option with the default runtime libraries gcc
9912builds.
9913
9914@end table
9915
9916@node M32R/D Options
9917@subsection M32R/D Options
9918@cindex M32R/D options
9919
9920These @option{-m} options are defined for Renesas M32R/D architectures:
9921
9922@table @gcctabopt
9923@item -m32r2
9924@opindex m32r2
9925Generate code for the M32R/2@.
9926
9927@item -m32rx
9928@opindex m32rx
9929Generate code for the M32R/X@.
9930
9931@item -m32r
9932@opindex m32r
9933Generate code for the M32R@. This is the default.
9934
9935@item -mmodel=small
9936@opindex mmodel=small
9937Assume all objects live in the lower 16MB of memory (so that their addresses
9938can be loaded with the @code{ld24} instruction), and assume all subroutines
9939are reachable with the @code{bl} instruction.
9940This is the default.
9941
9942The addressability of a particular object can be set with the
9943@code{model} attribute.
9944
9945@item -mmodel=medium
9946@opindex mmodel=medium
9947Assume objects may be anywhere in the 32-bit address space (the compiler
9948will generate @code{seth/add3} instructions to load their addresses), and
9949assume all subroutines are reachable with the @code{bl} instruction.
9950
9951@item -mmodel=large
9952@opindex mmodel=large
9953Assume objects may be anywhere in the 32-bit address space (the compiler
9954will generate @code{seth/add3} instructions to load their addresses), and
9955assume subroutines may not be reachable with the @code{bl} instruction
9956(the compiler will generate the much slower @code{seth/add3/jl}
9957instruction sequence).
9958
9959@item -msdata=none
9960@opindex msdata=none
9961Disable use of the small data area. Variables will be put into
9962one of @samp{.data}, @samp{bss}, or @samp{.rodata} (unless the
9963@code{section} attribute has been specified).
9964This is the default.
9965
9966The small data area consists of sections @samp{.sdata} and @samp{.sbss}.
9967Objects may be explicitly put in the small data area with the
9968@code{section} attribute using one of these sections.
9969
9970@item -msdata=sdata
9971@opindex msdata=sdata
9972Put small global and static data in the small data area, but do not
9973generate special code to reference them.
9974
9975@item -msdata=use
9976@opindex msdata=use
9977Put small global and static data in the small data area, and generate
9978special instructions to reference them.
9979
9980@item -G @var{num}
9981@opindex G
9982@cindex smaller data references
9983Put global and static objects less than or equal to @var{num} bytes
9984into the small data or bss sections instead of the normal data or bss
9985sections. The default value of @var{num} is 8.
9986The @option{-msdata} option must be set to one of @samp{sdata} or @samp{use}
9987for this option to have any effect.
9988
9989All modules should be compiled with the same @option{-G @var{num}} value.
9990Compiling with different values of @var{num} may or may not work; if it
9991doesn't the linker will give an error message---incorrect code will not be
9992generated.
9993
9994@item -mdebug
9995@opindex mdebug
9996Makes the M32R specific code in the compiler display some statistics
9997that might help in debugging programs.
9998
9999@item -malign-loops
10000@opindex malign-loops
10001Align all loops to a 32-byte boundary.
10002
10003@item -mno-align-loops
10004@opindex mno-align-loops
10005Do not enforce a 32-byte alignment for loops. This is the default.
10006
10007@item -missue-rate=@var{number}
10008@opindex missue-rate=@var{number}
10009Issue @var{number} instructions per cycle. @var{number} can only be 1
10010or 2.
10011
10012@item -mbranch-cost=@var{number}
10013@opindex mbranch-cost=@var{number}
10014@var{number} can only be 1 or 2. If it is 1 then branches will be
10015preferred over conditional code, if it is 2, then the opposite will
10016apply.
10017
10018@item -mflush-trap=@var{number}
10019@opindex mflush-trap=@var{number}
10020Specifies the trap number to use to flush the cache. The default is
1002112. Valid numbers are between 0 and 15 inclusive.
10022
10023@item -mno-flush-trap
10024@opindex mno-flush-trap
10025Specifies that the cache cannot be flushed by using a trap.
10026
10027@item -mflush-func=@var{name}
10028@opindex mflush-func=@var{name}
10029Specifies the name of the operating system function to call to flush
10030the cache. The default is @emph{_flush_cache}, but a function call
10031will only be used if a trap is not available.
10032
10033@item -mno-flush-func
10034@opindex mno-flush-func
10035Indicates that there is no OS function for flushing the cache.
10036
10037@end table
10038
10039@node M680x0 Options
10040@subsection M680x0 Options
10041@cindex M680x0 options
10042
10043These are the @samp{-m} options defined for the 68000 series. The default
10044values for these options depends on which style of 68000 was selected when
10045the compiler was configured; the defaults for the most common choices are
10046given below.
10047
10048@table @gcctabopt
10049@item -m68000
10050@itemx -mc68000
10051@opindex m68000
10052@opindex mc68000
10053Generate output for a 68000. This is the default
10054when the compiler is configured for 68000-based systems.
10055
10056Use this option for microcontrollers with a 68000 or EC000 core,
10057including the 68008, 68302, 68306, 68307, 68322, 68328 and 68356.
10058
10059@item -m68020
10060@itemx -mc68020
10061@opindex m68020
10062@opindex mc68020
10063Generate output for a 68020. This is the default
10064when the compiler is configured for 68020-based systems.
10065
10066@item -m68881
10067@opindex m68881
10068Generate output containing 68881 instructions for floating point.
10069This is the default for most 68020 systems unless @option{--nfp} was
10070specified when the compiler was configured.
10071
10072@item -m68030
10073@opindex m68030
10074Generate output for a 68030. This is the default when the compiler is
10075configured for 68030-based systems.
10076
10077@item -m68040
10078@opindex m68040
10079Generate output for a 68040. This is the default when the compiler is
10080configured for 68040-based systems.
10081
10082This option inhibits the use of 68881/68882 instructions that have to be
10083emulated by software on the 68040. Use this option if your 68040 does not
10084have code to emulate those instructions.
10085
10086@item -m68060
10087@opindex m68060
10088Generate output for a 68060. This is the default when the compiler is
10089configured for 68060-based systems.
10090
10091This option inhibits the use of 68020 and 68881/68882 instructions that
10092have to be emulated by software on the 68060. Use this option if your 68060
10093does not have code to emulate those instructions.
10094
10095@item -mcpu32
10096@opindex mcpu32
10097Generate output for a CPU32. This is the default
10098when the compiler is configured for CPU32-based systems.
10099
10100Use this option for microcontrollers with a
10101CPU32 or CPU32+ core, including the 68330, 68331, 68332, 68333, 68334,
1010268336, 68340, 68341, 68349 and 68360.
10103
10104@item -m5200
10105@opindex m5200
10106Generate output for a 520X ``coldfire'' family cpu. This is the default
10107when the compiler is configured for 520X-based systems.
10108
10109Use this option for microcontroller with a 5200 core, including
10110the MCF5202, MCF5203, MCF5204 and MCF5202.
10111
10112@item -mcfv4e
10113@opindex mcfv4e
10114Generate output for a ColdFire V4e family cpu (e.g.@: 547x/548x).
10115This includes use of hardware floating point instructions.
10116
10117@item -m68020-40
10118@opindex m68020-40
10119Generate output for a 68040, without using any of the new instructions.
10120This results in code which can run relatively efficiently on either a
1012168020/68881 or a 68030 or a 68040. The generated code does use the
1012268881 instructions that are emulated on the 68040.
10123
10124@item -m68020-60
10125@opindex m68020-60
10126Generate output for a 68060, without using any of the new instructions.
10127This results in code which can run relatively efficiently on either a
1012868020/68881 or a 68030 or a 68040. The generated code does use the
1012968881 instructions that are emulated on the 68060.
10130
10131@item -msoft-float
10132@opindex msoft-float
10133Generate output containing library calls for floating point.
10134@strong{Warning:} the requisite libraries are not available for all m68k
10135targets. Normally the facilities of the machine's usual C compiler are
10136used, but this can't be done directly in cross-compilation. You must
10137make your own arrangements to provide suitable library functions for
10138cross-compilation. The embedded targets @samp{m68k-*-aout} and
10139@samp{m68k-*-coff} do provide software floating point support.
10140
10141@item -mshort
10142@opindex mshort
10143Consider type @code{int} to be 16 bits wide, like @code{short int}.
10144Additionally, parameters passed on the stack are also aligned to a
1014516-bit boundary even on targets whose API mandates promotion to 32-bit.
10146
10147@item -mnobitfield
10148@opindex mnobitfield
10149Do not use the bit-field instructions. The @option{-m68000}, @option{-mcpu32}
10150and @option{-m5200} options imply @w{@option{-mnobitfield}}.
10151
10152@item -mbitfield
10153@opindex mbitfield
10154Do use the bit-field instructions. The @option{-m68020} option implies
10155@option{-mbitfield}. This is the default if you use a configuration
10156designed for a 68020.
10157
10158@item -mrtd
10159@opindex mrtd
10160Use a different function-calling convention, in which functions
10161that take a fixed number of arguments return with the @code{rtd}
10162instruction, which pops their arguments while returning. This
10163saves one instruction in the caller since there is no need to pop
10164the arguments there.
10165
10166This calling convention is incompatible with the one normally
10167used on Unix, so you cannot use it if you need to call libraries
10168compiled with the Unix compiler.
10169
10170Also, you must provide function prototypes for all functions that
10171take variable numbers of arguments (including @code{printf});
10172otherwise incorrect code will be generated for calls to those
10173functions.
10174
10175In addition, seriously incorrect code will result if you call a
10176function with too many arguments. (Normally, extra arguments are
10177harmlessly ignored.)
10178
10179The @code{rtd} instruction is supported by the 68010, 68020, 68030,
1018068040, 68060 and CPU32 processors, but not by the 68000 or 5200.
10181
10182@item -malign-int
10183@itemx -mno-align-int
10184@opindex malign-int
10185@opindex mno-align-int
10186Control whether GCC aligns @code{int}, @code{long}, @code{long long},
10187@code{float}, @code{double}, and @code{long double} variables on a 32-bit
10188boundary (@option{-malign-int}) or a 16-bit boundary (@option{-mno-align-int}).
10189Aligning variables on 32-bit boundaries produces code that runs somewhat
10190faster on processors with 32-bit busses at the expense of more memory.
10191
10192@strong{Warning:} if you use the @option{-malign-int} switch, GCC will
10193align structures containing the above types differently than
10194most published application binary interface specifications for the m68k.
10195
10196@item -mpcrel
10197@opindex mpcrel
10198Use the pc-relative addressing mode of the 68000 directly, instead of
10199using a global offset table. At present, this option implies @option{-fpic},
10200allowing at most a 16-bit offset for pc-relative addressing. @option{-fPIC} is
10201not presently supported with @option{-mpcrel}, though this could be supported for
1020268020 and higher processors.
10203
10204@item -mno-strict-align
10205@itemx -mstrict-align
10206@opindex mno-strict-align
10207@opindex mstrict-align
10208Do not (do) assume that unaligned memory references will be handled by
10209the system.
10210
10211@item -msep-data
10212Generate code that allows the data segment to be located in a different
10213area of memory from the text segment. This allows for execute in place in
10214an environment without virtual memory management. This option implies
10215@option{-fPIC}.
10216
10217@item -mno-sep-data
10218Generate code that assumes that the data segment follows the text segment.
10219This is the default.
10220
10221@item -mid-shared-library
10222Generate code that supports shared libraries via the library ID method.
10223This allows for execute in place and shared libraries in an environment
10224without virtual memory management. This option implies @option{-fPIC}.
10225
10226@item -mno-id-shared-library
10227Generate code that doesn't assume ID based shared libraries are being used.
10228This is the default.
10229
10230@item -mshared-library-id=n
10231Specified the identification number of the ID based shared library being
10232compiled. Specifying a value of 0 will generate more compact code, specifying
10233other values will force the allocation of that number to the current
10234library but is no more space or time efficient than omitting this option.
10235
10236@end table
10237
10238@node M68hc1x Options
10239@subsection M68hc1x Options
10240@cindex M68hc1x options
10241
10242These are the @samp{-m} options defined for the 68hc11 and 68hc12
10243microcontrollers. The default values for these options depends on
10244which style of microcontroller was selected when the compiler was configured;
10245the defaults for the most common choices are given below.
10246
10247@table @gcctabopt
10248@item -m6811
10249@itemx -m68hc11
10250@opindex m6811
10251@opindex m68hc11
10252Generate output for a 68HC11. This is the default
10253when the compiler is configured for 68HC11-based systems.
10254
10255@item -m6812
10256@itemx -m68hc12
10257@opindex m6812
10258@opindex m68hc12
10259Generate output for a 68HC12. This is the default
10260when the compiler is configured for 68HC12-based systems.
10261
10262@item -m68S12
10263@itemx -m68hcs12
10264@opindex m68S12
10265@opindex m68hcs12
10266Generate output for a 68HCS12.
10267
10268@item -mauto-incdec
10269@opindex mauto-incdec
10270Enable the use of 68HC12 pre and post auto-increment and auto-decrement
10271addressing modes.
10272
10273@item -minmax
10274@itemx -nominmax
10275@opindex minmax
10276@opindex mnominmax
10277Enable the use of 68HC12 min and max instructions.
10278
10279@item -mlong-calls
10280@itemx -mno-long-calls
10281@opindex mlong-calls
10282@opindex mno-long-calls
10283Treat all calls as being far away (near). If calls are assumed to be
10284far away, the compiler will use the @code{call} instruction to
10285call a function and the @code{rtc} instruction for returning.
10286
10287@item -mshort
10288@opindex mshort
10289Consider type @code{int} to be 16 bits wide, like @code{short int}.
10290
10291@item -msoft-reg-count=@var{count}
10292@opindex msoft-reg-count
10293Specify the number of pseudo-soft registers which are used for the
10294code generation. The maximum number is 32. Using more pseudo-soft
10295register may or may not result in better code depending on the program.
10296The default is 4 for 68HC11 and 2 for 68HC12.
10297
10298@end table
10299
10300@node MCore Options
10301@subsection MCore Options
10302@cindex MCore options
10303
10304These are the @samp{-m} options defined for the Motorola M*Core
10305processors.
10306
10307@table @gcctabopt
10308
10309@item -mhardlit
10310@itemx -mno-hardlit
10311@opindex mhardlit
10312@opindex mno-hardlit
10313Inline constants into the code stream if it can be done in two
10314instructions or less.
10315
10316@item -mdiv
10317@itemx -mno-div
10318@opindex mdiv
10319@opindex mno-div
10320Use the divide instruction. (Enabled by default).
10321
10322@item -mrelax-immediate
10323@itemx -mno-relax-immediate
10324@opindex mrelax-immediate
10325@opindex mno-relax-immediate
10326Allow arbitrary sized immediates in bit operations.
10327
10328@item -mwide-bitfields
10329@itemx -mno-wide-bitfields
10330@opindex mwide-bitfields
10331@opindex mno-wide-bitfields
10332Always treat bit-fields as int-sized.
10333
10334@item -m4byte-functions
10335@itemx -mno-4byte-functions
10336@opindex m4byte-functions
10337@opindex mno-4byte-functions
10338Force all functions to be aligned to a four byte boundary.
10339
10340@item -mcallgraph-data
10341@itemx -mno-callgraph-data
10342@opindex mcallgraph-data
10343@opindex mno-callgraph-data
10344Emit callgraph information.
10345
10346@item -mslow-bytes
10347@itemx -mno-slow-bytes
10348@opindex mslow-bytes
10349@opindex mno-slow-bytes
10350Prefer word access when reading byte quantities.
10351
10352@item -mlittle-endian
10353@itemx -mbig-endian
10354@opindex mlittle-endian
10355@opindex mbig-endian
10356Generate code for a little endian target.
10357
10358@item -m210
10359@itemx -m340
10360@opindex m210
10361@opindex m340
10362Generate code for the 210 processor.
10363@end table
10364
10365@node MIPS Options
10366@subsection MIPS Options
10367@cindex MIPS options
10368
10369@table @gcctabopt
10370
10371@item -EB
10372@opindex EB
10373Generate big-endian code.
10374
10375@item -EL
10376@opindex EL
10377Generate little-endian code. This is the default for @samp{mips*el-*-*}
10378configurations.
10379
10380@item -march=@var{arch}
10381@opindex march
10382Generate code that will run on @var{arch}, which can be the name of a
10383generic MIPS ISA, or the name of a particular processor.
10384The ISA names are:
10385@samp{mips1}, @samp{mips2}, @samp{mips3}, @samp{mips4},
10386@samp{mips32}, @samp{mips32r2}, and @samp{mips64}.
10387The processor names are:
10388@samp{4kc}, @samp{4km}, @samp{4kp},
10389@samp{5kc}, @samp{5kf},
10390@samp{20kc},
10391@samp{24k}, @samp{24kc}, @samp{24kf}, @samp{24kx},
10392@samp{m4k},
10393@samp{orion},
10394@samp{r2000}, @samp{r3000}, @samp{r3900}, @samp{r4000}, @samp{r4400},
10395@samp{r4600}, @samp{r4650}, @samp{r6000}, @samp{r8000},
10396@samp{rm7000}, @samp{rm9000},
10397@samp{sb1},
10398@samp{sr71000},
10399@samp{vr4100}, @samp{vr4111}, @samp{vr4120}, @samp{vr4130}, @samp{vr4300},
10400@samp{vr5000}, @samp{vr5400} and @samp{vr5500}.
10401The special value @samp{from-abi} selects the
10402most compatible architecture for the selected ABI (that is,
10403@samp{mips1} for 32-bit ABIs and @samp{mips3} for 64-bit ABIs)@.
10404
10405In processor names, a final @samp{000} can be abbreviated as @samp{k}
10406(for example, @samp{-march=r2k}). Prefixes are optional, and
10407@samp{vr} may be written @samp{r}.
10408
10409GCC defines two macros based on the value of this option. The first
10410is @samp{_MIPS_ARCH}, which gives the name of target architecture, as
10411a string. The second has the form @samp{_MIPS_ARCH_@var{foo}},
10412where @var{foo} is the capitalized value of @samp{_MIPS_ARCH}@.
10413For example, @samp{-march=r2000} will set @samp{_MIPS_ARCH}
10414to @samp{"r2000"} and define the macro @samp{_MIPS_ARCH_R2000}.
10415
10416Note that the @samp{_MIPS_ARCH} macro uses the processor names given
10417above. In other words, it will have the full prefix and will not
10418abbreviate @samp{000} as @samp{k}. In the case of @samp{from-abi},
10419the macro names the resolved architecture (either @samp{"mips1"} or
10420@samp{"mips3"}). It names the default architecture when no
10421@option{-march} option is given.
10422
10423@item -mtune=@var{arch}
10424@opindex mtune
10425Optimize for @var{arch}. Among other things, this option controls
10426the way instructions are scheduled, and the perceived cost of arithmetic
10427operations. The list of @var{arch} values is the same as for
10428@option{-march}.
10429
10430When this option is not used, GCC will optimize for the processor
10431specified by @option{-march}. By using @option{-march} and
10432@option{-mtune} together, it is possible to generate code that will
10433run on a family of processors, but optimize the code for one
10434particular member of that family.
10435
10436@samp{-mtune} defines the macros @samp{_MIPS_TUNE} and
10437@samp{_MIPS_TUNE_@var{foo}}, which work in the same way as the
10438@samp{-march} ones described above.
10439
10440@item -mips1
10441@opindex mips1
10442Equivalent to @samp{-march=mips1}.
10443
10444@item -mips2
10445@opindex mips2
10446Equivalent to @samp{-march=mips2}.
10447
10448@item -mips3
10449@opindex mips3
10450Equivalent to @samp{-march=mips3}.
10451
10452@item -mips4
10453@opindex mips4
10454Equivalent to @samp{-march=mips4}.
10455
10456@item -mips32
10457@opindex mips32
10458Equivalent to @samp{-march=mips32}.
10459
10460@item -mips32r2
10461@opindex mips32r2
10462Equivalent to @samp{-march=mips32r2}.
10463
10464@item -mips64
10465@opindex mips64
10466Equivalent to @samp{-march=mips64}.
10467
10468@item -mips16
10469@itemx -mno-mips16
10470@opindex mips16
10471@opindex mno-mips16
10472Generate (do not generate) MIPS16 code. If GCC is targetting a
10473MIPS32 or MIPS64 architecture, it will make use of the MIPS16e ASE@.
10474
10475@item -mabi=32
10476@itemx -mabi=o64
10477@itemx -mabi=n32
10478@itemx -mabi=64
10479@itemx -mabi=eabi
10480@opindex mabi=32
10481@opindex mabi=o64
10482@opindex mabi=n32
10483@opindex mabi=64
10484@opindex mabi=eabi
10485Generate code for the given ABI@.
10486
10487Note that the EABI has a 32-bit and a 64-bit variant. GCC normally
10488generates 64-bit code when you select a 64-bit architecture, but you
10489can use @option{-mgp32} to get 32-bit code instead.
10490
10491For information about the O64 ABI, see
10492@w{@uref{http://gcc.gnu.org/projects/mipso64-abi.html}}.
10493
10494@item -mabicalls
10495@itemx -mno-abicalls
10496@opindex mabicalls
10497@opindex mno-abicalls
10498Generate (do not generate) code that is suitable for SVR4-style
10499dynamic objects. @option{-mabicalls} is the default for SVR4-based
10500systems.
10501
10502@item -mshared
10503@itemx -mno-shared
10504Generate (do not generate) code that is fully position-independent,
10505and that can therefore be linked into shared libraries. This option
10506only affects @option{-mabicalls}.
10507
10508All @option{-mabicalls} code has traditionally been position-independent,
10509regardless of options like @option{-fPIC} and @option{-fpic}. However,
10510as an extension, the GNU toolchain allows executables to use absolute
10511accesses for locally-binding symbols. It can also use shorter GP
10512initialization sequences and generate direct calls to locally-defined
10513functions. This mode is selected by @option{-mno-shared}.
10514
10515@option{-mno-shared} depends on binutils 2.16 or higher and generates
10516objects that can only be linked by the GNU linker. However, the option
10517does not affect the ABI of the final executable; it only affects the ABI
10518of relocatable objects. Using @option{-mno-shared} will generally make
10519executables both smaller and quicker.
10520
10521@option{-mshared} is the default.
10522
10523@item -mxgot
10524@itemx -mno-xgot
10525@opindex mxgot
10526@opindex mno-xgot
10527Lift (do not lift) the usual restrictions on the size of the global
10528offset table.
10529
10530GCC normally uses a single instruction to load values from the GOT@.
10531While this is relatively efficient, it will only work if the GOT
10532is smaller than about 64k. Anything larger will cause the linker
10533to report an error such as:
10534
10535@cindex relocation truncated to fit (MIPS)
10536@smallexample
10537relocation truncated to fit: R_MIPS_GOT16 foobar
10538@end smallexample
10539
10540If this happens, you should recompile your code with @option{-mxgot}.
10541It should then work with very large GOTs, although it will also be
10542less efficient, since it will take three instructions to fetch the
10543value of a global symbol.
10544
10545Note that some linkers can create multiple GOTs. If you have such a
10546linker, you should only need to use @option{-mxgot} when a single object
10547file accesses more than 64k's worth of GOT entries. Very few do.
10548
10549These options have no effect unless GCC is generating position
10550independent code.
10551
10552@item -mgp32
10553@opindex mgp32
10554Assume that general-purpose registers are 32 bits wide.
10555
10556@item -mgp64
10557@opindex mgp64
10558Assume that general-purpose registers are 64 bits wide.
10559
10560@item -mfp32
10561@opindex mfp32
10562Assume that floating-point registers are 32 bits wide.
10563
10564@item -mfp64
10565@opindex mfp64
10566Assume that floating-point registers are 64 bits wide.
10567
10568@item -mhard-float
10569@opindex mhard-float
10570Use floating-point coprocessor instructions.
10571
10572@item -msoft-float
10573@opindex msoft-float
10574Do not use floating-point coprocessor instructions. Implement
10575floating-point calculations using library calls instead.
10576
10577@item -msingle-float
10578@opindex msingle-float
10579Assume that the floating-point coprocessor only supports single-precision
10580operations.
10581
10582@itemx -mdouble-float
10583@opindex mdouble-float
10584Assume that the floating-point coprocessor supports double-precision
10585operations. This is the default.
10586
10587@itemx -mdsp
10588@itemx -mno-dsp
10589@opindex mdsp
10590@opindex mno-dsp
10591Use (do not use) the MIPS DSP ASE. @xref{MIPS DSP Built-in Functions}.
10592
10593@itemx -mpaired-single
10594@itemx -mno-paired-single
10595@opindex mpaired-single
10596@opindex mno-paired-single
10597Use (do not use) paired-single floating-point instructions.
10598@xref{MIPS Paired-Single Support}. This option can only be used
10599when generating 64-bit code and requires hardware floating-point
10600support to be enabled.
10601
10602@itemx -mips3d
10603@itemx -mno-mips3d
10604@opindex mips3d
10605@opindex mno-mips3d
10606Use (do not use) the MIPS-3D ASE@. @xref{MIPS-3D Built-in Functions}.
10607The option @option{-mips3d} implies @option{-mpaired-single}.
10608
10609@item -mlong64
10610@opindex mlong64
10611Force @code{long} types to be 64 bits wide. See @option{-mlong32} for
10612an explanation of the default and the way that the pointer size is
10613determined.
10614
10615@item -mlong32
10616@opindex mlong32
10617Force @code{long}, @code{int}, and pointer types to be 32 bits wide.
10618
10619The default size of @code{int}s, @code{long}s and pointers depends on
10620the ABI@. All the supported ABIs use 32-bit @code{int}s. The n64 ABI
10621uses 64-bit @code{long}s, as does the 64-bit EABI; the others use
1062232-bit @code{long}s. Pointers are the same size as @code{long}s,
10623or the same size as integer registers, whichever is smaller.
10624
10625@item -msym32
10626@itemx -mno-sym32
10627@opindex msym32
10628@opindex mno-sym32
10629Assume (do not assume) that all symbols have 32-bit values, regardless
10630of the selected ABI@. This option is useful in combination with
10631@option{-mabi=64} and @option{-mno-abicalls} because it allows GCC
10632to generate shorter and faster references to symbolic addresses.
10633
10634@item -G @var{num}
10635@opindex G
10636@cindex smaller data references (MIPS)
10637@cindex gp-relative references (MIPS)
10638Put global and static items less than or equal to @var{num} bytes into
10639the small data or bss section instead of the normal data or bss section.
10640This allows the data to be accessed using a single instruction.
10641
10642All modules should be compiled with the same @option{-G @var{num}}
10643value.
10644
10645@item -membedded-data
10646@itemx -mno-embedded-data
10647@opindex membedded-data
10648@opindex mno-embedded-data
10649Allocate variables to the read-only data section first if possible, then
10650next in the small data section if possible, otherwise in data. This gives
10651slightly slower code than the default, but reduces the amount of RAM required
10652when executing, and thus may be preferred for some embedded systems.
10653
10654@item -muninit-const-in-rodata
10655@itemx -mno-uninit-const-in-rodata
10656@opindex muninit-const-in-rodata
10657@opindex mno-uninit-const-in-rodata
10658Put uninitialized @code{const} variables in the read-only data section.
10659This option is only meaningful in conjunction with @option{-membedded-data}.
10660
10661@item -msplit-addresses
10662@itemx -mno-split-addresses
10663@opindex msplit-addresses
10664@opindex mno-split-addresses
10665Enable (disable) use of the @code{%hi()} and @code{%lo()} assembler
10666relocation operators. This option has been superseded by
10667@option{-mexplicit-relocs} but is retained for backwards compatibility.
10668
10669@item -mexplicit-relocs
10670@itemx -mno-explicit-relocs
10671@opindex mexplicit-relocs
10672@opindex mno-explicit-relocs
10673Use (do not use) assembler relocation operators when dealing with symbolic
10674addresses. The alternative, selected by @option{-mno-explicit-relocs},
10675is to use assembler macros instead.
10676
10677@option{-mexplicit-relocs} is the default if GCC was configured
10678to use an assembler that supports relocation operators.
10679
10680@item -mcheck-zero-division
10681@itemx -mno-check-zero-division
10682@opindex mcheck-zero-division
10683@opindex mno-check-zero-division
10684Trap (do not trap) on integer division by zero. The default is
10685@option{-mcheck-zero-division}.
10686
10687@item -mdivide-traps
10688@itemx -mdivide-breaks
10689@opindex mdivide-traps
10690@opindex mdivide-breaks
10691MIPS systems check for division by zero by generating either a
10692conditional trap or a break instruction. Using traps results in
10693smaller code, but is only supported on MIPS II and later. Also, some
10694versions of the Linux kernel have a bug that prevents trap from
10695generating the proper signal (@code{SIGFPE}). Use @option{-mdivide-traps} to
10696allow conditional traps on architectures that support them and
10697@option{-mdivide-breaks} to force the use of breaks.
10698
10699The default is usually @option{-mdivide-traps}, but this can be
10700overridden at configure time using @option{--with-divide=breaks}.
10701Divide-by-zero checks can be completely disabled using
10702@option{-mno-check-zero-division}.
10703
10704@item -mmemcpy
10705@itemx -mno-memcpy
10706@opindex mmemcpy
10707@opindex mno-memcpy
10708Force (do not force) the use of @code{memcpy()} for non-trivial block
10709moves. The default is @option{-mno-memcpy}, which allows GCC to inline
10710most constant-sized copies.
10711
10712@item -mlong-calls
10713@itemx -mno-long-calls
10714@opindex mlong-calls
10715@opindex mno-long-calls
10716Disable (do not disable) use of the @code{jal} instruction. Calling
10717functions using @code{jal} is more efficient but requires the caller
10718and callee to be in the same 256 megabyte segment.
10719
10720This option has no effect on abicalls code. The default is
10721@option{-mno-long-calls}.
10722
10723@item -mmad
10724@itemx -mno-mad
10725@opindex mmad
10726@opindex mno-mad
10727Enable (disable) use of the @code{mad}, @code{madu} and @code{mul}
10728instructions, as provided by the R4650 ISA@.
10729
10730@item -mfused-madd
10731@itemx -mno-fused-madd
10732@opindex mfused-madd
10733@opindex mno-fused-madd
10734Enable (disable) use of the floating point multiply-accumulate
10735instructions, when they are available. The default is
10736@option{-mfused-madd}.
10737
10738When multiply-accumulate instructions are used, the intermediate
10739product is calculated to infinite precision and is not subject to
10740the FCSR Flush to Zero bit. This may be undesirable in some
10741circumstances.
10742
10743@item -nocpp
10744@opindex nocpp
10745Tell the MIPS assembler to not run its preprocessor over user
10746assembler files (with a @samp{.s} suffix) when assembling them.
10747
10748@item -mfix-r4000
10749@itemx -mno-fix-r4000
10750@opindex mfix-r4000
10751@opindex mno-fix-r4000
10752Work around certain R4000 CPU errata:
10753@itemize @minus
10754@item
10755A double-word or a variable shift may give an incorrect result if executed
10756immediately after starting an integer division.
10757@item
10758A double-word or a variable shift may give an incorrect result if executed
10759while an integer multiplication is in progress.
10760@item
10761An integer division may give an incorrect result if started in a delay slot
10762of a taken branch or a jump.
10763@end itemize
10764
10765@item -mfix-r4400
10766@itemx -mno-fix-r4400
10767@opindex mfix-r4400
10768@opindex mno-fix-r4400
10769Work around certain R4400 CPU errata:
10770@itemize @minus
10771@item
10772A double-word or a variable shift may give an incorrect result if executed
10773immediately after starting an integer division.
10774@end itemize
10775
10776@item -mfix-vr4120
10777@itemx -mno-fix-vr4120
10778@opindex mfix-vr4120
10779Work around certain VR4120 errata:
10780@itemize @minus
10781@item
10782@code{dmultu} does not always produce the correct result.
10783@item
10784@code{div} and @code{ddiv} do not always produce the correct result if one
10785of the operands is negative.
10786@end itemize
10787The workarounds for the division errata rely on special functions in
10788@file{libgcc.a}. At present, these functions are only provided by
10789the @code{mips64vr*-elf} configurations.
10790
10791Other VR4120 errata require a nop to be inserted between certain pairs of
10792instructions. These errata are handled by the assembler, not by GCC itself.
10793
10794@item -mfix-vr4130
10795@opindex mfix-vr4130
10796Work around the VR4130 @code{mflo}/@code{mfhi} errata. The
10797workarounds are implemented by the assembler rather than by GCC,
10798although GCC will avoid using @code{mflo} and @code{mfhi} if the
10799VR4130 @code{macc}, @code{macchi}, @code{dmacc} and @code{dmacchi}
10800instructions are available instead.
10801
10802@item -mfix-sb1
10803@itemx -mno-fix-sb1
10804@opindex mfix-sb1
10805Work around certain SB-1 CPU core errata.
10806(This flag currently works around the SB-1 revision 2
10807``F1'' and ``F2'' floating point errata.)
10808
10809@item -mflush-func=@var{func}
10810@itemx -mno-flush-func
10811@opindex mflush-func
10812Specifies the function to call to flush the I and D caches, or to not
10813call any such function. If called, the function must take the same
10814arguments as the common @code{_flush_func()}, that is, the address of the
10815memory range for which the cache is being flushed, the size of the
10816memory range, and the number 3 (to flush both caches). The default
10817depends on the target GCC was configured for, but commonly is either
10818@samp{_flush_func} or @samp{__cpu_flush}.
10819
10820@item -mbranch-likely
10821@itemx -mno-branch-likely
10822@opindex mbranch-likely
10823@opindex mno-branch-likely
10824Enable or disable use of Branch Likely instructions, regardless of the
10825default for the selected architecture. By default, Branch Likely
10826instructions may be generated if they are supported by the selected
10827architecture. An exception is for the MIPS32 and MIPS64 architectures
10828and processors which implement those architectures; for those, Branch
10829Likely instructions will not be generated by default because the MIPS32
10830and MIPS64 architectures specifically deprecate their use.
10831
10832@item -mfp-exceptions
10833@itemx -mno-fp-exceptions
10834@opindex mfp-exceptions
10835Specifies whether FP exceptions are enabled. This affects how we schedule
10836FP instructions for some processors. The default is that FP exceptions are
10837enabled.
10838
10839For instance, on the SB-1, if FP exceptions are disabled, and we are emitting
1084064-bit code, then we can use both FP pipes. Otherwise, we can only use one
10841FP pipe.
10842
10843@item -mvr4130-align
10844@itemx -mno-vr4130-align
10845@opindex mvr4130-align
10846The VR4130 pipeline is two-way superscalar, but can only issue two
10847instructions together if the first one is 8-byte aligned. When this
10848option is enabled, GCC will align pairs of instructions that it
10849thinks should execute in parallel.
10850
10851This option only has an effect when optimizing for the VR4130.
10852It normally makes code faster, but at the expense of making it bigger.
10853It is enabled by default at optimization level @option{-O3}.
10854@end table
10855
10856@node MMIX Options
10857@subsection MMIX Options
10858@cindex MMIX Options
10859
10860These options are defined for the MMIX:
10861
10862@table @gcctabopt
10863@item -mlibfuncs
10864@itemx -mno-libfuncs
10865@opindex mlibfuncs
10866@opindex mno-libfuncs
10867Specify that intrinsic library functions are being compiled, passing all
10868values in registers, no matter the size.
10869
10870@item -mepsilon
10871@itemx -mno-epsilon
10872@opindex mepsilon
10873@opindex mno-epsilon
10874Generate floating-point comparison instructions that compare with respect
10875to the @code{rE} epsilon register.
10876
10877@item -mabi=mmixware
10878@itemx -mabi=gnu
10879@opindex mabi-mmixware
10880@opindex mabi=gnu
10881Generate code that passes function parameters and return values that (in
10882the called function) are seen as registers @code{$0} and up, as opposed to
10883the GNU ABI which uses global registers @code{$231} and up.
10884
10885@item -mzero-extend
10886@itemx -mno-zero-extend
10887@opindex mzero-extend
10888@opindex mno-zero-extend
10889When reading data from memory in sizes shorter than 64 bits, use (do not
10890use) zero-extending load instructions by default, rather than
10891sign-extending ones.
10892
10893@item -mknuthdiv
10894@itemx -mno-knuthdiv
10895@opindex mknuthdiv
10896@opindex mno-knuthdiv
10897Make the result of a division yielding a remainder have the same sign as
10898the divisor. With the default, @option{-mno-knuthdiv}, the sign of the
10899remainder follows the sign of the dividend. Both methods are
10900arithmetically valid, the latter being almost exclusively used.
10901
10902@item -mtoplevel-symbols
10903@itemx -mno-toplevel-symbols
10904@opindex mtoplevel-symbols
10905@opindex mno-toplevel-symbols
10906Prepend (do not prepend) a @samp{:} to all global symbols, so the assembly
10907code can be used with the @code{PREFIX} assembly directive.
10908
10909@item -melf
10910@opindex melf
10911Generate an executable in the ELF format, rather than the default
10912@samp{mmo} format used by the @command{mmix} simulator.
10913
10914@item -mbranch-predict
10915@itemx -mno-branch-predict
10916@opindex mbranch-predict
10917@opindex mno-branch-predict
10918Use (do not use) the probable-branch instructions, when static branch
10919prediction indicates a probable branch.
10920
10921@item -mbase-addresses
10922@itemx -mno-base-addresses
10923@opindex mbase-addresses
10924@opindex mno-base-addresses
10925Generate (do not generate) code that uses @emph{base addresses}. Using a
10926base address automatically generates a request (handled by the assembler
10927and the linker) for a constant to be set up in a global register. The
10928register is used for one or more base address requests within the range 0
10929to 255 from the value held in the register. The generally leads to short
10930and fast code, but the number of different data items that can be
10931addressed is limited. This means that a program that uses lots of static
10932data may require @option{-mno-base-addresses}.
10933
10934@item -msingle-exit
10935@itemx -mno-single-exit
10936@opindex msingle-exit
10937@opindex mno-single-exit
10938Force (do not force) generated code to have a single exit point in each
10939function.
10940@end table
10941
10942@node MN10300 Options
10943@subsection MN10300 Options
10944@cindex MN10300 options
10945
10946These @option{-m} options are defined for Matsushita MN10300 architectures:
10947
10948@table @gcctabopt
10949@item -mmult-bug
10950@opindex mmult-bug
10951Generate code to avoid bugs in the multiply instructions for the MN10300
10952processors. This is the default.
10953
10954@item -mno-mult-bug
10955@opindex mno-mult-bug
10956Do not generate code to avoid bugs in the multiply instructions for the
10957MN10300 processors.
10958
10959@item -mam33
10960@opindex mam33
10961Generate code which uses features specific to the AM33 processor.
10962
10963@item -mno-am33
10964@opindex mno-am33
10965Do not generate code which uses features specific to the AM33 processor. This
10966is the default.
10967
10968@item -mreturn-pointer-on-d0
10969@opindex mreturn-pointer-on-d0
10970When generating a function which returns a pointer, return the pointer
10971in both @code{a0} and @code{d0}. Otherwise, the pointer is returned
10972only in a0, and attempts to call such functions without a prototype
10973would result in errors. Note that this option is on by default; use
10974@option{-mno-return-pointer-on-d0} to disable it.
10975
10976@item -mno-crt0
10977@opindex mno-crt0
10978Do not link in the C run-time initialization object file.
10979
10980@item -mrelax
10981@opindex mrelax
10982Indicate to the linker that it should perform a relaxation optimization pass
10983to shorten branches, calls and absolute memory addresses. This option only
10984has an effect when used on the command line for the final link step.
10985
10986This option makes symbolic debugging impossible.
10987@end table
10988
10989@node MT Options
10990@subsection MT Options
10991@cindex MT options
10992
10993These @option{-m} options are defined for Morpho MT architectures:
10994
10995@table @gcctabopt
10996
10997@item -march=@var{cpu-type}
10998@opindex march
10999Generate code that will run on @var{cpu-type}, which is the name of a system
11000representing a certain processor type. Possible values for
11001@var{cpu-type} are @samp{ms1-64-001}, @samp{ms1-16-002},
11002@samp{ms1-16-003} and @samp{ms2}.
11003
11004When this option is not used, the default is @option{-march=ms1-16-002}.
11005
11006@item -mbacc
11007@opindex mbacc
11008Use byte loads and stores when generating code.
11009
11010@item -mno-bacc
11011@opindex mno-bacc
11012Do not use byte loads and stores when generating code.
11013
11014@item -msim
11015@opindex msim
11016Use simulator runtime
11017
11018@item -mno-crt0
11019@opindex mno-crt0
11020Do not link in the C run-time initialization object file
11021@file{crti.o}. Other run-time initialization and termination files
11022such as @file{startup.o} and @file{exit.o} are still included on the
11023linker command line.
11024
11025@end table
11026
11027@node PDP-11 Options
11028@subsection PDP-11 Options
11029@cindex PDP-11 Options
11030
11031These options are defined for the PDP-11:
11032
11033@table @gcctabopt
11034@item -mfpu
11035@opindex mfpu
11036Use hardware FPP floating point. This is the default. (FIS floating
11037point on the PDP-11/40 is not supported.)
11038
11039@item -msoft-float
11040@opindex msoft-float
11041Do not use hardware floating point.
11042
11043@item -mac0
11044@opindex mac0
11045Return floating-point results in ac0 (fr0 in Unix assembler syntax).
11046
11047@item -mno-ac0
11048@opindex mno-ac0
11049Return floating-point results in memory. This is the default.
11050
11051@item -m40
11052@opindex m40
11053Generate code for a PDP-11/40.
11054
11055@item -m45
11056@opindex m45
11057Generate code for a PDP-11/45. This is the default.
11058
11059@item -m10
11060@opindex m10
11061Generate code for a PDP-11/10.
11062
11063@item -mbcopy-builtin
11064@opindex bcopy-builtin
11065Use inline @code{movmemhi} patterns for copying memory. This is the
11066default.
11067
11068@item -mbcopy
11069@opindex mbcopy
11070Do not use inline @code{movmemhi} patterns for copying memory.
11071
11072@item -mint16
11073@itemx -mno-int32
11074@opindex mint16
11075@opindex mno-int32
11076Use 16-bit @code{int}. This is the default.
11077
11078@item -mint32
11079@itemx -mno-int16
11080@opindex mint32
11081@opindex mno-int16
11082Use 32-bit @code{int}.
11083
11084@item -mfloat64
11085@itemx -mno-float32
11086@opindex mfloat64
11087@opindex mno-float32
11088Use 64-bit @code{float}. This is the default.
11089
11090@item -mfloat32
11091@itemx -mno-float64
11092@opindex mfloat32
11093@opindex mno-float64
11094Use 32-bit @code{float}.
11095
11096@item -mabshi
11097@opindex mabshi
11098Use @code{abshi2} pattern. This is the default.
11099
11100@item -mno-abshi
11101@opindex mno-abshi
11102Do not use @code{abshi2} pattern.
11103
11104@item -mbranch-expensive
11105@opindex mbranch-expensive
11106Pretend that branches are expensive. This is for experimenting with
11107code generation only.
11108
11109@item -mbranch-cheap
11110@opindex mbranch-cheap
11111Do not pretend that branches are expensive. This is the default.
11112
11113@item -msplit
11114@opindex msplit
11115Generate code for a system with split I&D@.
11116
11117@item -mno-split
11118@opindex mno-split
11119Generate code for a system without split I&D@. This is the default.
11120
11121@item -munix-asm
11122@opindex munix-asm
11123Use Unix assembler syntax. This is the default when configured for
11124@samp{pdp11-*-bsd}.
11125
11126@item -mdec-asm
11127@opindex mdec-asm
11128Use DEC assembler syntax. This is the default when configured for any
11129PDP-11 target other than @samp{pdp11-*-bsd}.
11130@end table
11131
11132@node PowerPC Options
11133@subsection PowerPC Options
11134@cindex PowerPC options
11135
11136These are listed under @xref{RS/6000 and PowerPC Options}.
11137
11138@node RS/6000 and PowerPC Options
11139@subsection IBM RS/6000 and PowerPC Options
11140@cindex RS/6000 and PowerPC Options
11141@cindex IBM RS/6000 and PowerPC Options
11142
11143These @samp{-m} options are defined for the IBM RS/6000 and PowerPC:
11144@table @gcctabopt
11145@item -mpower
11146@itemx -mno-power
11147@itemx -mpower2
11148@itemx -mno-power2
11149@itemx -mpowerpc
11150@itemx -mno-powerpc
11151@itemx -mpowerpc-gpopt
11152@itemx -mno-powerpc-gpopt
11153@itemx -mpowerpc-gfxopt
11154@itemx -mno-powerpc-gfxopt
11155@itemx -mpowerpc64
11156@itemx -mno-powerpc64
11157@itemx -mmfcrf
11158@itemx -mno-mfcrf
11159@itemx -mpopcntb
11160@itemx -mno-popcntb
11161@itemx -mfprnd
11162@itemx -mno-fprnd
11163@opindex mpower
11164@opindex mno-power
11165@opindex mpower2
11166@opindex mno-power2
11167@opindex mpowerpc
11168@opindex mno-powerpc
11169@opindex mpowerpc-gpopt
11170@opindex mno-powerpc-gpopt
11171@opindex mpowerpc-gfxopt
11172@opindex mno-powerpc-gfxopt
11173@opindex mpowerpc64
11174@opindex mno-powerpc64
11175@opindex mmfcrf
11176@opindex mno-mfcrf
11177@opindex mpopcntb
11178@opindex mno-popcntb
11179@opindex mfprnd
11180@opindex mno-fprnd
11181GCC supports two related instruction set architectures for the
11182RS/6000 and PowerPC@. The @dfn{POWER} instruction set are those
11183instructions supported by the @samp{rios} chip set used in the original
11184RS/6000 systems and the @dfn{PowerPC} instruction set is the
11185architecture of the Freescale MPC5xx, MPC6xx, MPC8xx microprocessors, and
11186the IBM 4xx, 6xx, and follow-on microprocessors.
11187
11188Neither architecture is a subset of the other. However there is a
11189large common subset of instructions supported by both. An MQ
11190register is included in processors supporting the POWER architecture.
11191
11192You use these options to specify which instructions are available on the
11193processor you are using. The default value of these options is
11194determined when configuring GCC@. Specifying the
11195@option{-mcpu=@var{cpu_type}} overrides the specification of these
11196options. We recommend you use the @option{-mcpu=@var{cpu_type}} option
11197rather than the options listed above.
11198
11199The @option{-mpower} option allows GCC to generate instructions that
11200are found only in the POWER architecture and to use the MQ register.
11201Specifying @option{-mpower2} implies @option{-power} and also allows GCC
11202to generate instructions that are present in the POWER2 architecture but
11203not the original POWER architecture.
11204
11205The @option{-mpowerpc} option allows GCC to generate instructions that
11206are found only in the 32-bit subset of the PowerPC architecture.
11207Specifying @option{-mpowerpc-gpopt} implies @option{-mpowerpc} and also allows
11208GCC to use the optional PowerPC architecture instructions in the
11209General Purpose group, including floating-point square root. Specifying
11210@option{-mpowerpc-gfxopt} implies @option{-mpowerpc} and also allows GCC to
11211use the optional PowerPC architecture instructions in the Graphics
11212group, including floating-point select.
11213
11214The @option{-mmfcrf} option allows GCC to generate the move from
11215condition register field instruction implemented on the POWER4
11216processor and other processors that support the PowerPC V2.01
11217architecture.
11218The @option{-mpopcntb} option allows GCC to generate the popcount and
11219double precision FP reciprocal estimate instruction implemented on the
11220POWER5 processor and other processors that support the PowerPC V2.02
11221architecture.
11222The @option{-mfprnd} option allows GCC to generate the FP round to
11223integer instructions implemented on the POWER5+ processor and other
11224processors that support the PowerPC V2.03 architecture.
11225
11226The @option{-mpowerpc64} option allows GCC to generate the additional
1122764-bit instructions that are found in the full PowerPC64 architecture
11228and to treat GPRs as 64-bit, doubleword quantities. GCC defaults to
11229@option{-mno-powerpc64}.
11230
11231If you specify both @option{-mno-power} and @option{-mno-powerpc}, GCC
11232will use only the instructions in the common subset of both
11233architectures plus some special AIX common-mode calls, and will not use
11234the MQ register. Specifying both @option{-mpower} and @option{-mpowerpc}
11235permits GCC to use any instruction from either architecture and to
11236allow use of the MQ register; specify this for the Motorola MPC601.
11237
11238@item -mnew-mnemonics
11239@itemx -mold-mnemonics
11240@opindex mnew-mnemonics
11241@opindex mold-mnemonics
11242Select which mnemonics to use in the generated assembler code. With
11243@option{-mnew-mnemonics}, GCC uses the assembler mnemonics defined for
11244the PowerPC architecture. With @option{-mold-mnemonics} it uses the
11245assembler mnemonics defined for the POWER architecture. Instructions
11246defined in only one architecture have only one mnemonic; GCC uses that
11247mnemonic irrespective of which of these options is specified.
11248
11249GCC defaults to the mnemonics appropriate for the architecture in
11250use. Specifying @option{-mcpu=@var{cpu_type}} sometimes overrides the
11251value of these option. Unless you are building a cross-compiler, you
11252should normally not specify either @option{-mnew-mnemonics} or
11253@option{-mold-mnemonics}, but should instead accept the default.
11254
11255@item -mcpu=@var{cpu_type}
11256@opindex mcpu
11257Set architecture type, register usage, choice of mnemonics, and
11258instruction scheduling parameters for machine type @var{cpu_type}.
11259Supported values for @var{cpu_type} are @samp{401}, @samp{403},
11260@samp{405}, @samp{405fp}, @samp{440}, @samp{440fp}, @samp{505},
11261@samp{601}, @samp{602}, @samp{603}, @samp{603e}, @samp{604},
11262@samp{604e}, @samp{620}, @samp{630}, @samp{740}, @samp{7400},
11263@samp{7450}, @samp{750}, @samp{801}, @samp{821}, @samp{823},
11264@samp{860}, @samp{970}, @samp{8540}, @samp{ec603e}, @samp{G3},
11265@samp{G4}, @samp{G5}, @samp{power}, @samp{power2}, @samp{power3},
11266@samp{power4}, @samp{power5}, @samp{power5+}, @samp{power6},
11267@samp{common}, @samp{powerpc}, @samp{powerpc64},
11268@samp{rios}, @samp{rios1}, @samp{rios2}, @samp{rsc}, and @samp{rs64}.
11269
11270@option{-mcpu=common} selects a completely generic processor. Code
11271generated under this option will run on any POWER or PowerPC processor.
11272GCC will use only the instructions in the common subset of both
11273architectures, and will not use the MQ register. GCC assumes a generic
11274processor model for scheduling purposes.
11275
11276@option{-mcpu=power}, @option{-mcpu=power2}, @option{-mcpu=powerpc}, and
11277@option{-mcpu=powerpc64} specify generic POWER, POWER2, pure 32-bit
11278PowerPC (i.e., not MPC601), and 64-bit PowerPC architecture machine
11279types, with an appropriate, generic processor model assumed for
11280scheduling purposes.
11281
11282The other options specify a specific processor. Code generated under
11283those options will run best on that processor, and may not run at all on
11284others.
11285
11286The @option{-mcpu} options automatically enable or disable the
11287following options: @option{-maltivec}, @option{-mfprnd},
11288@option{-mhard-float}, @option{-mmfcrf}, @option{-mmultiple},
11289@option{-mnew-mnemonics}, @option{-mpopcntb}, @option{-mpower},
11290@option{-mpower2}, @option{-mpowerpc64}, @option{-mpowerpc-gpopt},
11291@option{-mpowerpc-gfxopt}, @option{-mstring}, @option{-mmulhw}, @option{-mdlmzb}.
11292The particular options
11293set for any particular CPU will vary between compiler versions,
11294depending on what setting seems to produce optimal code for that CPU;
11295it doesn't necessarily reflect the actual hardware's capabilities. If
11296you wish to set an individual option to a particular value, you may
11297specify it after the @option{-mcpu} option, like @samp{-mcpu=970
11298-mno-altivec}.
11299
11300On AIX, the @option{-maltivec} and @option{-mpowerpc64} options are
11301not enabled or disabled by the @option{-mcpu} option at present because
11302AIX does not have full support for these options. You may still
11303enable or disable them individually if you're sure it'll work in your
11304environment.
11305
11306@item -mtune=@var{cpu_type}
11307@opindex mtune
11308Set the instruction scheduling parameters for machine type
11309@var{cpu_type}, but do not set the architecture type, register usage, or
11310choice of mnemonics, as @option{-mcpu=@var{cpu_type}} would. The same
11311values for @var{cpu_type} are used for @option{-mtune} as for
11312@option{-mcpu}. If both are specified, the code generated will use the
11313architecture, registers, and mnemonics set by @option{-mcpu}, but the
11314scheduling parameters set by @option{-mtune}.
11315
11316@item -mswdiv
11317@itemx -mno-swdiv
11318@opindex mswdiv
11319@opindex mno-swdiv
11320Generate code to compute division as reciprocal estimate and iterative
11321refinement, creating opportunities for increased throughput. This
11322feature requires: optional PowerPC Graphics instruction set for single
11323precision and FRE instruction for double precision, assuming divides
11324cannot generate user-visible traps, and the domain values not include
11325Infinities, denormals or zero denominator.
11326
11327@item -maltivec
11328@itemx -mno-altivec
11329@opindex maltivec
11330@opindex mno-altivec
11331Generate code that uses (does not use) AltiVec instructions, and also
11332enable the use of built-in functions that allow more direct access to
11333the AltiVec instruction set. You may also need to set
11334@option{-mabi=altivec} to adjust the current ABI with AltiVec ABI
11335enhancements.
11336
11337@item -mvrsave
11338@item -mno-vrsave
11339@opindex mvrsave
11340@opindex mno-vrsave
11341Generate VRSAVE instructions when generating AltiVec code.
11342
11343@item -msecure-plt
11344@opindex msecure-plt
11345Generate code that allows ld and ld.so to build executables and shared
11346libraries with non-exec .plt and .got sections. This is a PowerPC
1134732-bit SYSV ABI option.
11348
11349@item -mbss-plt
11350@opindex mbss-plt
11351Generate code that uses a BSS .plt section that ld.so fills in, and
11352requires .plt and .got sections that are both writable and executable.
11353This is a PowerPC 32-bit SYSV ABI option.
11354
11355@item -misel
11356@itemx -mno-isel
11357@opindex misel
11358@opindex mno-isel
11359This switch enables or disables the generation of ISEL instructions.
11360
11361@item -misel=@var{yes/no}
11362This switch has been deprecated. Use @option{-misel} and
11363@option{-mno-isel} instead.
11364
11365@item -mspe
11366@itemx -mno-spe
11367@opindex mspe
11368@opindex mno-spe
11369This switch enables or disables the generation of SPE simd
11370instructions.
11371
11372@item -mspe=@var{yes/no}
11373This option has been deprecated. Use @option{-mspe} and
11374@option{-mno-spe} instead.
11375
11376@item -mfloat-gprs=@var{yes/single/double/no}
11377@itemx -mfloat-gprs
11378@opindex mfloat-gprs
11379This switch enables or disables the generation of floating point
11380operations on the general purpose registers for architectures that
11381support it.
11382
11383The argument @var{yes} or @var{single} enables the use of
11384single-precision floating point operations.
11385
11386The argument @var{double} enables the use of single and
11387double-precision floating point operations.
11388
11389The argument @var{no} disables floating point operations on the
11390general purpose registers.
11391
11392This option is currently only available on the MPC854x.
11393
11394@item -m32
11395@itemx -m64
11396@opindex m32
11397@opindex m64
11398Generate code for 32-bit or 64-bit environments of Darwin and SVR4
11399targets (including GNU/Linux). The 32-bit environment sets int, long
11400and pointer to 32 bits and generates code that runs on any PowerPC
11401variant. The 64-bit environment sets int to 32 bits and long and
11402pointer to 64 bits, and generates code for PowerPC64, as for
11403@option{-mpowerpc64}.
11404
11405@item -mfull-toc
11406@itemx -mno-fp-in-toc
11407@itemx -mno-sum-in-toc
11408@itemx -mminimal-toc
11409@opindex mfull-toc
11410@opindex mno-fp-in-toc
11411@opindex mno-sum-in-toc
11412@opindex mminimal-toc
11413Modify generation of the TOC (Table Of Contents), which is created for
11414every executable file. The @option{-mfull-toc} option is selected by
11415default. In that case, GCC will allocate at least one TOC entry for
11416each unique non-automatic variable reference in your program. GCC
11417will also place floating-point constants in the TOC@. However, only
1141816,384 entries are available in the TOC@.
11419
11420If you receive a linker error message that saying you have overflowed
11421the available TOC space, you can reduce the amount of TOC space used
11422with the @option{-mno-fp-in-toc} and @option{-mno-sum-in-toc} options.
11423@option{-mno-fp-in-toc} prevents GCC from putting floating-point
11424constants in the TOC and @option{-mno-sum-in-toc} forces GCC to
11425generate code to calculate the sum of an address and a constant at
11426run-time instead of putting that sum into the TOC@. You may specify one
11427or both of these options. Each causes GCC to produce very slightly
11428slower and larger code at the expense of conserving TOC space.
11429
11430If you still run out of space in the TOC even when you specify both of
11431these options, specify @option{-mminimal-toc} instead. This option causes
11432GCC to make only one TOC entry for every file. When you specify this
11433option, GCC will produce code that is slower and larger but which
11434uses extremely little TOC space. You may wish to use this option
11435only on files that contain less frequently executed code.
11436
11437@item -maix64
11438@itemx -maix32
11439@opindex maix64
11440@opindex maix32
11441Enable 64-bit AIX ABI and calling convention: 64-bit pointers, 64-bit
11442@code{long} type, and the infrastructure needed to support them.
11443Specifying @option{-maix64} implies @option{-mpowerpc64} and
11444@option{-mpowerpc}, while @option{-maix32} disables the 64-bit ABI and
11445implies @option{-mno-powerpc64}. GCC defaults to @option{-maix32}.
11446
11447@item -mxl-compat
11448@itemx -mno-xl-compat
11449@opindex mxl-compat
11450@opindex mno-xl-compat
11451Produce code that conforms more closely to IBM XL compiler semantics
11452when using AIX-compatible ABI. Pass floating-point arguments to
11453prototyped functions beyond the register save area (RSA) on the stack
11454in addition to argument FPRs. Do not assume that most significant
11455double in 128-bit long double value is properly rounded when comparing
11456values and converting to double. Use XL symbol names for long double
11457support routines.
11458
11459The AIX calling convention was extended but not initially documented to
11460handle an obscure K&R C case of calling a function that takes the
11461address of its arguments with fewer arguments than declared. IBM XL
11462compilers access floating point arguments which do not fit in the
11463RSA from the stack when a subroutine is compiled without
11464optimization. Because always storing floating-point arguments on the
11465stack is inefficient and rarely needed, this option is not enabled by
11466default and only is necessary when calling subroutines compiled by IBM
11467XL compilers without optimization.
11468
11469@item -mpe
11470@opindex mpe
11471Support @dfn{IBM RS/6000 SP} @dfn{Parallel Environment} (PE)@. Link an
11472application written to use message passing with special startup code to
11473enable the application to run. The system must have PE installed in the
11474standard location (@file{/usr/lpp/ppe.poe/}), or the @file{specs} file
11475must be overridden with the @option{-specs=} option to specify the
11476appropriate directory location. The Parallel Environment does not
11477support threads, so the @option{-mpe} option and the @option{-pthread}
11478option are incompatible.
11479
11480@item -malign-natural
11481@itemx -malign-power
11482@opindex malign-natural
11483@opindex malign-power
11484On AIX, 32-bit Darwin, and 64-bit PowerPC GNU/Linux, the option
11485@option{-malign-natural} overrides the ABI-defined alignment of larger
11486types, such as floating-point doubles, on their natural size-based boundary.
11487The option @option{-malign-power} instructs GCC to follow the ABI-specified
11488alignment rules. GCC defaults to the standard alignment defined in the ABI@.
11489
11490On 64-bit Darwin, natural alignment is the default, and @option{-malign-power}
11491is not supported.
11492
11493@item -msoft-float
11494@itemx -mhard-float
11495@opindex msoft-float
11496@opindex mhard-float
11497Generate code that does not use (uses) the floating-point register set.
11498Software floating point emulation is provided if you use the
11499@option{-msoft-float} option, and pass the option to GCC when linking.
11500
11501@item -mmultiple
11502@itemx -mno-multiple
11503@opindex mmultiple
11504@opindex mno-multiple
11505Generate code that uses (does not use) the load multiple word
11506instructions and the store multiple word instructions. These
11507instructions are generated by default on POWER systems, and not
11508generated on PowerPC systems. Do not use @option{-mmultiple} on little
11509endian PowerPC systems, since those instructions do not work when the
11510processor is in little endian mode. The exceptions are PPC740 and
11511PPC750 which permit the instructions usage in little endian mode.
11512
11513@item -mstring
11514@itemx -mno-string
11515@opindex mstring
11516@opindex mno-string
11517Generate code that uses (does not use) the load string instructions
11518and the store string word instructions to save multiple registers and
11519do small block moves. These instructions are generated by default on
11520POWER systems, and not generated on PowerPC systems. Do not use
11521@option{-mstring} on little endian PowerPC systems, since those
11522instructions do not work when the processor is in little endian mode.
11523The exceptions are PPC740 and PPC750 which permit the instructions
11524usage in little endian mode.
11525
11526@item -mupdate
11527@itemx -mno-update
11528@opindex mupdate
11529@opindex mno-update
11530Generate code that uses (does not use) the load or store instructions
11531that update the base register to the address of the calculated memory
11532location. These instructions are generated by default. If you use
11533@option{-mno-update}, there is a small window between the time that the
11534stack pointer is updated and the address of the previous frame is
11535stored, which means code that walks the stack frame across interrupts or
11536signals may get corrupted data.
11537
11538@item -mfused-madd
11539@itemx -mno-fused-madd
11540@opindex mfused-madd
11541@opindex mno-fused-madd
11542Generate code that uses (does not use) the floating point multiply and
11543accumulate instructions. These instructions are generated by default if
11544hardware floating is used.
11545
11546@item -mmulhw
11547@itemx -mno-mulhw
11548@opindex mmulhw
11549@opindex mno-mulhw
11550Generate code that uses (does not use) the half-word multiply and
11551multiply-accumulate instructions on the IBM 405 and 440 processors.
11552These instructions are generated by default when targetting those
11553processors.
11554
11555@item -mdlmzb
11556@itemx -mno-dlmzb
11557@opindex mdlmzb
11558@opindex mno-dlmzb
11559Generate code that uses (does not use) the string-search @samp{dlmzb}
11560instruction on the IBM 405 and 440 processors. This instruction is
11561generated by default when targetting those processors.
11562
11563@item -mno-bit-align
11564@itemx -mbit-align
11565@opindex mno-bit-align
11566@opindex mbit-align
11567On System V.4 and embedded PowerPC systems do not (do) force structures
11568and unions that contain bit-fields to be aligned to the base type of the
11569bit-field.
11570
11571For example, by default a structure containing nothing but 8
11572@code{unsigned} bit-fields of length 1 would be aligned to a 4 byte
11573boundary and have a size of 4 bytes. By using @option{-mno-bit-align},
11574the structure would be aligned to a 1 byte boundary and be one byte in
11575size.
11576
11577@item -mno-strict-align
11578@itemx -mstrict-align
11579@opindex mno-strict-align
11580@opindex mstrict-align
11581On System V.4 and embedded PowerPC systems do not (do) assume that
11582unaligned memory references will be handled by the system.
11583
11584@item -mrelocatable
11585@itemx -mno-relocatable
11586@opindex mrelocatable
11587@opindex mno-relocatable
11588On embedded PowerPC systems generate code that allows (does not allow)
11589the program to be relocated to a different address at runtime. If you
11590use @option{-mrelocatable} on any module, all objects linked together must
11591be compiled with @option{-mrelocatable} or @option{-mrelocatable-lib}.
11592
11593@item -mrelocatable-lib
11594@itemx -mno-relocatable-lib
11595@opindex mrelocatable-lib
11596@opindex mno-relocatable-lib
11597On embedded PowerPC systems generate code that allows (does not allow)
11598the program to be relocated to a different address at runtime. Modules
11599compiled with @option{-mrelocatable-lib} can be linked with either modules
11600compiled without @option{-mrelocatable} and @option{-mrelocatable-lib} or
11601with modules compiled with the @option{-mrelocatable} options.
11602
11603@item -mno-toc
11604@itemx -mtoc
11605@opindex mno-toc
11606@opindex mtoc
11607On System V.4 and embedded PowerPC systems do not (do) assume that
11608register 2 contains a pointer to a global area pointing to the addresses
11609used in the program.
11610
11611@item -mlittle
11612@itemx -mlittle-endian
11613@opindex mlittle
11614@opindex mlittle-endian
11615On System V.4 and embedded PowerPC systems compile code for the
11616processor in little endian mode. The @option{-mlittle-endian} option is
11617the same as @option{-mlittle}.
11618
11619@item -mbig
11620@itemx -mbig-endian
11621@opindex mbig
11622@opindex mbig-endian
11623On System V.4 and embedded PowerPC systems compile code for the
11624processor in big endian mode. The @option{-mbig-endian} option is
11625the same as @option{-mbig}.
11626
11627@item -mdynamic-no-pic
11628@opindex mdynamic-no-pic
11629On Darwin and Mac OS X systems, compile code so that it is not
11630relocatable, but that its external references are relocatable. The
11631resulting code is suitable for applications, but not shared
11632libraries.
11633
11634@item -mprioritize-restricted-insns=@var{priority}
11635@opindex mprioritize-restricted-insns
11636This option controls the priority that is assigned to
11637dispatch-slot restricted instructions during the second scheduling
11638pass. The argument @var{priority} takes the value @var{0/1/2} to assign
11639@var{no/highest/second-highest} priority to dispatch slot restricted
11640instructions.
11641
11642@item -msched-costly-dep=@var{dependence_type}
11643@opindex msched-costly-dep
11644This option controls which dependences are considered costly
11645by the target during instruction scheduling. The argument
11646@var{dependence_type} takes one of the following values:
11647@var{no}: no dependence is costly,
11648@var{all}: all dependences are costly,
11649@var{true_store_to_load}: a true dependence from store to load is costly,
11650@var{store_to_load}: any dependence from store to load is costly,
11651@var{number}: any dependence which latency >= @var{number} is costly.
11652
11653@item -minsert-sched-nops=@var{scheme}
11654@opindex minsert-sched-nops
11655This option controls which nop insertion scheme will be used during
11656the second scheduling pass. The argument @var{scheme} takes one of the
11657following values:
11658@var{no}: Don't insert nops.
11659@var{pad}: Pad with nops any dispatch group which has vacant issue slots,
11660according to the scheduler's grouping.
11661@var{regroup_exact}: Insert nops to force costly dependent insns into
11662separate groups. Insert exactly as many nops as needed to force an insn
11663to a new group, according to the estimated processor grouping.
11664@var{number}: Insert nops to force costly dependent insns into
11665separate groups. Insert @var{number} nops to force an insn to a new group.
11666
11667@item -mcall-sysv
11668@opindex mcall-sysv
11669On System V.4 and embedded PowerPC systems compile code using calling
11670conventions that adheres to the March 1995 draft of the System V
11671Application Binary Interface, PowerPC processor supplement. This is the
11672default unless you configured GCC using @samp{powerpc-*-eabiaix}.
11673
11674@item -mcall-sysv-eabi
11675@opindex mcall-sysv-eabi
11676Specify both @option{-mcall-sysv} and @option{-meabi} options.
11677
11678@item -mcall-sysv-noeabi
11679@opindex mcall-sysv-noeabi
11680Specify both @option{-mcall-sysv} and @option{-mno-eabi} options.
11681
11682@item -mcall-solaris
11683@opindex mcall-solaris
11684On System V.4 and embedded PowerPC systems compile code for the Solaris
11685operating system.
11686
11687@item -mcall-linux
11688@opindex mcall-linux
11689On System V.4 and embedded PowerPC systems compile code for the
11690Linux-based GNU system.
11691
11692@item -mcall-gnu
11693@opindex mcall-gnu
11694On System V.4 and embedded PowerPC systems compile code for the
11695Hurd-based GNU system.
11696
11697@item -mcall-netbsd
11698@opindex mcall-netbsd
11699On System V.4 and embedded PowerPC systems compile code for the
11700NetBSD operating system.
11701
11702@item -maix-struct-return
11703@opindex maix-struct-return
11704Return all structures in memory (as specified by the AIX ABI)@.
11705
11706@item -msvr4-struct-return
11707@opindex msvr4-struct-return
11708Return structures smaller than 8 bytes in registers (as specified by the
11709SVR4 ABI)@.
11710
11711@item -mabi=@var{abi-type}
11712@opindex mabi
11713Extend the current ABI with a particular extension, or remove such extension.
11714Valid values are @var{altivec}, @var{no-altivec}, @var{spe},
11715@var{no-spe}, @var{ibmlongdouble}, @var{ieeelongdouble}@.
11716
11717@item -mabi=spe
11718@opindex mabi=spe
11719Extend the current ABI with SPE ABI extensions. This does not change
11720the default ABI, instead it adds the SPE ABI extensions to the current
11721ABI@.
11722
11723@item -mabi=no-spe
11724@opindex mabi=no-spe
11725Disable Booke SPE ABI extensions for the current ABI@.
11726
11727@item -mabi=ibmlongdouble
11728@opindex mabi=ibmlongdouble
11729Change the current ABI to use IBM extended precision long double.
11730This is a PowerPC 32-bit SYSV ABI option.
11731
11732@item -mabi=ieeelongdouble
11733@opindex mabi=ieeelongdouble
11734Change the current ABI to use IEEE extended precision long double.
11735This is a PowerPC 32-bit Linux ABI option.
11736
11737@item -mprototype
11738@itemx -mno-prototype
11739@opindex mprototype
11740@opindex mno-prototype
11741On System V.4 and embedded PowerPC systems assume that all calls to
11742variable argument functions are properly prototyped. Otherwise, the
11743compiler must insert an instruction before every non prototyped call to
11744set or clear bit 6 of the condition code register (@var{CR}) to
11745indicate whether floating point values were passed in the floating point
11746registers in case the function takes a variable arguments. With
11747@option{-mprototype}, only calls to prototyped variable argument functions
11748will set or clear the bit.
11749
11750@item -msim
11751@opindex msim
11752On embedded PowerPC systems, assume that the startup module is called
11753@file{sim-crt0.o} and that the standard C libraries are @file{libsim.a} and
11754@file{libc.a}. This is the default for @samp{powerpc-*-eabisim}.
11755configurations.
11756
11757@item -mmvme
11758@opindex mmvme
11759On embedded PowerPC systems, assume that the startup module is called
11760@file{crt0.o} and the standard C libraries are @file{libmvme.a} and
11761@file{libc.a}.
11762
11763@item -mads
11764@opindex mads
11765On embedded PowerPC systems, assume that the startup module is called
11766@file{crt0.o} and the standard C libraries are @file{libads.a} and
11767@file{libc.a}.
11768
11769@item -myellowknife
11770@opindex myellowknife
11771On embedded PowerPC systems, assume that the startup module is called
11772@file{crt0.o} and the standard C libraries are @file{libyk.a} and
11773@file{libc.a}.
11774
11775@item -mvxworks
11776@opindex mvxworks
11777On System V.4 and embedded PowerPC systems, specify that you are
11778compiling for a VxWorks system.
11779
11780@item -mwindiss
11781@opindex mwindiss
11782Specify that you are compiling for the WindISS simulation environment.
11783
11784@item -memb
11785@opindex memb
11786On embedded PowerPC systems, set the @var{PPC_EMB} bit in the ELF flags
11787header to indicate that @samp{eabi} extended relocations are used.
11788
11789@item -meabi
11790@itemx -mno-eabi
11791@opindex meabi
11792@opindex mno-eabi
11793On System V.4 and embedded PowerPC systems do (do not) adhere to the
11794Embedded Applications Binary Interface (eabi) which is a set of
11795modifications to the System V.4 specifications. Selecting @option{-meabi}
11796means that the stack is aligned to an 8 byte boundary, a function
11797@code{__eabi} is called to from @code{main} to set up the eabi
11798environment, and the @option{-msdata} option can use both @code{r2} and
11799@code{r13} to point to two separate small data areas. Selecting
11800@option{-mno-eabi} means that the stack is aligned to a 16 byte boundary,
11801do not call an initialization function from @code{main}, and the
11802@option{-msdata} option will only use @code{r13} to point to a single
11803small data area. The @option{-meabi} option is on by default if you
11804configured GCC using one of the @samp{powerpc*-*-eabi*} options.
11805
11806@item -msdata=eabi
11807@opindex msdata=eabi
11808On System V.4 and embedded PowerPC systems, put small initialized
11809@code{const} global and static data in the @samp{.sdata2} section, which
11810is pointed to by register @code{r2}. Put small initialized
11811non-@code{const} global and static data in the @samp{.sdata} section,
11812which is pointed to by register @code{r13}. Put small uninitialized
11813global and static data in the @samp{.sbss} section, which is adjacent to
11814the @samp{.sdata} section. The @option{-msdata=eabi} option is
11815incompatible with the @option{-mrelocatable} option. The
11816@option{-msdata=eabi} option also sets the @option{-memb} option.
11817
11818@item -msdata=sysv
11819@opindex msdata=sysv
11820On System V.4 and embedded PowerPC systems, put small global and static
11821data in the @samp{.sdata} section, which is pointed to by register
11822@code{r13}. Put small uninitialized global and static data in the
11823@samp{.sbss} section, which is adjacent to the @samp{.sdata} section.
11824The @option{-msdata=sysv} option is incompatible with the
11825@option{-mrelocatable} option.
11826
11827@item -msdata=default
11828@itemx -msdata
11829@opindex msdata=default
11830@opindex msdata
11831On System V.4 and embedded PowerPC systems, if @option{-meabi} is used,
11832compile code the same as @option{-msdata=eabi}, otherwise compile code the
11833same as @option{-msdata=sysv}.
11834
11835@item -msdata-data
11836@opindex msdata-data
11837On System V.4 and embedded PowerPC systems, put small global
11838data in the @samp{.sdata} section. Put small uninitialized global
11839data in the @samp{.sbss} section. Do not use register @code{r13}
11840to address small data however. This is the default behavior unless
11841other @option{-msdata} options are used.
11842
11843@item -msdata=none
11844@itemx -mno-sdata
11845@opindex msdata=none
11846@opindex mno-sdata
11847On embedded PowerPC systems, put all initialized global and static data
11848in the @samp{.data} section, and all uninitialized data in the
11849@samp{.bss} section.
11850
11851@item -G @var{num}
11852@opindex G
11853@cindex smaller data references (PowerPC)
11854@cindex .sdata/.sdata2 references (PowerPC)
11855On embedded PowerPC systems, put global and static items less than or
11856equal to @var{num} bytes into the small data or bss sections instead of
11857the normal data or bss section. By default, @var{num} is 8. The
11858@option{-G @var{num}} switch is also passed to the linker.
11859All modules should be compiled with the same @option{-G @var{num}} value.
11860
11861@item -mregnames
11862@itemx -mno-regnames
11863@opindex mregnames
11864@opindex mno-regnames
11865On System V.4 and embedded PowerPC systems do (do not) emit register
11866names in the assembly language output using symbolic forms.
11867
11868@item -mlongcall
11869@itemx -mno-longcall
11870@opindex mlongcall
11871@opindex mno-longcall
11872By default assume that all calls are far away so that a longer more
11873expensive calling sequence is required. This is required for calls
11874further than 32 megabytes (33,554,432 bytes) from the current location.
11875A short call will be generated if the compiler knows
11876the call cannot be that far away. This setting can be overridden by
11877the @code{shortcall} function attribute, or by @code{#pragma
11878longcall(0)}.
11879
11880Some linkers are capable of detecting out-of-range calls and generating
11881glue code on the fly. On these systems, long calls are unnecessary and
11882generate slower code. As of this writing, the AIX linker can do this,
11883as can the GNU linker for PowerPC/64. It is planned to add this feature
11884to the GNU linker for 32-bit PowerPC systems as well.
11885
11886On Darwin/PPC systems, @code{#pragma longcall} will generate ``jbsr
11887callee, L42'', plus a ``branch island'' (glue code). The two target
11888addresses represent the callee and the ``branch island''. The
11889Darwin/PPC linker will prefer the first address and generate a ``bl
11890callee'' if the PPC ``bl'' instruction will reach the callee directly;
11891otherwise, the linker will generate ``bl L42'' to call the ``branch
11892island''. The ``branch island'' is appended to the body of the
11893calling function; it computes the full 32-bit address of the callee
11894and jumps to it.
11895
11896On Mach-O (Darwin) systems, this option directs the compiler emit to
11897the glue for every direct call, and the Darwin linker decides whether
11898to use or discard it.
11899
11900In the future, we may cause GCC to ignore all longcall specifications
11901when the linker is known to generate glue.
11902
11903@item -pthread
11904@opindex pthread
11905Adds support for multithreading with the @dfn{pthreads} library.
11906This option sets flags for both the preprocessor and linker.
11907
11908@end table
11909
11910@node S/390 and zSeries Options
11911@subsection S/390 and zSeries Options
11912@cindex S/390 and zSeries Options
11913
11914These are the @samp{-m} options defined for the S/390 and zSeries architecture.
11915
11916@table @gcctabopt
11917@item -mhard-float
11918@itemx -msoft-float
11919@opindex mhard-float
11920@opindex msoft-float
11921Use (do not use) the hardware floating-point instructions and registers
11922for floating-point operations. When @option{-msoft-float} is specified,
11923functions in @file{libgcc.a} will be used to perform floating-point
11924operations. When @option{-mhard-float} is specified, the compiler
11925generates IEEE floating-point instructions. This is the default.
11926
11927@item -mlong-double-64
11928@itemx -mlong-double-128
11929@opindex mlong-double-64
11930@opindex mlong-double-128
11931These switches control the size of @code{long double} type. A size
11932of 64bit makes the @code{long double} type equivalent to the @code{double}
11933type. This is the default.
11934
11935@item -mbackchain
11936@itemx -mno-backchain
11937@opindex mbackchain
11938@opindex mno-backchain
11939Store (do not store) the address of the caller's frame as backchain pointer
11940into the callee's stack frame.
11941A backchain may be needed to allow debugging using tools that do not understand
11942DWARF-2 call frame information.
11943When @option{-mno-packed-stack} is in effect, the backchain pointer is stored
11944at the bottom of the stack frame; when @option{-mpacked-stack} is in effect,
11945the backchain is placed into the topmost word of the 96/160 byte register
11946save area.
11947
11948In general, code compiled with @option{-mbackchain} is call-compatible with
11949code compiled with @option{-mmo-backchain}; however, use of the backchain
11950for debugging purposes usually requires that the whole binary is built with
11951@option{-mbackchain}. Note that the combination of @option{-mbackchain},
11952@option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
11953to build a linux kernel use @option{-msoft-float}.
11954
11955The default is to not maintain the backchain.
11956
11957@item -mpacked-stack
11958@item -mno-packed-stack
11959@opindex mpacked-stack
11960@opindex mno-packed-stack
11961Use (do not use) the packed stack layout. When @option{-mno-packed-stack} is
11962specified, the compiler uses the all fields of the 96/160 byte register save
11963area only for their default purpose; unused fields still take up stack space.
11964When @option{-mpacked-stack} is specified, register save slots are densely
11965packed at the top of the register save area; unused space is reused for other
11966purposes, allowing for more efficient use of the available stack space.
11967However, when @option{-mbackchain} is also in effect, the topmost word of
11968the save area is always used to store the backchain, and the return address
11969register is always saved two words below the backchain.
11970
11971As long as the stack frame backchain is not used, code generated with
11972@option{-mpacked-stack} is call-compatible with code generated with
11973@option{-mno-packed-stack}. Note that some non-FSF releases of GCC 2.95 for
11974S/390 or zSeries generated code that uses the stack frame backchain at run
11975time, not just for debugging purposes. Such code is not call-compatible
11976with code compiled with @option{-mpacked-stack}. Also, note that the
11977combination of @option{-mbackchain},
11978@option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
11979to build a linux kernel use @option{-msoft-float}.
11980
11981The default is to not use the packed stack layout.
11982
11983@item -msmall-exec
11984@itemx -mno-small-exec
11985@opindex msmall-exec
11986@opindex mno-small-exec
11987Generate (or do not generate) code using the @code{bras} instruction
11988to do subroutine calls.
11989This only works reliably if the total executable size does not
11990exceed 64k. The default is to use the @code{basr} instruction instead,
11991which does not have this limitation.
11992
11993@item -m64
11994@itemx -m31
11995@opindex m64
11996@opindex m31
11997When @option{-m31} is specified, generate code compliant to the
11998GNU/Linux for S/390 ABI@. When @option{-m64} is specified, generate
11999code compliant to the GNU/Linux for zSeries ABI@. This allows GCC in
12000particular to generate 64-bit instructions. For the @samp{s390}
12001targets, the default is @option{-m31}, while the @samp{s390x}
12002targets default to @option{-m64}.
12003
12004@item -mzarch
12005@itemx -mesa
12006@opindex mzarch
12007@opindex mesa
12008When @option{-mzarch} is specified, generate code using the
12009instructions available on z/Architecture.
12010When @option{-mesa} is specified, generate code using the
12011instructions available on ESA/390. Note that @option{-mesa} is
12012not possible with @option{-m64}.
12013When generating code compliant to the GNU/Linux for S/390 ABI,
12014the default is @option{-mesa}. When generating code compliant
12015to the GNU/Linux for zSeries ABI, the default is @option{-mzarch}.
12016
12017@item -mmvcle
12018@itemx -mno-mvcle
12019@opindex mmvcle
12020@opindex mno-mvcle
12021Generate (or do not generate) code using the @code{mvcle} instruction
12022to perform block moves. When @option{-mno-mvcle} is specified,
12023use a @code{mvc} loop instead. This is the default unless optimizing for
12024size.
12025
12026@item -mdebug
12027@itemx -mno-debug
12028@opindex mdebug
12029@opindex mno-debug
12030Print (or do not print) additional debug information when compiling.
12031The default is to not print debug information.
12032
12033@item -march=@var{cpu-type}
12034@opindex march
12035Generate code that will run on @var{cpu-type}, which is the name of a system
12036representing a certain processor type. Possible values for
12037@var{cpu-type} are @samp{g5}, @samp{g6}, @samp{z900}, and @samp{z990}.
12038When generating code using the instructions available on z/Architecture,
12039the default is @option{-march=z900}. Otherwise, the default is
12040@option{-march=g5}.
12041
12042@item -mtune=@var{cpu-type}
12043@opindex mtune
12044Tune to @var{cpu-type} everything applicable about the generated code,
12045except for the ABI and the set of available instructions.
12046The list of @var{cpu-type} values is the same as for @option{-march}.
12047The default is the value used for @option{-march}.
12048
12049@item -mtpf-trace
12050@itemx -mno-tpf-trace
12051@opindex mtpf-trace
12052@opindex mno-tpf-trace
12053Generate code that adds (does not add) in TPF OS specific branches to trace
12054routines in the operating system. This option is off by default, even
12055when compiling for the TPF OS@.
12056
12057@item -mfused-madd
12058@itemx -mno-fused-madd
12059@opindex mfused-madd
12060@opindex mno-fused-madd
12061Generate code that uses (does not use) the floating point multiply and
12062accumulate instructions. These instructions are generated by default if
12063hardware floating point is used.
12064
12065@item -mwarn-framesize=@var{framesize}
12066@opindex mwarn-framesize
12067Emit a warning if the current function exceeds the given frame size. Because
12068this is a compile time check it doesn't need to be a real problem when the program
12069runs. It is intended to identify functions which most probably cause
12070a stack overflow. It is useful to be used in an environment with limited stack
12071size e.g.@: the linux kernel.
12072
12073@item -mwarn-dynamicstack
12074@opindex mwarn-dynamicstack
12075Emit a warning if the function calls alloca or uses dynamically
12076sized arrays. This is generally a bad idea with a limited stack size.
12077
12078@item -mstack-guard=@var{stack-guard}
12079@item -mstack-size=@var{stack-size}
12080@opindex mstack-guard
12081@opindex mstack-size
12082These arguments always have to be used in conjunction. If they are present the s390
12083back end emits additional instructions in the function prologue which trigger a trap
12084if the stack size is @var{stack-guard} bytes above the @var{stack-size}
12085(remember that the stack on s390 grows downward). These options are intended to
12086be used to help debugging stack overflow problems. The additionally emitted code
12087causes only little overhead and hence can also be used in production like systems
12088without greater performance degradation. The given values have to be exact
12089powers of 2 and @var{stack-size} has to be greater than @var{stack-guard} without
12090exceeding 64k.
12091In order to be efficient the extra code makes the assumption that the stack starts
12092at an address aligned to the value given by @var{stack-size}.
12093@end table
12094
12095@node Score Options
12096@subsection Score Options
12097@cindex Score Options
12098
12099These options are defined for Score implementations:
12100
12101@table @gcctabopt
12102@item -meb
12103@opindex meb
12104Compile code for big endian mode. This is the default.
12105
12106@item -mel
12107@opindex mel
12108Compile code for little endian mode.
12109
12110@item -mnhwloop
12111@opindex mnhwloop
12112Disable generate bcnz instruction.
12113
12114@item -muls
12115@opindex muls
12116Enable generate unaligned load and store instruction.
12117
12118@item -mmac
12119@opindex mmac
12120Enable the use of multiply-accumulate instructions. Disabled by default.
12121
12122@item -mscore5
12123@opindex mscore5
12124Specify the SCORE5 as the target architecture.
12125
12126@item -mscore5u
12127@opindex mscore5u
12128Specify the SCORE5U of the target architecture.
12129
12130@item -mscore7
12131@opindex mscore7
12132Specify the SCORE7 as the target architecture. This is the default.
12133
12134@item -mscore7d
12135@opindex mscore7d
12136Specify the SCORE7D as the target architecture.
12137@end table
12138
12139@node SH Options
12140@subsection SH Options
12141
12142These @samp{-m} options are defined for the SH implementations:
12143
12144@table @gcctabopt
12145@item -m1
12146@opindex m1
12147Generate code for the SH1.
12148
12149@item -m2
12150@opindex m2
12151Generate code for the SH2.
12152
12153@item -m2e
12154Generate code for the SH2e.
12155
12156@item -m3
12157@opindex m3
12158Generate code for the SH3.
12159
12160@item -m3e
12161@opindex m3e
12162Generate code for the SH3e.
12163
12164@item -m4-nofpu
12165@opindex m4-nofpu
12166Generate code for the SH4 without a floating-point unit.
12167
12168@item -m4-single-only
12169@opindex m4-single-only
12170Generate code for the SH4 with a floating-point unit that only
12171supports single-precision arithmetic.
12172
12173@item -m4-single
12174@opindex m4-single
12175Generate code for the SH4 assuming the floating-point unit is in
12176single-precision mode by default.
12177
12178@item -m4
12179@opindex m4
12180Generate code for the SH4.
12181
12182@item -m4a-nofpu
12183@opindex m4a-nofpu
12184Generate code for the SH4al-dsp, or for a SH4a in such a way that the
12185floating-point unit is not used.
12186
12187@item -m4a-single-only
12188@opindex m4a-single-only
12189Generate code for the SH4a, in such a way that no double-precision
12190floating point operations are used.
12191
12192@item -m4a-single
12193@opindex m4a-single
12194Generate code for the SH4a assuming the floating-point unit is in
12195single-precision mode by default.
12196
12197@item -m4a
12198@opindex m4a
12199Generate code for the SH4a.
12200
12201@item -m4al
12202@opindex m4al
12203Same as @option{-m4a-nofpu}, except that it implicitly passes
12204@option{-dsp} to the assembler. GCC doesn't generate any DSP
12205instructions at the moment.
12206
12207@item -mb
12208@opindex mb
12209Compile code for the processor in big endian mode.
12210
12211@item -ml
12212@opindex ml
12213Compile code for the processor in little endian mode.
12214
12215@item -mdalign
12216@opindex mdalign
12217Align doubles at 64-bit boundaries. Note that this changes the calling
12218conventions, and thus some functions from the standard C library will
12219not work unless you recompile it first with @option{-mdalign}.
12220
12221@item -mrelax
12222@opindex mrelax
12223Shorten some address references at link time, when possible; uses the
12224linker option @option{-relax}.
12225
12226@item -mbigtable
12227@opindex mbigtable
12228Use 32-bit offsets in @code{switch} tables. The default is to use
1222916-bit offsets.
12230
12231@item -mfmovd
12232@opindex mfmovd
12233Enable the use of the instruction @code{fmovd}.
12234
12235@item -mhitachi
12236@opindex mhitachi
12237Comply with the calling conventions defined by Renesas.
12238
12239@item -mrenesas
12240@opindex mhitachi
12241Comply with the calling conventions defined by Renesas.
12242
12243@item -mno-renesas
12244@opindex mhitachi
12245Comply with the calling conventions defined for GCC before the Renesas
12246conventions were available. This option is the default for all
12247targets of the SH toolchain except for @samp{sh-symbianelf}.
12248
12249@item -mnomacsave
12250@opindex mnomacsave
12251Mark the @code{MAC} register as call-clobbered, even if
12252@option{-mhitachi} is given.
12253
12254@item -mieee
12255@opindex mieee
12256Increase IEEE-compliance of floating-point code.
12257At the moment, this is equivalent to @option{-fno-finite-math-only}.
12258When generating 16 bit SH opcodes, getting IEEE-conforming results for
12259comparisons of NANs / infinities incurs extra overhead in every
12260floating point comparison, therefore the default is set to
12261@option{-ffinite-math-only}.
12262
12263@item -misize
12264@opindex misize
12265Dump instruction size and location in the assembly code.
12266
12267@item -mpadstruct
12268@opindex mpadstruct
12269This option is deprecated. It pads structures to multiple of 4 bytes,
12270which is incompatible with the SH ABI@.
12271
12272@item -mspace
12273@opindex mspace
12274Optimize for space instead of speed. Implied by @option{-Os}.
12275
12276@item -mprefergot
12277@opindex mprefergot
12278When generating position-independent code, emit function calls using
12279the Global Offset Table instead of the Procedure Linkage Table.
12280
12281@item -musermode
12282@opindex musermode
12283Generate a library function call to invalidate instruction cache
12284entries, after fixing up a trampoline. This library function call
12285doesn't assume it can write to the whole memory address space. This
12286is the default when the target is @code{sh-*-linux*}.
12287
12288@item -multcost=@var{number}
12289@opindex multcost=@var{number}
12290Set the cost to assume for a multiply insn.
12291
12292@item -mdiv=@var{strategy}
12293@opindex mdiv=@var{strategy}
12294Set the division strategy to use for SHmedia code. @var{strategy} must be
12295one of: call, call2, fp, inv, inv:minlat, inv20u, inv20l, inv:call,
12296inv:call2, inv:fp .
12297"fp" performs the operation in floating point. This has a very high latency,
12298but needs only a few instructions, so it might be a good choice if
12299your code has enough easily exploitable ILP to allow the compiler to
12300schedule the floating point instructions together with other instructions.
12301Division by zero causes a floating point exception.
12302"inv" uses integer operations to calculate the inverse of the divisor,
12303and then multiplies the dividend with the inverse. This strategy allows
12304cse and hoisting of the inverse calculation. Division by zero calculates
12305an unspecified result, but does not trap.
12306"inv:minlat" is a variant of "inv" where if no cse / hoisting opportunities
12307have been found, or if the entire operation has been hoisted to the same
12308place, the last stages of the inverse calculation are intertwined with the
12309final multiply to reduce the overall latency, at the expense of using a few
12310more instructions, and thus offering fewer scheduling opportunities with
12311other code.
12312"call" calls a library function that usually implements the inv:minlat
12313strategy.
12314This gives high code density for m5-*media-nofpu compilations.
12315"call2" uses a different entry point of the same library function, where it
12316assumes that a pointer to a lookup table has already been set up, which
12317exposes the pointer load to cse / code hoisting optimizations.
12318"inv:call", "inv:call2" and "inv:fp" all use the "inv" algorithm for initial
12319code generation, but if the code stays unoptimized, revert to the "call",
12320"call2", or "fp" strategies, respectively. Note that the
12321potentially-trapping side effect of division by zero is carried by a
12322separate instruction, so it is possible that all the integer instructions
12323are hoisted out, but the marker for the side effect stays where it is.
12324A recombination to fp operations or a call is not possible in that case.
12325"inv20u" and "inv20l" are variants of the "inv:minlat" strategy. In the case
12326that the inverse calculation was nor separated from the multiply, they speed
12327up division where the dividend fits into 20 bits (plus sign where applicable),
12328by inserting a test to skip a number of operations in this case; this test
12329slows down the case of larger dividends. inv20u assumes the case of a such
12330a small dividend to be unlikely, and inv20l assumes it to be likely.
12331
12332@item -mdivsi3_libfunc=@var{name}
12333@opindex mdivsi3_libfunc=@var{name}
12334Set the name of the library function used for 32 bit signed division to
12335@var{name}. This only affect the name used in the call and inv:call
12336division strategies, and the compiler will still expect the same
12337sets of input/output/clobbered registers as if this option was not present.
12338
12339@item -madjust-unroll
12340@opindex madjust-unroll
12341Throttle unrolling to avoid thrashing target registers.
12342This option only has an effect if the gcc code base supports the
12343TARGET_ADJUST_UNROLL_MAX target hook.
12344
12345@item -mindexed-addressing
12346@opindex mindexed-addressing
12347Enable the use of the indexed addressing mode for SHmedia32/SHcompact.
12348This is only safe if the hardware and/or OS implement 32 bit wrap-around
12349semantics for the indexed addressing mode. The architecture allows the
12350implementation of processors with 64 bit MMU, which the OS could use to
12351get 32 bit addressing, but since no current hardware implementation supports
12352this or any other way to make the indexed addressing mode safe to use in
12353the 32 bit ABI, the default is -mno-indexed-addressing.
12354
12355@item -mgettrcost=@var{number}
12356@opindex mgettrcost=@var{number}
12357Set the cost assumed for the gettr instruction to @var{number}.
12358The default is 2 if @option{-mpt-fixed} is in effect, 100 otherwise.
12359
12360@item -mpt-fixed
12361@opindex mpt-fixed
12362Assume pt* instructions won't trap. This will generally generate better
12363scheduled code, but is unsafe on current hardware. The current architecture
12364definition says that ptabs and ptrel trap when the target anded with 3 is 3.
12365This has the unintentional effect of making it unsafe to schedule ptabs /
12366ptrel before a branch, or hoist it out of a loop. For example,
12367__do_global_ctors, a part of libgcc that runs constructors at program
12368startup, calls functions in a list which is delimited by -1. With the
12369-mpt-fixed option, the ptabs will be done before testing against -1.
12370That means that all the constructors will be run a bit quicker, but when
12371the loop comes to the end of the list, the program crashes because ptabs
12372loads -1 into a target register. Since this option is unsafe for any
12373hardware implementing the current architecture specification, the default
12374is -mno-pt-fixed. Unless the user specifies a specific cost with
12375@option{-mgettrcost}, -mno-pt-fixed also implies @option{-mgettrcost=100};
12376this deters register allocation using target registers for storing
12377ordinary integers.
12378
12379@item -minvalid-symbols
12380@opindex minvalid-symbols
12381Assume symbols might be invalid. Ordinary function symbols generated by
12382the compiler will always be valid to load with movi/shori/ptabs or
12383movi/shori/ptrel, but with assembler and/or linker tricks it is possible
12384to generate symbols that will cause ptabs / ptrel to trap.
12385This option is only meaningful when @option{-mno-pt-fixed} is in effect.
12386It will then prevent cross-basic-block cse, hoisting and most scheduling
12387of symbol loads. The default is @option{-mno-invalid-symbols}.
12388@end table
12389
12390@node SPARC Options
12391@subsection SPARC Options
12392@cindex SPARC options
12393
12394These @samp{-m} options are supported on the SPARC:
12395
12396@table @gcctabopt
12397@item -mno-app-regs
12398@itemx -mapp-regs
12399@opindex mno-app-regs
12400@opindex mapp-regs
12401Specify @option{-mapp-regs} to generate output using the global registers
124022 through 4, which the SPARC SVR4 ABI reserves for applications. This
12403is the default.
12404
12405To be fully SVR4 ABI compliant at the cost of some performance loss,
12406specify @option{-mno-app-regs}. You should compile libraries and system
12407software with this option.
12408
12409@item -mfpu
12410@itemx -mhard-float
12411@opindex mfpu
12412@opindex mhard-float
12413Generate output containing floating point instructions. This is the
12414default.
12415
12416@item -mno-fpu
12417@itemx -msoft-float
12418@opindex mno-fpu
12419@opindex msoft-float
12420Generate output containing library calls for floating point.
12421@strong{Warning:} the requisite libraries are not available for all SPARC
12422targets. Normally the facilities of the machine's usual C compiler are
12423used, but this cannot be done directly in cross-compilation. You must make
12424your own arrangements to provide suitable library functions for
12425cross-compilation. The embedded targets @samp{sparc-*-aout} and
12426@samp{sparclite-*-*} do provide software floating point support.
12427
12428@option{-msoft-float} changes the calling convention in the output file;
12429therefore, it is only useful if you compile @emph{all} of a program with
12430this option. In particular, you need to compile @file{libgcc.a}, the
12431library that comes with GCC, with @option{-msoft-float} in order for
12432this to work.
12433
12434@item -mhard-quad-float
12435@opindex mhard-quad-float
12436Generate output containing quad-word (long double) floating point
12437instructions.
12438
12439@item -msoft-quad-float
12440@opindex msoft-quad-float
12441Generate output containing library calls for quad-word (long double)
12442floating point instructions. The functions called are those specified
12443in the SPARC ABI@. This is the default.
12444
12445As of this writing, there are no SPARC implementations that have hardware
12446support for the quad-word floating point instructions. They all invoke
12447a trap handler for one of these instructions, and then the trap handler
12448emulates the effect of the instruction. Because of the trap handler overhead,
12449this is much slower than calling the ABI library routines. Thus the
12450@option{-msoft-quad-float} option is the default.
12451
12452@item -mno-unaligned-doubles
12453@itemx -munaligned-doubles
12454@opindex mno-unaligned-doubles
12455@opindex munaligned-doubles
12456Assume that doubles have 8 byte alignment. This is the default.
12457
12458With @option{-munaligned-doubles}, GCC assumes that doubles have 8 byte
12459alignment only if they are contained in another type, or if they have an
12460absolute address. Otherwise, it assumes they have 4 byte alignment.
12461Specifying this option avoids some rare compatibility problems with code
12462generated by other compilers. It is not the default because it results
12463in a performance loss, especially for floating point code.
12464
12465@item -mno-faster-structs
12466@itemx -mfaster-structs
12467@opindex mno-faster-structs
12468@opindex mfaster-structs
12469With @option{-mfaster-structs}, the compiler assumes that structures
12470should have 8 byte alignment. This enables the use of pairs of
12471@code{ldd} and @code{std} instructions for copies in structure
12472assignment, in place of twice as many @code{ld} and @code{st} pairs.
12473However, the use of this changed alignment directly violates the SPARC
12474ABI@. Thus, it's intended only for use on targets where the developer
12475acknowledges that their resulting code will not be directly in line with
12476the rules of the ABI@.
12477
12478@item -mimpure-text
12479@opindex mimpure-text
12480@option{-mimpure-text}, used in addition to @option{-shared}, tells
12481the compiler to not pass @option{-z text} to the linker when linking a
12482shared object. Using this option, you can link position-dependent
12483code into a shared object.
12484
12485@option{-mimpure-text} suppresses the ``relocations remain against
12486allocatable but non-writable sections'' linker error message.
12487However, the necessary relocations will trigger copy-on-write, and the
12488shared object is not actually shared across processes. Instead of
12489using @option{-mimpure-text}, you should compile all source code with
12490@option{-fpic} or @option{-fPIC}.
12491
12492This option is only available on SunOS and Solaris.
12493
12494@item -mcpu=@var{cpu_type}
12495@opindex mcpu
12496Set the instruction set, register set, and instruction scheduling parameters
12497for machine type @var{cpu_type}. Supported values for @var{cpu_type} are
12498@samp{v7}, @samp{cypress}, @samp{v8}, @samp{supersparc}, @samp{sparclite},
12499@samp{f930}, @samp{f934}, @samp{hypersparc}, @samp{sparclite86x},
12500@samp{sparclet}, @samp{tsc701}, @samp{v9}, @samp{ultrasparc},
12501@samp{ultrasparc3}, and @samp{niagara}.
12502
12503Default instruction scheduling parameters are used for values that select
12504an architecture and not an implementation. These are @samp{v7}, @samp{v8},
12505@samp{sparclite}, @samp{sparclet}, @samp{v9}.
12506
12507Here is a list of each supported architecture and their supported
12508implementations.
12509
12510@smallexample
12511 v7: cypress
12512 v8: supersparc, hypersparc
12513 sparclite: f930, f934, sparclite86x
12514 sparclet: tsc701
12515 v9: ultrasparc, ultrasparc3, niagara
12516@end smallexample
12517
12518By default (unless configured otherwise), GCC generates code for the V7
12519variant of the SPARC architecture. With @option{-mcpu=cypress}, the compiler
12520additionally optimizes it for the Cypress CY7C602 chip, as used in the
12521SPARCStation/SPARCServer 3xx series. This is also appropriate for the older
12522SPARCStation 1, 2, IPX etc.
12523
12524With @option{-mcpu=v8}, GCC generates code for the V8 variant of the SPARC
12525architecture. The only difference from V7 code is that the compiler emits
12526the integer multiply and integer divide instructions which exist in SPARC-V8
12527but not in SPARC-V7. With @option{-mcpu=supersparc}, the compiler additionally
12528optimizes it for the SuperSPARC chip, as used in the SPARCStation 10, 1000 and
125292000 series.
12530
12531With @option{-mcpu=sparclite}, GCC generates code for the SPARClite variant of
12532the SPARC architecture. This adds the integer multiply, integer divide step
12533and scan (@code{ffs}) instructions which exist in SPARClite but not in SPARC-V7.
12534With @option{-mcpu=f930}, the compiler additionally optimizes it for the
12535Fujitsu MB86930 chip, which is the original SPARClite, with no FPU@. With
12536@option{-mcpu=f934}, the compiler additionally optimizes it for the Fujitsu
12537MB86934 chip, which is the more recent SPARClite with FPU@.
12538
12539With @option{-mcpu=sparclet}, GCC generates code for the SPARClet variant of
12540the SPARC architecture. This adds the integer multiply, multiply/accumulate,
12541integer divide step and scan (@code{ffs}) instructions which exist in SPARClet
12542but not in SPARC-V7. With @option{-mcpu=tsc701}, the compiler additionally
12543optimizes it for the TEMIC SPARClet chip.
12544
12545With @option{-mcpu=v9}, GCC generates code for the V9 variant of the SPARC
12546architecture. This adds 64-bit integer and floating-point move instructions,
125473 additional floating-point condition code registers and conditional move
12548instructions. With @option{-mcpu=ultrasparc}, the compiler additionally
12549optimizes it for the Sun UltraSPARC I/II/IIi chips. With
12550@option{-mcpu=ultrasparc3}, the compiler additionally optimizes it for the
12551Sun UltraSPARC III/III+/IIIi/IIIi+/IV/IV+ chips. With
12552@option{-mcpu=niagara}, the compiler additionally optimizes it for
12553Sun UltraSPARC T1 chips.
12554
12555@item -mtune=@var{cpu_type}
12556@opindex mtune
12557Set the instruction scheduling parameters for machine type
12558@var{cpu_type}, but do not set the instruction set or register set that the
12559option @option{-mcpu=@var{cpu_type}} would.
12560
12561The same values for @option{-mcpu=@var{cpu_type}} can be used for
12562@option{-mtune=@var{cpu_type}}, but the only useful values are those
12563that select a particular cpu implementation. Those are @samp{cypress},
12564@samp{supersparc}, @samp{hypersparc}, @samp{f930}, @samp{f934},
12565@samp{sparclite86x}, @samp{tsc701}, @samp{ultrasparc},
12566@samp{ultrasparc3}, and @samp{niagara}.
12567
12568@item -mv8plus
12569@itemx -mno-v8plus
12570@opindex mv8plus
12571@opindex mno-v8plus
12572With @option{-mv8plus}, GCC generates code for the SPARC-V8+ ABI@. The
12573difference from the V8 ABI is that the global and out registers are
12574considered 64-bit wide. This is enabled by default on Solaris in 32-bit
12575mode for all SPARC-V9 processors.
12576
12577@item -mvis
12578@itemx -mno-vis
12579@opindex mvis
12580@opindex mno-vis
12581With @option{-mvis}, GCC generates code that takes advantage of the UltraSPARC
12582Visual Instruction Set extensions. The default is @option{-mno-vis}.
12583@end table
12584
12585These @samp{-m} options are supported in addition to the above
12586on SPARC-V9 processors in 64-bit environments:
12587
12588@table @gcctabopt
12589@item -mlittle-endian
12590@opindex mlittle-endian
12591Generate code for a processor running in little-endian mode. It is only
12592available for a few configurations and most notably not on Solaris and Linux.
12593
12594@item -m32
12595@itemx -m64
12596@opindex m32
12597@opindex m64
12598Generate code for a 32-bit or 64-bit environment.
12599The 32-bit environment sets int, long and pointer to 32 bits.
12600The 64-bit environment sets int to 32 bits and long and pointer
12601to 64 bits.
12602
12603@item -mcmodel=medlow
12604@opindex mcmodel=medlow
12605Generate code for the Medium/Low code model: 64-bit addresses, programs
12606must be linked in the low 32 bits of memory. Programs can be statically
12607or dynamically linked.
12608
12609@item -mcmodel=medmid
12610@opindex mcmodel=medmid
12611Generate code for the Medium/Middle code model: 64-bit addresses, programs
12612must be linked in the low 44 bits of memory, the text and data segments must
12613be less than 2GB in size and the data segment must be located within 2GB of
12614the text segment.
12615
12616@item -mcmodel=medany
12617@opindex mcmodel=medany
12618Generate code for the Medium/Anywhere code model: 64-bit addresses, programs
12619may be linked anywhere in memory, the text and data segments must be less
12620than 2GB in size and the data segment must be located within 2GB of the
12621text segment.
12622
12623@item -mcmodel=embmedany
12624@opindex mcmodel=embmedany
12625Generate code for the Medium/Anywhere code model for embedded systems:
1262664-bit addresses, the text and data segments must be less than 2GB in
12627size, both starting anywhere in memory (determined at link time). The
12628global register %g4 points to the base of the data segment. Programs
12629are statically linked and PIC is not supported.
12630
12631@item -mstack-bias
12632@itemx -mno-stack-bias
12633@opindex mstack-bias
12634@opindex mno-stack-bias
12635With @option{-mstack-bias}, GCC assumes that the stack pointer, and
12636frame pointer if present, are offset by @minus{}2047 which must be added back
12637when making stack frame references. This is the default in 64-bit mode.
12638Otherwise, assume no such offset is present.
12639@end table
12640
12641These switches are supported in addition to the above on Solaris:
12642
12643@table @gcctabopt
12644@item -threads
12645@opindex threads
12646Add support for multithreading using the Solaris threads library. This
12647option sets flags for both the preprocessor and linker. This option does
12648not affect the thread safety of object code produced by the compiler or
12649that of libraries supplied with it.
12650
12651@item -pthreads
12652@opindex pthreads
12653Add support for multithreading using the POSIX threads library. This
12654option sets flags for both the preprocessor and linker. This option does
12655not affect the thread safety of object code produced by the compiler or
12656that of libraries supplied with it.
12657
12658@item -pthread
12659@opindex pthread
12660This is a synonym for @option{-pthreads}.
12661@end table
12662
12663@node System V Options
12664@subsection Options for System V
12665
12666These additional options are available on System V Release 4 for
12667compatibility with other compilers on those systems:
12668
12669@table @gcctabopt
12670@item -G
12671@opindex G
12672Create a shared object.
12673It is recommended that @option{-symbolic} or @option{-shared} be used instead.
12674
12675@item -Qy
12676@opindex Qy
12677Identify the versions of each tool used by the compiler, in a
12678@code{.ident} assembler directive in the output.
12679
12680@item -Qn
12681@opindex Qn
12682Refrain from adding @code{.ident} directives to the output file (this is
12683the default).
12684
12685@item -YP,@var{dirs}
12686@opindex YP
12687Search the directories @var{dirs}, and no others, for libraries
12688specified with @option{-l}.
12689
12690@item -Ym,@var{dir}
12691@opindex Ym
12692Look in the directory @var{dir} to find the M4 preprocessor.
12693The assembler uses this option.
12694@c This is supposed to go with a -Yd for predefined M4 macro files, but
12695@c the generic assembler that comes with Solaris takes just -Ym.
12696@end table
12697
12698@node TMS320C3x/C4x Options
12699@subsection TMS320C3x/C4x Options
12700@cindex TMS320C3x/C4x Options
12701
12702These @samp{-m} options are defined for TMS320C3x/C4x implementations:
12703
12704@table @gcctabopt
12705
12706@item -mcpu=@var{cpu_type}
12707@opindex mcpu
12708Set the instruction set, register set, and instruction scheduling
12709parameters for machine type @var{cpu_type}. Supported values for
12710@var{cpu_type} are @samp{c30}, @samp{c31}, @samp{c32}, @samp{c40}, and
12711@samp{c44}. The default is @samp{c40} to generate code for the
12712TMS320C40.
12713
12714@item -mbig-memory
12715@itemx -mbig
12716@itemx -msmall-memory
12717@itemx -msmall
12718@opindex mbig-memory
12719@opindex mbig
12720@opindex msmall-memory
12721@opindex msmall
12722Generates code for the big or small memory model. The small memory
12723model assumed that all data fits into one 64K word page. At run-time
12724the data page (DP) register must be set to point to the 64K page
12725containing the .bss and .data program sections. The big memory model is
12726the default and requires reloading of the DP register for every direct
12727memory access.
12728
12729@item -mbk
12730@itemx -mno-bk
12731@opindex mbk
12732@opindex mno-bk
12733Allow (disallow) allocation of general integer operands into the block
12734count register BK@.
12735
12736@item -mdb
12737@itemx -mno-db
12738@opindex mdb
12739@opindex mno-db
12740Enable (disable) generation of code using decrement and branch,
12741DBcond(D), instructions. This is enabled by default for the C4x. To be
12742on the safe side, this is disabled for the C3x, since the maximum
12743iteration count on the C3x is @math{2^{23} + 1} (but who iterates loops more than
12744@math{2^{23}} times on the C3x?). Note that GCC will try to reverse a loop so
12745that it can utilize the decrement and branch instruction, but will give
12746up if there is more than one memory reference in the loop. Thus a loop
12747where the loop counter is decremented can generate slightly more
12748efficient code, in cases where the RPTB instruction cannot be utilized.
12749
12750@item -mdp-isr-reload
12751@itemx -mparanoid
12752@opindex mdp-isr-reload
12753@opindex mparanoid
12754Force the DP register to be saved on entry to an interrupt service
12755routine (ISR), reloaded to point to the data section, and restored on
12756exit from the ISR@. This should not be required unless someone has
12757violated the small memory model by modifying the DP register, say within
12758an object library.
12759
12760@item -mmpyi
12761@itemx -mno-mpyi
12762@opindex mmpyi
12763@opindex mno-mpyi
12764For the C3x use the 24-bit MPYI instruction for integer multiplies
12765instead of a library call to guarantee 32-bit results. Note that if one
12766of the operands is a constant, then the multiplication will be performed
12767using shifts and adds. If the @option{-mmpyi} option is not specified for the C3x,
12768then squaring operations are performed inline instead of a library call.
12769
12770@item -mfast-fix
12771@itemx -mno-fast-fix
12772@opindex mfast-fix
12773@opindex mno-fast-fix
12774The C3x/C4x FIX instruction to convert a floating point value to an
12775integer value chooses the nearest integer less than or equal to the
12776floating point value rather than to the nearest integer. Thus if the
12777floating point number is negative, the result will be incorrectly
12778truncated an additional code is necessary to detect and correct this
12779case. This option can be used to disable generation of the additional
12780code required to correct the result.
12781
12782@item -mrptb
12783@itemx -mno-rptb
12784@opindex mrptb
12785@opindex mno-rptb
12786Enable (disable) generation of repeat block sequences using the RPTB
12787instruction for zero overhead looping. The RPTB construct is only used
12788for innermost loops that do not call functions or jump across the loop
12789boundaries. There is no advantage having nested RPTB loops due to the
12790overhead required to save and restore the RC, RS, and RE registers.
12791This is enabled by default with @option{-O2}.
12792
12793@item -mrpts=@var{count}
12794@itemx -mno-rpts
12795@opindex mrpts
12796@opindex mno-rpts
12797Enable (disable) the use of the single instruction repeat instruction
12798RPTS@. If a repeat block contains a single instruction, and the loop
12799count can be guaranteed to be less than the value @var{count}, GCC will
12800emit a RPTS instruction instead of a RPTB@. If no value is specified,
12801then a RPTS will be emitted even if the loop count cannot be determined
12802at compile time. Note that the repeated instruction following RPTS does
12803not have to be reloaded from memory each iteration, thus freeing up the
12804CPU buses for operands. However, since interrupts are blocked by this
12805instruction, it is disabled by default.
12806
12807@item -mloop-unsigned
12808@itemx -mno-loop-unsigned
12809@opindex mloop-unsigned
12810@opindex mno-loop-unsigned
12811The maximum iteration count when using RPTS and RPTB (and DB on the C40)
12812is @math{2^{31} + 1} since these instructions test if the iteration count is
12813negative to terminate the loop. If the iteration count is unsigned
12814there is a possibility than the @math{2^{31} + 1} maximum iteration count may be
12815exceeded. This switch allows an unsigned iteration count.
12816
12817@item -mti
12818@opindex mti
12819Try to emit an assembler syntax that the TI assembler (asm30) is happy
12820with. This also enforces compatibility with the API employed by the TI
12821C3x C compiler. For example, long doubles are passed as structures
12822rather than in floating point registers.
12823
12824@item -mregparm
12825@itemx -mmemparm
12826@opindex mregparm
12827@opindex mmemparm
12828Generate code that uses registers (stack) for passing arguments to functions.
12829By default, arguments are passed in registers where possible rather
12830than by pushing arguments on to the stack.
12831
12832@item -mparallel-insns
12833@itemx -mno-parallel-insns
12834@opindex mparallel-insns
12835@opindex mno-parallel-insns
12836Allow the generation of parallel instructions. This is enabled by
12837default with @option{-O2}.
12838
12839@item -mparallel-mpy
12840@itemx -mno-parallel-mpy
12841@opindex mparallel-mpy
12842@opindex mno-parallel-mpy
12843Allow the generation of MPY||ADD and MPY||SUB parallel instructions,
12844provided @option{-mparallel-insns} is also specified. These instructions have
12845tight register constraints which can pessimize the code generation
12846of large functions.
12847
12848@end table
12849
12850@node V850 Options
12851@subsection V850 Options
12852@cindex V850 Options
12853
12854These @samp{-m} options are defined for V850 implementations:
12855
12856@table @gcctabopt
12857@item -mlong-calls
12858@itemx -mno-long-calls
12859@opindex mlong-calls
12860@opindex mno-long-calls
12861Treat all calls as being far away (near). If calls are assumed to be
12862far away, the compiler will always load the functions address up into a
12863register, and call indirect through the pointer.
12864
12865@item -mno-ep
12866@itemx -mep
12867@opindex mno-ep
12868@opindex mep
12869Do not optimize (do optimize) basic blocks that use the same index
12870pointer 4 or more times to copy pointer into the @code{ep} register, and
12871use the shorter @code{sld} and @code{sst} instructions. The @option{-mep}
12872option is on by default if you optimize.
12873
12874@item -mno-prolog-function
12875@itemx -mprolog-function
12876@opindex mno-prolog-function
12877@opindex mprolog-function
12878Do not use (do use) external functions to save and restore registers
12879at the prologue and epilogue of a function. The external functions
12880are slower, but use less code space if more than one function saves
12881the same number of registers. The @option{-mprolog-function} option
12882is on by default if you optimize.
12883
12884@item -mspace
12885@opindex mspace
12886Try to make the code as small as possible. At present, this just turns
12887on the @option{-mep} and @option{-mprolog-function} options.
12888
12889@item -mtda=@var{n}
12890@opindex mtda
12891Put static or global variables whose size is @var{n} bytes or less into
12892the tiny data area that register @code{ep} points to. The tiny data
12893area can hold up to 256 bytes in total (128 bytes for byte references).
12894
12895@item -msda=@var{n}
12896@opindex msda
12897Put static or global variables whose size is @var{n} bytes or less into
12898the small data area that register @code{gp} points to. The small data
12899area can hold up to 64 kilobytes.
12900
12901@item -mzda=@var{n}
12902@opindex mzda
12903Put static or global variables whose size is @var{n} bytes or less into
12904the first 32 kilobytes of memory.
12905
12906@item -mv850
12907@opindex mv850
12908Specify that the target processor is the V850.
12909
12910@item -mbig-switch
12911@opindex mbig-switch
12912Generate code suitable for big switch tables. Use this option only if
12913the assembler/linker complain about out of range branches within a switch
12914table.
12915
12916@item -mapp-regs
12917@opindex mapp-regs
12918This option will cause r2 and r5 to be used in the code generated by
12919the compiler. This setting is the default.
12920
12921@item -mno-app-regs
12922@opindex mno-app-regs
12923This option will cause r2 and r5 to be treated as fixed registers.
12924
12925@item -mv850e1
12926@opindex mv850e1
12927Specify that the target processor is the V850E1. The preprocessor
12928constants @samp{__v850e1__} and @samp{__v850e__} will be defined if
12929this option is used.
12930
12931@item -mv850e
12932@opindex mv850e
12933Specify that the target processor is the V850E@. The preprocessor
12934constant @samp{__v850e__} will be defined if this option is used.
12935
12936If neither @option{-mv850} nor @option{-mv850e} nor @option{-mv850e1}
12937are defined then a default target processor will be chosen and the
12938relevant @samp{__v850*__} preprocessor constant will be defined.
12939
12940The preprocessor constants @samp{__v850} and @samp{__v851__} are always
12941defined, regardless of which processor variant is the target.
12942
12943@item -mdisable-callt
12944@opindex mdisable-callt
12945This option will suppress generation of the CALLT instruction for the
12946v850e and v850e1 flavors of the v850 architecture. The default is
12947@option{-mno-disable-callt} which allows the CALLT instruction to be used.
12948
12949@end table
12950
12951@node VAX Options
12952@subsection VAX Options
12953@cindex VAX options
12954
12955These @samp{-m} options are defined for the VAX:
12956
12957@table @gcctabopt
12958@item -munix
12959@opindex munix
12960Do not output certain jump instructions (@code{aobleq} and so on)
12961that the Unix assembler for the VAX cannot handle across long
12962ranges.
12963
12964@item -mgnu
12965@opindex mgnu
12966Do output those jump instructions, on the assumption that you
12967will assemble with the GNU assembler.
12968
12969@item -mg
12970@opindex mg
12971Output code for g-format floating point numbers instead of d-format.
12972@end table
12973
12974@node x86-64 Options
12975@subsection x86-64 Options
12976@cindex x86-64 options
12977
12978These are listed under @xref{i386 and x86-64 Options}.
12979
12980@node Xstormy16 Options
12981@subsection Xstormy16 Options
12982@cindex Xstormy16 Options
12983
12984These options are defined for Xstormy16:
12985
12986@table @gcctabopt
12987@item -msim
12988@opindex msim
12989Choose startup files and linker script suitable for the simulator.
12990@end table
12991
12992@node Xtensa Options
12993@subsection Xtensa Options
12994@cindex Xtensa Options
12995
12996These options are supported for Xtensa targets:
12997
12998@table @gcctabopt
12999@item -mconst16
13000@itemx -mno-const16
13001@opindex mconst16
13002@opindex mno-const16
13003Enable or disable use of @code{CONST16} instructions for loading
13004constant values. The @code{CONST16} instruction is currently not a
13005standard option from Tensilica. When enabled, @code{CONST16}
13006instructions are always used in place of the standard @code{L32R}
13007instructions. The use of @code{CONST16} is enabled by default only if
13008the @code{L32R} instruction is not available.
13009
13010@item -mfused-madd
13011@itemx -mno-fused-madd
13012@opindex mfused-madd
13013@opindex mno-fused-madd
13014Enable or disable use of fused multiply/add and multiply/subtract
13015instructions in the floating-point option. This has no effect if the
13016floating-point option is not also enabled. Disabling fused multiply/add
13017and multiply/subtract instructions forces the compiler to use separate
13018instructions for the multiply and add/subtract operations. This may be
13019desirable in some cases where strict IEEE 754-compliant results are
13020required: the fused multiply add/subtract instructions do not round the
13021intermediate result, thereby producing results with @emph{more} bits of
13022precision than specified by the IEEE standard. Disabling fused multiply
13023add/subtract instructions also ensures that the program output is not
13024sensitive to the compiler's ability to combine multiply and add/subtract
13025operations.
13026
13027@item -mtext-section-literals
13028@itemx -mno-text-section-literals
13029@opindex mtext-section-literals
13030@opindex mno-text-section-literals
13031Control the treatment of literal pools. The default is
13032@option{-mno-text-section-literals}, which places literals in a separate
13033section in the output file. This allows the literal pool to be placed
13034in a data RAM/ROM, and it also allows the linker to combine literal
13035pools from separate object files to remove redundant literals and
13036improve code size. With @option{-mtext-section-literals}, the literals
13037are interspersed in the text section in order to keep them as close as
13038possible to their references. This may be necessary for large assembly
13039files.
13040
13041@item -mtarget-align
13042@itemx -mno-target-align
13043@opindex mtarget-align
13044@opindex mno-target-align
13045When this option is enabled, GCC instructs the assembler to
13046automatically align instructions to reduce branch penalties at the
13047expense of some code density. The assembler attempts to widen density
13048instructions to align branch targets and the instructions following call
13049instructions. If there are not enough preceding safe density
13050instructions to align a target, no widening will be performed. The
13051default is @option{-mtarget-align}. These options do not affect the
13052treatment of auto-aligned instructions like @code{LOOP}, which the
13053assembler will always align, either by widening density instructions or
13054by inserting no-op instructions.
13055
13056@item -mlongcalls
13057@itemx -mno-longcalls
13058@opindex mlongcalls
13059@opindex mno-longcalls
13060When this option is enabled, GCC instructs the assembler to translate
13061direct calls to indirect calls unless it can determine that the target
13062of a direct call is in the range allowed by the call instruction. This
13063translation typically occurs for calls to functions in other source
13064files. Specifically, the assembler translates a direct @code{CALL}
13065instruction into an @code{L32R} followed by a @code{CALLX} instruction.
13066The default is @option{-mno-longcalls}. This option should be used in
13067programs where the call target can potentially be out of range. This
13068option is implemented in the assembler, not the compiler, so the
13069assembly code generated by GCC will still show direct call
13070instructions---look at the disassembled object code to see the actual
13071instructions. Note that the assembler will use an indirect call for
13072every cross-file call, not just those that really will be out of range.
13073@end table
13074
13075@node zSeries Options
13076@subsection zSeries Options
13077@cindex zSeries options
13078
13079These are listed under @xref{S/390 and zSeries Options}.
13080
13081@node Code Gen Options
13082@section Options for Code Generation Conventions
13083@cindex code generation conventions
13084@cindex options, code generation
13085@cindex run-time options
13086
13087These machine-independent options control the interface conventions
13088used in code generation.
13089
13090Most of them have both positive and negative forms; the negative form
13091of @option{-ffoo} would be @option{-fno-foo}. In the table below, only
13092one of the forms is listed---the one which is not the default. You
13093can figure out the other form by either removing @samp{no-} or adding
13094it.
13095
13096@table @gcctabopt
13097@item -fbounds-check
13098@opindex fbounds-check
13099For front-ends that support it, generate additional code to check that
13100indices used to access arrays are within the declared range. This is
13101currently only supported by the Java and Fortran front-ends, where
13102this option defaults to true and false respectively.
13103
13104@item -ftrapv
13105@opindex ftrapv
13106This option generates traps for signed overflow on addition, subtraction,
13107multiplication operations.
13108
13109@item -fwrapv
13110@opindex fwrapv
13111This option instructs the compiler to assume that signed arithmetic
13112overflow of addition, subtraction and multiplication wraps around
13113using twos-complement representation. This flag enables some optimizations
13114and disables others. This option is enabled by default for the Java
13115front-end, as required by the Java language specification.
13116
13117@item -fexceptions
13118@opindex fexceptions
13119Enable exception handling. Generates extra code needed to propagate
13120exceptions. For some targets, this implies GCC will generate frame
13121unwind information for all functions, which can produce significant data
13122size overhead, although it does not affect execution. If you do not
13123specify this option, GCC will enable it by default for languages like
13124C++ which normally require exception handling, and disable it for
13125languages like C that do not normally require it. However, you may need
13126to enable this option when compiling C code that needs to interoperate
13127properly with exception handlers written in C++. You may also wish to
13128disable this option if you are compiling older C++ programs that don't
13129use exception handling.
13130
13131@item -fnon-call-exceptions
13132@opindex fnon-call-exceptions
13133Generate code that allows trapping instructions to throw exceptions.
13134Note that this requires platform-specific runtime support that does
13135not exist everywhere. Moreover, it only allows @emph{trapping}
13136instructions to throw exceptions, i.e.@: memory references or floating
13137point instructions. It does not allow exceptions to be thrown from
13138arbitrary signal handlers such as @code{SIGALRM}.
13139
13140@item -funwind-tables
13141@opindex funwind-tables
13142Similar to @option{-fexceptions}, except that it will just generate any needed
13143static data, but will not affect the generated code in any other way.
13144You will normally not enable this option; instead, a language processor
13145that needs this handling would enable it on your behalf.
13146
13147@item -fasynchronous-unwind-tables
13148@opindex fasynchronous-unwind-tables
13149Generate unwind table in dwarf2 format, if supported by target machine. The
13150table is exact at each instruction boundary, so it can be used for stack
13151unwinding from asynchronous events (such as debugger or garbage collector).
13152
13153@item -fpcc-struct-return
13154@opindex fpcc-struct-return
13155Return ``short'' @code{struct} and @code{union} values in memory like
13156longer ones, rather than in registers. This convention is less
13157efficient, but it has the advantage of allowing intercallability between
13158GCC-compiled files and files compiled with other compilers, particularly
13159the Portable C Compiler (pcc).
13160
13161The precise convention for returning structures in memory depends
13162on the target configuration macros.
13163
13164Short structures and unions are those whose size and alignment match
13165that of some integer type.
13166
13167@strong{Warning:} code compiled with the @option{-fpcc-struct-return}
13168switch is not binary compatible with code compiled with the
13169@option{-freg-struct-return} switch.
13170Use it to conform to a non-default application binary interface.
13171
13172@item -freg-struct-return
13173@opindex freg-struct-return
13174Return @code{struct} and @code{union} values in registers when possible.
13175This is more efficient for small structures than
13176@option{-fpcc-struct-return}.
13177
13178If you specify neither @option{-fpcc-struct-return} nor
13179@option{-freg-struct-return}, GCC defaults to whichever convention is
13180standard for the target. If there is no standard convention, GCC
13181defaults to @option{-fpcc-struct-return}, except on targets where GCC is
13182the principal compiler. In those cases, we can choose the standard, and
13183we chose the more efficient register return alternative.
13184
13185@strong{Warning:} code compiled with the @option{-freg-struct-return}
13186switch is not binary compatible with code compiled with the
13187@option{-fpcc-struct-return} switch.
13188Use it to conform to a non-default application binary interface.
13189
13190@item -fshort-enums
13191@opindex fshort-enums
13192Allocate to an @code{enum} type only as many bytes as it needs for the
13193declared range of possible values. Specifically, the @code{enum} type
13194will be equivalent to the smallest integer type which has enough room.
13195
13196@strong{Warning:} the @option{-fshort-enums} switch causes GCC to generate
13197code that is not binary compatible with code generated without that switch.
13198Use it to conform to a non-default application binary interface.
13199
13200@item -fshort-double
13201@opindex fshort-double
13202Use the same size for @code{double} as for @code{float}.
13203
13204@strong{Warning:} the @option{-fshort-double} switch causes GCC to generate
13205code that is not binary compatible with code generated without that switch.
13206Use it to conform to a non-default application binary interface.
13207
13208@item -fshort-wchar
13209@opindex fshort-wchar
13210Override the underlying type for @samp{wchar_t} to be @samp{short
13211unsigned int} instead of the default for the target. This option is
13212useful for building programs to run under WINE@.
13213
13214@strong{Warning:} the @option{-fshort-wchar} switch causes GCC to generate
13215code that is not binary compatible with code generated without that switch.
13216Use it to conform to a non-default application binary interface.
13217
13218@item -fno-common
13219@opindex fno-common
13220In C, allocate even uninitialized global variables in the data section of the
13221object file, rather than generating them as common blocks. This has the
13222effect that if the same variable is declared (without @code{extern}) in
13223two different compilations, you will get an error when you link them.
13224The only reason this might be useful is if you wish to verify that the
13225program will work on other systems which always work this way.
13226
13227@item -fno-ident
13228@opindex fno-ident
13229Ignore the @samp{#ident} directive.
13230
13231@item -finhibit-size-directive
13232@opindex finhibit-size-directive
13233Don't output a @code{.size} assembler directive, or anything else that
13234would cause trouble if the function is split in the middle, and the
13235two halves are placed at locations far apart in memory. This option is
13236used when compiling @file{crtstuff.c}; you should not need to use it
13237for anything else.
13238
13239@item -fverbose-asm
13240@opindex fverbose-asm
13241Put extra commentary information in the generated assembly code to
13242make it more readable. This option is generally only of use to those
13243who actually need to read the generated assembly code (perhaps while
13244debugging the compiler itself).
13245
13246@option{-fno-verbose-asm}, the default, causes the
13247extra information to be omitted and is useful when comparing two assembler
13248files.
13249
13250@item -fpic
13251@opindex fpic
13252@cindex global offset table
13253@cindex PIC
13254Generate position-independent code (PIC) suitable for use in a shared
13255library, if supported for the target machine. Such code accesses all
13256constant addresses through a global offset table (GOT)@. The dynamic
13257loader resolves the GOT entries when the program starts (the dynamic
13258loader is not part of GCC; it is part of the operating system). If
13259the GOT size for the linked executable exceeds a machine-specific
13260maximum size, you get an error message from the linker indicating that
13261@option{-fpic} does not work; in that case, recompile with @option{-fPIC}
13262instead. (These maximums are 8k on the SPARC and 32k
13263on the m68k and RS/6000. The 386 has no such limit.)
13264
13265Position-independent code requires special support, and therefore works
13266only on certain machines. For the 386, GCC supports PIC for System V
13267but not for the Sun 386i. Code generated for the IBM RS/6000 is always
13268position-independent.
13269
13270When this flag is set, the macros @code{__pic__} and @code{__PIC__}
13271are defined to 1.
13272
13273@item -fPIC
13274@opindex fPIC
13275If supported for the target machine, emit position-independent code,
13276suitable for dynamic linking and avoiding any limit on the size of the
13277global offset table. This option makes a difference on the m68k,
13278PowerPC and SPARC@.
13279
13280Position-independent code requires special support, and therefore works
13281only on certain machines.
13282
13283When this flag is set, the macros @code{__pic__} and @code{__PIC__}
13284are defined to 2.
13285
13286@item -fpie
13287@itemx -fPIE
13288@opindex fpie
13289@opindex fPIE
13290These options are similar to @option{-fpic} and @option{-fPIC}, but
13291generated position independent code can be only linked into executables.
13292Usually these options are used when @option{-pie} GCC option will be
13293used during linking.
13294
13295@item -fno-jump-tables
13296@opindex fno-jump-tables
13297Do not use jump tables for switch statements even where it would be
13298more efficient than other code generation strategies. This option is
13299of use in conjunction with @option{-fpic} or @option{-fPIC} for
13300building code which forms part of a dynamic linker and cannot
13301reference the address of a jump table. On some targets, jump tables
13302do not require a GOT and this option is not needed.
13303
13304@item -ffixed-@var{reg}
13305@opindex ffixed
13306Treat the register named @var{reg} as a fixed register; generated code
13307should never refer to it (except perhaps as a stack pointer, frame
13308pointer or in some other fixed role).
13309
13310@var{reg} must be the name of a register. The register names accepted
13311are machine-specific and are defined in the @code{REGISTER_NAMES}
13312macro in the machine description macro file.
13313
13314This flag does not have a negative form, because it specifies a
13315three-way choice.
13316
13317@item -fcall-used-@var{reg}
13318@opindex fcall-used
13319Treat the register named @var{reg} as an allocable register that is
13320clobbered by function calls. It may be allocated for temporaries or
13321variables that do not live across a call. Functions compiled this way
13322will not save and restore the register @var{reg}.
13323
13324It is an error to used this flag with the frame pointer or stack pointer.
13325Use of this flag for other registers that have fixed pervasive roles in
13326the machine's execution model will produce disastrous results.
13327
13328This flag does not have a negative form, because it specifies a
13329three-way choice.
13330
13331@item -fcall-saved-@var{reg}
13332@opindex fcall-saved
13333Treat the register named @var{reg} as an allocable register saved by
13334functions. It may be allocated even for temporaries or variables that
13335live across a call. Functions compiled this way will save and restore
13336the register @var{reg} if they use it.
13337
13338It is an error to used this flag with the frame pointer or stack pointer.
13339Use of this flag for other registers that have fixed pervasive roles in
13340the machine's execution model will produce disastrous results.
13341
13342A different sort of disaster will result from the use of this flag for
13343a register in which function values may be returned.
13344
13345This flag does not have a negative form, because it specifies a
13346three-way choice.
13347
13348@item -fpack-struct[=@var{n}]
13349@opindex fpack-struct
13350Without a value specified, pack all structure members together without
13351holes. When a value is specified (which must be a small power of two), pack
13352structure members according to this value, representing the maximum
13353alignment (that is, objects with default alignment requirements larger than
13354this will be output potentially unaligned at the next fitting location.
13355
13356@strong{Warning:} the @option{-fpack-struct} switch causes GCC to generate
13357code that is not binary compatible with code generated without that switch.
13358Additionally, it makes the code suboptimal.
13359Use it to conform to a non-default application binary interface.
13360
13361@item -finstrument-functions
13362@opindex finstrument-functions
13363Generate instrumentation calls for entry and exit to functions. Just
13364after function entry and just before function exit, the following
13365profiling functions will be called with the address of the current
13366function and its call site. (On some platforms,
13367@code{__builtin_return_address} does not work beyond the current
13368function, so the call site information may not be available to the
13369profiling functions otherwise.)
13370
13371@smallexample
13372void __cyg_profile_func_enter (void *this_fn,
13373 void *call_site);
13374void __cyg_profile_func_exit (void *this_fn,
13375 void *call_site);
13376@end smallexample
13377
13378The first argument is the address of the start of the current function,
13379which may be looked up exactly in the symbol table.
13380
13381This instrumentation is also done for functions expanded inline in other
13382functions. The profiling calls will indicate where, conceptually, the
13383inline function is entered and exited. This means that addressable
13384versions of such functions must be available. If all your uses of a
13385function are expanded inline, this may mean an additional expansion of
13386code size. If you use @samp{extern inline} in your C code, an
13387addressable version of such functions must be provided. (This is
13388normally the case anyways, but if you get lucky and the optimizer always
13389expands the functions inline, you might have gotten away without
13390providing static copies.)
13391
13392A function may be given the attribute @code{no_instrument_function}, in
13393which case this instrumentation will not be done. This can be used, for
13394example, for the profiling functions listed above, high-priority
13395interrupt routines, and any functions from which the profiling functions
13396cannot safely be called (perhaps signal handlers, if the profiling
13397routines generate output or allocate memory).
13398
13399@item -finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{}
13400@opindex finstrument-functions-exclude-file-list
13401
13402Set the list of functions that are excluded from instrumentation (see
13403the description of @code{-finstrument-functions}). If the file that
13404contains a function definition matches with one of @var{file}, then
13405that function is not instrumented. The match is done on substrings:
13406if the @var{file} parameter is a substring of the file name, it is
13407considered to be a match.
13408
13409For example,
13410@code{-finstrument-functions-exclude-file-list=/bits/stl,include/sys}
13411will exclude any inline function defined in files whose pathnames
13412contain @code{/bits/stl} or @code{include/sys}.
13413
13414If, for some reason, you want to include letter @code{','} in one of
13415@var{sym}, write @code{'\,'}. For example,
13416@code{-finstrument-functions-exclude-file-list='\,\,tmp'}
13417(note the single quote surrounding the option).
13418
13419@item -finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{}
13420@opindex finstrument-functions-exclude-function-list
13421
13422This is similar to @code{-finstrument-functions-exclude-file-list},
13423but this option sets the list of function names to be excluded from
13424instrumentation. The function name to be matched is its user-visible
13425name, such as @code{vector<int> blah(const vector<int> &)}, not the
13426internal mangled name (e.g., @code{_Z4blahRSt6vectorIiSaIiEE}). The
13427match is done on substrings: if the @var{sym} parameter is a substring
13428of the function name, it is considered to be a match.
13429
13430@item -fstack-check
13431@opindex fstack-check
13432Generate code to verify that you do not go beyond the boundary of the
13433stack. You should specify this flag if you are running in an
13434environment with multiple threads, but only rarely need to specify it in
13435a single-threaded environment since stack overflow is automatically
13436detected on nearly all systems if there is only one stack.
13437
13438Note that this switch does not actually cause checking to be done; the
13439operating system must do that. The switch causes generation of code
13440to ensure that the operating system sees the stack being extended.
13441
13442@item -fstack-limit-register=@var{reg}
13443@itemx -fstack-limit-symbol=@var{sym}
13444@itemx -fno-stack-limit
13445@opindex fstack-limit-register
13446@opindex fstack-limit-symbol
13447@opindex fno-stack-limit
13448Generate code to ensure that the stack does not grow beyond a certain value,
13449either the value of a register or the address of a symbol. If the stack
13450would grow beyond the value, a signal is raised. For most targets,
13451the signal is raised before the stack overruns the boundary, so
13452it is possible to catch the signal without taking special precautions.
13453
13454For instance, if the stack starts at absolute address @samp{0x80000000}
13455and grows downwards, you can use the flags
13456@option{-fstack-limit-symbol=__stack_limit} and
13457@option{-Wl,--defsym,__stack_limit=0x7ffe0000} to enforce a stack limit
13458of 128KB@. Note that this may only work with the GNU linker.
13459
13460@cindex aliasing of parameters
13461@cindex parameters, aliased
13462@item -fargument-alias
13463@itemx -fargument-noalias
13464@itemx -fargument-noalias-global
13465@itemx -fargument-noalias-anything
13466@opindex fargument-alias
13467@opindex fargument-noalias
13468@opindex fargument-noalias-global
13469@opindex fargument-noalias-anything
13470Specify the possible relationships among parameters and between
13471parameters and global data.
13472
13473@option{-fargument-alias} specifies that arguments (parameters) may
13474alias each other and may alias global storage.@*
13475@option{-fargument-noalias} specifies that arguments do not alias
13476each other, but may alias global storage.@*
13477@option{-fargument-noalias-global} specifies that arguments do not
13478alias each other and do not alias global storage.
13479@option{-fargument-noalias-anything} specifies that arguments do not
13480alias any other storage.
13481
13482Each language will automatically use whatever option is required by
13483the language standard. You should not need to use these options yourself.
13484
13485@item -fleading-underscore
13486@opindex fleading-underscore
13487This option and its counterpart, @option{-fno-leading-underscore}, forcibly
13488change the way C symbols are represented in the object file. One use
13489is to help link with legacy assembly code.
13490
13491@strong{Warning:} the @option{-fleading-underscore} switch causes GCC to
13492generate code that is not binary compatible with code generated without that
13493switch. Use it to conform to a non-default application binary interface.
13494Not all targets provide complete support for this switch.
13495
13496@item -ftls-model=@var{model}
13497Alter the thread-local storage model to be used (@pxref{Thread-Local}).
13498The @var{model} argument should be one of @code{global-dynamic},
13499@code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
13500
13501The default without @option{-fpic} is @code{initial-exec}; with
13502@option{-fpic} the default is @code{global-dynamic}.
13503
13504@item -fvisibility=@var{default|internal|hidden|protected}
13505@opindex fvisibility
13506Set the default ELF image symbol visibility to the specified option---all
13507symbols will be marked with this unless overridden within the code.
13508Using this feature can very substantially improve linking and
13509load times of shared object libraries, produce more optimized
13510code, provide near-perfect API export and prevent symbol clashes.
13511It is @strong{strongly} recommended that you use this in any shared objects
13512you distribute.
13513
13514Despite the nomenclature, @code{default} always means public ie;
13515available to be linked against from outside the shared object.
13516@code{protected} and @code{internal} are pretty useless in real-world
13517usage so the only other commonly used option will be @code{hidden}.
13518The default if @option{-fvisibility} isn't specified is
13519@code{default}, i.e., make every
13520symbol public---this causes the same behavior as previous versions of
13521GCC@.
13522
13523A good explanation of the benefits offered by ensuring ELF
13524symbols have the correct visibility is given by ``How To Write
13525Shared Libraries'' by Ulrich Drepper (which can be found at
13526@w{@uref{http://people.redhat.com/~drepper/}})---however a superior
13527solution made possible by this option to marking things hidden when
13528the default is public is to make the default hidden and mark things
13529public. This is the norm with DLL's on Windows and with @option{-fvisibility=hidden}
13530and @code{__attribute__ ((visibility("default")))} instead of
13531@code{__declspec(dllexport)} you get almost identical semantics with
13532identical syntax. This is a great boon to those working with
13533cross-platform projects.
13534
13535For those adding visibility support to existing code, you may find
13536@samp{#pragma GCC visibility} of use. This works by you enclosing
13537the declarations you wish to set visibility for with (for example)
13538@samp{#pragma GCC visibility push(hidden)} and
13539@samp{#pragma GCC visibility pop}.
13540Bear in mind that symbol visibility should be viewed @strong{as
13541part of the API interface contract} and thus all new code should
13542always specify visibility when it is not the default ie; declarations
13543only for use within the local DSO should @strong{always} be marked explicitly
13544as hidden as so to avoid PLT indirection overheads---making this
13545abundantly clear also aids readability and self-documentation of the code.
13546Note that due to ISO C++ specification requirements, operator new and
13547operator delete must always be of default visibility.
13548
13549Be aware that headers from outside your project, in particular system
13550headers and headers from any other library you use, may not be
13551expecting to be compiled with visibility other than the default. You
13552may need to explicitly say @samp{#pragma GCC visibility push(default)}
13553before including any such headers.
13554
13555@samp{extern} declarations are not affected by @samp{-fvisibility}, so
13556a lot of code can be recompiled with @samp{-fvisibility=hidden} with
13557no modifications. However, this means that calls to @samp{extern}
13558functions with no explicit visibility will use the PLT, so it is more
13559effective to use @samp{__attribute ((visibility))} and/or
13560@samp{#pragma GCC visibility} to tell the compiler which @samp{extern}
13561declarations should be treated as hidden.
13562
13563Note that @samp{-fvisibility} does affect C++ vague linkage
13564entities. This means that, for instance, an exception class that will
13565be thrown between DSOs must be explicitly marked with default
13566visibility so that the @samp{type_info} nodes will be unified between
13567the DSOs.
13568
13569An overview of these techniques, their benefits and how to use them
13570is at @w{@uref{http://gcc.gnu.org/wiki/Visibility}}.
13571
13572@end table
13573
13574@c man end
13575
13576@node Environment Variables
13577@section Environment Variables Affecting GCC
13578@cindex environment variables
13579
13580@c man begin ENVIRONMENT
13581This section describes several environment variables that affect how GCC
13582operates. Some of them work by specifying directories or prefixes to use
13583when searching for various kinds of files. Some are used to specify other
13584aspects of the compilation environment.
13585
13586Note that you can also specify places to search using options such as
13587@option{-B}, @option{-I} and @option{-L} (@pxref{Directory Options}). These
13588take precedence over places specified using environment variables, which
13589in turn take precedence over those specified by the configuration of GCC@.
13590@xref{Driver,, Controlling the Compilation Driver @file{gcc}, gccint,
13591GNU Compiler Collection (GCC) Internals}.
13592
13593@table @env
13594@item LANG
13595@itemx LC_CTYPE
13596@c @itemx LC_COLLATE
13597@itemx LC_MESSAGES
13598@c @itemx LC_MONETARY
13599@c @itemx LC_NUMERIC
13600@c @itemx LC_TIME
13601@itemx LC_ALL
13602@findex LANG
13603@findex LC_CTYPE
13604@c @findex LC_COLLATE
13605@findex LC_MESSAGES
13606@c @findex LC_MONETARY
13607@c @findex LC_NUMERIC
13608@c @findex LC_TIME
13609@findex LC_ALL
13610@cindex locale
13611These environment variables control the way that GCC uses
13612localization information that allow GCC to work with different
13613national conventions. GCC inspects the locale categories
13614@env{LC_CTYPE} and @env{LC_MESSAGES} if it has been configured to do
13615so. These locale categories can be set to any value supported by your
13616installation. A typical value is @samp{en_GB.UTF-8} for English in the United
13617Kingdom encoded in UTF-8.
13618
13619The @env{LC_CTYPE} environment variable specifies character
13620classification. GCC uses it to determine the character boundaries in
13621a string; this is needed for some multibyte encodings that contain quote
13622and escape characters that would otherwise be interpreted as a string
13623end or escape.
13624
13625The @env{LC_MESSAGES} environment variable specifies the language to
13626use in diagnostic messages.
13627
13628If the @env{LC_ALL} environment variable is set, it overrides the value
13629of @env{LC_CTYPE} and @env{LC_MESSAGES}; otherwise, @env{LC_CTYPE}
13630and @env{LC_MESSAGES} default to the value of the @env{LANG}
13631environment variable. If none of these variables are set, GCC
13632defaults to traditional C English behavior.
13633
13634@item TMPDIR
13635@findex TMPDIR
13636If @env{TMPDIR} is set, it specifies the directory to use for temporary
13637files. GCC uses temporary files to hold the output of one stage of
13638compilation which is to be used as input to the next stage: for example,
13639the output of the preprocessor, which is the input to the compiler
13640proper.
13641
13642@item GCC_EXEC_PREFIX
13643@findex GCC_EXEC_PREFIX
13644If @env{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the
13645names of the subprograms executed by the compiler. No slash is added
13646when this prefix is combined with the name of a subprogram, but you can
13647specify a prefix that ends with a slash if you wish.
13648
13649If @env{GCC_EXEC_PREFIX} is not set, GCC will attempt to figure out
13650an appropriate prefix to use based on the pathname it was invoked with.
13651
13652If GCC cannot find the subprogram using the specified prefix, it
13653tries looking in the usual places for the subprogram.
13654
13655The default value of @env{GCC_EXEC_PREFIX} is
13656@file{@var{prefix}/lib/gcc/} where @var{prefix} is the value
13657of @code{prefix} when you ran the @file{configure} script.
13658
13659Other prefixes specified with @option{-B} take precedence over this prefix.
13660
13661This prefix is also used for finding files such as @file{crt0.o} that are
13662used for linking.
13663
13664In addition, the prefix is used in an unusual way in finding the
13665directories to search for header files. For each of the standard
13666directories whose name normally begins with @samp{/usr/local/lib/gcc}
13667(more precisely, with the value of @env{GCC_INCLUDE_DIR}), GCC tries
13668replacing that beginning with the specified prefix to produce an
13669alternate directory name. Thus, with @option{-Bfoo/}, GCC will search
13670@file{foo/bar} where it would normally search @file{/usr/local/lib/bar}.
13671These alternate directories are searched first; the standard directories
13672come next.
13673
13674@item COMPILER_PATH
13675@findex COMPILER_PATH
13676The value of @env{COMPILER_PATH} is a colon-separated list of
13677directories, much like @env{PATH}. GCC tries the directories thus
13678specified when searching for subprograms, if it can't find the
13679subprograms using @env{GCC_EXEC_PREFIX}.
13680
13681@item LIBRARY_PATH
13682@findex LIBRARY_PATH
13683The value of @env{LIBRARY_PATH} is a colon-separated list of
13684directories, much like @env{PATH}. When configured as a native compiler,
13685GCC tries the directories thus specified when searching for special
13686linker files, if it can't find them using @env{GCC_EXEC_PREFIX}. Linking
13687using GCC also uses these directories when searching for ordinary
13688libraries for the @option{-l} option (but directories specified with
13689@option{-L} come first).
13690
13691@item LANG
13692@findex LANG
13693@cindex locale definition
13694This variable is used to pass locale information to the compiler. One way in
13695which this information is used is to determine the character set to be used
13696when character literals, string literals and comments are parsed in C and C++.
13697When the compiler is configured to allow multibyte characters,
13698the following values for @env{LANG} are recognized:
13699
13700@table @samp
13701@item C-JIS
13702Recognize JIS characters.
13703@item C-SJIS
13704Recognize SJIS characters.
13705@item C-EUCJP
13706Recognize EUCJP characters.
13707@end table
13708
13709If @env{LANG} is not defined, or if it has some other value, then the
13710compiler will use mblen and mbtowc as defined by the default locale to
13711recognize and translate multibyte characters.
13712@end table
13713
13714@noindent
13715Some additional environments variables affect the behavior of the
13716preprocessor.
13717
13718@include cppenv.texi
13719
13720@c man end
13721
13722@node Precompiled Headers
13723@section Using Precompiled Headers
13724@cindex precompiled headers
13725@cindex speed of compilation
13726
13727Often large projects have many header files that are included in every
13728source file. The time the compiler takes to process these header files
13729over and over again can account for nearly all of the time required to
13730build the project. To make builds faster, GCC allows users to
13731`precompile' a header file; then, if builds can use the precompiled
13732header file they will be much faster.
13733
13734To create a precompiled header file, simply compile it as you would any
13735other file, if necessary using the @option{-x} option to make the driver
13736treat it as a C or C++ header file. You will probably want to use a
13737tool like @command{make} to keep the precompiled header up-to-date when
13738the headers it contains change.
13739
13740A precompiled header file will be searched for when @code{#include} is
13741seen in the compilation. As it searches for the included file
13742(@pxref{Search Path,,Search Path,cpp,The C Preprocessor}) the
13743compiler looks for a precompiled header in each directory just before it
13744looks for the include file in that directory. The name searched for is
13745the name specified in the @code{#include} with @samp{.gch} appended. If
13746the precompiled header file can't be used, it is ignored.
13747
13748For instance, if you have @code{#include "all.h"}, and you have
13749@file{all.h.gch} in the same directory as @file{all.h}, then the
13750precompiled header file will be used if possible, and the original
13751header will be used otherwise.
13752
13753Alternatively, you might decide to put the precompiled header file in a
13754directory and use @option{-I} to ensure that directory is searched
13755before (or instead of) the directory containing the original header.
13756Then, if you want to check that the precompiled header file is always
13757used, you can put a file of the same name as the original header in this
13758directory containing an @code{#error} command.
13759
13760This also works with @option{-include}. So yet another way to use
13761precompiled headers, good for projects not designed with precompiled
13762header files in mind, is to simply take most of the header files used by
13763a project, include them from another header file, precompile that header
13764file, and @option{-include} the precompiled header. If the header files
13765have guards against multiple inclusion, they will be skipped because
13766they've already been included (in the precompiled header).
13767
13768If you need to precompile the same header file for different
13769languages, targets, or compiler options, you can instead make a
13770@emph{directory} named like @file{all.h.gch}, and put each precompiled
13771header in the directory, perhaps using @option{-o}. It doesn't matter
13772what you call the files in the directory, every precompiled header in
13773the directory will be considered. The first precompiled header
13774encountered in the directory that is valid for this compilation will
13775be used; they're searched in no particular order.
13776
13777There are many other possibilities, limited only by your imagination,
13778good sense, and the constraints of your build system.
13779
13780A precompiled header file can be used only when these conditions apply:
13781
13782@itemize
13783@item
13784Only one precompiled header can be used in a particular compilation.
13785
13786@item
13787A precompiled header can't be used once the first C token is seen. You
13788can have preprocessor directives before a precompiled header; you can
13789even include a precompiled header from inside another header, so long as
13790there are no C tokens before the @code{#include}.
13791
13792@item
13793The precompiled header file must be produced for the same language as
13794the current compilation. You can't use a C precompiled header for a C++
13795compilation.
13796
13797@item
13798The precompiled header file must have been produced by the same compiler
13799binary as the current compilation is using.
13800
13801@item
13802Any macros defined before the precompiled header is included must
13803either be defined in the same way as when the precompiled header was
13804generated, or must not affect the precompiled header, which usually
13805means that they don't appear in the precompiled header at all.
13806
13807The @option{-D} option is one way to define a macro before a
13808precompiled header is included; using a @code{#define} can also do it.
13809There are also some options that define macros implicitly, like
13810@option{-O} and @option{-Wdeprecated}; the same rule applies to macros
13811defined this way.
13812
13813@item If debugging information is output when using the precompiled
13814header, using @option{-g} or similar, the same kind of debugging information
13815must have been output when building the precompiled header. However,
13816a precompiled header built using @option{-g} can be used in a compilation
13817when no debugging information is being output.
13818
13819@item The same @option{-m} options must generally be used when building
13820and using the precompiled header. @xref{Submodel Options},
13821for any cases where this rule is relaxed.
13822
13823@item Each of the following options must be the same when building and using
13824the precompiled header:
13825
13826@gccoptlist{-fexceptions -funit-at-a-time}
13827
13828@item
13829Some other command-line options starting with @option{-f},
13830@option{-p}, or @option{-O} must be defined in the same way as when
13831the precompiled header was generated. At present, it's not clear
13832which options are safe to change and which are not; the safest choice
13833is to use exactly the same options when generating and using the
13834precompiled header. The following are known to be safe:
13835
13836@gccoptlist{-fmessage-length= -fpreprocessed
13837-fsched-interblock -fsched-spec -fsched-spec-load -fsched-spec-load-dangerous
13838-fsched-verbose=<number> -fschedule-insns -fvisibility=
13839-pedantic-errors}
13840
13841@end itemize
13842
13843For all of these except the last, the compiler will automatically
13844ignore the precompiled header if the conditions aren't met. If you
13845find an option combination that doesn't work and doesn't cause the
13846precompiled header to be ignored, please consider filing a bug report,
13847see @ref{Bugs}.
13848
13849If you do use differing options when generating and using the
13850precompiled header, the actual behavior will be a mixture of the
13851behavior for the options. For instance, if you use @option{-g} to
13852generate the precompiled header but not when using it, you may or may
13853not get debugging information for routines in the precompiled header.
13854
13855@node Running Protoize
13856@section Running Protoize
13857
13858The program @code{protoize} is an optional part of GCC@. You can use
13859it to add prototypes to a program, thus converting the program to ISO
13860C in one respect. The companion program @code{unprotoize} does the
13861reverse: it removes argument types from any prototypes that are found.
13862
13863When you run these programs, you must specify a set of source files as
13864command line arguments. The conversion programs start out by compiling
13865these files to see what functions they define. The information gathered
13866about a file @var{foo} is saved in a file named @file{@var{foo}.X}.
13867
13868After scanning comes actual conversion. The specified files are all
13869eligible to be converted; any files they include (whether sources or
13870just headers) are eligible as well.
13871
13872But not all the eligible files are converted. By default,
13873@code{protoize} and @code{unprotoize} convert only source and header
13874files in the current directory. You can specify additional directories
13875whose files should be converted with the @option{-d @var{directory}}
13876option. You can also specify particular files to exclude with the
13877@option{-x @var{file}} option. A file is converted if it is eligible, its
13878directory name matches one of the specified directory names, and its
13879name within the directory has not been excluded.
13880
13881Basic conversion with @code{protoize} consists of rewriting most
13882function definitions and function declarations to specify the types of
13883the arguments. The only ones not rewritten are those for varargs
13884functions.
13885
13886@code{protoize} optionally inserts prototype declarations at the
13887beginning of the source file, to make them available for any calls that
13888precede the function's definition. Or it can insert prototype
13889declarations with block scope in the blocks where undeclared functions
13890are called.
13891
13892Basic conversion with @code{unprotoize} consists of rewriting most
13893function declarations to remove any argument types, and rewriting
13894function definitions to the old-style pre-ISO form.
13895
13896Both conversion programs print a warning for any function declaration or
13897definition that they can't convert. You can suppress these warnings
13898with @option{-q}.
13899
13900The output from @code{protoize} or @code{unprotoize} replaces the
13901original source file. The original file is renamed to a name ending
13902with @samp{.save} (for DOS, the saved filename ends in @samp{.sav}
13903without the original @samp{.c} suffix). If the @samp{.save} (@samp{.sav}
13904for DOS) file already exists, then the source file is simply discarded.
13905
13906@code{protoize} and @code{unprotoize} both depend on GCC itself to
13907scan the program and collect information about the functions it uses.
13908So neither of these programs will work until GCC is installed.
13909
13910Here is a table of the options you can use with @code{protoize} and
13911@code{unprotoize}. Each option works with both programs unless
13912otherwise stated.
13913
13914@table @code
13915@item -B @var{directory}
13916Look for the file @file{SYSCALLS.c.X} in @var{directory}, instead of the
13917usual directory (normally @file{/usr/local/lib}). This file contains
13918prototype information about standard system functions. This option
13919applies only to @code{protoize}.
13920
13921@item -c @var{compilation-options}
13922Use @var{compilation-options} as the options when running @command{gcc} to
13923produce the @samp{.X} files. The special option @option{-aux-info} is
13924always passed in addition, to tell @command{gcc} to write a @samp{.X} file.
13925
13926Note that the compilation options must be given as a single argument to
13927@code{protoize} or @code{unprotoize}. If you want to specify several
13928@command{gcc} options, you must quote the entire set of compilation options
13929to make them a single word in the shell.
13930
13931There are certain @command{gcc} arguments that you cannot use, because they
13932would produce the wrong kind of output. These include @option{-g},
13933@option{-O}, @option{-c}, @option{-S}, and @option{-o} If you include these in
13934the @var{compilation-options}, they are ignored.
13935
13936@item -C
13937Rename files to end in @samp{.C} (@samp{.cc} for DOS-based file
13938systems) instead of @samp{.c}. This is convenient if you are converting
13939a C program to C++. This option applies only to @code{protoize}.
13940
13941@item -g
13942Add explicit global declarations. This means inserting explicit
13943declarations at the beginning of each source file for each function
13944that is called in the file and was not declared. These declarations
13945precede the first function definition that contains a call to an
13946undeclared function. This option applies only to @code{protoize}.
13947
13948@item -i @var{string}
13949Indent old-style parameter declarations with the string @var{string}.
13950This option applies only to @code{protoize}.
13951
13952@code{unprotoize} converts prototyped function definitions to old-style
13953function definitions, where the arguments are declared between the
13954argument list and the initial @samp{@{}. By default, @code{unprotoize}
13955uses five spaces as the indentation. If you want to indent with just
13956one space instead, use @option{-i " "}.
13957
13958@item -k
13959Keep the @samp{.X} files. Normally, they are deleted after conversion
13960is finished.
13961
13962@item -l
13963Add explicit local declarations. @code{protoize} with @option{-l} inserts
13964a prototype declaration for each function in each block which calls the
13965function without any declaration. This option applies only to
13966@code{protoize}.
13967
13968@item -n
13969Make no real changes. This mode just prints information about the conversions
13970that would have been done without @option{-n}.
13971
13972@item -N
13973Make no @samp{.save} files. The original files are simply deleted.
13974Use this option with caution.
13975
13976@item -p @var{program}
13977Use the program @var{program} as the compiler. Normally, the name
13978@file{gcc} is used.
13979
13980@item -q
13981Work quietly. Most warnings are suppressed.
13982
13983@item -v
13984Print the version number, just like @option{-v} for @command{gcc}.
13985@end table
13986
13987If you need special compiler options to compile one of your program's
13988source files, then you should generate that file's @samp{.X} file
13989specially, by running @command{gcc} on that source file with the
13990appropriate options and the option @option{-aux-info}. Then run
13991@code{protoize} on the entire set of files. @code{protoize} will use
13992the existing @samp{.X} file because it is newer than the source file.
13993For example:
13994
13995@smallexample
13996gcc -Dfoo=bar file1.c -aux-info file1.X
13997protoize *.c
13998@end smallexample
13999
14000@noindent
14001You need to include the special files along with the rest in the
14002@code{protoize} command, even though their @samp{.X} files already
14003exist, because otherwise they won't get converted.
14004
14005@xref{Protoize Caveats}, for more information on how to use
14006@code{protoize} successfully.
14007
| 1666@item -fno-weak
1667@opindex fno-weak
1668Do not use weak symbol support, even if it is provided by the linker.
1669By default, G++ will use weak symbols if they are available. This
1670option exists only for testing, and should not be used by end-users;
1671it will result in inferior code and has no benefits. This option may
1672be removed in a future release of G++.
1673
1674@item -nostdinc++
1675@opindex nostdinc++
1676Do not search for header files in the standard directories specific to
1677C++, but do still search the other standard directories. (This option
1678is used when building the C++ library.)
1679@end table
1680
1681In addition, these optimization, warning, and code generation options
1682have meanings only for C++ programs:
1683
1684@table @gcctabopt
1685@item -fno-default-inline
1686@opindex fno-default-inline
1687Do not assume @samp{inline} for functions defined inside a class scope.
1688@xref{Optimize Options,,Options That Control Optimization}. Note that these
1689functions will have linkage like inline functions; they just won't be
1690inlined by default.
1691
1692@item -Wabi @r{(C++ only)}
1693@opindex Wabi
1694Warn when G++ generates code that is probably not compatible with the
1695vendor-neutral C++ ABI@. Although an effort has been made to warn about
1696all such cases, there are probably some cases that are not warned about,
1697even though G++ is generating incompatible code. There may also be
1698cases where warnings are emitted even though the code that is generated
1699will be compatible.
1700
1701You should rewrite your code to avoid these warnings if you are
1702concerned about the fact that code generated by G++ may not be binary
1703compatible with code generated by other compilers.
1704
1705The known incompatibilities at this point include:
1706
1707@itemize @bullet
1708
1709@item
1710Incorrect handling of tail-padding for bit-fields. G++ may attempt to
1711pack data into the same byte as a base class. For example:
1712
1713@smallexample
1714struct A @{ virtual void f(); int f1 : 1; @};
1715struct B : public A @{ int f2 : 1; @};
1716@end smallexample
1717
1718@noindent
1719In this case, G++ will place @code{B::f2} into the same byte
1720as@code{A::f1}; other compilers will not. You can avoid this problem
1721by explicitly padding @code{A} so that its size is a multiple of the
1722byte size on your platform; that will cause G++ and other compilers to
1723layout @code{B} identically.
1724
1725@item
1726Incorrect handling of tail-padding for virtual bases. G++ does not use
1727tail padding when laying out virtual bases. For example:
1728
1729@smallexample
1730struct A @{ virtual void f(); char c1; @};
1731struct B @{ B(); char c2; @};
1732struct C : public A, public virtual B @{@};
1733@end smallexample
1734
1735@noindent
1736In this case, G++ will not place @code{B} into the tail-padding for
1737@code{A}; other compilers will. You can avoid this problem by
1738explicitly padding @code{A} so that its size is a multiple of its
1739alignment (ignoring virtual base classes); that will cause G++ and other
1740compilers to layout @code{C} identically.
1741
1742@item
1743Incorrect handling of bit-fields with declared widths greater than that
1744of their underlying types, when the bit-fields appear in a union. For
1745example:
1746
1747@smallexample
1748union U @{ int i : 4096; @};
1749@end smallexample
1750
1751@noindent
1752Assuming that an @code{int} does not have 4096 bits, G++ will make the
1753union too small by the number of bits in an @code{int}.
1754
1755@item
1756Empty classes can be placed at incorrect offsets. For example:
1757
1758@smallexample
1759struct A @{@};
1760
1761struct B @{
1762 A a;
1763 virtual void f ();
1764@};
1765
1766struct C : public B, public A @{@};
1767@end smallexample
1768
1769@noindent
1770G++ will place the @code{A} base class of @code{C} at a nonzero offset;
1771it should be placed at offset zero. G++ mistakenly believes that the
1772@code{A} data member of @code{B} is already at offset zero.
1773
1774@item
1775Names of template functions whose types involve @code{typename} or
1776template template parameters can be mangled incorrectly.
1777
1778@smallexample
1779template <typename Q>
1780void f(typename Q::X) @{@}
1781
1782template <template <typename> class Q>
1783void f(typename Q<int>::X) @{@}
1784@end smallexample
1785
1786@noindent
1787Instantiations of these templates may be mangled incorrectly.
1788
1789@end itemize
1790
1791@item -Wctor-dtor-privacy @r{(C++ only)}
1792@opindex Wctor-dtor-privacy
1793Warn when a class seems unusable because all the constructors or
1794destructors in that class are private, and it has neither friends nor
1795public static member functions.
1796
1797@item -Wnon-virtual-dtor @r{(C++ only)}
1798@opindex Wnon-virtual-dtor
1799Warn when a class appears to be polymorphic, thereby requiring a virtual
1800destructor, yet it declares a non-virtual one. This warning is also
1801enabled if -Weffc++ is specified.
1802
1803@item -Wreorder @r{(C++ only)}
1804@opindex Wreorder
1805@cindex reordering, warning
1806@cindex warning for reordering of member initializers
1807Warn when the order of member initializers given in the code does not
1808match the order in which they must be executed. For instance:
1809
1810@smallexample
1811struct A @{
1812 int i;
1813 int j;
1814 A(): j (0), i (1) @{ @}
1815@};
1816@end smallexample
1817
1818The compiler will rearrange the member initializers for @samp{i}
1819and @samp{j} to match the declaration order of the members, emitting
1820a warning to that effect. This warning is enabled by @option{-Wall}.
1821@end table
1822
1823The following @option{-W@dots{}} options are not affected by @option{-Wall}.
1824
1825@table @gcctabopt
1826@item -Weffc++ @r{(C++ only)}
1827@opindex Weffc++
1828Warn about violations of the following style guidelines from Scott Meyers'
1829@cite{Effective C++} book:
1830
1831@itemize @bullet
1832@item
1833Item 11: Define a copy constructor and an assignment operator for classes
1834with dynamically allocated memory.
1835
1836@item
1837Item 12: Prefer initialization to assignment in constructors.
1838
1839@item
1840Item 14: Make destructors virtual in base classes.
1841
1842@item
1843Item 15: Have @code{operator=} return a reference to @code{*this}.
1844
1845@item
1846Item 23: Don't try to return a reference when you must return an object.
1847
1848@end itemize
1849
1850Also warn about violations of the following style guidelines from
1851Scott Meyers' @cite{More Effective C++} book:
1852
1853@itemize @bullet
1854@item
1855Item 6: Distinguish between prefix and postfix forms of increment and
1856decrement operators.
1857
1858@item
1859Item 7: Never overload @code{&&}, @code{||}, or @code{,}.
1860
1861@end itemize
1862
1863When selecting this option, be aware that the standard library
1864headers do not obey all of these guidelines; use @samp{grep -v}
1865to filter out those warnings.
1866
1867@item -Wno-deprecated @r{(C++ only)}
1868@opindex Wno-deprecated
1869Do not warn about usage of deprecated features. @xref{Deprecated Features}.
1870
1871@item -Wstrict-null-sentinel @r{(C++ only)}
1872@opindex Wstrict-null-sentinel
1873Warn also about the use of an uncasted @code{NULL} as sentinel. When
1874compiling only with GCC this is a valid sentinel, as @code{NULL} is defined
1875to @code{__null}. Although it is a null pointer constant not a null pointer,
1876it is guaranteed to of the same size as a pointer. But this use is
1877not portable across different compilers.
1878
1879@item -Wno-non-template-friend @r{(C++ only)}
1880@opindex Wno-non-template-friend
1881Disable warnings when non-templatized friend functions are declared
1882within a template. Since the advent of explicit template specification
1883support in G++, if the name of the friend is an unqualified-id (i.e.,
1884@samp{friend foo(int)}), the C++ language specification demands that the
1885friend declare or define an ordinary, nontemplate function. (Section
188614.5.3). Before G++ implemented explicit specification, unqualified-ids
1887could be interpreted as a particular specialization of a templatized
1888function. Because this non-conforming behavior is no longer the default
1889behavior for G++, @option{-Wnon-template-friend} allows the compiler to
1890check existing code for potential trouble spots and is on by default.
1891This new compiler behavior can be turned off with
1892@option{-Wno-non-template-friend} which keeps the conformant compiler code
1893but disables the helpful warning.
1894
1895@item -Wold-style-cast @r{(C++ only)}
1896@opindex Wold-style-cast
1897Warn if an old-style (C-style) cast to a non-void type is used within
1898a C++ program. The new-style casts (@samp{dynamic_cast},
1899@samp{static_cast}, @samp{reinterpret_cast}, and @samp{const_cast}) are
1900less vulnerable to unintended effects and much easier to search for.
1901
1902@item -Woverloaded-virtual @r{(C++ only)}
1903@opindex Woverloaded-virtual
1904@cindex overloaded virtual fn, warning
1905@cindex warning for overloaded virtual fn
1906Warn when a function declaration hides virtual functions from a
1907base class. For example, in:
1908
1909@smallexample
1910struct A @{
1911 virtual void f();
1912@};
1913
1914struct B: public A @{
1915 void f(int);
1916@};
1917@end smallexample
1918
1919the @code{A} class version of @code{f} is hidden in @code{B}, and code
1920like:
1921
1922@smallexample
1923B* b;
1924b->f();
1925@end smallexample
1926
1927will fail to compile.
1928
1929@item -Wno-pmf-conversions @r{(C++ only)}
1930@opindex Wno-pmf-conversions
1931Disable the diagnostic for converting a bound pointer to member function
1932to a plain pointer.
1933
1934@item -Wsign-promo @r{(C++ only)}
1935@opindex Wsign-promo
1936Warn when overload resolution chooses a promotion from unsigned or
1937enumerated type to a signed type, over a conversion to an unsigned type of
1938the same size. Previous versions of G++ would try to preserve
1939unsignedness, but the standard mandates the current behavior.
1940
1941@smallexample
1942struct A @{
1943 operator int ();
1944 A& operator = (int);
1945@};
1946
1947main ()
1948@{
1949 A a,b;
1950 a = b;
1951@}
1952@end smallexample
1953
1954In this example, G++ will synthesize a default @samp{A& operator =
1955(const A&);}, while cfront will use the user-defined @samp{operator =}.
1956@end table
1957
1958@node Language Independent Options
1959@section Options to Control Diagnostic Messages Formatting
1960@cindex options to control diagnostics formatting
1961@cindex diagnostic messages
1962@cindex message formatting
1963
1964Traditionally, diagnostic messages have been formatted irrespective of
1965the output device's aspect (e.g.@: its width, @dots{}). The options described
1966below can be used to control the diagnostic messages formatting
1967algorithm, e.g.@: how many characters per line, how often source location
1968information should be reported. Right now, only the C++ front end can
1969honor these options. However it is expected, in the near future, that
1970the remaining front ends would be able to digest them correctly.
1971
1972@table @gcctabopt
1973@item -fmessage-length=@var{n}
1974@opindex fmessage-length
1975Try to format error messages so that they fit on lines of about @var{n}
1976characters. The default is 72 characters for @command{g++} and 0 for the rest of
1977the front ends supported by GCC@. If @var{n} is zero, then no
1978line-wrapping will be done; each error message will appear on a single
1979line.
1980
1981@opindex fdiagnostics-show-location
1982@item -fdiagnostics-show-location=once
1983Only meaningful in line-wrapping mode. Instructs the diagnostic messages
1984reporter to emit @emph{once} source location information; that is, in
1985case the message is too long to fit on a single physical line and has to
1986be wrapped, the source location won't be emitted (as prefix) again,
1987over and over, in subsequent continuation lines. This is the default
1988behavior.
1989
1990@item -fdiagnostics-show-location=every-line
1991Only meaningful in line-wrapping mode. Instructs the diagnostic
1992messages reporter to emit the same source location information (as
1993prefix) for physical lines that result from the process of breaking
1994a message which is too long to fit on a single line.
1995
1996@item -fdiagnostics-show-option
1997@opindex fdiagnostics-show-option
1998This option instructs the diagnostic machinery to add text to each
1999diagnostic emitted, which indicates which command line option directly
2000controls that diagnostic, when such an option is known to the
2001diagnostic machinery.
2002
2003@end table
2004
2005@node Warning Options
2006@section Options to Request or Suppress Warnings
2007@cindex options to control warnings
2008@cindex warning messages
2009@cindex messages, warning
2010@cindex suppressing warnings
2011
2012Warnings are diagnostic messages that report constructions which
2013are not inherently erroneous but which are risky or suggest there
2014may have been an error.
2015
2016You can request many specific warnings with options beginning @samp{-W},
2017for example @option{-Wimplicit} to request warnings on implicit
2018declarations. Each of these specific warning options also has a
2019negative form beginning @samp{-Wno-} to turn off warnings;
2020for example, @option{-Wno-implicit}. This manual lists only one of the
2021two forms, whichever is not the default.
2022
2023The following options control the amount and kinds of warnings produced
2024by GCC; for further, language-specific options also refer to
2025@ref{C++ Dialect Options}.
2026
2027@table @gcctabopt
2028@cindex syntax checking
2029@item -fsyntax-only
2030@opindex fsyntax-only
2031Check the code for syntax errors, but don't do anything beyond that.
2032
2033@item -pedantic
2034@opindex pedantic
2035Issue all the warnings demanded by strict ISO C and ISO C++;
2036reject all programs that use forbidden extensions, and some other
2037programs that do not follow ISO C and ISO C++. For ISO C, follows the
2038version of the ISO C standard specified by any @option{-std} option used.
2039
2040Valid ISO C and ISO C++ programs should compile properly with or without
2041this option (though a rare few will require @option{-ansi} or a
2042@option{-std} option specifying the required version of ISO C)@. However,
2043without this option, certain GNU extensions and traditional C and C++
2044features are supported as well. With this option, they are rejected.
2045
2046@option{-pedantic} does not cause warning messages for use of the
2047alternate keywords whose names begin and end with @samp{__}. Pedantic
2048warnings are also disabled in the expression that follows
2049@code{__extension__}. However, only system header files should use
2050these escape routes; application programs should avoid them.
2051@xref{Alternate Keywords}.
2052
2053Some users try to use @option{-pedantic} to check programs for strict ISO
2054C conformance. They soon find that it does not do quite what they want:
2055it finds some non-ISO practices, but not all---only those for which
2056ISO C @emph{requires} a diagnostic, and some others for which
2057diagnostics have been added.
2058
2059A feature to report any failure to conform to ISO C might be useful in
2060some instances, but would require considerable additional work and would
2061be quite different from @option{-pedantic}. We don't have plans to
2062support such a feature in the near future.
2063
2064Where the standard specified with @option{-std} represents a GNU
2065extended dialect of C, such as @samp{gnu89} or @samp{gnu99}, there is a
2066corresponding @dfn{base standard}, the version of ISO C on which the GNU
2067extended dialect is based. Warnings from @option{-pedantic} are given
2068where they are required by the base standard. (It would not make sense
2069for such warnings to be given only for features not in the specified GNU
2070C dialect, since by definition the GNU dialects of C include all
2071features the compiler supports with the given option, and there would be
2072nothing to warn about.)
2073
2074@item -pedantic-errors
2075@opindex pedantic-errors
2076Like @option{-pedantic}, except that errors are produced rather than
2077warnings.
2078
2079@item -w
2080@opindex w
2081Inhibit all warning messages.
2082
2083@item -Wno-import
2084@opindex Wno-import
2085Inhibit warning messages about the use of @samp{#import}.
2086
2087@c APPLE LOCAL begin -Wnewline-eof 2001-08-23 --sts **
2088@item -Wnewline-eof
2089@opindex Wnewline-eof
2090Warn about files missing a newline at the end of the file. (Apple compatible)
2091@c APPLE LOCAL end -Wnewline-eof 2001-08-23 --sts **
2092
2093@item -Wchar-subscripts
2094@opindex Wchar-subscripts
2095Warn if an array subscript has type @code{char}. This is a common cause
2096of error, as programmers often forget that this type is signed on some
2097machines.
2098This warning is enabled by @option{-Wall}.
2099
2100@item -Wcomment
2101@opindex Wcomment
2102Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
2103comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
2104This warning is enabled by @option{-Wall}.
2105
2106@item -Wfatal-errors
2107@opindex Wfatal-errors
2108This option causes the compiler to abort compilation on the first error
2109occurred rather than trying to keep going and printing further error
2110messages.
2111
2112@item -Wformat
2113@opindex Wformat
2114@opindex ffreestanding
2115@opindex fno-builtin
2116Check calls to @code{printf} and @code{scanf}, etc., to make sure that
2117the arguments supplied have types appropriate to the format string
2118specified, and that the conversions specified in the format string make
2119sense. This includes standard functions, and others specified by format
2120attributes (@pxref{Function Attributes}), in the @code{printf},
2121@code{scanf}, @code{strftime} and @code{strfmon} (an X/Open extension,
2122not in the C standard) families (or other target-specific families).
2123Which functions are checked without format attributes having been
2124specified depends on the standard version selected, and such checks of
2125functions without the attribute specified are disabled by
2126@option{-ffreestanding} or @option{-fno-builtin}.
2127
2128The formats are checked against the format features supported by GNU
2129libc version 2.2. These include all ISO C90 and C99 features, as well
2130as features from the Single Unix Specification and some BSD and GNU
2131extensions. Other library implementations may not support all these
2132features; GCC does not support warning about features that go beyond a
2133particular library's limitations. However, if @option{-pedantic} is used
2134with @option{-Wformat}, warnings will be given about format features not
2135in the selected standard version (but not for @code{strfmon} formats,
2136since those are not in any version of the C standard). @xref{C Dialect
2137Options,,Options Controlling C Dialect}.
2138
2139Since @option{-Wformat} also checks for null format arguments for
2140several functions, @option{-Wformat} also implies @option{-Wnonnull}.
2141
2142@option{-Wformat} is included in @option{-Wall}. For more control over some
2143aspects of format checking, the options @option{-Wformat-y2k},
2144@option{-Wno-format-extra-args}, @option{-Wno-format-zero-length},
2145@option{-Wformat-nonliteral}, @option{-Wformat-security}, and
2146@option{-Wformat=2} are available, but are not included in @option{-Wall}.
2147
2148@item -Wformat-y2k
2149@opindex Wformat-y2k
2150If @option{-Wformat} is specified, also warn about @code{strftime}
2151formats which may yield only a two-digit year.
2152
2153@item -Wno-format-extra-args
2154@opindex Wno-format-extra-args
2155If @option{-Wformat} is specified, do not warn about excess arguments to a
2156@code{printf} or @code{scanf} format function. The C standard specifies
2157that such arguments are ignored.
2158
2159Where the unused arguments lie between used arguments that are
2160specified with @samp{$} operand number specifications, normally
2161warnings are still given, since the implementation could not know what
2162type to pass to @code{va_arg} to skip the unused arguments. However,
2163in the case of @code{scanf} formats, this option will suppress the
2164warning if the unused arguments are all pointers, since the Single
2165Unix Specification says that such unused arguments are allowed.
2166
2167@item -Wno-format-zero-length
2168@opindex Wno-format-zero-length
2169If @option{-Wformat} is specified, do not warn about zero-length formats.
2170The C standard specifies that zero-length formats are allowed.
2171
2172@item -Wformat-nonliteral
2173@opindex Wformat-nonliteral
2174If @option{-Wformat} is specified, also warn if the format string is not a
2175string literal and so cannot be checked, unless the format function
2176takes its format arguments as a @code{va_list}.
2177
2178@item -Wformat-security
2179@opindex Wformat-security
2180If @option{-Wformat} is specified, also warn about uses of format
2181functions that represent possible security problems. At present, this
2182warns about calls to @code{printf} and @code{scanf} functions where the
2183format string is not a string literal and there are no format arguments,
2184as in @code{printf (foo);}. This may be a security hole if the format
2185string came from untrusted input and contains @samp{%n}. (This is
2186currently a subset of what @option{-Wformat-nonliteral} warns about, but
2187in future warnings may be added to @option{-Wformat-security} that are not
2188included in @option{-Wformat-nonliteral}.)
2189
2190@item -Wformat=2
2191@opindex Wformat=2
2192Enable @option{-Wformat} plus format checks not included in
2193@option{-Wformat}. Currently equivalent to @samp{-Wformat
2194-Wformat-nonliteral -Wformat-security -Wformat-y2k}.
2195
2196@item -Wnonnull
2197@opindex Wnonnull
2198Warn about passing a null pointer for arguments marked as
2199requiring a non-null value by the @code{nonnull} function attribute.
2200
2201@option{-Wnonnull} is included in @option{-Wall} and @option{-Wformat}. It
2202can be disabled with the @option{-Wno-nonnull} option.
2203
2204@item -Winit-self @r{(C and C++ only)}
2205@opindex Winit-self
2206Warn about uninitialized variables which are initialized with themselves.
2207Note this option can only be used with the @option{-Wuninitialized} option,
2208which in turn only works with @option{-O1} and above.
2209
2210For example, GCC will warn about @code{i} being uninitialized in the
2211following snippet only when @option{-Winit-self} has been specified:
2212@smallexample
2213@group
2214int f()
2215@{
2216 int i = i;
2217 return i;
2218@}
2219@end group
2220@end smallexample
2221
2222@item -Wimplicit-int
2223@opindex Wimplicit-int
2224Warn when a declaration does not specify a type.
2225This warning is enabled by @option{-Wall}.
2226
2227@item -Wimplicit-function-declaration
2228@itemx -Werror-implicit-function-declaration
2229@opindex Wimplicit-function-declaration
2230@opindex Werror-implicit-function-declaration
2231Give a warning (or error) whenever a function is used before being
2232declared. The form @option{-Wno-error-implicit-function-declaration}
2233is not supported.
2234This warning is enabled by @option{-Wall} (as a warning, not an error).
2235
2236@item -Wimplicit
2237@opindex Wimplicit
2238Same as @option{-Wimplicit-int} and @option{-Wimplicit-function-declaration}.
2239This warning is enabled by @option{-Wall}.
2240
2241@item -Wmain
2242@opindex Wmain
2243Warn if the type of @samp{main} is suspicious. @samp{main} should be a
2244function with external linkage, returning int, taking either zero
2245arguments, two, or three arguments of appropriate types.
2246This warning is enabled by @option{-Wall}.
2247
2248@item -Wmissing-braces
2249@opindex Wmissing-braces
2250Warn if an aggregate or union initializer is not fully bracketed. In
2251the following example, the initializer for @samp{a} is not fully
2252bracketed, but that for @samp{b} is fully bracketed.
2253
2254@smallexample
2255int a[2][2] = @{ 0, 1, 2, 3 @};
2256int b[2][2] = @{ @{ 0, 1 @}, @{ 2, 3 @} @};
2257@end smallexample
2258
2259This warning is enabled by @option{-Wall}.
2260
2261@item -Wmissing-include-dirs @r{(C and C++ only)}
2262@opindex Wmissing-include-dirs
2263Warn if a user-supplied include directory does not exist.
2264
2265@item -Wparentheses
2266@opindex Wparentheses
2267Warn if parentheses are omitted in certain contexts, such
2268as when there is an assignment in a context where a truth value
2269is expected, or when operators are nested whose precedence people
2270often get confused about.
2271
2272Also warn if a comparison like @samp{x<=y<=z} appears; this is
2273equivalent to @samp{(x<=y ? 1 : 0) <= z}, which is a different
2274interpretation from that of ordinary mathematical notation.
2275
2276Also warn about constructions where there may be confusion to which
2277@code{if} statement an @code{else} branch belongs. Here is an example of
2278such a case:
2279
2280@smallexample
2281@group
2282@{
2283 if (a)
2284 if (b)
2285 foo ();
2286 else
2287 bar ();
2288@}
2289@end group
2290@end smallexample
2291
2292In C/C++, every @code{else} branch belongs to the innermost possible
2293@code{if} statement, which in this example is @code{if (b)}. This is
2294often not what the programmer expected, as illustrated in the above
2295example by indentation the programmer chose. When there is the
2296potential for this confusion, GCC will issue a warning when this flag
2297is specified. To eliminate the warning, add explicit braces around
2298the innermost @code{if} statement so there is no way the @code{else}
2299could belong to the enclosing @code{if}. The resulting code would
2300look like this:
2301
2302@smallexample
2303@group
2304@{
2305 if (a)
2306 @{
2307 if (b)
2308 foo ();
2309 else
2310 bar ();
2311 @}
2312@}
2313@end group
2314@end smallexample
2315
2316This warning is enabled by @option{-Wall}.
2317
2318@item -Wsequence-point
2319@opindex Wsequence-point
2320Warn about code that may have undefined semantics because of violations
2321of sequence point rules in the C and C++ standards.
2322
2323The C and C++ standards defines the order in which expressions in a C/C++
2324program are evaluated in terms of @dfn{sequence points}, which represent
2325a partial ordering between the execution of parts of the program: those
2326executed before the sequence point, and those executed after it. These
2327occur after the evaluation of a full expression (one which is not part
2328of a larger expression), after the evaluation of the first operand of a
2329@code{&&}, @code{||}, @code{? :} or @code{,} (comma) operator, before a
2330function is called (but after the evaluation of its arguments and the
2331expression denoting the called function), and in certain other places.
2332Other than as expressed by the sequence point rules, the order of
2333evaluation of subexpressions of an expression is not specified. All
2334these rules describe only a partial order rather than a total order,
2335since, for example, if two functions are called within one expression
2336with no sequence point between them, the order in which the functions
2337are called is not specified. However, the standards committee have
2338ruled that function calls do not overlap.
2339
2340It is not specified when between sequence points modifications to the
2341values of objects take effect. Programs whose behavior depends on this
2342have undefined behavior; the C and C++ standards specify that ``Between
2343the previous and next sequence point an object shall have its stored
2344value modified at most once by the evaluation of an expression.
2345Furthermore, the prior value shall be read only to determine the value
2346to be stored.''. If a program breaks these rules, the results on any
2347particular implementation are entirely unpredictable.
2348
2349Examples of code with undefined behavior are @code{a = a++;}, @code{a[n]
2350= b[n++]} and @code{a[i++] = i;}. Some more complicated cases are not
2351diagnosed by this option, and it may give an occasional false positive
2352result, but in general it has been found fairly effective at detecting
2353this sort of problem in programs.
2354
2355The standard is worded confusingly, therefore there is some debate
2356over the precise meaning of the sequence point rules in subtle cases.
2357Links to discussions of the problem, including proposed formal
2358definitions, may be found on the GCC readings page, at
2359@w{@uref{http://gcc.gnu.org/readings.html}}.
2360
2361This warning is enabled by @option{-Wall} for C and C++.
2362
2363@item -Wreturn-type
2364@opindex Wreturn-type
2365Warn whenever a function is defined with a return-type that defaults to
2366@code{int}. Also warn about any @code{return} statement with no
2367return-value in a function whose return-type is not @code{void}.
2368
2369For C, also warn if the return type of a function has a type qualifier
2370such as @code{const}. Such a type qualifier has no effect, since the
2371value returned by a function is not an lvalue. ISO C prohibits
2372qualified @code{void} return types on function definitions, so such
2373return types always receive a warning even without this option.
2374
2375For C++, a function without return type always produces a diagnostic
2376message, even when @option{-Wno-return-type} is specified. The only
2377exceptions are @samp{main} and functions defined in system headers.
2378
2379This warning is enabled by @option{-Wall}.
2380
2381@item -Wswitch
2382@opindex Wswitch
2383Warn whenever a @code{switch} statement has an index of enumerated type
2384and lacks a @code{case} for one or more of the named codes of that
2385enumeration. (The presence of a @code{default} label prevents this
2386warning.) @code{case} labels outside the enumeration range also
2387provoke warnings when this option is used.
2388This warning is enabled by @option{-Wall}.
2389
2390@item -Wswitch-default
2391@opindex Wswitch-switch
2392Warn whenever a @code{switch} statement does not have a @code{default}
2393case.
2394
2395@item -Wswitch-enum
2396@opindex Wswitch-enum
2397Warn whenever a @code{switch} statement has an index of enumerated type
2398and lacks a @code{case} for one or more of the named codes of that
2399enumeration. @code{case} labels outside the enumeration range also
2400provoke warnings when this option is used.
2401
2402@item -Wtrigraphs
2403@opindex Wtrigraphs
2404Warn if any trigraphs are encountered that might change the meaning of
2405the program (trigraphs within comments are not warned about).
2406This warning is enabled by @option{-Wall}.
2407
2408@item -Wunused-function
2409@opindex Wunused-function
2410Warn whenever a static function is declared but not defined or a
2411non-inline static function is unused.
2412This warning is enabled by @option{-Wall}.
2413
2414@item -Wunused-label
2415@opindex Wunused-label
2416Warn whenever a label is declared but not used.
2417This warning is enabled by @option{-Wall}.
2418
2419To suppress this warning use the @samp{unused} attribute
2420(@pxref{Variable Attributes}).
2421
2422@item -Wunused-parameter
2423@opindex Wunused-parameter
2424Warn whenever a function parameter is unused aside from its declaration.
2425
2426To suppress this warning use the @samp{unused} attribute
2427(@pxref{Variable Attributes}).
2428
2429@item -Wunused-variable
2430@opindex Wunused-variable
2431Warn whenever a local variable or non-constant static variable is unused
2432aside from its declaration.
2433This warning is enabled by @option{-Wall}.
2434
2435To suppress this warning use the @samp{unused} attribute
2436(@pxref{Variable Attributes}).
2437
2438@item -Wunused-value
2439@opindex Wunused-value
2440Warn whenever a statement computes a result that is explicitly not used.
2441This warning is enabled by @option{-Wall}.
2442
2443To suppress this warning cast the expression to @samp{void}.
2444
2445@item -Wunused
2446@opindex Wunused
2447All the above @option{-Wunused} options combined.
2448
2449In order to get a warning about an unused function parameter, you must
2450either specify @samp{-Wextra -Wunused} (note that @samp{-Wall} implies
2451@samp{-Wunused}), or separately specify @option{-Wunused-parameter}.
2452
2453@item -Wuninitialized
2454@opindex Wuninitialized
2455Warn if an automatic variable is used without first being initialized or
2456if a variable may be clobbered by a @code{setjmp} call.
2457
2458These warnings are possible only in optimizing compilation,
2459because they require data flow information that is computed only
2460when optimizing. If you do not specify @option{-O}, you will not get
2461these warnings. Instead, GCC will issue a warning about @option{-Wuninitialized}
2462requiring @option{-O}.
2463
2464If you want to warn about code which uses the uninitialized value of the
2465variable in its own initializer, use the @option{-Winit-self} option.
2466
2467These warnings occur for individual uninitialized or clobbered
2468elements of structure, union or array variables as well as for
2469variables which are uninitialized or clobbered as a whole. They do
2470not occur for variables or elements declared @code{volatile}. Because
2471these warnings depend on optimization, the exact variables or elements
2472for which there are warnings will depend on the precise optimization
2473options and version of GCC used.
2474
2475Note that there may be no warning about a variable that is used only
2476to compute a value that itself is never used, because such
2477computations may be deleted by data flow analysis before the warnings
2478are printed.
2479
2480These warnings are made optional because GCC is not smart
2481enough to see all the reasons why the code might be correct
2482despite appearing to have an error. Here is one example of how
2483this can happen:
2484
2485@smallexample
2486@group
2487@{
2488 int x;
2489 switch (y)
2490 @{
2491 case 1: x = 1;
2492 break;
2493 case 2: x = 4;
2494 break;
2495 case 3: x = 5;
2496 @}
2497 foo (x);
2498@}
2499@end group
2500@end smallexample
2501
2502@noindent
2503If the value of @code{y} is always 1, 2 or 3, then @code{x} is
2504always initialized, but GCC doesn't know this. Here is
2505another common case:
2506
2507@smallexample
2508@{
2509 int save_y;
2510 if (change_y) save_y = y, y = new_y;
2511 @dots{}
2512 if (change_y) y = save_y;
2513@}
2514@end smallexample
2515
2516@noindent
2517This has no bug because @code{save_y} is used only if it is set.
2518
2519@cindex @code{longjmp} warnings
2520This option also warns when a non-volatile automatic variable might be
2521changed by a call to @code{longjmp}. These warnings as well are possible
2522only in optimizing compilation.
2523
2524The compiler sees only the calls to @code{setjmp}. It cannot know
2525where @code{longjmp} will be called; in fact, a signal handler could
2526call it at any point in the code. As a result, you may get a warning
2527even when there is in fact no problem because @code{longjmp} cannot
2528in fact be called at the place which would cause a problem.
2529
2530Some spurious warnings can be avoided if you declare all the functions
2531you use that never return as @code{noreturn}. @xref{Function
2532Attributes}.
2533
2534This warning is enabled by @option{-Wall}.
2535
2536@item -Wunknown-pragmas
2537@opindex Wunknown-pragmas
2538@cindex warning for unknown pragmas
2539@cindex unknown pragmas, warning
2540@cindex pragmas, warning of unknown
2541Warn when a #pragma directive is encountered which is not understood by
2542GCC@. If this command line option is used, warnings will even be issued
2543for unknown pragmas in system header files. This is not the case if
2544the warnings were only enabled by the @option{-Wall} command line option.
2545
2546@item -Wno-pragmas
2547@opindex Wno-pragmas
2548@opindex Wpragmas
2549Do not warn about misuses of pragmas, such as incorrect parameters,
2550invalid syntax, or conflicts between pragmas. See also
2551@samp{-Wunknown-pragmas}.
2552
2553@item -Wstrict-aliasing
2554@opindex Wstrict-aliasing
2555This option is only active when @option{-fstrict-aliasing} is active.
2556It warns about code which might break the strict aliasing rules that the
2557compiler is using for optimization. The warning does not catch all
2558cases, but does attempt to catch the more common pitfalls. It is
2559included in @option{-Wall}.
2560It is equivalent to -Wstrict-aliasing=3
2561
2562@item -Wstrict-aliasing=n
2563@opindex Wstrict-aliasing=n
2564This option is only active when @option{-fstrict-aliasing} is active.
2565It warns about code which might break the strict aliasing rules that the
2566compiler is using for optimization.
2567Higher levels correspond to higher accuracy (fewer false positives).
2568Higher levels also correspond to more effort, similar to the way -O works.
2569@option{-Wstrict-aliasing} is equivalent to @option{-Wstrict-aliasing=n},
2570with n=3.
2571
2572Level 1: Most aggressive, quick, least accurate.
2573Possibly useful when higher levels
2574do not warn but -fstrict-aliasing still breaks the code, as it has very few
2575false negatives. However, it has many false positives.
2576Warns for all pointer conversions between possibly incompatible types,
2577even if never dereferenced. Runs in the frontend only.
2578
2579Level 2: Aggressive, quick, not too precise.
2580May still have many false positives (not as many as level 1 though),
2581and few false negatives (but possibly more than level 1).
2582Unlike level 1, it only warns when an address is taken. Warns about
2583incomplete types. Runs in the frontend only.
2584
2585Level 3 (default for @option{-Wstrict-aliasing}):
2586Should have very few false positives and few false
2587negatives. Slightly slower than levels 1 or 2 when optimization is enabled.
2588Takes care of the common punn+dereference pattern in the frontend:
2589@code{*(int*)&some_float}.
2590If optimization is enabled, it also runs in the backend, where it deals
2591with multiple statement cases using flow-sensitive points-to information.
2592Only warns when the converted pointer is dereferenced.
2593Does not warn about incomplete types.
2594
2595@item -Wstrict-overflow
2596@item -Wstrict-overflow=@var{n}
2597@opindex Wstrict-overflow
2598This option is only active when @option{-fstrict-overflow} is active.
2599It warns about cases where the compiler optimizes based on the
2600assumption that signed overflow does not occur. Note that it does not
2601warn about all cases where the code might overflow: it only warns
2602about cases where the compiler implements some optimization. Thus
2603this warning depends on the optimization level.
2604
2605An optimization which assumes that signed overflow does not occur is
2606perfectly safe if the values of the variables involved are such that
2607overflow never does, in fact, occur. Therefore this warning can
2608easily give a false positive: a warning about code which is not
2609actually a problem. To help focus on important issues, several
2610warning levels are defined. No warnings are issued for the use of
2611undefined signed overflow when estimating how many iterations a loop
2612will require, in particular when determining whether a loop will be
2613executed at all.
2614
2615@table @option
2616@item -Wstrict-overflow=1
2617Warn about cases which are both questionable and easy to avoid. For
2618example: @code{x + 1 > x}; with @option{-fstrict-overflow}, the
2619compiler will simplify this to @code{1}. This level of
2620@option{-Wstrict-overflow} is enabled by @option{-Wall}; higher levels
2621are not, and must be explicitly requested.
2622
2623@item -Wstrict-overflow=2
2624Also warn about other cases where a comparison is simplified to a
2625constant. For example: @code{abs (x) >= 0}. This can only be
2626simplified when @option{-fstrict-overflow} is in effect, because
2627@code{abs (INT_MIN)} overflows to @code{INT_MIN}, which is less than
2628zero. @option{-Wstrict-overflow} (with no level) is the same as
2629@option{-Wstrict-overflow=2}.
2630
2631@item -Wstrict-overflow=3
2632Also warn about other cases where a comparison is simplified. For
2633example: @code{x + 1 > 1} will be simplified to @code{x > 0}.
2634
2635@item -Wstrict-overflow=4
2636Also warn about other simplifications not covered by the above cases.
2637For example: @code{(x * 10) / 5} will be simplified to @code{x * 2}.
2638
2639@item -Wstrict-overflow=5
2640Also warn about cases where the compiler reduces the magnitude of a
2641constant involved in a comparison. For example: @code{x + 2 > y} will
2642be simplified to @code{x + 1 >= y}. This is reported only at the
2643highest warning level because this simplification applies to many
2644comparisons, so this warning level will give a very large number of
2645false positives.
2646@end table
2647
2648@item -Wall
2649@opindex Wall
2650All of the above @samp{-W} options combined. This enables all the
2651warnings about constructions that some users consider questionable, and
2652that are easy to avoid (or modify to prevent the warning), even in
2653conjunction with macros. This also enables some language-specific
2654warnings described in @ref{C++ Dialect Options}.
2655@end table
2656
2657The following @option{-W@dots{}} options are not implied by @option{-Wall}.
2658Some of them warn about constructions that users generally do not
2659consider questionable, but which occasionally you might wish to check
2660for; others warn about constructions that are necessary or hard to avoid
2661in some cases, and there is no simple way to modify the code to suppress
2662the warning.
2663
2664@table @gcctabopt
2665@item -Wextra
2666@opindex W
2667@opindex Wextra
2668(This option used to be called @option{-W}. The older name is still
2669supported, but the newer name is more descriptive.) Print extra warning
2670messages for these events:
2671
2672@itemize @bullet
2673@item
2674A function can return either with or without a value. (Falling
2675off the end of the function body is considered returning without
2676a value.) For example, this function would evoke such a
2677warning:
2678
2679@smallexample
2680@group
2681foo (a)
2682@{
2683 if (a > 0)
2684 return a;
2685@}
2686@end group
2687@end smallexample
2688
2689@item
2690An expression-statement or the left-hand side of a comma expression
2691contains no side effects.
2692To suppress the warning, cast the unused expression to void.
2693For example, an expression such as @samp{x[i,j]} will cause a warning,
2694but @samp{x[(void)i,j]} will not.
2695
2696@item
2697An unsigned value is compared against zero with @samp{<} or @samp{>=}.
2698
2699@item
2700Storage-class specifiers like @code{static} are not the first things in
2701a declaration. According to the C Standard, this usage is obsolescent.
2702
2703@item
2704If @option{-Wall} or @option{-Wunused} is also specified, warn about unused
2705arguments.
2706
2707@item
2708A comparison between signed and unsigned values could produce an
2709incorrect result when the signed value is converted to unsigned.
2710(But don't warn if @option{-Wno-sign-compare} is also specified.)
2711
2712@item
2713An aggregate has an initializer which does not initialize all members.
2714This warning can be independently controlled by
2715@option{-Wmissing-field-initializers}.
2716
2717@item
2718An initialized field without side effects is overridden when using
2719designated initializers (@pxref{Designated Inits, , Designated
2720Initializers}). This warning can be independently controlled by
2721@option{-Woverride-init}.
2722
2723@item
2724A function parameter is declared without a type specifier in K&R-style
2725functions:
2726
2727@smallexample
2728void foo(bar) @{ @}
2729@end smallexample
2730
2731@item
2732An empty body occurs in an @samp{if} or @samp{else} statement.
2733
2734@item
2735A pointer is compared against integer zero with @samp{<}, @samp{<=},
2736@samp{>}, or @samp{>=}.
2737
2738@item
2739A variable might be changed by @samp{longjmp} or @samp{vfork}.
2740
2741@item @r{(C++ only)}
2742An enumerator and a non-enumerator both appear in a conditional expression.
2743
2744@item @r{(C++ only)}
2745A non-static reference or non-static @samp{const} member appears in a
2746class without constructors.
2747
2748@item @r{(C++ only)}
2749Ambiguous virtual bases.
2750
2751@item @r{(C++ only)}
2752Subscripting an array which has been declared @samp{register}.
2753
2754@item @r{(C++ only)}
2755Taking the address of a variable which has been declared @samp{register}.
2756
2757@item @r{(C++ only)}
2758A base class is not initialized in a derived class' copy constructor.
2759@end itemize
2760
2761@item -Wno-div-by-zero
2762@opindex Wno-div-by-zero
2763@opindex Wdiv-by-zero
2764Do not warn about compile-time integer division by zero. Floating point
2765division by zero is not warned about, as it can be a legitimate way of
2766obtaining infinities and NaNs.
2767
2768@item -Wsystem-headers
2769@opindex Wsystem-headers
2770@cindex warnings from system headers
2771@cindex system headers, warnings from
2772Print warning messages for constructs found in system header files.
2773Warnings from system headers are normally suppressed, on the assumption
2774that they usually do not indicate real problems and would only make the
2775compiler output harder to read. Using this command line option tells
2776GCC to emit warnings from system headers as if they occurred in user
2777code. However, note that using @option{-Wall} in conjunction with this
2778option will @emph{not} warn about unknown pragmas in system
2779headers---for that, @option{-Wunknown-pragmas} must also be used.
2780
2781@item -Wfloat-equal
2782@opindex Wfloat-equal
2783Warn if floating point values are used in equality comparisons.
2784
2785The idea behind this is that sometimes it is convenient (for the
2786programmer) to consider floating-point values as approximations to
2787infinitely precise real numbers. If you are doing this, then you need
2788to compute (by analyzing the code, or in some other way) the maximum or
2789likely maximum error that the computation introduces, and allow for it
2790when performing comparisons (and when producing output, but that's a
2791different problem). In particular, instead of testing for equality, you
2792would check to see whether the two values have ranges that overlap; and
2793this is done with the relational operators, so equality comparisons are
2794probably mistaken.
2795
2796@item -Wtraditional @r{(C only)}
2797@opindex Wtraditional
2798Warn about certain constructs that behave differently in traditional and
2799ISO C@. Also warn about ISO C constructs that have no traditional C
2800equivalent, and/or problematic constructs which should be avoided.
2801
2802@itemize @bullet
2803@item
2804Macro parameters that appear within string literals in the macro body.
2805In traditional C macro replacement takes place within string literals,
2806but does not in ISO C@.
2807
2808@item
2809In traditional C, some preprocessor directives did not exist.
2810Traditional preprocessors would only consider a line to be a directive
2811if the @samp{#} appeared in column 1 on the line. Therefore
2812@option{-Wtraditional} warns about directives that traditional C
2813understands but would ignore because the @samp{#} does not appear as the
2814first character on the line. It also suggests you hide directives like
2815@samp{#pragma} not understood by traditional C by indenting them. Some
2816traditional implementations would not recognize @samp{#elif}, so it
2817suggests avoiding it altogether.
2818
2819@item
2820A function-like macro that appears without arguments.
2821
2822@item
2823The unary plus operator.
2824
2825@item
2826The @samp{U} integer constant suffix, or the @samp{F} or @samp{L} floating point
2827constant suffixes. (Traditional C does support the @samp{L} suffix on integer
2828constants.) Note, these suffixes appear in macros defined in the system
2829headers of most modern systems, e.g.@: the @samp{_MIN}/@samp{_MAX} macros in @code{<limits.h>}.
2830Use of these macros in user code might normally lead to spurious
2831warnings, however GCC's integrated preprocessor has enough context to
2832avoid warning in these cases.
2833
2834@item
2835A function declared external in one block and then used after the end of
2836the block.
2837
2838@item
2839A @code{switch} statement has an operand of type @code{long}.
2840
2841@item
2842A non-@code{static} function declaration follows a @code{static} one.
2843This construct is not accepted by some traditional C compilers.
2844
2845@item
2846The ISO type of an integer constant has a different width or
2847signedness from its traditional type. This warning is only issued if
2848the base of the constant is ten. I.e.@: hexadecimal or octal values, which
2849typically represent bit patterns, are not warned about.
2850
2851@item
2852Usage of ISO string concatenation is detected.
2853
2854@item
2855Initialization of automatic aggregates.
2856
2857@item
2858Identifier conflicts with labels. Traditional C lacks a separate
2859namespace for labels.
2860
2861@item
2862Initialization of unions. If the initializer is zero, the warning is
2863omitted. This is done under the assumption that the zero initializer in
2864user code appears conditioned on e.g.@: @code{__STDC__} to avoid missing
2865initializer warnings and relies on default initialization to zero in the
2866traditional C case.
2867
2868@item
2869Conversions by prototypes between fixed/floating point values and vice
2870versa. The absence of these prototypes when compiling with traditional
2871C would cause serious problems. This is a subset of the possible
2872conversion warnings, for the full set use @option{-Wconversion}.
2873
2874@item
2875Use of ISO C style function definitions. This warning intentionally is
2876@emph{not} issued for prototype declarations or variadic functions
2877because these ISO C features will appear in your code when using
2878libiberty's traditional C compatibility macros, @code{PARAMS} and
2879@code{VPARAMS}. This warning is also bypassed for nested functions
2880because that feature is already a GCC extension and thus not relevant to
2881traditional C compatibility.
2882@end itemize
2883
2884@item -Wdeclaration-after-statement @r{(C only)}
2885@opindex Wdeclaration-after-statement
2886Warn when a declaration is found after a statement in a block. This
2887construct, known from C++, was introduced with ISO C99 and is by default
2888allowed in GCC@. It is not supported by ISO C90 and was not supported by
2889GCC versions before GCC 3.0. @xref{Mixed Declarations}.
2890
2891@item -Wundef
2892@opindex Wundef
2893Warn if an undefined identifier is evaluated in an @samp{#if} directive.
2894
2895@item -Wno-endif-labels
2896@opindex Wno-endif-labels
2897@opindex Wendif-labels
2898Do not warn whenever an @samp{#else} or an @samp{#endif} are followed by text.
2899
2900@item -Wshadow
2901@opindex Wshadow
2902Warn whenever a local variable shadows another local variable, parameter or
2903global variable or whenever a built-in function is shadowed.
2904
2905@item -Wlarger-than-@var{len}
2906@opindex Wlarger-than
2907Warn whenever an object of larger than @var{len} bytes is defined.
2908
2909@item -Wframe-larger-than-@var{len}
2910@opindex Wframe-larger-than
2911Warn whenever the frame size of a function is larger than @var{len} bytes.
2912
2913@item -Wunsafe-loop-optimizations
2914@opindex Wunsafe-loop-optimizations
2915Warn if the loop cannot be optimized because the compiler could not
2916assume anything on the bounds of the loop indices. With
2917@option{-funsafe-loop-optimizations} warn if the compiler made
2918such assumptions.
2919
2920@item -Wpointer-arith
2921@opindex Wpointer-arith
2922Warn about anything that depends on the ``size of'' a function type or
2923of @code{void}. GNU C assigns these types a size of 1, for
2924convenience in calculations with @code{void *} pointers and pointers
2925to functions.
2926
2927@item -Wbad-function-cast @r{(C only)}
2928@opindex Wbad-function-cast
2929Warn whenever a function call is cast to a non-matching type.
2930For example, warn if @code{int malloc()} is cast to @code{anything *}.
2931
2932@item -Wc++-compat
2933Warn about ISO C constructs that are outside of the common subset of
2934ISO C and ISO C++, e.g.@: request for implicit conversion from
2935@code{void *} to a pointer to non-@code{void} type.
2936
2937@item -Wcast-qual
2938@opindex Wcast-qual
2939Warn whenever a pointer is cast so as to remove a type qualifier from
2940the target type. For example, warn if a @code{const char *} is cast
2941to an ordinary @code{char *}.
2942
2943@item -Wcast-align
2944@opindex Wcast-align
2945Warn whenever a pointer is cast such that the required alignment of the
2946target is increased. For example, warn if a @code{char *} is cast to
2947an @code{int *} on machines where integers can only be accessed at
2948two- or four-byte boundaries.
2949
2950@item -Wwrite-strings
2951@opindex Wwrite-strings
2952When compiling C, give string constants the type @code{const
2953char[@var{length}]} so that
2954copying the address of one into a non-@code{const} @code{char *}
2955pointer will get a warning; when compiling C++, warn about the
2956deprecated conversion from string literals to @code{char *}. This
2957warning, by default, is enabled for C++ programs.
2958These warnings will help you find at
2959compile time code that can try to write into a string constant, but
2960only if you have been very careful about using @code{const} in
2961declarations and prototypes. Otherwise, it will just be a nuisance;
2962this is why we did not make @option{-Wall} request these warnings.
2963
2964@item -Wconversion
2965@opindex Wconversion
2966Warn if a prototype causes a type conversion that is different from what
2967would happen to the same argument in the absence of a prototype. This
2968includes conversions of fixed point to floating and vice versa, and
2969conversions changing the width or signedness of a fixed point argument
2970except when the same as the default promotion.
2971
2972Also, warn if a negative integer constant expression is implicitly
2973converted to an unsigned type. For example, warn about the assignment
2974@code{x = -1} if @code{x} is unsigned. But do not warn about explicit
2975casts like @code{(unsigned) -1}.
2976
2977@item -Wsign-compare
2978@opindex Wsign-compare
2979@cindex warning for comparison of signed and unsigned values
2980@cindex comparison of signed and unsigned values, warning
2981@cindex signed and unsigned values, comparison warning
2982Warn when a comparison between signed and unsigned values could produce
2983an incorrect result when the signed value is converted to unsigned.
2984This warning is also enabled by @option{-Wextra}; to get the other warnings
2985of @option{-Wextra} without this warning, use @samp{-Wextra -Wno-sign-compare}.
2986
2987@item -Waddress
2988@opindex Waddress
2989@opindex Wno-address
2990Warn about suspicious uses of memory addresses. These include using
2991the address of a function in a conditional expression, such as
2992@code{void func(void); if (func)}, and comparisons against the memory
2993address of a string literal, such as @code{if (x == "abc")}. Such
2994uses typically indicate a programmer error: the address of a function
2995always evaluates to true, so their use in a conditional usually
2996indicate that the programmer forgot the parentheses in a function
2997call; and comparisons against string literals result in unspecified
2998behavior and are not portable in C, so they usually indicate that the
2999programmer intended to use @code{strcmp}. This warning is enabled by
3000@option{-Wall}.
3001
3002@item -Waggregate-return
3003@opindex Waggregate-return
3004Warn if any functions that return structures or unions are defined or
3005called. (In languages where you can return an array, this also elicits
3006a warning.)
3007
3008@item -Wno-attributes
3009@opindex Wno-attributes
3010@opindex Wattributes
3011Do not warn if an unexpected @code{__attribute__} is used, such as
3012unrecognized attributes, function attributes applied to variables,
3013etc. This will not stop errors for incorrect use of supported
3014attributes.
3015
3016@item -Wstrict-prototypes @r{(C only)}
3017@opindex Wstrict-prototypes
3018Warn if a function is declared or defined without specifying the
3019argument types. (An old-style function definition is permitted without
3020a warning if preceded by a declaration which specifies the argument
3021types.)
3022
3023@item -Wold-style-definition @r{(C only)}
3024@opindex Wold-style-definition
3025Warn if an old-style function definition is used. A warning is given
3026even if there is a previous prototype.
3027
3028@item -Wmissing-prototypes @r{(C only)}
3029@opindex Wmissing-prototypes
3030Warn if a global function is defined without a previous prototype
3031declaration. This warning is issued even if the definition itself
3032provides a prototype. The aim is to detect global functions that fail
3033to be declared in header files.
3034
3035@item -Wmissing-declarations @r{(C only)}
3036@opindex Wmissing-declarations
3037Warn if a global function is defined without a previous declaration.
3038Do so even if the definition itself provides a prototype.
3039Use this option to detect global functions that are not declared in
3040header files.
3041
3042@item -Wmissing-field-initializers
3043@opindex Wmissing-field-initializers
3044@opindex W
3045@opindex Wextra
3046Warn if a structure's initializer has some fields missing. For
3047example, the following code would cause such a warning, because
3048@code{x.h} is implicitly zero:
3049
3050@smallexample
3051struct s @{ int f, g, h; @};
3052struct s x = @{ 3, 4 @};
3053@end smallexample
3054
3055This option does not warn about designated initializers, so the following
3056modification would not trigger a warning:
3057
3058@smallexample
3059struct s @{ int f, g, h; @};
3060struct s x = @{ .f = 3, .g = 4 @};
3061@end smallexample
3062
3063This warning is included in @option{-Wextra}. To get other @option{-Wextra}
3064warnings without this one, use @samp{-Wextra -Wno-missing-field-initializers}.
3065
3066@item -Wmissing-noreturn
3067@opindex Wmissing-noreturn
3068Warn about functions which might be candidates for attribute @code{noreturn}.
3069Note these are only possible candidates, not absolute ones. Care should
3070be taken to manually verify functions actually do not ever return before
3071adding the @code{noreturn} attribute, otherwise subtle code generation
3072bugs could be introduced. You will not get a warning for @code{main} in
3073hosted C environments.
3074
3075@item -Wmissing-format-attribute
3076@opindex Wmissing-format-attribute
3077@opindex Wformat
3078Warn about function pointers which might be candidates for @code{format}
3079attributes. Note these are only possible candidates, not absolute ones.
3080GCC will guess that function pointers with @code{format} attributes that
3081are used in assignment, initialization, parameter passing or return
3082statements should have a corresponding @code{format} attribute in the
3083resulting type. I.e.@: the left-hand side of the assignment or
3084initialization, the type of the parameter variable, or the return type
3085of the containing function respectively should also have a @code{format}
3086attribute to avoid the warning.
3087
3088GCC will also warn about function definitions which might be
3089candidates for @code{format} attributes. Again, these are only
3090possible candidates. GCC will guess that @code{format} attributes
3091might be appropriate for any function that calls a function like
3092@code{vprintf} or @code{vscanf}, but this might not always be the
3093case, and some functions for which @code{format} attributes are
3094appropriate may not be detected.
3095
3096@item -Wno-multichar
3097@opindex Wno-multichar
3098@opindex Wmultichar
3099Do not warn if a multicharacter constant (@samp{'FOOF'}) is used.
3100Usually they indicate a typo in the user's code, as they have
3101implementation-defined values, and should not be used in portable code.
3102
3103@item -Wnormalized=<none|id|nfc|nfkc>
3104@opindex Wnormalized
3105@cindex NFC
3106@cindex NFKC
3107@cindex character set, input normalization
3108In ISO C and ISO C++, two identifiers are different if they are
3109different sequences of characters. However, sometimes when characters
3110outside the basic ASCII character set are used, you can have two
3111different character sequences that look the same. To avoid confusion,
3112the ISO 10646 standard sets out some @dfn{normalization rules} which
3113when applied ensure that two sequences that look the same are turned into
3114the same sequence. GCC can warn you if you are using identifiers which
3115have not been normalized; this option controls that warning.
3116
3117There are four levels of warning that GCC supports. The default is
3118@option{-Wnormalized=nfc}, which warns about any identifier which is
3119not in the ISO 10646 ``C'' normalized form, @dfn{NFC}. NFC is the
3120recommended form for most uses.
3121
3122Unfortunately, there are some characters which ISO C and ISO C++ allow
3123in identifiers that when turned into NFC aren't allowable as
3124identifiers. That is, there's no way to use these symbols in portable
3125ISO C or C++ and have all your identifiers in NFC.
3126@option{-Wnormalized=id} suppresses the warning for these characters.
3127It is hoped that future versions of the standards involved will correct
3128this, which is why this option is not the default.
3129
3130You can switch the warning off for all characters by writing
3131@option{-Wnormalized=none}. You would only want to do this if you
3132were using some other normalization scheme (like ``D''), because
3133otherwise you can easily create bugs that are literally impossible to see.
3134
3135Some characters in ISO 10646 have distinct meanings but look identical
3136in some fonts or display methodologies, especially once formatting has
3137been applied. For instance @code{\u207F}, ``SUPERSCRIPT LATIN SMALL
3138LETTER N'', will display just like a regular @code{n} which has been
3139placed in a superscript. ISO 10646 defines the @dfn{NFKC}
3140normalization scheme to convert all these into a standard form as
3141well, and GCC will warn if your code is not in NFKC if you use
3142@option{-Wnormalized=nfkc}. This warning is comparable to warning
3143about every identifier that contains the letter O because it might be
3144confused with the digit 0, and so is not the default, but may be
3145useful as a local coding convention if the programming environment is
3146unable to be fixed to display these characters distinctly.
3147
3148@item -Wno-deprecated-declarations
3149@opindex Wno-deprecated-declarations
3150Do not warn about uses of functions (@pxref{Function Attributes}),
3151variables (@pxref{Variable Attributes}), and types (@pxref{Type
3152Attributes}) marked as deprecated by using the @code{deprecated}
3153attribute.
3154
3155@item -Wno-overflow
3156@opindex Wno-overflow
3157Do not warn about compile-time overflow in constant expressions.
3158
3159@item -Woverride-init
3160@opindex Woverride-init
3161@opindex W
3162@opindex Wextra
3163Warn if an initialized field without side effects is overridden when
3164using designated initializers (@pxref{Designated Inits, , Designated
3165Initializers}).
3166
3167This warning is included in @option{-Wextra}. To get other
3168@option{-Wextra} warnings without this one, use @samp{-Wextra
3169-Wno-override-init}.
3170
3171@item -Wpacked
3172@opindex Wpacked
3173Warn if a structure is given the packed attribute, but the packed
3174attribute has no effect on the layout or size of the structure.
3175Such structures may be mis-aligned for little benefit. For
3176instance, in this code, the variable @code{f.x} in @code{struct bar}
3177will be misaligned even though @code{struct bar} does not itself
3178have the packed attribute:
3179
3180@smallexample
3181@group
3182struct foo @{
3183 int x;
3184 char a, b, c, d;
3185@} __attribute__((packed));
3186struct bar @{
3187 char z;
3188 struct foo f;
3189@};
3190@end group
3191@end smallexample
3192
3193@item -Wpadded
3194@opindex Wpadded
3195Warn if padding is included in a structure, either to align an element
3196of the structure or to align the whole structure. Sometimes when this
3197happens it is possible to rearrange the fields of the structure to
3198reduce the padding and so make the structure smaller.
3199
3200@item -Wredundant-decls
3201@opindex Wredundant-decls
3202Warn if anything is declared more than once in the same scope, even in
3203cases where multiple declaration is valid and changes nothing.
3204
3205@item -Wnested-externs @r{(C only)}
3206@opindex Wnested-externs
3207Warn if an @code{extern} declaration is encountered within a function.
3208
3209@item -Wunreachable-code
3210@opindex Wunreachable-code
3211Warn if the compiler detects that code will never be executed.
3212
3213This option is intended to warn when the compiler detects that at
3214least a whole line of source code will never be executed, because
3215some condition is never satisfied or because it is after a
3216procedure that never returns.
3217
3218It is possible for this option to produce a warning even though there
3219are circumstances under which part of the affected line can be executed,
3220so care should be taken when removing apparently-unreachable code.
3221
3222For instance, when a function is inlined, a warning may mean that the
3223line is unreachable in only one inlined copy of the function.
3224
3225This option is not made part of @option{-Wall} because in a debugging
3226version of a program there is often substantial code which checks
3227correct functioning of the program and is, hopefully, unreachable
3228because the program does work. Another common use of unreachable
3229code is to provide behavior which is selectable at compile-time.
3230
3231@item -Winline
3232@opindex Winline
3233Warn if a function can not be inlined and it was declared as inline.
3234Even with this option, the compiler will not warn about failures to
3235inline functions declared in system headers.
3236
3237The compiler uses a variety of heuristics to determine whether or not
3238to inline a function. For example, the compiler takes into account
3239the size of the function being inlined and the amount of inlining
3240that has already been done in the current function. Therefore,
3241seemingly insignificant changes in the source program can cause the
3242warnings produced by @option{-Winline} to appear or disappear.
3243
3244@item -Wno-invalid-offsetof @r{(C++ only)}
3245@opindex Wno-invalid-offsetof
3246Suppress warnings from applying the @samp{offsetof} macro to a non-POD
3247type. According to the 1998 ISO C++ standard, applying @samp{offsetof}
3248to a non-POD type is undefined. In existing C++ implementations,
3249however, @samp{offsetof} typically gives meaningful results even when
3250applied to certain kinds of non-POD types. (Such as a simple
3251@samp{struct} that fails to be a POD type only by virtue of having a
3252constructor.) This flag is for users who are aware that they are
3253writing nonportable code and who have deliberately chosen to ignore the
3254warning about it.
3255
3256The restrictions on @samp{offsetof} may be relaxed in a future version
3257of the C++ standard.
3258
3259@item -Wno-int-to-pointer-cast @r{(C only)}
3260@opindex Wno-int-to-pointer-cast
3261Suppress warnings from casts to pointer type of an integer of a
3262different size.
3263
3264@item -Wno-pointer-to-int-cast @r{(C only)}
3265@opindex Wno-pointer-to-int-cast
3266Suppress warnings from casts from a pointer to an integer type of a
3267different size.
3268
3269@item -Winvalid-pch
3270@opindex Winvalid-pch
3271Warn if a precompiled header (@pxref{Precompiled Headers}) is found in
3272the search path but can't be used.
3273
3274@item -Wlong-long
3275@opindex Wlong-long
3276@opindex Wno-long-long
3277Warn if @samp{long long} type is used. This is default. To inhibit
3278the warning messages, use @option{-Wno-long-long}. Flags
3279@option{-Wlong-long} and @option{-Wno-long-long} are taken into account
3280only when @option{-pedantic} flag is used.
3281
3282@item -Wvariadic-macros
3283@opindex Wvariadic-macros
3284@opindex Wno-variadic-macros
3285Warn if variadic macros are used in pedantic ISO C90 mode, or the GNU
3286alternate syntax when in pedantic ISO C99 mode. This is default.
3287To inhibit the warning messages, use @option{-Wno-variadic-macros}.
3288
3289@item -Wvla
3290@opindex Wvla
3291@opindex Wno-vla
3292Warn if variable length array is used in the code.
3293@option{-Wno-vla} will prevent the @option{-pedantic} warning of
3294the variable length array.
3295
3296@item -Wvolatile-register-var
3297@opindex Wvolatile-register-var
3298@opindex Wno-volatile-register-var
3299Warn if a register variable is declared volatile. The volatile
3300modifier does not inhibit all optimizations that may eliminate reads
3301and/or writes to register variables.
3302
3303@item -Wdisabled-optimization
3304@opindex Wdisabled-optimization
3305Warn if a requested optimization pass is disabled. This warning does
3306not generally indicate that there is anything wrong with your code; it
3307merely indicates that GCC's optimizers were unable to handle the code
3308effectively. Often, the problem is that your code is too big or too
3309complex; GCC will refuse to optimize programs when the optimization
3310itself is likely to take inordinate amounts of time.
3311
3312@item -Wpointer-sign
3313@opindex Wpointer-sign
3314@opindex Wno-pointer-sign
3315Warn for pointer argument passing or assignment with different signedness.
3316This option is only supported for C. It is implied by @option{-Wall}
3317and by @option{-pedantic}, which can be disabled with
3318@option{-Wno-pointer-sign}.
3319
3320@item -Werror
3321@opindex Werror
3322Make all warnings into errors.
3323
3324@item -Werror=
3325@opindex Werror=
3326Make the specified warning into an errors. The specifier for a
3327warning is appended, for example @option{-Werror=switch} turns the
3328warnings controlled by @option{-Wswitch} into errors. This switch
3329takes a negative form, to be used to negate @option{-Werror} for
3330specific warnings, for example @option{-Wno-error=switch} makes
3331@option{-Wswitch} warnings not be errors, even when @option{-Werror}
3332is in effect. You can use the @option{-fdiagnostics-show-option}
3333option to have each controllable warning amended with the option which
3334controls it, to determine what to use with this option.
3335
3336Note that specifying @option{-Werror=}@var{foo} automatically implies
3337@option{-W}@var{foo}. However, @option{-Wno-error=}@var{foo} does not
3338imply anything.
3339
3340@item -Wstack-protector
3341@opindex Wstack-protector
3342This option is only active when @option{-fstack-protector} is active. It
3343warns about functions that will not be protected against stack smashing.
3344
3345@item -Woverlength-strings
3346@opindex Woverlength-strings
3347Warn about string constants which are longer than the ``minimum
3348maximum'' length specified in the C standard. Modern compilers
3349generally allow string constants which are much longer than the
3350standard's minimum limit, but very portable programs should avoid
3351using longer strings.
3352
3353The limit applies @emph{after} string constant concatenation, and does
3354not count the trailing NUL@. In C89, the limit was 509 characters; in
3355C99, it was raised to 4095. C++98 does not specify a normative
3356minimum maximum, so we do not diagnose overlength strings in C++@.
3357
3358This option is implied by @option{-pedantic}, and can be disabled with
3359@option{-Wno-overlength-strings}.
3360@end table
3361
3362@node Debugging Options
3363@section Options for Debugging Your Program or GCC
3364@cindex options, debugging
3365@cindex debugging information options
3366
3367GCC has various special options that are used for debugging
3368either your program or GCC:
3369
3370@table @gcctabopt
3371@item -g
3372@opindex g
3373Produce debugging information in the operating system's native format
3374(stabs, COFF, XCOFF, or DWARF 2)@. GDB can work with this debugging
3375information.
3376
3377On most systems that use stabs format, @option{-g} enables use of extra
3378debugging information that only GDB can use; this extra information
3379makes debugging work better in GDB but will probably make other debuggers
3380crash or
3381refuse to read the program. If you want to control for certain whether
3382to generate the extra information, use @option{-gstabs+}, @option{-gstabs},
3383@option{-gxcoff+}, @option{-gxcoff}, or @option{-gvms} (see below).
3384
3385GCC allows you to use @option{-g} with
3386@option{-O}. The shortcuts taken by optimized code may occasionally
3387produce surprising results: some variables you declared may not exist
3388at all; flow of control may briefly move where you did not expect it;
3389some statements may not be executed because they compute constant
3390results or their values were already at hand; some statements may
3391execute in different places because they were moved out of loops.
3392
3393Nevertheless it proves possible to debug optimized output. This makes
3394it reasonable to use the optimizer for programs that might have bugs.
3395
3396The following options are useful when GCC is generated with the
3397capability for more than one debugging format.
3398
3399@item -ggdb
3400@opindex ggdb
3401Produce debugging information for use by GDB@. This means to use the
3402most expressive format available (DWARF 2, stabs, or the native format
3403if neither of those are supported), including GDB extensions if at all
3404possible.
3405
3406@item -gstabs
3407@opindex gstabs
3408Produce debugging information in stabs format (if that is supported),
3409without GDB extensions. This is the format used by DBX on most BSD
3410systems. On MIPS, Alpha and System V Release 4 systems this option
3411produces stabs debugging output which is not understood by DBX or SDB@.
3412On System V Release 4 systems this option requires the GNU assembler.
3413
3414@item -feliminate-unused-debug-symbols
3415@opindex feliminate-unused-debug-symbols
3416Produce debugging information in stabs format (if that is supported),
3417for only symbols that are actually used.
3418
3419@item -femit-class-debug-always
3420Instead of emitting debugging information for a C++ class in only one
3421object file, emit it in all object files using the class. This option
3422should be used only with debuggers that are unable to handle the way GCC
3423normally emits debugging information for classes because using this
3424option will increase the size of debugging information by as much as a
3425factor of two.
3426
3427@item -gstabs+
3428@opindex gstabs+
3429Produce debugging information in stabs format (if that is supported),
3430using GNU extensions understood only by the GNU debugger (GDB)@. The
3431use of these extensions is likely to make other debuggers crash or
3432refuse to read the program.
3433
3434@item -gcoff
3435@opindex gcoff
3436Produce debugging information in COFF format (if that is supported).
3437This is the format used by SDB on most System V systems prior to
3438System V Release 4.
3439
3440@item -gxcoff
3441@opindex gxcoff
3442Produce debugging information in XCOFF format (if that is supported).
3443This is the format used by the DBX debugger on IBM RS/6000 systems.
3444
3445@item -gxcoff+
3446@opindex gxcoff+
3447Produce debugging information in XCOFF format (if that is supported),
3448using GNU extensions understood only by the GNU debugger (GDB)@. The
3449use of these extensions is likely to make other debuggers crash or
3450refuse to read the program, and may cause assemblers other than the GNU
3451assembler (GAS) to fail with an error.
3452
3453@item -gdwarf-2
3454@opindex gdwarf-2
3455Produce debugging information in DWARF version 2 format (if that is
3456supported). This is the format used by DBX on IRIX 6. With this
3457option, GCC uses features of DWARF version 3 when they are useful;
3458version 3 is upward compatible with version 2, but may still cause
3459problems for older debuggers.
3460
3461@item -gvms
3462@opindex gvms
3463Produce debugging information in VMS debug format (if that is
3464supported). This is the format used by DEBUG on VMS systems.
3465
3466@item -g@var{level}
3467@itemx -ggdb@var{level}
3468@itemx -gstabs@var{level}
3469@itemx -gcoff@var{level}
3470@itemx -gxcoff@var{level}
3471@itemx -gvms@var{level}
3472Request debugging information and also use @var{level} to specify how
3473much information. The default level is 2.
3474
3475Level 1 produces minimal information, enough for making backtraces in
3476parts of the program that you don't plan to debug. This includes
3477descriptions of functions and external variables, but no information
3478about local variables and no line numbers.
3479
3480Level 3 includes extra information, such as all the macro definitions
3481present in the program. Some debuggers support macro expansion when
3482you use @option{-g3}.
3483
3484@option{-gdwarf-2} does not accept a concatenated debug level, because
3485GCC used to support an option @option{-gdwarf} that meant to generate
3486debug information in version 1 of the DWARF format (which is very
3487different from version 2), and it would have been too confusing. That
3488debug format is long obsolete, but the option cannot be changed now.
3489Instead use an additional @option{-g@var{level}} option to change the
3490debug level for DWARF2.
3491
3492@item -feliminate-dwarf2-dups
3493@opindex feliminate-dwarf2-dups
3494Compress DWARF2 debugging information by eliminating duplicated
3495information about each symbol. This option only makes sense when
3496generating DWARF2 debugging information with @option{-gdwarf-2}.
3497
3498@item -femit-struct-debug-baseonly
3499Emit debug information for struct-like types
3500only when the base name of the compilation source file
3501matches the base name of file in which the struct was defined.
3502
3503This option substantially reduces the size of debugging information,
3504but at significant potential loss in type information to the debugger.
3505See @option{-femit-struct-debug-reduced} for a less aggressive option.
3506See @option{-femit-struct-debug-detailed} for more detailed control.
3507
3508This option works only with DWARF 2.
3509
3510@item -femit-struct-debug-reduced
3511Emit debug information for struct-like types
3512only when the base name of the compilation source file
3513matches the base name of file in which the type was defined,
3514unless the struct is a template or defined in a system header.
3515
3516This option significantly reduces the size of debugging information,
3517with some potential loss in type information to the debugger.
3518See @option{-femit-struct-debug-baseonly} for a more aggressive option.
3519See @option{-femit-struct-debug-detailed} for more detailed control.
3520
3521This option works only with DWARF 2.
3522
3523@item -femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]}
3524Specify the struct-like types
3525for which the compiler will generate debug information.
3526The intent is to reduce duplicate struct debug information
3527between different object files within the same program.
3528
3529This option is a detailed version of
3530@option{-femit-struct-debug-reduced} and @option{-femit-struct-debug-baseonly},
3531which will serve for most needs.
3532
3533A specification has the syntax
3534[@samp{dir:}|@samp{ind:}][@samp{ord:}|@samp{gen:}](@samp{any}|@samp{sys}|@samp{base}|@samp{none})
3535
3536The optional first word limits the specification to
3537structs that are used directly (@samp{dir:}) or used indirectly (@samp{ind:}).
3538A struct type is used directly when it is the type of a variable, member.
3539Indirect uses arise through pointers to structs.
3540That is, when use of an incomplete struct would be legal, the use is indirect.
3541An example is
3542@samp{struct one direct; struct two * indirect;}.
3543
3544The optional second word limits the specification to
3545ordinary structs (@samp{ord:}) or generic structs (@samp{gen:}).
3546Generic structs are a bit complicated to explain.
3547For C++, these are non-explicit specializations of template classes,
3548or non-template classes within the above.
3549Other programming languages have generics,
3550but @samp{-femit-struct-debug-detailed} does not yet implement them.
3551
3552The third word specifies the source files for those
3553structs for which the compiler will emit debug information.
3554The values @samp{none} and @samp{any} have the normal meaning.
3555The value @samp{base} means that
3556the base of name of the file in which the type declaration appears
3557must match the base of the name of the main compilation file.
3558In practice, this means that
3559types declared in @file{foo.c} and @file{foo.h} will have debug information,
3560but types declared in other header will not.
3561The value @samp{sys} means those types satisfying @samp{base}
3562or declared in system or compiler headers.
3563
3564You may need to experiment to determine the best settings for your application.
3565
3566The default is @samp{-femit-struct-debug-detailed=all}.
3567
3568This option works only with DWARF 2.
3569
3570@cindex @command{prof}
3571@item -p
3572@opindex p
3573Generate extra code to write profile information suitable for the
3574analysis program @command{prof}. You must use this option when compiling
3575the source files you want data about, and you must also use it when
3576linking.
3577
3578@cindex @command{gprof}
3579@item -pg
3580@opindex pg
3581Generate extra code to write profile information suitable for the
3582analysis program @command{gprof}. You must use this option when compiling
3583the source files you want data about, and you must also use it when
3584linking.
3585
3586@item -Q
3587@opindex Q
3588Makes the compiler print out each function name as it is compiled, and
3589print some statistics about each pass when it finishes.
3590
3591@item -ftime-report
3592@opindex ftime-report
3593Makes the compiler print some statistics about the time consumed by each
3594pass when it finishes.
3595
3596@item -fmem-report
3597@opindex fmem-report
3598Makes the compiler print some statistics about permanent memory
3599allocation when it finishes.
3600
3601@item -fprofile-arcs
3602@opindex fprofile-arcs
3603Add code so that program flow @dfn{arcs} are instrumented. During
3604execution the program records how many times each branch and call is
3605executed and how many times it is taken or returns. When the compiled
3606program exits it saves this data to a file called
3607@file{@var{auxname}.gcda} for each source file. The data may be used for
3608profile-directed optimizations (@option{-fbranch-probabilities}), or for
3609test coverage analysis (@option{-ftest-coverage}). Each object file's
3610@var{auxname} is generated from the name of the output file, if
3611explicitly specified and it is not the final executable, otherwise it is
3612the basename of the source file. In both cases any suffix is removed
3613(e.g.@: @file{foo.gcda} for input file @file{dir/foo.c}, or
3614@file{dir/foo.gcda} for output file specified as @option{-o dir/foo.o}).
3615@xref{Cross-profiling}.
3616
3617@cindex @command{gcov}
3618@item --coverage
3619@opindex coverage
3620
3621This option is used to compile and link code instrumented for coverage
3622analysis. The option is a synonym for @option{-fprofile-arcs}
3623@option{-ftest-coverage} (when compiling) and @option{-lgcov} (when
3624linking). See the documentation for those options for more details.
3625
3626@itemize
3627
3628@item
3629Compile the source files with @option{-fprofile-arcs} plus optimization
3630and code generation options. For test coverage analysis, use the
3631additional @option{-ftest-coverage} option. You do not need to profile
3632every source file in a program.
3633
3634@item
3635Link your object files with @option{-lgcov} or @option{-fprofile-arcs}
3636(the latter implies the former).
3637
3638@item
3639Run the program on a representative workload to generate the arc profile
3640information. This may be repeated any number of times. You can run
3641concurrent instances of your program, and provided that the file system
3642supports locking, the data files will be correctly updated. Also
3643@code{fork} calls are detected and correctly handled (double counting
3644will not happen).
3645
3646@item
3647For profile-directed optimizations, compile the source files again with
3648the same optimization and code generation options plus
3649@option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that
3650Control Optimization}).
3651
3652@item
3653For test coverage analysis, use @command{gcov} to produce human readable
3654information from the @file{.gcno} and @file{.gcda} files. Refer to the
3655@command{gcov} documentation for further information.
3656
3657@end itemize
3658
3659With @option{-fprofile-arcs}, for each function of your program GCC
3660creates a program flow graph, then finds a spanning tree for the graph.
3661Only arcs that are not on the spanning tree have to be instrumented: the
3662compiler adds code to count the number of times that these arcs are
3663executed. When an arc is the only exit or only entrance to a block, the
3664instrumentation code can be added to the block; otherwise, a new basic
3665block must be created to hold the instrumentation code.
3666
3667@need 2000
3668@item -ftest-coverage
3669@opindex ftest-coverage
3670Produce a notes file that the @command{gcov} code-coverage utility
3671(@pxref{Gcov,, @command{gcov}---a Test Coverage Program}) can use to
3672show program coverage. Each source file's note file is called
3673@file{@var{auxname}.gcno}. Refer to the @option{-fprofile-arcs} option
3674above for a description of @var{auxname} and instructions on how to
3675generate test coverage data. Coverage data will match the source files
3676more closely, if you do not optimize.
3677
3678@item -d@var{letters}
3679@item -fdump-rtl-@var{pass}
3680@opindex d
3681Says to make debugging dumps during compilation at times specified by
3682@var{letters}. This is used for debugging the RTL-based passes of the
3683compiler. The file names for most of the dumps are made by appending a
3684pass number and a word to the @var{dumpname}. @var{dumpname} is generated
3685from the name of the output file, if explicitly specified and it is not
3686an executable, otherwise it is the basename of the source file.
3687
3688Most debug dumps can be enabled either passing a letter to the @option{-d}
3689option, or with a long @option{-fdump-rtl} switch; here are the possible
3690letters for use in @var{letters} and @var{pass}, and their meanings:
3691
3692@table @gcctabopt
3693@item -dA
3694@opindex dA
3695Annotate the assembler output with miscellaneous debugging information.
3696
3697@item -dB
3698@itemx -fdump-rtl-bbro
3699@opindex dB
3700@opindex fdump-rtl-bbro
3701Dump after block reordering, to @file{@var{file}.148r.bbro}.
3702
3703@item -dc
3704@itemx -fdump-rtl-combine
3705@opindex dc
3706@opindex fdump-rtl-combine
3707Dump after instruction combination, to the file @file{@var{file}.129r.combine}.
3708
3709@item -dC
3710@itemx -fdump-rtl-ce1
3711@itemx -fdump-rtl-ce2
3712@opindex dC
3713@opindex fdump-rtl-ce1
3714@opindex fdump-rtl-ce2
3715@option{-dC} and @option{-fdump-rtl-ce1} enable dumping after the
3716first if conversion, to the file @file{@var{file}.117r.ce1}. @option{-dC}
3717and @option{-fdump-rtl-ce2} enable dumping after the second if
3718conversion, to the file @file{@var{file}.130r.ce2}.
3719
3720@item -dd
3721@itemx -fdump-rtl-btl
3722@itemx -fdump-rtl-dbr
3723@opindex dd
3724@opindex fdump-rtl-btl
3725@opindex fdump-rtl-dbr
3726@option{-dd} and @option{-fdump-rtl-btl} enable dumping after branch
3727target load optimization, to @file{@var{file}.31.btl}. @option{-dd}
3728and @option{-fdump-rtl-dbr} enable dumping after delayed branch
3729scheduling, to @file{@var{file}.36.dbr}.
3730
3731@item -dD
3732@opindex dD
3733Dump all macro definitions, at the end of preprocessing, in addition to
3734normal output.
3735
3736@item -dE
3737@itemx -fdump-rtl-ce3
3738@opindex dE
3739@opindex fdump-rtl-ce3
3740Dump after the third if conversion, to @file{@var{file}.146r.ce3}.
3741
3742@item -df
3743@itemx -fdump-rtl-cfg
3744@itemx -fdump-rtl-life
3745@opindex df
3746@opindex fdump-rtl-cfg
3747@opindex fdump-rtl-life
3748@option{-df} and @option{-fdump-rtl-cfg} enable dumping after control
3749and data flow analysis, to @file{@var{file}.116r.cfg}. @option{-df}
3750and @option{-fdump-rtl-cfg} enable dumping dump after life analysis,
3751to @file{@var{file}.128r.life1} and @file{@var{file}.135r.life2}.
3752
3753@item -dg
3754@itemx -fdump-rtl-greg
3755@opindex dg
3756@opindex fdump-rtl-greg
3757Dump after global register allocation, to @file{@var{file}.139r.greg}.
3758
3759@item -dG
3760@itemx -fdump-rtl-gcse
3761@itemx -fdump-rtl-bypass
3762@opindex dG
3763@opindex fdump-rtl-gcse
3764@opindex fdump-rtl-bypass
3765@option{-dG} and @option{-fdump-rtl-gcse} enable dumping after GCSE, to
3766@file{@var{file}.114r.gcse}. @option{-dG} and @option{-fdump-rtl-bypass}
3767enable dumping after jump bypassing and control flow optimizations, to
3768@file{@var{file}.115r.bypass}.
3769
3770@item -dh
3771@itemx -fdump-rtl-eh
3772@opindex dh
3773@opindex fdump-rtl-eh
3774Dump after finalization of EH handling code, to @file{@var{file}.02.eh}.
3775
3776@item -di
3777@itemx -fdump-rtl-sibling
3778@opindex di
3779@opindex fdump-rtl-sibling
3780Dump after sibling call optimizations, to @file{@var{file}.106r.sibling}.
3781
3782@item -dj
3783@itemx -fdump-rtl-jump
3784@opindex dj
3785@opindex fdump-rtl-jump
3786Dump after the first jump optimization, to @file{@var{file}.112r.jump}.
3787
3788@item -dk
3789@itemx -fdump-rtl-stack
3790@opindex dk
3791@opindex fdump-rtl-stack
3792Dump after conversion from registers to stack, to @file{@var{file}.152r.stack}.
3793
3794@item -dl
3795@itemx -fdump-rtl-lreg
3796@opindex dl
3797@opindex fdump-rtl-lreg
3798Dump after local register allocation, to @file{@var{file}.138r.lreg}.
3799
3800@item -dL
3801@itemx -fdump-rtl-loop2
3802@opindex dL
3803@opindex fdump-rtl-loop2
3804@option{-dL} and @option{-fdump-rtl-loop2} enable dumping after the
3805loop optimization pass, to @file{@var{file}.119r.loop2},
3806@file{@var{file}.120r.loop2_init},
3807@file{@var{file}.121r.loop2_invariant}, and
3808@file{@var{file}.125r.loop2_done}.
3809
3810@item -dm
3811@itemx -fdump-rtl-sms
3812@opindex dm
3813@opindex fdump-rtl-sms
3814Dump after modulo scheduling, to @file{@var{file}.136r.sms}.
3815
3816@item -dM
3817@itemx -fdump-rtl-mach
3818@opindex dM
3819@opindex fdump-rtl-mach
3820Dump after performing the machine dependent reorganization pass, to
3821@file{@var{file}.155r.mach}.
3822
3823@item -dn
3824@itemx -fdump-rtl-rnreg
3825@opindex dn
3826@opindex fdump-rtl-rnreg
3827Dump after register renumbering, to @file{@var{file}.147r.rnreg}.
3828
3829@item -dN
3830@itemx -fdump-rtl-regmove
3831@opindex dN
3832@opindex fdump-rtl-regmove
3833Dump after the register move pass, to @file{@var{file}.132r.regmove}.
3834
3835@item -do
3836@itemx -fdump-rtl-postreload
3837@opindex do
3838@opindex fdump-rtl-postreload
3839Dump after post-reload optimizations, to @file{@var{file}.24.postreload}.
3840
3841@item -dr
3842@itemx -fdump-rtl-expand
3843@opindex dr
3844@opindex fdump-rtl-expand
3845Dump after RTL generation, to @file{@var{file}.104r.expand}.
3846
3847@item -dR
3848@itemx -fdump-rtl-sched2
3849@opindex dR
3850@opindex fdump-rtl-sched2
3851Dump after the second scheduling pass, to @file{@var{file}.150r.sched2}.
3852
3853@item -ds
3854@itemx -fdump-rtl-cse
3855@opindex ds
3856@opindex fdump-rtl-cse
3857Dump after CSE (including the jump optimization that sometimes follows
3858CSE), to @file{@var{file}.113r.cse}.
3859
3860@item -dS
3861@itemx -fdump-rtl-sched
3862@opindex dS
3863@opindex fdump-rtl-sched
3864Dump after the first scheduling pass, to @file{@var{file}.21.sched}.
3865
3866@item -dt
3867@itemx -fdump-rtl-cse2
3868@opindex dt
3869@opindex fdump-rtl-cse2
3870Dump after the second CSE pass (including the jump optimization that
3871sometimes follows CSE), to @file{@var{file}.127r.cse2}.
3872
3873@item -dT
3874@itemx -fdump-rtl-tracer
3875@opindex dT
3876@opindex fdump-rtl-tracer
3877Dump after running tracer, to @file{@var{file}.118r.tracer}.
3878
3879@item -dV
3880@itemx -fdump-rtl-vpt
3881@itemx -fdump-rtl-vartrack
3882@opindex dV
3883@opindex fdump-rtl-vpt
3884@opindex fdump-rtl-vartrack
3885@option{-dV} and @option{-fdump-rtl-vpt} enable dumping after the value
3886profile transformations, to @file{@var{file}.10.vpt}. @option{-dV}
3887and @option{-fdump-rtl-vartrack} enable dumping after variable tracking,
3888to @file{@var{file}.154r.vartrack}.
3889
3890@item -dw
3891@itemx -fdump-rtl-flow2
3892@opindex dw
3893@opindex fdump-rtl-flow2
3894Dump after the second flow pass, to @file{@var{file}.142r.flow2}.
3895
3896@item -dz
3897@itemx -fdump-rtl-peephole2
3898@opindex dz
3899@opindex fdump-rtl-peephole2
3900Dump after the peephole pass, to @file{@var{file}.145r.peephole2}.
3901
3902@item -dZ
3903@itemx -fdump-rtl-web
3904@opindex dZ
3905@opindex fdump-rtl-web
3906Dump after live range splitting, to @file{@var{file}.126r.web}.
3907
3908@item -da
3909@itemx -fdump-rtl-all
3910@opindex da
3911@opindex fdump-rtl-all
3912Produce all the dumps listed above.
3913
3914@item -dH
3915@opindex dH
3916Produce a core dump whenever an error occurs.
3917
3918@item -dm
3919@opindex dm
3920Print statistics on memory usage, at the end of the run, to
3921standard error.
3922
3923@item -dp
3924@opindex dp
3925Annotate the assembler output with a comment indicating which
3926pattern and alternative was used. The length of each instruction is
3927also printed.
3928
3929@item -dP
3930@opindex dP
3931Dump the RTL in the assembler output as a comment before each instruction.
3932Also turns on @option{-dp} annotation.
3933
3934@item -dv
3935@opindex dv
3936For each of the other indicated dump files (either with @option{-d} or
3937@option{-fdump-rtl-@var{pass}}), dump a representation of the control flow
3938graph suitable for viewing with VCG to @file{@var{file}.@var{pass}.vcg}.
3939
3940@item -dx
3941@opindex dx
3942Just generate RTL for a function instead of compiling it. Usually used
3943with @samp{r} (@option{-fdump-rtl-expand}).
3944
3945@item -dy
3946@opindex dy
3947Dump debugging information during parsing, to standard error.
3948@end table
3949
3950@item -fdump-noaddr
3951@opindex fdump-noaddr
3952When doing debugging dumps (see @option{-d} option above), suppress
3953address output. This makes it more feasible to use diff on debugging
3954dumps for compiler invocations with different compiler binaries and/or
3955different text / bss / data / heap / stack / dso start locations.
3956
3957@item -fdump-unnumbered
3958@opindex fdump-unnumbered
3959When doing debugging dumps (see @option{-d} option above), suppress instruction
3960numbers, line number note and address output. This makes it more feasible to
3961use diff on debugging dumps for compiler invocations with different
3962options, in particular with and without @option{-g}.
3963
3964@item -fdump-translation-unit @r{(C++ only)}
3965@itemx -fdump-translation-unit-@var{options} @r{(C++ only)}
3966@opindex fdump-translation-unit
3967Dump a representation of the tree structure for the entire translation
3968unit to a file. The file name is made by appending @file{.tu} to the
3969source file name. If the @samp{-@var{options}} form is used, @var{options}
3970controls the details of the dump as described for the
3971@option{-fdump-tree} options.
3972
3973@item -fdump-class-hierarchy @r{(C++ only)}
3974@itemx -fdump-class-hierarchy-@var{options} @r{(C++ only)}
3975@opindex fdump-class-hierarchy
3976Dump a representation of each class's hierarchy and virtual function
3977table layout to a file. The file name is made by appending @file{.class}
3978to the source file name. If the @samp{-@var{options}} form is used,
3979@var{options} controls the details of the dump as described for the
3980@option{-fdump-tree} options.
3981
3982@item -fdump-ipa-@var{switch}
3983@opindex fdump-ipa
3984Control the dumping at various stages of inter-procedural analysis
3985language tree to a file. The file name is generated by appending a switch
3986specific suffix to the source file name. The following dumps are possible:
3987
3988@table @samp
3989@item all
3990Enables all inter-procedural analysis dumps; currently the only produced
3991dump is the @samp{cgraph} dump.
3992
3993@item cgraph
3994Dumps information about call-graph optimization, unused function removal,
3995and inlining decisions.
3996@end table
3997
3998@item -fdump-tree-@var{switch}
3999@itemx -fdump-tree-@var{switch}-@var{options}
4000@opindex fdump-tree
4001Control the dumping at various stages of processing the intermediate
4002language tree to a file. The file name is generated by appending a switch
4003specific suffix to the source file name. If the @samp{-@var{options}}
4004form is used, @var{options} is a list of @samp{-} separated options that
4005control the details of the dump. Not all options are applicable to all
4006dumps, those which are not meaningful will be ignored. The following
4007options are available
4008
4009@table @samp
4010@item address
4011Print the address of each node. Usually this is not meaningful as it
4012changes according to the environment and source file. Its primary use
4013is for tying up a dump file with a debug environment.
4014@item slim
4015Inhibit dumping of members of a scope or body of a function merely
4016because that scope has been reached. Only dump such items when they
4017are directly reachable by some other path. When dumping pretty-printed
4018trees, this option inhibits dumping the bodies of control structures.
4019@item raw
4020Print a raw representation of the tree. By default, trees are
4021pretty-printed into a C-like representation.
4022@item details
4023Enable more detailed dumps (not honored by every dump option).
4024@item stats
4025Enable dumping various statistics about the pass (not honored by every dump
4026option).
4027@item blocks
4028Enable showing basic block boundaries (disabled in raw dumps).
4029@item vops
4030Enable showing virtual operands for every statement.
4031@item lineno
4032Enable showing line numbers for statements.
4033@item uid
4034Enable showing the unique ID (@code{DECL_UID}) for each variable.
4035@item all
4036Turn on all options, except @option{raw}, @option{slim} and @option{lineno}.
4037@end table
4038
4039The following tree dumps are possible:
4040@table @samp
4041
4042@item original
4043Dump before any tree based optimization, to @file{@var{file}.original}.
4044
4045@item optimized
4046Dump after all tree based optimization, to @file{@var{file}.optimized}.
4047
4048@item inlined
4049Dump after function inlining, to @file{@var{file}.inlined}.
4050
4051@item gimple
4052@opindex fdump-tree-gimple
4053Dump each function before and after the gimplification pass to a file. The
4054file name is made by appending @file{.gimple} to the source file name.
4055
4056@item cfg
4057@opindex fdump-tree-cfg
4058Dump the control flow graph of each function to a file. The file name is
4059made by appending @file{.cfg} to the source file name.
4060
4061@item vcg
4062@opindex fdump-tree-vcg
4063Dump the control flow graph of each function to a file in VCG format. The
4064file name is made by appending @file{.vcg} to the source file name. Note
4065that if the file contains more than one function, the generated file cannot
4066be used directly by VCG@. You will need to cut and paste each function's
4067graph into its own separate file first.
4068
4069@item ch
4070@opindex fdump-tree-ch
4071Dump each function after copying loop headers. The file name is made by
4072appending @file{.ch} to the source file name.
4073
4074@item ssa
4075@opindex fdump-tree-ssa
4076Dump SSA related information to a file. The file name is made by appending
4077@file{.ssa} to the source file name.
4078
4079@item salias
4080@opindex fdump-tree-salias
4081Dump structure aliasing variable information to a file. This file name
4082is made by appending @file{.salias} to the source file name.
4083
4084@item alias
4085@opindex fdump-tree-alias
4086Dump aliasing information for each function. The file name is made by
4087appending @file{.alias} to the source file name.
4088
4089@item ccp
4090@opindex fdump-tree-ccp
4091Dump each function after CCP@. The file name is made by appending
4092@file{.ccp} to the source file name.
4093
4094@item storeccp
4095@opindex fdump-tree-storeccp
4096Dump each function after STORE-CCP. The file name is made by appending
4097@file{.storeccp} to the source file name.
4098
4099@item pre
4100@opindex fdump-tree-pre
4101Dump trees after partial redundancy elimination. The file name is made
4102by appending @file{.pre} to the source file name.
4103
4104@item fre
4105@opindex fdump-tree-fre
4106Dump trees after full redundancy elimination. The file name is made
4107by appending @file{.fre} to the source file name.
4108
4109@item copyprop
4110@opindex fdump-tree-copyprop
4111Dump trees after copy propagation. The file name is made
4112by appending @file{.copyprop} to the source file name.
4113
4114@item store_copyprop
4115@opindex fdump-tree-store_copyprop
4116Dump trees after store copy-propagation. The file name is made
4117by appending @file{.store_copyprop} to the source file name.
4118
4119@item dce
4120@opindex fdump-tree-dce
4121Dump each function after dead code elimination. The file name is made by
4122appending @file{.dce} to the source file name.
4123
4124@item mudflap
4125@opindex fdump-tree-mudflap
4126Dump each function after adding mudflap instrumentation. The file name is
4127made by appending @file{.mudflap} to the source file name.
4128
4129@item sra
4130@opindex fdump-tree-sra
4131Dump each function after performing scalar replacement of aggregates. The
4132file name is made by appending @file{.sra} to the source file name.
4133
4134@item sink
4135@opindex fdump-tree-sink
4136Dump each function after performing code sinking. The file name is made
4137by appending @file{.sink} to the source file name.
4138
4139@item dom
4140@opindex fdump-tree-dom
4141Dump each function after applying dominator tree optimizations. The file
4142name is made by appending @file{.dom} to the source file name.
4143
4144@item dse
4145@opindex fdump-tree-dse
4146Dump each function after applying dead store elimination. The file
4147name is made by appending @file{.dse} to the source file name.
4148
4149@item phiopt
4150@opindex fdump-tree-phiopt
4151Dump each function after optimizing PHI nodes into straightline code. The file
4152name is made by appending @file{.phiopt} to the source file name.
4153
4154@item forwprop
4155@opindex fdump-tree-forwprop
4156Dump each function after forward propagating single use variables. The file
4157name is made by appending @file{.forwprop} to the source file name.
4158
4159@item copyrename
4160@opindex fdump-tree-copyrename
4161Dump each function after applying the copy rename optimization. The file
4162name is made by appending @file{.copyrename} to the source file name.
4163
4164@item nrv
4165@opindex fdump-tree-nrv
4166Dump each function after applying the named return value optimization on
4167generic trees. The file name is made by appending @file{.nrv} to the source
4168file name.
4169
4170@item vect
4171@opindex fdump-tree-vect
4172Dump each function after applying vectorization of loops. The file name is
4173made by appending @file{.vect} to the source file name.
4174
4175@item vrp
4176@opindex fdump-tree-vrp
4177Dump each function after Value Range Propagation (VRP). The file name
4178is made by appending @file{.vrp} to the source file name.
4179
4180@item all
4181@opindex fdump-tree-all
4182Enable all the available tree dumps with the flags provided in this option.
4183@end table
4184
4185@item -ftree-vectorizer-verbose=@var{n}
4186@opindex ftree-vectorizer-verbose
4187This option controls the amount of debugging output the vectorizer prints.
4188This information is written to standard error, unless
4189@option{-fdump-tree-all} or @option{-fdump-tree-vect} is specified,
4190in which case it is output to the usual dump listing file, @file{.vect}.
4191For @var{n}=0 no diagnostic information is reported.
4192If @var{n}=1 the vectorizer reports each loop that got vectorized,
4193and the total number of loops that got vectorized.
4194If @var{n}=2 the vectorizer also reports non-vectorized loops that passed
4195the first analysis phase (vect_analyze_loop_form) - i.e. countable,
4196inner-most, single-bb, single-entry/exit loops. This is the same verbosity
4197level that @option{-fdump-tree-vect-stats} uses.
4198Higher verbosity levels mean either more information dumped for each
4199reported loop, or same amount of information reported for more loops:
4200If @var{n}=3, alignment related information is added to the reports.
4201If @var{n}=4, data-references related information (e.g. memory dependences,
4202memory access-patterns) is added to the reports.
4203If @var{n}=5, the vectorizer reports also non-vectorized inner-most loops
4204that did not pass the first analysis phase (i.e. may not be countable, or
4205may have complicated control-flow).
4206If @var{n}=6, the vectorizer reports also non-vectorized nested loops.
4207For @var{n}=7, all the information the vectorizer generates during its
4208analysis and transformation is reported. This is the same verbosity level
4209that @option{-fdump-tree-vect-details} uses.
4210
4211@item -frandom-seed=@var{string}
4212@opindex frandom-string
4213This option provides a seed that GCC uses when it would otherwise use
4214random numbers. It is used to generate certain symbol names
4215that have to be different in every compiled file. It is also used to
4216place unique stamps in coverage data files and the object files that
4217produce them. You can use the @option{-frandom-seed} option to produce
4218reproducibly identical object files.
4219
4220The @var{string} should be different for every file you compile.
4221
4222@item -fsched-verbose=@var{n}
4223@opindex fsched-verbose
4224On targets that use instruction scheduling, this option controls the
4225amount of debugging output the scheduler prints. This information is
4226written to standard error, unless @option{-dS} or @option{-dR} is
4227specified, in which case it is output to the usual dump
4228listing file, @file{.sched} or @file{.sched2} respectively. However
4229for @var{n} greater than nine, the output is always printed to standard
4230error.
4231
4232For @var{n} greater than zero, @option{-fsched-verbose} outputs the
4233same information as @option{-dRS}. For @var{n} greater than one, it
4234also output basic block probabilities, detailed ready list information
4235and unit/insn info. For @var{n} greater than two, it includes RTL
4236at abort point, control-flow and regions info. And for @var{n} over
4237four, @option{-fsched-verbose} also includes dependence info.
4238
4239@item -save-temps
4240@opindex save-temps
4241Store the usual ``temporary'' intermediate files permanently; place them
4242in the current directory and name them based on the source file. Thus,
4243compiling @file{foo.c} with @samp{-c -save-temps} would produce files
4244@file{foo.i} and @file{foo.s}, as well as @file{foo.o}. This creates a
4245preprocessed @file{foo.i} output file even though the compiler now
4246normally uses an integrated preprocessor.
4247
4248When used in combination with the @option{-x} command line option,
4249@option{-save-temps} is sensible enough to avoid over writing an
4250input source file with the same extension as an intermediate file.
4251The corresponding intermediate file may be obtained by renaming the
4252source file before using @option{-save-temps}.
4253
4254@item -time
4255@opindex time
4256Report the CPU time taken by each subprocess in the compilation
4257sequence. For C source files, this is the compiler proper and assembler
4258(plus the linker if linking is done). The output looks like this:
4259
4260@smallexample
4261# cc1 0.12 0.01
4262# as 0.00 0.01
4263@end smallexample
4264
4265The first number on each line is the ``user time'', that is time spent
4266executing the program itself. The second number is ``system time'',
4267time spent executing operating system routines on behalf of the program.
4268Both numbers are in seconds.
4269
4270@item -fvar-tracking
4271@opindex fvar-tracking
4272Run variable tracking pass. It computes where variables are stored at each
4273position in code. Better debugging information is then generated
4274(if the debugging information format supports this information).
4275
4276It is enabled by default when compiling with optimization (@option{-Os},
4277@option{-O}, @option{-O2}, ...), debugging information (@option{-g}) and
4278the debug info format supports it.
4279
4280@item -print-file-name=@var{library}
4281@opindex print-file-name
4282Print the full absolute name of the library file @var{library} that
4283would be used when linking---and don't do anything else. With this
4284option, GCC does not compile or link anything; it just prints the
4285file name.
4286
4287@item -print-multi-directory
4288@opindex print-multi-directory
4289Print the directory name corresponding to the multilib selected by any
4290other switches present in the command line. This directory is supposed
4291to exist in @env{GCC_EXEC_PREFIX}.
4292
4293@item -print-multi-lib
4294@opindex print-multi-lib
4295Print the mapping from multilib directory names to compiler switches
4296that enable them. The directory name is separated from the switches by
4297@samp{;}, and each switch starts with an @samp{@@} instead of the
4298@samp{-}, without spaces between multiple switches. This is supposed to
4299ease shell-processing.
4300
4301@item -print-prog-name=@var{program}
4302@opindex print-prog-name
4303Like @option{-print-file-name}, but searches for a program such as @samp{cpp}.
4304
4305@item -print-libgcc-file-name
4306@opindex print-libgcc-file-name
4307Same as @option{-print-file-name=libgcc.a}.
4308
4309This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs}
4310but you do want to link with @file{libgcc.a}. You can do
4311
4312@smallexample
4313gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
4314@end smallexample
4315
4316@item -print-search-dirs
4317@opindex print-search-dirs
4318Print the name of the configured installation directory and a list of
4319program and library directories @command{gcc} will search---and don't do anything else.
4320
4321This is useful when @command{gcc} prints the error message
4322@samp{installation problem, cannot exec cpp0: No such file or directory}.
4323To resolve this you either need to put @file{cpp0} and the other compiler
4324components where @command{gcc} expects to find them, or you can set the environment
4325variable @env{GCC_EXEC_PREFIX} to the directory where you installed them.
4326Don't forget the trailing @samp{/}.
4327@xref{Environment Variables}.
4328
4329@item -dumpmachine
4330@opindex dumpmachine
4331Print the compiler's target machine (for example,
4332@samp{i686-pc-linux-gnu})---and don't do anything else.
4333
4334@item -dumpversion
4335@opindex dumpversion
4336Print the compiler version (for example, @samp{3.0})---and don't do
4337anything else.
4338
4339@item -dumpspecs
4340@opindex dumpspecs
4341Print the compiler's built-in specs---and don't do anything else. (This
4342is used when GCC itself is being built.) @xref{Spec Files}.
4343
4344@item -feliminate-unused-debug-types
4345@opindex feliminate-unused-debug-types
4346Normally, when producing DWARF2 output, GCC will emit debugging
4347information for all types declared in a compilation
4348unit, regardless of whether or not they are actually used
4349in that compilation unit. Sometimes this is useful, such as
4350if, in the debugger, you want to cast a value to a type that is
4351not actually used in your program (but is declared). More often,
4352however, this results in a significant amount of wasted space.
4353With this option, GCC will avoid producing debug symbol output
4354for types that are nowhere used in the source file being compiled.
4355@end table
4356
4357@node Optimize Options
4358@section Options That Control Optimization
4359@cindex optimize options
4360@cindex options, optimization
4361
4362These options control various sorts of optimizations.
4363
4364Without any optimization option, the compiler's goal is to reduce the
4365cost of compilation and to make debugging produce the expected
4366results. Statements are independent: if you stop the program with a
4367breakpoint between statements, you can then assign a new value to any
4368variable or change the program counter to any other statement in the
4369function and get exactly the results you would expect from the source
4370code.
4371
4372Turning on optimization flags makes the compiler attempt to improve
4373the performance and/or code size at the expense of compilation time
4374and possibly the ability to debug the program.
4375
4376The compiler performs optimization based on the knowledge it has of
4377the program. Optimization levels @option{-O} and above, in
4378particular, enable @emph{unit-at-a-time} mode, which allows the
4379compiler to consider information gained from later functions in
4380the file when compiling a function. Compiling multiple files at
4381once to a single output file in @emph{unit-at-a-time} mode allows
4382the compiler to use information gained from all of the files when
4383compiling each of them.
4384
4385Not all optimizations are controlled directly by a flag. Only
4386optimizations that have a flag are listed.
4387
4388@table @gcctabopt
4389@item -O
4390@itemx -O1
4391@opindex O
4392@opindex O1
4393Optimize. Optimizing compilation takes somewhat more time, and a lot
4394more memory for a large function.
4395
4396With @option{-O}, the compiler tries to reduce code size and execution
4397time, without performing any optimizations that take a great deal of
4398compilation time.
4399
4400@option{-O} turns on the following optimization flags:
4401@gccoptlist{-fdefer-pop @gol
4402-fdelayed-branch @gol
4403-fguess-branch-probability @gol
4404-fcprop-registers @gol
4405-fif-conversion @gol
4406-fif-conversion2 @gol
4407-ftree-ccp @gol
4408-ftree-dce @gol
4409-ftree-dominator-opts @gol
4410-ftree-dse @gol
4411-ftree-ter @gol
4412-ftree-lrs @gol
4413-ftree-sra @gol
4414-ftree-copyrename @gol
4415-ftree-fre @gol
4416-ftree-ch @gol
4417-funit-at-a-time @gol
4418-fmerge-constants}
4419
4420@option{-O} also turns on @option{-fomit-frame-pointer} on machines
4421where doing so does not interfere with debugging.
4422
4423@item -O2
4424@opindex O2
4425Optimize even more. GCC performs nearly all supported optimizations
4426that do not involve a space-speed tradeoff. The compiler does not
4427perform loop unrolling or function inlining when you specify @option{-O2}.
4428As compared to @option{-O}, this option increases both compilation time
4429and the performance of the generated code.
4430
4431@option{-O2} turns on all optimization flags specified by @option{-O}. It
4432also turns on the following optimization flags:
4433@gccoptlist{-fthread-jumps @gol
4434-fcrossjumping @gol
4435-foptimize-sibling-calls @gol
4436-fcse-follow-jumps -fcse-skip-blocks @gol
4437-fgcse -fgcse-lm @gol
4438-fexpensive-optimizations @gol
4439-frerun-cse-after-loop @gol
4440-fcaller-saves @gol
4441-fpeephole2 @gol
4442-fschedule-insns -fschedule-insns2 @gol
4443-fsched-interblock -fsched-spec @gol
4444-fregmove @gol
4445-fstrict-aliasing -fstrict-overflow @gol
4446-fdelete-null-pointer-checks @gol
4447-freorder-blocks -freorder-functions @gol
4448-falign-functions -falign-jumps @gol
4449-falign-loops -falign-labels @gol
4450-ftree-vrp @gol
4451-ftree-pre}
4452
4453Please note the warning under @option{-fgcse} about
4454invoking @option{-O2} on programs that use computed gotos.
4455
4456@option{-O2} doesn't turn on @option{-ftree-vrp} for the Ada compiler.
4457This option must be explicitly specified on the command line to be
4458enabled for the Ada compiler.
4459
4460@item -O3
4461@opindex O3
4462Optimize yet more. @option{-O3} turns on all optimizations specified by
4463@option{-O2} and also turns on the @option{-finline-functions},
4464@option{-funswitch-loops} and @option{-fgcse-after-reload} options.
4465
4466@item -O0
4467@opindex O0
4468Do not optimize. This is the default.
4469
4470@item -Os
4471@opindex Os
4472Optimize for size. @option{-Os} enables all @option{-O2} optimizations that
4473do not typically increase code size. It also performs further
4474optimizations designed to reduce code size.
4475
4476@option{-Os} disables the following optimization flags:
4477@gccoptlist{-falign-functions -falign-jumps -falign-loops @gol
4478-falign-labels -freorder-blocks -freorder-blocks-and-partition @gol
4479-fprefetch-loop-arrays -ftree-vect-loop-version}
4480
4481If you use multiple @option{-O} options, with or without level numbers,
4482the last such option is the one that is effective.
4483@end table
4484
4485Options of the form @option{-f@var{flag}} specify machine-independent
4486flags. Most flags have both positive and negative forms; the negative
4487form of @option{-ffoo} would be @option{-fno-foo}. In the table
4488below, only one of the forms is listed---the one you typically will
4489use. You can figure out the other form by either removing @samp{no-}
4490or adding it.
4491
4492The following options control specific optimizations. They are either
4493activated by @option{-O} options or are related to ones that are. You
4494can use the following flags in the rare cases when ``fine-tuning'' of
4495optimizations to be performed is desired.
4496
4497@table @gcctabopt
4498@item -fno-default-inline
4499@opindex fno-default-inline
4500Do not make member functions inline by default merely because they are
4501defined inside the class scope (C++ only). Otherwise, when you specify
4502@w{@option{-O}}, member functions defined inside class scope are compiled
4503inline by default; i.e., you don't need to add @samp{inline} in front of
4504the member function name.
4505
4506@item -fno-defer-pop
4507@opindex fno-defer-pop
4508Always pop the arguments to each function call as soon as that function
4509returns. For machines which must pop arguments after a function call,
4510the compiler normally lets arguments accumulate on the stack for several
4511function calls and pops them all at once.
4512
4513Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4514
4515@item -fforce-mem
4516@opindex fforce-mem
4517Force memory operands to be copied into registers before doing
4518arithmetic on them. This produces better code by making all memory
4519references potential common subexpressions. When they are not common
4520subexpressions, instruction combination should eliminate the separate
4521register-load. This option is now a nop and will be removed in 4.3.
4522
4523@item -fforce-addr
4524@opindex fforce-addr
4525Force memory address constants to be copied into registers before
4526doing arithmetic on them.
4527
4528@item -fomit-frame-pointer
4529@opindex fomit-frame-pointer
4530Don't keep the frame pointer in a register for functions that
4531don't need one. This avoids the instructions to save, set up and
4532restore frame pointers; it also makes an extra register available
4533in many functions. @strong{It also makes debugging impossible on
4534some machines.}
4535
4536On some machines, such as the VAX, this flag has no effect, because
4537the standard calling sequence automatically handles the frame pointer
4538and nothing is saved by pretending it doesn't exist. The
4539machine-description macro @code{FRAME_POINTER_REQUIRED} controls
4540whether a target machine supports this flag. @xref{Registers,,Register
4541Usage, gccint, GNU Compiler Collection (GCC) Internals}.
4542
4543Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4544
4545@item -foptimize-sibling-calls
4546@opindex foptimize-sibling-calls
4547Optimize sibling and tail recursive calls.
4548
4549Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4550
4551@item -fno-inline
4552@opindex fno-inline
4553Don't pay attention to the @code{inline} keyword. Normally this option
4554is used to keep the compiler from expanding any functions inline.
4555Note that if you are not optimizing, no functions can be expanded inline.
4556
4557@item -finline-functions
4558@opindex finline-functions
4559Integrate all simple functions into their callers. The compiler
4560heuristically decides which functions are simple enough to be worth
4561integrating in this way.
4562
4563If all calls to a given function are integrated, and the function is
4564declared @code{static}, then the function is normally not output as
4565assembler code in its own right.
4566
4567Enabled at level @option{-O3}.
4568
4569@item -finline-functions-called-once
4570@opindex finline-functions-called-once
4571Consider all @code{static} functions called once for inlining into their
4572caller even if they are not marked @code{inline}. If a call to a given
4573function is integrated, then the function is not output as assembler code
4574in its own right.
4575
4576Enabled if @option{-funit-at-a-time} is enabled.
4577
4578@item -fearly-inlining
4579@opindex fearly-inlining
4580Inline functions marked by @code{always_inline} and functions whose body seems
4581smaller than the function call overhead early before doing
4582@option{-fprofile-generate} instrumentation and real inlining pass. Doing so
4583makes profiling significantly cheaper and usually inlining faster on programs
4584having large chains of nested wrapper functions.
4585
4586Enabled by default.
4587
4588@item -finline-limit=@var{n}
4589@opindex finline-limit
4590By default, GCC limits the size of functions that can be inlined. This flag
4591allows the control of this limit for functions that are explicitly marked as
4592inline (i.e., marked with the inline keyword or defined within the class
4593definition in c++). @var{n} is the size of functions that can be inlined in
4594number of pseudo instructions (not counting parameter handling). The default
4595value of @var{n} is 600.
4596Increasing this value can result in more inlined code at
4597the cost of compilation time and memory consumption. Decreasing usually makes
4598the compilation faster and less code will be inlined (which presumably
4599means slower programs). This option is particularly useful for programs that
4600use inlining heavily such as those based on recursive templates with C++.
4601
4602Inlining is actually controlled by a number of parameters, which may be
4603specified individually by using @option{--param @var{name}=@var{value}}.
4604The @option{-finline-limit=@var{n}} option sets some of these parameters
4605as follows:
4606
4607@table @gcctabopt
4608@item max-inline-insns-single
4609 is set to @var{n}/2.
4610@item max-inline-insns-auto
4611 is set to @var{n}/2.
4612@item min-inline-insns
4613 is set to 130 or @var{n}/4, whichever is smaller.
4614@item max-inline-insns-rtl
4615 is set to @var{n}.
4616@end table
4617
4618See below for a documentation of the individual
4619parameters controlling inlining.
4620
4621@emph{Note:} pseudo instruction represents, in this particular context, an
4622abstract measurement of function's size. In no way does it represent a count
4623of assembly instructions and as such its exact meaning might change from one
4624release to an another.
4625
4626@item -fkeep-inline-functions
4627@opindex fkeep-inline-functions
4628In C, emit @code{static} functions that are declared @code{inline}
4629into the object file, even if the function has been inlined into all
4630of its callers. This switch does not affect functions using the
4631@code{extern inline} extension in GNU C@. In C++, emit any and all
4632inline functions into the object file.
4633
4634@item -fkeep-static-consts
4635@opindex fkeep-static-consts
4636Emit variables declared @code{static const} when optimization isn't turned
4637on, even if the variables aren't referenced.
4638
4639GCC enables this option by default. If you want to force the compiler to
4640check if the variable was referenced, regardless of whether or not
4641optimization is turned on, use the @option{-fno-keep-static-consts} option.
4642
4643@item -fmerge-constants
4644Attempt to merge identical constants (string constants and floating point
4645constants) across compilation units.
4646
4647This option is the default for optimized compilation if the assembler and
4648linker support it. Use @option{-fno-merge-constants} to inhibit this
4649behavior.
4650
4651Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4652
4653@item -fmerge-all-constants
4654Attempt to merge identical constants and identical variables.
4655
4656This option implies @option{-fmerge-constants}. In addition to
4657@option{-fmerge-constants} this considers e.g.@: even constant initialized
4658arrays or initialized constant variables with integral or floating point
4659types. Languages like C or C++ require each non-automatic variable to
4660have distinct location, so using this option will result in non-conforming
4661behavior.
4662
4663@item -fmodulo-sched
4664@opindex fmodulo-sched
4665Perform swing modulo scheduling immediately before the first scheduling
4666pass. This pass looks at innermost loops and reorders their
4667instructions by overlapping different iterations.
4668
4669@item -fno-branch-count-reg
4670@opindex fno-branch-count-reg
4671Do not use ``decrement and branch'' instructions on a count register,
4672but instead generate a sequence of instructions that decrement a
4673register, compare it against zero, then branch based upon the result.
4674This option is only meaningful on architectures that support such
4675instructions, which include x86, PowerPC, IA-64 and S/390.
4676
4677The default is @option{-fbranch-count-reg}.
4678
4679@item -fno-function-cse
4680@opindex fno-function-cse
4681Do not put function addresses in registers; make each instruction that
4682calls a constant function contain the function's address explicitly.
4683
4684This option results in less efficient code, but some strange hacks
4685that alter the assembler output may be confused by the optimizations
4686performed when this option is not used.
4687
4688The default is @option{-ffunction-cse}
4689
4690@item -fno-zero-initialized-in-bss
4691@opindex fno-zero-initialized-in-bss
4692If the target supports a BSS section, GCC by default puts variables that
4693are initialized to zero into BSS@. This can save space in the resulting
4694code.
4695
4696This option turns off this behavior because some programs explicitly
4697rely on variables going to the data section. E.g., so that the
4698resulting executable can find the beginning of that section and/or make
4699assumptions based on that.
4700
4701The default is @option{-fzero-initialized-in-bss}.
4702
4703@item -fbounds-check
4704@opindex fbounds-check
4705For front-ends that support it, generate additional code to check that
4706indices used to access arrays are within the declared range. This is
4707currently only supported by the Java and Fortran front-ends, where
4708this option defaults to true and false respectively.
4709
4710@item -fmudflap -fmudflapth -fmudflapir
4711@opindex fmudflap
4712@opindex fmudflapth
4713@opindex fmudflapir
4714@cindex bounds checking
4715@cindex mudflap
4716For front-ends that support it (C and C++), instrument all risky
4717pointer/array dereferencing operations, some standard library
4718string/heap functions, and some other associated constructs with
4719range/validity tests. Modules so instrumented should be immune to
4720buffer overflows, invalid heap use, and some other classes of C/C++
4721programming errors. The instrumentation relies on a separate runtime
4722library (@file{libmudflap}), which will be linked into a program if
4723@option{-fmudflap} is given at link time. Run-time behavior of the
4724instrumented program is controlled by the @env{MUDFLAP_OPTIONS}
4725environment variable. See @code{env MUDFLAP_OPTIONS=-help a.out}
4726for its options.
4727
4728Use @option{-fmudflapth} instead of @option{-fmudflap} to compile and to
4729link if your program is multi-threaded. Use @option{-fmudflapir}, in
4730addition to @option{-fmudflap} or @option{-fmudflapth}, if
4731instrumentation should ignore pointer reads. This produces less
4732instrumentation (and therefore faster execution) and still provides
4733some protection against outright memory corrupting writes, but allows
4734erroneously read data to propagate within a program.
4735
4736@item -fthread-jumps
4737@opindex fthread-jumps
4738Perform optimizations where we check to see if a jump branches to a
4739location where another comparison subsumed by the first is found. If
4740so, the first branch is redirected to either the destination of the
4741second branch or a point immediately following it, depending on whether
4742the condition is known to be true or false.
4743
4744Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4745
4746@item -fcse-follow-jumps
4747@opindex fcse-follow-jumps
4748In common subexpression elimination, scan through jump instructions
4749when the target of the jump is not reached by any other path. For
4750example, when CSE encounters an @code{if} statement with an
4751@code{else} clause, CSE will follow the jump when the condition
4752tested is false.
4753
4754Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4755
4756@item -fcse-skip-blocks
4757@opindex fcse-skip-blocks
4758This is similar to @option{-fcse-follow-jumps}, but causes CSE to
4759follow jumps which conditionally skip over blocks. When CSE
4760encounters a simple @code{if} statement with no else clause,
4761@option{-fcse-skip-blocks} causes CSE to follow the jump around the
4762body of the @code{if}.
4763
4764Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4765
4766@item -frerun-cse-after-loop
4767@opindex frerun-cse-after-loop
4768Re-run common subexpression elimination after loop optimizations has been
4769performed.
4770
4771Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4772
4773@item -fgcse
4774@opindex fgcse
4775Perform a global common subexpression elimination pass.
4776This pass also performs global constant and copy propagation.
4777
4778@emph{Note:} When compiling a program using computed gotos, a GCC
4779extension, you may get better runtime performance if you disable
4780the global common subexpression elimination pass by adding
4781@option{-fno-gcse} to the command line.
4782
4783Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4784
4785@item -fgcse-lm
4786@opindex fgcse-lm
4787When @option{-fgcse-lm} is enabled, global common subexpression elimination will
4788attempt to move loads which are only killed by stores into themselves. This
4789allows a loop containing a load/store sequence to be changed to a load outside
4790the loop, and a copy/store within the loop.
4791
4792Enabled by default when gcse is enabled.
4793
4794@item -fgcse-sm
4795@opindex fgcse-sm
4796When @option{-fgcse-sm} is enabled, a store motion pass is run after
4797global common subexpression elimination. This pass will attempt to move
4798stores out of loops. When used in conjunction with @option{-fgcse-lm},
4799loops containing a load/store sequence can be changed to a load before
4800the loop and a store after the loop.
4801
4802Not enabled at any optimization level.
4803
4804@item -fgcse-las
4805@opindex fgcse-las
4806When @option{-fgcse-las} is enabled, the global common subexpression
4807elimination pass eliminates redundant loads that come after stores to the
4808same memory location (both partial and full redundancies).
4809
4810Not enabled at any optimization level.
4811
4812@item -fgcse-after-reload
4813@opindex fgcse-after-reload
4814When @option{-fgcse-after-reload} is enabled, a redundant load elimination
4815pass is performed after reload. The purpose of this pass is to cleanup
4816redundant spilling.
4817
4818@item -funsafe-loop-optimizations
4819@opindex funsafe-loop-optimizations
4820If given, the loop optimizer will assume that loop indices do not
4821overflow, and that the loops with nontrivial exit condition are not
4822infinite. This enables a wider range of loop optimizations even if
4823the loop optimizer itself cannot prove that these assumptions are valid.
4824Using @option{-Wunsafe-loop-optimizations}, the compiler will warn you
4825if it finds this kind of loop.
4826
4827@item -fcrossjumping
4828@opindex crossjumping
4829Perform cross-jumping transformation. This transformation unifies equivalent code and save code size. The
4830resulting code may or may not perform better than without cross-jumping.
4831
4832Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4833
4834@item -fif-conversion
4835@opindex if-conversion
4836Attempt to transform conditional jumps into branch-less equivalents. This
4837include use of conditional moves, min, max, set flags and abs instructions, and
4838some tricks doable by standard arithmetics. The use of conditional execution
4839on chips where it is available is controlled by @code{if-conversion2}.
4840
4841Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4842
4843@item -fif-conversion2
4844@opindex if-conversion2
4845Use conditional execution (where available) to transform conditional jumps into
4846branch-less equivalents.
4847
4848Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4849
4850@item -fdelete-null-pointer-checks
4851@opindex fdelete-null-pointer-checks
4852Use global dataflow analysis to identify and eliminate useless checks
4853for null pointers. The compiler assumes that dereferencing a null
4854pointer would have halted the program. If a pointer is checked after
4855it has already been dereferenced, it cannot be null.
4856
4857In some environments, this assumption is not true, and programs can
4858safely dereference null pointers. Use
4859@option{-fno-delete-null-pointer-checks} to disable this optimization
4860for programs which depend on that behavior.
4861
4862Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4863
4864@item -fexpensive-optimizations
4865@opindex fexpensive-optimizations
4866Perform a number of minor optimizations that are relatively expensive.
4867
4868Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4869
4870@item -foptimize-register-move
4871@itemx -fregmove
4872@opindex foptimize-register-move
4873@opindex fregmove
4874Attempt to reassign register numbers in move instructions and as
4875operands of other simple instructions in order to maximize the amount of
4876register tying. This is especially helpful on machines with two-operand
4877instructions.
4878
4879Note @option{-fregmove} and @option{-foptimize-register-move} are the same
4880optimization.
4881
4882Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4883
4884@item -fdelayed-branch
4885@opindex fdelayed-branch
4886If supported for the target machine, attempt to reorder instructions
4887to exploit instruction slots available after delayed branch
4888instructions.
4889
4890Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4891
4892@item -fschedule-insns
4893@opindex fschedule-insns
4894If supported for the target machine, attempt to reorder instructions to
4895eliminate execution stalls due to required data being unavailable. This
4896helps machines that have slow floating point or memory load instructions
4897by allowing other instructions to be issued until the result of the load
4898or floating point instruction is required.
4899
4900Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4901
4902@item -fschedule-insns2
4903@opindex fschedule-insns2
4904Similar to @option{-fschedule-insns}, but requests an additional pass of
4905instruction scheduling after register allocation has been done. This is
4906especially useful on machines with a relatively small number of
4907registers and where memory load instructions take more than one cycle.
4908
4909Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4910
4911@item -fno-sched-interblock
4912@opindex fno-sched-interblock
4913Don't schedule instructions across basic blocks. This is normally
4914enabled by default when scheduling before register allocation, i.e.@:
4915with @option{-fschedule-insns} or at @option{-O2} or higher.
4916
4917@item -fno-sched-spec
4918@opindex fno-sched-spec
4919Don't allow speculative motion of non-load instructions. This is normally
4920enabled by default when scheduling before register allocation, i.e.@:
4921with @option{-fschedule-insns} or at @option{-O2} or higher.
4922
4923@item -fsched-spec-load
4924@opindex fsched-spec-load
4925Allow speculative motion of some load instructions. This only makes
4926sense when scheduling before register allocation, i.e.@: with
4927@option{-fschedule-insns} or at @option{-O2} or higher.
4928
4929@item -fsched-spec-load-dangerous
4930@opindex fsched-spec-load-dangerous
4931Allow speculative motion of more load instructions. This only makes
4932sense when scheduling before register allocation, i.e.@: with
4933@option{-fschedule-insns} or at @option{-O2} or higher.
4934
4935@item -fsched-stalled-insns=@var{n}
4936@opindex fsched-stalled-insns
4937Define how many insns (if any) can be moved prematurely from the queue
4938of stalled insns into the ready list, during the second scheduling pass.
4939
4940@item -fsched-stalled-insns-dep=@var{n}
4941@opindex fsched-stalled-insns-dep
4942Define how many insn groups (cycles) will be examined for a dependency
4943on a stalled insn that is candidate for premature removal from the queue
4944of stalled insns. Has an effect only during the second scheduling pass,
4945and only if @option{-fsched-stalled-insns} is used and its value is not zero.
4946
4947@item -fsched2-use-superblocks
4948@opindex fsched2-use-superblocks
4949When scheduling after register allocation, do use superblock scheduling
4950algorithm. Superblock scheduling allows motion across basic block boundaries
4951resulting on faster schedules. This option is experimental, as not all machine
4952descriptions used by GCC model the CPU closely enough to avoid unreliable
4953results from the algorithm.
4954
4955This only makes sense when scheduling after register allocation, i.e.@: with
4956@option{-fschedule-insns2} or at @option{-O2} or higher.
4957
4958@item -fsched2-use-traces
4959@opindex fsched2-use-traces
4960Use @option{-fsched2-use-superblocks} algorithm when scheduling after register
4961allocation and additionally perform code duplication in order to increase the
4962size of superblocks using tracer pass. See @option{-ftracer} for details on
4963trace formation.
4964
4965This mode should produce faster but significantly longer programs. Also
4966without @option{-fbranch-probabilities} the traces constructed may not
4967match the reality and hurt the performance. This only makes
4968sense when scheduling after register allocation, i.e.@: with
4969@option{-fschedule-insns2} or at @option{-O2} or higher.
4970
4971@item -fsee
4972@opindex fsee
4973Eliminates redundant extension instructions and move the non redundant
4974ones to optimal placement using LCM.
4975
4976@item -freschedule-modulo-scheduled-loops
4977@opindex fscheduling-in-modulo-scheduled-loops
4978The modulo scheduling comes before the traditional scheduling, if a loop was modulo scheduled
4979we may want to prevent the later scheduling passes from changing its schedule, we use this
4980option to control that.
4981
4982@item -fcaller-saves
4983@opindex fcaller-saves
4984Enable values to be allocated in registers that will be clobbered by
4985function calls, by emitting extra instructions to save and restore the
4986registers around such calls. Such allocation is done only when it
4987seems to result in better code than would otherwise be produced.
4988
4989This option is always enabled by default on certain machines, usually
4990those which have no call-preserved registers to use instead.
4991
4992Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4993
4994@item -ftree-pre
4995Perform Partial Redundancy Elimination (PRE) on trees. This flag is
4996enabled by default at @option{-O2} and @option{-O3}.
4997
4998@item -ftree-fre
4999Perform Full Redundancy Elimination (FRE) on trees. The difference
5000between FRE and PRE is that FRE only considers expressions
5001that are computed on all paths leading to the redundant computation.
5002This analysis faster than PRE, though it exposes fewer redundancies.
5003This flag is enabled by default at @option{-O} and higher.
5004
5005@item -ftree-copy-prop
5006Perform copy propagation on trees. This pass eliminates unnecessary
5007copy operations. This flag is enabled by default at @option{-O} and
5008higher.
5009
5010@item -ftree-store-copy-prop
5011Perform copy propagation of memory loads and stores. This pass
5012eliminates unnecessary copy operations in memory references
5013(structures, global variables, arrays, etc). This flag is enabled by
5014default at @option{-O2} and higher.
5015
5016@item -ftree-salias
5017Perform structural alias analysis on trees. This flag
5018is enabled by default at @option{-O} and higher.
5019
5020@item -fipa-pta
5021Perform interprocedural pointer analysis.
5022
5023@item -ftree-sink
5024Perform forward store motion on trees. This flag is
5025enabled by default at @option{-O} and higher.
5026
5027@item -ftree-ccp
5028Perform sparse conditional constant propagation (CCP) on trees. This
5029pass only operates on local scalar variables and is enabled by default
5030at @option{-O} and higher.
5031
5032@item -ftree-store-ccp
5033Perform sparse conditional constant propagation (CCP) on trees. This
5034pass operates on both local scalar variables and memory stores and
5035loads (global variables, structures, arrays, etc). This flag is
5036enabled by default at @option{-O2} and higher.
5037
5038@item -ftree-dce
5039Perform dead code elimination (DCE) on trees. This flag is enabled by
5040default at @option{-O} and higher.
5041
5042@item -ftree-dominator-opts
5043Perform a variety of simple scalar cleanups (constant/copy
5044propagation, redundancy elimination, range propagation and expression
5045simplification) based on a dominator tree traversal. This also
5046performs jump threading (to reduce jumps to jumps). This flag is
5047enabled by default at @option{-O} and higher.
5048
5049@item -ftree-ch
5050Perform loop header copying on trees. This is beneficial since it increases
5051effectiveness of code motion optimizations. It also saves one jump. This flag
5052is enabled by default at @option{-O} and higher. It is not enabled
5053for @option{-Os}, since it usually increases code size.
5054
5055@item -ftree-loop-optimize
5056Perform loop optimizations on trees. This flag is enabled by default
5057at @option{-O} and higher.
5058
5059@item -ftree-loop-linear
5060Perform linear loop transformations on tree. This flag can improve cache
5061performance and allow further loop optimizations to take place.
5062
5063@item -ftree-loop-im
5064Perform loop invariant motion on trees. This pass moves only invariants that
5065would be hard to handle at RTL level (function calls, operations that expand to
5066nontrivial sequences of insns). With @option{-funswitch-loops} it also moves
5067operands of conditions that are invariant out of the loop, so that we can use
5068just trivial invariantness analysis in loop unswitching. The pass also includes
5069store motion.
5070
5071@item -ftree-loop-ivcanon
5072Create a canonical counter for number of iterations in the loop for that
5073determining number of iterations requires complicated analysis. Later
5074optimizations then may determine the number easily. Useful especially
5075in connection with unrolling.
5076
5077@item -fivopts
5078Perform induction variable optimizations (strength reduction, induction
5079variable merging and induction variable elimination) on trees.
5080
5081@item -ftree-sra
5082Perform scalar replacement of aggregates. This pass replaces structure
5083references with scalars to prevent committing structures to memory too
5084early. This flag is enabled by default at @option{-O} and higher.
5085
5086@item -ftree-copyrename
5087Perform copy renaming on trees. This pass attempts to rename compiler
5088temporaries to other variables at copy locations, usually resulting in
5089variable names which more closely resemble the original variables. This flag
5090is enabled by default at @option{-O} and higher.
5091
5092@item -ftree-ter
5093Perform temporary expression replacement during the SSA->normal phase. Single
5094use/single def temporaries are replaced at their use location with their
5095defining expression. This results in non-GIMPLE code, but gives the expanders
5096much more complex trees to work on resulting in better RTL generation. This is
5097enabled by default at @option{-O} and higher.
5098
5099@item -ftree-lrs
5100Perform live range splitting during the SSA->normal phase. Distinct live
5101ranges of a variable are split into unique variables, allowing for better
5102optimization later. This is enabled by default at @option{-O} and higher.
5103
5104@item -ftree-vectorize
5105Perform loop vectorization on trees.
5106
5107@item -ftree-vect-loop-version
5108@opindex ftree-vect-loop-version
5109Perform loop versioning when doing loop vectorization on trees. When a loop
5110appears to be vectorizable except that data alignment or data dependence cannot
5111be determined at compile time then vectorized and non-vectorized versions of
5112the loop are generated along with runtime checks for alignment or dependence
5113to control which version is executed. This option is enabled by default
5114except at level @option{-Os} where it is disabled.
5115
5116@item -ftree-vrp
5117Perform Value Range Propagation on trees. This is similar to the
5118constant propagation pass, but instead of values, ranges of values are
5119propagated. This allows the optimizers to remove unnecessary range
5120checks like array bound checks and null pointer checks. This is
5121enabled by default at @option{-O2} and higher. Null pointer check
5122elimination is only done if @option{-fdelete-null-pointer-checks} is
5123enabled.
5124
5125@item -ftracer
5126@opindex ftracer
5127Perform tail duplication to enlarge superblock size. This transformation
5128simplifies the control flow of the function allowing other optimizations to do
5129better job.
5130
5131@item -funroll-loops
5132@opindex funroll-loops
5133Unroll loops whose number of iterations can be determined at compile
5134time or upon entry to the loop. @option{-funroll-loops} implies
5135@option{-frerun-cse-after-loop}. This option makes code larger,
5136and may or may not make it run faster.
5137
5138@item -funroll-all-loops
5139@opindex funroll-all-loops
5140Unroll all loops, even if their number of iterations is uncertain when
5141the loop is entered. This usually makes programs run more slowly.
5142@option{-funroll-all-loops} implies the same options as
5143@option{-funroll-loops},
5144
5145@item -fsplit-ivs-in-unroller
5146@opindex fsplit-ivs-in-unroller
5147Enables expressing of values of induction variables in later iterations
5148of the unrolled loop using the value in the first iteration. This breaks
5149long dependency chains, thus improving efficiency of the scheduling passes.
5150
5151Combination of @option{-fweb} and CSE is often sufficient to obtain the
5152same effect. However in cases the loop body is more complicated than
5153a single basic block, this is not reliable. It also does not work at all
5154on some of the architectures due to restrictions in the CSE pass.
5155
5156This optimization is enabled by default.
5157
5158@item -fvariable-expansion-in-unroller
5159@opindex fvariable-expansion-in-unroller
5160With this option, the compiler will create multiple copies of some
5161local variables when unrolling a loop which can result in superior code.
5162
5163@item -fprefetch-loop-arrays
5164@opindex fprefetch-loop-arrays
5165If supported by the target machine, generate instructions to prefetch
5166memory to improve the performance of loops that access large arrays.
5167
5168This option may generate better or worse code; results are highly
5169dependent on the structure of loops within the source code.
5170
5171Disabled at level @option{-Os}.
5172
5173@item -fno-peephole
5174@itemx -fno-peephole2
5175@opindex fno-peephole
5176@opindex fno-peephole2
5177Disable any machine-specific peephole optimizations. The difference
5178between @option{-fno-peephole} and @option{-fno-peephole2} is in how they
5179are implemented in the compiler; some targets use one, some use the
5180other, a few use both.
5181
5182@option{-fpeephole} is enabled by default.
5183@option{-fpeephole2} enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5184
5185@item -fno-guess-branch-probability
5186@opindex fno-guess-branch-probability
5187Do not guess branch probabilities using heuristics.
5188
5189GCC will use heuristics to guess branch probabilities if they are
5190not provided by profiling feedback (@option{-fprofile-arcs}). These
5191heuristics are based on the control flow graph. If some branch probabilities
5192are specified by @samp{__builtin_expect}, then the heuristics will be
5193used to guess branch probabilities for the rest of the control flow graph,
5194taking the @samp{__builtin_expect} info into account. The interactions
5195between the heuristics and @samp{__builtin_expect} can be complex, and in
5196some cases, it may be useful to disable the heuristics so that the effects
5197of @samp{__builtin_expect} are easier to understand.
5198
5199The default is @option{-fguess-branch-probability} at levels
5200@option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5201
5202@item -freorder-blocks
5203@opindex freorder-blocks
5204Reorder basic blocks in the compiled function in order to reduce number of
5205taken branches and improve code locality.
5206
5207Enabled at levels @option{-O2}, @option{-O3}.
5208
5209@item -freorder-blocks-and-partition
5210@opindex freorder-blocks-and-partition
5211In addition to reordering basic blocks in the compiled function, in order
5212to reduce number of taken branches, partitions hot and cold basic blocks
5213into separate sections of the assembly and .o files, to improve
5214paging and cache locality performance.
5215
5216This optimization is automatically turned off in the presence of
5217exception handling, for linkonce sections, for functions with a user-defined
5218section attribute and on any architecture that does not support named
5219sections.
5220
5221@item -freorder-functions
5222@opindex freorder-functions
5223Reorder functions in the object file in order to
5224improve code locality. This is implemented by using special
5225subsections @code{.text.hot} for most frequently executed functions and
5226@code{.text.unlikely} for unlikely executed functions. Reordering is done by
5227the linker so object file format must support named sections and linker must
5228place them in a reasonable way.
5229
5230Also profile feedback must be available in to make this option effective. See
5231@option{-fprofile-arcs} for details.
5232
5233Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5234
5235@item -fstrict-aliasing
5236@opindex fstrict-aliasing
5237Allows the compiler to assume the strictest aliasing rules applicable to
5238the language being compiled. For C (and C++), this activates
5239optimizations based on the type of expressions. In particular, an
5240object of one type is assumed never to reside at the same address as an
5241object of a different type, unless the types are almost the same. For
5242example, an @code{unsigned int} can alias an @code{int}, but not a
5243@code{void*} or a @code{double}. A character type may alias any other
5244type.
5245
5246Pay special attention to code like this:
5247@smallexample
5248union a_union @{
5249 int i;
5250 double d;
5251@};
5252
5253int f() @{
5254 a_union t;
5255 t.d = 3.0;
5256 return t.i;
5257@}
5258@end smallexample
5259The practice of reading from a different union member than the one most
5260recently written to (called ``type-punning'') is common. Even with
5261@option{-fstrict-aliasing}, type-punning is allowed, provided the memory
5262is accessed through the union type. So, the code above will work as
5263expected. However, this code might not:
5264@smallexample
5265int f() @{
5266 a_union t;
5267 int* ip;
5268 t.d = 3.0;
5269 ip = &t.i;
5270 return *ip;
5271@}
5272@end smallexample
5273
5274Every language that wishes to perform language-specific alias analysis
5275should define a function that computes, given an @code{tree}
5276node, an alias set for the node. Nodes in different alias sets are not
5277allowed to alias. For an example, see the C front-end function
5278@code{c_get_alias_set}.
5279
5280Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5281
5282@item -fstrict-overflow
5283@opindex fstrict-overflow
5284Allow the compiler to assume strict signed overflow rules, depending
5285on the language being compiled. For C (and C++) this means that
5286overflow when doing arithmetic with signed numbers is undefined, which
5287means that the compiler may assume that it will not happen. This
5288permits various optimizations. For example, the compiler will assume
5289that an expression like @code{i + 10 > i} will always be true for
5290signed @code{i}. This assumption is only valid if signed overflow is
5291undefined, as the expression is false if @code{i + 10} overflows when
5292using twos complement arithmetic. When this option is in effect any
5293attempt to determine whether an operation on signed numbers will
5294overflow must be written carefully to not actually involve overflow.
5295
5296See also the @option{-fwrapv} option. Using @option{-fwrapv} means
5297that signed overflow is fully defined: it wraps. When
5298@option{-fwrapv} is used, there is no difference between
5299@option{-fstrict-overflow} and @option{-fno-strict-overflow}. With
5300@option{-fwrapv} certain types of overflow are permitted. For
5301example, if the compiler gets an overflow when doing arithmetic on
5302constants, the overflowed value can still be used with
5303@option{-fwrapv}, but not otherwise.
5304
5305The @option{-fstrict-overflow} option is enabled at levels
5306@option{-O2}, @option{-O3}, @option{-Os}.
5307
5308@item -falign-functions
5309@itemx -falign-functions=@var{n}
5310@opindex falign-functions
5311Align the start of functions to the next power-of-two greater than
5312@var{n}, skipping up to @var{n} bytes. For instance,
5313@option{-falign-functions=32} aligns functions to the next 32-byte
5314boundary, but @option{-falign-functions=24} would align to the next
531532-byte boundary only if this can be done by skipping 23 bytes or less.
5316
5317@option{-fno-align-functions} and @option{-falign-functions=1} are
5318equivalent and mean that functions will not be aligned.
5319
5320Some assemblers only support this flag when @var{n} is a power of two;
5321in that case, it is rounded up.
5322
5323If @var{n} is not specified or is zero, use a machine-dependent default.
5324
5325Enabled at levels @option{-O2}, @option{-O3}.
5326
5327@item -falign-labels
5328@itemx -falign-labels=@var{n}
5329@opindex falign-labels
5330Align all branch targets to a power-of-two boundary, skipping up to
5331@var{n} bytes like @option{-falign-functions}. This option can easily
5332make code slower, because it must insert dummy operations for when the
5333branch target is reached in the usual flow of the code.
5334
5335@option{-fno-align-labels} and @option{-falign-labels=1} are
5336equivalent and mean that labels will not be aligned.
5337
5338If @option{-falign-loops} or @option{-falign-jumps} are applicable and
5339are greater than this value, then their values are used instead.
5340
5341If @var{n} is not specified or is zero, use a machine-dependent default
5342which is very likely to be @samp{1}, meaning no alignment.
5343
5344Enabled at levels @option{-O2}, @option{-O3}.
5345
5346@item -falign-loops
5347@itemx -falign-loops=@var{n}
5348@opindex falign-loops
5349Align loops to a power-of-two boundary, skipping up to @var{n} bytes
5350like @option{-falign-functions}. The hope is that the loop will be
5351executed many times, which will make up for any execution of the dummy
5352operations.
5353
5354@option{-fno-align-loops} and @option{-falign-loops=1} are
5355equivalent and mean that loops will not be aligned.
5356
5357If @var{n} is not specified or is zero, use a machine-dependent default.
5358
5359Enabled at levels @option{-O2}, @option{-O3}.
5360
5361@item -falign-jumps
5362@itemx -falign-jumps=@var{n}
5363@opindex falign-jumps
5364Align branch targets to a power-of-two boundary, for branch targets
5365where the targets can only be reached by jumping, skipping up to @var{n}
5366bytes like @option{-falign-functions}. In this case, no dummy operations
5367need be executed.
5368
5369@option{-fno-align-jumps} and @option{-falign-jumps=1} are
5370equivalent and mean that loops will not be aligned.
5371
5372If @var{n} is not specified or is zero, use a machine-dependent default.
5373
5374Enabled at levels @option{-O2}, @option{-O3}.
5375
5376@item -funit-at-a-time
5377@opindex funit-at-a-time
5378Parse the whole compilation unit before starting to produce code.
5379This allows some extra optimizations to take place but consumes
5380more memory (in general). There are some compatibility issues
5381with @emph{unit-at-a-time} mode:
5382@itemize @bullet
5383@item
5384enabling @emph{unit-at-a-time} mode may change the order
5385in which functions, variables, and top-level @code{asm} statements
5386are emitted, and will likely break code relying on some particular
5387ordering. The majority of such top-level @code{asm} statements,
5388though, can be replaced by @code{section} attributes. The
5389@option{fno-toplevel-reorder} option may be used to keep the ordering
5390used in the input file, at the cost of some optimizations.
5391
5392@item
5393@emph{unit-at-a-time} mode removes unreferenced static variables
5394and functions. This may result in undefined references
5395when an @code{asm} statement refers directly to variables or functions
5396that are otherwise unused. In that case either the variable/function
5397shall be listed as an operand of the @code{asm} statement operand or,
5398in the case of top-level @code{asm} statements the attribute @code{used}
5399shall be used on the declaration.
5400
5401@item
5402Static functions now can use non-standard passing conventions that
5403may break @code{asm} statements calling functions directly. Again,
5404attribute @code{used} will prevent this behavior.
5405@end itemize
5406
5407As a temporary workaround, @option{-fno-unit-at-a-time} can be used,
5408but this scheme may not be supported by future releases of GCC@.
5409
5410Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5411
5412@item -fno-toplevel-reorder
5413Do not reorder top-level functions, variables, and @code{asm}
5414statements. Output them in the same order that they appear in the
5415input file. When this option is used, unreferenced static variables
5416will not be removed. This option is intended to support existing code
5417which relies on a particular ordering. For new code, it is better to
5418use attributes.
5419
5420@item -fweb
5421@opindex fweb
5422Constructs webs as commonly used for register allocation purposes and assign
5423each web individual pseudo register. This allows the register allocation pass
5424to operate on pseudos directly, but also strengthens several other optimization
5425passes, such as CSE, loop optimizer and trivial dead code remover. It can,
5426however, make debugging impossible, since variables will no longer stay in a
5427``home register''.
5428
5429Enabled by default with @option{-funroll-loops}.
5430
5431@item -fwhole-program
5432@opindex fwhole-program
5433Assume that the current compilation unit represents whole program being
5434compiled. All public functions and variables with the exception of @code{main}
5435and those merged by attribute @code{externally_visible} become static functions
5436and in a affect gets more aggressively optimized by interprocedural optimizers.
5437While this option is equivalent to proper use of @code{static} keyword for
5438programs consisting of single file, in combination with option
5439@option{--combine} this flag can be used to compile most of smaller scale C
5440programs since the functions and variables become local for the whole combined
5441compilation unit, not for the single source file itself.
5442
5443
5444@item -fno-cprop-registers
5445@opindex fno-cprop-registers
5446After register allocation and post-register allocation instruction splitting,
5447we perform a copy-propagation pass to try to reduce scheduling dependencies
5448and occasionally eliminate the copy.
5449
5450Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5451
5452@item -fprofile-generate
5453@opindex fprofile-generate
5454
5455Enable options usually used for instrumenting application to produce
5456profile useful for later recompilation with profile feedback based
5457optimization. You must use @option{-fprofile-generate} both when
5458compiling and when linking your program.
5459
5460The following options are enabled: @code{-fprofile-arcs}, @code{-fprofile-values}, @code{-fvpt}.
5461
5462@item -fprofile-use
5463@opindex fprofile-use
5464Enable profile feedback directed optimizations, and optimizations
5465generally profitable only with profile feedback available.
5466
5467The following options are enabled: @code{-fbranch-probabilities}, @code{-fvpt},
5468@code{-funroll-loops}, @code{-fpeel-loops}, @code{-ftracer}
5469
5470@end table
5471
5472The following options control compiler behavior regarding floating
5473point arithmetic. These options trade off between speed and
5474correctness. All must be specifically enabled.
5475
5476@table @gcctabopt
5477@item -ffloat-store
5478@opindex ffloat-store
5479Do not store floating point variables in registers, and inhibit other
5480options that might change whether a floating point value is taken from a
5481register or memory.
5482
5483@cindex floating point precision
5484This option prevents undesirable excess precision on machines such as
5485the 68000 where the floating registers (of the 68881) keep more
5486precision than a @code{double} is supposed to have. Similarly for the
5487x86 architecture. For most programs, the excess precision does only
5488good, but a few programs rely on the precise definition of IEEE floating
5489point. Use @option{-ffloat-store} for such programs, after modifying
5490them to store all pertinent intermediate computations into variables.
5491
5492@item -ffast-math
5493@opindex ffast-math
5494Sets @option{-fno-math-errno}, @option{-funsafe-math-optimizations}, @*
5495@option{-fno-trapping-math}, @option{-ffinite-math-only},
5496@option{-fno-rounding-math}, @option{-fno-signaling-nans}
5497and @option{fcx-limited-range}.
5498
5499This option causes the preprocessor macro @code{__FAST_MATH__} to be defined.
5500
5501This option should never be turned on by any @option{-O} option since
5502it can result in incorrect output for programs which depend on
5503an exact implementation of IEEE or ISO rules/specifications for
5504math functions.
5505
5506@item -fno-math-errno
5507@opindex fno-math-errno
5508Do not set ERRNO after calling math functions that are executed
5509with a single instruction, e.g., sqrt. A program that relies on
5510IEEE exceptions for math error handling may want to use this flag
5511for speed while maintaining IEEE arithmetic compatibility.
5512
5513This option should never be turned on by any @option{-O} option since
5514it can result in incorrect output for programs which depend on
5515an exact implementation of IEEE or ISO rules/specifications for
5516math functions.
5517
5518The default is @option{-fmath-errno}.
5519
5520On Darwin and FreeBSD systems, the math library never sets @code{errno}.
5521There is therefore
5522no reason for the compiler to consider the possibility that it might,
5523and @option{-fno-math-errno} is the default.
5524
5525@item -funsafe-math-optimizations
5526@opindex funsafe-math-optimizations
5527Allow optimizations for floating-point arithmetic that (a) assume
5528that arguments and results are valid and (b) may violate IEEE or
5529ANSI standards. When used at link-time, it may include libraries
5530or startup files that change the default FPU control word or other
5531similar optimizations.
5532
5533This option should never be turned on by any @option{-O} option since
5534it can result in incorrect output for programs which depend on
5535an exact implementation of IEEE or ISO rules/specifications for
5536math functions.
5537
5538The default is @option{-fno-unsafe-math-optimizations}.
5539
5540@item -ffinite-math-only
5541@opindex ffinite-math-only
5542Allow optimizations for floating-point arithmetic that assume
5543that arguments and results are not NaNs or +-Infs.
5544
5545This option should never be turned on by any @option{-O} option since
5546it can result in incorrect output for programs which depend on
5547an exact implementation of IEEE or ISO rules/specifications.
5548
5549The default is @option{-fno-finite-math-only}.
5550
5551@item -fno-trapping-math
5552@opindex fno-trapping-math
5553Compile code assuming that floating-point operations cannot generate
5554user-visible traps. These traps include division by zero, overflow,
5555underflow, inexact result and invalid operation. This option implies
5556@option{-fno-signaling-nans}. Setting this option may allow faster
5557code if one relies on ``non-stop'' IEEE arithmetic, for example.
5558
5559This option should never be turned on by any @option{-O} option since
5560it can result in incorrect output for programs which depend on
5561an exact implementation of IEEE or ISO rules/specifications for
5562math functions.
5563
5564The default is @option{-ftrapping-math}.
5565
5566@item -frounding-math
5567@opindex frounding-math
5568Disable transformations and optimizations that assume default floating
5569point rounding behavior. This is round-to-zero for all floating point
5570to integer conversions, and round-to-nearest for all other arithmetic
5571truncations. This option should be specified for programs that change
5572the FP rounding mode dynamically, or that may be executed with a
5573non-default rounding mode. This option disables constant folding of
5574floating point expressions at compile-time (which may be affected by
5575rounding mode) and arithmetic transformations that are unsafe in the
5576presence of sign-dependent rounding modes.
5577
5578The default is @option{-fno-rounding-math}.
5579
5580This option is experimental and does not currently guarantee to
5581disable all GCC optimizations that are affected by rounding mode.
5582Future versions of GCC may provide finer control of this setting
5583using C99's @code{FENV_ACCESS} pragma. This command line option
5584will be used to specify the default state for @code{FENV_ACCESS}.
5585
5586@item -frtl-abstract-sequences
5587@opindex frtl-abstract-sequences
5588It is a size optimization method. This option is to find identical
5589sequences of code, which can be turned into pseudo-procedures and
5590then replace all occurrences with calls to the newly created
5591subroutine. It is kind of an opposite of @option{-finline-functions}.
5592This optimization runs at RTL level.
5593
5594@item -fsignaling-nans
5595@opindex fsignaling-nans
5596Compile code assuming that IEEE signaling NaNs may generate user-visible
5597traps during floating-point operations. Setting this option disables
5598optimizations that may change the number of exceptions visible with
5599signaling NaNs. This option implies @option{-ftrapping-math}.
5600
5601This option causes the preprocessor macro @code{__SUPPORT_SNAN__} to
5602be defined.
5603
5604The default is @option{-fno-signaling-nans}.
5605
5606This option is experimental and does not currently guarantee to
5607disable all GCC optimizations that affect signaling NaN behavior.
5608
5609@item -fsingle-precision-constant
5610@opindex fsingle-precision-constant
5611Treat floating point constant as single precision constant instead of
5612implicitly converting it to double precision constant.
5613
5614@item -fcx-limited-range
5615@itemx -fno-cx-limited-range
5616@opindex fcx-limited-range
5617@opindex fno-cx-limited-range
5618When enabled, this option states that a range reduction step is not
5619needed when performing complex division. The default is
5620@option{-fno-cx-limited-range}, but is enabled by @option{-ffast-math}.
5621
5622This option controls the default setting of the ISO C99
5623@code{CX_LIMITED_RANGE} pragma. Nevertheless, the option applies to
5624all languages.
5625
5626@end table
5627
5628The following options control optimizations that may improve
5629performance, but are not enabled by any @option{-O} options. This
5630section includes experimental options that may produce broken code.
5631
5632@table @gcctabopt
5633@item -fbranch-probabilities
5634@opindex fbranch-probabilities
5635After running a program compiled with @option{-fprofile-arcs}
5636(@pxref{Debugging Options,, Options for Debugging Your Program or
5637@command{gcc}}), you can compile it a second time using
5638@option{-fbranch-probabilities}, to improve optimizations based on
5639the number of times each branch was taken. When the program
5640compiled with @option{-fprofile-arcs} exits it saves arc execution
5641counts to a file called @file{@var{sourcename}.gcda} for each source
5642file The information in this data file is very dependent on the
5643structure of the generated code, so you must use the same source code
5644and the same optimization options for both compilations.
5645
5646With @option{-fbranch-probabilities}, GCC puts a
5647@samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}.
5648These can be used to improve optimization. Currently, they are only
5649used in one place: in @file{reorg.c}, instead of guessing which path a
5650branch is mostly to take, the @samp{REG_BR_PROB} values are used to
5651exactly determine which path is taken more often.
5652
5653@item -fprofile-values
5654@opindex fprofile-values
5655If combined with @option{-fprofile-arcs}, it adds code so that some
5656data about values of expressions in the program is gathered.
5657
5658With @option{-fbranch-probabilities}, it reads back the data gathered
5659from profiling values of expressions and adds @samp{REG_VALUE_PROFILE}
5660notes to instructions for their later usage in optimizations.
5661
5662Enabled with @option{-fprofile-generate} and @option{-fprofile-use}.
5663
5664@item -fvpt
5665@opindex fvpt
5666If combined with @option{-fprofile-arcs}, it instructs the compiler to add
5667a code to gather information about values of expressions.
5668
5669With @option{-fbranch-probabilities}, it reads back the data gathered
5670and actually performs the optimizations based on them.
5671Currently the optimizations include specialization of division operation
5672using the knowledge about the value of the denominator.
5673
5674@item -frename-registers
5675@opindex frename-registers
5676Attempt to avoid false dependencies in scheduled code by making use
5677of registers left over after register allocation. This optimization
5678will most benefit processors with lots of registers. Depending on the
5679debug information format adopted by the target, however, it can
5680make debugging impossible, since variables will no longer stay in
5681a ``home register''.
5682
5683Enabled by default with @option{-funroll-loops}.
5684
5685@item -ftracer
5686@opindex ftracer
5687Perform tail duplication to enlarge superblock size. This transformation
5688simplifies the control flow of the function allowing other optimizations to do
5689better job.
5690
5691Enabled with @option{-fprofile-use}.
5692
5693@item -funroll-loops
5694@opindex funroll-loops
5695Unroll loops whose number of iterations can be determined at compile time or
5696upon entry to the loop. @option{-funroll-loops} implies
5697@option{-frerun-cse-after-loop}, @option{-fweb} and @option{-frename-registers}.
5698It also turns on complete loop peeling (i.e.@: complete removal of loops with
5699small constant number of iterations). This option makes code larger, and may
5700or may not make it run faster.
5701
5702Enabled with @option{-fprofile-use}.
5703
5704@item -funroll-all-loops
5705@opindex funroll-all-loops
5706Unroll all loops, even if their number of iterations is uncertain when
5707the loop is entered. This usually makes programs run more slowly.
5708@option{-funroll-all-loops} implies the same options as
5709@option{-funroll-loops}.
5710
5711@item -fpeel-loops
5712@opindex fpeel-loops
5713Peels the loops for that there is enough information that they do not
5714roll much (from profile feedback). It also turns on complete loop peeling
5715(i.e.@: complete removal of loops with small constant number of iterations).
5716
5717Enabled with @option{-fprofile-use}.
5718
5719@item -fmove-loop-invariants
5720@opindex fmove-loop-invariants
5721Enables the loop invariant motion pass in the RTL loop optimizer. Enabled
5722at level @option{-O1}
5723
5724@item -funswitch-loops
5725@opindex funswitch-loops
5726Move branches with loop invariant conditions out of the loop, with duplicates
5727of the loop on both branches (modified according to result of the condition).
5728
5729@item -ffunction-sections
5730@itemx -fdata-sections
5731@opindex ffunction-sections
5732@opindex fdata-sections
5733Place each function or data item into its own section in the output
5734file if the target supports arbitrary sections. The name of the
5735function or the name of the data item determines the section's name
5736in the output file.
5737
5738Use these options on systems where the linker can perform optimizations
5739to improve locality of reference in the instruction space. Most systems
5740using the ELF object format and SPARC processors running Solaris 2 have
5741linkers with such optimizations. AIX may have these optimizations in
5742the future.
5743
5744Only use these options when there are significant benefits from doing
5745so. When you specify these options, the assembler and linker will
5746create larger object and executable files and will also be slower.
5747You will not be able to use @code{gprof} on all systems if you
5748specify this option and you may have problems with debugging if
5749you specify both this option and @option{-g}.
5750
5751@item -fbranch-target-load-optimize
5752@opindex fbranch-target-load-optimize
5753Perform branch target register load optimization before prologue / epilogue
5754threading.
5755The use of target registers can typically be exposed only during reload,
5756thus hoisting loads out of loops and doing inter-block scheduling needs
5757a separate optimization pass.
5758
5759@item -fbranch-target-load-optimize2
5760@opindex fbranch-target-load-optimize2
5761Perform branch target register load optimization after prologue / epilogue
5762threading.
5763
5764@item -fbtr-bb-exclusive
5765@opindex fbtr-bb-exclusive
5766When performing branch target register load optimization, don't reuse
5767branch target registers in within any basic block.
5768
5769@item -fstack-protector
5770Emit extra code to check for buffer overflows, such as stack smashing
5771attacks. This is done by adding a guard variable to functions with
5772vulnerable objects. This includes functions that call alloca, and
5773functions with buffers larger than 8 bytes. The guards are initialized
5774when a function is entered and then checked when the function exits.
5775If a guard check fails, an error message is printed and the program exits.
5776
5777@item -fstack-protector-all
5778Like @option{-fstack-protector} except that all functions are protected.
5779
5780@item -fsection-anchors
5781@opindex fsection-anchors
5782Try to reduce the number of symbolic address calculations by using
5783shared ``anchor'' symbols to address nearby objects. This transformation
5784can help to reduce the number of GOT entries and GOT accesses on some
5785targets.
5786
5787For example, the implementation of the following function @code{foo}:
5788
5789@smallexample
5790static int a, b, c;
5791int foo (void) @{ return a + b + c; @}
5792@end smallexample
5793
5794would usually calculate the addresses of all three variables, but if you
5795compile it with @option{-fsection-anchors}, it will access the variables
5796from a common anchor point instead. The effect is similar to the
5797following pseudocode (which isn't valid C):
5798
5799@smallexample
5800int foo (void)
5801@{
5802 register int *xr = &x;
5803 return xr[&a - &x] + xr[&b - &x] + xr[&c - &x];
5804@}
5805@end smallexample
5806
5807Not all targets support this option.
5808
5809@item --param @var{name}=@var{value}
5810@opindex param
5811In some places, GCC uses various constants to control the amount of
5812optimization that is done. For example, GCC will not inline functions
5813that contain more that a certain number of instructions. You can
5814control some of these constants on the command-line using the
5815@option{--param} option.
5816
5817The names of specific parameters, and the meaning of the values, are
5818tied to the internals of the compiler, and are subject to change
5819without notice in future releases.
5820
5821In each case, the @var{value} is an integer. The allowable choices for
5822@var{name} are given in the following table:
5823
5824@table @gcctabopt
5825@item salias-max-implicit-fields
5826The maximum number of fields in a variable without direct
5827structure accesses for which structure aliasing will consider trying
5828to track each field. The default is 5
5829
5830@item salias-max-array-elements
5831The maximum number of elements an array can have and its elements
5832still be tracked individually by structure aliasing. The default is 4
5833
5834@item sra-max-structure-size
5835The maximum structure size, in bytes, at which the scalar replacement
5836of aggregates (SRA) optimization will perform block copies. The
5837default value, 0, implies that GCC will select the most appropriate
5838size itself.
5839
5840@item sra-field-structure-ratio
5841The threshold ratio (as a percentage) between instantiated fields and
5842the complete structure size. We say that if the ratio of the number
5843of bytes in instantiated fields to the number of bytes in the complete
5844structure exceeds this parameter, then block copies are not used. The
5845default is 75.
5846
5847@item max-crossjump-edges
5848The maximum number of incoming edges to consider for crossjumping.
5849The algorithm used by @option{-fcrossjumping} is @math{O(N^2)} in
5850the number of edges incoming to each block. Increasing values mean
5851more aggressive optimization, making the compile time increase with
5852probably small improvement in executable size.
5853
5854@item min-crossjump-insns
5855The minimum number of instructions which must be matched at the end
5856of two blocks before crossjumping will be performed on them. This
5857value is ignored in the case where all instructions in the block being
5858crossjumped from are matched. The default value is 5.
5859
5860@item max-grow-copy-bb-insns
5861The maximum code size expansion factor when copying basic blocks
5862instead of jumping. The expansion is relative to a jump instruction.
5863The default value is 8.
5864
5865@item max-goto-duplication-insns
5866The maximum number of instructions to duplicate to a block that jumps
5867to a computed goto. To avoid @math{O(N^2)} behavior in a number of
5868passes, GCC factors computed gotos early in the compilation process,
5869and unfactors them as late as possible. Only computed jumps at the
5870end of a basic blocks with no more than max-goto-duplication-insns are
5871unfactored. The default value is 8.
5872
5873@item max-delay-slot-insn-search
5874The maximum number of instructions to consider when looking for an
5875instruction to fill a delay slot. If more than this arbitrary number of
5876instructions is searched, the time savings from filling the delay slot
5877will be minimal so stop searching. Increasing values mean more
5878aggressive optimization, making the compile time increase with probably
5879small improvement in executable run time.
5880
5881@item max-delay-slot-live-search
5882When trying to fill delay slots, the maximum number of instructions to
5883consider when searching for a block with valid live register
5884information. Increasing this arbitrarily chosen value means more
5885aggressive optimization, increasing the compile time. This parameter
5886should be removed when the delay slot code is rewritten to maintain the
5887control-flow graph.
5888
5889@item max-gcse-memory
5890The approximate maximum amount of memory that will be allocated in
5891order to perform the global common subexpression elimination
5892optimization. If more memory than specified is required, the
5893optimization will not be done.
5894
5895@item max-gcse-passes
5896The maximum number of passes of GCSE to run. The default is 1.
5897
5898@item max-pending-list-length
5899The maximum number of pending dependencies scheduling will allow
5900before flushing the current state and starting over. Large functions
5901with few branches or calls can create excessively large lists which
5902needlessly consume memory and resources.
5903
5904@item max-inline-insns-single
5905Several parameters control the tree inliner used in gcc.
5906This number sets the maximum number of instructions (counted in GCC's
5907internal representation) in a single function that the tree inliner
5908will consider for inlining. This only affects functions declared
5909inline and methods implemented in a class declaration (C++).
5910The default value is 450.
5911
5912@item max-inline-insns-auto
5913When you use @option{-finline-functions} (included in @option{-O3}),
5914a lot of functions that would otherwise not be considered for inlining
5915by the compiler will be investigated. To those functions, a different
5916(more restrictive) limit compared to functions declared inline can
5917be applied.
5918The default value is 90.
5919
5920@item large-function-insns
5921The limit specifying really large functions. For functions larger than this
5922limit after inlining inlining is constrained by
5923@option{--param large-function-growth}. This parameter is useful primarily
5924to avoid extreme compilation time caused by non-linear algorithms used by the
5925backend.
5926This parameter is ignored when @option{-funit-at-a-time} is not used.
5927The default value is 2700.
5928
5929@item large-function-growth
5930Specifies maximal growth of large function caused by inlining in percents.
5931This parameter is ignored when @option{-funit-at-a-time} is not used.
5932The default value is 100 which limits large function growth to 2.0 times
5933the original size.
5934
5935@item large-unit-insns
5936The limit specifying large translation unit. Growth caused by inlining of
5937units larger than this limit is limited by @option{--param inline-unit-growth}.
5938For small units this might be too tight (consider unit consisting of function A
5939that is inline and B that just calls A three time. If B is small relative to
5940A, the growth of unit is 300\% and yet such inlining is very sane. For very
5941large units consisting of small inlininable functions however the overall unit
5942growth limit is needed to avoid exponential explosion of code size. Thus for
5943smaller units, the size is increased to @option{--param large-unit-insns}
5944before applying @option{--param inline-unit-growth}. The default is 10000
5945
5946@item inline-unit-growth
5947Specifies maximal overall growth of the compilation unit caused by inlining.
5948This parameter is ignored when @option{-funit-at-a-time} is not used.
5949The default value is 50 which limits unit growth to 1.5 times the original
5950size.
5951
5952@item max-inline-insns-recursive
5953@itemx max-inline-insns-recursive-auto
5954Specifies maximum number of instructions out-of-line copy of self recursive inline
5955function can grow into by performing recursive inlining.
5956
5957For functions declared inline @option{--param max-inline-insns-recursive} is
5958taken into account. For function not declared inline, recursive inlining
5959happens only when @option{-finline-functions} (included in @option{-O3}) is
5960enabled and @option{--param max-inline-insns-recursive-auto} is used. The
5961default value is 450.
5962
5963@item max-inline-recursive-depth
5964@itemx max-inline-recursive-depth-auto
5965Specifies maximum recursion depth used by the recursive inlining.
5966
5967For functions declared inline @option{--param max-inline-recursive-depth} is
5968taken into account. For function not declared inline, recursive inlining
5969happens only when @option{-finline-functions} (included in @option{-O3}) is
5970enabled and @option{--param max-inline-recursive-depth-auto} is used. The
5971default value is 450.
5972
5973@item min-inline-recursive-probability
5974Recursive inlining is profitable only for function having deep recursion
5975in average and can hurt for function having little recursion depth by
5976increasing the prologue size or complexity of function body to other
5977optimizers.
5978
5979When profile feedback is available (see @option{-fprofile-generate}) the actual
5980recursion depth can be guessed from probability that function will recurse via
5981given call expression. This parameter limits inlining only to call expression
5982whose probability exceeds given threshold (in percents). The default value is
598310.
5984
5985@item inline-call-cost
5986Specify cost of call instruction relative to simple arithmetics operations
5987(having cost of 1). Increasing this cost disqualifies inlining of non-leaf
5988functions and at the same time increases size of leaf function that is believed to
5989reduce function size by being inlined. In effect it increases amount of
5990inlining for code having large abstraction penalty (many functions that just
5991pass the arguments to other functions) and decrease inlining for code with low
5992abstraction penalty. The default value is 16.
5993
5994@item max-unrolled-insns
5995The maximum number of instructions that a loop should have if that loop
5996is unrolled, and if the loop is unrolled, it determines how many times
5997the loop code is unrolled.
5998
5999@item max-average-unrolled-insns
6000The maximum number of instructions biased by probabilities of their execution
6001that a loop should have if that loop is unrolled, and if the loop is unrolled,
6002it determines how many times the loop code is unrolled.
6003
6004@item max-unroll-times
6005The maximum number of unrollings of a single loop.
6006
6007@item max-peeled-insns
6008The maximum number of instructions that a loop should have if that loop
6009is peeled, and if the loop is peeled, it determines how many times
6010the loop code is peeled.
6011
6012@item max-peel-times
6013The maximum number of peelings of a single loop.
6014
6015@item max-completely-peeled-insns
6016The maximum number of insns of a completely peeled loop.
6017
6018@item max-completely-peel-times
6019The maximum number of iterations of a loop to be suitable for complete peeling.
6020
6021@item max-unswitch-insns
6022The maximum number of insns of an unswitched loop.
6023
6024@item max-unswitch-level
6025The maximum number of branches unswitched in a single loop.
6026
6027@item lim-expensive
6028The minimum cost of an expensive expression in the loop invariant motion.
6029
6030@item iv-consider-all-candidates-bound
6031Bound on number of candidates for induction variables below that
6032all candidates are considered for each use in induction variable
6033optimizations. Only the most relevant candidates are considered
6034if there are more candidates, to avoid quadratic time complexity.
6035
6036@item iv-max-considered-uses
6037The induction variable optimizations give up on loops that contain more
6038induction variable uses.
6039
6040@item iv-always-prune-cand-set-bound
6041If number of candidates in the set is smaller than this value,
6042we always try to remove unnecessary ivs from the set during its
6043optimization when a new iv is added to the set.
6044
6045@item scev-max-expr-size
6046Bound on size of expressions used in the scalar evolutions analyzer.
6047Large expressions slow the analyzer.
6048
6049@item vect-max-version-checks
6050The maximum number of runtime checks that can be performed when doing
6051loop versioning in the vectorizer. See option ftree-vect-loop-version
6052for more information.
6053
6054@item max-iterations-to-track
6055
6056The maximum number of iterations of a loop the brute force algorithm
6057for analysis of # of iterations of the loop tries to evaluate.
6058
6059@item hot-bb-count-fraction
6060Select fraction of the maximal count of repetitions of basic block in program
6061given basic block needs to have to be considered hot.
6062
6063@item hot-bb-frequency-fraction
6064Select fraction of the maximal frequency of executions of basic block in
6065function given basic block needs to have to be considered hot
6066
6067@item max-predicted-iterations
6068The maximum number of loop iterations we predict statically. This is useful
6069in cases where function contain single loop with known bound and other loop
6070with unknown. We predict the known number of iterations correctly, while
6071the unknown number of iterations average to roughly 10. This means that the
6072loop without bounds would appear artificially cold relative to the other one.
6073
6074@item tracer-dynamic-coverage
6075@itemx tracer-dynamic-coverage-feedback
6076
6077This value is used to limit superblock formation once the given percentage of
6078executed instructions is covered. This limits unnecessary code size
6079expansion.
6080
6081The @option{tracer-dynamic-coverage-feedback} is used only when profile
6082feedback is available. The real profiles (as opposed to statically estimated
6083ones) are much less balanced allowing the threshold to be larger value.
6084
6085@item tracer-max-code-growth
6086Stop tail duplication once code growth has reached given percentage. This is
6087rather hokey argument, as most of the duplicates will be eliminated later in
6088cross jumping, so it may be set to much higher values than is the desired code
6089growth.
6090
6091@item tracer-min-branch-ratio
6092
6093Stop reverse growth when the reverse probability of best edge is less than this
6094threshold (in percent).
6095
6096@item tracer-min-branch-ratio
6097@itemx tracer-min-branch-ratio-feedback
6098
6099Stop forward growth if the best edge do have probability lower than this
6100threshold.
6101
6102Similarly to @option{tracer-dynamic-coverage} two values are present, one for
6103compilation for profile feedback and one for compilation without. The value
6104for compilation with profile feedback needs to be more conservative (higher) in
6105order to make tracer effective.
6106
6107@item max-cse-path-length
6108
6109Maximum number of basic blocks on path that cse considers. The default is 10.
6110
6111@item max-cse-insns
6112The maximum instructions CSE process before flushing. The default is 1000.
6113
6114@item global-var-threshold
6115
6116Counts the number of function calls (@var{n}) and the number of
6117call-clobbered variables (@var{v}). If @var{n}x@var{v} is larger than this limit, a
6118single artificial variable will be created to represent all the
6119call-clobbered variables at function call sites. This artificial
6120variable will then be made to alias every call-clobbered variable.
6121(done as @code{int * size_t} on the host machine; beware overflow).
6122
6123@item max-aliased-vops
6124
6125Maximum number of virtual operands allowed to represent aliases
6126before triggering the alias grouping heuristic. Alias grouping
6127reduces compile times and memory consumption needed for aliasing at
6128the expense of precision loss in alias information.
6129
6130@item ggc-min-expand
6131
6132GCC uses a garbage collector to manage its own memory allocation. This
6133parameter specifies the minimum percentage by which the garbage
6134collector's heap should be allowed to expand between collections.
6135Tuning this may improve compilation speed; it has no effect on code
6136generation.
6137
6138The default is 30% + 70% * (RAM/1GB) with an upper bound of 100% when
6139RAM >= 1GB@. If @code{getrlimit} is available, the notion of "RAM" is
6140the smallest of actual RAM and @code{RLIMIT_DATA} or @code{RLIMIT_AS}. If
6141GCC is not able to calculate RAM on a particular platform, the lower
6142bound of 30% is used. Setting this parameter and
6143@option{ggc-min-heapsize} to zero causes a full collection to occur at
6144every opportunity. This is extremely slow, but can be useful for
6145debugging.
6146
6147@item ggc-min-heapsize
6148
6149Minimum size of the garbage collector's heap before it begins bothering
6150to collect garbage. The first collection occurs after the heap expands
6151by @option{ggc-min-expand}% beyond @option{ggc-min-heapsize}. Again,
6152tuning this may improve compilation speed, and has no effect on code
6153generation.
6154
6155The default is the smaller of RAM/8, RLIMIT_RSS, or a limit which
6156tries to ensure that RLIMIT_DATA or RLIMIT_AS are not exceeded, but
6157with a lower bound of 4096 (four megabytes) and an upper bound of
6158131072 (128 megabytes). If GCC is not able to calculate RAM on a
6159particular platform, the lower bound is used. Setting this parameter
6160very large effectively disables garbage collection. Setting this
6161parameter and @option{ggc-min-expand} to zero causes a full collection
6162to occur at every opportunity.
6163
6164@item max-reload-search-insns
6165The maximum number of instruction reload should look backward for equivalent
6166register. Increasing values mean more aggressive optimization, making the
6167compile time increase with probably slightly better performance. The default
6168value is 100.
6169
6170@item max-cselib-memory-locations
6171The maximum number of memory locations cselib should take into account.
6172Increasing values mean more aggressive optimization, making the compile time
6173increase with probably slightly better performance. The default value is 500.
6174
6175@item max-flow-memory-locations
6176Similar as @option{max-cselib-memory-locations} but for dataflow liveness.
6177The default value is 100.
6178
6179@item reorder-blocks-duplicate
6180@itemx reorder-blocks-duplicate-feedback
6181
6182Used by basic block reordering pass to decide whether to use unconditional
6183branch or duplicate the code on its destination. Code is duplicated when its
6184estimated size is smaller than this value multiplied by the estimated size of
6185unconditional jump in the hot spots of the program.
6186
6187The @option{reorder-block-duplicate-feedback} is used only when profile
6188feedback is available and may be set to higher values than
6189@option{reorder-block-duplicate} since information about the hot spots is more
6190accurate.
6191
6192@item max-sched-ready-insns
6193The maximum number of instructions ready to be issued the scheduler should
6194consider at any given time during the first scheduling pass. Increasing
6195values mean more thorough searches, making the compilation time increase
6196with probably little benefit. The default value is 100.
6197
6198@item max-sched-region-blocks
6199The maximum number of blocks in a region to be considered for
6200interblock scheduling. The default value is 10.
6201
6202@item max-sched-region-insns
6203The maximum number of insns in a region to be considered for
6204interblock scheduling. The default value is 100.
6205
6206@item min-spec-prob
6207The minimum probability (in percents) of reaching a source block
6208for interblock speculative scheduling. The default value is 40.
6209
6210@item max-sched-extend-regions-iters
6211The maximum number of iterations through CFG to extend regions.
62120 - disable region extension,
6213N - do at most N iterations.
6214The default value is 0.
6215
6216@item max-sched-insn-conflict-delay
6217The maximum conflict delay for an insn to be considered for speculative motion.
6218The default value is 3.
6219
6220@item sched-spec-prob-cutoff
6221The minimal probability of speculation success (in percents), so that
6222speculative insn will be scheduled.
6223The default value is 40.
6224
6225@item max-last-value-rtl
6226
6227The maximum size measured as number of RTLs that can be recorded in an expression
6228in combiner for a pseudo register as last known value of that register. The default
6229is 10000.
6230
6231@item integer-share-limit
6232Small integer constants can use a shared data structure, reducing the
6233compiler's memory usage and increasing its speed. This sets the maximum
6234value of a shared integer constant's. The default value is 256.
6235
6236@item min-virtual-mappings
6237Specifies the minimum number of virtual mappings in the incremental
6238SSA updater that should be registered to trigger the virtual mappings
6239heuristic defined by virtual-mappings-ratio. The default value is
6240100.
6241
6242@item virtual-mappings-ratio
6243If the number of virtual mappings is virtual-mappings-ratio bigger
6244than the number of virtual symbols to be updated, then the incremental
6245SSA updater switches to a full update for those symbols. The default
6246ratio is 3.
6247
6248@item ssp-buffer-size
6249The minimum size of buffers (i.e. arrays) that will receive stack smashing
6250protection when @option{-fstack-protection} is used.
6251
6252@item max-jump-thread-duplication-stmts
6253Maximum number of statements allowed in a block that needs to be
6254duplicated when threading jumps.
6255
6256@item max-fields-for-field-sensitive
6257Maximum number of fields in a structure we will treat in
6258a field sensitive manner during pointer analysis.
6259
6260@end table
6261@end table
6262
6263@node Preprocessor Options
6264@section Options Controlling the Preprocessor
6265@cindex preprocessor options
6266@cindex options, preprocessor
6267
6268These options control the C preprocessor, which is run on each C source
6269file before actual compilation.
6270
6271If you use the @option{-E} option, nothing is done except preprocessing.
6272Some of these options make sense only together with @option{-E} because
6273they cause the preprocessor output to be unsuitable for actual
6274compilation.
6275
6276@table @gcctabopt
6277@opindex Wp
6278You can use @option{-Wp,@var{option}} to bypass the compiler driver
6279and pass @var{option} directly through to the preprocessor. If
6280@var{option} contains commas, it is split into multiple options at the
6281commas. However, many options are modified, translated or interpreted
6282by the compiler driver before being passed to the preprocessor, and
6283@option{-Wp} forcibly bypasses this phase. The preprocessor's direct
6284interface is undocumented and subject to change, so whenever possible
6285you should avoid using @option{-Wp} and let the driver handle the
6286options instead.
6287
6288@item -Xpreprocessor @var{option}
6289@opindex preprocessor
6290Pass @var{option} as an option to the preprocessor. You can use this to
6291supply system-specific preprocessor options which GCC does not know how to
6292recognize.
6293
6294If you want to pass an option that takes an argument, you must use
6295@option{-Xpreprocessor} twice, once for the option and once for the argument.
6296@end table
6297
6298@include cppopts.texi
6299
6300@node Assembler Options
6301@section Passing Options to the Assembler
6302
6303@c prevent bad page break with this line
6304You can pass options to the assembler.
6305
6306@table @gcctabopt
6307@item -Wa,@var{option}
6308@opindex Wa
6309Pass @var{option} as an option to the assembler. If @var{option}
6310contains commas, it is split into multiple options at the commas.
6311
6312@item -Xassembler @var{option}
6313@opindex Xassembler
6314Pass @var{option} as an option to the assembler. You can use this to
6315supply system-specific assembler options which GCC does not know how to
6316recognize.
6317
6318If you want to pass an option that takes an argument, you must use
6319@option{-Xassembler} twice, once for the option and once for the argument.
6320
6321@end table
6322
6323@node Link Options
6324@section Options for Linking
6325@cindex link options
6326@cindex options, linking
6327
6328These options come into play when the compiler links object files into
6329an executable output file. They are meaningless if the compiler is
6330not doing a link step.
6331
6332@table @gcctabopt
6333@cindex file names
6334@item @var{object-file-name}
6335A file name that does not end in a special recognized suffix is
6336considered to name an object file or library. (Object files are
6337distinguished from libraries by the linker according to the file
6338contents.) If linking is done, these object files are used as input
6339to the linker.
6340
6341@item -c
6342@itemx -S
6343@itemx -E
6344@opindex c
6345@opindex S
6346@opindex E
6347If any of these options is used, then the linker is not run, and
6348object file names should not be used as arguments. @xref{Overall
6349Options}.
6350
6351@cindex Libraries
6352@item -l@var{library}
6353@itemx -l @var{library}
6354@opindex l
6355Search the library named @var{library} when linking. (The second
6356alternative with the library as a separate argument is only for
6357POSIX compliance and is not recommended.)
6358
6359It makes a difference where in the command you write this option; the
6360linker searches and processes libraries and object files in the order they
6361are specified. Thus, @samp{foo.o -lz bar.o} searches library @samp{z}
6362after file @file{foo.o} but before @file{bar.o}. If @file{bar.o} refers
6363to functions in @samp{z}, those functions may not be loaded.
6364
6365The linker searches a standard list of directories for the library,
6366which is actually a file named @file{lib@var{library}.a}. The linker
6367then uses this file as if it had been specified precisely by name.
6368
6369The directories searched include several standard system directories
6370plus any that you specify with @option{-L}.
6371
6372Normally the files found this way are library files---archive files
6373whose members are object files. The linker handles an archive file by
6374scanning through it for members which define symbols that have so far
6375been referenced but not defined. But if the file that is found is an
6376ordinary object file, it is linked in the usual fashion. The only
6377difference between using an @option{-l} option and specifying a file name
6378is that @option{-l} surrounds @var{library} with @samp{lib} and @samp{.a}
6379and searches several directories.
6380
6381@item -nostartfiles
6382@opindex nostartfiles
6383Do not use the standard system startup files when linking.
6384The standard system libraries are used normally, unless @option{-nostdlib}
6385or @option{-nodefaultlibs} is used.
6386
6387@item -nodefaultlibs
6388@opindex nodefaultlibs
6389Do not use the standard system libraries when linking.
6390Only the libraries you specify will be passed to the linker.
6391The standard startup files are used normally, unless @option{-nostartfiles}
6392is used. The compiler may generate calls to @code{memcmp},
6393@code{memset}, @code{memcpy} and @code{memmove}.
6394These entries are usually resolved by entries in
6395libc. These entry points should be supplied through some other
6396mechanism when this option is specified.
6397
6398@item -nostdlib
6399@opindex nostdlib
6400Do not use the standard system startup files or libraries when linking.
6401No startup files and only the libraries you specify will be passed to
6402the linker. The compiler may generate calls to @code{memcmp}, @code{memset},
6403@code{memcpy} and @code{memmove}.
6404These entries are usually resolved by entries in
6405libc. These entry points should be supplied through some other
6406mechanism when this option is specified.
6407
6408@cindex @option{-lgcc}, use with @option{-nostdlib}
6409@cindex @option{-nostdlib} and unresolved references
6410@cindex unresolved references and @option{-nostdlib}
6411@cindex @option{-lgcc}, use with @option{-nodefaultlibs}
6412@cindex @option{-nodefaultlibs} and unresolved references
6413@cindex unresolved references and @option{-nodefaultlibs}
6414One of the standard libraries bypassed by @option{-nostdlib} and
6415@option{-nodefaultlibs} is @file{libgcc.a}, a library of internal subroutines
6416that GCC uses to overcome shortcomings of particular machines, or special
6417needs for some languages.
6418(@xref{Interface,,Interfacing to GCC Output,gccint,GNU Compiler
6419Collection (GCC) Internals},
6420for more discussion of @file{libgcc.a}.)
6421In most cases, you need @file{libgcc.a} even when you want to avoid
6422other standard libraries. In other words, when you specify @option{-nostdlib}
6423or @option{-nodefaultlibs} you should usually specify @option{-lgcc} as well.
6424This ensures that you have no unresolved references to internal GCC
6425library subroutines. (For example, @samp{__main}, used to ensure C++
6426constructors will be called; @pxref{Collect2,,@code{collect2}, gccint,
6427GNU Compiler Collection (GCC) Internals}.)
6428
6429@item -pie
6430@opindex pie
6431Produce a position independent executable on targets which support it.
6432For predictable results, you must also specify the same set of options
6433that were used to generate code (@option{-fpie}, @option{-fPIE},
6434or model suboptions) when you specify this option.
6435
6436@item -rdynamic
6437@opindex rdynamic
6438Pass the flag @option{-export-dynamic} to the ELF linker, on targets
6439that support it. This instructs the linker to add all symbols, not
6440only used ones, to the dynamic symbol table. This option is needed
6441for some uses of @code{dlopen} or to allow obtaining backtraces
6442from within a program.
6443
6444@item -s
6445@opindex s
6446Remove all symbol table and relocation information from the executable.
6447
6448@item -static
6449@opindex static
6450On systems that support dynamic linking, this prevents linking with the shared
6451libraries. On other systems, this option has no effect.
6452
6453@item -shared
6454@opindex shared
6455Produce a shared object which can then be linked with other objects to
6456form an executable. Not all systems support this option. For predictable
6457results, you must also specify the same set of options that were used to
6458generate code (@option{-fpic}, @option{-fPIC}, or model suboptions)
6459when you specify this option.@footnote{On some systems, @samp{gcc -shared}
6460needs to build supplementary stub code for constructors to work. On
6461multi-libbed systems, @samp{gcc -shared} must select the correct support
6462libraries to link against. Failing to supply the correct flags may lead
6463to subtle defects. Supplying them in cases where they are not necessary
6464is innocuous.}
6465
6466@item -shared-libgcc
6467@itemx -static-libgcc
6468@opindex shared-libgcc
6469@opindex static-libgcc
6470On systems that provide @file{libgcc} as a shared library, these options
6471force the use of either the shared or static version respectively.
6472If no shared version of @file{libgcc} was built when the compiler was
6473configured, these options have no effect.
6474
6475There are several situations in which an application should use the
6476shared @file{libgcc} instead of the static version. The most common
6477of these is when the application wishes to throw and catch exceptions
6478across different shared libraries. In that case, each of the libraries
6479as well as the application itself should use the shared @file{libgcc}.
6480
6481Therefore, the G++ and GCJ drivers automatically add
6482@option{-shared-libgcc} whenever you build a shared library or a main
6483executable, because C++ and Java programs typically use exceptions, so
6484this is the right thing to do.
6485
6486If, instead, you use the GCC driver to create shared libraries, you may
6487find that they will not always be linked with the shared @file{libgcc}.
6488If GCC finds, at its configuration time, that you have a non-GNU linker
6489or a GNU linker that does not support option @option{--eh-frame-hdr},
6490it will link the shared version of @file{libgcc} into shared libraries
6491by default. Otherwise, it will take advantage of the linker and optimize
6492away the linking with the shared version of @file{libgcc}, linking with
6493the static version of libgcc by default. This allows exceptions to
6494propagate through such shared libraries, without incurring relocation
6495costs at library load time.
6496
6497However, if a library or main executable is supposed to throw or catch
6498exceptions, you must link it using the G++ or GCJ driver, as appropriate
6499for the languages used in the program, or using the option
6500@option{-shared-libgcc}, such that it is linked with the shared
6501@file{libgcc}.
6502
6503@item -symbolic
6504@opindex symbolic
6505Bind references to global symbols when building a shared object. Warn
6506about any unresolved references (unless overridden by the link editor
6507option @samp{-Xlinker -z -Xlinker defs}). Only a few systems support
6508this option.
6509
6510@item -Xlinker @var{option}
6511@opindex Xlinker
6512Pass @var{option} as an option to the linker. You can use this to
6513supply system-specific linker options which GCC does not know how to
6514recognize.
6515
6516If you want to pass an option that takes an argument, you must use
6517@option{-Xlinker} twice, once for the option and once for the argument.
6518For example, to pass @option{-assert definitions}, you must write
6519@samp{-Xlinker -assert -Xlinker definitions}. It does not work to write
6520@option{-Xlinker "-assert definitions"}, because this passes the entire
6521string as a single argument, which is not what the linker expects.
6522
6523@item -Wl,@var{option}
6524@opindex Wl
6525Pass @var{option} as an option to the linker. If @var{option} contains
6526commas, it is split into multiple options at the commas.
6527
6528@item -u @var{symbol}
6529@opindex u
6530Pretend the symbol @var{symbol} is undefined, to force linking of
6531library modules to define it. You can use @option{-u} multiple times with
6532different symbols to force loading of additional library modules.
6533@end table
6534
6535@node Directory Options
6536@section Options for Directory Search
6537@cindex directory options
6538@cindex options, directory search
6539@cindex search path
6540
6541These options specify directories to search for header files, for
6542libraries and for parts of the compiler:
6543
6544@table @gcctabopt
6545@item -I@var{dir}
6546@opindex I
6547Add the directory @var{dir} to the head of the list of directories to be
6548searched for header files. This can be used to override a system header
6549file, substituting your own version, since these directories are
6550searched before the system header file directories. However, you should
6551not use this option to add directories that contain vendor-supplied
6552system header files (use @option{-isystem} for that). If you use more than
6553one @option{-I} option, the directories are scanned in left-to-right
6554order; the standard system directories come after.
6555
6556If a standard system include directory, or a directory specified with
6557@option{-isystem}, is also specified with @option{-I}, the @option{-I}
6558option will be ignored. The directory will still be searched but as a
6559system directory at its normal position in the system include chain.
6560This is to ensure that GCC's procedure to fix buggy system headers and
6561the ordering for the include_next directive are not inadvertently changed.
6562If you really need to change the search order for system directories,
6563use the @option{-nostdinc} and/or @option{-isystem} options.
6564
6565@item -iquote@var{dir}
6566@opindex iquote
6567Add the directory @var{dir} to the head of the list of directories to
6568be searched for header files only for the case of @samp{#include
6569"@var{file}"}; they are not searched for @samp{#include <@var{file}>},
6570otherwise just like @option{-I}.
6571
6572@item -L@var{dir}
6573@opindex L
6574Add directory @var{dir} to the list of directories to be searched
6575for @option{-l}.
6576
6577@item -B@var{prefix}
6578@opindex B
6579This option specifies where to find the executables, libraries,
6580include files, and data files of the compiler itself.
6581
6582The compiler driver program runs one or more of the subprograms
6583@file{cpp}, @file{cc1}, @file{as} and @file{ld}. It tries
6584@var{prefix} as a prefix for each program it tries to run, both with and
6585without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}).
6586
6587For each subprogram to be run, the compiler driver first tries the
6588@option{-B} prefix, if any. If that name is not found, or if @option{-B}
6589was not specified, the driver tries two standard prefixes, which are
6590@file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc/}. If neither of
6591those results in a file name that is found, the unmodified program
6592name is searched for using the directories specified in your
6593@env{PATH} environment variable.
6594
6595The compiler will check to see if the path provided by the @option{-B}
6596refers to a directory, and if necessary it will add a directory
6597separator character at the end of the path.
6598
6599@option{-B} prefixes that effectively specify directory names also apply
6600to libraries in the linker, because the compiler translates these
6601options into @option{-L} options for the linker. They also apply to
6602includes files in the preprocessor, because the compiler translates these
6603options into @option{-isystem} options for the preprocessor. In this case,
6604the compiler appends @samp{include} to the prefix.
6605
6606The run-time support file @file{libgcc.a} can also be searched for using
6607the @option{-B} prefix, if needed. If it is not found there, the two
6608standard prefixes above are tried, and that is all. The file is left
6609out of the link if it is not found by those means.
6610
6611Another way to specify a prefix much like the @option{-B} prefix is to use
6612the environment variable @env{GCC_EXEC_PREFIX}. @xref{Environment
6613Variables}.
6614
6615As a special kludge, if the path provided by @option{-B} is
6616@file{[dir/]stage@var{N}/}, where @var{N} is a number in the range 0 to
66179, then it will be replaced by @file{[dir/]include}. This is to help
6618with boot-strapping the compiler.
6619
6620@item -specs=@var{file}
6621@opindex specs
6622Process @var{file} after the compiler reads in the standard @file{specs}
6623file, in order to override the defaults that the @file{gcc} driver
6624program uses when determining what switches to pass to @file{cc1},
6625@file{cc1plus}, @file{as}, @file{ld}, etc. More than one
6626@option{-specs=@var{file}} can be specified on the command line, and they
6627are processed in order, from left to right.
6628
6629@item --sysroot=@var{dir}
6630@opindex sysroot
6631Use @var{dir} as the logical root directory for headers and libraries.
6632For example, if the compiler would normally search for headers in
6633@file{/usr/include} and libraries in @file{/usr/lib}, it will instead
6634search @file{@var{dir}/usr/include} and @file{@var{dir}/usr/lib}.
6635
6636If you use both this option and the @option{-isysroot} option, then
6637the @option{--sysroot} option will apply to libraries, but the
6638@option{-isysroot} option will apply to header files.
6639
6640The GNU linker (beginning with version 2.16) has the necessary support
6641for this option. If your linker does not support this option, the
6642header file aspect of @option{--sysroot} will still work, but the
6643library aspect will not.
6644
6645@item -I-
6646@opindex I-
6647This option has been deprecated. Please use @option{-iquote} instead for
6648@option{-I} directories before the @option{-I-} and remove the @option{-I-}.
6649Any directories you specify with @option{-I} options before the @option{-I-}
6650option are searched only for the case of @samp{#include "@var{file}"};
6651they are not searched for @samp{#include <@var{file}>}.
6652
6653If additional directories are specified with @option{-I} options after
6654the @option{-I-}, these directories are searched for all @samp{#include}
6655directives. (Ordinarily @emph{all} @option{-I} directories are used
6656this way.)
6657
6658In addition, the @option{-I-} option inhibits the use of the current
6659directory (where the current input file came from) as the first search
6660directory for @samp{#include "@var{file}"}. There is no way to
6661override this effect of @option{-I-}. With @option{-I.} you can specify
6662searching the directory which was current when the compiler was
6663invoked. That is not exactly the same as what the preprocessor does
6664by default, but it is often satisfactory.
6665
6666@option{-I-} does not inhibit the use of the standard system directories
6667for header files. Thus, @option{-I-} and @option{-nostdinc} are
6668independent.
6669@end table
6670
6671@c man end
6672
6673@node Spec Files
6674@section Specifying subprocesses and the switches to pass to them
6675@cindex Spec Files
6676
6677@command{gcc} is a driver program. It performs its job by invoking a
6678sequence of other programs to do the work of compiling, assembling and
6679linking. GCC interprets its command-line parameters and uses these to
6680deduce which programs it should invoke, and which command-line options
6681it ought to place on their command lines. This behavior is controlled
6682by @dfn{spec strings}. In most cases there is one spec string for each
6683program that GCC can invoke, but a few programs have multiple spec
6684strings to control their behavior. The spec strings built into GCC can
6685be overridden by using the @option{-specs=} command-line switch to specify
6686a spec file.
6687
6688@dfn{Spec files} are plaintext files that are used to construct spec
6689strings. They consist of a sequence of directives separated by blank
6690lines. The type of directive is determined by the first non-whitespace
6691character on the line and it can be one of the following:
6692
6693@table @code
6694@item %@var{command}
6695Issues a @var{command} to the spec file processor. The commands that can
6696appear here are:
6697
6698@table @code
6699@item %include <@var{file}>
6700@cindex %include
6701Search for @var{file} and insert its text at the current point in the
6702specs file.
6703
6704@item %include_noerr <@var{file}>
6705@cindex %include_noerr
6706Just like @samp{%include}, but do not generate an error message if the include
6707file cannot be found.
6708
6709@item %rename @var{old_name} @var{new_name}
6710@cindex %rename
6711Rename the spec string @var{old_name} to @var{new_name}.
6712
6713@end table
6714
6715@item *[@var{spec_name}]:
6716This tells the compiler to create, override or delete the named spec
6717string. All lines after this directive up to the next directive or
6718blank line are considered to be the text for the spec string. If this
6719results in an empty string then the spec will be deleted. (Or, if the
6720spec did not exist, then nothing will happened.) Otherwise, if the spec
6721does not currently exist a new spec will be created. If the spec does
6722exist then its contents will be overridden by the text of this
6723directive, unless the first character of that text is the @samp{+}
6724character, in which case the text will be appended to the spec.
6725
6726@item [@var{suffix}]:
6727Creates a new @samp{[@var{suffix}] spec} pair. All lines after this directive
6728and up to the next directive or blank line are considered to make up the
6729spec string for the indicated suffix. When the compiler encounters an
6730input file with the named suffix, it will processes the spec string in
6731order to work out how to compile that file. For example:
6732
6733@smallexample
6734.ZZ:
6735z-compile -input %i
6736@end smallexample
6737
6738This says that any input file whose name ends in @samp{.ZZ} should be
6739passed to the program @samp{z-compile}, which should be invoked with the
6740command-line switch @option{-input} and with the result of performing the
6741@samp{%i} substitution. (See below.)
6742
6743As an alternative to providing a spec string, the text that follows a
6744suffix directive can be one of the following:
6745
6746@table @code
6747@item @@@var{language}
6748This says that the suffix is an alias for a known @var{language}. This is
6749similar to using the @option{-x} command-line switch to GCC to specify a
6750language explicitly. For example:
6751
6752@smallexample
6753.ZZ:
6754@@c++
6755@end smallexample
6756
6757Says that .ZZ files are, in fact, C++ source files.
6758
6759@item #@var{name}
6760This causes an error messages saying:
6761
6762@smallexample
6763@var{name} compiler not installed on this system.
6764@end smallexample
6765@end table
6766
6767GCC already has an extensive list of suffixes built into it.
6768This directive will add an entry to the end of the list of suffixes, but
6769since the list is searched from the end backwards, it is effectively
6770possible to override earlier entries using this technique.
6771
6772@end table
6773
6774GCC has the following spec strings built into it. Spec files can
6775override these strings or create their own. Note that individual
6776targets can also add their own spec strings to this list.
6777
6778@smallexample
6779asm Options to pass to the assembler
6780asm_final Options to pass to the assembler post-processor
6781cpp Options to pass to the C preprocessor
6782cc1 Options to pass to the C compiler
6783cc1plus Options to pass to the C++ compiler
6784endfile Object files to include at the end of the link
6785link Options to pass to the linker
6786lib Libraries to include on the command line to the linker
6787libgcc Decides which GCC support library to pass to the linker
6788linker Sets the name of the linker
6789predefines Defines to be passed to the C preprocessor
6790signed_char Defines to pass to CPP to say whether @code{char} is signed
6791 by default
6792startfile Object files to include at the start of the link
6793@end smallexample
6794
6795Here is a small example of a spec file:
6796
6797@smallexample
6798%rename lib old_lib
6799
6800*lib:
6801--start-group -lgcc -lc -leval1 --end-group %(old_lib)
6802@end smallexample
6803
6804This example renames the spec called @samp{lib} to @samp{old_lib} and
6805then overrides the previous definition of @samp{lib} with a new one.
6806The new definition adds in some extra command-line options before
6807including the text of the old definition.
6808
6809@dfn{Spec strings} are a list of command-line options to be passed to their
6810corresponding program. In addition, the spec strings can contain
6811@samp{%}-prefixed sequences to substitute variable text or to
6812conditionally insert text into the command line. Using these constructs
6813it is possible to generate quite complex command lines.
6814
6815Here is a table of all defined @samp{%}-sequences for spec
6816strings. Note that spaces are not generated automatically around the
6817results of expanding these sequences. Therefore you can concatenate them
6818together or combine them with constant text in a single argument.
6819
6820@table @code
6821@item %%
6822Substitute one @samp{%} into the program name or argument.
6823
6824@item %i
6825Substitute the name of the input file being processed.
6826
6827@item %b
6828Substitute the basename of the input file being processed.
6829This is the substring up to (and not including) the last period
6830and not including the directory.
6831
6832@item %B
6833This is the same as @samp{%b}, but include the file suffix (text after
6834the last period).
6835
6836@item %d
6837Marks the argument containing or following the @samp{%d} as a
6838temporary file name, so that that file will be deleted if GCC exits
6839successfully. Unlike @samp{%g}, this contributes no text to the
6840argument.
6841
6842@item %g@var{suffix}
6843Substitute a file name that has suffix @var{suffix} and is chosen
6844once per compilation, and mark the argument in the same way as
6845@samp{%d}. To reduce exposure to denial-of-service attacks, the file
6846name is now chosen in a way that is hard to predict even when previously
6847chosen file names are known. For example, @samp{%g.s @dots{} %g.o @dots{} %g.s}
6848might turn into @samp{ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s}. @var{suffix} matches
6849the regexp @samp{[.A-Za-z]*} or the special string @samp{%O}, which is
6850treated exactly as if @samp{%O} had been preprocessed. Previously, @samp{%g}
6851was simply substituted with a file name chosen once per compilation,
6852without regard to any appended suffix (which was therefore treated
6853just like ordinary text), making such attacks more likely to succeed.
6854
6855@item %u@var{suffix}
6856Like @samp{%g}, but generates a new temporary file name even if
6857@samp{%u@var{suffix}} was already seen.
6858
6859@item %U@var{suffix}
6860Substitutes the last file name generated with @samp{%u@var{suffix}}, generating a
6861new one if there is no such last file name. In the absence of any
6862@samp{%u@var{suffix}}, this is just like @samp{%g@var{suffix}}, except they don't share
6863the same suffix @emph{space}, so @samp{%g.s @dots{} %U.s @dots{} %g.s @dots{} %U.s}
6864would involve the generation of two distinct file names, one
6865for each @samp{%g.s} and another for each @samp{%U.s}. Previously, @samp{%U} was
6866simply substituted with a file name chosen for the previous @samp{%u},
6867without regard to any appended suffix.
6868
6869@item %j@var{suffix}
6870Substitutes the name of the @code{HOST_BIT_BUCKET}, if any, and if it is
6871writable, and if save-temps is off; otherwise, substitute the name
6872of a temporary file, just like @samp{%u}. This temporary file is not
6873meant for communication between processes, but rather as a junk
6874disposal mechanism.
6875
6876@item %|@var{suffix}
6877@itemx %m@var{suffix}
6878Like @samp{%g}, except if @option{-pipe} is in effect. In that case
6879@samp{%|} substitutes a single dash and @samp{%m} substitutes nothing at
6880all. These are the two most common ways to instruct a program that it
6881should read from standard input or write to standard output. If you
6882need something more elaborate you can use an @samp{%@{pipe:@code{X}@}}
6883construct: see for example @file{f/lang-specs.h}.
6884
6885@item %.@var{SUFFIX}
6886Substitutes @var{.SUFFIX} for the suffixes of a matched switch's args
6887when it is subsequently output with @samp{%*}. @var{SUFFIX} is
6888terminated by the next space or %.
6889
6890@item %w
6891Marks the argument containing or following the @samp{%w} as the
6892designated output file of this compilation. This puts the argument
6893into the sequence of arguments that @samp{%o} will substitute later.
6894
6895@item %o
6896Substitutes the names of all the output files, with spaces
6897automatically placed around them. You should write spaces
6898around the @samp{%o} as well or the results are undefined.
6899@samp{%o} is for use in the specs for running the linker.
6900Input files whose names have no recognized suffix are not compiled
6901at all, but they are included among the output files, so they will
6902be linked.
6903
6904@item %O
6905Substitutes the suffix for object files. Note that this is
6906handled specially when it immediately follows @samp{%g, %u, or %U},
6907because of the need for those to form complete file names. The
6908handling is such that @samp{%O} is treated exactly as if it had already
6909been substituted, except that @samp{%g, %u, and %U} do not currently
6910support additional @var{suffix} characters following @samp{%O} as they would
6911following, for example, @samp{.o}.
6912
6913@item %p
6914Substitutes the standard macro predefinitions for the
6915current target machine. Use this when running @code{cpp}.
6916
6917@item %P
6918Like @samp{%p}, but puts @samp{__} before and after the name of each
6919predefined macro, except for macros that start with @samp{__} or with
6920@samp{_@var{L}}, where @var{L} is an uppercase letter. This is for ISO
6921C@.
6922
6923@item %I
6924Substitute any of @option{-iprefix} (made from @env{GCC_EXEC_PREFIX}),
6925@option{-isysroot} (made from @env{TARGET_SYSTEM_ROOT}),
6926@option{-isystem} (made from @env{COMPILER_PATH} and @option{-B} options)
6927and @option{-imultilib} as necessary.
6928
6929@item %s
6930Current argument is the name of a library or startup file of some sort.
6931Search for that file in a standard list of directories and substitute
6932the full name found.
6933
6934@item %e@var{str}
6935Print @var{str} as an error message. @var{str} is terminated by a newline.
6936Use this when inconsistent options are detected.
6937
6938@item %(@var{name})
6939Substitute the contents of spec string @var{name} at this point.
6940
6941@item %[@var{name}]
6942Like @samp{%(@dots{})} but put @samp{__} around @option{-D} arguments.
6943
6944@item %x@{@var{option}@}
6945Accumulate an option for @samp{%X}.
6946
6947@item %X
6948Output the accumulated linker options specified by @option{-Wl} or a @samp{%x}
6949spec string.
6950
6951@item %Y
6952Output the accumulated assembler options specified by @option{-Wa}.
6953
6954@item %Z
6955Output the accumulated preprocessor options specified by @option{-Wp}.
6956
6957@item %a
6958Process the @code{asm} spec. This is used to compute the
6959switches to be passed to the assembler.
6960
6961@item %A
6962Process the @code{asm_final} spec. This is a spec string for
6963passing switches to an assembler post-processor, if such a program is
6964needed.
6965
6966@item %l
6967Process the @code{link} spec. This is the spec for computing the
6968command line passed to the linker. Typically it will make use of the
6969@samp{%L %G %S %D and %E} sequences.
6970
6971@item %D
6972Dump out a @option{-L} option for each directory that GCC believes might
6973contain startup files. If the target supports multilibs then the
6974current multilib directory will be prepended to each of these paths.
6975
6976@item %L
6977Process the @code{lib} spec. This is a spec string for deciding which
6978libraries should be included on the command line to the linker.
6979
6980@item %G
6981Process the @code{libgcc} spec. This is a spec string for deciding
6982which GCC support library should be included on the command line to the linker.
6983
6984@item %S
6985Process the @code{startfile} spec. This is a spec for deciding which
6986object files should be the first ones passed to the linker. Typically
6987this might be a file named @file{crt0.o}.
6988
6989@item %E
6990Process the @code{endfile} spec. This is a spec string that specifies
6991the last object files that will be passed to the linker.
6992
6993@item %C
6994Process the @code{cpp} spec. This is used to construct the arguments
6995to be passed to the C preprocessor.
6996
6997@item %1
6998Process the @code{cc1} spec. This is used to construct the options to be
6999passed to the actual C compiler (@samp{cc1}).
7000
7001@item %2
7002Process the @code{cc1plus} spec. This is used to construct the options to be
7003passed to the actual C++ compiler (@samp{cc1plus}).
7004
7005@item %*
7006Substitute the variable part of a matched option. See below.
7007Note that each comma in the substituted string is replaced by
7008a single space.
7009
7010@item %<@code{S}
7011Remove all occurrences of @code{-S} from the command line. Note---this
7012command is position dependent. @samp{%} commands in the spec string
7013before this one will see @code{-S}, @samp{%} commands in the spec string
7014after this one will not.
7015
7016@item %:@var{function}(@var{args})
7017Call the named function @var{function}, passing it @var{args}.
7018@var{args} is first processed as a nested spec string, then split
7019into an argument vector in the usual fashion. The function returns
7020a string which is processed as if it had appeared literally as part
7021of the current spec.
7022
7023The following built-in spec functions are provided:
7024
7025@table @code
7026@item @code{if-exists}
7027The @code{if-exists} spec function takes one argument, an absolute
7028pathname to a file. If the file exists, @code{if-exists} returns the
7029pathname. Here is a small example of its usage:
7030
7031@smallexample
7032*startfile:
7033crt0%O%s %:if-exists(crti%O%s) crtbegin%O%s
7034@end smallexample
7035
7036@item @code{if-exists-else}
7037The @code{if-exists-else} spec function is similar to the @code{if-exists}
7038spec function, except that it takes two arguments. The first argument is
7039an absolute pathname to a file. If the file exists, @code{if-exists-else}
7040returns the pathname. If it does not exist, it returns the second argument.
7041This way, @code{if-exists-else} can be used to select one file or another,
7042based on the existence of the first. Here is a small example of its usage:
7043
7044@smallexample
7045*startfile:
7046crt0%O%s %:if-exists(crti%O%s) \
7047%:if-exists-else(crtbeginT%O%s crtbegin%O%s)
7048@end smallexample
7049
7050@item @code{replace-outfile}
7051The @code{replace-outfile} spec function takes two arguments. It looks for the
7052first argument in the outfiles array and replaces it with the second argument. Here
7053is a small example of its usage:
7054
7055@smallexample
7056%@{static|static-libgcc|static-libstdc++:%:replace-outfile(-lstdc++ \
7057libstdc++.a%s)@}
7058
7059@end smallexample
7060
7061@end table
7062
7063@item %@{@code{S}@}
7064Substitutes the @code{-S} switch, if that switch was given to GCC@.
7065If that switch was not specified, this substitutes nothing. Note that
7066the leading dash is omitted when specifying this option, and it is
7067automatically inserted if the substitution is performed. Thus the spec
7068string @samp{%@{foo@}} would match the command-line option @option{-foo}
7069and would output the command line option @option{-foo}.
7070
7071@item %W@{@code{S}@}
7072Like %@{@code{S}@} but mark last argument supplied within as a file to be
7073deleted on failure.
7074
7075@item %@{@code{S}*@}
7076Substitutes all the switches specified to GCC whose names start
7077with @code{-S}, but which also take an argument. This is used for
7078switches like @option{-o}, @option{-D}, @option{-I}, etc.
7079GCC considers @option{-o foo} as being
7080one switch whose names starts with @samp{o}. %@{o*@} would substitute this
7081text, including the space. Thus two arguments would be generated.
7082
7083@item %@{@code{S}*&@code{T}*@}
7084Like %@{@code{S}*@}, but preserve order of @code{S} and @code{T} options
7085(the order of @code{S} and @code{T} in the spec is not significant).
7086There can be any number of ampersand-separated variables; for each the
7087wild card is optional. Useful for CPP as @samp{%@{D*&U*&A*@}}.
7088
7089@item %@{@code{S}:@code{X}@}
7090Substitutes @code{X}, if the @samp{-S} switch was given to GCC@.
7091
7092@item %@{!@code{S}:@code{X}@}
7093Substitutes @code{X}, if the @samp{-S} switch was @emph{not} given to GCC@.
7094
7095@item %@{@code{S}*:@code{X}@}
7096Substitutes @code{X} if one or more switches whose names start with
7097@code{-S} are specified to GCC@. Normally @code{X} is substituted only
7098once, no matter how many such switches appeared. However, if @code{%*}
7099appears somewhere in @code{X}, then @code{X} will be substituted once
7100for each matching switch, with the @code{%*} replaced by the part of
7101that switch that matched the @code{*}.
7102
7103@item %@{.@code{S}:@code{X}@}
7104Substitutes @code{X}, if processing a file with suffix @code{S}.
7105
7106@item %@{!.@code{S}:@code{X}@}
7107Substitutes @code{X}, if @emph{not} processing a file with suffix @code{S}.
7108
7109@item %@{@code{S}|@code{P}:@code{X}@}
7110Substitutes @code{X} if either @code{-S} or @code{-P} was given to GCC@.
7111This may be combined with @samp{!}, @samp{.}, and @code{*} sequences as well,
7112although they have a stronger binding than the @samp{|}. If @code{%*}
7113appears in @code{X}, all of the alternatives must be starred, and only
7114the first matching alternative is substituted.
7115
7116For example, a spec string like this:
7117
7118@smallexample
7119%@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@}
7120@end smallexample
7121
7122will output the following command-line options from the following input
7123command-line options:
7124
7125@smallexample
7126fred.c -foo -baz
7127jim.d -bar -boggle
7128-d fred.c -foo -baz -boggle
7129-d jim.d -bar -baz -boggle
7130@end smallexample
7131
7132@item %@{S:X; T:Y; :D@}
7133
7134If @code{S} was given to GCC, substitutes @code{X}; else if @code{T} was
7135given to GCC, substitutes @code{Y}; else substitutes @code{D}. There can
7136be as many clauses as you need. This may be combined with @code{.},
7137@code{!}, @code{|}, and @code{*} as needed.
7138
7139
7140@end table
7141
7142The conditional text @code{X} in a %@{@code{S}:@code{X}@} or similar
7143construct may contain other nested @samp{%} constructs or spaces, or
7144even newlines. They are processed as usual, as described above.
7145Trailing white space in @code{X} is ignored. White space may also
7146appear anywhere on the left side of the colon in these constructs,
7147except between @code{.} or @code{*} and the corresponding word.
7148
7149The @option{-O}, @option{-f}, @option{-m}, and @option{-W} switches are
7150handled specifically in these constructs. If another value of
7151@option{-O} or the negated form of a @option{-f}, @option{-m}, or
7152@option{-W} switch is found later in the command line, the earlier
7153switch value is ignored, except with @{@code{S}*@} where @code{S} is
7154just one letter, which passes all matching options.
7155
7156The character @samp{|} at the beginning of the predicate text is used to
7157indicate that a command should be piped to the following command, but
7158only if @option{-pipe} is specified.
7159
7160It is built into GCC which switches take arguments and which do not.
7161(You might think it would be useful to generalize this to allow each
7162compiler's spec to say which switches take arguments. But this cannot
7163be done in a consistent fashion. GCC cannot even decide which input
7164files have been specified without knowing which switches take arguments,
7165and it must know which input files to compile in order to tell which
7166compilers to run).
7167
7168GCC also knows implicitly that arguments starting in @option{-l} are to be
7169treated as compiler output files, and passed to the linker in their
7170proper position among the other output files.
7171
7172@c man begin OPTIONS
7173
7174@node Target Options
7175@section Specifying Target Machine and Compiler Version
7176@cindex target options
7177@cindex cross compiling
7178@cindex specifying machine version
7179@cindex specifying compiler version and target machine
7180@cindex compiler version, specifying
7181@cindex target machine, specifying
7182
7183The usual way to run GCC is to run the executable called @file{gcc}, or
7184@file{<machine>-gcc} when cross-compiling, or
7185@file{<machine>-gcc-<version>} to run a version other than the one that
7186was installed last. Sometimes this is inconvenient, so GCC provides
7187options that will switch to another cross-compiler or version.
7188
7189@table @gcctabopt
7190@item -b @var{machine}
7191@opindex b
7192The argument @var{machine} specifies the target machine for compilation.
7193
7194The value to use for @var{machine} is the same as was specified as the
7195machine type when configuring GCC as a cross-compiler. For
7196example, if a cross-compiler was configured with @samp{configure
7197arm-elf}, meaning to compile for an arm processor with elf binaries,
7198then you would specify @option{-b arm-elf} to run that cross compiler.
7199Because there are other options beginning with @option{-b}, the
7200configuration must contain a hyphen.
7201
7202@item -V @var{version}
7203@opindex V
7204The argument @var{version} specifies which version of GCC to run.
7205This is useful when multiple versions are installed. For example,
7206@var{version} might be @samp{4.0}, meaning to run GCC version 4.0.
7207@end table
7208
7209The @option{-V} and @option{-b} options work by running the
7210@file{<machine>-gcc-<version>} executable, so there's no real reason to
7211use them if you can just run that directly.
7212
7213@node Submodel Options
7214@section Hardware Models and Configurations
7215@cindex submodel options
7216@cindex specifying hardware config
7217@cindex hardware models and configurations, specifying
7218@cindex machine dependent options
7219
7220Earlier we discussed the standard option @option{-b} which chooses among
7221different installed compilers for completely different target
7222machines, such as VAX vs.@: 68000 vs.@: 80386.
7223
7224In addition, each of these target machine types can have its own
7225special options, starting with @samp{-m}, to choose among various
7226hardware models or configurations---for example, 68010 vs 68020,
7227floating coprocessor or none. A single installed version of the
7228compiler can compile for any model or configuration, according to the
7229options specified.
7230
7231Some configurations of the compiler also support additional special
7232options, usually for compatibility with other compilers on the same
7233platform.
7234
7235@c This list is ordered alphanumerically by subsection name.
7236@c It should be the same order and spelling as these options are listed
7237@c in Machine Dependent Options
7238
7239@menu
7240* ARC Options::
7241* ARM Options::
7242* AVR Options::
7243* Blackfin Options::
7244* CRIS Options::
7245* CRX Options::
7246* Darwin Options::
7247* DEC Alpha Options::
7248* DEC Alpha/VMS Options::
7249* FRV Options::
7250* GNU/Linux Options::
7251* H8/300 Options::
7252* HPPA Options::
7253* i386 and x86-64 Options::
7254* IA-64 Options::
7255* M32C Options::
7256* M32R/D Options::
7257* M680x0 Options::
7258* M68hc1x Options::
7259* MCore Options::
7260* MIPS Options::
7261* MMIX Options::
7262* MN10300 Options::
7263* MT Options::
7264* PDP-11 Options::
7265* PowerPC Options::
7266* RS/6000 and PowerPC Options::
7267* S/390 and zSeries Options::
7268* Score Options::
7269* SH Options::
7270* SPARC Options::
7271* System V Options::
7272* TMS320C3x/C4x Options::
7273* V850 Options::
7274* VAX Options::
7275* x86-64 Options::
7276* Xstormy16 Options::
7277* Xtensa Options::
7278* zSeries Options::
7279@end menu
7280
7281@node ARC Options
7282@subsection ARC Options
7283@cindex ARC Options
7284
7285These options are defined for ARC implementations:
7286
7287@table @gcctabopt
7288@item -EL
7289@opindex EL
7290Compile code for little endian mode. This is the default.
7291
7292@item -EB
7293@opindex EB
7294Compile code for big endian mode.
7295
7296@item -mmangle-cpu
7297@opindex mmangle-cpu
7298Prepend the name of the cpu to all public symbol names.
7299In multiple-processor systems, there are many ARC variants with different
7300instruction and register set characteristics. This flag prevents code
7301compiled for one cpu to be linked with code compiled for another.
7302No facility exists for handling variants that are ``almost identical''.
7303This is an all or nothing option.
7304
7305@item -mcpu=@var{cpu}
7306@opindex mcpu
7307Compile code for ARC variant @var{cpu}.
7308Which variants are supported depend on the configuration.
7309All variants support @option{-mcpu=base}, this is the default.
7310
7311@item -mtext=@var{text-section}
7312@itemx -mdata=@var{data-section}
7313@itemx -mrodata=@var{readonly-data-section}
7314@opindex mtext
7315@opindex mdata
7316@opindex mrodata
7317Put functions, data, and readonly data in @var{text-section},
7318@var{data-section}, and @var{readonly-data-section} respectively
7319by default. This can be overridden with the @code{section} attribute.
7320@xref{Variable Attributes}.
7321
7322@end table
7323
7324@node ARM Options
7325@subsection ARM Options
7326@cindex ARM options
7327
7328These @samp{-m} options are defined for Advanced RISC Machines (ARM)
7329architectures:
7330
7331@table @gcctabopt
7332@item -mabi=@var{name}
7333@opindex mabi
7334Generate code for the specified ABI@. Permissible values are: @samp{apcs-gnu},
7335@samp{atpcs}, @samp{aapcs}, @samp{aapcs-linux} and @samp{iwmmxt}.
7336
7337@item -mapcs-frame
7338@opindex mapcs-frame
7339Generate a stack frame that is compliant with the ARM Procedure Call
7340Standard for all functions, even if this is not strictly necessary for
7341correct execution of the code. Specifying @option{-fomit-frame-pointer}
7342with this option will cause the stack frames not to be generated for
7343leaf functions. The default is @option{-mno-apcs-frame}.
7344
7345@item -mapcs
7346@opindex mapcs
7347This is a synonym for @option{-mapcs-frame}.
7348
7349@ignore
7350@c not currently implemented
7351@item -mapcs-stack-check
7352@opindex mapcs-stack-check
7353Generate code to check the amount of stack space available upon entry to
7354every function (that actually uses some stack space). If there is
7355insufficient space available then either the function
7356@samp{__rt_stkovf_split_small} or @samp{__rt_stkovf_split_big} will be
7357called, depending upon the amount of stack space required. The run time
7358system is required to provide these functions. The default is
7359@option{-mno-apcs-stack-check}, since this produces smaller code.
7360
7361@c not currently implemented
7362@item -mapcs-float
7363@opindex mapcs-float
7364Pass floating point arguments using the float point registers. This is
7365one of the variants of the APCS@. This option is recommended if the
7366target hardware has a floating point unit or if a lot of floating point
7367arithmetic is going to be performed by the code. The default is
7368@option{-mno-apcs-float}, since integer only code is slightly increased in
7369size if @option{-mapcs-float} is used.
7370
7371@c not currently implemented
7372@item -mapcs-reentrant
7373@opindex mapcs-reentrant
7374Generate reentrant, position independent code. The default is
7375@option{-mno-apcs-reentrant}.
7376@end ignore
7377
7378@item -mthumb-interwork
7379@opindex mthumb-interwork
7380Generate code which supports calling between the ARM and Thumb
7381instruction sets. Without this option the two instruction sets cannot
7382be reliably used inside one program. The default is
7383@option{-mno-thumb-interwork}, since slightly larger code is generated
7384when @option{-mthumb-interwork} is specified.
7385
7386@item -mno-sched-prolog
7387@opindex mno-sched-prolog
7388Prevent the reordering of instructions in the function prolog, or the
7389merging of those instruction with the instructions in the function's
7390body. This means that all functions will start with a recognizable set
7391of instructions (or in fact one of a choice from a small set of
7392different function prologues), and this information can be used to
7393locate the start if functions inside an executable piece of code. The
7394default is @option{-msched-prolog}.
7395
7396@item -mhard-float
7397@opindex mhard-float
7398Generate output containing floating point instructions. This is the
7399default.
7400
7401@item -msoft-float
7402@opindex msoft-float
7403Generate output containing library calls for floating point.
7404@strong{Warning:} the requisite libraries are not available for all ARM
7405targets. Normally the facilities of the machine's usual C compiler are
7406used, but this cannot be done directly in cross-compilation. You must make
7407your own arrangements to provide suitable library functions for
7408cross-compilation.
7409
7410@option{-msoft-float} changes the calling convention in the output file;
7411therefore, it is only useful if you compile @emph{all} of a program with
7412this option. In particular, you need to compile @file{libgcc.a}, the
7413library that comes with GCC, with @option{-msoft-float} in order for
7414this to work.
7415
7416@item -mfloat-abi=@var{name}
7417@opindex mfloat-abi
7418Specifies which ABI to use for floating point values. Permissible values
7419are: @samp{soft}, @samp{softfp} and @samp{hard}.
7420
7421@samp{soft} and @samp{hard} are equivalent to @option{-msoft-float}
7422and @option{-mhard-float} respectively. @samp{softfp} allows the generation
7423of floating point instructions, but still uses the soft-float calling
7424conventions.
7425
7426@item -mlittle-endian
7427@opindex mlittle-endian
7428Generate code for a processor running in little-endian mode. This is
7429the default for all standard configurations.
7430
7431@item -mbig-endian
7432@opindex mbig-endian
7433Generate code for a processor running in big-endian mode; the default is
7434to compile code for a little-endian processor.
7435
7436@item -mwords-little-endian
7437@opindex mwords-little-endian
7438This option only applies when generating code for big-endian processors.
7439Generate code for a little-endian word order but a big-endian byte
7440order. That is, a byte order of the form @samp{32107654}. Note: this
7441option should only be used if you require compatibility with code for
7442big-endian ARM processors generated by versions of the compiler prior to
74432.8.
7444
7445@item -mcpu=@var{name}
7446@opindex mcpu
7447This specifies the name of the target ARM processor. GCC uses this name
7448to determine what kind of instructions it can emit when generating
7449assembly code. Permissible names are: @samp{arm2}, @samp{arm250},
7450@samp{arm3}, @samp{arm6}, @samp{arm60}, @samp{arm600}, @samp{arm610},
7451@samp{arm620}, @samp{arm7}, @samp{arm7m}, @samp{arm7d}, @samp{arm7dm},
7452@samp{arm7di}, @samp{arm7dmi}, @samp{arm70}, @samp{arm700},
7453@samp{arm700i}, @samp{arm710}, @samp{arm710c}, @samp{arm7100},
7454@samp{arm7500}, @samp{arm7500fe}, @samp{arm7tdmi}, @samp{arm7tdmi-s},
7455@samp{arm8}, @samp{strongarm}, @samp{strongarm110}, @samp{strongarm1100},
7456@samp{arm8}, @samp{arm810}, @samp{arm9}, @samp{arm9e}, @samp{arm920},
7457@samp{arm920t}, @samp{arm922t}, @samp{arm946e-s}, @samp{arm966e-s},
7458@samp{arm968e-s}, @samp{arm926ej-s}, @samp{arm940t}, @samp{arm9tdmi},
7459@samp{arm10tdmi}, @samp{arm1020t}, @samp{arm1026ej-s},
7460@samp{arm10e}, @samp{arm1020e}, @samp{arm1022e},
7461@samp{arm1136j-s}, @samp{arm1136jf-s}, @samp{mpcore}, @samp{mpcorenovfp},
7462@samp{arm1176jz-s}, @samp{arm1176jzf-s}, @samp{xscale}, @samp{iwmmxt},
7463@samp{ep9312}.
7464
7465@itemx -mtune=@var{name}
7466@opindex mtune
7467This option is very similar to the @option{-mcpu=} option, except that
7468instead of specifying the actual target processor type, and hence
7469restricting which instructions can be used, it specifies that GCC should
7470tune the performance of the code as if the target were of the type
7471specified in this option, but still choosing the instructions that it
7472will generate based on the cpu specified by a @option{-mcpu=} option.
7473For some ARM implementations better performance can be obtained by using
7474this option.
7475
7476@item -march=@var{name}
7477@opindex march
7478This specifies the name of the target ARM architecture. GCC uses this
7479name to determine what kind of instructions it can emit when generating
7480assembly code. This option can be used in conjunction with or instead
7481of the @option{-mcpu=} option. Permissible names are: @samp{armv2},
7482@samp{armv2a}, @samp{armv3}, @samp{armv3m}, @samp{armv4}, @samp{armv4t},
7483@samp{armv5}, @samp{armv5t}, @samp{armv5te}, @samp{armv6}, @samp{armv6j},
7484@samp{iwmmxt}, @samp{ep9312}.
7485
7486@item -mfpu=@var{name}
7487@itemx -mfpe=@var{number}
7488@itemx -mfp=@var{number}
7489@opindex mfpu
7490@opindex mfpe
7491@opindex mfp
7492This specifies what floating point hardware (or hardware emulation) is
7493available on the target. Permissible names are: @samp{fpa}, @samp{fpe2},
7494@samp{fpe3}, @samp{maverick}, @samp{vfp}. @option{-mfp} and @option{-mfpe}
7495are synonyms for @option{-mfpu}=@samp{fpe}@var{number}, for compatibility
7496with older versions of GCC@.
7497
7498If @option{-msoft-float} is specified this specifies the format of
7499floating point values.
7500
7501@item -mstructure-size-boundary=@var{n}
7502@opindex mstructure-size-boundary
7503The size of all structures and unions will be rounded up to a multiple
7504of the number of bits set by this option. Permissible values are 8, 32
7505and 64. The default value varies for different toolchains. For the COFF
7506targeted toolchain the default value is 8. A value of 64 is only allowed
7507if the underlying ABI supports it.
7508
7509Specifying the larger number can produce faster, more efficient code, but
7510can also increase the size of the program. Different values are potentially
7511incompatible. Code compiled with one value cannot necessarily expect to
7512work with code or libraries compiled with another value, if they exchange
7513information using structures or unions.
7514
7515@item -mabort-on-noreturn
7516@opindex mabort-on-noreturn
7517Generate a call to the function @code{abort} at the end of a
7518@code{noreturn} function. It will be executed if the function tries to
7519return.
7520
7521@item -mlong-calls
7522@itemx -mno-long-calls
7523@opindex mlong-calls
7524@opindex mno-long-calls
7525Tells the compiler to perform function calls by first loading the
7526address of the function into a register and then performing a subroutine
7527call on this register. This switch is needed if the target function
7528will lie outside of the 64 megabyte addressing range of the offset based
7529version of subroutine call instruction.
7530
7531Even if this switch is enabled, not all function calls will be turned
7532into long calls. The heuristic is that static functions, functions
7533which have the @samp{short-call} attribute, functions that are inside
7534the scope of a @samp{#pragma no_long_calls} directive and functions whose
7535definitions have already been compiled within the current compilation
7536unit, will not be turned into long calls. The exception to this rule is
7537that weak function definitions, functions with the @samp{long-call}
7538attribute or the @samp{section} attribute, and functions that are within
7539the scope of a @samp{#pragma long_calls} directive, will always be
7540turned into long calls.
7541
7542This feature is not enabled by default. Specifying
7543@option{-mno-long-calls} will restore the default behavior, as will
7544placing the function calls within the scope of a @samp{#pragma
7545long_calls_off} directive. Note these switches have no effect on how
7546the compiler generates code to handle function calls via function
7547pointers.
7548
7549@item -mnop-fun-dllimport
7550@opindex mnop-fun-dllimport
7551Disable support for the @code{dllimport} attribute.
7552
7553@item -msingle-pic-base
7554@opindex msingle-pic-base
7555Treat the register used for PIC addressing as read-only, rather than
7556loading it in the prologue for each function. The run-time system is
7557responsible for initializing this register with an appropriate value
7558before execution begins.
7559
7560@item -mpic-register=@var{reg}
7561@opindex mpic-register
7562Specify the register to be used for PIC addressing. The default is R10
7563unless stack-checking is enabled, when R9 is used.
7564
7565@item -mcirrus-fix-invalid-insns
7566@opindex mcirrus-fix-invalid-insns
7567@opindex mno-cirrus-fix-invalid-insns
7568Insert NOPs into the instruction stream to in order to work around
7569problems with invalid Maverick instruction combinations. This option
7570is only valid if the @option{-mcpu=ep9312} option has been used to
7571enable generation of instructions for the Cirrus Maverick floating
7572point co-processor. This option is not enabled by default, since the
7573problem is only present in older Maverick implementations. The default
7574can be re-enabled by use of the @option{-mno-cirrus-fix-invalid-insns}
7575switch.
7576
7577@item -mpoke-function-name
7578@opindex mpoke-function-name
7579Write the name of each function into the text section, directly
7580preceding the function prologue. The generated code is similar to this:
7581
7582@smallexample
7583 t0
7584 .ascii "arm_poke_function_name", 0
7585 .align
7586 t1
7587 .word 0xff000000 + (t1 - t0)
7588 arm_poke_function_name
7589 mov ip, sp
7590 stmfd sp!, @{fp, ip, lr, pc@}
7591 sub fp, ip, #4
7592@end smallexample
7593
7594When performing a stack backtrace, code can inspect the value of
7595@code{pc} stored at @code{fp + 0}. If the trace function then looks at
7596location @code{pc - 12} and the top 8 bits are set, then we know that
7597there is a function name embedded immediately preceding this location
7598and has length @code{((pc[-3]) & 0xff000000)}.
7599
7600@item -mthumb
7601@opindex mthumb
7602Generate code for the 16-bit Thumb instruction set. The default is to
7603use the 32-bit ARM instruction set.
7604
7605@item -mtpcs-frame
7606@opindex mtpcs-frame
7607Generate a stack frame that is compliant with the Thumb Procedure Call
7608Standard for all non-leaf functions. (A leaf function is one that does
7609not call any other functions.) The default is @option{-mno-tpcs-frame}.
7610
7611@item -mtpcs-leaf-frame
7612@opindex mtpcs-leaf-frame
7613Generate a stack frame that is compliant with the Thumb Procedure Call
7614Standard for all leaf functions. (A leaf function is one that does
7615not call any other functions.) The default is @option{-mno-apcs-leaf-frame}.
7616
7617@item -mcallee-super-interworking
7618@opindex mcallee-super-interworking
7619Gives all externally visible functions in the file being compiled an ARM
7620instruction set header which switches to Thumb mode before executing the
7621rest of the function. This allows these functions to be called from
7622non-interworking code.
7623
7624@item -mcaller-super-interworking
7625@opindex mcaller-super-interworking
7626Allows calls via function pointers (including virtual functions) to
7627execute correctly regardless of whether the target code has been
7628compiled for interworking or not. There is a small overhead in the cost
7629of executing a function pointer if this option is enabled.
7630
7631@item -mtp=@var{name}
7632@opindex mtp
7633Specify the access model for the thread local storage pointer. The valid
7634models are @option{soft}, which generates calls to @code{__aeabi_read_tp},
7635@option{cp15}, which fetches the thread pointer from @code{cp15} directly
7636(supported in the arm6k architecture), and @option{auto}, which uses the
7637best available method for the selected processor. The default setting is
7638@option{auto}.
7639
7640@end table
7641
7642@node AVR Options
7643@subsection AVR Options
7644@cindex AVR Options
7645
7646These options are defined for AVR implementations:
7647
7648@table @gcctabopt
7649@item -mmcu=@var{mcu}
7650@opindex mmcu
7651Specify ATMEL AVR instruction set or MCU type.
7652
7653Instruction set avr1 is for the minimal AVR core, not supported by the C
7654compiler, only for assembler programs (MCU types: at90s1200, attiny10,
7655attiny11, attiny12, attiny15, attiny28).
7656
7657Instruction set avr2 (default) is for the classic AVR core with up to
76588K program memory space (MCU types: at90s2313, at90s2323, attiny22,
7659at90s2333, at90s2343, at90s4414, at90s4433, at90s4434, at90s8515,
7660at90c8534, at90s8535).
7661
7662Instruction set avr3 is for the classic AVR core with up to 128K program
7663memory space (MCU types: atmega103, atmega603, at43usb320, at76c711).
7664
7665Instruction set avr4 is for the enhanced AVR core with up to 8K program
7666memory space (MCU types: atmega8, atmega83, atmega85).
7667
7668Instruction set avr5 is for the enhanced AVR core with up to 128K program
7669memory space (MCU types: atmega16, atmega161, atmega163, atmega32, atmega323,
7670atmega64, atmega128, at43usb355, at94k).
7671
7672@item -msize
7673@opindex msize
7674Output instruction sizes to the asm file.
7675
7676@item -minit-stack=@var{N}
7677@opindex minit-stack
7678Specify the initial stack address, which may be a symbol or numeric value,
7679@samp{__stack} is the default.
7680
7681@item -mno-interrupts
7682@opindex mno-interrupts
7683Generated code is not compatible with hardware interrupts.
7684Code size will be smaller.
7685
7686@item -mcall-prologues
7687@opindex mcall-prologues
7688Functions prologues/epilogues expanded as call to appropriate
7689subroutines. Code size will be smaller.
7690
7691@item -mno-tablejump
7692@opindex mno-tablejump
7693Do not generate tablejump insns which sometimes increase code size.
7694
7695@item -mtiny-stack
7696@opindex mtiny-stack
7697Change only the low 8 bits of the stack pointer.
7698
7699@item -mint8
7700@opindex mint8
7701Assume int to be 8 bit integer. This affects the sizes of all types: A
7702char will be 1 byte, an int will be 1 byte, an long will be 2 bytes
7703and long long will be 4 bytes. Please note that this option does not
7704comply to the C standards, but it will provide you with smaller code
7705size.
7706@end table
7707
7708@node Blackfin Options
7709@subsection Blackfin Options
7710@cindex Blackfin Options
7711
7712@table @gcctabopt
7713@item -momit-leaf-frame-pointer
7714@opindex momit-leaf-frame-pointer
7715Don't keep the frame pointer in a register for leaf functions. This
7716avoids the instructions to save, set up and restore frame pointers and
7717makes an extra register available in leaf functions. The option
7718@option{-fomit-frame-pointer} removes the frame pointer for all functions
7719which might make debugging harder.
7720
7721@item -mspecld-anomaly
7722@opindex mspecld-anomaly
7723When enabled, the compiler will ensure that the generated code does not
7724contain speculative loads after jump instructions. This option is enabled
7725by default.
7726
7727@item -mno-specld-anomaly
7728@opindex mno-specld-anomaly
7729Don't generate extra code to prevent speculative loads from occurring.
7730
7731@item -mcsync-anomaly
7732@opindex mcsync-anomaly
7733When enabled, the compiler will ensure that the generated code does not
7734contain CSYNC or SSYNC instructions too soon after conditional branches.
7735This option is enabled by default.
7736
7737@item -mno-csync-anomaly
7738@opindex mno-csync-anomaly
7739Don't generate extra code to prevent CSYNC or SSYNC instructions from
7740occurring too soon after a conditional branch.
7741
7742@item -mlow-64k
7743@opindex mlow-64k
7744When enabled, the compiler is free to take advantage of the knowledge that
7745the entire program fits into the low 64k of memory.
7746
7747@item -mno-low-64k
7748@opindex mno-low-64k
7749Assume that the program is arbitrarily large. This is the default.
7750
7751@item -mid-shared-library
7752@opindex mid-shared-library
7753Generate code that supports shared libraries via the library ID method.
7754This allows for execute in place and shared libraries in an environment
7755without virtual memory management. This option implies @option{-fPIC}.
7756
7757@item -mno-id-shared-library
7758@opindex mno-id-shared-library
7759Generate code that doesn't assume ID based shared libraries are being used.
7760This is the default.
7761
7762@item -mshared-library-id=n
7763@opindex mshared-library-id
7764Specified the identification number of the ID based shared library being
7765compiled. Specifying a value of 0 will generate more compact code, specifying
7766other values will force the allocation of that number to the current
7767library but is no more space or time efficient than omitting this option.
7768
7769@item -mlong-calls
7770@itemx -mno-long-calls
7771@opindex mlong-calls
7772@opindex mno-long-calls
7773Tells the compiler to perform function calls by first loading the
7774address of the function into a register and then performing a subroutine
7775call on this register. This switch is needed if the target function
7776will lie outside of the 24 bit addressing range of the offset based
7777version of subroutine call instruction.
7778
7779This feature is not enabled by default. Specifying
7780@option{-mno-long-calls} will restore the default behavior. Note these
7781switches have no effect on how the compiler generates code to handle
7782function calls via function pointers.
7783@end table
7784
7785@node CRIS Options
7786@subsection CRIS Options
7787@cindex CRIS Options
7788
7789These options are defined specifically for the CRIS ports.
7790
7791@table @gcctabopt
7792@item -march=@var{architecture-type}
7793@itemx -mcpu=@var{architecture-type}
7794@opindex march
7795@opindex mcpu
7796Generate code for the specified architecture. The choices for
7797@var{architecture-type} are @samp{v3}, @samp{v8} and @samp{v10} for
7798respectively ETRAX@w{ }4, ETRAX@w{ }100, and ETRAX@w{ }100@w{ }LX@.
7799Default is @samp{v0} except for cris-axis-linux-gnu, where the default is
7800@samp{v10}.
7801
7802@item -mtune=@var{architecture-type}
7803@opindex mtune
7804Tune to @var{architecture-type} everything applicable about the generated
7805code, except for the ABI and the set of available instructions. The
7806choices for @var{architecture-type} are the same as for
7807@option{-march=@var{architecture-type}}.
7808
7809@item -mmax-stack-frame=@var{n}
7810@opindex mmax-stack-frame
7811Warn when the stack frame of a function exceeds @var{n} bytes.
7812
7813@item -melinux-stacksize=@var{n}
7814@opindex melinux-stacksize
7815Only available with the @samp{cris-axis-aout} target. Arranges for
7816indications in the program to the kernel loader that the stack of the
7817program should be set to @var{n} bytes.
7818
7819@item -metrax4
7820@itemx -metrax100
7821@opindex metrax4
7822@opindex metrax100
7823The options @option{-metrax4} and @option{-metrax100} are synonyms for
7824@option{-march=v3} and @option{-march=v8} respectively.
7825
7826@item -mmul-bug-workaround
7827@itemx -mno-mul-bug-workaround
7828@opindex mmul-bug-workaround
7829@opindex mno-mul-bug-workaround
7830Work around a bug in the @code{muls} and @code{mulu} instructions for CPU
7831models where it applies. This option is active by default.
7832
7833@item -mpdebug
7834@opindex mpdebug
7835Enable CRIS-specific verbose debug-related information in the assembly
7836code. This option also has the effect to turn off the @samp{#NO_APP}
7837formatted-code indicator to the assembler at the beginning of the
7838assembly file.
7839
7840@item -mcc-init
7841@opindex mcc-init
7842Do not use condition-code results from previous instruction; always emit
7843compare and test instructions before use of condition codes.
7844
7845@item -mno-side-effects
7846@opindex mno-side-effects
7847Do not emit instructions with side-effects in addressing modes other than
7848post-increment.
7849
7850@item -mstack-align
7851@itemx -mno-stack-align
7852@itemx -mdata-align
7853@itemx -mno-data-align
7854@itemx -mconst-align
7855@itemx -mno-const-align
7856@opindex mstack-align
7857@opindex mno-stack-align
7858@opindex mdata-align
7859@opindex mno-data-align
7860@opindex mconst-align
7861@opindex mno-const-align
7862These options (no-options) arranges (eliminate arrangements) for the
7863stack-frame, individual data and constants to be aligned for the maximum
7864single data access size for the chosen CPU model. The default is to
7865arrange for 32-bit alignment. ABI details such as structure layout are
7866not affected by these options.
7867
7868@item -m32-bit
7869@itemx -m16-bit
7870@itemx -m8-bit
7871@opindex m32-bit
7872@opindex m16-bit
7873@opindex m8-bit
7874Similar to the stack- data- and const-align options above, these options
7875arrange for stack-frame, writable data and constants to all be 32-bit,
787616-bit or 8-bit aligned. The default is 32-bit alignment.
7877
7878@item -mno-prologue-epilogue
7879@itemx -mprologue-epilogue
7880@opindex mno-prologue-epilogue
7881@opindex mprologue-epilogue
7882With @option{-mno-prologue-epilogue}, the normal function prologue and
7883epilogue that sets up the stack-frame are omitted and no return
7884instructions or return sequences are generated in the code. Use this
7885option only together with visual inspection of the compiled code: no
7886warnings or errors are generated when call-saved registers must be saved,
7887or storage for local variable needs to be allocated.
7888
7889@item -mno-gotplt
7890@itemx -mgotplt
7891@opindex mno-gotplt
7892@opindex mgotplt
7893With @option{-fpic} and @option{-fPIC}, don't generate (do generate)
7894instruction sequences that load addresses for functions from the PLT part
7895of the GOT rather than (traditional on other architectures) calls to the
7896PLT@. The default is @option{-mgotplt}.
7897
7898@item -maout
7899@opindex maout
7900Legacy no-op option only recognized with the cris-axis-aout target.
7901
7902@item -melf
7903@opindex melf
7904Legacy no-op option only recognized with the cris-axis-elf and
7905cris-axis-linux-gnu targets.
7906
7907@item -melinux
7908@opindex melinux
7909Only recognized with the cris-axis-aout target, where it selects a
7910GNU/linux-like multilib, include files and instruction set for
7911@option{-march=v8}.
7912
7913@item -mlinux
7914@opindex mlinux
7915Legacy no-op option only recognized with the cris-axis-linux-gnu target.
7916
7917@item -sim
7918@opindex sim
7919This option, recognized for the cris-axis-aout and cris-axis-elf arranges
7920to link with input-output functions from a simulator library. Code,
7921initialized data and zero-initialized data are allocated consecutively.
7922
7923@item -sim2
7924@opindex sim2
7925Like @option{-sim}, but pass linker options to locate initialized data at
79260x40000000 and zero-initialized data at 0x80000000.
7927@end table
7928
7929@node CRX Options
7930@subsection CRX Options
7931@cindex CRX Options
7932
7933These options are defined specifically for the CRX ports.
7934
7935@table @gcctabopt
7936
7937@item -mmac
7938@opindex mmac
7939Enable the use of multiply-accumulate instructions. Disabled by default.
7940
7941@item -mpush-args
7942@opindex mpush-args
7943Push instructions will be used to pass outgoing arguments when functions
7944are called. Enabled by default.
7945@end table
7946
7947@node Darwin Options
7948@subsection Darwin Options
7949@cindex Darwin options
7950
7951These options are defined for all architectures running the Darwin operating
7952system.
7953
7954FSF GCC on Darwin does not create ``fat'' object files; it will create
7955an object file for the single architecture that it was built to
7956target. Apple's GCC on Darwin does create ``fat'' files if multiple
7957@option{-arch} options are used; it does so by running the compiler or
7958linker multiple times and joining the results together with
7959@file{lipo}.
7960
7961The subtype of the file created (like @samp{ppc7400} or @samp{ppc970} or
7962@samp{i686}) is determined by the flags that specify the ISA
7963that GCC is targetting, like @option{-mcpu} or @option{-march}. The
7964@option{-force_cpusubtype_ALL} option can be used to override this.
7965
7966The Darwin tools vary in their behavior when presented with an ISA
7967mismatch. The assembler, @file{as}, will only permit instructions to
7968be used that are valid for the subtype of the file it is generating,
7969so you cannot put 64-bit instructions in an @samp{ppc750} object file.
7970The linker for shared libraries, @file{/usr/bin/libtool}, will fail
7971and print an error if asked to create a shared library with a less
7972restrictive subtype than its input files (for instance, trying to put
7973a @samp{ppc970} object file in a @samp{ppc7400} library). The linker
7974for executables, @file{ld}, will quietly give the executable the most
7975restrictive subtype of any of its input files.
7976
7977@table @gcctabopt
7978@item -F@var{dir}
7979@opindex F
7980Add the framework directory @var{dir} to the head of the list of
7981directories to be searched for header files. These directories are
7982interleaved with those specified by @option{-I} options and are
7983scanned in a left-to-right order.
7984
7985A framework directory is a directory with frameworks in it. A
7986framework is a directory with a @samp{"Headers"} and/or
7987@samp{"PrivateHeaders"} directory contained directly in it that ends
7988in @samp{".framework"}. The name of a framework is the name of this
7989directory excluding the @samp{".framework"}. Headers associated with
7990the framework are found in one of those two directories, with
7991@samp{"Headers"} being searched first. A subframework is a framework
7992directory that is in a framework's @samp{"Frameworks"} directory.
7993Includes of subframework headers can only appear in a header of a
7994framework that contains the subframework, or in a sibling subframework
7995header. Two subframeworks are siblings if they occur in the same
7996framework. A subframework should not have the same name as a
7997framework, a warning will be issued if this is violated. Currently a
7998subframework cannot have subframeworks, in the future, the mechanism
7999may be extended to support this. The standard frameworks can be found
8000in @samp{"/System/Library/Frameworks"} and
8001@samp{"/Library/Frameworks"}. An example include looks like
8002@code{#include <Framework/header.h>}, where @samp{Framework} denotes
8003the name of the framework and header.h is found in the
8004@samp{"PrivateHeaders"} or @samp{"Headers"} directory.
8005
8006@item -gused
8007@opindex gused
8008Emit debugging information for symbols that are used. For STABS
8009debugging format, this enables @option{-feliminate-unused-debug-symbols}.
8010This is by default ON@.
8011
8012@item -gfull
8013@opindex gfull
8014Emit debugging information for all symbols and types.
8015
8016@item -mmacosx-version-min=@var{version}
8017The earliest version of MacOS X that this executable will run on
8018is @var{version}. Typical values of @var{version} include @code{10.1},
8019@code{10.2}, and @code{10.3.9}.
8020
8021The default for this option is to make choices that seem to be most
8022useful.
8023
8024@item -mkernel
8025@opindex mkernel
8026Enable kernel development mode. The @option{-mkernel} option sets
8027@option{-static}, @option{-fno-common}, @option{-fno-cxa-atexit},
8028@option{-fno-exceptions}, @option{-fno-non-call-exceptions},
8029@option{-fapple-kext}, @option{-fno-weak} and @option{-fno-rtti} where
8030applicable. This mode also sets @option{-mno-altivec},
8031@option{-msoft-float}, @option{-fno-builtin} and
8032@option{-mlong-branch} for PowerPC targets.
8033
8034@item -mone-byte-bool
8035@opindex mone-byte-bool
8036Override the defaults for @samp{bool} so that @samp{sizeof(bool)==1}.
8037By default @samp{sizeof(bool)} is @samp{4} when compiling for
8038Darwin/PowerPC and @samp{1} when compiling for Darwin/x86, so this
8039option has no effect on x86.
8040
8041@strong{Warning:} The @option{-mone-byte-bool} switch causes GCC
8042to generate code that is not binary compatible with code generated
8043without that switch. Using this switch may require recompiling all
8044other modules in a program, including system libraries. Use this
8045switch to conform to a non-default data model.
8046
8047@item -mfix-and-continue
8048@itemx -ffix-and-continue
8049@itemx -findirect-data
8050@opindex mfix-and-continue
8051@opindex ffix-and-continue
8052@opindex findirect-data
8053Generate code suitable for fast turn around development. Needed to
8054enable gdb to dynamically load @code{.o} files into already running
8055programs. @option{-findirect-data} and @option{-ffix-and-continue}
8056are provided for backwards compatibility.
8057
8058@item -all_load
8059@opindex all_load
8060Loads all members of static archive libraries.
8061See man ld(1) for more information.
8062
8063@item -arch_errors_fatal
8064@opindex arch_errors_fatal
8065Cause the errors having to do with files that have the wrong architecture
8066to be fatal.
8067
8068@item -bind_at_load
8069@opindex bind_at_load
8070Causes the output file to be marked such that the dynamic linker will
8071bind all undefined references when the file is loaded or launched.
8072
8073@item -bundle
8074@opindex bundle
8075Produce a Mach-o bundle format file.
8076See man ld(1) for more information.
8077
8078@item -bundle_loader @var{executable}
8079@opindex bundle_loader
8080This option specifies the @var{executable} that will be loading the build
8081output file being linked. See man ld(1) for more information.
8082
8083@item -dynamiclib
8084@opindex dynamiclib
8085When passed this option, GCC will produce a dynamic library instead of
8086an executable when linking, using the Darwin @file{libtool} command.
8087
8088@item -force_cpusubtype_ALL
8089@opindex force_cpusubtype_ALL
8090This causes GCC's output file to have the @var{ALL} subtype, instead of
8091one controlled by the @option{-mcpu} or @option{-march} option.
8092
8093@item -allowable_client @var{client_name}
8094@itemx -client_name
8095@itemx -compatibility_version
8096@itemx -current_version
8097@itemx -dead_strip
8098@itemx -dependency-file
8099@itemx -dylib_file
8100@itemx -dylinker_install_name
8101@itemx -dynamic
8102@itemx -exported_symbols_list
8103@itemx -filelist
8104@itemx -flat_namespace
8105@itemx -force_flat_namespace
8106@itemx -headerpad_max_install_names
8107@itemx -image_base
8108@itemx -init
8109@itemx -install_name
8110@itemx -keep_private_externs
8111@itemx -multi_module
8112@itemx -multiply_defined
8113@itemx -multiply_defined_unused
8114@itemx -noall_load
8115@itemx -no_dead_strip_inits_and_terms
8116@itemx -nofixprebinding
8117@itemx -nomultidefs
8118@itemx -noprebind
8119@itemx -noseglinkedit
8120@itemx -pagezero_size
8121@itemx -prebind
8122@itemx -prebind_all_twolevel_modules
8123@itemx -private_bundle
8124@itemx -read_only_relocs
8125@itemx -sectalign
8126@itemx -sectobjectsymbols
8127@itemx -whyload
8128@itemx -seg1addr
8129@itemx -sectcreate
8130@itemx -sectobjectsymbols
8131@itemx -sectorder
8132@itemx -segaddr
8133@itemx -segs_read_only_addr
8134@itemx -segs_read_write_addr
8135@itemx -seg_addr_table
8136@itemx -seg_addr_table_filename
8137@itemx -seglinkedit
8138@itemx -segprot
8139@itemx -segs_read_only_addr
8140@itemx -segs_read_write_addr
8141@itemx -single_module
8142@itemx -static
8143@itemx -sub_library
8144@itemx -sub_umbrella
8145@itemx -twolevel_namespace
8146@itemx -umbrella
8147@itemx -undefined
8148@itemx -unexported_symbols_list
8149@itemx -weak_reference_mismatches
8150@itemx -whatsloaded
8151
8152@opindex allowable_client
8153@opindex client_name
8154@opindex compatibility_version
8155@opindex current_version
8156@opindex dead_strip
8157@opindex dependency-file
8158@opindex dylib_file
8159@opindex dylinker_install_name
8160@opindex dynamic
8161@opindex exported_symbols_list
8162@opindex filelist
8163@opindex flat_namespace
8164@opindex force_flat_namespace
8165@opindex headerpad_max_install_names
8166@opindex image_base
8167@opindex init
8168@opindex install_name
8169@opindex keep_private_externs
8170@opindex multi_module
8171@opindex multiply_defined
8172@opindex multiply_defined_unused
8173@opindex noall_load
8174@opindex no_dead_strip_inits_and_terms
8175@opindex nofixprebinding
8176@opindex nomultidefs
8177@opindex noprebind
8178@opindex noseglinkedit
8179@opindex pagezero_size
8180@opindex prebind
8181@opindex prebind_all_twolevel_modules
8182@opindex private_bundle
8183@opindex read_only_relocs
8184@opindex sectalign
8185@opindex sectobjectsymbols
8186@opindex whyload
8187@opindex seg1addr
8188@opindex sectcreate
8189@opindex sectobjectsymbols
8190@opindex sectorder
8191@opindex segaddr
8192@opindex segs_read_only_addr
8193@opindex segs_read_write_addr
8194@opindex seg_addr_table
8195@opindex seg_addr_table_filename
8196@opindex seglinkedit
8197@opindex segprot
8198@opindex segs_read_only_addr
8199@opindex segs_read_write_addr
8200@opindex single_module
8201@opindex static
8202@opindex sub_library
8203@opindex sub_umbrella
8204@opindex twolevel_namespace
8205@opindex umbrella
8206@opindex undefined
8207@opindex unexported_symbols_list
8208@opindex weak_reference_mismatches
8209@opindex whatsloaded
8210
8211These options are passed to the Darwin linker. The Darwin linker man page
8212describes them in detail.
8213@end table
8214
8215@node DEC Alpha Options
8216@subsection DEC Alpha Options
8217
8218These @samp{-m} options are defined for the DEC Alpha implementations:
8219
8220@table @gcctabopt
8221@item -mno-soft-float
8222@itemx -msoft-float
8223@opindex mno-soft-float
8224@opindex msoft-float
8225Use (do not use) the hardware floating-point instructions for
8226floating-point operations. When @option{-msoft-float} is specified,
8227functions in @file{libgcc.a} will be used to perform floating-point
8228operations. Unless they are replaced by routines that emulate the
8229floating-point operations, or compiled in such a way as to call such
8230emulations routines, these routines will issue floating-point
8231operations. If you are compiling for an Alpha without floating-point
8232operations, you must ensure that the library is built so as not to call
8233them.
8234
8235Note that Alpha implementations without floating-point operations are
8236required to have floating-point registers.
8237
8238@item -mfp-reg
8239@itemx -mno-fp-regs
8240@opindex mfp-reg
8241@opindex mno-fp-regs
8242Generate code that uses (does not use) the floating-point register set.
8243@option{-mno-fp-regs} implies @option{-msoft-float}. If the floating-point
8244register set is not used, floating point operands are passed in integer
8245registers as if they were integers and floating-point results are passed
8246in @code{$0} instead of @code{$f0}. This is a non-standard calling sequence,
8247so any function with a floating-point argument or return value called by code
8248compiled with @option{-mno-fp-regs} must also be compiled with that
8249option.
8250
8251A typical use of this option is building a kernel that does not use,
8252and hence need not save and restore, any floating-point registers.
8253
8254@item -mieee
8255@opindex mieee
8256The Alpha architecture implements floating-point hardware optimized for
8257maximum performance. It is mostly compliant with the IEEE floating
8258point standard. However, for full compliance, software assistance is
8259required. This option generates code fully IEEE compliant code
8260@emph{except} that the @var{inexact-flag} is not maintained (see below).
8261If this option is turned on, the preprocessor macro @code{_IEEE_FP} is
8262defined during compilation. The resulting code is less efficient but is
8263able to correctly support denormalized numbers and exceptional IEEE
8264values such as not-a-number and plus/minus infinity. Other Alpha
8265compilers call this option @option{-ieee_with_no_inexact}.
8266
8267@item -mieee-with-inexact
8268@opindex mieee-with-inexact
8269This is like @option{-mieee} except the generated code also maintains
8270the IEEE @var{inexact-flag}. Turning on this option causes the
8271generated code to implement fully-compliant IEEE math. In addition to
8272@code{_IEEE_FP}, @code{_IEEE_FP_EXACT} is defined as a preprocessor
8273macro. On some Alpha implementations the resulting code may execute
8274significantly slower than the code generated by default. Since there is
8275very little code that depends on the @var{inexact-flag}, you should
8276normally not specify this option. Other Alpha compilers call this
8277option @option{-ieee_with_inexact}.
8278
8279@item -mfp-trap-mode=@var{trap-mode}
8280@opindex mfp-trap-mode
8281This option controls what floating-point related traps are enabled.
8282Other Alpha compilers call this option @option{-fptm @var{trap-mode}}.
8283The trap mode can be set to one of four values:
8284
8285@table @samp
8286@item n
8287This is the default (normal) setting. The only traps that are enabled
8288are the ones that cannot be disabled in software (e.g., division by zero
8289trap).
8290
8291@item u
8292In addition to the traps enabled by @samp{n}, underflow traps are enabled
8293as well.
8294
8295@item su
8296Like @samp{u}, but the instructions are marked to be safe for software
8297completion (see Alpha architecture manual for details).
8298
8299@item sui
8300Like @samp{su}, but inexact traps are enabled as well.
8301@end table
8302
8303@item -mfp-rounding-mode=@var{rounding-mode}
8304@opindex mfp-rounding-mode
8305Selects the IEEE rounding mode. Other Alpha compilers call this option
8306@option{-fprm @var{rounding-mode}}. The @var{rounding-mode} can be one
8307of:
8308
8309@table @samp
8310@item n
8311Normal IEEE rounding mode. Floating point numbers are rounded towards
8312the nearest machine number or towards the even machine number in case
8313of a tie.
8314
8315@item m
8316Round towards minus infinity.
8317
8318@item c
8319Chopped rounding mode. Floating point numbers are rounded towards zero.
8320
8321@item d
8322Dynamic rounding mode. A field in the floating point control register
8323(@var{fpcr}, see Alpha architecture reference manual) controls the
8324rounding mode in effect. The C library initializes this register for
8325rounding towards plus infinity. Thus, unless your program modifies the
8326@var{fpcr}, @samp{d} corresponds to round towards plus infinity.
8327@end table
8328
8329@item -mtrap-precision=@var{trap-precision}
8330@opindex mtrap-precision
8331In the Alpha architecture, floating point traps are imprecise. This
8332means without software assistance it is impossible to recover from a
8333floating trap and program execution normally needs to be terminated.
8334GCC can generate code that can assist operating system trap handlers
8335in determining the exact location that caused a floating point trap.
8336Depending on the requirements of an application, different levels of
8337precisions can be selected:
8338
8339@table @samp
8340@item p
8341Program precision. This option is the default and means a trap handler
8342can only identify which program caused a floating point exception.
8343
8344@item f
8345Function precision. The trap handler can determine the function that
8346caused a floating point exception.
8347
8348@item i
8349Instruction precision. The trap handler can determine the exact
8350instruction that caused a floating point exception.
8351@end table
8352
8353Other Alpha compilers provide the equivalent options called
8354@option{-scope_safe} and @option{-resumption_safe}.
8355
8356@item -mieee-conformant
8357@opindex mieee-conformant
8358This option marks the generated code as IEEE conformant. You must not
8359use this option unless you also specify @option{-mtrap-precision=i} and either
8360@option{-mfp-trap-mode=su} or @option{-mfp-trap-mode=sui}. Its only effect
8361is to emit the line @samp{.eflag 48} in the function prologue of the
8362generated assembly file. Under DEC Unix, this has the effect that
8363IEEE-conformant math library routines will be linked in.
8364
8365@item -mbuild-constants
8366@opindex mbuild-constants
8367Normally GCC examines a 32- or 64-bit integer constant to
8368see if it can construct it from smaller constants in two or three
8369instructions. If it cannot, it will output the constant as a literal and
8370generate code to load it from the data segment at runtime.
8371
8372Use this option to require GCC to construct @emph{all} integer constants
8373using code, even if it takes more instructions (the maximum is six).
8374
8375You would typically use this option to build a shared library dynamic
8376loader. Itself a shared library, it must relocate itself in memory
8377before it can find the variables and constants in its own data segment.
8378
8379@item -malpha-as
8380@itemx -mgas
8381@opindex malpha-as
8382@opindex mgas
8383Select whether to generate code to be assembled by the vendor-supplied
8384assembler (@option{-malpha-as}) or by the GNU assembler @option{-mgas}.
8385
8386@item -mbwx
8387@itemx -mno-bwx
8388@itemx -mcix
8389@itemx -mno-cix
8390@itemx -mfix
8391@itemx -mno-fix
8392@itemx -mmax
8393@itemx -mno-max
8394@opindex mbwx
8395@opindex mno-bwx
8396@opindex mcix
8397@opindex mno-cix
8398@opindex mfix
8399@opindex mno-fix
8400@opindex mmax
8401@opindex mno-max
8402Indicate whether GCC should generate code to use the optional BWX,
8403CIX, FIX and MAX instruction sets. The default is to use the instruction
8404sets supported by the CPU type specified via @option{-mcpu=} option or that
8405of the CPU on which GCC was built if none was specified.
8406
8407@item -mfloat-vax
8408@itemx -mfloat-ieee
8409@opindex mfloat-vax
8410@opindex mfloat-ieee
8411Generate code that uses (does not use) VAX F and G floating point
8412arithmetic instead of IEEE single and double precision.
8413
8414@item -mexplicit-relocs
8415@itemx -mno-explicit-relocs
8416@opindex mexplicit-relocs
8417@opindex mno-explicit-relocs
8418Older Alpha assemblers provided no way to generate symbol relocations
8419except via assembler macros. Use of these macros does not allow
8420optimal instruction scheduling. GNU binutils as of version 2.12
8421supports a new syntax that allows the compiler to explicitly mark
8422which relocations should apply to which instructions. This option
8423is mostly useful for debugging, as GCC detects the capabilities of
8424the assembler when it is built and sets the default accordingly.
8425
8426@item -msmall-data
8427@itemx -mlarge-data
8428@opindex msmall-data
8429@opindex mlarge-data
8430When @option{-mexplicit-relocs} is in effect, static data is
8431accessed via @dfn{gp-relative} relocations. When @option{-msmall-data}
8432is used, objects 8 bytes long or smaller are placed in a @dfn{small data area}
8433(the @code{.sdata} and @code{.sbss} sections) and are accessed via
843416-bit relocations off of the @code{$gp} register. This limits the
8435size of the small data area to 64KB, but allows the variables to be
8436directly accessed via a single instruction.
8437
8438The default is @option{-mlarge-data}. With this option the data area
8439is limited to just below 2GB@. Programs that require more than 2GB of
8440data must use @code{malloc} or @code{mmap} to allocate the data in the
8441heap instead of in the program's data segment.
8442
8443When generating code for shared libraries, @option{-fpic} implies
8444@option{-msmall-data} and @option{-fPIC} implies @option{-mlarge-data}.
8445
8446@item -msmall-text
8447@itemx -mlarge-text
8448@opindex msmall-text
8449@opindex mlarge-text
8450When @option{-msmall-text} is used, the compiler assumes that the
8451code of the entire program (or shared library) fits in 4MB, and is
8452thus reachable with a branch instruction. When @option{-msmall-data}
8453is used, the compiler can assume that all local symbols share the
8454same @code{$gp} value, and thus reduce the number of instructions
8455required for a function call from 4 to 1.
8456
8457The default is @option{-mlarge-text}.
8458
8459@item -mcpu=@var{cpu_type}
8460@opindex mcpu
8461Set the instruction set and instruction scheduling parameters for
8462machine type @var{cpu_type}. You can specify either the @samp{EV}
8463style name or the corresponding chip number. GCC supports scheduling
8464parameters for the EV4, EV5 and EV6 family of processors and will
8465choose the default values for the instruction set from the processor
8466you specify. If you do not specify a processor type, GCC will default
8467to the processor on which the compiler was built.
8468
8469Supported values for @var{cpu_type} are
8470
8471@table @samp
8472@item ev4
8473@itemx ev45
8474@itemx 21064
8475Schedules as an EV4 and has no instruction set extensions.
8476
8477@item ev5
8478@itemx 21164
8479Schedules as an EV5 and has no instruction set extensions.
8480
8481@item ev56
8482@itemx 21164a
8483Schedules as an EV5 and supports the BWX extension.
8484
8485@item pca56
8486@itemx 21164pc
8487@itemx 21164PC
8488Schedules as an EV5 and supports the BWX and MAX extensions.
8489
8490@item ev6
8491@itemx 21264
8492Schedules as an EV6 and supports the BWX, FIX, and MAX extensions.
8493
8494@item ev67
8495@itemx 21264a
8496Schedules as an EV6 and supports the BWX, CIX, FIX, and MAX extensions.
8497@end table
8498
8499@item -mtune=@var{cpu_type}
8500@opindex mtune
8501Set only the instruction scheduling parameters for machine type
8502@var{cpu_type}. The instruction set is not changed.
8503
8504@item -mmemory-latency=@var{time}
8505@opindex mmemory-latency
8506Sets the latency the scheduler should assume for typical memory
8507references as seen by the application. This number is highly
8508dependent on the memory access patterns used by the application
8509and the size of the external cache on the machine.
8510
8511Valid options for @var{time} are
8512
8513@table @samp
8514@item @var{number}
8515A decimal number representing clock cycles.
8516
8517@item L1
8518@itemx L2
8519@itemx L3
8520@itemx main
8521The compiler contains estimates of the number of clock cycles for
8522``typical'' EV4 & EV5 hardware for the Level 1, 2 & 3 caches
8523(also called Dcache, Scache, and Bcache), as well as to main memory.
8524Note that L3 is only valid for EV5.
8525
8526@end table
8527@end table
8528
8529@node DEC Alpha/VMS Options
8530@subsection DEC Alpha/VMS Options
8531
8532These @samp{-m} options are defined for the DEC Alpha/VMS implementations:
8533
8534@table @gcctabopt
8535@item -mvms-return-codes
8536@opindex mvms-return-codes
8537Return VMS condition codes from main. The default is to return POSIX
8538style condition (e.g.@ error) codes.
8539@end table
8540
8541@node FRV Options
8542@subsection FRV Options
8543@cindex FRV Options
8544
8545@table @gcctabopt
8546@item -mgpr-32
8547@opindex mgpr-32
8548
8549Only use the first 32 general purpose registers.
8550
8551@item -mgpr-64
8552@opindex mgpr-64
8553
8554Use all 64 general purpose registers.
8555
8556@item -mfpr-32
8557@opindex mfpr-32
8558
8559Use only the first 32 floating point registers.
8560
8561@item -mfpr-64
8562@opindex mfpr-64
8563
8564Use all 64 floating point registers
8565
8566@item -mhard-float
8567@opindex mhard-float
8568
8569Use hardware instructions for floating point operations.
8570
8571@item -msoft-float
8572@opindex msoft-float
8573
8574Use library routines for floating point operations.
8575
8576@item -malloc-cc
8577@opindex malloc-cc
8578
8579Dynamically allocate condition code registers.
8580
8581@item -mfixed-cc
8582@opindex mfixed-cc
8583
8584Do not try to dynamically allocate condition code registers, only
8585use @code{icc0} and @code{fcc0}.
8586
8587@item -mdword
8588@opindex mdword
8589
8590Change ABI to use double word insns.
8591
8592@item -mno-dword
8593@opindex mno-dword
8594
8595Do not use double word instructions.
8596
8597@item -mdouble
8598@opindex mdouble
8599
8600Use floating point double instructions.
8601
8602@item -mno-double
8603@opindex mno-double
8604
8605Do not use floating point double instructions.
8606
8607@item -mmedia
8608@opindex mmedia
8609
8610Use media instructions.
8611
8612@item -mno-media
8613@opindex mno-media
8614
8615Do not use media instructions.
8616
8617@item -mmuladd
8618@opindex mmuladd
8619
8620Use multiply and add/subtract instructions.
8621
8622@item -mno-muladd
8623@opindex mno-muladd
8624
8625Do not use multiply and add/subtract instructions.
8626
8627@item -mfdpic
8628@opindex mfdpic
8629
8630Select the FDPIC ABI, that uses function descriptors to represent
8631pointers to functions. Without any PIC/PIE-related options, it
8632implies @option{-fPIE}. With @option{-fpic} or @option{-fpie}, it
8633assumes GOT entries and small data are within a 12-bit range from the
8634GOT base address; with @option{-fPIC} or @option{-fPIE}, GOT offsets
8635are computed with 32 bits.
8636
8637@item -minline-plt
8638@opindex minline-plt
8639
8640Enable inlining of PLT entries in function calls to functions that are
8641not known to bind locally. It has no effect without @option{-mfdpic}.
8642It's enabled by default if optimizing for speed and compiling for
8643shared libraries (i.e., @option{-fPIC} or @option{-fpic}), or when an
8644optimization option such as @option{-O3} or above is present in the
8645command line.
8646
8647@item -mTLS
8648@opindex TLS
8649
8650Assume a large TLS segment when generating thread-local code.
8651
8652@item -mtls
8653@opindex tls
8654
8655Do not assume a large TLS segment when generating thread-local code.
8656
8657@item -mgprel-ro
8658@opindex mgprel-ro
8659
8660Enable the use of @code{GPREL} relocations in the FDPIC ABI for data
8661that is known to be in read-only sections. It's enabled by default,
8662except for @option{-fpic} or @option{-fpie}: even though it may help
8663make the global offset table smaller, it trades 1 instruction for 4.
8664With @option{-fPIC} or @option{-fPIE}, it trades 3 instructions for 4,
8665one of which may be shared by multiple symbols, and it avoids the need
8666for a GOT entry for the referenced symbol, so it's more likely to be a
8667win. If it is not, @option{-mno-gprel-ro} can be used to disable it.
8668
8669@item -multilib-library-pic
8670@opindex multilib-library-pic
8671
8672Link with the (library, not FD) pic libraries. It's implied by
8673@option{-mlibrary-pic}, as well as by @option{-fPIC} and
8674@option{-fpic} without @option{-mfdpic}. You should never have to use
8675it explicitly.
8676
8677@item -mlinked-fp
8678@opindex mlinked-fp
8679
8680Follow the EABI requirement of always creating a frame pointer whenever
8681a stack frame is allocated. This option is enabled by default and can
8682be disabled with @option{-mno-linked-fp}.
8683
8684@item -mlong-calls
8685@opindex mlong-calls
8686
8687Use indirect addressing to call functions outside the current
8688compilation unit. This allows the functions to be placed anywhere
8689within the 32-bit address space.
8690
8691@item -malign-labels
8692@opindex malign-labels
8693
8694Try to align labels to an 8-byte boundary by inserting nops into the
8695previous packet. This option only has an effect when VLIW packing
8696is enabled. It doesn't create new packets; it merely adds nops to
8697existing ones.
8698
8699@item -mlibrary-pic
8700@opindex mlibrary-pic
8701
8702Generate position-independent EABI code.
8703
8704@item -macc-4
8705@opindex macc-4
8706
8707Use only the first four media accumulator registers.
8708
8709@item -macc-8
8710@opindex macc-8
8711
8712Use all eight media accumulator registers.
8713
8714@item -mpack
8715@opindex mpack
8716
8717Pack VLIW instructions.
8718
8719@item -mno-pack
8720@opindex mno-pack
8721
8722Do not pack VLIW instructions.
8723
8724@item -mno-eflags
8725@opindex mno-eflags
8726
8727Do not mark ABI switches in e_flags.
8728
8729@item -mcond-move
8730@opindex mcond-move
8731
8732Enable the use of conditional-move instructions (default).
8733
8734This switch is mainly for debugging the compiler and will likely be removed
8735in a future version.
8736
8737@item -mno-cond-move
8738@opindex mno-cond-move
8739
8740Disable the use of conditional-move instructions.
8741
8742This switch is mainly for debugging the compiler and will likely be removed
8743in a future version.
8744
8745@item -mscc
8746@opindex mscc
8747
8748Enable the use of conditional set instructions (default).
8749
8750This switch is mainly for debugging the compiler and will likely be removed
8751in a future version.
8752
8753@item -mno-scc
8754@opindex mno-scc
8755
8756Disable the use of conditional set instructions.
8757
8758This switch is mainly for debugging the compiler and will likely be removed
8759in a future version.
8760
8761@item -mcond-exec
8762@opindex mcond-exec
8763
8764Enable the use of conditional execution (default).
8765
8766This switch is mainly for debugging the compiler and will likely be removed
8767in a future version.
8768
8769@item -mno-cond-exec
8770@opindex mno-cond-exec
8771
8772Disable the use of conditional execution.
8773
8774This switch is mainly for debugging the compiler and will likely be removed
8775in a future version.
8776
8777@item -mvliw-branch
8778@opindex mvliw-branch
8779
8780Run a pass to pack branches into VLIW instructions (default).
8781
8782This switch is mainly for debugging the compiler and will likely be removed
8783in a future version.
8784
8785@item -mno-vliw-branch
8786@opindex mno-vliw-branch
8787
8788Do not run a pass to pack branches into VLIW instructions.
8789
8790This switch is mainly for debugging the compiler and will likely be removed
8791in a future version.
8792
8793@item -mmulti-cond-exec
8794@opindex mmulti-cond-exec
8795
8796Enable optimization of @code{&&} and @code{||} in conditional execution
8797(default).
8798
8799This switch is mainly for debugging the compiler and will likely be removed
8800in a future version.
8801
8802@item -mno-multi-cond-exec
8803@opindex mno-multi-cond-exec
8804
8805Disable optimization of @code{&&} and @code{||} in conditional execution.
8806
8807This switch is mainly for debugging the compiler and will likely be removed
8808in a future version.
8809
8810@item -mnested-cond-exec
8811@opindex mnested-cond-exec
8812
8813Enable nested conditional execution optimizations (default).
8814
8815This switch is mainly for debugging the compiler and will likely be removed
8816in a future version.
8817
8818@item -mno-nested-cond-exec
8819@opindex mno-nested-cond-exec
8820
8821Disable nested conditional execution optimizations.
8822
8823This switch is mainly for debugging the compiler and will likely be removed
8824in a future version.
8825
8826@item -moptimize-membar
8827@opindex moptimize-membar
8828
8829This switch removes redundant @code{membar} instructions from the
8830compiler generated code. It is enabled by default.
8831
8832@item -mno-optimize-membar
8833@opindex mno-optimize-membar
8834
8835This switch disables the automatic removal of redundant @code{membar}
8836instructions from the generated code.
8837
8838@item -mtomcat-stats
8839@opindex mtomcat-stats
8840
8841Cause gas to print out tomcat statistics.
8842
8843@item -mcpu=@var{cpu}
8844@opindex mcpu
8845
8846Select the processor type for which to generate code. Possible values are
8847@samp{frv}, @samp{fr550}, @samp{tomcat}, @samp{fr500}, @samp{fr450},
8848@samp{fr405}, @samp{fr400}, @samp{fr300} and @samp{simple}.
8849
8850@end table
8851
8852@node GNU/Linux Options
8853@subsection GNU/Linux Options
8854
8855These @samp{-m} options are defined for GNU/Linux targets:
8856
8857@table @gcctabopt
8858@item -mglibc
8859@opindex mglibc
8860Use the GNU C library instead of uClibc. This is the default except
8861on @samp{*-*-linux-*uclibc*} targets.
8862
8863@item -muclibc
8864@opindex muclibc
8865Use uClibc instead of the GNU C library. This is the default on
8866@samp{*-*-linux-*uclibc*} targets.
8867@end table
8868
8869@node H8/300 Options
8870@subsection H8/300 Options
8871
8872These @samp{-m} options are defined for the H8/300 implementations:
8873
8874@table @gcctabopt
8875@item -mrelax
8876@opindex mrelax
8877Shorten some address references at link time, when possible; uses the
8878linker option @option{-relax}. @xref{H8/300,, @code{ld} and the H8/300,
8879ld, Using ld}, for a fuller description.
8880
8881@item -mh
8882@opindex mh
8883Generate code for the H8/300H@.
8884
8885@item -ms
8886@opindex ms
8887Generate code for the H8S@.
8888
8889@item -mn
8890@opindex mn
8891Generate code for the H8S and H8/300H in the normal mode. This switch
8892must be used either with @option{-mh} or @option{-ms}.
8893
8894@item -ms2600
8895@opindex ms2600
8896Generate code for the H8S/2600. This switch must be used with @option{-ms}.
8897
8898@item -mint32
8899@opindex mint32
8900Make @code{int} data 32 bits by default.
8901
8902@item -malign-300
8903@opindex malign-300
8904On the H8/300H and H8S, use the same alignment rules as for the H8/300.
8905The default for the H8/300H and H8S is to align longs and floats on 4
8906byte boundaries.
8907@option{-malign-300} causes them to be aligned on 2 byte boundaries.
8908This option has no effect on the H8/300.
8909@end table
8910
8911@node HPPA Options
8912@subsection HPPA Options
8913@cindex HPPA Options
8914
8915These @samp{-m} options are defined for the HPPA family of computers:
8916
8917@table @gcctabopt
8918@item -march=@var{architecture-type}
8919@opindex march
8920Generate code for the specified architecture. The choices for
8921@var{architecture-type} are @samp{1.0} for PA 1.0, @samp{1.1} for PA
89221.1, and @samp{2.0} for PA 2.0 processors. Refer to
8923@file{/usr/lib/sched.models} on an HP-UX system to determine the proper
8924architecture option for your machine. Code compiled for lower numbered
8925architectures will run on higher numbered architectures, but not the
8926other way around.
8927
8928@item -mpa-risc-1-0
8929@itemx -mpa-risc-1-1
8930@itemx -mpa-risc-2-0
8931@opindex mpa-risc-1-0
8932@opindex mpa-risc-1-1
8933@opindex mpa-risc-2-0
8934Synonyms for @option{-march=1.0}, @option{-march=1.1}, and @option{-march=2.0} respectively.
8935
8936@item -mbig-switch
8937@opindex mbig-switch
8938Generate code suitable for big switch tables. Use this option only if
8939the assembler/linker complain about out of range branches within a switch
8940table.
8941
8942@item -mjump-in-delay
8943@opindex mjump-in-delay
8944Fill delay slots of function calls with unconditional jump instructions
8945by modifying the return pointer for the function call to be the target
8946of the conditional jump.
8947
8948@item -mdisable-fpregs
8949@opindex mdisable-fpregs
8950Prevent floating point registers from being used in any manner. This is
8951necessary for compiling kernels which perform lazy context switching of
8952floating point registers. If you use this option and attempt to perform
8953floating point operations, the compiler will abort.
8954
8955@item -mdisable-indexing
8956@opindex mdisable-indexing
8957Prevent the compiler from using indexing address modes. This avoids some
8958rather obscure problems when compiling MIG generated code under MACH@.
8959
8960@item -mno-space-regs
8961@opindex mno-space-regs
8962Generate code that assumes the target has no space registers. This allows
8963GCC to generate faster indirect calls and use unscaled index address modes.
8964
8965Such code is suitable for level 0 PA systems and kernels.
8966
8967@item -mfast-indirect-calls
8968@opindex mfast-indirect-calls
8969Generate code that assumes calls never cross space boundaries. This
8970allows GCC to emit code which performs faster indirect calls.
8971
8972This option will not work in the presence of shared libraries or nested
8973functions.
8974
8975@item -mfixed-range=@var{register-range}
8976@opindex mfixed-range
8977Generate code treating the given register range as fixed registers.
8978A fixed register is one that the register allocator can not use. This is
8979useful when compiling kernel code. A register range is specified as
8980two registers separated by a dash. Multiple register ranges can be
8981specified separated by a comma.
8982
8983@item -mlong-load-store
8984@opindex mlong-load-store
8985Generate 3-instruction load and store sequences as sometimes required by
8986the HP-UX 10 linker. This is equivalent to the @samp{+k} option to
8987the HP compilers.
8988
8989@item -mportable-runtime
8990@opindex mportable-runtime
8991Use the portable calling conventions proposed by HP for ELF systems.
8992
8993@item -mgas
8994@opindex mgas
8995Enable the use of assembler directives only GAS understands.
8996
8997@item -mschedule=@var{cpu-type}
8998@opindex mschedule
8999Schedule code according to the constraints for the machine type
9000@var{cpu-type}. The choices for @var{cpu-type} are @samp{700}
9001@samp{7100}, @samp{7100LC}, @samp{7200}, @samp{7300} and @samp{8000}. Refer
9002to @file{/usr/lib/sched.models} on an HP-UX system to determine the
9003proper scheduling option for your machine. The default scheduling is
9004@samp{8000}.
9005
9006@item -mlinker-opt
9007@opindex mlinker-opt
9008Enable the optimization pass in the HP-UX linker. Note this makes symbolic
9009debugging impossible. It also triggers a bug in the HP-UX 8 and HP-UX 9
9010linkers in which they give bogus error messages when linking some programs.
9011
9012@item -msoft-float
9013@opindex msoft-float
9014Generate output containing library calls for floating point.
9015@strong{Warning:} the requisite libraries are not available for all HPPA
9016targets. Normally the facilities of the machine's usual C compiler are
9017used, but this cannot be done directly in cross-compilation. You must make
9018your own arrangements to provide suitable library functions for
9019cross-compilation. The embedded target @samp{hppa1.1-*-pro}
9020does provide software floating point support.
9021
9022@option{-msoft-float} changes the calling convention in the output file;
9023therefore, it is only useful if you compile @emph{all} of a program with
9024this option. In particular, you need to compile @file{libgcc.a}, the
9025library that comes with GCC, with @option{-msoft-float} in order for
9026this to work.
9027
9028@item -msio
9029@opindex msio
9030Generate the predefine, @code{_SIO}, for server IO@. The default is
9031@option{-mwsio}. This generates the predefines, @code{__hp9000s700},
9032@code{__hp9000s700__} and @code{_WSIO}, for workstation IO@. These
9033options are available under HP-UX and HI-UX@.
9034
9035@item -mgnu-ld
9036@opindex gnu-ld
9037Use GNU ld specific options. This passes @option{-shared} to ld when
9038building a shared library. It is the default when GCC is configured,
9039explicitly or implicitly, with the GNU linker. This option does not
9040have any affect on which ld is called, it only changes what parameters
9041are passed to that ld. The ld that is called is determined by the
9042@option{--with-ld} configure option, GCC's program search path, and
9043finally by the user's @env{PATH}. The linker used by GCC can be printed
9044using @samp{which `gcc -print-prog-name=ld`}. This option is only available
9045on the 64 bit HP-UX GCC, i.e. configured with @samp{hppa*64*-*-hpux*}.
9046
9047@item -mhp-ld
9048@opindex hp-ld
9049Use HP ld specific options. This passes @option{-b} to ld when building
9050a shared library and passes @option{+Accept TypeMismatch} to ld on all
9051links. It is the default when GCC is configured, explicitly or
9052implicitly, with the HP linker. This option does not have any affect on
9053which ld is called, it only changes what parameters are passed to that
9054ld. The ld that is called is determined by the @option{--with-ld}
9055configure option, GCC's program search path, and finally by the user's
9056@env{PATH}. The linker used by GCC can be printed using @samp{which
9057`gcc -print-prog-name=ld`}. This option is only available on the 64 bit
9058HP-UX GCC, i.e. configured with @samp{hppa*64*-*-hpux*}.
9059
9060@item -mlong-calls
9061@opindex mno-long-calls
9062Generate code that uses long call sequences. This ensures that a call
9063is always able to reach linker generated stubs. The default is to generate
9064long calls only when the distance from the call site to the beginning
9065of the function or translation unit, as the case may be, exceeds a
9066predefined limit set by the branch type being used. The limits for
9067normal calls are 7,600,000 and 240,000 bytes, respectively for the
9068PA 2.0 and PA 1.X architectures. Sibcalls are always limited at
9069240,000 bytes.
9070
9071Distances are measured from the beginning of functions when using the
9072@option{-ffunction-sections} option, or when using the @option{-mgas}
9073and @option{-mno-portable-runtime} options together under HP-UX with
9074the SOM linker.
9075
9076It is normally not desirable to use this option as it will degrade
9077performance. However, it may be useful in large applications,
9078particularly when partial linking is used to build the application.
9079
9080The types of long calls used depends on the capabilities of the
9081assembler and linker, and the type of code being generated. The
9082impact on systems that support long absolute calls, and long pic
9083symbol-difference or pc-relative calls should be relatively small.
9084However, an indirect call is used on 32-bit ELF systems in pic code
9085and it is quite long.
9086
9087@item -munix=@var{unix-std}
9088@opindex march
9089Generate compiler predefines and select a startfile for the specified
9090UNIX standard. The choices for @var{unix-std} are @samp{93}, @samp{95}
9091and @samp{98}. @samp{93} is supported on all HP-UX versions. @samp{95}
9092is available on HP-UX 10.10 and later. @samp{98} is available on HP-UX
909311.11 and later. The default values are @samp{93} for HP-UX 10.00,
9094@samp{95} for HP-UX 10.10 though to 11.00, and @samp{98} for HP-UX 11.11
9095and later.
9096
9097@option{-munix=93} provides the same predefines as GCC 3.3 and 3.4.
9098@option{-munix=95} provides additional predefines for @code{XOPEN_UNIX}
9099and @code{_XOPEN_SOURCE_EXTENDED}, and the startfile @file{unix95.o}.
9100@option{-munix=98} provides additional predefines for @code{_XOPEN_UNIX},
9101@code{_XOPEN_SOURCE_EXTENDED}, @code{_INCLUDE__STDC_A1_SOURCE} and
9102@code{_INCLUDE_XOPEN_SOURCE_500}, and the startfile @file{unix98.o}.
9103
9104It is @emph{important} to note that this option changes the interfaces
9105for various library routines. It also affects the operational behavior
9106of the C library. Thus, @emph{extreme} care is needed in using this
9107option.
9108
9109Library code that is intended to operate with more than one UNIX
9110standard must test, set and restore the variable @var{__xpg4_extended_mask}
9111as appropriate. Most GNU software doesn't provide this capability.
9112
9113@item -nolibdld
9114@opindex nolibdld
9115Suppress the generation of link options to search libdld.sl when the
9116@option{-static} option is specified on HP-UX 10 and later.
9117
9118@item -static
9119@opindex static
9120The HP-UX implementation of setlocale in libc has a dependency on
9121libdld.sl. There isn't an archive version of libdld.sl. Thus,
9122when the @option{-static} option is specified, special link options
9123are needed to resolve this dependency.
9124
9125On HP-UX 10 and later, the GCC driver adds the necessary options to
9126link with libdld.sl when the @option{-static} option is specified.
9127This causes the resulting binary to be dynamic. On the 64-bit port,
9128the linkers generate dynamic binaries by default in any case. The
9129@option{-nolibdld} option can be used to prevent the GCC driver from
9130adding these link options.
9131
9132@item -threads
9133@opindex threads
9134Add support for multithreading with the @dfn{dce thread} library
9135under HP-UX@. This option sets flags for both the preprocessor and
9136linker.
9137@end table
9138
9139@node i386 and x86-64 Options
9140@subsection Intel 386 and AMD x86-64 Options
9141@cindex i386 Options
9142@cindex x86-64 Options
9143@cindex Intel 386 Options
9144@cindex AMD x86-64 Options
9145
9146These @samp{-m} options are defined for the i386 and x86-64 family of
9147computers:
9148
9149@table @gcctabopt
9150@item -mtune=@var{cpu-type}
9151@opindex mtune
9152Tune to @var{cpu-type} everything applicable about the generated code, except
9153for the ABI and the set of available instructions. The choices for
9154@var{cpu-type} are:
9155@table @emph
9156@item generic
9157Produce code optimized for the most common IA32/AMD64/EM64T processors.
9158If you know the CPU on which your code will run, then you should use
9159the corresponding @option{-mtune} option instead of
9160@option{-mtune=generic}. But, if you do not know exactly what CPU users
9161of your application will have, then you should use this option.
9162
9163As new processors are deployed in the marketplace, the behavior of this
9164option will change. Therefore, if you upgrade to a newer version of
9165GCC, the code generated option will change to reflect the processors
9166that were most common when that version of GCC was released.
9167
9168There is no @option{-march=generic} option because @option{-march}
9169indicates the instruction set the compiler can use, and there is no
9170generic instruction set applicable to all processors. In contrast,
9171@option{-mtune} indicates the processor (or, in this case, collection of
9172processors) for which the code is optimized.
9173@item native
9174This selects the CPU to tune for at compilation time by determining
9175the processor type of the compiling machine. Using @option{-mtune=native}
9176will produce code optimized for the local machine under the constraints
9177of the selected instruction set. Using @option{-march=native} will
9178enable all instruction subsets supported by the local machine (hence
9179the result might not run on different machines).
9180@item i386
9181Original Intel's i386 CPU@.
9182@item i486
9183Intel's i486 CPU@. (No scheduling is implemented for this chip.)
9184@item i586, pentium
9185Intel Pentium CPU with no MMX support.
9186@item pentium-mmx
9187Intel PentiumMMX CPU based on Pentium core with MMX instruction set support.
9188@item pentiumpro
9189Intel PentiumPro CPU@.
9190@item i686
9191Same as @code{generic}, but when used as @code{march} option, PentiumPro
9192instruction set will be used, so the code will run on all i686 family chips.
9193@item pentium2
9194Intel Pentium2 CPU based on PentiumPro core with MMX instruction set support.
9195@item pentium3, pentium3m
9196Intel Pentium3 CPU based on PentiumPro core with MMX and SSE instruction set
9197support.
9198@item pentium-m
9199Low power version of Intel Pentium3 CPU with MMX, SSE and SSE2 instruction set
9200support. Used by Centrino notebooks.
9201@item pentium4, pentium4m
9202Intel Pentium4 CPU with MMX, SSE and SSE2 instruction set support.
9203@item prescott
9204Improved version of Intel Pentium4 CPU with MMX, SSE, SSE2 and SSE3 instruction
9205set support.
9206@item nocona
9207Improved version of Intel Pentium4 CPU with 64-bit extensions, MMX, SSE,
9208SSE2 and SSE3 instruction set support.
9209@item core2
9210Intel Core2 CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3 and SSSE3
9211instruction set support.
9212@item k6
9213AMD K6 CPU with MMX instruction set support.
9214@item k6-2, k6-3
9215Improved versions of AMD K6 CPU with MMX and 3dNOW! instruction set support.
9216@item athlon, athlon-tbird
9217AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW! and SSE prefetch instructions
9218support.
9219@item athlon-4, athlon-xp, athlon-mp
9220Improved AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW! and full SSE
9221instruction set support.
9222@item k8, opteron, athlon64, athlon-fx
9223AMD K8 core based CPUs with x86-64 instruction set support. (This supersets
9224MMX, SSE, SSE2, 3dNOW!, enhanced 3dNOW! and 64-bit instruction set extensions.)
9225@item k8-sse3, opteron-sse3, athlon64-sse3
9226Improved versions of k8, opteron and athlon64 with SSE3 instruction set support.
9227@item amdfam10, barcelona
9228AMD Family 10h core based CPUs with x86-64 instruction set support. (This
9229supersets MMX, SSE, SSE2, SSE3, SSE4A, 3dNOW!, enhanced 3dNOW!, ABM and 64-bit
9230instruction set extensions.)
9231@item winchip-c6
9232IDT Winchip C6 CPU, dealt in same way as i486 with additional MMX instruction
9233set support.
9234@item winchip2
9235IDT Winchip2 CPU, dealt in same way as i486 with additional MMX and 3dNOW!
9236instruction set support.
9237@item c3
9238Via C3 CPU with MMX and 3dNOW! instruction set support. (No scheduling is
9239implemented for this chip.)
9240@item c3-2
9241Via C3-2 CPU with MMX and SSE instruction set support. (No scheduling is
9242implemented for this chip.)
9243@item geode
9244Embedded AMD CPU with MMX and 3dNOW! instruction set support.
9245@end table
9246
9247While picking a specific @var{cpu-type} will schedule things appropriately
9248for that particular chip, the compiler will not generate any code that
9249does not run on the i386 without the @option{-march=@var{cpu-type}} option
9250being used.
9251
9252@item -march=@var{cpu-type}
9253@opindex march
9254Generate instructions for the machine type @var{cpu-type}. The choices
9255for @var{cpu-type} are the same as for @option{-mtune}. Moreover,
9256specifying @option{-march=@var{cpu-type}} implies @option{-mtune=@var{cpu-type}}.
9257
9258@item -mcpu=@var{cpu-type}
9259@opindex mcpu
9260A deprecated synonym for @option{-mtune}.
9261
9262@item -m386
9263@itemx -m486
9264@itemx -mpentium
9265@itemx -mpentiumpro
9266@opindex m386
9267@opindex m486
9268@opindex mpentium
9269@opindex mpentiumpro
9270These options are synonyms for @option{-mtune=i386}, @option{-mtune=i486},
9271@option{-mtune=pentium}, and @option{-mtune=pentiumpro} respectively.
9272These synonyms are deprecated.
9273
9274@item -mfpmath=@var{unit}
9275@opindex march
9276Generate floating point arithmetics for selected unit @var{unit}. The choices
9277for @var{unit} are:
9278
9279@table @samp
9280@item 387
9281Use the standard 387 floating point coprocessor present majority of chips and
9282emulated otherwise. Code compiled with this option will run almost everywhere.
9283The temporary results are computed in 80bit precision instead of precision
9284specified by the type resulting in slightly different results compared to most
9285of other chips. See @option{-ffloat-store} for more detailed description.
9286
9287This is the default choice for i386 compiler.
9288
9289@item sse
9290Use scalar floating point instructions present in the SSE instruction set.
9291This instruction set is supported by Pentium3 and newer chips, in the AMD line
9292by Athlon-4, Athlon-xp and Athlon-mp chips. The earlier version of SSE
9293instruction set supports only single precision arithmetics, thus the double and
9294extended precision arithmetics is still done using 387. Later version, present
9295only in Pentium4 and the future AMD x86-64 chips supports double precision
9296arithmetics too.
9297
9298For the i386 compiler, you need to use @option{-march=@var{cpu-type}}, @option{-msse}
9299or @option{-msse2} switches to enable SSE extensions and make this option
9300effective. For the x86-64 compiler, these extensions are enabled by default.
9301
9302The resulting code should be considerably faster in the majority of cases and avoid
9303the numerical instability problems of 387 code, but may break some existing
9304code that expects temporaries to be 80bit.
9305
9306This is the default choice for the x86-64 compiler.
9307
9308@item sse,387
9309Attempt to utilize both instruction sets at once. This effectively double the
9310amount of available registers and on chips with separate execution units for
9311387 and SSE the execution resources too. Use this option with care, as it is
9312still experimental, because the GCC register allocator does not model separate
9313functional units well resulting in instable performance.
9314@end table
9315
9316@item -masm=@var{dialect}
9317@opindex masm=@var{dialect}
9318Output asm instructions using selected @var{dialect}. Supported
9319choices are @samp{intel} or @samp{att} (the default one). Darwin does
9320not support @samp{intel}.
9321
9322@item -mieee-fp
9323@itemx -mno-ieee-fp
9324@opindex mieee-fp
9325@opindex mno-ieee-fp
9326Control whether or not the compiler uses IEEE floating point
9327comparisons. These handle correctly the case where the result of a
9328comparison is unordered.
9329
9330@item -msoft-float
9331@opindex msoft-float
9332Generate output containing library calls for floating point.
9333@strong{Warning:} the requisite libraries are not part of GCC@.
9334Normally the facilities of the machine's usual C compiler are used, but
9335this can't be done directly in cross-compilation. You must make your
9336own arrangements to provide suitable library functions for
9337cross-compilation.
9338
9339On machines where a function returns floating point results in the 80387
9340register stack, some floating point opcodes may be emitted even if
9341@option{-msoft-float} is used.
9342
9343@item -mno-fp-ret-in-387
9344@opindex mno-fp-ret-in-387
9345Do not use the FPU registers for return values of functions.
9346
9347The usual calling convention has functions return values of types
9348@code{float} and @code{double} in an FPU register, even if there
9349is no FPU@. The idea is that the operating system should emulate
9350an FPU@.
9351
9352The option @option{-mno-fp-ret-in-387} causes such values to be returned
9353in ordinary CPU registers instead.
9354
9355@item -mno-fancy-math-387
9356@opindex mno-fancy-math-387
9357Some 387 emulators do not support the @code{sin}, @code{cos} and
9358@code{sqrt} instructions for the 387. Specify this option to avoid
9359generating those instructions. This option is the default on
9360OpenBSD and NetBSD@. This option is overridden when @option{-march}
9361indicates that the target cpu will always have an FPU and so the
9362instruction will not need emulation. As of revision 2.6.1, these
9363instructions are not generated unless you also use the
9364@option{-funsafe-math-optimizations} switch.
9365
9366@item -malign-double
9367@itemx -mno-align-double
9368@opindex malign-double
9369@opindex mno-align-double
9370Control whether GCC aligns @code{double}, @code{long double}, and
9371@code{long long} variables on a two word boundary or a one word
9372boundary. Aligning @code{double} variables on a two word boundary will
9373produce code that runs somewhat faster on a @samp{Pentium} at the
9374expense of more memory.
9375
9376On x86-64, @option{-malign-double} is enabled by default.
9377
9378@strong{Warning:} if you use the @option{-malign-double} switch,
9379structures containing the above types will be aligned differently than
9380the published application binary interface specifications for the 386
9381and will not be binary compatible with structures in code compiled
9382without that switch.
9383
9384@item -m96bit-long-double
9385@itemx -m128bit-long-double
9386@opindex m96bit-long-double
9387@opindex m128bit-long-double
9388These switches control the size of @code{long double} type. The i386
9389application binary interface specifies the size to be 96 bits,
9390so @option{-m96bit-long-double} is the default in 32 bit mode.
9391
9392Modern architectures (Pentium and newer) would prefer @code{long double}
9393to be aligned to an 8 or 16 byte boundary. In arrays or structures
9394conforming to the ABI, this would not be possible. So specifying a
9395@option{-m128bit-long-double} will align @code{long double}
9396to a 16 byte boundary by padding the @code{long double} with an additional
939732 bit zero.
9398
9399In the x86-64 compiler, @option{-m128bit-long-double} is the default choice as
9400its ABI specifies that @code{long double} is to be aligned on 16 byte boundary.
9401
9402Notice that neither of these options enable any extra precision over the x87
9403standard of 80 bits for a @code{long double}.
9404
9405@strong{Warning:} if you override the default value for your target ABI, the
9406structures and arrays containing @code{long double} variables will change
9407their size as well as function calling convention for function taking
9408@code{long double} will be modified. Hence they will not be binary
9409compatible with arrays or structures in code compiled without that switch.
9410
9411@item -mmlarge-data-threshold=@var{number}
9412@opindex mlarge-data-threshold=@var{number}
9413When @option{-mcmodel=medium} is specified, the data greater than
9414@var{threshold} are placed in large data section. This value must be the
9415same across all object linked into the binary and defaults to 65535.
9416
9417@item -msvr3-shlib
9418@itemx -mno-svr3-shlib
9419@opindex msvr3-shlib
9420@opindex mno-svr3-shlib
9421Control whether GCC places uninitialized local variables into the
9422@code{bss} or @code{data} segments. @option{-msvr3-shlib} places them
9423into @code{bss}. These options are meaningful only on System V Release 3.
9424
9425@item -mrtd
9426@opindex mrtd
9427Use a different function-calling convention, in which functions that
9428take a fixed number of arguments return with the @code{ret} @var{num}
9429instruction, which pops their arguments while returning. This saves one
9430instruction in the caller since there is no need to pop the arguments
9431there.
9432
9433You can specify that an individual function is called with this calling
9434sequence with the function attribute @samp{stdcall}. You can also
9435override the @option{-mrtd} option by using the function attribute
9436@samp{cdecl}. @xref{Function Attributes}.
9437
9438@strong{Warning:} this calling convention is incompatible with the one
9439normally used on Unix, so you cannot use it if you need to call
9440libraries compiled with the Unix compiler.
9441
9442Also, you must provide function prototypes for all functions that
9443take variable numbers of arguments (including @code{printf});
9444otherwise incorrect code will be generated for calls to those
9445functions.
9446
9447In addition, seriously incorrect code will result if you call a
9448function with too many arguments. (Normally, extra arguments are
9449harmlessly ignored.)
9450
9451@item -mregparm=@var{num}
9452@opindex mregparm
9453Control how many registers are used to pass integer arguments. By
9454default, no registers are used to pass arguments, and at most 3
9455registers can be used. You can control this behavior for a specific
9456function by using the function attribute @samp{regparm}.
9457@xref{Function Attributes}.
9458
9459@strong{Warning:} if you use this switch, and
9460@var{num} is nonzero, then you must build all modules with the same
9461value, including any libraries. This includes the system libraries and
9462startup modules.
9463
9464@item -msseregparm
9465@opindex msseregparm
9466Use SSE register passing conventions for float and double arguments
9467and return values. You can control this behavior for a specific
9468function by using the function attribute @samp{sseregparm}.
9469@xref{Function Attributes}.
9470
9471@strong{Warning:} if you use this switch then you must build all
9472modules with the same value, including any libraries. This includes
9473the system libraries and startup modules.
9474
9475@item -mstackrealign
9476@opindex mstackrealign
9477Realign the stack at entry. On the Intel x86, the
9478@option{-mstackrealign} option will generate an alternate prologue and
9479epilogue that realigns the runtime stack. This supports mixing legacy
9480codes that keep a 4-byte aligned stack with modern codes that keep a
948116-byte stack for SSE compatibility. The alternate prologue and
9482epilogue are slower and bigger than the regular ones, and the
9483alternate prologue requires an extra scratch register; this lowers the
9484number of registers available if used in conjunction with the
9485@code{regparm} attribute. The @option{-mstackrealign} option is
9486incompatible with the nested function prologue; this is considered a
9487hard error. See also the attribute @code{force_align_arg_pointer},
9488applicable to individual functions.
9489
9490@item -mpreferred-stack-boundary=@var{num}
9491@opindex mpreferred-stack-boundary
9492Attempt to keep the stack boundary aligned to a 2 raised to @var{num}
9493byte boundary. If @option{-mpreferred-stack-boundary} is not specified,
9494the default is 4 (16 bytes or 128 bits).
9495
9496On Pentium and PentiumPro, @code{double} and @code{long double} values
9497should be aligned to an 8 byte boundary (see @option{-malign-double}) or
9498suffer significant run time performance penalties. On Pentium III, the
9499Streaming SIMD Extension (SSE) data type @code{__m128} may not work
9500properly if it is not 16 byte aligned.
9501
9502To ensure proper alignment of this values on the stack, the stack boundary
9503must be as aligned as that required by any value stored on the stack.
9504Further, every function must be generated such that it keeps the stack
9505aligned. Thus calling a function compiled with a higher preferred
9506stack boundary from a function compiled with a lower preferred stack
9507boundary will most likely misalign the stack. It is recommended that
9508libraries that use callbacks always use the default setting.
9509
9510This extra alignment does consume extra stack space, and generally
9511increases code size. Code that is sensitive to stack space usage, such
9512as embedded systems and operating system kernels, may want to reduce the
9513preferred alignment to @option{-mpreferred-stack-boundary=2}.
9514
9515@item -mmmx
9516@itemx -mno-mmx
9517@item -msse
9518@itemx -mno-sse
9519@item -msse2
9520@itemx -mno-sse2
9521@item -msse3
9522@itemx -mno-sse3
9523@item -mssse3
9524@itemx -mno-ssse3
9525@item -msse4a
9526@item -mno-sse4a
9527@item -m3dnow
9528@itemx -mno-3dnow
9529@item -mpopcnt
9530@itemx -mno-popcnt
9531@item -mabm
9532@itemx -mno-abm
9533@item -maes
9534@itemx -mno-aes
9535@opindex mmmx
9536@opindex mno-mmx
9537@opindex msse
9538@opindex mno-sse
9539@opindex m3dnow
9540@opindex mno-3dnow
9541These switches enable or disable the use of instructions in the MMX,
9542SSE, SSE2, SSE3, SSSE3, SSE4A, ABM, AES or 3DNow! extended
9543instruction sets. These extensions are also available as built-in
9544functions: see @ref{X86 Built-in Functions}, for details of the functions
9545enabled and disabled by these switches.
9546
9547To have SSE/SSE2 instructions generated automatically from floating-point
9548code (as opposed to 387 instructions), see @option{-mfpmath=sse}.
9549
9550These options will enable GCC to use these extended instructions in
9551generated code, even without @option{-mfpmath=sse}. Applications which
9552perform runtime CPU detection must compile separate files for each
9553supported architecture, using the appropriate flags. In particular,
9554the file containing the CPU detection code should be compiled without
9555these options.
9556
9557@item -mpush-args
9558@itemx -mno-push-args
9559@opindex mpush-args
9560@opindex mno-push-args
9561Use PUSH operations to store outgoing parameters. This method is shorter
9562and usually equally fast as method using SUB/MOV operations and is enabled
9563by default. In some cases disabling it may improve performance because of
9564improved scheduling and reduced dependencies.
9565
9566@item -maccumulate-outgoing-args
9567@opindex maccumulate-outgoing-args
9568If enabled, the maximum amount of space required for outgoing arguments will be
9569computed in the function prologue. This is faster on most modern CPUs
9570because of reduced dependencies, improved scheduling and reduced stack usage
9571when preferred stack boundary is not equal to 2. The drawback is a notable
9572increase in code size. This switch implies @option{-mno-push-args}.
9573
9574@item -mthreads
9575@opindex mthreads
9576Support thread-safe exception handling on @samp{Mingw32}. Code that relies
9577on thread-safe exception handling must compile and link all code with the
9578@option{-mthreads} option. When compiling, @option{-mthreads} defines
9579@option{-D_MT}; when linking, it links in a special thread helper library
9580@option{-lmingwthrd} which cleans up per thread exception handling data.
9581
9582@item -mno-align-stringops
9583@opindex mno-align-stringops
9584Do not align destination of inlined string operations. This switch reduces
9585code size and improves performance in case the destination is already aligned,
9586but GCC doesn't know about it.
9587
9588@item -minline-all-stringops
9589@opindex minline-all-stringops
9590By default GCC inlines string operations only when destination is known to be
9591aligned at least to 4 byte boundary. This enables more inlining, increase code
9592size, but may improve performance of code that depends on fast memcpy, strlen
9593and memset for short lengths.
9594
9595@item -momit-leaf-frame-pointer
9596@opindex momit-leaf-frame-pointer
9597Don't keep the frame pointer in a register for leaf functions. This
9598avoids the instructions to save, set up and restore frame pointers and
9599makes an extra register available in leaf functions. The option
9600@option{-fomit-frame-pointer} removes the frame pointer for all functions
9601which might make debugging harder.
9602
9603@item -mtls-direct-seg-refs
9604@itemx -mno-tls-direct-seg-refs
9605@opindex mtls-direct-seg-refs
9606Controls whether TLS variables may be accessed with offsets from the
9607TLS segment register (@code{%gs} for 32-bit, @code{%fs} for 64-bit),
9608or whether the thread base pointer must be added. Whether or not this
9609is legal depends on the operating system, and whether it maps the
9610segment to cover the entire TLS area.
9611
9612For systems that use GNU libc, the default is on.
9613@end table
9614
9615These @samp{-m} switches are supported in addition to the above
9616on AMD x86-64 processors in 64-bit environments.
9617
9618@table @gcctabopt
9619@item -m32
9620@itemx -m64
9621@opindex m32
9622@opindex m64
9623Generate code for a 32-bit or 64-bit environment.
9624The 32-bit environment sets int, long and pointer to 32 bits and
9625generates code that runs on any i386 system.
9626The 64-bit environment sets int to 32 bits and long and pointer
9627to 64 bits and generates code for AMD's x86-64 architecture. For
9628darwin only the -m64 option turns off the @option{-fno-pic} and
9629@option{-mdynamic-no-pic} options.
9630
9631@item -mno-red-zone
9632@opindex no-red-zone
9633Do not use a so called red zone for x86-64 code. The red zone is mandated
9634by the x86-64 ABI, it is a 128-byte area beyond the location of the
9635stack pointer that will not be modified by signal or interrupt handlers
9636and therefore can be used for temporary data without adjusting the stack
9637pointer. The flag @option{-mno-red-zone} disables this red zone.
9638
9639@item -mcmodel=small
9640@opindex mcmodel=small
9641Generate code for the small code model: the program and its symbols must
9642be linked in the lower 2 GB of the address space. Pointers are 64 bits.
9643Programs can be statically or dynamically linked. This is the default
9644code model.
9645
9646@item -mcmodel=kernel
9647@opindex mcmodel=kernel
9648Generate code for the kernel code model. The kernel runs in the
9649negative 2 GB of the address space.
9650This model has to be used for Linux kernel code.
9651
9652@item -mcmodel=medium
9653@opindex mcmodel=medium
9654Generate code for the medium model: The program is linked in the lower 2
9655GB of the address space but symbols can be located anywhere in the
9656address space. Programs can be statically or dynamically linked, but
9657building of shared libraries are not supported with the medium model.
9658
9659@item -mcmodel=large
9660@opindex mcmodel=large
9661Generate code for the large model: This model makes no assumptions
9662about addresses and sizes of sections. Currently GCC does not implement
9663this model.
9664@end table
9665
9666@node IA-64 Options
9667@subsection IA-64 Options
9668@cindex IA-64 Options
9669
9670These are the @samp{-m} options defined for the Intel IA-64 architecture.
9671
9672@table @gcctabopt
9673@item -mbig-endian
9674@opindex mbig-endian
9675Generate code for a big endian target. This is the default for HP-UX@.
9676
9677@item -mlittle-endian
9678@opindex mlittle-endian
9679Generate code for a little endian target. This is the default for AIX5
9680and GNU/Linux.
9681
9682@item -mgnu-as
9683@itemx -mno-gnu-as
9684@opindex mgnu-as
9685@opindex mno-gnu-as
9686Generate (or don't) code for the GNU assembler. This is the default.
9687@c Also, this is the default if the configure option @option{--with-gnu-as}
9688@c is used.
9689
9690@item -mgnu-ld
9691@itemx -mno-gnu-ld
9692@opindex mgnu-ld
9693@opindex mno-gnu-ld
9694Generate (or don't) code for the GNU linker. This is the default.
9695@c Also, this is the default if the configure option @option{--with-gnu-ld}
9696@c is used.
9697
9698@item -mno-pic
9699@opindex mno-pic
9700Generate code that does not use a global pointer register. The result
9701is not position independent code, and violates the IA-64 ABI@.
9702
9703@item -mvolatile-asm-stop
9704@itemx -mno-volatile-asm-stop
9705@opindex mvolatile-asm-stop
9706@opindex mno-volatile-asm-stop
9707Generate (or don't) a stop bit immediately before and after volatile asm
9708statements.
9709
9710@item -mregister-names
9711@itemx -mno-register-names
9712@opindex mregister-names
9713@opindex mno-register-names
9714Generate (or don't) @samp{in}, @samp{loc}, and @samp{out} register names for
9715the stacked registers. This may make assembler output more readable.
9716
9717@item -mno-sdata
9718@itemx -msdata
9719@opindex mno-sdata
9720@opindex msdata
9721Disable (or enable) optimizations that use the small data section. This may
9722be useful for working around optimizer bugs.
9723
9724@item -mconstant-gp
9725@opindex mconstant-gp
9726Generate code that uses a single constant global pointer value. This is
9727useful when compiling kernel code.
9728
9729@item -mauto-pic
9730@opindex mauto-pic
9731Generate code that is self-relocatable. This implies @option{-mconstant-gp}.
9732This is useful when compiling firmware code.
9733
9734@item -minline-float-divide-min-latency
9735@opindex minline-float-divide-min-latency
9736Generate code for inline divides of floating point values
9737using the minimum latency algorithm.
9738
9739@item -minline-float-divide-max-throughput
9740@opindex minline-float-divide-max-throughput
9741Generate code for inline divides of floating point values
9742using the maximum throughput algorithm.
9743
9744@item -minline-int-divide-min-latency
9745@opindex minline-int-divide-min-latency
9746Generate code for inline divides of integer values
9747using the minimum latency algorithm.
9748
9749@item -minline-int-divide-max-throughput
9750@opindex minline-int-divide-max-throughput
9751Generate code for inline divides of integer values
9752using the maximum throughput algorithm.
9753
9754@item -minline-sqrt-min-latency
9755@opindex minline-sqrt-min-latency
9756Generate code for inline square roots
9757using the minimum latency algorithm.
9758
9759@item -minline-sqrt-max-throughput
9760@opindex minline-sqrt-max-throughput
9761Generate code for inline square roots
9762using the maximum throughput algorithm.
9763
9764@item -mno-dwarf2-asm
9765@itemx -mdwarf2-asm
9766@opindex mno-dwarf2-asm
9767@opindex mdwarf2-asm
9768Don't (or do) generate assembler code for the DWARF2 line number debugging
9769info. This may be useful when not using the GNU assembler.
9770
9771@item -mearly-stop-bits
9772@itemx -mno-early-stop-bits
9773@opindex mearly-stop-bits
9774@opindex mno-early-stop-bits
9775Allow stop bits to be placed earlier than immediately preceding the
9776instruction that triggered the stop bit. This can improve instruction
9777scheduling, but does not always do so.
9778
9779@item -mfixed-range=@var{register-range}
9780@opindex mfixed-range
9781Generate code treating the given register range as fixed registers.
9782A fixed register is one that the register allocator can not use. This is
9783useful when compiling kernel code. A register range is specified as
9784two registers separated by a dash. Multiple register ranges can be
9785specified separated by a comma.
9786
9787@item -mtls-size=@var{tls-size}
9788@opindex mtls-size
9789Specify bit size of immediate TLS offsets. Valid values are 14, 22, and
979064.
9791
9792@item -mtune=@var{cpu-type}
9793@opindex mtune
9794Tune the instruction scheduling for a particular CPU, Valid values are
9795itanium, itanium1, merced, itanium2, and mckinley.
9796
9797@item -mt
9798@itemx -pthread
9799@opindex mt
9800@opindex pthread
9801Add support for multithreading using the POSIX threads library. This
9802option sets flags for both the preprocessor and linker. It does
9803not affect the thread safety of object code produced by the compiler or
9804that of libraries supplied with it. These are HP-UX specific flags.
9805
9806@item -milp32
9807@itemx -mlp64
9808@opindex milp32
9809@opindex mlp64
9810Generate code for a 32-bit or 64-bit environment.
9811The 32-bit environment sets int, long and pointer to 32 bits.
9812The 64-bit environment sets int to 32 bits and long and pointer
9813to 64 bits. These are HP-UX specific flags.
9814
9815@item -mno-sched-br-data-spec
9816@itemx -msched-br-data-spec
9817@opindex mno-sched-br-data-spec
9818@opindex msched-br-data-spec
9819(Dis/En)able data speculative scheduling before reload.
9820This will result in generation of the ld.a instructions and
9821the corresponding check instructions (ld.c / chk.a).
9822The default is 'disable'.
9823
9824@item -msched-ar-data-spec
9825@itemx -mno-sched-ar-data-spec
9826@opindex msched-ar-data-spec
9827@opindex mno-sched-ar-data-spec
9828(En/Dis)able data speculative scheduling after reload.
9829This will result in generation of the ld.a instructions and
9830the corresponding check instructions (ld.c / chk.a).
9831The default is 'enable'.
9832
9833@item -mno-sched-control-spec
9834@itemx -msched-control-spec
9835@opindex mno-sched-control-spec
9836@opindex msched-control-spec
9837(Dis/En)able control speculative scheduling. This feature is
9838available only during region scheduling (i.e. before reload).
9839This will result in generation of the ld.s instructions and
9840the corresponding check instructions chk.s .
9841The default is 'disable'.
9842
9843@item -msched-br-in-data-spec
9844@itemx -mno-sched-br-in-data-spec
9845@opindex msched-br-in-data-spec
9846@opindex mno-sched-br-in-data-spec
9847(En/Dis)able speculative scheduling of the instructions that
9848are dependent on the data speculative loads before reload.
9849This is effective only with @option{-msched-br-data-spec} enabled.
9850The default is 'enable'.
9851
9852@item -msched-ar-in-data-spec
9853@itemx -mno-sched-ar-in-data-spec
9854@opindex msched-ar-in-data-spec
9855@opindex mno-sched-ar-in-data-spec
9856(En/Dis)able speculative scheduling of the instructions that
9857are dependent on the data speculative loads after reload.
9858This is effective only with @option{-msched-ar-data-spec} enabled.
9859The default is 'enable'.
9860
9861@item -msched-in-control-spec
9862@itemx -mno-sched-in-control-spec
9863@opindex msched-in-control-spec
9864@opindex mno-sched-in-control-spec
9865(En/Dis)able speculative scheduling of the instructions that
9866are dependent on the control speculative loads.
9867This is effective only with @option{-msched-control-spec} enabled.
9868The default is 'enable'.
9869
9870@item -msched-ldc
9871@itemx -mno-sched-ldc
9872@opindex msched-ldc
9873@opindex mno-sched-ldc
9874(En/Dis)able use of simple data speculation checks ld.c .
9875If disabled, only chk.a instructions will be emitted to check
9876data speculative loads.
9877The default is 'enable'.
9878
9879@item -mno-sched-control-ldc
9880@itemx -msched-control-ldc
9881@opindex mno-sched-control-ldc
9882@opindex msched-control-ldc
9883(Dis/En)able use of ld.c instructions to check control speculative loads.
9884If enabled, in case of control speculative load with no speculatively
9885scheduled dependent instructions this load will be emitted as ld.sa and
9886ld.c will be used to check it.
9887The default is 'disable'.
9888
9889@item -mno-sched-spec-verbose
9890@itemx -msched-spec-verbose
9891@opindex mno-sched-spec-verbose
9892@opindex msched-spec-verbose
9893(Dis/En)able printing of the information about speculative motions.
9894
9895@item -mno-sched-prefer-non-data-spec-insns
9896@itemx -msched-prefer-non-data-spec-insns
9897@opindex mno-sched-prefer-non-data-spec-insns
9898@opindex msched-prefer-non-data-spec-insns
9899If enabled, data speculative instructions will be chosen for schedule
9900only if there are no other choices at the moment. This will make
9901the use of the data speculation much more conservative.
9902The default is 'disable'.
9903
9904@item -mno-sched-prefer-non-control-spec-insns
9905@itemx -msched-prefer-non-control-spec-insns
9906@opindex mno-sched-prefer-non-control-spec-insns
9907@opindex msched-prefer-non-control-spec-insns
9908If enabled, control speculative instructions will be chosen for schedule
9909only if there are no other choices at the moment. This will make
9910the use of the control speculation much more conservative.
9911The default is 'disable'.
9912
9913@item -mno-sched-count-spec-in-critical-path
9914@itemx -msched-count-spec-in-critical-path
9915@opindex mno-sched-count-spec-in-critical-path
9916@opindex msched-count-spec-in-critical-path
9917If enabled, speculative dependencies will be considered during
9918computation of the instructions priorities. This will make the use of the
9919speculation a bit more conservative.
9920The default is 'disable'.
9921
9922@end table
9923
9924@node M32C Options
9925@subsection M32C Options
9926@cindex M32C options
9927
9928@table @gcctabopt
9929@item -mcpu=@var{name}
9930@opindex mcpu=
9931Select the CPU for which code is generated. @var{name} may be one of
9932@samp{r8c} for the R8C/Tiny series, @samp{m16c} for the M16C (up to
9933/60) series, @samp{m32cm} for the M16C/80 series, or @samp{m32c} for
9934the M32C/80 series.
9935
9936@item -msim
9937@opindex msim
9938Specifies that the program will be run on the simulator. This causes
9939an alternate runtime library to be linked in which supports, for
9940example, file I/O. You must not use this option when generating
9941programs that will run on real hardware; you must provide your own
9942runtime library for whatever I/O functions are needed.
9943
9944@item -memregs=@var{number}
9945@opindex memregs=
9946Specifies the number of memory-based pseudo-registers GCC will use
9947during code generation. These pseudo-registers will be used like real
9948registers, so there is a tradeoff between GCC's ability to fit the
9949code into available registers, and the performance penalty of using
9950memory instead of registers. Note that all modules in a program must
9951be compiled with the same value for this option. Because of that, you
9952must not use this option with the default runtime libraries gcc
9953builds.
9954
9955@end table
9956
9957@node M32R/D Options
9958@subsection M32R/D Options
9959@cindex M32R/D options
9960
9961These @option{-m} options are defined for Renesas M32R/D architectures:
9962
9963@table @gcctabopt
9964@item -m32r2
9965@opindex m32r2
9966Generate code for the M32R/2@.
9967
9968@item -m32rx
9969@opindex m32rx
9970Generate code for the M32R/X@.
9971
9972@item -m32r
9973@opindex m32r
9974Generate code for the M32R@. This is the default.
9975
9976@item -mmodel=small
9977@opindex mmodel=small
9978Assume all objects live in the lower 16MB of memory (so that their addresses
9979can be loaded with the @code{ld24} instruction), and assume all subroutines
9980are reachable with the @code{bl} instruction.
9981This is the default.
9982
9983The addressability of a particular object can be set with the
9984@code{model} attribute.
9985
9986@item -mmodel=medium
9987@opindex mmodel=medium
9988Assume objects may be anywhere in the 32-bit address space (the compiler
9989will generate @code{seth/add3} instructions to load their addresses), and
9990assume all subroutines are reachable with the @code{bl} instruction.
9991
9992@item -mmodel=large
9993@opindex mmodel=large
9994Assume objects may be anywhere in the 32-bit address space (the compiler
9995will generate @code{seth/add3} instructions to load their addresses), and
9996assume subroutines may not be reachable with the @code{bl} instruction
9997(the compiler will generate the much slower @code{seth/add3/jl}
9998instruction sequence).
9999
10000@item -msdata=none
10001@opindex msdata=none
10002Disable use of the small data area. Variables will be put into
10003one of @samp{.data}, @samp{bss}, or @samp{.rodata} (unless the
10004@code{section} attribute has been specified).
10005This is the default.
10006
10007The small data area consists of sections @samp{.sdata} and @samp{.sbss}.
10008Objects may be explicitly put in the small data area with the
10009@code{section} attribute using one of these sections.
10010
10011@item -msdata=sdata
10012@opindex msdata=sdata
10013Put small global and static data in the small data area, but do not
10014generate special code to reference them.
10015
10016@item -msdata=use
10017@opindex msdata=use
10018Put small global and static data in the small data area, and generate
10019special instructions to reference them.
10020
10021@item -G @var{num}
10022@opindex G
10023@cindex smaller data references
10024Put global and static objects less than or equal to @var{num} bytes
10025into the small data or bss sections instead of the normal data or bss
10026sections. The default value of @var{num} is 8.
10027The @option{-msdata} option must be set to one of @samp{sdata} or @samp{use}
10028for this option to have any effect.
10029
10030All modules should be compiled with the same @option{-G @var{num}} value.
10031Compiling with different values of @var{num} may or may not work; if it
10032doesn't the linker will give an error message---incorrect code will not be
10033generated.
10034
10035@item -mdebug
10036@opindex mdebug
10037Makes the M32R specific code in the compiler display some statistics
10038that might help in debugging programs.
10039
10040@item -malign-loops
10041@opindex malign-loops
10042Align all loops to a 32-byte boundary.
10043
10044@item -mno-align-loops
10045@opindex mno-align-loops
10046Do not enforce a 32-byte alignment for loops. This is the default.
10047
10048@item -missue-rate=@var{number}
10049@opindex missue-rate=@var{number}
10050Issue @var{number} instructions per cycle. @var{number} can only be 1
10051or 2.
10052
10053@item -mbranch-cost=@var{number}
10054@opindex mbranch-cost=@var{number}
10055@var{number} can only be 1 or 2. If it is 1 then branches will be
10056preferred over conditional code, if it is 2, then the opposite will
10057apply.
10058
10059@item -mflush-trap=@var{number}
10060@opindex mflush-trap=@var{number}
10061Specifies the trap number to use to flush the cache. The default is
1006212. Valid numbers are between 0 and 15 inclusive.
10063
10064@item -mno-flush-trap
10065@opindex mno-flush-trap
10066Specifies that the cache cannot be flushed by using a trap.
10067
10068@item -mflush-func=@var{name}
10069@opindex mflush-func=@var{name}
10070Specifies the name of the operating system function to call to flush
10071the cache. The default is @emph{_flush_cache}, but a function call
10072will only be used if a trap is not available.
10073
10074@item -mno-flush-func
10075@opindex mno-flush-func
10076Indicates that there is no OS function for flushing the cache.
10077
10078@end table
10079
10080@node M680x0 Options
10081@subsection M680x0 Options
10082@cindex M680x0 options
10083
10084These are the @samp{-m} options defined for the 68000 series. The default
10085values for these options depends on which style of 68000 was selected when
10086the compiler was configured; the defaults for the most common choices are
10087given below.
10088
10089@table @gcctabopt
10090@item -m68000
10091@itemx -mc68000
10092@opindex m68000
10093@opindex mc68000
10094Generate output for a 68000. This is the default
10095when the compiler is configured for 68000-based systems.
10096
10097Use this option for microcontrollers with a 68000 or EC000 core,
10098including the 68008, 68302, 68306, 68307, 68322, 68328 and 68356.
10099
10100@item -m68020
10101@itemx -mc68020
10102@opindex m68020
10103@opindex mc68020
10104Generate output for a 68020. This is the default
10105when the compiler is configured for 68020-based systems.
10106
10107@item -m68881
10108@opindex m68881
10109Generate output containing 68881 instructions for floating point.
10110This is the default for most 68020 systems unless @option{--nfp} was
10111specified when the compiler was configured.
10112
10113@item -m68030
10114@opindex m68030
10115Generate output for a 68030. This is the default when the compiler is
10116configured for 68030-based systems.
10117
10118@item -m68040
10119@opindex m68040
10120Generate output for a 68040. This is the default when the compiler is
10121configured for 68040-based systems.
10122
10123This option inhibits the use of 68881/68882 instructions that have to be
10124emulated by software on the 68040. Use this option if your 68040 does not
10125have code to emulate those instructions.
10126
10127@item -m68060
10128@opindex m68060
10129Generate output for a 68060. This is the default when the compiler is
10130configured for 68060-based systems.
10131
10132This option inhibits the use of 68020 and 68881/68882 instructions that
10133have to be emulated by software on the 68060. Use this option if your 68060
10134does not have code to emulate those instructions.
10135
10136@item -mcpu32
10137@opindex mcpu32
10138Generate output for a CPU32. This is the default
10139when the compiler is configured for CPU32-based systems.
10140
10141Use this option for microcontrollers with a
10142CPU32 or CPU32+ core, including the 68330, 68331, 68332, 68333, 68334,
1014368336, 68340, 68341, 68349 and 68360.
10144
10145@item -m5200
10146@opindex m5200
10147Generate output for a 520X ``coldfire'' family cpu. This is the default
10148when the compiler is configured for 520X-based systems.
10149
10150Use this option for microcontroller with a 5200 core, including
10151the MCF5202, MCF5203, MCF5204 and MCF5202.
10152
10153@item -mcfv4e
10154@opindex mcfv4e
10155Generate output for a ColdFire V4e family cpu (e.g.@: 547x/548x).
10156This includes use of hardware floating point instructions.
10157
10158@item -m68020-40
10159@opindex m68020-40
10160Generate output for a 68040, without using any of the new instructions.
10161This results in code which can run relatively efficiently on either a
1016268020/68881 or a 68030 or a 68040. The generated code does use the
1016368881 instructions that are emulated on the 68040.
10164
10165@item -m68020-60
10166@opindex m68020-60
10167Generate output for a 68060, without using any of the new instructions.
10168This results in code which can run relatively efficiently on either a
1016968020/68881 or a 68030 or a 68040. The generated code does use the
1017068881 instructions that are emulated on the 68060.
10171
10172@item -msoft-float
10173@opindex msoft-float
10174Generate output containing library calls for floating point.
10175@strong{Warning:} the requisite libraries are not available for all m68k
10176targets. Normally the facilities of the machine's usual C compiler are
10177used, but this can't be done directly in cross-compilation. You must
10178make your own arrangements to provide suitable library functions for
10179cross-compilation. The embedded targets @samp{m68k-*-aout} and
10180@samp{m68k-*-coff} do provide software floating point support.
10181
10182@item -mshort
10183@opindex mshort
10184Consider type @code{int} to be 16 bits wide, like @code{short int}.
10185Additionally, parameters passed on the stack are also aligned to a
1018616-bit boundary even on targets whose API mandates promotion to 32-bit.
10187
10188@item -mnobitfield
10189@opindex mnobitfield
10190Do not use the bit-field instructions. The @option{-m68000}, @option{-mcpu32}
10191and @option{-m5200} options imply @w{@option{-mnobitfield}}.
10192
10193@item -mbitfield
10194@opindex mbitfield
10195Do use the bit-field instructions. The @option{-m68020} option implies
10196@option{-mbitfield}. This is the default if you use a configuration
10197designed for a 68020.
10198
10199@item -mrtd
10200@opindex mrtd
10201Use a different function-calling convention, in which functions
10202that take a fixed number of arguments return with the @code{rtd}
10203instruction, which pops their arguments while returning. This
10204saves one instruction in the caller since there is no need to pop
10205the arguments there.
10206
10207This calling convention is incompatible with the one normally
10208used on Unix, so you cannot use it if you need to call libraries
10209compiled with the Unix compiler.
10210
10211Also, you must provide function prototypes for all functions that
10212take variable numbers of arguments (including @code{printf});
10213otherwise incorrect code will be generated for calls to those
10214functions.
10215
10216In addition, seriously incorrect code will result if you call a
10217function with too many arguments. (Normally, extra arguments are
10218harmlessly ignored.)
10219
10220The @code{rtd} instruction is supported by the 68010, 68020, 68030,
1022168040, 68060 and CPU32 processors, but not by the 68000 or 5200.
10222
10223@item -malign-int
10224@itemx -mno-align-int
10225@opindex malign-int
10226@opindex mno-align-int
10227Control whether GCC aligns @code{int}, @code{long}, @code{long long},
10228@code{float}, @code{double}, and @code{long double} variables on a 32-bit
10229boundary (@option{-malign-int}) or a 16-bit boundary (@option{-mno-align-int}).
10230Aligning variables on 32-bit boundaries produces code that runs somewhat
10231faster on processors with 32-bit busses at the expense of more memory.
10232
10233@strong{Warning:} if you use the @option{-malign-int} switch, GCC will
10234align structures containing the above types differently than
10235most published application binary interface specifications for the m68k.
10236
10237@item -mpcrel
10238@opindex mpcrel
10239Use the pc-relative addressing mode of the 68000 directly, instead of
10240using a global offset table. At present, this option implies @option{-fpic},
10241allowing at most a 16-bit offset for pc-relative addressing. @option{-fPIC} is
10242not presently supported with @option{-mpcrel}, though this could be supported for
1024368020 and higher processors.
10244
10245@item -mno-strict-align
10246@itemx -mstrict-align
10247@opindex mno-strict-align
10248@opindex mstrict-align
10249Do not (do) assume that unaligned memory references will be handled by
10250the system.
10251
10252@item -msep-data
10253Generate code that allows the data segment to be located in a different
10254area of memory from the text segment. This allows for execute in place in
10255an environment without virtual memory management. This option implies
10256@option{-fPIC}.
10257
10258@item -mno-sep-data
10259Generate code that assumes that the data segment follows the text segment.
10260This is the default.
10261
10262@item -mid-shared-library
10263Generate code that supports shared libraries via the library ID method.
10264This allows for execute in place and shared libraries in an environment
10265without virtual memory management. This option implies @option{-fPIC}.
10266
10267@item -mno-id-shared-library
10268Generate code that doesn't assume ID based shared libraries are being used.
10269This is the default.
10270
10271@item -mshared-library-id=n
10272Specified the identification number of the ID based shared library being
10273compiled. Specifying a value of 0 will generate more compact code, specifying
10274other values will force the allocation of that number to the current
10275library but is no more space or time efficient than omitting this option.
10276
10277@end table
10278
10279@node M68hc1x Options
10280@subsection M68hc1x Options
10281@cindex M68hc1x options
10282
10283These are the @samp{-m} options defined for the 68hc11 and 68hc12
10284microcontrollers. The default values for these options depends on
10285which style of microcontroller was selected when the compiler was configured;
10286the defaults for the most common choices are given below.
10287
10288@table @gcctabopt
10289@item -m6811
10290@itemx -m68hc11
10291@opindex m6811
10292@opindex m68hc11
10293Generate output for a 68HC11. This is the default
10294when the compiler is configured for 68HC11-based systems.
10295
10296@item -m6812
10297@itemx -m68hc12
10298@opindex m6812
10299@opindex m68hc12
10300Generate output for a 68HC12. This is the default
10301when the compiler is configured for 68HC12-based systems.
10302
10303@item -m68S12
10304@itemx -m68hcs12
10305@opindex m68S12
10306@opindex m68hcs12
10307Generate output for a 68HCS12.
10308
10309@item -mauto-incdec
10310@opindex mauto-incdec
10311Enable the use of 68HC12 pre and post auto-increment and auto-decrement
10312addressing modes.
10313
10314@item -minmax
10315@itemx -nominmax
10316@opindex minmax
10317@opindex mnominmax
10318Enable the use of 68HC12 min and max instructions.
10319
10320@item -mlong-calls
10321@itemx -mno-long-calls
10322@opindex mlong-calls
10323@opindex mno-long-calls
10324Treat all calls as being far away (near). If calls are assumed to be
10325far away, the compiler will use the @code{call} instruction to
10326call a function and the @code{rtc} instruction for returning.
10327
10328@item -mshort
10329@opindex mshort
10330Consider type @code{int} to be 16 bits wide, like @code{short int}.
10331
10332@item -msoft-reg-count=@var{count}
10333@opindex msoft-reg-count
10334Specify the number of pseudo-soft registers which are used for the
10335code generation. The maximum number is 32. Using more pseudo-soft
10336register may or may not result in better code depending on the program.
10337The default is 4 for 68HC11 and 2 for 68HC12.
10338
10339@end table
10340
10341@node MCore Options
10342@subsection MCore Options
10343@cindex MCore options
10344
10345These are the @samp{-m} options defined for the Motorola M*Core
10346processors.
10347
10348@table @gcctabopt
10349
10350@item -mhardlit
10351@itemx -mno-hardlit
10352@opindex mhardlit
10353@opindex mno-hardlit
10354Inline constants into the code stream if it can be done in two
10355instructions or less.
10356
10357@item -mdiv
10358@itemx -mno-div
10359@opindex mdiv
10360@opindex mno-div
10361Use the divide instruction. (Enabled by default).
10362
10363@item -mrelax-immediate
10364@itemx -mno-relax-immediate
10365@opindex mrelax-immediate
10366@opindex mno-relax-immediate
10367Allow arbitrary sized immediates in bit operations.
10368
10369@item -mwide-bitfields
10370@itemx -mno-wide-bitfields
10371@opindex mwide-bitfields
10372@opindex mno-wide-bitfields
10373Always treat bit-fields as int-sized.
10374
10375@item -m4byte-functions
10376@itemx -mno-4byte-functions
10377@opindex m4byte-functions
10378@opindex mno-4byte-functions
10379Force all functions to be aligned to a four byte boundary.
10380
10381@item -mcallgraph-data
10382@itemx -mno-callgraph-data
10383@opindex mcallgraph-data
10384@opindex mno-callgraph-data
10385Emit callgraph information.
10386
10387@item -mslow-bytes
10388@itemx -mno-slow-bytes
10389@opindex mslow-bytes
10390@opindex mno-slow-bytes
10391Prefer word access when reading byte quantities.
10392
10393@item -mlittle-endian
10394@itemx -mbig-endian
10395@opindex mlittle-endian
10396@opindex mbig-endian
10397Generate code for a little endian target.
10398
10399@item -m210
10400@itemx -m340
10401@opindex m210
10402@opindex m340
10403Generate code for the 210 processor.
10404@end table
10405
10406@node MIPS Options
10407@subsection MIPS Options
10408@cindex MIPS options
10409
10410@table @gcctabopt
10411
10412@item -EB
10413@opindex EB
10414Generate big-endian code.
10415
10416@item -EL
10417@opindex EL
10418Generate little-endian code. This is the default for @samp{mips*el-*-*}
10419configurations.
10420
10421@item -march=@var{arch}
10422@opindex march
10423Generate code that will run on @var{arch}, which can be the name of a
10424generic MIPS ISA, or the name of a particular processor.
10425The ISA names are:
10426@samp{mips1}, @samp{mips2}, @samp{mips3}, @samp{mips4},
10427@samp{mips32}, @samp{mips32r2}, and @samp{mips64}.
10428The processor names are:
10429@samp{4kc}, @samp{4km}, @samp{4kp},
10430@samp{5kc}, @samp{5kf},
10431@samp{20kc},
10432@samp{24k}, @samp{24kc}, @samp{24kf}, @samp{24kx},
10433@samp{m4k},
10434@samp{orion},
10435@samp{r2000}, @samp{r3000}, @samp{r3900}, @samp{r4000}, @samp{r4400},
10436@samp{r4600}, @samp{r4650}, @samp{r6000}, @samp{r8000},
10437@samp{rm7000}, @samp{rm9000},
10438@samp{sb1},
10439@samp{sr71000},
10440@samp{vr4100}, @samp{vr4111}, @samp{vr4120}, @samp{vr4130}, @samp{vr4300},
10441@samp{vr5000}, @samp{vr5400} and @samp{vr5500}.
10442The special value @samp{from-abi} selects the
10443most compatible architecture for the selected ABI (that is,
10444@samp{mips1} for 32-bit ABIs and @samp{mips3} for 64-bit ABIs)@.
10445
10446In processor names, a final @samp{000} can be abbreviated as @samp{k}
10447(for example, @samp{-march=r2k}). Prefixes are optional, and
10448@samp{vr} may be written @samp{r}.
10449
10450GCC defines two macros based on the value of this option. The first
10451is @samp{_MIPS_ARCH}, which gives the name of target architecture, as
10452a string. The second has the form @samp{_MIPS_ARCH_@var{foo}},
10453where @var{foo} is the capitalized value of @samp{_MIPS_ARCH}@.
10454For example, @samp{-march=r2000} will set @samp{_MIPS_ARCH}
10455to @samp{"r2000"} and define the macro @samp{_MIPS_ARCH_R2000}.
10456
10457Note that the @samp{_MIPS_ARCH} macro uses the processor names given
10458above. In other words, it will have the full prefix and will not
10459abbreviate @samp{000} as @samp{k}. In the case of @samp{from-abi},
10460the macro names the resolved architecture (either @samp{"mips1"} or
10461@samp{"mips3"}). It names the default architecture when no
10462@option{-march} option is given.
10463
10464@item -mtune=@var{arch}
10465@opindex mtune
10466Optimize for @var{arch}. Among other things, this option controls
10467the way instructions are scheduled, and the perceived cost of arithmetic
10468operations. The list of @var{arch} values is the same as for
10469@option{-march}.
10470
10471When this option is not used, GCC will optimize for the processor
10472specified by @option{-march}. By using @option{-march} and
10473@option{-mtune} together, it is possible to generate code that will
10474run on a family of processors, but optimize the code for one
10475particular member of that family.
10476
10477@samp{-mtune} defines the macros @samp{_MIPS_TUNE} and
10478@samp{_MIPS_TUNE_@var{foo}}, which work in the same way as the
10479@samp{-march} ones described above.
10480
10481@item -mips1
10482@opindex mips1
10483Equivalent to @samp{-march=mips1}.
10484
10485@item -mips2
10486@opindex mips2
10487Equivalent to @samp{-march=mips2}.
10488
10489@item -mips3
10490@opindex mips3
10491Equivalent to @samp{-march=mips3}.
10492
10493@item -mips4
10494@opindex mips4
10495Equivalent to @samp{-march=mips4}.
10496
10497@item -mips32
10498@opindex mips32
10499Equivalent to @samp{-march=mips32}.
10500
10501@item -mips32r2
10502@opindex mips32r2
10503Equivalent to @samp{-march=mips32r2}.
10504
10505@item -mips64
10506@opindex mips64
10507Equivalent to @samp{-march=mips64}.
10508
10509@item -mips16
10510@itemx -mno-mips16
10511@opindex mips16
10512@opindex mno-mips16
10513Generate (do not generate) MIPS16 code. If GCC is targetting a
10514MIPS32 or MIPS64 architecture, it will make use of the MIPS16e ASE@.
10515
10516@item -mabi=32
10517@itemx -mabi=o64
10518@itemx -mabi=n32
10519@itemx -mabi=64
10520@itemx -mabi=eabi
10521@opindex mabi=32
10522@opindex mabi=o64
10523@opindex mabi=n32
10524@opindex mabi=64
10525@opindex mabi=eabi
10526Generate code for the given ABI@.
10527
10528Note that the EABI has a 32-bit and a 64-bit variant. GCC normally
10529generates 64-bit code when you select a 64-bit architecture, but you
10530can use @option{-mgp32} to get 32-bit code instead.
10531
10532For information about the O64 ABI, see
10533@w{@uref{http://gcc.gnu.org/projects/mipso64-abi.html}}.
10534
10535@item -mabicalls
10536@itemx -mno-abicalls
10537@opindex mabicalls
10538@opindex mno-abicalls
10539Generate (do not generate) code that is suitable for SVR4-style
10540dynamic objects. @option{-mabicalls} is the default for SVR4-based
10541systems.
10542
10543@item -mshared
10544@itemx -mno-shared
10545Generate (do not generate) code that is fully position-independent,
10546and that can therefore be linked into shared libraries. This option
10547only affects @option{-mabicalls}.
10548
10549All @option{-mabicalls} code has traditionally been position-independent,
10550regardless of options like @option{-fPIC} and @option{-fpic}. However,
10551as an extension, the GNU toolchain allows executables to use absolute
10552accesses for locally-binding symbols. It can also use shorter GP
10553initialization sequences and generate direct calls to locally-defined
10554functions. This mode is selected by @option{-mno-shared}.
10555
10556@option{-mno-shared} depends on binutils 2.16 or higher and generates
10557objects that can only be linked by the GNU linker. However, the option
10558does not affect the ABI of the final executable; it only affects the ABI
10559of relocatable objects. Using @option{-mno-shared} will generally make
10560executables both smaller and quicker.
10561
10562@option{-mshared} is the default.
10563
10564@item -mxgot
10565@itemx -mno-xgot
10566@opindex mxgot
10567@opindex mno-xgot
10568Lift (do not lift) the usual restrictions on the size of the global
10569offset table.
10570
10571GCC normally uses a single instruction to load values from the GOT@.
10572While this is relatively efficient, it will only work if the GOT
10573is smaller than about 64k. Anything larger will cause the linker
10574to report an error such as:
10575
10576@cindex relocation truncated to fit (MIPS)
10577@smallexample
10578relocation truncated to fit: R_MIPS_GOT16 foobar
10579@end smallexample
10580
10581If this happens, you should recompile your code with @option{-mxgot}.
10582It should then work with very large GOTs, although it will also be
10583less efficient, since it will take three instructions to fetch the
10584value of a global symbol.
10585
10586Note that some linkers can create multiple GOTs. If you have such a
10587linker, you should only need to use @option{-mxgot} when a single object
10588file accesses more than 64k's worth of GOT entries. Very few do.
10589
10590These options have no effect unless GCC is generating position
10591independent code.
10592
10593@item -mgp32
10594@opindex mgp32
10595Assume that general-purpose registers are 32 bits wide.
10596
10597@item -mgp64
10598@opindex mgp64
10599Assume that general-purpose registers are 64 bits wide.
10600
10601@item -mfp32
10602@opindex mfp32
10603Assume that floating-point registers are 32 bits wide.
10604
10605@item -mfp64
10606@opindex mfp64
10607Assume that floating-point registers are 64 bits wide.
10608
10609@item -mhard-float
10610@opindex mhard-float
10611Use floating-point coprocessor instructions.
10612
10613@item -msoft-float
10614@opindex msoft-float
10615Do not use floating-point coprocessor instructions. Implement
10616floating-point calculations using library calls instead.
10617
10618@item -msingle-float
10619@opindex msingle-float
10620Assume that the floating-point coprocessor only supports single-precision
10621operations.
10622
10623@itemx -mdouble-float
10624@opindex mdouble-float
10625Assume that the floating-point coprocessor supports double-precision
10626operations. This is the default.
10627
10628@itemx -mdsp
10629@itemx -mno-dsp
10630@opindex mdsp
10631@opindex mno-dsp
10632Use (do not use) the MIPS DSP ASE. @xref{MIPS DSP Built-in Functions}.
10633
10634@itemx -mpaired-single
10635@itemx -mno-paired-single
10636@opindex mpaired-single
10637@opindex mno-paired-single
10638Use (do not use) paired-single floating-point instructions.
10639@xref{MIPS Paired-Single Support}. This option can only be used
10640when generating 64-bit code and requires hardware floating-point
10641support to be enabled.
10642
10643@itemx -mips3d
10644@itemx -mno-mips3d
10645@opindex mips3d
10646@opindex mno-mips3d
10647Use (do not use) the MIPS-3D ASE@. @xref{MIPS-3D Built-in Functions}.
10648The option @option{-mips3d} implies @option{-mpaired-single}.
10649
10650@item -mlong64
10651@opindex mlong64
10652Force @code{long} types to be 64 bits wide. See @option{-mlong32} for
10653an explanation of the default and the way that the pointer size is
10654determined.
10655
10656@item -mlong32
10657@opindex mlong32
10658Force @code{long}, @code{int}, and pointer types to be 32 bits wide.
10659
10660The default size of @code{int}s, @code{long}s and pointers depends on
10661the ABI@. All the supported ABIs use 32-bit @code{int}s. The n64 ABI
10662uses 64-bit @code{long}s, as does the 64-bit EABI; the others use
1066332-bit @code{long}s. Pointers are the same size as @code{long}s,
10664or the same size as integer registers, whichever is smaller.
10665
10666@item -msym32
10667@itemx -mno-sym32
10668@opindex msym32
10669@opindex mno-sym32
10670Assume (do not assume) that all symbols have 32-bit values, regardless
10671of the selected ABI@. This option is useful in combination with
10672@option{-mabi=64} and @option{-mno-abicalls} because it allows GCC
10673to generate shorter and faster references to symbolic addresses.
10674
10675@item -G @var{num}
10676@opindex G
10677@cindex smaller data references (MIPS)
10678@cindex gp-relative references (MIPS)
10679Put global and static items less than or equal to @var{num} bytes into
10680the small data or bss section instead of the normal data or bss section.
10681This allows the data to be accessed using a single instruction.
10682
10683All modules should be compiled with the same @option{-G @var{num}}
10684value.
10685
10686@item -membedded-data
10687@itemx -mno-embedded-data
10688@opindex membedded-data
10689@opindex mno-embedded-data
10690Allocate variables to the read-only data section first if possible, then
10691next in the small data section if possible, otherwise in data. This gives
10692slightly slower code than the default, but reduces the amount of RAM required
10693when executing, and thus may be preferred for some embedded systems.
10694
10695@item -muninit-const-in-rodata
10696@itemx -mno-uninit-const-in-rodata
10697@opindex muninit-const-in-rodata
10698@opindex mno-uninit-const-in-rodata
10699Put uninitialized @code{const} variables in the read-only data section.
10700This option is only meaningful in conjunction with @option{-membedded-data}.
10701
10702@item -msplit-addresses
10703@itemx -mno-split-addresses
10704@opindex msplit-addresses
10705@opindex mno-split-addresses
10706Enable (disable) use of the @code{%hi()} and @code{%lo()} assembler
10707relocation operators. This option has been superseded by
10708@option{-mexplicit-relocs} but is retained for backwards compatibility.
10709
10710@item -mexplicit-relocs
10711@itemx -mno-explicit-relocs
10712@opindex mexplicit-relocs
10713@opindex mno-explicit-relocs
10714Use (do not use) assembler relocation operators when dealing with symbolic
10715addresses. The alternative, selected by @option{-mno-explicit-relocs},
10716is to use assembler macros instead.
10717
10718@option{-mexplicit-relocs} is the default if GCC was configured
10719to use an assembler that supports relocation operators.
10720
10721@item -mcheck-zero-division
10722@itemx -mno-check-zero-division
10723@opindex mcheck-zero-division
10724@opindex mno-check-zero-division
10725Trap (do not trap) on integer division by zero. The default is
10726@option{-mcheck-zero-division}.
10727
10728@item -mdivide-traps
10729@itemx -mdivide-breaks
10730@opindex mdivide-traps
10731@opindex mdivide-breaks
10732MIPS systems check for division by zero by generating either a
10733conditional trap or a break instruction. Using traps results in
10734smaller code, but is only supported on MIPS II and later. Also, some
10735versions of the Linux kernel have a bug that prevents trap from
10736generating the proper signal (@code{SIGFPE}). Use @option{-mdivide-traps} to
10737allow conditional traps on architectures that support them and
10738@option{-mdivide-breaks} to force the use of breaks.
10739
10740The default is usually @option{-mdivide-traps}, but this can be
10741overridden at configure time using @option{--with-divide=breaks}.
10742Divide-by-zero checks can be completely disabled using
10743@option{-mno-check-zero-division}.
10744
10745@item -mmemcpy
10746@itemx -mno-memcpy
10747@opindex mmemcpy
10748@opindex mno-memcpy
10749Force (do not force) the use of @code{memcpy()} for non-trivial block
10750moves. The default is @option{-mno-memcpy}, which allows GCC to inline
10751most constant-sized copies.
10752
10753@item -mlong-calls
10754@itemx -mno-long-calls
10755@opindex mlong-calls
10756@opindex mno-long-calls
10757Disable (do not disable) use of the @code{jal} instruction. Calling
10758functions using @code{jal} is more efficient but requires the caller
10759and callee to be in the same 256 megabyte segment.
10760
10761This option has no effect on abicalls code. The default is
10762@option{-mno-long-calls}.
10763
10764@item -mmad
10765@itemx -mno-mad
10766@opindex mmad
10767@opindex mno-mad
10768Enable (disable) use of the @code{mad}, @code{madu} and @code{mul}
10769instructions, as provided by the R4650 ISA@.
10770
10771@item -mfused-madd
10772@itemx -mno-fused-madd
10773@opindex mfused-madd
10774@opindex mno-fused-madd
10775Enable (disable) use of the floating point multiply-accumulate
10776instructions, when they are available. The default is
10777@option{-mfused-madd}.
10778
10779When multiply-accumulate instructions are used, the intermediate
10780product is calculated to infinite precision and is not subject to
10781the FCSR Flush to Zero bit. This may be undesirable in some
10782circumstances.
10783
10784@item -nocpp
10785@opindex nocpp
10786Tell the MIPS assembler to not run its preprocessor over user
10787assembler files (with a @samp{.s} suffix) when assembling them.
10788
10789@item -mfix-r4000
10790@itemx -mno-fix-r4000
10791@opindex mfix-r4000
10792@opindex mno-fix-r4000
10793Work around certain R4000 CPU errata:
10794@itemize @minus
10795@item
10796A double-word or a variable shift may give an incorrect result if executed
10797immediately after starting an integer division.
10798@item
10799A double-word or a variable shift may give an incorrect result if executed
10800while an integer multiplication is in progress.
10801@item
10802An integer division may give an incorrect result if started in a delay slot
10803of a taken branch or a jump.
10804@end itemize
10805
10806@item -mfix-r4400
10807@itemx -mno-fix-r4400
10808@opindex mfix-r4400
10809@opindex mno-fix-r4400
10810Work around certain R4400 CPU errata:
10811@itemize @minus
10812@item
10813A double-word or a variable shift may give an incorrect result if executed
10814immediately after starting an integer division.
10815@end itemize
10816
10817@item -mfix-vr4120
10818@itemx -mno-fix-vr4120
10819@opindex mfix-vr4120
10820Work around certain VR4120 errata:
10821@itemize @minus
10822@item
10823@code{dmultu} does not always produce the correct result.
10824@item
10825@code{div} and @code{ddiv} do not always produce the correct result if one
10826of the operands is negative.
10827@end itemize
10828The workarounds for the division errata rely on special functions in
10829@file{libgcc.a}. At present, these functions are only provided by
10830the @code{mips64vr*-elf} configurations.
10831
10832Other VR4120 errata require a nop to be inserted between certain pairs of
10833instructions. These errata are handled by the assembler, not by GCC itself.
10834
10835@item -mfix-vr4130
10836@opindex mfix-vr4130
10837Work around the VR4130 @code{mflo}/@code{mfhi} errata. The
10838workarounds are implemented by the assembler rather than by GCC,
10839although GCC will avoid using @code{mflo} and @code{mfhi} if the
10840VR4130 @code{macc}, @code{macchi}, @code{dmacc} and @code{dmacchi}
10841instructions are available instead.
10842
10843@item -mfix-sb1
10844@itemx -mno-fix-sb1
10845@opindex mfix-sb1
10846Work around certain SB-1 CPU core errata.
10847(This flag currently works around the SB-1 revision 2
10848``F1'' and ``F2'' floating point errata.)
10849
10850@item -mflush-func=@var{func}
10851@itemx -mno-flush-func
10852@opindex mflush-func
10853Specifies the function to call to flush the I and D caches, or to not
10854call any such function. If called, the function must take the same
10855arguments as the common @code{_flush_func()}, that is, the address of the
10856memory range for which the cache is being flushed, the size of the
10857memory range, and the number 3 (to flush both caches). The default
10858depends on the target GCC was configured for, but commonly is either
10859@samp{_flush_func} or @samp{__cpu_flush}.
10860
10861@item -mbranch-likely
10862@itemx -mno-branch-likely
10863@opindex mbranch-likely
10864@opindex mno-branch-likely
10865Enable or disable use of Branch Likely instructions, regardless of the
10866default for the selected architecture. By default, Branch Likely
10867instructions may be generated if they are supported by the selected
10868architecture. An exception is for the MIPS32 and MIPS64 architectures
10869and processors which implement those architectures; for those, Branch
10870Likely instructions will not be generated by default because the MIPS32
10871and MIPS64 architectures specifically deprecate their use.
10872
10873@item -mfp-exceptions
10874@itemx -mno-fp-exceptions
10875@opindex mfp-exceptions
10876Specifies whether FP exceptions are enabled. This affects how we schedule
10877FP instructions for some processors. The default is that FP exceptions are
10878enabled.
10879
10880For instance, on the SB-1, if FP exceptions are disabled, and we are emitting
1088164-bit code, then we can use both FP pipes. Otherwise, we can only use one
10882FP pipe.
10883
10884@item -mvr4130-align
10885@itemx -mno-vr4130-align
10886@opindex mvr4130-align
10887The VR4130 pipeline is two-way superscalar, but can only issue two
10888instructions together if the first one is 8-byte aligned. When this
10889option is enabled, GCC will align pairs of instructions that it
10890thinks should execute in parallel.
10891
10892This option only has an effect when optimizing for the VR4130.
10893It normally makes code faster, but at the expense of making it bigger.
10894It is enabled by default at optimization level @option{-O3}.
10895@end table
10896
10897@node MMIX Options
10898@subsection MMIX Options
10899@cindex MMIX Options
10900
10901These options are defined for the MMIX:
10902
10903@table @gcctabopt
10904@item -mlibfuncs
10905@itemx -mno-libfuncs
10906@opindex mlibfuncs
10907@opindex mno-libfuncs
10908Specify that intrinsic library functions are being compiled, passing all
10909values in registers, no matter the size.
10910
10911@item -mepsilon
10912@itemx -mno-epsilon
10913@opindex mepsilon
10914@opindex mno-epsilon
10915Generate floating-point comparison instructions that compare with respect
10916to the @code{rE} epsilon register.
10917
10918@item -mabi=mmixware
10919@itemx -mabi=gnu
10920@opindex mabi-mmixware
10921@opindex mabi=gnu
10922Generate code that passes function parameters and return values that (in
10923the called function) are seen as registers @code{$0} and up, as opposed to
10924the GNU ABI which uses global registers @code{$231} and up.
10925
10926@item -mzero-extend
10927@itemx -mno-zero-extend
10928@opindex mzero-extend
10929@opindex mno-zero-extend
10930When reading data from memory in sizes shorter than 64 bits, use (do not
10931use) zero-extending load instructions by default, rather than
10932sign-extending ones.
10933
10934@item -mknuthdiv
10935@itemx -mno-knuthdiv
10936@opindex mknuthdiv
10937@opindex mno-knuthdiv
10938Make the result of a division yielding a remainder have the same sign as
10939the divisor. With the default, @option{-mno-knuthdiv}, the sign of the
10940remainder follows the sign of the dividend. Both methods are
10941arithmetically valid, the latter being almost exclusively used.
10942
10943@item -mtoplevel-symbols
10944@itemx -mno-toplevel-symbols
10945@opindex mtoplevel-symbols
10946@opindex mno-toplevel-symbols
10947Prepend (do not prepend) a @samp{:} to all global symbols, so the assembly
10948code can be used with the @code{PREFIX} assembly directive.
10949
10950@item -melf
10951@opindex melf
10952Generate an executable in the ELF format, rather than the default
10953@samp{mmo} format used by the @command{mmix} simulator.
10954
10955@item -mbranch-predict
10956@itemx -mno-branch-predict
10957@opindex mbranch-predict
10958@opindex mno-branch-predict
10959Use (do not use) the probable-branch instructions, when static branch
10960prediction indicates a probable branch.
10961
10962@item -mbase-addresses
10963@itemx -mno-base-addresses
10964@opindex mbase-addresses
10965@opindex mno-base-addresses
10966Generate (do not generate) code that uses @emph{base addresses}. Using a
10967base address automatically generates a request (handled by the assembler
10968and the linker) for a constant to be set up in a global register. The
10969register is used for one or more base address requests within the range 0
10970to 255 from the value held in the register. The generally leads to short
10971and fast code, but the number of different data items that can be
10972addressed is limited. This means that a program that uses lots of static
10973data may require @option{-mno-base-addresses}.
10974
10975@item -msingle-exit
10976@itemx -mno-single-exit
10977@opindex msingle-exit
10978@opindex mno-single-exit
10979Force (do not force) generated code to have a single exit point in each
10980function.
10981@end table
10982
10983@node MN10300 Options
10984@subsection MN10300 Options
10985@cindex MN10300 options
10986
10987These @option{-m} options are defined for Matsushita MN10300 architectures:
10988
10989@table @gcctabopt
10990@item -mmult-bug
10991@opindex mmult-bug
10992Generate code to avoid bugs in the multiply instructions for the MN10300
10993processors. This is the default.
10994
10995@item -mno-mult-bug
10996@opindex mno-mult-bug
10997Do not generate code to avoid bugs in the multiply instructions for the
10998MN10300 processors.
10999
11000@item -mam33
11001@opindex mam33
11002Generate code which uses features specific to the AM33 processor.
11003
11004@item -mno-am33
11005@opindex mno-am33
11006Do not generate code which uses features specific to the AM33 processor. This
11007is the default.
11008
11009@item -mreturn-pointer-on-d0
11010@opindex mreturn-pointer-on-d0
11011When generating a function which returns a pointer, return the pointer
11012in both @code{a0} and @code{d0}. Otherwise, the pointer is returned
11013only in a0, and attempts to call such functions without a prototype
11014would result in errors. Note that this option is on by default; use
11015@option{-mno-return-pointer-on-d0} to disable it.
11016
11017@item -mno-crt0
11018@opindex mno-crt0
11019Do not link in the C run-time initialization object file.
11020
11021@item -mrelax
11022@opindex mrelax
11023Indicate to the linker that it should perform a relaxation optimization pass
11024to shorten branches, calls and absolute memory addresses. This option only
11025has an effect when used on the command line for the final link step.
11026
11027This option makes symbolic debugging impossible.
11028@end table
11029
11030@node MT Options
11031@subsection MT Options
11032@cindex MT options
11033
11034These @option{-m} options are defined for Morpho MT architectures:
11035
11036@table @gcctabopt
11037
11038@item -march=@var{cpu-type}
11039@opindex march
11040Generate code that will run on @var{cpu-type}, which is the name of a system
11041representing a certain processor type. Possible values for
11042@var{cpu-type} are @samp{ms1-64-001}, @samp{ms1-16-002},
11043@samp{ms1-16-003} and @samp{ms2}.
11044
11045When this option is not used, the default is @option{-march=ms1-16-002}.
11046
11047@item -mbacc
11048@opindex mbacc
11049Use byte loads and stores when generating code.
11050
11051@item -mno-bacc
11052@opindex mno-bacc
11053Do not use byte loads and stores when generating code.
11054
11055@item -msim
11056@opindex msim
11057Use simulator runtime
11058
11059@item -mno-crt0
11060@opindex mno-crt0
11061Do not link in the C run-time initialization object file
11062@file{crti.o}. Other run-time initialization and termination files
11063such as @file{startup.o} and @file{exit.o} are still included on the
11064linker command line.
11065
11066@end table
11067
11068@node PDP-11 Options
11069@subsection PDP-11 Options
11070@cindex PDP-11 Options
11071
11072These options are defined for the PDP-11:
11073
11074@table @gcctabopt
11075@item -mfpu
11076@opindex mfpu
11077Use hardware FPP floating point. This is the default. (FIS floating
11078point on the PDP-11/40 is not supported.)
11079
11080@item -msoft-float
11081@opindex msoft-float
11082Do not use hardware floating point.
11083
11084@item -mac0
11085@opindex mac0
11086Return floating-point results in ac0 (fr0 in Unix assembler syntax).
11087
11088@item -mno-ac0
11089@opindex mno-ac0
11090Return floating-point results in memory. This is the default.
11091
11092@item -m40
11093@opindex m40
11094Generate code for a PDP-11/40.
11095
11096@item -m45
11097@opindex m45
11098Generate code for a PDP-11/45. This is the default.
11099
11100@item -m10
11101@opindex m10
11102Generate code for a PDP-11/10.
11103
11104@item -mbcopy-builtin
11105@opindex bcopy-builtin
11106Use inline @code{movmemhi} patterns for copying memory. This is the
11107default.
11108
11109@item -mbcopy
11110@opindex mbcopy
11111Do not use inline @code{movmemhi} patterns for copying memory.
11112
11113@item -mint16
11114@itemx -mno-int32
11115@opindex mint16
11116@opindex mno-int32
11117Use 16-bit @code{int}. This is the default.
11118
11119@item -mint32
11120@itemx -mno-int16
11121@opindex mint32
11122@opindex mno-int16
11123Use 32-bit @code{int}.
11124
11125@item -mfloat64
11126@itemx -mno-float32
11127@opindex mfloat64
11128@opindex mno-float32
11129Use 64-bit @code{float}. This is the default.
11130
11131@item -mfloat32
11132@itemx -mno-float64
11133@opindex mfloat32
11134@opindex mno-float64
11135Use 32-bit @code{float}.
11136
11137@item -mabshi
11138@opindex mabshi
11139Use @code{abshi2} pattern. This is the default.
11140
11141@item -mno-abshi
11142@opindex mno-abshi
11143Do not use @code{abshi2} pattern.
11144
11145@item -mbranch-expensive
11146@opindex mbranch-expensive
11147Pretend that branches are expensive. This is for experimenting with
11148code generation only.
11149
11150@item -mbranch-cheap
11151@opindex mbranch-cheap
11152Do not pretend that branches are expensive. This is the default.
11153
11154@item -msplit
11155@opindex msplit
11156Generate code for a system with split I&D@.
11157
11158@item -mno-split
11159@opindex mno-split
11160Generate code for a system without split I&D@. This is the default.
11161
11162@item -munix-asm
11163@opindex munix-asm
11164Use Unix assembler syntax. This is the default when configured for
11165@samp{pdp11-*-bsd}.
11166
11167@item -mdec-asm
11168@opindex mdec-asm
11169Use DEC assembler syntax. This is the default when configured for any
11170PDP-11 target other than @samp{pdp11-*-bsd}.
11171@end table
11172
11173@node PowerPC Options
11174@subsection PowerPC Options
11175@cindex PowerPC options
11176
11177These are listed under @xref{RS/6000 and PowerPC Options}.
11178
11179@node RS/6000 and PowerPC Options
11180@subsection IBM RS/6000 and PowerPC Options
11181@cindex RS/6000 and PowerPC Options
11182@cindex IBM RS/6000 and PowerPC Options
11183
11184These @samp{-m} options are defined for the IBM RS/6000 and PowerPC:
11185@table @gcctabopt
11186@item -mpower
11187@itemx -mno-power
11188@itemx -mpower2
11189@itemx -mno-power2
11190@itemx -mpowerpc
11191@itemx -mno-powerpc
11192@itemx -mpowerpc-gpopt
11193@itemx -mno-powerpc-gpopt
11194@itemx -mpowerpc-gfxopt
11195@itemx -mno-powerpc-gfxopt
11196@itemx -mpowerpc64
11197@itemx -mno-powerpc64
11198@itemx -mmfcrf
11199@itemx -mno-mfcrf
11200@itemx -mpopcntb
11201@itemx -mno-popcntb
11202@itemx -mfprnd
11203@itemx -mno-fprnd
11204@opindex mpower
11205@opindex mno-power
11206@opindex mpower2
11207@opindex mno-power2
11208@opindex mpowerpc
11209@opindex mno-powerpc
11210@opindex mpowerpc-gpopt
11211@opindex mno-powerpc-gpopt
11212@opindex mpowerpc-gfxopt
11213@opindex mno-powerpc-gfxopt
11214@opindex mpowerpc64
11215@opindex mno-powerpc64
11216@opindex mmfcrf
11217@opindex mno-mfcrf
11218@opindex mpopcntb
11219@opindex mno-popcntb
11220@opindex mfprnd
11221@opindex mno-fprnd
11222GCC supports two related instruction set architectures for the
11223RS/6000 and PowerPC@. The @dfn{POWER} instruction set are those
11224instructions supported by the @samp{rios} chip set used in the original
11225RS/6000 systems and the @dfn{PowerPC} instruction set is the
11226architecture of the Freescale MPC5xx, MPC6xx, MPC8xx microprocessors, and
11227the IBM 4xx, 6xx, and follow-on microprocessors.
11228
11229Neither architecture is a subset of the other. However there is a
11230large common subset of instructions supported by both. An MQ
11231register is included in processors supporting the POWER architecture.
11232
11233You use these options to specify which instructions are available on the
11234processor you are using. The default value of these options is
11235determined when configuring GCC@. Specifying the
11236@option{-mcpu=@var{cpu_type}} overrides the specification of these
11237options. We recommend you use the @option{-mcpu=@var{cpu_type}} option
11238rather than the options listed above.
11239
11240The @option{-mpower} option allows GCC to generate instructions that
11241are found only in the POWER architecture and to use the MQ register.
11242Specifying @option{-mpower2} implies @option{-power} and also allows GCC
11243to generate instructions that are present in the POWER2 architecture but
11244not the original POWER architecture.
11245
11246The @option{-mpowerpc} option allows GCC to generate instructions that
11247are found only in the 32-bit subset of the PowerPC architecture.
11248Specifying @option{-mpowerpc-gpopt} implies @option{-mpowerpc} and also allows
11249GCC to use the optional PowerPC architecture instructions in the
11250General Purpose group, including floating-point square root. Specifying
11251@option{-mpowerpc-gfxopt} implies @option{-mpowerpc} and also allows GCC to
11252use the optional PowerPC architecture instructions in the Graphics
11253group, including floating-point select.
11254
11255The @option{-mmfcrf} option allows GCC to generate the move from
11256condition register field instruction implemented on the POWER4
11257processor and other processors that support the PowerPC V2.01
11258architecture.
11259The @option{-mpopcntb} option allows GCC to generate the popcount and
11260double precision FP reciprocal estimate instruction implemented on the
11261POWER5 processor and other processors that support the PowerPC V2.02
11262architecture.
11263The @option{-mfprnd} option allows GCC to generate the FP round to
11264integer instructions implemented on the POWER5+ processor and other
11265processors that support the PowerPC V2.03 architecture.
11266
11267The @option{-mpowerpc64} option allows GCC to generate the additional
1126864-bit instructions that are found in the full PowerPC64 architecture
11269and to treat GPRs as 64-bit, doubleword quantities. GCC defaults to
11270@option{-mno-powerpc64}.
11271
11272If you specify both @option{-mno-power} and @option{-mno-powerpc}, GCC
11273will use only the instructions in the common subset of both
11274architectures plus some special AIX common-mode calls, and will not use
11275the MQ register. Specifying both @option{-mpower} and @option{-mpowerpc}
11276permits GCC to use any instruction from either architecture and to
11277allow use of the MQ register; specify this for the Motorola MPC601.
11278
11279@item -mnew-mnemonics
11280@itemx -mold-mnemonics
11281@opindex mnew-mnemonics
11282@opindex mold-mnemonics
11283Select which mnemonics to use in the generated assembler code. With
11284@option{-mnew-mnemonics}, GCC uses the assembler mnemonics defined for
11285the PowerPC architecture. With @option{-mold-mnemonics} it uses the
11286assembler mnemonics defined for the POWER architecture. Instructions
11287defined in only one architecture have only one mnemonic; GCC uses that
11288mnemonic irrespective of which of these options is specified.
11289
11290GCC defaults to the mnemonics appropriate for the architecture in
11291use. Specifying @option{-mcpu=@var{cpu_type}} sometimes overrides the
11292value of these option. Unless you are building a cross-compiler, you
11293should normally not specify either @option{-mnew-mnemonics} or
11294@option{-mold-mnemonics}, but should instead accept the default.
11295
11296@item -mcpu=@var{cpu_type}
11297@opindex mcpu
11298Set architecture type, register usage, choice of mnemonics, and
11299instruction scheduling parameters for machine type @var{cpu_type}.
11300Supported values for @var{cpu_type} are @samp{401}, @samp{403},
11301@samp{405}, @samp{405fp}, @samp{440}, @samp{440fp}, @samp{505},
11302@samp{601}, @samp{602}, @samp{603}, @samp{603e}, @samp{604},
11303@samp{604e}, @samp{620}, @samp{630}, @samp{740}, @samp{7400},
11304@samp{7450}, @samp{750}, @samp{801}, @samp{821}, @samp{823},
11305@samp{860}, @samp{970}, @samp{8540}, @samp{ec603e}, @samp{G3},
11306@samp{G4}, @samp{G5}, @samp{power}, @samp{power2}, @samp{power3},
11307@samp{power4}, @samp{power5}, @samp{power5+}, @samp{power6},
11308@samp{common}, @samp{powerpc}, @samp{powerpc64},
11309@samp{rios}, @samp{rios1}, @samp{rios2}, @samp{rsc}, and @samp{rs64}.
11310
11311@option{-mcpu=common} selects a completely generic processor. Code
11312generated under this option will run on any POWER or PowerPC processor.
11313GCC will use only the instructions in the common subset of both
11314architectures, and will not use the MQ register. GCC assumes a generic
11315processor model for scheduling purposes.
11316
11317@option{-mcpu=power}, @option{-mcpu=power2}, @option{-mcpu=powerpc}, and
11318@option{-mcpu=powerpc64} specify generic POWER, POWER2, pure 32-bit
11319PowerPC (i.e., not MPC601), and 64-bit PowerPC architecture machine
11320types, with an appropriate, generic processor model assumed for
11321scheduling purposes.
11322
11323The other options specify a specific processor. Code generated under
11324those options will run best on that processor, and may not run at all on
11325others.
11326
11327The @option{-mcpu} options automatically enable or disable the
11328following options: @option{-maltivec}, @option{-mfprnd},
11329@option{-mhard-float}, @option{-mmfcrf}, @option{-mmultiple},
11330@option{-mnew-mnemonics}, @option{-mpopcntb}, @option{-mpower},
11331@option{-mpower2}, @option{-mpowerpc64}, @option{-mpowerpc-gpopt},
11332@option{-mpowerpc-gfxopt}, @option{-mstring}, @option{-mmulhw}, @option{-mdlmzb}.
11333The particular options
11334set for any particular CPU will vary between compiler versions,
11335depending on what setting seems to produce optimal code for that CPU;
11336it doesn't necessarily reflect the actual hardware's capabilities. If
11337you wish to set an individual option to a particular value, you may
11338specify it after the @option{-mcpu} option, like @samp{-mcpu=970
11339-mno-altivec}.
11340
11341On AIX, the @option{-maltivec} and @option{-mpowerpc64} options are
11342not enabled or disabled by the @option{-mcpu} option at present because
11343AIX does not have full support for these options. You may still
11344enable or disable them individually if you're sure it'll work in your
11345environment.
11346
11347@item -mtune=@var{cpu_type}
11348@opindex mtune
11349Set the instruction scheduling parameters for machine type
11350@var{cpu_type}, but do not set the architecture type, register usage, or
11351choice of mnemonics, as @option{-mcpu=@var{cpu_type}} would. The same
11352values for @var{cpu_type} are used for @option{-mtune} as for
11353@option{-mcpu}. If both are specified, the code generated will use the
11354architecture, registers, and mnemonics set by @option{-mcpu}, but the
11355scheduling parameters set by @option{-mtune}.
11356
11357@item -mswdiv
11358@itemx -mno-swdiv
11359@opindex mswdiv
11360@opindex mno-swdiv
11361Generate code to compute division as reciprocal estimate and iterative
11362refinement, creating opportunities for increased throughput. This
11363feature requires: optional PowerPC Graphics instruction set for single
11364precision and FRE instruction for double precision, assuming divides
11365cannot generate user-visible traps, and the domain values not include
11366Infinities, denormals or zero denominator.
11367
11368@item -maltivec
11369@itemx -mno-altivec
11370@opindex maltivec
11371@opindex mno-altivec
11372Generate code that uses (does not use) AltiVec instructions, and also
11373enable the use of built-in functions that allow more direct access to
11374the AltiVec instruction set. You may also need to set
11375@option{-mabi=altivec} to adjust the current ABI with AltiVec ABI
11376enhancements.
11377
11378@item -mvrsave
11379@item -mno-vrsave
11380@opindex mvrsave
11381@opindex mno-vrsave
11382Generate VRSAVE instructions when generating AltiVec code.
11383
11384@item -msecure-plt
11385@opindex msecure-plt
11386Generate code that allows ld and ld.so to build executables and shared
11387libraries with non-exec .plt and .got sections. This is a PowerPC
1138832-bit SYSV ABI option.
11389
11390@item -mbss-plt
11391@opindex mbss-plt
11392Generate code that uses a BSS .plt section that ld.so fills in, and
11393requires .plt and .got sections that are both writable and executable.
11394This is a PowerPC 32-bit SYSV ABI option.
11395
11396@item -misel
11397@itemx -mno-isel
11398@opindex misel
11399@opindex mno-isel
11400This switch enables or disables the generation of ISEL instructions.
11401
11402@item -misel=@var{yes/no}
11403This switch has been deprecated. Use @option{-misel} and
11404@option{-mno-isel} instead.
11405
11406@item -mspe
11407@itemx -mno-spe
11408@opindex mspe
11409@opindex mno-spe
11410This switch enables or disables the generation of SPE simd
11411instructions.
11412
11413@item -mspe=@var{yes/no}
11414This option has been deprecated. Use @option{-mspe} and
11415@option{-mno-spe} instead.
11416
11417@item -mfloat-gprs=@var{yes/single/double/no}
11418@itemx -mfloat-gprs
11419@opindex mfloat-gprs
11420This switch enables or disables the generation of floating point
11421operations on the general purpose registers for architectures that
11422support it.
11423
11424The argument @var{yes} or @var{single} enables the use of
11425single-precision floating point operations.
11426
11427The argument @var{double} enables the use of single and
11428double-precision floating point operations.
11429
11430The argument @var{no} disables floating point operations on the
11431general purpose registers.
11432
11433This option is currently only available on the MPC854x.
11434
11435@item -m32
11436@itemx -m64
11437@opindex m32
11438@opindex m64
11439Generate code for 32-bit or 64-bit environments of Darwin and SVR4
11440targets (including GNU/Linux). The 32-bit environment sets int, long
11441and pointer to 32 bits and generates code that runs on any PowerPC
11442variant. The 64-bit environment sets int to 32 bits and long and
11443pointer to 64 bits, and generates code for PowerPC64, as for
11444@option{-mpowerpc64}.
11445
11446@item -mfull-toc
11447@itemx -mno-fp-in-toc
11448@itemx -mno-sum-in-toc
11449@itemx -mminimal-toc
11450@opindex mfull-toc
11451@opindex mno-fp-in-toc
11452@opindex mno-sum-in-toc
11453@opindex mminimal-toc
11454Modify generation of the TOC (Table Of Contents), which is created for
11455every executable file. The @option{-mfull-toc} option is selected by
11456default. In that case, GCC will allocate at least one TOC entry for
11457each unique non-automatic variable reference in your program. GCC
11458will also place floating-point constants in the TOC@. However, only
1145916,384 entries are available in the TOC@.
11460
11461If you receive a linker error message that saying you have overflowed
11462the available TOC space, you can reduce the amount of TOC space used
11463with the @option{-mno-fp-in-toc} and @option{-mno-sum-in-toc} options.
11464@option{-mno-fp-in-toc} prevents GCC from putting floating-point
11465constants in the TOC and @option{-mno-sum-in-toc} forces GCC to
11466generate code to calculate the sum of an address and a constant at
11467run-time instead of putting that sum into the TOC@. You may specify one
11468or both of these options. Each causes GCC to produce very slightly
11469slower and larger code at the expense of conserving TOC space.
11470
11471If you still run out of space in the TOC even when you specify both of
11472these options, specify @option{-mminimal-toc} instead. This option causes
11473GCC to make only one TOC entry for every file. When you specify this
11474option, GCC will produce code that is slower and larger but which
11475uses extremely little TOC space. You may wish to use this option
11476only on files that contain less frequently executed code.
11477
11478@item -maix64
11479@itemx -maix32
11480@opindex maix64
11481@opindex maix32
11482Enable 64-bit AIX ABI and calling convention: 64-bit pointers, 64-bit
11483@code{long} type, and the infrastructure needed to support them.
11484Specifying @option{-maix64} implies @option{-mpowerpc64} and
11485@option{-mpowerpc}, while @option{-maix32} disables the 64-bit ABI and
11486implies @option{-mno-powerpc64}. GCC defaults to @option{-maix32}.
11487
11488@item -mxl-compat
11489@itemx -mno-xl-compat
11490@opindex mxl-compat
11491@opindex mno-xl-compat
11492Produce code that conforms more closely to IBM XL compiler semantics
11493when using AIX-compatible ABI. Pass floating-point arguments to
11494prototyped functions beyond the register save area (RSA) on the stack
11495in addition to argument FPRs. Do not assume that most significant
11496double in 128-bit long double value is properly rounded when comparing
11497values and converting to double. Use XL symbol names for long double
11498support routines.
11499
11500The AIX calling convention was extended but not initially documented to
11501handle an obscure K&R C case of calling a function that takes the
11502address of its arguments with fewer arguments than declared. IBM XL
11503compilers access floating point arguments which do not fit in the
11504RSA from the stack when a subroutine is compiled without
11505optimization. Because always storing floating-point arguments on the
11506stack is inefficient and rarely needed, this option is not enabled by
11507default and only is necessary when calling subroutines compiled by IBM
11508XL compilers without optimization.
11509
11510@item -mpe
11511@opindex mpe
11512Support @dfn{IBM RS/6000 SP} @dfn{Parallel Environment} (PE)@. Link an
11513application written to use message passing with special startup code to
11514enable the application to run. The system must have PE installed in the
11515standard location (@file{/usr/lpp/ppe.poe/}), or the @file{specs} file
11516must be overridden with the @option{-specs=} option to specify the
11517appropriate directory location. The Parallel Environment does not
11518support threads, so the @option{-mpe} option and the @option{-pthread}
11519option are incompatible.
11520
11521@item -malign-natural
11522@itemx -malign-power
11523@opindex malign-natural
11524@opindex malign-power
11525On AIX, 32-bit Darwin, and 64-bit PowerPC GNU/Linux, the option
11526@option{-malign-natural} overrides the ABI-defined alignment of larger
11527types, such as floating-point doubles, on their natural size-based boundary.
11528The option @option{-malign-power} instructs GCC to follow the ABI-specified
11529alignment rules. GCC defaults to the standard alignment defined in the ABI@.
11530
11531On 64-bit Darwin, natural alignment is the default, and @option{-malign-power}
11532is not supported.
11533
11534@item -msoft-float
11535@itemx -mhard-float
11536@opindex msoft-float
11537@opindex mhard-float
11538Generate code that does not use (uses) the floating-point register set.
11539Software floating point emulation is provided if you use the
11540@option{-msoft-float} option, and pass the option to GCC when linking.
11541
11542@item -mmultiple
11543@itemx -mno-multiple
11544@opindex mmultiple
11545@opindex mno-multiple
11546Generate code that uses (does not use) the load multiple word
11547instructions and the store multiple word instructions. These
11548instructions are generated by default on POWER systems, and not
11549generated on PowerPC systems. Do not use @option{-mmultiple} on little
11550endian PowerPC systems, since those instructions do not work when the
11551processor is in little endian mode. The exceptions are PPC740 and
11552PPC750 which permit the instructions usage in little endian mode.
11553
11554@item -mstring
11555@itemx -mno-string
11556@opindex mstring
11557@opindex mno-string
11558Generate code that uses (does not use) the load string instructions
11559and the store string word instructions to save multiple registers and
11560do small block moves. These instructions are generated by default on
11561POWER systems, and not generated on PowerPC systems. Do not use
11562@option{-mstring} on little endian PowerPC systems, since those
11563instructions do not work when the processor is in little endian mode.
11564The exceptions are PPC740 and PPC750 which permit the instructions
11565usage in little endian mode.
11566
11567@item -mupdate
11568@itemx -mno-update
11569@opindex mupdate
11570@opindex mno-update
11571Generate code that uses (does not use) the load or store instructions
11572that update the base register to the address of the calculated memory
11573location. These instructions are generated by default. If you use
11574@option{-mno-update}, there is a small window between the time that the
11575stack pointer is updated and the address of the previous frame is
11576stored, which means code that walks the stack frame across interrupts or
11577signals may get corrupted data.
11578
11579@item -mfused-madd
11580@itemx -mno-fused-madd
11581@opindex mfused-madd
11582@opindex mno-fused-madd
11583Generate code that uses (does not use) the floating point multiply and
11584accumulate instructions. These instructions are generated by default if
11585hardware floating is used.
11586
11587@item -mmulhw
11588@itemx -mno-mulhw
11589@opindex mmulhw
11590@opindex mno-mulhw
11591Generate code that uses (does not use) the half-word multiply and
11592multiply-accumulate instructions on the IBM 405 and 440 processors.
11593These instructions are generated by default when targetting those
11594processors.
11595
11596@item -mdlmzb
11597@itemx -mno-dlmzb
11598@opindex mdlmzb
11599@opindex mno-dlmzb
11600Generate code that uses (does not use) the string-search @samp{dlmzb}
11601instruction on the IBM 405 and 440 processors. This instruction is
11602generated by default when targetting those processors.
11603
11604@item -mno-bit-align
11605@itemx -mbit-align
11606@opindex mno-bit-align
11607@opindex mbit-align
11608On System V.4 and embedded PowerPC systems do not (do) force structures
11609and unions that contain bit-fields to be aligned to the base type of the
11610bit-field.
11611
11612For example, by default a structure containing nothing but 8
11613@code{unsigned} bit-fields of length 1 would be aligned to a 4 byte
11614boundary and have a size of 4 bytes. By using @option{-mno-bit-align},
11615the structure would be aligned to a 1 byte boundary and be one byte in
11616size.
11617
11618@item -mno-strict-align
11619@itemx -mstrict-align
11620@opindex mno-strict-align
11621@opindex mstrict-align
11622On System V.4 and embedded PowerPC systems do not (do) assume that
11623unaligned memory references will be handled by the system.
11624
11625@item -mrelocatable
11626@itemx -mno-relocatable
11627@opindex mrelocatable
11628@opindex mno-relocatable
11629On embedded PowerPC systems generate code that allows (does not allow)
11630the program to be relocated to a different address at runtime. If you
11631use @option{-mrelocatable} on any module, all objects linked together must
11632be compiled with @option{-mrelocatable} or @option{-mrelocatable-lib}.
11633
11634@item -mrelocatable-lib
11635@itemx -mno-relocatable-lib
11636@opindex mrelocatable-lib
11637@opindex mno-relocatable-lib
11638On embedded PowerPC systems generate code that allows (does not allow)
11639the program to be relocated to a different address at runtime. Modules
11640compiled with @option{-mrelocatable-lib} can be linked with either modules
11641compiled without @option{-mrelocatable} and @option{-mrelocatable-lib} or
11642with modules compiled with the @option{-mrelocatable} options.
11643
11644@item -mno-toc
11645@itemx -mtoc
11646@opindex mno-toc
11647@opindex mtoc
11648On System V.4 and embedded PowerPC systems do not (do) assume that
11649register 2 contains a pointer to a global area pointing to the addresses
11650used in the program.
11651
11652@item -mlittle
11653@itemx -mlittle-endian
11654@opindex mlittle
11655@opindex mlittle-endian
11656On System V.4 and embedded PowerPC systems compile code for the
11657processor in little endian mode. The @option{-mlittle-endian} option is
11658the same as @option{-mlittle}.
11659
11660@item -mbig
11661@itemx -mbig-endian
11662@opindex mbig
11663@opindex mbig-endian
11664On System V.4 and embedded PowerPC systems compile code for the
11665processor in big endian mode. The @option{-mbig-endian} option is
11666the same as @option{-mbig}.
11667
11668@item -mdynamic-no-pic
11669@opindex mdynamic-no-pic
11670On Darwin and Mac OS X systems, compile code so that it is not
11671relocatable, but that its external references are relocatable. The
11672resulting code is suitable for applications, but not shared
11673libraries.
11674
11675@item -mprioritize-restricted-insns=@var{priority}
11676@opindex mprioritize-restricted-insns
11677This option controls the priority that is assigned to
11678dispatch-slot restricted instructions during the second scheduling
11679pass. The argument @var{priority} takes the value @var{0/1/2} to assign
11680@var{no/highest/second-highest} priority to dispatch slot restricted
11681instructions.
11682
11683@item -msched-costly-dep=@var{dependence_type}
11684@opindex msched-costly-dep
11685This option controls which dependences are considered costly
11686by the target during instruction scheduling. The argument
11687@var{dependence_type} takes one of the following values:
11688@var{no}: no dependence is costly,
11689@var{all}: all dependences are costly,
11690@var{true_store_to_load}: a true dependence from store to load is costly,
11691@var{store_to_load}: any dependence from store to load is costly,
11692@var{number}: any dependence which latency >= @var{number} is costly.
11693
11694@item -minsert-sched-nops=@var{scheme}
11695@opindex minsert-sched-nops
11696This option controls which nop insertion scheme will be used during
11697the second scheduling pass. The argument @var{scheme} takes one of the
11698following values:
11699@var{no}: Don't insert nops.
11700@var{pad}: Pad with nops any dispatch group which has vacant issue slots,
11701according to the scheduler's grouping.
11702@var{regroup_exact}: Insert nops to force costly dependent insns into
11703separate groups. Insert exactly as many nops as needed to force an insn
11704to a new group, according to the estimated processor grouping.
11705@var{number}: Insert nops to force costly dependent insns into
11706separate groups. Insert @var{number} nops to force an insn to a new group.
11707
11708@item -mcall-sysv
11709@opindex mcall-sysv
11710On System V.4 and embedded PowerPC systems compile code using calling
11711conventions that adheres to the March 1995 draft of the System V
11712Application Binary Interface, PowerPC processor supplement. This is the
11713default unless you configured GCC using @samp{powerpc-*-eabiaix}.
11714
11715@item -mcall-sysv-eabi
11716@opindex mcall-sysv-eabi
11717Specify both @option{-mcall-sysv} and @option{-meabi} options.
11718
11719@item -mcall-sysv-noeabi
11720@opindex mcall-sysv-noeabi
11721Specify both @option{-mcall-sysv} and @option{-mno-eabi} options.
11722
11723@item -mcall-solaris
11724@opindex mcall-solaris
11725On System V.4 and embedded PowerPC systems compile code for the Solaris
11726operating system.
11727
11728@item -mcall-linux
11729@opindex mcall-linux
11730On System V.4 and embedded PowerPC systems compile code for the
11731Linux-based GNU system.
11732
11733@item -mcall-gnu
11734@opindex mcall-gnu
11735On System V.4 and embedded PowerPC systems compile code for the
11736Hurd-based GNU system.
11737
11738@item -mcall-netbsd
11739@opindex mcall-netbsd
11740On System V.4 and embedded PowerPC systems compile code for the
11741NetBSD operating system.
11742
11743@item -maix-struct-return
11744@opindex maix-struct-return
11745Return all structures in memory (as specified by the AIX ABI)@.
11746
11747@item -msvr4-struct-return
11748@opindex msvr4-struct-return
11749Return structures smaller than 8 bytes in registers (as specified by the
11750SVR4 ABI)@.
11751
11752@item -mabi=@var{abi-type}
11753@opindex mabi
11754Extend the current ABI with a particular extension, or remove such extension.
11755Valid values are @var{altivec}, @var{no-altivec}, @var{spe},
11756@var{no-spe}, @var{ibmlongdouble}, @var{ieeelongdouble}@.
11757
11758@item -mabi=spe
11759@opindex mabi=spe
11760Extend the current ABI with SPE ABI extensions. This does not change
11761the default ABI, instead it adds the SPE ABI extensions to the current
11762ABI@.
11763
11764@item -mabi=no-spe
11765@opindex mabi=no-spe
11766Disable Booke SPE ABI extensions for the current ABI@.
11767
11768@item -mabi=ibmlongdouble
11769@opindex mabi=ibmlongdouble
11770Change the current ABI to use IBM extended precision long double.
11771This is a PowerPC 32-bit SYSV ABI option.
11772
11773@item -mabi=ieeelongdouble
11774@opindex mabi=ieeelongdouble
11775Change the current ABI to use IEEE extended precision long double.
11776This is a PowerPC 32-bit Linux ABI option.
11777
11778@item -mprototype
11779@itemx -mno-prototype
11780@opindex mprototype
11781@opindex mno-prototype
11782On System V.4 and embedded PowerPC systems assume that all calls to
11783variable argument functions are properly prototyped. Otherwise, the
11784compiler must insert an instruction before every non prototyped call to
11785set or clear bit 6 of the condition code register (@var{CR}) to
11786indicate whether floating point values were passed in the floating point
11787registers in case the function takes a variable arguments. With
11788@option{-mprototype}, only calls to prototyped variable argument functions
11789will set or clear the bit.
11790
11791@item -msim
11792@opindex msim
11793On embedded PowerPC systems, assume that the startup module is called
11794@file{sim-crt0.o} and that the standard C libraries are @file{libsim.a} and
11795@file{libc.a}. This is the default for @samp{powerpc-*-eabisim}.
11796configurations.
11797
11798@item -mmvme
11799@opindex mmvme
11800On embedded PowerPC systems, assume that the startup module is called
11801@file{crt0.o} and the standard C libraries are @file{libmvme.a} and
11802@file{libc.a}.
11803
11804@item -mads
11805@opindex mads
11806On embedded PowerPC systems, assume that the startup module is called
11807@file{crt0.o} and the standard C libraries are @file{libads.a} and
11808@file{libc.a}.
11809
11810@item -myellowknife
11811@opindex myellowknife
11812On embedded PowerPC systems, assume that the startup module is called
11813@file{crt0.o} and the standard C libraries are @file{libyk.a} and
11814@file{libc.a}.
11815
11816@item -mvxworks
11817@opindex mvxworks
11818On System V.4 and embedded PowerPC systems, specify that you are
11819compiling for a VxWorks system.
11820
11821@item -mwindiss
11822@opindex mwindiss
11823Specify that you are compiling for the WindISS simulation environment.
11824
11825@item -memb
11826@opindex memb
11827On embedded PowerPC systems, set the @var{PPC_EMB} bit in the ELF flags
11828header to indicate that @samp{eabi} extended relocations are used.
11829
11830@item -meabi
11831@itemx -mno-eabi
11832@opindex meabi
11833@opindex mno-eabi
11834On System V.4 and embedded PowerPC systems do (do not) adhere to the
11835Embedded Applications Binary Interface (eabi) which is a set of
11836modifications to the System V.4 specifications. Selecting @option{-meabi}
11837means that the stack is aligned to an 8 byte boundary, a function
11838@code{__eabi} is called to from @code{main} to set up the eabi
11839environment, and the @option{-msdata} option can use both @code{r2} and
11840@code{r13} to point to two separate small data areas. Selecting
11841@option{-mno-eabi} means that the stack is aligned to a 16 byte boundary,
11842do not call an initialization function from @code{main}, and the
11843@option{-msdata} option will only use @code{r13} to point to a single
11844small data area. The @option{-meabi} option is on by default if you
11845configured GCC using one of the @samp{powerpc*-*-eabi*} options.
11846
11847@item -msdata=eabi
11848@opindex msdata=eabi
11849On System V.4 and embedded PowerPC systems, put small initialized
11850@code{const} global and static data in the @samp{.sdata2} section, which
11851is pointed to by register @code{r2}. Put small initialized
11852non-@code{const} global and static data in the @samp{.sdata} section,
11853which is pointed to by register @code{r13}. Put small uninitialized
11854global and static data in the @samp{.sbss} section, which is adjacent to
11855the @samp{.sdata} section. The @option{-msdata=eabi} option is
11856incompatible with the @option{-mrelocatable} option. The
11857@option{-msdata=eabi} option also sets the @option{-memb} option.
11858
11859@item -msdata=sysv
11860@opindex msdata=sysv
11861On System V.4 and embedded PowerPC systems, put small global and static
11862data in the @samp{.sdata} section, which is pointed to by register
11863@code{r13}. Put small uninitialized global and static data in the
11864@samp{.sbss} section, which is adjacent to the @samp{.sdata} section.
11865The @option{-msdata=sysv} option is incompatible with the
11866@option{-mrelocatable} option.
11867
11868@item -msdata=default
11869@itemx -msdata
11870@opindex msdata=default
11871@opindex msdata
11872On System V.4 and embedded PowerPC systems, if @option{-meabi} is used,
11873compile code the same as @option{-msdata=eabi}, otherwise compile code the
11874same as @option{-msdata=sysv}.
11875
11876@item -msdata-data
11877@opindex msdata-data
11878On System V.4 and embedded PowerPC systems, put small global
11879data in the @samp{.sdata} section. Put small uninitialized global
11880data in the @samp{.sbss} section. Do not use register @code{r13}
11881to address small data however. This is the default behavior unless
11882other @option{-msdata} options are used.
11883
11884@item -msdata=none
11885@itemx -mno-sdata
11886@opindex msdata=none
11887@opindex mno-sdata
11888On embedded PowerPC systems, put all initialized global and static data
11889in the @samp{.data} section, and all uninitialized data in the
11890@samp{.bss} section.
11891
11892@item -G @var{num}
11893@opindex G
11894@cindex smaller data references (PowerPC)
11895@cindex .sdata/.sdata2 references (PowerPC)
11896On embedded PowerPC systems, put global and static items less than or
11897equal to @var{num} bytes into the small data or bss sections instead of
11898the normal data or bss section. By default, @var{num} is 8. The
11899@option{-G @var{num}} switch is also passed to the linker.
11900All modules should be compiled with the same @option{-G @var{num}} value.
11901
11902@item -mregnames
11903@itemx -mno-regnames
11904@opindex mregnames
11905@opindex mno-regnames
11906On System V.4 and embedded PowerPC systems do (do not) emit register
11907names in the assembly language output using symbolic forms.
11908
11909@item -mlongcall
11910@itemx -mno-longcall
11911@opindex mlongcall
11912@opindex mno-longcall
11913By default assume that all calls are far away so that a longer more
11914expensive calling sequence is required. This is required for calls
11915further than 32 megabytes (33,554,432 bytes) from the current location.
11916A short call will be generated if the compiler knows
11917the call cannot be that far away. This setting can be overridden by
11918the @code{shortcall} function attribute, or by @code{#pragma
11919longcall(0)}.
11920
11921Some linkers are capable of detecting out-of-range calls and generating
11922glue code on the fly. On these systems, long calls are unnecessary and
11923generate slower code. As of this writing, the AIX linker can do this,
11924as can the GNU linker for PowerPC/64. It is planned to add this feature
11925to the GNU linker for 32-bit PowerPC systems as well.
11926
11927On Darwin/PPC systems, @code{#pragma longcall} will generate ``jbsr
11928callee, L42'', plus a ``branch island'' (glue code). The two target
11929addresses represent the callee and the ``branch island''. The
11930Darwin/PPC linker will prefer the first address and generate a ``bl
11931callee'' if the PPC ``bl'' instruction will reach the callee directly;
11932otherwise, the linker will generate ``bl L42'' to call the ``branch
11933island''. The ``branch island'' is appended to the body of the
11934calling function; it computes the full 32-bit address of the callee
11935and jumps to it.
11936
11937On Mach-O (Darwin) systems, this option directs the compiler emit to
11938the glue for every direct call, and the Darwin linker decides whether
11939to use or discard it.
11940
11941In the future, we may cause GCC to ignore all longcall specifications
11942when the linker is known to generate glue.
11943
11944@item -pthread
11945@opindex pthread
11946Adds support for multithreading with the @dfn{pthreads} library.
11947This option sets flags for both the preprocessor and linker.
11948
11949@end table
11950
11951@node S/390 and zSeries Options
11952@subsection S/390 and zSeries Options
11953@cindex S/390 and zSeries Options
11954
11955These are the @samp{-m} options defined for the S/390 and zSeries architecture.
11956
11957@table @gcctabopt
11958@item -mhard-float
11959@itemx -msoft-float
11960@opindex mhard-float
11961@opindex msoft-float
11962Use (do not use) the hardware floating-point instructions and registers
11963for floating-point operations. When @option{-msoft-float} is specified,
11964functions in @file{libgcc.a} will be used to perform floating-point
11965operations. When @option{-mhard-float} is specified, the compiler
11966generates IEEE floating-point instructions. This is the default.
11967
11968@item -mlong-double-64
11969@itemx -mlong-double-128
11970@opindex mlong-double-64
11971@opindex mlong-double-128
11972These switches control the size of @code{long double} type. A size
11973of 64bit makes the @code{long double} type equivalent to the @code{double}
11974type. This is the default.
11975
11976@item -mbackchain
11977@itemx -mno-backchain
11978@opindex mbackchain
11979@opindex mno-backchain
11980Store (do not store) the address of the caller's frame as backchain pointer
11981into the callee's stack frame.
11982A backchain may be needed to allow debugging using tools that do not understand
11983DWARF-2 call frame information.
11984When @option{-mno-packed-stack} is in effect, the backchain pointer is stored
11985at the bottom of the stack frame; when @option{-mpacked-stack} is in effect,
11986the backchain is placed into the topmost word of the 96/160 byte register
11987save area.
11988
11989In general, code compiled with @option{-mbackchain} is call-compatible with
11990code compiled with @option{-mmo-backchain}; however, use of the backchain
11991for debugging purposes usually requires that the whole binary is built with
11992@option{-mbackchain}. Note that the combination of @option{-mbackchain},
11993@option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
11994to build a linux kernel use @option{-msoft-float}.
11995
11996The default is to not maintain the backchain.
11997
11998@item -mpacked-stack
11999@item -mno-packed-stack
12000@opindex mpacked-stack
12001@opindex mno-packed-stack
12002Use (do not use) the packed stack layout. When @option{-mno-packed-stack} is
12003specified, the compiler uses the all fields of the 96/160 byte register save
12004area only for their default purpose; unused fields still take up stack space.
12005When @option{-mpacked-stack} is specified, register save slots are densely
12006packed at the top of the register save area; unused space is reused for other
12007purposes, allowing for more efficient use of the available stack space.
12008However, when @option{-mbackchain} is also in effect, the topmost word of
12009the save area is always used to store the backchain, and the return address
12010register is always saved two words below the backchain.
12011
12012As long as the stack frame backchain is not used, code generated with
12013@option{-mpacked-stack} is call-compatible with code generated with
12014@option{-mno-packed-stack}. Note that some non-FSF releases of GCC 2.95 for
12015S/390 or zSeries generated code that uses the stack frame backchain at run
12016time, not just for debugging purposes. Such code is not call-compatible
12017with code compiled with @option{-mpacked-stack}. Also, note that the
12018combination of @option{-mbackchain},
12019@option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
12020to build a linux kernel use @option{-msoft-float}.
12021
12022The default is to not use the packed stack layout.
12023
12024@item -msmall-exec
12025@itemx -mno-small-exec
12026@opindex msmall-exec
12027@opindex mno-small-exec
12028Generate (or do not generate) code using the @code{bras} instruction
12029to do subroutine calls.
12030This only works reliably if the total executable size does not
12031exceed 64k. The default is to use the @code{basr} instruction instead,
12032which does not have this limitation.
12033
12034@item -m64
12035@itemx -m31
12036@opindex m64
12037@opindex m31
12038When @option{-m31} is specified, generate code compliant to the
12039GNU/Linux for S/390 ABI@. When @option{-m64} is specified, generate
12040code compliant to the GNU/Linux for zSeries ABI@. This allows GCC in
12041particular to generate 64-bit instructions. For the @samp{s390}
12042targets, the default is @option{-m31}, while the @samp{s390x}
12043targets default to @option{-m64}.
12044
12045@item -mzarch
12046@itemx -mesa
12047@opindex mzarch
12048@opindex mesa
12049When @option{-mzarch} is specified, generate code using the
12050instructions available on z/Architecture.
12051When @option{-mesa} is specified, generate code using the
12052instructions available on ESA/390. Note that @option{-mesa} is
12053not possible with @option{-m64}.
12054When generating code compliant to the GNU/Linux for S/390 ABI,
12055the default is @option{-mesa}. When generating code compliant
12056to the GNU/Linux for zSeries ABI, the default is @option{-mzarch}.
12057
12058@item -mmvcle
12059@itemx -mno-mvcle
12060@opindex mmvcle
12061@opindex mno-mvcle
12062Generate (or do not generate) code using the @code{mvcle} instruction
12063to perform block moves. When @option{-mno-mvcle} is specified,
12064use a @code{mvc} loop instead. This is the default unless optimizing for
12065size.
12066
12067@item -mdebug
12068@itemx -mno-debug
12069@opindex mdebug
12070@opindex mno-debug
12071Print (or do not print) additional debug information when compiling.
12072The default is to not print debug information.
12073
12074@item -march=@var{cpu-type}
12075@opindex march
12076Generate code that will run on @var{cpu-type}, which is the name of a system
12077representing a certain processor type. Possible values for
12078@var{cpu-type} are @samp{g5}, @samp{g6}, @samp{z900}, and @samp{z990}.
12079When generating code using the instructions available on z/Architecture,
12080the default is @option{-march=z900}. Otherwise, the default is
12081@option{-march=g5}.
12082
12083@item -mtune=@var{cpu-type}
12084@opindex mtune
12085Tune to @var{cpu-type} everything applicable about the generated code,
12086except for the ABI and the set of available instructions.
12087The list of @var{cpu-type} values is the same as for @option{-march}.
12088The default is the value used for @option{-march}.
12089
12090@item -mtpf-trace
12091@itemx -mno-tpf-trace
12092@opindex mtpf-trace
12093@opindex mno-tpf-trace
12094Generate code that adds (does not add) in TPF OS specific branches to trace
12095routines in the operating system. This option is off by default, even
12096when compiling for the TPF OS@.
12097
12098@item -mfused-madd
12099@itemx -mno-fused-madd
12100@opindex mfused-madd
12101@opindex mno-fused-madd
12102Generate code that uses (does not use) the floating point multiply and
12103accumulate instructions. These instructions are generated by default if
12104hardware floating point is used.
12105
12106@item -mwarn-framesize=@var{framesize}
12107@opindex mwarn-framesize
12108Emit a warning if the current function exceeds the given frame size. Because
12109this is a compile time check it doesn't need to be a real problem when the program
12110runs. It is intended to identify functions which most probably cause
12111a stack overflow. It is useful to be used in an environment with limited stack
12112size e.g.@: the linux kernel.
12113
12114@item -mwarn-dynamicstack
12115@opindex mwarn-dynamicstack
12116Emit a warning if the function calls alloca or uses dynamically
12117sized arrays. This is generally a bad idea with a limited stack size.
12118
12119@item -mstack-guard=@var{stack-guard}
12120@item -mstack-size=@var{stack-size}
12121@opindex mstack-guard
12122@opindex mstack-size
12123These arguments always have to be used in conjunction. If they are present the s390
12124back end emits additional instructions in the function prologue which trigger a trap
12125if the stack size is @var{stack-guard} bytes above the @var{stack-size}
12126(remember that the stack on s390 grows downward). These options are intended to
12127be used to help debugging stack overflow problems. The additionally emitted code
12128causes only little overhead and hence can also be used in production like systems
12129without greater performance degradation. The given values have to be exact
12130powers of 2 and @var{stack-size} has to be greater than @var{stack-guard} without
12131exceeding 64k.
12132In order to be efficient the extra code makes the assumption that the stack starts
12133at an address aligned to the value given by @var{stack-size}.
12134@end table
12135
12136@node Score Options
12137@subsection Score Options
12138@cindex Score Options
12139
12140These options are defined for Score implementations:
12141
12142@table @gcctabopt
12143@item -meb
12144@opindex meb
12145Compile code for big endian mode. This is the default.
12146
12147@item -mel
12148@opindex mel
12149Compile code for little endian mode.
12150
12151@item -mnhwloop
12152@opindex mnhwloop
12153Disable generate bcnz instruction.
12154
12155@item -muls
12156@opindex muls
12157Enable generate unaligned load and store instruction.
12158
12159@item -mmac
12160@opindex mmac
12161Enable the use of multiply-accumulate instructions. Disabled by default.
12162
12163@item -mscore5
12164@opindex mscore5
12165Specify the SCORE5 as the target architecture.
12166
12167@item -mscore5u
12168@opindex mscore5u
12169Specify the SCORE5U of the target architecture.
12170
12171@item -mscore7
12172@opindex mscore7
12173Specify the SCORE7 as the target architecture. This is the default.
12174
12175@item -mscore7d
12176@opindex mscore7d
12177Specify the SCORE7D as the target architecture.
12178@end table
12179
12180@node SH Options
12181@subsection SH Options
12182
12183These @samp{-m} options are defined for the SH implementations:
12184
12185@table @gcctabopt
12186@item -m1
12187@opindex m1
12188Generate code for the SH1.
12189
12190@item -m2
12191@opindex m2
12192Generate code for the SH2.
12193
12194@item -m2e
12195Generate code for the SH2e.
12196
12197@item -m3
12198@opindex m3
12199Generate code for the SH3.
12200
12201@item -m3e
12202@opindex m3e
12203Generate code for the SH3e.
12204
12205@item -m4-nofpu
12206@opindex m4-nofpu
12207Generate code for the SH4 without a floating-point unit.
12208
12209@item -m4-single-only
12210@opindex m4-single-only
12211Generate code for the SH4 with a floating-point unit that only
12212supports single-precision arithmetic.
12213
12214@item -m4-single
12215@opindex m4-single
12216Generate code for the SH4 assuming the floating-point unit is in
12217single-precision mode by default.
12218
12219@item -m4
12220@opindex m4
12221Generate code for the SH4.
12222
12223@item -m4a-nofpu
12224@opindex m4a-nofpu
12225Generate code for the SH4al-dsp, or for a SH4a in such a way that the
12226floating-point unit is not used.
12227
12228@item -m4a-single-only
12229@opindex m4a-single-only
12230Generate code for the SH4a, in such a way that no double-precision
12231floating point operations are used.
12232
12233@item -m4a-single
12234@opindex m4a-single
12235Generate code for the SH4a assuming the floating-point unit is in
12236single-precision mode by default.
12237
12238@item -m4a
12239@opindex m4a
12240Generate code for the SH4a.
12241
12242@item -m4al
12243@opindex m4al
12244Same as @option{-m4a-nofpu}, except that it implicitly passes
12245@option{-dsp} to the assembler. GCC doesn't generate any DSP
12246instructions at the moment.
12247
12248@item -mb
12249@opindex mb
12250Compile code for the processor in big endian mode.
12251
12252@item -ml
12253@opindex ml
12254Compile code for the processor in little endian mode.
12255
12256@item -mdalign
12257@opindex mdalign
12258Align doubles at 64-bit boundaries. Note that this changes the calling
12259conventions, and thus some functions from the standard C library will
12260not work unless you recompile it first with @option{-mdalign}.
12261
12262@item -mrelax
12263@opindex mrelax
12264Shorten some address references at link time, when possible; uses the
12265linker option @option{-relax}.
12266
12267@item -mbigtable
12268@opindex mbigtable
12269Use 32-bit offsets in @code{switch} tables. The default is to use
1227016-bit offsets.
12271
12272@item -mfmovd
12273@opindex mfmovd
12274Enable the use of the instruction @code{fmovd}.
12275
12276@item -mhitachi
12277@opindex mhitachi
12278Comply with the calling conventions defined by Renesas.
12279
12280@item -mrenesas
12281@opindex mhitachi
12282Comply with the calling conventions defined by Renesas.
12283
12284@item -mno-renesas
12285@opindex mhitachi
12286Comply with the calling conventions defined for GCC before the Renesas
12287conventions were available. This option is the default for all
12288targets of the SH toolchain except for @samp{sh-symbianelf}.
12289
12290@item -mnomacsave
12291@opindex mnomacsave
12292Mark the @code{MAC} register as call-clobbered, even if
12293@option{-mhitachi} is given.
12294
12295@item -mieee
12296@opindex mieee
12297Increase IEEE-compliance of floating-point code.
12298At the moment, this is equivalent to @option{-fno-finite-math-only}.
12299When generating 16 bit SH opcodes, getting IEEE-conforming results for
12300comparisons of NANs / infinities incurs extra overhead in every
12301floating point comparison, therefore the default is set to
12302@option{-ffinite-math-only}.
12303
12304@item -misize
12305@opindex misize
12306Dump instruction size and location in the assembly code.
12307
12308@item -mpadstruct
12309@opindex mpadstruct
12310This option is deprecated. It pads structures to multiple of 4 bytes,
12311which is incompatible with the SH ABI@.
12312
12313@item -mspace
12314@opindex mspace
12315Optimize for space instead of speed. Implied by @option{-Os}.
12316
12317@item -mprefergot
12318@opindex mprefergot
12319When generating position-independent code, emit function calls using
12320the Global Offset Table instead of the Procedure Linkage Table.
12321
12322@item -musermode
12323@opindex musermode
12324Generate a library function call to invalidate instruction cache
12325entries, after fixing up a trampoline. This library function call
12326doesn't assume it can write to the whole memory address space. This
12327is the default when the target is @code{sh-*-linux*}.
12328
12329@item -multcost=@var{number}
12330@opindex multcost=@var{number}
12331Set the cost to assume for a multiply insn.
12332
12333@item -mdiv=@var{strategy}
12334@opindex mdiv=@var{strategy}
12335Set the division strategy to use for SHmedia code. @var{strategy} must be
12336one of: call, call2, fp, inv, inv:minlat, inv20u, inv20l, inv:call,
12337inv:call2, inv:fp .
12338"fp" performs the operation in floating point. This has a very high latency,
12339but needs only a few instructions, so it might be a good choice if
12340your code has enough easily exploitable ILP to allow the compiler to
12341schedule the floating point instructions together with other instructions.
12342Division by zero causes a floating point exception.
12343"inv" uses integer operations to calculate the inverse of the divisor,
12344and then multiplies the dividend with the inverse. This strategy allows
12345cse and hoisting of the inverse calculation. Division by zero calculates
12346an unspecified result, but does not trap.
12347"inv:minlat" is a variant of "inv" where if no cse / hoisting opportunities
12348have been found, or if the entire operation has been hoisted to the same
12349place, the last stages of the inverse calculation are intertwined with the
12350final multiply to reduce the overall latency, at the expense of using a few
12351more instructions, and thus offering fewer scheduling opportunities with
12352other code.
12353"call" calls a library function that usually implements the inv:minlat
12354strategy.
12355This gives high code density for m5-*media-nofpu compilations.
12356"call2" uses a different entry point of the same library function, where it
12357assumes that a pointer to a lookup table has already been set up, which
12358exposes the pointer load to cse / code hoisting optimizations.
12359"inv:call", "inv:call2" and "inv:fp" all use the "inv" algorithm for initial
12360code generation, but if the code stays unoptimized, revert to the "call",
12361"call2", or "fp" strategies, respectively. Note that the
12362potentially-trapping side effect of division by zero is carried by a
12363separate instruction, so it is possible that all the integer instructions
12364are hoisted out, but the marker for the side effect stays where it is.
12365A recombination to fp operations or a call is not possible in that case.
12366"inv20u" and "inv20l" are variants of the "inv:minlat" strategy. In the case
12367that the inverse calculation was nor separated from the multiply, they speed
12368up division where the dividend fits into 20 bits (plus sign where applicable),
12369by inserting a test to skip a number of operations in this case; this test
12370slows down the case of larger dividends. inv20u assumes the case of a such
12371a small dividend to be unlikely, and inv20l assumes it to be likely.
12372
12373@item -mdivsi3_libfunc=@var{name}
12374@opindex mdivsi3_libfunc=@var{name}
12375Set the name of the library function used for 32 bit signed division to
12376@var{name}. This only affect the name used in the call and inv:call
12377division strategies, and the compiler will still expect the same
12378sets of input/output/clobbered registers as if this option was not present.
12379
12380@item -madjust-unroll
12381@opindex madjust-unroll
12382Throttle unrolling to avoid thrashing target registers.
12383This option only has an effect if the gcc code base supports the
12384TARGET_ADJUST_UNROLL_MAX target hook.
12385
12386@item -mindexed-addressing
12387@opindex mindexed-addressing
12388Enable the use of the indexed addressing mode for SHmedia32/SHcompact.
12389This is only safe if the hardware and/or OS implement 32 bit wrap-around
12390semantics for the indexed addressing mode. The architecture allows the
12391implementation of processors with 64 bit MMU, which the OS could use to
12392get 32 bit addressing, but since no current hardware implementation supports
12393this or any other way to make the indexed addressing mode safe to use in
12394the 32 bit ABI, the default is -mno-indexed-addressing.
12395
12396@item -mgettrcost=@var{number}
12397@opindex mgettrcost=@var{number}
12398Set the cost assumed for the gettr instruction to @var{number}.
12399The default is 2 if @option{-mpt-fixed} is in effect, 100 otherwise.
12400
12401@item -mpt-fixed
12402@opindex mpt-fixed
12403Assume pt* instructions won't trap. This will generally generate better
12404scheduled code, but is unsafe on current hardware. The current architecture
12405definition says that ptabs and ptrel trap when the target anded with 3 is 3.
12406This has the unintentional effect of making it unsafe to schedule ptabs /
12407ptrel before a branch, or hoist it out of a loop. For example,
12408__do_global_ctors, a part of libgcc that runs constructors at program
12409startup, calls functions in a list which is delimited by -1. With the
12410-mpt-fixed option, the ptabs will be done before testing against -1.
12411That means that all the constructors will be run a bit quicker, but when
12412the loop comes to the end of the list, the program crashes because ptabs
12413loads -1 into a target register. Since this option is unsafe for any
12414hardware implementing the current architecture specification, the default
12415is -mno-pt-fixed. Unless the user specifies a specific cost with
12416@option{-mgettrcost}, -mno-pt-fixed also implies @option{-mgettrcost=100};
12417this deters register allocation using target registers for storing
12418ordinary integers.
12419
12420@item -minvalid-symbols
12421@opindex minvalid-symbols
12422Assume symbols might be invalid. Ordinary function symbols generated by
12423the compiler will always be valid to load with movi/shori/ptabs or
12424movi/shori/ptrel, but with assembler and/or linker tricks it is possible
12425to generate symbols that will cause ptabs / ptrel to trap.
12426This option is only meaningful when @option{-mno-pt-fixed} is in effect.
12427It will then prevent cross-basic-block cse, hoisting and most scheduling
12428of symbol loads. The default is @option{-mno-invalid-symbols}.
12429@end table
12430
12431@node SPARC Options
12432@subsection SPARC Options
12433@cindex SPARC options
12434
12435These @samp{-m} options are supported on the SPARC:
12436
12437@table @gcctabopt
12438@item -mno-app-regs
12439@itemx -mapp-regs
12440@opindex mno-app-regs
12441@opindex mapp-regs
12442Specify @option{-mapp-regs} to generate output using the global registers
124432 through 4, which the SPARC SVR4 ABI reserves for applications. This
12444is the default.
12445
12446To be fully SVR4 ABI compliant at the cost of some performance loss,
12447specify @option{-mno-app-regs}. You should compile libraries and system
12448software with this option.
12449
12450@item -mfpu
12451@itemx -mhard-float
12452@opindex mfpu
12453@opindex mhard-float
12454Generate output containing floating point instructions. This is the
12455default.
12456
12457@item -mno-fpu
12458@itemx -msoft-float
12459@opindex mno-fpu
12460@opindex msoft-float
12461Generate output containing library calls for floating point.
12462@strong{Warning:} the requisite libraries are not available for all SPARC
12463targets. Normally the facilities of the machine's usual C compiler are
12464used, but this cannot be done directly in cross-compilation. You must make
12465your own arrangements to provide suitable library functions for
12466cross-compilation. The embedded targets @samp{sparc-*-aout} and
12467@samp{sparclite-*-*} do provide software floating point support.
12468
12469@option{-msoft-float} changes the calling convention in the output file;
12470therefore, it is only useful if you compile @emph{all} of a program with
12471this option. In particular, you need to compile @file{libgcc.a}, the
12472library that comes with GCC, with @option{-msoft-float} in order for
12473this to work.
12474
12475@item -mhard-quad-float
12476@opindex mhard-quad-float
12477Generate output containing quad-word (long double) floating point
12478instructions.
12479
12480@item -msoft-quad-float
12481@opindex msoft-quad-float
12482Generate output containing library calls for quad-word (long double)
12483floating point instructions. The functions called are those specified
12484in the SPARC ABI@. This is the default.
12485
12486As of this writing, there are no SPARC implementations that have hardware
12487support for the quad-word floating point instructions. They all invoke
12488a trap handler for one of these instructions, and then the trap handler
12489emulates the effect of the instruction. Because of the trap handler overhead,
12490this is much slower than calling the ABI library routines. Thus the
12491@option{-msoft-quad-float} option is the default.
12492
12493@item -mno-unaligned-doubles
12494@itemx -munaligned-doubles
12495@opindex mno-unaligned-doubles
12496@opindex munaligned-doubles
12497Assume that doubles have 8 byte alignment. This is the default.
12498
12499With @option{-munaligned-doubles}, GCC assumes that doubles have 8 byte
12500alignment only if they are contained in another type, or if they have an
12501absolute address. Otherwise, it assumes they have 4 byte alignment.
12502Specifying this option avoids some rare compatibility problems with code
12503generated by other compilers. It is not the default because it results
12504in a performance loss, especially for floating point code.
12505
12506@item -mno-faster-structs
12507@itemx -mfaster-structs
12508@opindex mno-faster-structs
12509@opindex mfaster-structs
12510With @option{-mfaster-structs}, the compiler assumes that structures
12511should have 8 byte alignment. This enables the use of pairs of
12512@code{ldd} and @code{std} instructions for copies in structure
12513assignment, in place of twice as many @code{ld} and @code{st} pairs.
12514However, the use of this changed alignment directly violates the SPARC
12515ABI@. Thus, it's intended only for use on targets where the developer
12516acknowledges that their resulting code will not be directly in line with
12517the rules of the ABI@.
12518
12519@item -mimpure-text
12520@opindex mimpure-text
12521@option{-mimpure-text}, used in addition to @option{-shared}, tells
12522the compiler to not pass @option{-z text} to the linker when linking a
12523shared object. Using this option, you can link position-dependent
12524code into a shared object.
12525
12526@option{-mimpure-text} suppresses the ``relocations remain against
12527allocatable but non-writable sections'' linker error message.
12528However, the necessary relocations will trigger copy-on-write, and the
12529shared object is not actually shared across processes. Instead of
12530using @option{-mimpure-text}, you should compile all source code with
12531@option{-fpic} or @option{-fPIC}.
12532
12533This option is only available on SunOS and Solaris.
12534
12535@item -mcpu=@var{cpu_type}
12536@opindex mcpu
12537Set the instruction set, register set, and instruction scheduling parameters
12538for machine type @var{cpu_type}. Supported values for @var{cpu_type} are
12539@samp{v7}, @samp{cypress}, @samp{v8}, @samp{supersparc}, @samp{sparclite},
12540@samp{f930}, @samp{f934}, @samp{hypersparc}, @samp{sparclite86x},
12541@samp{sparclet}, @samp{tsc701}, @samp{v9}, @samp{ultrasparc},
12542@samp{ultrasparc3}, and @samp{niagara}.
12543
12544Default instruction scheduling parameters are used for values that select
12545an architecture and not an implementation. These are @samp{v7}, @samp{v8},
12546@samp{sparclite}, @samp{sparclet}, @samp{v9}.
12547
12548Here is a list of each supported architecture and their supported
12549implementations.
12550
12551@smallexample
12552 v7: cypress
12553 v8: supersparc, hypersparc
12554 sparclite: f930, f934, sparclite86x
12555 sparclet: tsc701
12556 v9: ultrasparc, ultrasparc3, niagara
12557@end smallexample
12558
12559By default (unless configured otherwise), GCC generates code for the V7
12560variant of the SPARC architecture. With @option{-mcpu=cypress}, the compiler
12561additionally optimizes it for the Cypress CY7C602 chip, as used in the
12562SPARCStation/SPARCServer 3xx series. This is also appropriate for the older
12563SPARCStation 1, 2, IPX etc.
12564
12565With @option{-mcpu=v8}, GCC generates code for the V8 variant of the SPARC
12566architecture. The only difference from V7 code is that the compiler emits
12567the integer multiply and integer divide instructions which exist in SPARC-V8
12568but not in SPARC-V7. With @option{-mcpu=supersparc}, the compiler additionally
12569optimizes it for the SuperSPARC chip, as used in the SPARCStation 10, 1000 and
125702000 series.
12571
12572With @option{-mcpu=sparclite}, GCC generates code for the SPARClite variant of
12573the SPARC architecture. This adds the integer multiply, integer divide step
12574and scan (@code{ffs}) instructions which exist in SPARClite but not in SPARC-V7.
12575With @option{-mcpu=f930}, the compiler additionally optimizes it for the
12576Fujitsu MB86930 chip, which is the original SPARClite, with no FPU@. With
12577@option{-mcpu=f934}, the compiler additionally optimizes it for the Fujitsu
12578MB86934 chip, which is the more recent SPARClite with FPU@.
12579
12580With @option{-mcpu=sparclet}, GCC generates code for the SPARClet variant of
12581the SPARC architecture. This adds the integer multiply, multiply/accumulate,
12582integer divide step and scan (@code{ffs}) instructions which exist in SPARClet
12583but not in SPARC-V7. With @option{-mcpu=tsc701}, the compiler additionally
12584optimizes it for the TEMIC SPARClet chip.
12585
12586With @option{-mcpu=v9}, GCC generates code for the V9 variant of the SPARC
12587architecture. This adds 64-bit integer and floating-point move instructions,
125883 additional floating-point condition code registers and conditional move
12589instructions. With @option{-mcpu=ultrasparc}, the compiler additionally
12590optimizes it for the Sun UltraSPARC I/II/IIi chips. With
12591@option{-mcpu=ultrasparc3}, the compiler additionally optimizes it for the
12592Sun UltraSPARC III/III+/IIIi/IIIi+/IV/IV+ chips. With
12593@option{-mcpu=niagara}, the compiler additionally optimizes it for
12594Sun UltraSPARC T1 chips.
12595
12596@item -mtune=@var{cpu_type}
12597@opindex mtune
12598Set the instruction scheduling parameters for machine type
12599@var{cpu_type}, but do not set the instruction set or register set that the
12600option @option{-mcpu=@var{cpu_type}} would.
12601
12602The same values for @option{-mcpu=@var{cpu_type}} can be used for
12603@option{-mtune=@var{cpu_type}}, but the only useful values are those
12604that select a particular cpu implementation. Those are @samp{cypress},
12605@samp{supersparc}, @samp{hypersparc}, @samp{f930}, @samp{f934},
12606@samp{sparclite86x}, @samp{tsc701}, @samp{ultrasparc},
12607@samp{ultrasparc3}, and @samp{niagara}.
12608
12609@item -mv8plus
12610@itemx -mno-v8plus
12611@opindex mv8plus
12612@opindex mno-v8plus
12613With @option{-mv8plus}, GCC generates code for the SPARC-V8+ ABI@. The
12614difference from the V8 ABI is that the global and out registers are
12615considered 64-bit wide. This is enabled by default on Solaris in 32-bit
12616mode for all SPARC-V9 processors.
12617
12618@item -mvis
12619@itemx -mno-vis
12620@opindex mvis
12621@opindex mno-vis
12622With @option{-mvis}, GCC generates code that takes advantage of the UltraSPARC
12623Visual Instruction Set extensions. The default is @option{-mno-vis}.
12624@end table
12625
12626These @samp{-m} options are supported in addition to the above
12627on SPARC-V9 processors in 64-bit environments:
12628
12629@table @gcctabopt
12630@item -mlittle-endian
12631@opindex mlittle-endian
12632Generate code for a processor running in little-endian mode. It is only
12633available for a few configurations and most notably not on Solaris and Linux.
12634
12635@item -m32
12636@itemx -m64
12637@opindex m32
12638@opindex m64
12639Generate code for a 32-bit or 64-bit environment.
12640The 32-bit environment sets int, long and pointer to 32 bits.
12641The 64-bit environment sets int to 32 bits and long and pointer
12642to 64 bits.
12643
12644@item -mcmodel=medlow
12645@opindex mcmodel=medlow
12646Generate code for the Medium/Low code model: 64-bit addresses, programs
12647must be linked in the low 32 bits of memory. Programs can be statically
12648or dynamically linked.
12649
12650@item -mcmodel=medmid
12651@opindex mcmodel=medmid
12652Generate code for the Medium/Middle code model: 64-bit addresses, programs
12653must be linked in the low 44 bits of memory, the text and data segments must
12654be less than 2GB in size and the data segment must be located within 2GB of
12655the text segment.
12656
12657@item -mcmodel=medany
12658@opindex mcmodel=medany
12659Generate code for the Medium/Anywhere code model: 64-bit addresses, programs
12660may be linked anywhere in memory, the text and data segments must be less
12661than 2GB in size and the data segment must be located within 2GB of the
12662text segment.
12663
12664@item -mcmodel=embmedany
12665@opindex mcmodel=embmedany
12666Generate code for the Medium/Anywhere code model for embedded systems:
1266764-bit addresses, the text and data segments must be less than 2GB in
12668size, both starting anywhere in memory (determined at link time). The
12669global register %g4 points to the base of the data segment. Programs
12670are statically linked and PIC is not supported.
12671
12672@item -mstack-bias
12673@itemx -mno-stack-bias
12674@opindex mstack-bias
12675@opindex mno-stack-bias
12676With @option{-mstack-bias}, GCC assumes that the stack pointer, and
12677frame pointer if present, are offset by @minus{}2047 which must be added back
12678when making stack frame references. This is the default in 64-bit mode.
12679Otherwise, assume no such offset is present.
12680@end table
12681
12682These switches are supported in addition to the above on Solaris:
12683
12684@table @gcctabopt
12685@item -threads
12686@opindex threads
12687Add support for multithreading using the Solaris threads library. This
12688option sets flags for both the preprocessor and linker. This option does
12689not affect the thread safety of object code produced by the compiler or
12690that of libraries supplied with it.
12691
12692@item -pthreads
12693@opindex pthreads
12694Add support for multithreading using the POSIX threads library. This
12695option sets flags for both the preprocessor and linker. This option does
12696not affect the thread safety of object code produced by the compiler or
12697that of libraries supplied with it.
12698
12699@item -pthread
12700@opindex pthread
12701This is a synonym for @option{-pthreads}.
12702@end table
12703
12704@node System V Options
12705@subsection Options for System V
12706
12707These additional options are available on System V Release 4 for
12708compatibility with other compilers on those systems:
12709
12710@table @gcctabopt
12711@item -G
12712@opindex G
12713Create a shared object.
12714It is recommended that @option{-symbolic} or @option{-shared} be used instead.
12715
12716@item -Qy
12717@opindex Qy
12718Identify the versions of each tool used by the compiler, in a
12719@code{.ident} assembler directive in the output.
12720
12721@item -Qn
12722@opindex Qn
12723Refrain from adding @code{.ident} directives to the output file (this is
12724the default).
12725
12726@item -YP,@var{dirs}
12727@opindex YP
12728Search the directories @var{dirs}, and no others, for libraries
12729specified with @option{-l}.
12730
12731@item -Ym,@var{dir}
12732@opindex Ym
12733Look in the directory @var{dir} to find the M4 preprocessor.
12734The assembler uses this option.
12735@c This is supposed to go with a -Yd for predefined M4 macro files, but
12736@c the generic assembler that comes with Solaris takes just -Ym.
12737@end table
12738
12739@node TMS320C3x/C4x Options
12740@subsection TMS320C3x/C4x Options
12741@cindex TMS320C3x/C4x Options
12742
12743These @samp{-m} options are defined for TMS320C3x/C4x implementations:
12744
12745@table @gcctabopt
12746
12747@item -mcpu=@var{cpu_type}
12748@opindex mcpu
12749Set the instruction set, register set, and instruction scheduling
12750parameters for machine type @var{cpu_type}. Supported values for
12751@var{cpu_type} are @samp{c30}, @samp{c31}, @samp{c32}, @samp{c40}, and
12752@samp{c44}. The default is @samp{c40} to generate code for the
12753TMS320C40.
12754
12755@item -mbig-memory
12756@itemx -mbig
12757@itemx -msmall-memory
12758@itemx -msmall
12759@opindex mbig-memory
12760@opindex mbig
12761@opindex msmall-memory
12762@opindex msmall
12763Generates code for the big or small memory model. The small memory
12764model assumed that all data fits into one 64K word page. At run-time
12765the data page (DP) register must be set to point to the 64K page
12766containing the .bss and .data program sections. The big memory model is
12767the default and requires reloading of the DP register for every direct
12768memory access.
12769
12770@item -mbk
12771@itemx -mno-bk
12772@opindex mbk
12773@opindex mno-bk
12774Allow (disallow) allocation of general integer operands into the block
12775count register BK@.
12776
12777@item -mdb
12778@itemx -mno-db
12779@opindex mdb
12780@opindex mno-db
12781Enable (disable) generation of code using decrement and branch,
12782DBcond(D), instructions. This is enabled by default for the C4x. To be
12783on the safe side, this is disabled for the C3x, since the maximum
12784iteration count on the C3x is @math{2^{23} + 1} (but who iterates loops more than
12785@math{2^{23}} times on the C3x?). Note that GCC will try to reverse a loop so
12786that it can utilize the decrement and branch instruction, but will give
12787up if there is more than one memory reference in the loop. Thus a loop
12788where the loop counter is decremented can generate slightly more
12789efficient code, in cases where the RPTB instruction cannot be utilized.
12790
12791@item -mdp-isr-reload
12792@itemx -mparanoid
12793@opindex mdp-isr-reload
12794@opindex mparanoid
12795Force the DP register to be saved on entry to an interrupt service
12796routine (ISR), reloaded to point to the data section, and restored on
12797exit from the ISR@. This should not be required unless someone has
12798violated the small memory model by modifying the DP register, say within
12799an object library.
12800
12801@item -mmpyi
12802@itemx -mno-mpyi
12803@opindex mmpyi
12804@opindex mno-mpyi
12805For the C3x use the 24-bit MPYI instruction for integer multiplies
12806instead of a library call to guarantee 32-bit results. Note that if one
12807of the operands is a constant, then the multiplication will be performed
12808using shifts and adds. If the @option{-mmpyi} option is not specified for the C3x,
12809then squaring operations are performed inline instead of a library call.
12810
12811@item -mfast-fix
12812@itemx -mno-fast-fix
12813@opindex mfast-fix
12814@opindex mno-fast-fix
12815The C3x/C4x FIX instruction to convert a floating point value to an
12816integer value chooses the nearest integer less than or equal to the
12817floating point value rather than to the nearest integer. Thus if the
12818floating point number is negative, the result will be incorrectly
12819truncated an additional code is necessary to detect and correct this
12820case. This option can be used to disable generation of the additional
12821code required to correct the result.
12822
12823@item -mrptb
12824@itemx -mno-rptb
12825@opindex mrptb
12826@opindex mno-rptb
12827Enable (disable) generation of repeat block sequences using the RPTB
12828instruction for zero overhead looping. The RPTB construct is only used
12829for innermost loops that do not call functions or jump across the loop
12830boundaries. There is no advantage having nested RPTB loops due to the
12831overhead required to save and restore the RC, RS, and RE registers.
12832This is enabled by default with @option{-O2}.
12833
12834@item -mrpts=@var{count}
12835@itemx -mno-rpts
12836@opindex mrpts
12837@opindex mno-rpts
12838Enable (disable) the use of the single instruction repeat instruction
12839RPTS@. If a repeat block contains a single instruction, and the loop
12840count can be guaranteed to be less than the value @var{count}, GCC will
12841emit a RPTS instruction instead of a RPTB@. If no value is specified,
12842then a RPTS will be emitted even if the loop count cannot be determined
12843at compile time. Note that the repeated instruction following RPTS does
12844not have to be reloaded from memory each iteration, thus freeing up the
12845CPU buses for operands. However, since interrupts are blocked by this
12846instruction, it is disabled by default.
12847
12848@item -mloop-unsigned
12849@itemx -mno-loop-unsigned
12850@opindex mloop-unsigned
12851@opindex mno-loop-unsigned
12852The maximum iteration count when using RPTS and RPTB (and DB on the C40)
12853is @math{2^{31} + 1} since these instructions test if the iteration count is
12854negative to terminate the loop. If the iteration count is unsigned
12855there is a possibility than the @math{2^{31} + 1} maximum iteration count may be
12856exceeded. This switch allows an unsigned iteration count.
12857
12858@item -mti
12859@opindex mti
12860Try to emit an assembler syntax that the TI assembler (asm30) is happy
12861with. This also enforces compatibility with the API employed by the TI
12862C3x C compiler. For example, long doubles are passed as structures
12863rather than in floating point registers.
12864
12865@item -mregparm
12866@itemx -mmemparm
12867@opindex mregparm
12868@opindex mmemparm
12869Generate code that uses registers (stack) for passing arguments to functions.
12870By default, arguments are passed in registers where possible rather
12871than by pushing arguments on to the stack.
12872
12873@item -mparallel-insns
12874@itemx -mno-parallel-insns
12875@opindex mparallel-insns
12876@opindex mno-parallel-insns
12877Allow the generation of parallel instructions. This is enabled by
12878default with @option{-O2}.
12879
12880@item -mparallel-mpy
12881@itemx -mno-parallel-mpy
12882@opindex mparallel-mpy
12883@opindex mno-parallel-mpy
12884Allow the generation of MPY||ADD and MPY||SUB parallel instructions,
12885provided @option{-mparallel-insns} is also specified. These instructions have
12886tight register constraints which can pessimize the code generation
12887of large functions.
12888
12889@end table
12890
12891@node V850 Options
12892@subsection V850 Options
12893@cindex V850 Options
12894
12895These @samp{-m} options are defined for V850 implementations:
12896
12897@table @gcctabopt
12898@item -mlong-calls
12899@itemx -mno-long-calls
12900@opindex mlong-calls
12901@opindex mno-long-calls
12902Treat all calls as being far away (near). If calls are assumed to be
12903far away, the compiler will always load the functions address up into a
12904register, and call indirect through the pointer.
12905
12906@item -mno-ep
12907@itemx -mep
12908@opindex mno-ep
12909@opindex mep
12910Do not optimize (do optimize) basic blocks that use the same index
12911pointer 4 or more times to copy pointer into the @code{ep} register, and
12912use the shorter @code{sld} and @code{sst} instructions. The @option{-mep}
12913option is on by default if you optimize.
12914
12915@item -mno-prolog-function
12916@itemx -mprolog-function
12917@opindex mno-prolog-function
12918@opindex mprolog-function
12919Do not use (do use) external functions to save and restore registers
12920at the prologue and epilogue of a function. The external functions
12921are slower, but use less code space if more than one function saves
12922the same number of registers. The @option{-mprolog-function} option
12923is on by default if you optimize.
12924
12925@item -mspace
12926@opindex mspace
12927Try to make the code as small as possible. At present, this just turns
12928on the @option{-mep} and @option{-mprolog-function} options.
12929
12930@item -mtda=@var{n}
12931@opindex mtda
12932Put static or global variables whose size is @var{n} bytes or less into
12933the tiny data area that register @code{ep} points to. The tiny data
12934area can hold up to 256 bytes in total (128 bytes for byte references).
12935
12936@item -msda=@var{n}
12937@opindex msda
12938Put static or global variables whose size is @var{n} bytes or less into
12939the small data area that register @code{gp} points to. The small data
12940area can hold up to 64 kilobytes.
12941
12942@item -mzda=@var{n}
12943@opindex mzda
12944Put static or global variables whose size is @var{n} bytes or less into
12945the first 32 kilobytes of memory.
12946
12947@item -mv850
12948@opindex mv850
12949Specify that the target processor is the V850.
12950
12951@item -mbig-switch
12952@opindex mbig-switch
12953Generate code suitable for big switch tables. Use this option only if
12954the assembler/linker complain about out of range branches within a switch
12955table.
12956
12957@item -mapp-regs
12958@opindex mapp-regs
12959This option will cause r2 and r5 to be used in the code generated by
12960the compiler. This setting is the default.
12961
12962@item -mno-app-regs
12963@opindex mno-app-regs
12964This option will cause r2 and r5 to be treated as fixed registers.
12965
12966@item -mv850e1
12967@opindex mv850e1
12968Specify that the target processor is the V850E1. The preprocessor
12969constants @samp{__v850e1__} and @samp{__v850e__} will be defined if
12970this option is used.
12971
12972@item -mv850e
12973@opindex mv850e
12974Specify that the target processor is the V850E@. The preprocessor
12975constant @samp{__v850e__} will be defined if this option is used.
12976
12977If neither @option{-mv850} nor @option{-mv850e} nor @option{-mv850e1}
12978are defined then a default target processor will be chosen and the
12979relevant @samp{__v850*__} preprocessor constant will be defined.
12980
12981The preprocessor constants @samp{__v850} and @samp{__v851__} are always
12982defined, regardless of which processor variant is the target.
12983
12984@item -mdisable-callt
12985@opindex mdisable-callt
12986This option will suppress generation of the CALLT instruction for the
12987v850e and v850e1 flavors of the v850 architecture. The default is
12988@option{-mno-disable-callt} which allows the CALLT instruction to be used.
12989
12990@end table
12991
12992@node VAX Options
12993@subsection VAX Options
12994@cindex VAX options
12995
12996These @samp{-m} options are defined for the VAX:
12997
12998@table @gcctabopt
12999@item -munix
13000@opindex munix
13001Do not output certain jump instructions (@code{aobleq} and so on)
13002that the Unix assembler for the VAX cannot handle across long
13003ranges.
13004
13005@item -mgnu
13006@opindex mgnu
13007Do output those jump instructions, on the assumption that you
13008will assemble with the GNU assembler.
13009
13010@item -mg
13011@opindex mg
13012Output code for g-format floating point numbers instead of d-format.
13013@end table
13014
13015@node x86-64 Options
13016@subsection x86-64 Options
13017@cindex x86-64 options
13018
13019These are listed under @xref{i386 and x86-64 Options}.
13020
13021@node Xstormy16 Options
13022@subsection Xstormy16 Options
13023@cindex Xstormy16 Options
13024
13025These options are defined for Xstormy16:
13026
13027@table @gcctabopt
13028@item -msim
13029@opindex msim
13030Choose startup files and linker script suitable for the simulator.
13031@end table
13032
13033@node Xtensa Options
13034@subsection Xtensa Options
13035@cindex Xtensa Options
13036
13037These options are supported for Xtensa targets:
13038
13039@table @gcctabopt
13040@item -mconst16
13041@itemx -mno-const16
13042@opindex mconst16
13043@opindex mno-const16
13044Enable or disable use of @code{CONST16} instructions for loading
13045constant values. The @code{CONST16} instruction is currently not a
13046standard option from Tensilica. When enabled, @code{CONST16}
13047instructions are always used in place of the standard @code{L32R}
13048instructions. The use of @code{CONST16} is enabled by default only if
13049the @code{L32R} instruction is not available.
13050
13051@item -mfused-madd
13052@itemx -mno-fused-madd
13053@opindex mfused-madd
13054@opindex mno-fused-madd
13055Enable or disable use of fused multiply/add and multiply/subtract
13056instructions in the floating-point option. This has no effect if the
13057floating-point option is not also enabled. Disabling fused multiply/add
13058and multiply/subtract instructions forces the compiler to use separate
13059instructions for the multiply and add/subtract operations. This may be
13060desirable in some cases where strict IEEE 754-compliant results are
13061required: the fused multiply add/subtract instructions do not round the
13062intermediate result, thereby producing results with @emph{more} bits of
13063precision than specified by the IEEE standard. Disabling fused multiply
13064add/subtract instructions also ensures that the program output is not
13065sensitive to the compiler's ability to combine multiply and add/subtract
13066operations.
13067
13068@item -mtext-section-literals
13069@itemx -mno-text-section-literals
13070@opindex mtext-section-literals
13071@opindex mno-text-section-literals
13072Control the treatment of literal pools. The default is
13073@option{-mno-text-section-literals}, which places literals in a separate
13074section in the output file. This allows the literal pool to be placed
13075in a data RAM/ROM, and it also allows the linker to combine literal
13076pools from separate object files to remove redundant literals and
13077improve code size. With @option{-mtext-section-literals}, the literals
13078are interspersed in the text section in order to keep them as close as
13079possible to their references. This may be necessary for large assembly
13080files.
13081
13082@item -mtarget-align
13083@itemx -mno-target-align
13084@opindex mtarget-align
13085@opindex mno-target-align
13086When this option is enabled, GCC instructs the assembler to
13087automatically align instructions to reduce branch penalties at the
13088expense of some code density. The assembler attempts to widen density
13089instructions to align branch targets and the instructions following call
13090instructions. If there are not enough preceding safe density
13091instructions to align a target, no widening will be performed. The
13092default is @option{-mtarget-align}. These options do not affect the
13093treatment of auto-aligned instructions like @code{LOOP}, which the
13094assembler will always align, either by widening density instructions or
13095by inserting no-op instructions.
13096
13097@item -mlongcalls
13098@itemx -mno-longcalls
13099@opindex mlongcalls
13100@opindex mno-longcalls
13101When this option is enabled, GCC instructs the assembler to translate
13102direct calls to indirect calls unless it can determine that the target
13103of a direct call is in the range allowed by the call instruction. This
13104translation typically occurs for calls to functions in other source
13105files. Specifically, the assembler translates a direct @code{CALL}
13106instruction into an @code{L32R} followed by a @code{CALLX} instruction.
13107The default is @option{-mno-longcalls}. This option should be used in
13108programs where the call target can potentially be out of range. This
13109option is implemented in the assembler, not the compiler, so the
13110assembly code generated by GCC will still show direct call
13111instructions---look at the disassembled object code to see the actual
13112instructions. Note that the assembler will use an indirect call for
13113every cross-file call, not just those that really will be out of range.
13114@end table
13115
13116@node zSeries Options
13117@subsection zSeries Options
13118@cindex zSeries options
13119
13120These are listed under @xref{S/390 and zSeries Options}.
13121
13122@node Code Gen Options
13123@section Options for Code Generation Conventions
13124@cindex code generation conventions
13125@cindex options, code generation
13126@cindex run-time options
13127
13128These machine-independent options control the interface conventions
13129used in code generation.
13130
13131Most of them have both positive and negative forms; the negative form
13132of @option{-ffoo} would be @option{-fno-foo}. In the table below, only
13133one of the forms is listed---the one which is not the default. You
13134can figure out the other form by either removing @samp{no-} or adding
13135it.
13136
13137@table @gcctabopt
13138@item -fbounds-check
13139@opindex fbounds-check
13140For front-ends that support it, generate additional code to check that
13141indices used to access arrays are within the declared range. This is
13142currently only supported by the Java and Fortran front-ends, where
13143this option defaults to true and false respectively.
13144
13145@item -ftrapv
13146@opindex ftrapv
13147This option generates traps for signed overflow on addition, subtraction,
13148multiplication operations.
13149
13150@item -fwrapv
13151@opindex fwrapv
13152This option instructs the compiler to assume that signed arithmetic
13153overflow of addition, subtraction and multiplication wraps around
13154using twos-complement representation. This flag enables some optimizations
13155and disables others. This option is enabled by default for the Java
13156front-end, as required by the Java language specification.
13157
13158@item -fexceptions
13159@opindex fexceptions
13160Enable exception handling. Generates extra code needed to propagate
13161exceptions. For some targets, this implies GCC will generate frame
13162unwind information for all functions, which can produce significant data
13163size overhead, although it does not affect execution. If you do not
13164specify this option, GCC will enable it by default for languages like
13165C++ which normally require exception handling, and disable it for
13166languages like C that do not normally require it. However, you may need
13167to enable this option when compiling C code that needs to interoperate
13168properly with exception handlers written in C++. You may also wish to
13169disable this option if you are compiling older C++ programs that don't
13170use exception handling.
13171
13172@item -fnon-call-exceptions
13173@opindex fnon-call-exceptions
13174Generate code that allows trapping instructions to throw exceptions.
13175Note that this requires platform-specific runtime support that does
13176not exist everywhere. Moreover, it only allows @emph{trapping}
13177instructions to throw exceptions, i.e.@: memory references or floating
13178point instructions. It does not allow exceptions to be thrown from
13179arbitrary signal handlers such as @code{SIGALRM}.
13180
13181@item -funwind-tables
13182@opindex funwind-tables
13183Similar to @option{-fexceptions}, except that it will just generate any needed
13184static data, but will not affect the generated code in any other way.
13185You will normally not enable this option; instead, a language processor
13186that needs this handling would enable it on your behalf.
13187
13188@item -fasynchronous-unwind-tables
13189@opindex fasynchronous-unwind-tables
13190Generate unwind table in dwarf2 format, if supported by target machine. The
13191table is exact at each instruction boundary, so it can be used for stack
13192unwinding from asynchronous events (such as debugger or garbage collector).
13193
13194@item -fpcc-struct-return
13195@opindex fpcc-struct-return
13196Return ``short'' @code{struct} and @code{union} values in memory like
13197longer ones, rather than in registers. This convention is less
13198efficient, but it has the advantage of allowing intercallability between
13199GCC-compiled files and files compiled with other compilers, particularly
13200the Portable C Compiler (pcc).
13201
13202The precise convention for returning structures in memory depends
13203on the target configuration macros.
13204
13205Short structures and unions are those whose size and alignment match
13206that of some integer type.
13207
13208@strong{Warning:} code compiled with the @option{-fpcc-struct-return}
13209switch is not binary compatible with code compiled with the
13210@option{-freg-struct-return} switch.
13211Use it to conform to a non-default application binary interface.
13212
13213@item -freg-struct-return
13214@opindex freg-struct-return
13215Return @code{struct} and @code{union} values in registers when possible.
13216This is more efficient for small structures than
13217@option{-fpcc-struct-return}.
13218
13219If you specify neither @option{-fpcc-struct-return} nor
13220@option{-freg-struct-return}, GCC defaults to whichever convention is
13221standard for the target. If there is no standard convention, GCC
13222defaults to @option{-fpcc-struct-return}, except on targets where GCC is
13223the principal compiler. In those cases, we can choose the standard, and
13224we chose the more efficient register return alternative.
13225
13226@strong{Warning:} code compiled with the @option{-freg-struct-return}
13227switch is not binary compatible with code compiled with the
13228@option{-fpcc-struct-return} switch.
13229Use it to conform to a non-default application binary interface.
13230
13231@item -fshort-enums
13232@opindex fshort-enums
13233Allocate to an @code{enum} type only as many bytes as it needs for the
13234declared range of possible values. Specifically, the @code{enum} type
13235will be equivalent to the smallest integer type which has enough room.
13236
13237@strong{Warning:} the @option{-fshort-enums} 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-double
13242@opindex fshort-double
13243Use the same size for @code{double} as for @code{float}.
13244
13245@strong{Warning:} the @option{-fshort-double} switch causes GCC to generate
13246code that is not binary compatible with code generated without that switch.
13247Use it to conform to a non-default application binary interface.
13248
13249@item -fshort-wchar
13250@opindex fshort-wchar
13251Override the underlying type for @samp{wchar_t} to be @samp{short
13252unsigned int} instead of the default for the target. This option is
13253useful for building programs to run under WINE@.
13254
13255@strong{Warning:} the @option{-fshort-wchar} switch causes GCC to generate
13256code that is not binary compatible with code generated without that switch.
13257Use it to conform to a non-default application binary interface.
13258
13259@item -fno-common
13260@opindex fno-common
13261In C, allocate even uninitialized global variables in the data section of the
13262object file, rather than generating them as common blocks. This has the
13263effect that if the same variable is declared (without @code{extern}) in
13264two different compilations, you will get an error when you link them.
13265The only reason this might be useful is if you wish to verify that the
13266program will work on other systems which always work this way.
13267
13268@item -fno-ident
13269@opindex fno-ident
13270Ignore the @samp{#ident} directive.
13271
13272@item -finhibit-size-directive
13273@opindex finhibit-size-directive
13274Don't output a @code{.size} assembler directive, or anything else that
13275would cause trouble if the function is split in the middle, and the
13276two halves are placed at locations far apart in memory. This option is
13277used when compiling @file{crtstuff.c}; you should not need to use it
13278for anything else.
13279
13280@item -fverbose-asm
13281@opindex fverbose-asm
13282Put extra commentary information in the generated assembly code to
13283make it more readable. This option is generally only of use to those
13284who actually need to read the generated assembly code (perhaps while
13285debugging the compiler itself).
13286
13287@option{-fno-verbose-asm}, the default, causes the
13288extra information to be omitted and is useful when comparing two assembler
13289files.
13290
13291@item -fpic
13292@opindex fpic
13293@cindex global offset table
13294@cindex PIC
13295Generate position-independent code (PIC) suitable for use in a shared
13296library, if supported for the target machine. Such code accesses all
13297constant addresses through a global offset table (GOT)@. The dynamic
13298loader resolves the GOT entries when the program starts (the dynamic
13299loader is not part of GCC; it is part of the operating system). If
13300the GOT size for the linked executable exceeds a machine-specific
13301maximum size, you get an error message from the linker indicating that
13302@option{-fpic} does not work; in that case, recompile with @option{-fPIC}
13303instead. (These maximums are 8k on the SPARC and 32k
13304on the m68k and RS/6000. The 386 has no such limit.)
13305
13306Position-independent code requires special support, and therefore works
13307only on certain machines. For the 386, GCC supports PIC for System V
13308but not for the Sun 386i. Code generated for the IBM RS/6000 is always
13309position-independent.
13310
13311When this flag is set, the macros @code{__pic__} and @code{__PIC__}
13312are defined to 1.
13313
13314@item -fPIC
13315@opindex fPIC
13316If supported for the target machine, emit position-independent code,
13317suitable for dynamic linking and avoiding any limit on the size of the
13318global offset table. This option makes a difference on the m68k,
13319PowerPC and SPARC@.
13320
13321Position-independent code requires special support, and therefore works
13322only on certain machines.
13323
13324When this flag is set, the macros @code{__pic__} and @code{__PIC__}
13325are defined to 2.
13326
13327@item -fpie
13328@itemx -fPIE
13329@opindex fpie
13330@opindex fPIE
13331These options are similar to @option{-fpic} and @option{-fPIC}, but
13332generated position independent code can be only linked into executables.
13333Usually these options are used when @option{-pie} GCC option will be
13334used during linking.
13335
13336@item -fno-jump-tables
13337@opindex fno-jump-tables
13338Do not use jump tables for switch statements even where it would be
13339more efficient than other code generation strategies. This option is
13340of use in conjunction with @option{-fpic} or @option{-fPIC} for
13341building code which forms part of a dynamic linker and cannot
13342reference the address of a jump table. On some targets, jump tables
13343do not require a GOT and this option is not needed.
13344
13345@item -ffixed-@var{reg}
13346@opindex ffixed
13347Treat the register named @var{reg} as a fixed register; generated code
13348should never refer to it (except perhaps as a stack pointer, frame
13349pointer or in some other fixed role).
13350
13351@var{reg} must be the name of a register. The register names accepted
13352are machine-specific and are defined in the @code{REGISTER_NAMES}
13353macro in the machine description macro file.
13354
13355This flag does not have a negative form, because it specifies a
13356three-way choice.
13357
13358@item -fcall-used-@var{reg}
13359@opindex fcall-used
13360Treat the register named @var{reg} as an allocable register that is
13361clobbered by function calls. It may be allocated for temporaries or
13362variables that do not live across a call. Functions compiled this way
13363will not save and restore the register @var{reg}.
13364
13365It is an error to used this flag with the frame pointer or stack pointer.
13366Use of this flag for other registers that have fixed pervasive roles in
13367the machine's execution model will produce disastrous results.
13368
13369This flag does not have a negative form, because it specifies a
13370three-way choice.
13371
13372@item -fcall-saved-@var{reg}
13373@opindex fcall-saved
13374Treat the register named @var{reg} as an allocable register saved by
13375functions. It may be allocated even for temporaries or variables that
13376live across a call. Functions compiled this way will save and restore
13377the register @var{reg} if they use it.
13378
13379It is an error to used this flag with the frame pointer or stack pointer.
13380Use of this flag for other registers that have fixed pervasive roles in
13381the machine's execution model will produce disastrous results.
13382
13383A different sort of disaster will result from the use of this flag for
13384a register in which function values may be returned.
13385
13386This flag does not have a negative form, because it specifies a
13387three-way choice.
13388
13389@item -fpack-struct[=@var{n}]
13390@opindex fpack-struct
13391Without a value specified, pack all structure members together without
13392holes. When a value is specified (which must be a small power of two), pack
13393structure members according to this value, representing the maximum
13394alignment (that is, objects with default alignment requirements larger than
13395this will be output potentially unaligned at the next fitting location.
13396
13397@strong{Warning:} the @option{-fpack-struct} switch causes GCC to generate
13398code that is not binary compatible with code generated without that switch.
13399Additionally, it makes the code suboptimal.
13400Use it to conform to a non-default application binary interface.
13401
13402@item -finstrument-functions
13403@opindex finstrument-functions
13404Generate instrumentation calls for entry and exit to functions. Just
13405after function entry and just before function exit, the following
13406profiling functions will be called with the address of the current
13407function and its call site. (On some platforms,
13408@code{__builtin_return_address} does not work beyond the current
13409function, so the call site information may not be available to the
13410profiling functions otherwise.)
13411
13412@smallexample
13413void __cyg_profile_func_enter (void *this_fn,
13414 void *call_site);
13415void __cyg_profile_func_exit (void *this_fn,
13416 void *call_site);
13417@end smallexample
13418
13419The first argument is the address of the start of the current function,
13420which may be looked up exactly in the symbol table.
13421
13422This instrumentation is also done for functions expanded inline in other
13423functions. The profiling calls will indicate where, conceptually, the
13424inline function is entered and exited. This means that addressable
13425versions of such functions must be available. If all your uses of a
13426function are expanded inline, this may mean an additional expansion of
13427code size. If you use @samp{extern inline} in your C code, an
13428addressable version of such functions must be provided. (This is
13429normally the case anyways, but if you get lucky and the optimizer always
13430expands the functions inline, you might have gotten away without
13431providing static copies.)
13432
13433A function may be given the attribute @code{no_instrument_function}, in
13434which case this instrumentation will not be done. This can be used, for
13435example, for the profiling functions listed above, high-priority
13436interrupt routines, and any functions from which the profiling functions
13437cannot safely be called (perhaps signal handlers, if the profiling
13438routines generate output or allocate memory).
13439
13440@item -finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{}
13441@opindex finstrument-functions-exclude-file-list
13442
13443Set the list of functions that are excluded from instrumentation (see
13444the description of @code{-finstrument-functions}). If the file that
13445contains a function definition matches with one of @var{file}, then
13446that function is not instrumented. The match is done on substrings:
13447if the @var{file} parameter is a substring of the file name, it is
13448considered to be a match.
13449
13450For example,
13451@code{-finstrument-functions-exclude-file-list=/bits/stl,include/sys}
13452will exclude any inline function defined in files whose pathnames
13453contain @code{/bits/stl} or @code{include/sys}.
13454
13455If, for some reason, you want to include letter @code{','} in one of
13456@var{sym}, write @code{'\,'}. For example,
13457@code{-finstrument-functions-exclude-file-list='\,\,tmp'}
13458(note the single quote surrounding the option).
13459
13460@item -finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{}
13461@opindex finstrument-functions-exclude-function-list
13462
13463This is similar to @code{-finstrument-functions-exclude-file-list},
13464but this option sets the list of function names to be excluded from
13465instrumentation. The function name to be matched is its user-visible
13466name, such as @code{vector<int> blah(const vector<int> &)}, not the
13467internal mangled name (e.g., @code{_Z4blahRSt6vectorIiSaIiEE}). The
13468match is done on substrings: if the @var{sym} parameter is a substring
13469of the function name, it is considered to be a match.
13470
13471@item -fstack-check
13472@opindex fstack-check
13473Generate code to verify that you do not go beyond the boundary of the
13474stack. You should specify this flag if you are running in an
13475environment with multiple threads, but only rarely need to specify it in
13476a single-threaded environment since stack overflow is automatically
13477detected on nearly all systems if there is only one stack.
13478
13479Note that this switch does not actually cause checking to be done; the
13480operating system must do that. The switch causes generation of code
13481to ensure that the operating system sees the stack being extended.
13482
13483@item -fstack-limit-register=@var{reg}
13484@itemx -fstack-limit-symbol=@var{sym}
13485@itemx -fno-stack-limit
13486@opindex fstack-limit-register
13487@opindex fstack-limit-symbol
13488@opindex fno-stack-limit
13489Generate code to ensure that the stack does not grow beyond a certain value,
13490either the value of a register or the address of a symbol. If the stack
13491would grow beyond the value, a signal is raised. For most targets,
13492the signal is raised before the stack overruns the boundary, so
13493it is possible to catch the signal without taking special precautions.
13494
13495For instance, if the stack starts at absolute address @samp{0x80000000}
13496and grows downwards, you can use the flags
13497@option{-fstack-limit-symbol=__stack_limit} and
13498@option{-Wl,--defsym,__stack_limit=0x7ffe0000} to enforce a stack limit
13499of 128KB@. Note that this may only work with the GNU linker.
13500
13501@cindex aliasing of parameters
13502@cindex parameters, aliased
13503@item -fargument-alias
13504@itemx -fargument-noalias
13505@itemx -fargument-noalias-global
13506@itemx -fargument-noalias-anything
13507@opindex fargument-alias
13508@opindex fargument-noalias
13509@opindex fargument-noalias-global
13510@opindex fargument-noalias-anything
13511Specify the possible relationships among parameters and between
13512parameters and global data.
13513
13514@option{-fargument-alias} specifies that arguments (parameters) may
13515alias each other and may alias global storage.@*
13516@option{-fargument-noalias} specifies that arguments do not alias
13517each other, but may alias global storage.@*
13518@option{-fargument-noalias-global} specifies that arguments do not
13519alias each other and do not alias global storage.
13520@option{-fargument-noalias-anything} specifies that arguments do not
13521alias any other storage.
13522
13523Each language will automatically use whatever option is required by
13524the language standard. You should not need to use these options yourself.
13525
13526@item -fleading-underscore
13527@opindex fleading-underscore
13528This option and its counterpart, @option{-fno-leading-underscore}, forcibly
13529change the way C symbols are represented in the object file. One use
13530is to help link with legacy assembly code.
13531
13532@strong{Warning:} the @option{-fleading-underscore} switch causes GCC to
13533generate code that is not binary compatible with code generated without that
13534switch. Use it to conform to a non-default application binary interface.
13535Not all targets provide complete support for this switch.
13536
13537@item -ftls-model=@var{model}
13538Alter the thread-local storage model to be used (@pxref{Thread-Local}).
13539The @var{model} argument should be one of @code{global-dynamic},
13540@code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
13541
13542The default without @option{-fpic} is @code{initial-exec}; with
13543@option{-fpic} the default is @code{global-dynamic}.
13544
13545@item -fvisibility=@var{default|internal|hidden|protected}
13546@opindex fvisibility
13547Set the default ELF image symbol visibility to the specified option---all
13548symbols will be marked with this unless overridden within the code.
13549Using this feature can very substantially improve linking and
13550load times of shared object libraries, produce more optimized
13551code, provide near-perfect API export and prevent symbol clashes.
13552It is @strong{strongly} recommended that you use this in any shared objects
13553you distribute.
13554
13555Despite the nomenclature, @code{default} always means public ie;
13556available to be linked against from outside the shared object.
13557@code{protected} and @code{internal} are pretty useless in real-world
13558usage so the only other commonly used option will be @code{hidden}.
13559The default if @option{-fvisibility} isn't specified is
13560@code{default}, i.e., make every
13561symbol public---this causes the same behavior as previous versions of
13562GCC@.
13563
13564A good explanation of the benefits offered by ensuring ELF
13565symbols have the correct visibility is given by ``How To Write
13566Shared Libraries'' by Ulrich Drepper (which can be found at
13567@w{@uref{http://people.redhat.com/~drepper/}})---however a superior
13568solution made possible by this option to marking things hidden when
13569the default is public is to make the default hidden and mark things
13570public. This is the norm with DLL's on Windows and with @option{-fvisibility=hidden}
13571and @code{__attribute__ ((visibility("default")))} instead of
13572@code{__declspec(dllexport)} you get almost identical semantics with
13573identical syntax. This is a great boon to those working with
13574cross-platform projects.
13575
13576For those adding visibility support to existing code, you may find
13577@samp{#pragma GCC visibility} of use. This works by you enclosing
13578the declarations you wish to set visibility for with (for example)
13579@samp{#pragma GCC visibility push(hidden)} and
13580@samp{#pragma GCC visibility pop}.
13581Bear in mind that symbol visibility should be viewed @strong{as
13582part of the API interface contract} and thus all new code should
13583always specify visibility when it is not the default ie; declarations
13584only for use within the local DSO should @strong{always} be marked explicitly
13585as hidden as so to avoid PLT indirection overheads---making this
13586abundantly clear also aids readability and self-documentation of the code.
13587Note that due to ISO C++ specification requirements, operator new and
13588operator delete must always be of default visibility.
13589
13590Be aware that headers from outside your project, in particular system
13591headers and headers from any other library you use, may not be
13592expecting to be compiled with visibility other than the default. You
13593may need to explicitly say @samp{#pragma GCC visibility push(default)}
13594before including any such headers.
13595
13596@samp{extern} declarations are not affected by @samp{-fvisibility}, so
13597a lot of code can be recompiled with @samp{-fvisibility=hidden} with
13598no modifications. However, this means that calls to @samp{extern}
13599functions with no explicit visibility will use the PLT, so it is more
13600effective to use @samp{__attribute ((visibility))} and/or
13601@samp{#pragma GCC visibility} to tell the compiler which @samp{extern}
13602declarations should be treated as hidden.
13603
13604Note that @samp{-fvisibility} does affect C++ vague linkage
13605entities. This means that, for instance, an exception class that will
13606be thrown between DSOs must be explicitly marked with default
13607visibility so that the @samp{type_info} nodes will be unified between
13608the DSOs.
13609
13610An overview of these techniques, their benefits and how to use them
13611is at @w{@uref{http://gcc.gnu.org/wiki/Visibility}}.
13612
13613@end table
13614
13615@c man end
13616
13617@node Environment Variables
13618@section Environment Variables Affecting GCC
13619@cindex environment variables
13620
13621@c man begin ENVIRONMENT
13622This section describes several environment variables that affect how GCC
13623operates. Some of them work by specifying directories or prefixes to use
13624when searching for various kinds of files. Some are used to specify other
13625aspects of the compilation environment.
13626
13627Note that you can also specify places to search using options such as
13628@option{-B}, @option{-I} and @option{-L} (@pxref{Directory Options}). These
13629take precedence over places specified using environment variables, which
13630in turn take precedence over those specified by the configuration of GCC@.
13631@xref{Driver,, Controlling the Compilation Driver @file{gcc}, gccint,
13632GNU Compiler Collection (GCC) Internals}.
13633
13634@table @env
13635@item LANG
13636@itemx LC_CTYPE
13637@c @itemx LC_COLLATE
13638@itemx LC_MESSAGES
13639@c @itemx LC_MONETARY
13640@c @itemx LC_NUMERIC
13641@c @itemx LC_TIME
13642@itemx LC_ALL
13643@findex LANG
13644@findex LC_CTYPE
13645@c @findex LC_COLLATE
13646@findex LC_MESSAGES
13647@c @findex LC_MONETARY
13648@c @findex LC_NUMERIC
13649@c @findex LC_TIME
13650@findex LC_ALL
13651@cindex locale
13652These environment variables control the way that GCC uses
13653localization information that allow GCC to work with different
13654national conventions. GCC inspects the locale categories
13655@env{LC_CTYPE} and @env{LC_MESSAGES} if it has been configured to do
13656so. These locale categories can be set to any value supported by your
13657installation. A typical value is @samp{en_GB.UTF-8} for English in the United
13658Kingdom encoded in UTF-8.
13659
13660The @env{LC_CTYPE} environment variable specifies character
13661classification. GCC uses it to determine the character boundaries in
13662a string; this is needed for some multibyte encodings that contain quote
13663and escape characters that would otherwise be interpreted as a string
13664end or escape.
13665
13666The @env{LC_MESSAGES} environment variable specifies the language to
13667use in diagnostic messages.
13668
13669If the @env{LC_ALL} environment variable is set, it overrides the value
13670of @env{LC_CTYPE} and @env{LC_MESSAGES}; otherwise, @env{LC_CTYPE}
13671and @env{LC_MESSAGES} default to the value of the @env{LANG}
13672environment variable. If none of these variables are set, GCC
13673defaults to traditional C English behavior.
13674
13675@item TMPDIR
13676@findex TMPDIR
13677If @env{TMPDIR} is set, it specifies the directory to use for temporary
13678files. GCC uses temporary files to hold the output of one stage of
13679compilation which is to be used as input to the next stage: for example,
13680the output of the preprocessor, which is the input to the compiler
13681proper.
13682
13683@item GCC_EXEC_PREFIX
13684@findex GCC_EXEC_PREFIX
13685If @env{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the
13686names of the subprograms executed by the compiler. No slash is added
13687when this prefix is combined with the name of a subprogram, but you can
13688specify a prefix that ends with a slash if you wish.
13689
13690If @env{GCC_EXEC_PREFIX} is not set, GCC will attempt to figure out
13691an appropriate prefix to use based on the pathname it was invoked with.
13692
13693If GCC cannot find the subprogram using the specified prefix, it
13694tries looking in the usual places for the subprogram.
13695
13696The default value of @env{GCC_EXEC_PREFIX} is
13697@file{@var{prefix}/lib/gcc/} where @var{prefix} is the value
13698of @code{prefix} when you ran the @file{configure} script.
13699
13700Other prefixes specified with @option{-B} take precedence over this prefix.
13701
13702This prefix is also used for finding files such as @file{crt0.o} that are
13703used for linking.
13704
13705In addition, the prefix is used in an unusual way in finding the
13706directories to search for header files. For each of the standard
13707directories whose name normally begins with @samp{/usr/local/lib/gcc}
13708(more precisely, with the value of @env{GCC_INCLUDE_DIR}), GCC tries
13709replacing that beginning with the specified prefix to produce an
13710alternate directory name. Thus, with @option{-Bfoo/}, GCC will search
13711@file{foo/bar} where it would normally search @file{/usr/local/lib/bar}.
13712These alternate directories are searched first; the standard directories
13713come next.
13714
13715@item COMPILER_PATH
13716@findex COMPILER_PATH
13717The value of @env{COMPILER_PATH} is a colon-separated list of
13718directories, much like @env{PATH}. GCC tries the directories thus
13719specified when searching for subprograms, if it can't find the
13720subprograms using @env{GCC_EXEC_PREFIX}.
13721
13722@item LIBRARY_PATH
13723@findex LIBRARY_PATH
13724The value of @env{LIBRARY_PATH} is a colon-separated list of
13725directories, much like @env{PATH}. When configured as a native compiler,
13726GCC tries the directories thus specified when searching for special
13727linker files, if it can't find them using @env{GCC_EXEC_PREFIX}. Linking
13728using GCC also uses these directories when searching for ordinary
13729libraries for the @option{-l} option (but directories specified with
13730@option{-L} come first).
13731
13732@item LANG
13733@findex LANG
13734@cindex locale definition
13735This variable is used to pass locale information to the compiler. One way in
13736which this information is used is to determine the character set to be used
13737when character literals, string literals and comments are parsed in C and C++.
13738When the compiler is configured to allow multibyte characters,
13739the following values for @env{LANG} are recognized:
13740
13741@table @samp
13742@item C-JIS
13743Recognize JIS characters.
13744@item C-SJIS
13745Recognize SJIS characters.
13746@item C-EUCJP
13747Recognize EUCJP characters.
13748@end table
13749
13750If @env{LANG} is not defined, or if it has some other value, then the
13751compiler will use mblen and mbtowc as defined by the default locale to
13752recognize and translate multibyte characters.
13753@end table
13754
13755@noindent
13756Some additional environments variables affect the behavior of the
13757preprocessor.
13758
13759@include cppenv.texi
13760
13761@c man end
13762
13763@node Precompiled Headers
13764@section Using Precompiled Headers
13765@cindex precompiled headers
13766@cindex speed of compilation
13767
13768Often large projects have many header files that are included in every
13769source file. The time the compiler takes to process these header files
13770over and over again can account for nearly all of the time required to
13771build the project. To make builds faster, GCC allows users to
13772`precompile' a header file; then, if builds can use the precompiled
13773header file they will be much faster.
13774
13775To create a precompiled header file, simply compile it as you would any
13776other file, if necessary using the @option{-x} option to make the driver
13777treat it as a C or C++ header file. You will probably want to use a
13778tool like @command{make} to keep the precompiled header up-to-date when
13779the headers it contains change.
13780
13781A precompiled header file will be searched for when @code{#include} is
13782seen in the compilation. As it searches for the included file
13783(@pxref{Search Path,,Search Path,cpp,The C Preprocessor}) the
13784compiler looks for a precompiled header in each directory just before it
13785looks for the include file in that directory. The name searched for is
13786the name specified in the @code{#include} with @samp{.gch} appended. If
13787the precompiled header file can't be used, it is ignored.
13788
13789For instance, if you have @code{#include "all.h"}, and you have
13790@file{all.h.gch} in the same directory as @file{all.h}, then the
13791precompiled header file will be used if possible, and the original
13792header will be used otherwise.
13793
13794Alternatively, you might decide to put the precompiled header file in a
13795directory and use @option{-I} to ensure that directory is searched
13796before (or instead of) the directory containing the original header.
13797Then, if you want to check that the precompiled header file is always
13798used, you can put a file of the same name as the original header in this
13799directory containing an @code{#error} command.
13800
13801This also works with @option{-include}. So yet another way to use
13802precompiled headers, good for projects not designed with precompiled
13803header files in mind, is to simply take most of the header files used by
13804a project, include them from another header file, precompile that header
13805file, and @option{-include} the precompiled header. If the header files
13806have guards against multiple inclusion, they will be skipped because
13807they've already been included (in the precompiled header).
13808
13809If you need to precompile the same header file for different
13810languages, targets, or compiler options, you can instead make a
13811@emph{directory} named like @file{all.h.gch}, and put each precompiled
13812header in the directory, perhaps using @option{-o}. It doesn't matter
13813what you call the files in the directory, every precompiled header in
13814the directory will be considered. The first precompiled header
13815encountered in the directory that is valid for this compilation will
13816be used; they're searched in no particular order.
13817
13818There are many other possibilities, limited only by your imagination,
13819good sense, and the constraints of your build system.
13820
13821A precompiled header file can be used only when these conditions apply:
13822
13823@itemize
13824@item
13825Only one precompiled header can be used in a particular compilation.
13826
13827@item
13828A precompiled header can't be used once the first C token is seen. You
13829can have preprocessor directives before a precompiled header; you can
13830even include a precompiled header from inside another header, so long as
13831there are no C tokens before the @code{#include}.
13832
13833@item
13834The precompiled header file must be produced for the same language as
13835the current compilation. You can't use a C precompiled header for a C++
13836compilation.
13837
13838@item
13839The precompiled header file must have been produced by the same compiler
13840binary as the current compilation is using.
13841
13842@item
13843Any macros defined before the precompiled header is included must
13844either be defined in the same way as when the precompiled header was
13845generated, or must not affect the precompiled header, which usually
13846means that they don't appear in the precompiled header at all.
13847
13848The @option{-D} option is one way to define a macro before a
13849precompiled header is included; using a @code{#define} can also do it.
13850There are also some options that define macros implicitly, like
13851@option{-O} and @option{-Wdeprecated}; the same rule applies to macros
13852defined this way.
13853
13854@item If debugging information is output when using the precompiled
13855header, using @option{-g} or similar, the same kind of debugging information
13856must have been output when building the precompiled header. However,
13857a precompiled header built using @option{-g} can be used in a compilation
13858when no debugging information is being output.
13859
13860@item The same @option{-m} options must generally be used when building
13861and using the precompiled header. @xref{Submodel Options},
13862for any cases where this rule is relaxed.
13863
13864@item Each of the following options must be the same when building and using
13865the precompiled header:
13866
13867@gccoptlist{-fexceptions -funit-at-a-time}
13868
13869@item
13870Some other command-line options starting with @option{-f},
13871@option{-p}, or @option{-O} must be defined in the same way as when
13872the precompiled header was generated. At present, it's not clear
13873which options are safe to change and which are not; the safest choice
13874is to use exactly the same options when generating and using the
13875precompiled header. The following are known to be safe:
13876
13877@gccoptlist{-fmessage-length= -fpreprocessed
13878-fsched-interblock -fsched-spec -fsched-spec-load -fsched-spec-load-dangerous
13879-fsched-verbose=<number> -fschedule-insns -fvisibility=
13880-pedantic-errors}
13881
13882@end itemize
13883
13884For all of these except the last, the compiler will automatically
13885ignore the precompiled header if the conditions aren't met. If you
13886find an option combination that doesn't work and doesn't cause the
13887precompiled header to be ignored, please consider filing a bug report,
13888see @ref{Bugs}.
13889
13890If you do use differing options when generating and using the
13891precompiled header, the actual behavior will be a mixture of the
13892behavior for the options. For instance, if you use @option{-g} to
13893generate the precompiled header but not when using it, you may or may
13894not get debugging information for routines in the precompiled header.
13895
13896@node Running Protoize
13897@section Running Protoize
13898
13899The program @code{protoize} is an optional part of GCC@. You can use
13900it to add prototypes to a program, thus converting the program to ISO
13901C in one respect. The companion program @code{unprotoize} does the
13902reverse: it removes argument types from any prototypes that are found.
13903
13904When you run these programs, you must specify a set of source files as
13905command line arguments. The conversion programs start out by compiling
13906these files to see what functions they define. The information gathered
13907about a file @var{foo} is saved in a file named @file{@var{foo}.X}.
13908
13909After scanning comes actual conversion. The specified files are all
13910eligible to be converted; any files they include (whether sources or
13911just headers) are eligible as well.
13912
13913But not all the eligible files are converted. By default,
13914@code{protoize} and @code{unprotoize} convert only source and header
13915files in the current directory. You can specify additional directories
13916whose files should be converted with the @option{-d @var{directory}}
13917option. You can also specify particular files to exclude with the
13918@option{-x @var{file}} option. A file is converted if it is eligible, its
13919directory name matches one of the specified directory names, and its
13920name within the directory has not been excluded.
13921
13922Basic conversion with @code{protoize} consists of rewriting most
13923function definitions and function declarations to specify the types of
13924the arguments. The only ones not rewritten are those for varargs
13925functions.
13926
13927@code{protoize} optionally inserts prototype declarations at the
13928beginning of the source file, to make them available for any calls that
13929precede the function's definition. Or it can insert prototype
13930declarations with block scope in the blocks where undeclared functions
13931are called.
13932
13933Basic conversion with @code{unprotoize} consists of rewriting most
13934function declarations to remove any argument types, and rewriting
13935function definitions to the old-style pre-ISO form.
13936
13937Both conversion programs print a warning for any function declaration or
13938definition that they can't convert. You can suppress these warnings
13939with @option{-q}.
13940
13941The output from @code{protoize} or @code{unprotoize} replaces the
13942original source file. The original file is renamed to a name ending
13943with @samp{.save} (for DOS, the saved filename ends in @samp{.sav}
13944without the original @samp{.c} suffix). If the @samp{.save} (@samp{.sav}
13945for DOS) file already exists, then the source file is simply discarded.
13946
13947@code{protoize} and @code{unprotoize} both depend on GCC itself to
13948scan the program and collect information about the functions it uses.
13949So neither of these programs will work until GCC is installed.
13950
13951Here is a table of the options you can use with @code{protoize} and
13952@code{unprotoize}. Each option works with both programs unless
13953otherwise stated.
13954
13955@table @code
13956@item -B @var{directory}
13957Look for the file @file{SYSCALLS.c.X} in @var{directory}, instead of the
13958usual directory (normally @file{/usr/local/lib}). This file contains
13959prototype information about standard system functions. This option
13960applies only to @code{protoize}.
13961
13962@item -c @var{compilation-options}
13963Use @var{compilation-options} as the options when running @command{gcc} to
13964produce the @samp{.X} files. The special option @option{-aux-info} is
13965always passed in addition, to tell @command{gcc} to write a @samp{.X} file.
13966
13967Note that the compilation options must be given as a single argument to
13968@code{protoize} or @code{unprotoize}. If you want to specify several
13969@command{gcc} options, you must quote the entire set of compilation options
13970to make them a single word in the shell.
13971
13972There are certain @command{gcc} arguments that you cannot use, because they
13973would produce the wrong kind of output. These include @option{-g},
13974@option{-O}, @option{-c}, @option{-S}, and @option{-o} If you include these in
13975the @var{compilation-options}, they are ignored.
13976
13977@item -C
13978Rename files to end in @samp{.C} (@samp{.cc} for DOS-based file
13979systems) instead of @samp{.c}. This is convenient if you are converting
13980a C program to C++. This option applies only to @code{protoize}.
13981
13982@item -g
13983Add explicit global declarations. This means inserting explicit
13984declarations at the beginning of each source file for each function
13985that is called in the file and was not declared. These declarations
13986precede the first function definition that contains a call to an
13987undeclared function. This option applies only to @code{protoize}.
13988
13989@item -i @var{string}
13990Indent old-style parameter declarations with the string @var{string}.
13991This option applies only to @code{protoize}.
13992
13993@code{unprotoize} converts prototyped function definitions to old-style
13994function definitions, where the arguments are declared between the
13995argument list and the initial @samp{@{}. By default, @code{unprotoize}
13996uses five spaces as the indentation. If you want to indent with just
13997one space instead, use @option{-i " "}.
13998
13999@item -k
14000Keep the @samp{.X} files. Normally, they are deleted after conversion
14001is finished.
14002
14003@item -l
14004Add explicit local declarations. @code{protoize} with @option{-l} inserts
14005a prototype declaration for each function in each block which calls the
14006function without any declaration. This option applies only to
14007@code{protoize}.
14008
14009@item -n
14010Make no real changes. This mode just prints information about the conversions
14011that would have been done without @option{-n}.
14012
14013@item -N
14014Make no @samp{.save} files. The original files are simply deleted.
14015Use this option with caution.
14016
14017@item -p @var{program}
14018Use the program @var{program} as the compiler. Normally, the name
14019@file{gcc} is used.
14020
14021@item -q
14022Work quietly. Most warnings are suppressed.
14023
14024@item -v
14025Print the version number, just like @option{-v} for @command{gcc}.
14026@end table
14027
14028If you need special compiler options to compile one of your program's
14029source files, then you should generate that file's @samp{.X} file
14030specially, by running @command{gcc} on that source file with the
14031appropriate options and the option @option{-aux-info}. Then run
14032@code{protoize} on the entire set of files. @code{protoize} will use
14033the existing @samp{.X} file because it is newer than the source file.
14034For example:
14035
14036@smallexample
14037gcc -Dfoo=bar file1.c -aux-info file1.X
14038protoize *.c
14039@end smallexample
14040
14041@noindent
14042You need to include the special files along with the rest in the
14043@code{protoize} command, even though their @samp{.X} files already
14044exist, because otherwise they won't get converted.
14045
14046@xref{Protoize Caveats}, for more information on how to use
14047@code{protoize} successfully.
14048
|