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
|