1 @c Copyright (C) 1988,89,92,93,94,95,96,97,1998 Free Software Foundation, Inc.
2 @c This is part of the GCC manual.
3 @c For copying conditions, see the file gcc.texi.
6 @chapter GNU CC Command Options
7 @cindex GNU CC command options
8 @cindex command options
9 @cindex options, GNU CC command
11 When you invoke GNU CC, it normally does preprocessing, compilation,
12 assembly and linking. The ``overall options'' allow you to stop this
13 process at an intermediate stage. For example, the @samp{-c} option
14 says not to run the linker. Then the output consists of object files
15 output by the assembler.
17 Other options are passed on to one stage of processing. Some options
18 control the preprocessor and others the compiler itself. Yet other
19 options control the assembler and linker; most of these are not
20 documented here, since you rarely need to use any of them.
22 @cindex C compilation options
23 Most of the command line options that you can use with GNU CC are useful
24 for C programs; when an option is only useful with another language
25 (usually C++), the explanation says so explicitly. If the description
26 for a particular option does not mention a source language, you can use
27 that option with all supported languages.
29 @cindex C++ compilation options
30 @xref{Invoking G++,,Compiling C++ Programs}, for a summary of special
31 options for compiling C++ programs.
33 @cindex grouping options
34 @cindex options, grouping
35 The @code{gcc} program accepts options and file names as operands. Many
36 options have multiletter names; therefore multiple single-letter options
37 may @emph{not} be grouped: @samp{-dr} is very different from @w{@samp{-d
40 @cindex order of options
41 @cindex options, order
42 You can mix options and other arguments. For the most part, the order
43 you use doesn't matter. Order does matter when you use several options
44 of the same kind; for example, if you specify @samp{-L} more than once,
45 the directories are searched in the order specified.
47 Many options have long names starting with @samp{-f} or with
48 @samp{-W}---for example, @samp{-fforce-mem},
49 @samp{-fstrength-reduce}, @samp{-Wformat} and so on. Most of
50 these have both positive and negative forms; the negative form of
51 @samp{-ffoo} would be @samp{-fno-foo}. This manual documents
52 only one of these two forms, whichever one is not the default.
55 * Option Summary:: Brief list of all options, without explanations.
56 * Overall Options:: Controlling the kind of output:
57 an executable, object files, assembler files,
58 or preprocessed source.
59 * Invoking G++:: Compiling C++ programs.
60 * C Dialect Options:: Controlling the variant of C language compiled.
61 * C++ Dialect Options:: Variations on C++.
62 * Warning Options:: How picky should the compiler be?
63 * Debugging Options:: Symbol tables, measurements, and debugging dumps.
64 * Optimize Options:: How much optimization?
65 * Preprocessor Options:: Controlling header files and macro definitions.
66 Also, getting dependency information for Make.
67 * Assembler Options:: Passing options to the assembler.
68 * Link Options:: Specifying libraries and so on.
69 * Directory Options:: Where to find header files and libraries.
70 Where to find the compiler executable files.
71 * Target Options:: Running a cross-compiler, or an old version of GNU CC.
72 * Submodel Options:: Specifying minor hardware or convention variations,
73 such as 68010 vs 68020.
74 * Code Gen Options:: Specifying conventions for function calls, data layout
76 * Environment Variables:: Env vars that affect GNU CC.
77 * Running Protoize:: Automatically adding or removing function prototypes.
81 @section Option Summary
83 Here is a summary of all the options, grouped by type. Explanations are
84 in the following sections.
88 @xref{Overall Options,,Options Controlling the Kind of Output}.
90 -c -S -E -o @var{file} -pipe -v --help -x @var{language}
93 @item C Language Options
94 @xref{C Dialect Options,,Options Controlling C Dialect}.
96 -ansi -flang-isoc9x -fallow-single-precision -fcond-mismatch -fno-asm
97 -fno-builtin -ffreestanding -fhosted -fsigned-bitfields -fsigned-char
98 -funsigned-bitfields -funsigned-char -fwritable-strings
99 -traditional -traditional-cpp -trigraphs
102 @item C++ Language Options
103 @xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
105 -fno-access-control -fcheck-new -fconserve-space -fdollars-in-identifiers
106 -fno-elide-constructors -fexternal-templates -ffor-scope
107 -fno-for-scope -fno-gnu-keywords -fguiding-decls -fhandle-signatures
108 -fhonor-std -fhuge-objects -fno-implicit-templates -finit-priority
109 -fno-implement-inlines -fname-mangling-version-@var{n} -fno-default-inline
110 -foperator-names -fno-optional-diags -frepo -fstrict-prototype
111 -fsquangle -ftemplate-depth-@var{n} -fthis-is-variable -fvtable-thunks
115 @item Warning Options
116 @xref{Warning Options,,Options to Request or Suppress Warnings}.
118 -fsyntax-only -pedantic -pedantic-errors
119 -w -W -Wall -Waggregate-return -Wbad-function-cast
120 -Wcast-align -Wcast-qual -Wchar-subscript -Wcomment
121 -Wconversion -Werror -Wformat
122 -Wid-clash-@var{len} -Wimplicit -Wimplicit-int
123 -Wimplicit-function-declaration -Wimport
124 -Werror-implicit-function-declaration -Winline
125 -Wlarger-than-@var{len} -Wlong-long
126 -Wmain -Wmissing-declarations -Wmissing-noreturn
127 -Wmissing-prototypes -Wmultichar -Wnested-externs -Wno-import
128 -Wno-non-template-friend -Wold-style-cast -Woverloaded-virtual
129 -Wparentheses -Wpointer-arith -Wredundant-decls -Wreorder
130 -Wreturn-type -Wshadow -Wsign-compare -Wstrict-prototypes
131 -Wswitch -Wsynth -Wtraditional
132 -Wtrigraphs -Wundef -Wuninitialized -Wunused -Wwrite-strings
136 @item Debugging Options
137 @xref{Debugging Options,,Options for Debugging Your Program or GCC}.
139 -a -ax -d@var{letters} -fdump-unnumbered -fpretend-float
140 -fprofile-arcs -ftest-coverage
141 -g -g@var{level} -gcoff -gdwarf -gdwarf-1 -gdwarf-1+ -gdwarf-2
142 -ggdb -gstabs -gstabs+ -gxcoff -gxcoff+
143 -p -pg -print-file-name=@var{library} -print-libgcc-file-name
144 -print-prog-name=@var{program} -print-search-dirs -save-temps
147 @item Optimization Options
148 @xref{Optimize Options,,Options that Control Optimization}.
150 -fbranch-probabilities -foptimize-register-moves
151 -fcaller-saves -fcse-follow-jumps -fcse-skip-blocks
152 -fdelayed-branch -fexpensive-optimizations
153 -ffast-math -ffloat-store -fforce-addr -fforce-mem
154 -fdata-sections -ffunction-sections -fgcse
155 -finline-functions -fkeep-inline-functions
156 -fno-default-inline -fno-defer-pop -fno-function-cse
157 -fno-inline -fno-peephole -fomit-frame-pointer -fregmove
158 -frerun-cse-after-loop -frerun-loop-opt -fschedule-insns
159 -fschedule-insns2 -fstrength-reduce -fthread-jumps
160 -funroll-all-loops -funroll-loops
161 -fmove-all-movables -freduce-all-givs -fstrict-aliasing
162 -O -O0 -O1 -O2 -O3 -Os
165 @item Preprocessor Options
166 @xref{Preprocessor Options,,Options Controlling the Preprocessor}.
168 -A@var{question}(@var{answer}) -C -dD -dM -dN
169 -D@var{macro}@r{[}=@var{defn}@r{]} -E -H
171 -include @var{file} -imacros @var{file}
172 -iprefix @var{file} -iwithprefix @var{dir}
173 -iwithprefixbefore @var{dir} -isystem @var{dir}
174 -M -MD -MM -MMD -MG -nostdinc -P -trigraphs
175 -undef -U@var{macro} -Wp,@var{option}
178 @item Assembler Option
179 @xref{Assembler Options,,Passing Options to the Assembler}.
185 @xref{Link Options,,Options for Linking}.
187 @var{object-file-name} -l@var{library}
188 -nostartfiles -nodefaultlibs -nostdlib
189 -s -static -shared -symbolic
190 -Wl,@var{option} -Xlinker @var{option}
194 @item Directory Options
195 @xref{Directory Options,,Options for Directory Search}.
197 -B@var{prefix} -I@var{dir} -I- -L@var{dir} -specs=@var{file}
201 @c I wrote this xref this way to avoid overfull hbox. -- rms
202 @xref{Target Options}.
204 -b @var{machine} -V @var{version}
207 @item Machine Dependent Options
208 @xref{Submodel Options,,Hardware Models and Configurations}.
210 @emph{M680x0 Options}
211 -m68000 -m68020 -m68020-40 -m68020-60 -m68030 -m68040
212 -m68060 -mcpu32 -m5200 -m68881 -mbitfield -mc68000 -mc68020
213 -mfpa -mnobitfield -mrtd -mshort -msoft-float
221 -mtune=@var{cpu type}
222 -mcmodel=@var{code model}
223 -malign-jumps=@var{num} -malign-loops=@var{num}
224 -malign-functions=@var{num}
226 -mapp-regs -mbroken-saverestore -mcypress -mepilogue
227 -mflat -mfpu -mhard-float -mhard-quad-float
228 -mimpure-text -mlive-g0 -mno-app-regs -mno-epilogue
229 -mno-flat -mno-fpu -mno-impure-text
230 -mno-stack-bias -mno-unaligned-doubles
231 -msoft-float -msoft-quad-float -msparclite -mstack-bias
232 -msupersparc -munaligned-doubles -mv8
234 @emph{Convex Options}
235 -mc1 -mc2 -mc32 -mc34 -mc38
236 -margcount -mnoargcount
238 -mvolatile-cache -mvolatile-nocache
240 @emph{AMD29K Options}
241 -m29000 -m29050 -mbw -mnbw -mdw -mndw
242 -mlarge -mnormal -msmall
243 -mkernel-registers -mno-reuse-arg-regs
244 -mno-stack-check -mno-storem-bug
245 -mreuse-arg-regs -msoft-float -mstack-check
246 -mstorem-bug -muser-registers
249 -mapcs-frame -mno-apcs-frame
251 -mapcs-stack-check -mno-apcs-stack-check
252 -mapcs-float -mno-apcs-float
253 -mapcs-reentrant -mno-apcs-reentrant
254 -msched-prolog -mno-sched-prolog
255 -mlittle-endian -mbig-endian -mwords-little-endian
256 -mshort-load-bytes -mno-short-load-bytes -mshort-load-words -mno-short-load-words
257 -msoft-float -mhard-float -mfpe
258 -mthumb-interwork -mno-thumb-interwork
259 -mcpu= -march= -mfpe=
260 -mstructure-size-boundary=
261 -mbsd -mxopen -mno-symrename
264 -mtpcs-frame -mno-tpcs-frame
265 -mtpcs-leaf-frame -mno-tpcs-leaf-frame
266 -mlittle-endian -mbig-endian
267 -mthumb-interwork -mno-thumb-interwork
268 -mstructure-size-boundary=
270 @emph{MN10200 Options}
273 @emph{MN10300 Options}
278 @emph{M32R/D Options}
279 -mcode-model=@var{model type} -msdata=@var{sdata type}
283 -m88000 -m88100 -m88110 -mbig-pic
284 -mcheck-zero-division -mhandle-large-shift
285 -midentify-revision -mno-check-zero-division
286 -mno-ocs-debug-info -mno-ocs-frame-position
287 -mno-optimize-arg-area -mno-serialize-volatile
288 -mno-underscores -mocs-debug-info
289 -mocs-frame-position -moptimize-arg-area
290 -mserialize-volatile -mshort-data-@var{num} -msvr3
291 -msvr4 -mtrap-large-shift -muse-div-instruction
292 -mversion-03.00 -mwarn-passed-structs
294 @emph{RS/6000 and PowerPC Options}
296 -mtune=@var{cpu type}
297 -mpower -mno-power -mpower2 -mno-power2
298 -mpowerpc -mno-powerpc
299 -mpowerpc-gpopt -mno-powerpc-gpopt
300 -mpowerpc-gfxopt -mno-powerpc-gfxopt
301 -mnew-mnemonics -mno-new-mnemonics
302 -mfull-toc -mminimal-toc -mno-fop-in-toc -mno-sum-in-toc
303 -maix64 -maix32 -mxl-call -mno-xl-call -mthreads -mpe
304 -msoft-float -mhard-float -mmultiple -mno-multiple
305 -mstring -mno-string -mupdate -mno-update
306 -mfused-madd -mno-fused-madd -mbit-align -mno-bit-align
307 -mstrict-align -mno-strict-align -mrelocatable
308 -mno-relocatable -mrelocatable-lib -mno-relocatable-lib
309 -mtoc -mno-toc -mlittle -mlittle-endian -mbig -mbig-endian
310 -mcall-aix -mcall-sysv -mprototype -mno-prototype
311 -msim -mmvme -mads -myellowknife -memb -msdata
312 -msdata=@var{opt} -G @var{num}
315 -mcall-lib-mul -mfp-arg-in-fpregs -mfp-arg-in-gregs
316 -mfull-fp-blocks -mhc-struct-return -min-line-mul
317 -mminimum-fp-blocks -mnohc-struct-return
320 -mabicalls -mcpu=@var{cpu type} -membedded-data
321 -membedded-pic -mfp32 -mfp64 -mgas -mgp32 -mgp64
322 -mgpopt -mhalf-pic -mhard-float -mint64 -mips1
323 -mips2 -mips3 -mips4 -mlong64 -mlong-calls -mmemcpy
324 -mmips-as -mmips-tfile -mno-abicalls
325 -mno-embedded-data -mno-embedded-pic
326 -mno-gpopt -mno-long-calls
327 -mno-memcpy -mno-mips-tfile -mno-rnames -mno-stats
328 -mrnames -msoft-float
329 -m4650 -msingle-float -mmad
330 -mstats -EL -EB -G @var{num} -nocpp
331 -mabi=32 -mabi=n32 -mabi=64 -mabi=eabi
335 -march=@var{cpu type}
336 -mieee-fp -mno-fancy-math-387
337 -mno-fp-ret-in-387 -msoft-float -msvr3-shlib
338 -mno-wide-multiply -mrtd -malign-double
339 -mreg-alloc=@var{list} -mregparm=@var{num}
340 -malign-jumps=@var{num} -malign-loops=@var{num}
341 -malign-functions=@var{num}
344 -mbig-switch -mdisable-fpregs -mdisable-indexing
345 -mfast-indirect-calls -mgas -mjump-in-delay
346 -mlong-load-store -mno-big-switch -mno-disable-fpregs
347 -mno-disable-indexing -mno-fast-indirect-calls -mno-gas
348 -mno-jump-in-delay -mno-long-load-store
349 -mno-portable-runtime -mno-soft-float -mno-space
350 -mno-space-regs -msoft-float -mpa-risc-1-0
351 -mpa-risc-1-1 -mportable-runtime
352 -mschedule=@var{list} -mspace -mspace-regs
354 @emph{Intel 960 Options}
355 -m@var{cpu type} -masm-compat -mclean-linkage
356 -mcode-align -mcomplex-addr -mleaf-procedures
357 -mic-compat -mic2.0-compat -mic3.0-compat
358 -mintel-asm -mno-clean-linkage -mno-code-align
359 -mno-complex-addr -mno-leaf-procedures
360 -mno-old-align -mno-strict-align -mno-tail-call
361 -mnumerics -mold-align -msoft-float -mstrict-align
364 @emph{DEC Alpha Options}
365 -mfp-regs -mno-fp-regs -mno-soft-float -msoft-float
367 -mieee -mieee-with-inexact -mieee-conformant
368 -mfp-trap-mode=@var{mode} -mfp-rounding-mode=@var{mode}
369 -mtrap-precision=@var{mode} -mbuild-constants
371 -mbwx -mno-bwx -mcix -mno-cix -mmax -mno-max
372 -mmemory-latency=@var{time}
374 @emph{Clipper Options}
377 @emph{H8/300 Options}
378 -mrelax -mh -ms -mint32 -malign-300
381 -m1 -m2 -m3 -m3e -mb -ml -mdalign -mrelax
383 @emph{System V Options}
384 -Qy -Qn -YP,@var{paths} -Ym,@var{dir}
388 -mmangle-cpu -mcpu=@var{cpu} -mtext=@var{text section}
389 -mdata=@var{data section} -mrodata=@var{readonly data section}
392 -mlong-calls -mno-long-calls -mep -mno-ep
393 -mprolog-function -mno-prolog-function -mspace
394 -mtda=@var{n} -msda=@var{n} -mzda=@var{n}
398 -m32032 -m32332 -m32532 -m32081 -m32381 -mmult-add -mnomult-add
399 -msoft-float -mrtd -mnortd -mregparam -mnoregparam -msb -mnosb
400 -mbitfield -mnobitfield -mhimem -mnohimem
403 @item Code Generation Options
404 @xref{Code Gen Options,,Options for Code Generation Conventions}.
406 -fcall-saved-@var{reg} -fcall-used-@var{reg}
407 -fexceptions -ffixed-@var{reg} -finhibit-size-directive
408 -fcheck-memory-usage -fprefix-function-name
409 -fno-common -fno-ident -fno-gnu-linker
410 -fpcc-struct-return -fpic -fPIC
411 -freg-struct-return -fshared-data -fshort-enums
412 -fshort-double -fvolatile -fvolatile-global
413 -fverbose-asm -fpack-struct -fstack-check
414 -fargument-alias -fargument-noalias
415 -fargument-noalias-global
421 * Overall Options:: Controlling the kind of output:
422 an executable, object files, assembler files,
423 or preprocessed source.
424 * C Dialect Options:: Controlling the variant of C language compiled.
425 * C++ Dialect Options:: Variations on C++.
426 * Warning Options:: How picky should the compiler be?
427 * Debugging Options:: Symbol tables, measurements, and debugging dumps.
428 * Optimize Options:: How much optimization?
429 * Preprocessor Options:: Controlling header files and macro definitions.
430 Also, getting dependency information for Make.
431 * Assembler Options:: Passing options to the assembler.
432 * Link Options:: Specifying libraries and so on.
433 * Directory Options:: Where to find header files and libraries.
434 Where to find the compiler executable files.
435 * Target Options:: Running a cross-compiler, or an old version of GNU CC.
438 @node Overall Options
439 @section Options Controlling the Kind of Output
441 Compilation can involve up to four stages: preprocessing, compilation
442 proper, assembly and linking, always in that order. The first three
443 stages apply to an individual source file, and end by producing an
444 object file; linking combines all the object files (those newly
445 compiled, and those specified as input) into an executable file.
447 @cindex file name suffix
448 For any given input file, the file name suffix determines what kind of
453 C source code which must be preprocessed.
456 C source code which should not be preprocessed.
459 C++ source code which should not be preprocessed.
462 Objective-C source code. Note that you must link with the library
463 @file{libobjc.a} to make an Objective-C program work.
466 C header file (not to be compiled or linked).
469 @itemx @var{file}.cxx
470 @itemx @var{file}.cpp
472 C++ source code which must be preprocessed. Note that in @samp{.cxx},
473 the last two letters must both be literally @samp{x}. Likewise,
474 @samp{.C} refers to a literal capital C.
480 Assembler code which must be preprocessed.
483 An object file to be fed straight into linking.
484 Any file name with no recognized suffix is treated this way.
487 You can specify the input language explicitly with the @samp{-x} option:
490 @item -x @var{language}
491 Specify explicitly the @var{language} for the following input files
492 (rather than letting the compiler choose a default based on the file
493 name suffix). This option applies to all following input files until
494 the next @samp{-x} option. Possible values for @var{language} are:
497 c-header cpp-output c++-cpp-output
498 assembler assembler-with-cpp
502 Turn off any specification of a language, so that subsequent files are
503 handled according to their file name suffixes (as they are if @samp{-x}
504 has not been used at all).
507 If you only want some of the stages of compilation, you can use
508 @samp{-x} (or filename suffixes) to tell @code{gcc} where to start, and
509 one of the options @samp{-c}, @samp{-S}, or @samp{-E} to say where
510 @code{gcc} is to stop. Note that some combinations (for example,
511 @samp{-x cpp-output -E} instruct @code{gcc} to do nothing at all.
515 Compile or assemble the source files, but do not link. The linking
516 stage simply is not done. The ultimate output is in the form of an
517 object file for each source file.
519 By default, the object file name for a source file is made by replacing
520 the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}.
522 Unrecognized input files, not requiring compilation or assembly, are
526 Stop after the stage of compilation proper; do not assemble. The output
527 is in the form of an assembler code file for each non-assembler input
530 By default, the assembler file name for a source file is made by
531 replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}.
533 Input files that don't require compilation are ignored.
536 Stop after the preprocessing stage; do not run the compiler proper. The
537 output is in the form of preprocessed source code, which is sent to the
540 Input files which don't require preprocessing are ignored.
542 @cindex output file option
544 Place output in file @var{file}. This applies regardless to whatever
545 sort of output is being produced, whether it be an executable file,
546 an object file, an assembler file or preprocessed C code.
548 Since only one output file can be specified, it does not make sense to
549 use @samp{-o} when compiling more than one input file, unless you are
550 producing an executable file as output.
552 If @samp{-o} is not specified, the default is to put an executable file
553 in @file{a.out}, the object file for @file{@var{source}.@var{suffix}} in
554 @file{@var{source}.o}, its assembler file in @file{@var{source}.s}, and
555 all preprocessed C source on standard output.@refill
558 Print (on standard error output) the commands executed to run the stages
559 of compilation. Also print the version number of the compiler driver
560 program and of the preprocessor and the compiler proper.
563 Use pipes rather than temporary files for communication between the
564 various stages of compilation. This fails to work on some systems where
565 the assembler is unable to read from a pipe; but the GNU assembler has
569 Print (on the standard output) a description of the command line options
570 understood by @code{gcc}. If the @code{-v} option is also specified
571 then @code{--help} will also be passed on to the various processes
572 invoked by @code{gcc}, so that they can display the command line options
573 they accept. If the @code{-W} option is also specified then command
574 line options which have no documentation associated with them will also
579 @section Compiling C++ Programs
581 @cindex suffixes for C++ source
582 @cindex C++ source file suffixes
583 C++ source files conventionally use one of the suffixes @samp{.C},
584 @samp{.cc}, @samp{cpp}, or @samp{.cxx}; preprocessed C++ files use the
585 suffix @samp{.ii}. GNU CC recognizes files with these names and
586 compiles them as C++ programs even if you call the compiler the same way
587 as for compiling C programs (usually with the name @code{gcc}).
591 However, C++ programs often require class libraries as well as a
592 compiler that understands the C++ language---and under some
593 circumstances, you might want to compile programs from standard input,
594 or otherwise without a suffix that flags them as C++ programs.
595 @code{g++} is a program that calls GNU CC with the default language
596 set to C++, and automatically specifies linking against the C++
598 @cindex @code{g++ 1.@var{xx}}
599 @cindex @code{g++}, separate compiler
600 @cindex @code{g++} older version
601 @footnote{Prior to release 2 of the compiler,
602 there was a separate @code{g++} compiler. That version was based on GNU
603 CC, but not integrated with it. Versions of @code{g++} with a
604 @samp{1.@var{xx}} version number---for example, @code{g++} version 1.37
605 or 1.42---are much less reliable than the versions integrated with GCC
606 2. Moreover, combining G++ @samp{1.@var{xx}} with a version 2 GCC will
607 simply not work.} On many systems, the script @code{g++} is also
608 installed with the name @code{c++}.
610 @cindex invoking @code{g++}
611 When you compile C++ programs, you may specify many of the same
612 command-line options that you use for compiling programs in any
613 language; or command-line options meaningful for C and related
614 languages; or options that are meaningful only for C++ programs.
615 @xref{C Dialect Options,,Options Controlling C Dialect}, for
616 explanations of options for languages related to C.
617 @xref{C++ Dialect Options,,Options Controlling C++ Dialect}, for
618 explanations of options that are meaningful only for C++ programs.
620 @node C Dialect Options
621 @section Options Controlling C Dialect
622 @cindex dialect options
623 @cindex language dialect options
624 @cindex options, dialect
626 The following options control the dialect of C (or languages derived
627 from C, such as C++ and Objective C) that the compiler accepts:
632 Support all ANSI standard C programs.
634 This turns off certain features of GNU C that are incompatible with ANSI
635 C, such as the @code{asm}, @code{inline} and @code{typeof} keywords, and
636 predefined macros such as @code{unix} and @code{vax} that identify the
637 type of system you are using. It also enables the undesirable and
638 rarely used ANSI trigraph feature, and it disables recognition of C++
639 style @samp{//} comments.
641 The alternate keywords @code{__asm__}, @code{__extension__},
642 @code{__inline__} and @code{__typeof__} continue to work despite
643 @samp{-ansi}. You would not want to use them in an ANSI C program, of
644 course, but it is useful to put them in header files that might be included
645 in compilations done with @samp{-ansi}. Alternate predefined macros
646 such as @code{__unix__} and @code{__vax__} are also available, with or
647 without @samp{-ansi}.
649 The @samp{-ansi} option does not cause non-ANSI programs to be
650 rejected gratuitously. For that, @samp{-pedantic} is required in
651 addition to @samp{-ansi}. @xref{Warning Options}.
653 The macro @code{__STRICT_ANSI__} is predefined when the @samp{-ansi}
654 option is used. Some header files may notice this macro and refrain
655 from declaring certain functions or defining certain macros that the
656 ANSI standard doesn't call for; this is to avoid interfering with any
657 programs that might use these names for other things.
659 The functions @code{alloca}, @code{abort}, @code{exit}, and
660 @code{_exit} are not builtin functions when @samp{-ansi} is used.
663 Enable support for features found in the C9X standard. In particular,
664 enable support for the C9X @code{restrict} keyword.
666 Even when this option is not specified, you can still use some C9X
667 features in so far as they do not conflict with previous C standards.
668 For example, you may use @code{__restrict__} even when -flang-isoc9x
672 Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
673 keyword, so that code can use these words as identifiers. You can use
674 the keywords @code{__asm__}, @code{__inline__} and @code{__typeof__}
675 instead. @samp{-ansi} implies @samp{-fno-asm}.
677 In C++, this switch only affects the @code{typeof} keyword, since
678 @code{asm} and @code{inline} are standard keywords. You may want to
679 use the @samp{-fno-gnu-keywords} flag instead, as it also disables the
680 other, C++-specific, extension keywords such as @code{headof}.
683 @cindex builtin functions
699 Don't recognize builtin functions that do not begin with `__builtin_'
700 as prefix. Currently, the functions affected include @code{abort},
701 @code{abs}, @code{alloca}, @code{cos}, @code{exit}, @code{fabs},
702 @code{ffs}, @code{labs}, @code{memcmp}, @code{memcpy}, @code{sin},
703 @code{sqrt}, @code{strcmp}, @code{strcpy}, and @code{strlen}.
705 GCC normally generates special code to handle certain builtin functions
706 more efficiently; for instance, calls to @code{alloca} may become single
707 instructions that adjust the stack directly, and calls to @code{memcpy}
708 may become inline copy loops. The resulting code is often both smaller
709 and faster, but since the function calls no longer appear as such, you
710 cannot set a breakpoint on those calls, nor can you change the behavior
711 of the functions by linking with a different library.
713 The @samp{-ansi} option prevents @code{alloca} and @code{ffs} from being
714 builtin functions, since these functions do not have an ANSI standard
718 @cindex hosted environment
720 Assert that compilation takes place in a hosted environment. This implies
721 @samp{-fbuiltin}. A hosted environment is one in which the
722 entire standard library is available, and in which @code{main} has a return
723 type of @code{int}. Examples are nearly everything except a kernel.
724 This is equivalent to @samp{-fno-freestanding}.
727 @cindex hosted environment
729 Assert that compilation takes place in a freestanding environment. This
730 implies @samp{-fno-builtin}. A freestanding environment
731 is one in which the standard library may not exist, and program startup may
732 not necessarily be at @code{main}. The most obvious example is an OS kernel.
733 This is equivalent to @samp{-fno-hosted}.
736 Support ANSI C trigraphs. You don't want to know about this
737 brain-damage. The @samp{-ansi} option implies @samp{-trigraphs}.
739 @cindex traditional C language
740 @cindex C language, traditional
742 Attempt to support some aspects of traditional C compilers.
747 All @code{extern} declarations take effect globally even if they
748 are written inside of a function definition. This includes implicit
749 declarations of functions.
752 The newer keywords @code{typeof}, @code{inline}, @code{signed}, @code{const}
753 and @code{volatile} are not recognized. (You can still use the
754 alternative keywords such as @code{__typeof__}, @code{__inline__}, and
758 Comparisons between pointers and integers are always allowed.
761 Integer types @code{unsigned short} and @code{unsigned char} promote
762 to @code{unsigned int}.
765 Out-of-range floating point literals are not an error.
768 Certain constructs which ANSI regards as a single invalid preprocessing
769 number, such as @samp{0xe-0xd}, are treated as expressions instead.
772 String ``constants'' are not necessarily constant; they are stored in
773 writable space, and identical looking constants are allocated
774 separately. (This is the same as the effect of
775 @samp{-fwritable-strings}.)
777 @cindex @code{longjmp} and automatic variables
779 All automatic variables not declared @code{register} are preserved by
780 @code{longjmp}. Ordinarily, GNU C follows ANSI C: automatic variables
781 not declared @code{volatile} may be clobbered.
786 @cindex escape sequences, traditional
787 The character escape sequences @samp{\x} and @samp{\a} evaluate as the
788 literal characters @samp{x} and @samp{a} respectively. Without
789 @w{@samp{-traditional}}, @samp{\x} is a prefix for the hexadecimal
790 representation of a character, and @samp{\a} produces a bell.
793 You may wish to use @samp{-fno-builtin} as well as @samp{-traditional}
794 if your program uses names that are normally GNU C builtin functions for
795 other purposes of its own.
797 You cannot use @samp{-traditional} if you include any header files that
798 rely on ANSI C features. Some vendors are starting to ship systems with
799 ANSI C header files and you cannot use @samp{-traditional} on such
800 systems to compile files that include any system headers.
802 The @samp{-traditional} option also enables @samp{-traditional-cpp},
803 which is described next.
805 @item -traditional-cpp
806 Attempt to support some aspects of traditional C preprocessors.
811 Comments convert to nothing at all, rather than to a space. This allows
812 traditional token concatenation.
815 In a preprocessing directive, the @samp{#} symbol must appear as the first
819 Macro arguments are recognized within string constants in a macro
820 definition (and their values are stringified, though without additional
821 quote marks, when they appear in such a context). The preprocessor
822 always considers a string constant to end at a newline.
825 @cindex detecting @w{@samp{-traditional}}
826 The predefined macro @code{__STDC__} is not defined when you use
827 @samp{-traditional}, but @code{__GNUC__} is (since the GNU extensions
828 which @code{__GNUC__} indicates are not affected by
829 @samp{-traditional}). If you need to write header files that work
830 differently depending on whether @samp{-traditional} is in use, by
831 testing both of these predefined macros you can distinguish four
832 situations: GNU C, traditional GNU C, other ANSI C compilers, and other
833 old C compilers. The predefined macro @code{__STDC_VERSION__} is also
834 not defined when you use @samp{-traditional}. @xref{Standard
835 Predefined,,Standard Predefined Macros,cpp.info,The C Preprocessor},
836 for more discussion of these and other predefined macros.
839 @cindex string constants vs newline
840 @cindex newline vs string constants
841 The preprocessor considers a string constant to end at a newline (unless
842 the newline is escaped with @samp{\}). (Without @w{@samp{-traditional}},
843 string constants can contain the newline character as typed.)
846 @item -fcond-mismatch
847 Allow conditional expressions with mismatched types in the second and
848 third arguments. The value of such an expression is void.
850 @item -funsigned-char
851 Let the type @code{char} be unsigned, like @code{unsigned char}.
853 Each kind of machine has a default for what @code{char} should
854 be. It is either like @code{unsigned char} by default or like
855 @code{signed char} by default.
857 Ideally, a portable program should always use @code{signed char} or
858 @code{unsigned char} when it depends on the signedness of an object.
859 But many programs have been written to use plain @code{char} and
860 expect it to be signed, or expect it to be unsigned, depending on the
861 machines they were written for. This option, and its inverse, let you
862 make such a program work with the opposite default.
864 The type @code{char} is always a distinct type from each of
865 @code{signed char} or @code{unsigned char}, even though its behavior
866 is always just like one of those two.
869 Let the type @code{char} be signed, like @code{signed char}.
871 Note that this is equivalent to @samp{-fno-unsigned-char}, which is
872 the negative form of @samp{-funsigned-char}. Likewise, the option
873 @samp{-fno-signed-char} is equivalent to @samp{-funsigned-char}.
875 You may wish to use @samp{-fno-builtin} as well as @samp{-traditional}
876 if your program uses names that are normally GNU C builtin functions for
877 other purposes of its own.
879 You cannot use @samp{-traditional} if you include any header files that
880 rely on ANSI C features. Some vendors are starting to ship systems with
881 ANSI C header files and you cannot use @samp{-traditional} on such
882 systems to compile files that include any system headers.
884 @item -fsigned-bitfields
885 @itemx -funsigned-bitfields
886 @itemx -fno-signed-bitfields
887 @itemx -fno-unsigned-bitfields
888 These options control whether a bitfield is signed or unsigned, when the
889 declaration does not use either @code{signed} or @code{unsigned}. By
890 default, such a bitfield is signed, because this is consistent: the
891 basic integer types such as @code{int} are signed types.
893 However, when @samp{-traditional} is used, bitfields are all unsigned
896 @item -fwritable-strings
897 Store string constants in the writable data segment and don't uniquize
898 them. This is for compatibility with old programs which assume they can
899 write into string constants. The option @samp{-traditional} also has
902 Writing into string constants is a very bad idea; ``constants'' should
905 @item -fallow-single-precision
906 Do not promote single precision math operations to double precision,
907 even when compiling with @samp{-traditional}.
909 Traditional K&R C promotes all floating point operations to double
910 precision, regardless of the sizes of the operands. On the
911 architecture for which you are compiling, single precision may be faster
912 than double precision. If you must use @samp{-traditional}, but want
913 to use single precision operations when the operands are single
914 precision, use this option. This option has no effect when compiling
915 with ANSI or GNU C conventions (the default).
919 @node C++ Dialect Options
920 @section Options Controlling C++ Dialect
922 @cindex compiler options, C++
923 @cindex C++ options, command line
925 This section describes the command-line options that are only meaningful
926 for C++ programs; but you can also use most of the GNU compiler options
927 regardless of what language your program is in. For example, you
928 might compile a file @code{firstClass.C} like this:
931 g++ -g -frepo -O -c firstClass.C
935 In this example, only @samp{-frepo} is an option meant
936 only for C++ programs; you can use the other options with any
937 language supported by GNU CC.
939 Here is a list of options that are @emph{only} for compiling C++ programs:
942 @item -fno-access-control
943 Turn off all access checking. This switch is mainly useful for working
944 around bugs in the access control code.
947 Check that the pointer returned by @code{operator new} is non-null
948 before attempting to modify the storage allocated. The current Working
949 Paper requires that @code{operator new} never return a null pointer, so
950 this check is normally unnecessary.
952 An alternative to using this option is to specify that your
953 @code{operator new} does not throw any exceptions; if you declare it
954 @samp{throw()}, g++ will check the return value. See also @samp{new
957 @item -fconserve-space
958 Put uninitialized or runtime-initialized global variables into the
959 common segment, as C does. This saves space in the executable at the
960 cost of not diagnosing duplicate definitions. If you compile with this
961 flag and your program mysteriously crashes after @code{main()} has
962 completed, you may have an object that is being destroyed twice because
963 two definitions were merged.
965 This option is no longer useful on most targets, now that support has
966 been added for putting variables into BSS without making them common.
968 @item -fdollars-in-identifiers
969 Accept @samp{$} in identifiers. You can also explicitly prohibit use of
970 @samp{$} with the option @samp{-fno-dollars-in-identifiers}. (GNU C allows
971 @samp{$} by default on most target systems, but there are a few exceptions.)
972 Traditional C allowed the character @samp{$} to form part of
973 identifiers. However, ANSI C and C++ forbid @samp{$} in identifiers.
975 @item -fno-elide-constructors
976 The C++ standard allows an implementation to omit creating a temporary
977 which is only used to initialize another object of the same type.
978 Specifying this option disables that optimization, and forces g++ to
979 call the copy constructor in all cases.
981 @item -fexternal-templates
982 Cause template instantiations to obey @samp{#pragma interface} and
983 @samp{implementation}; template instances are emitted or not according
984 to the location of the template definition. @xref{Template
985 Instantiation}, for more information.
987 This option is deprecated.
989 @item -falt-external-templates
990 Similar to -fexternal-templates, but template instances are emitted or
991 not according to the place where they are first instantiated.
992 @xref{Template Instantiation}, for more information.
994 This option is deprecated.
997 @itemx -fno-for-scope
998 If -ffor-scope is specified, the scope of variables declared in
999 a @i{for-init-statement} is limited to the @samp{for} loop itself,
1000 as specified by the draft C++ standard.
1001 If -fno-for-scope is specified, the scope of variables declared in
1002 a @i{for-init-statement} extends to the end of the enclosing scope,
1003 as was the case in old versions of gcc, and other (traditional)
1004 implementations of C++.
1006 The default if neither flag is given to follow the standard,
1007 but to allow and give a warning for old-style code that would
1008 otherwise be invalid, or have different behavior.
1010 @item -fno-gnu-keywords
1011 Do not recognize @code{classof}, @code{headof}, @code{signature},
1012 @code{sigof} or @code{typeof} as a keyword, so that code can use these
1013 words as identifiers. You can use the keywords @code{__classof__},
1014 @code{__headof__}, @code{__signature__}, @code{__sigof__}, and
1015 @code{__typeof__} instead. @samp{-ansi} implies
1016 @samp{-fno-gnu-keywords}.
1018 @item -fguiding-decls
1019 Treat a function declaration with the same type as a potential function
1020 template instantiation as though it declares that instantiation, not a
1021 normal function. If a definition is given for the function later in the
1022 translation unit (or another translation unit if the target supports
1023 weak symbols), that definition will be used; otherwise the template will
1024 be instantiated. This behavior reflects the C++ language prior to
1025 September 1996, when guiding declarations were removed.
1027 This option implies @samp{-fname-mangling-version-0}, and will not work
1028 with other name mangling versions. Like all options that change the
1029 ABI, all C++ code, @emph{including libgcc.a} must be built with the same
1030 setting of this option.
1032 @item -fhandle-signatures
1033 Recognize the @code{signature} and @code{sigof} keywords for specifying
1034 abstract types. The default (@samp{-fno-handle-signatures}) is not to
1035 recognize them. @xref{C++ Signatures, Type Abstraction using
1039 Treat the @code{namespace std} as a namespace, instead of ignoring
1040 it. For compatibility with earlier versions of g++, the compiler will,
1041 by default, ignore @code{namespace-declarations},
1042 @code{using-declarations}, @code{using-directives}, and
1043 @code{namespace-names}, if they involve @code{std}.
1045 @item -fhuge-objects
1046 Support virtual function calls for objects that exceed the size
1047 representable by a @samp{short int}. Users should not use this flag by
1048 default; if you need to use it, the compiler will tell you so.
1050 This flag is not useful when compiling with -fvtable-thunks.
1052 Like all options that change the ABI, all C++ code, @emph{including
1053 libgcc} must be built with the same setting of this option.
1055 @item -fno-implicit-templates
1056 Never emit code for templates which are instantiated implicitly (i.e. by
1057 use); only emit code for explicit instantiations. @xref{Template
1058 Instantiation}, for more information.
1060 @item -finit-priority
1061 Support @samp{__attribute__ ((init_priority (n)))} for controlling the
1062 order of initialization of file-scope objects. On ELF targets, this
1063 requires GNU ld 2.10 or later.
1065 @item -fno-implement-inlines
1066 To save space, do not emit out-of-line copies of inline functions
1067 controlled by @samp{#pragma implementation}. This will cause linker
1068 errors if these functions are not inlined everywhere they are called.
1070 @item -fname-mangling-version-@var{n}
1071 Control the way in which names are mangled. Version 0 is compatible
1072 with versions of g++ before 2.8. Version 1 is the default. Version 1
1073 will allow correct mangling of function templates. For example,
1074 version 0 mangling does not mangle foo<int, double> and foo<int, char>
1075 given this declaration:
1078 template <class T, class U> void foo(T t);
1081 @item -foperator-names
1082 Recognize the operator name keywords @code{and}, @code{bitand},
1083 @code{bitor}, @code{compl}, @code{not}, @code{or} and @code{xor} as
1084 synonyms for the symbols they refer to. @samp{-ansi} implies
1085 @samp{-foperator-names}.
1087 @item -fno-optional-diags
1088 Disable diagnostics that the standard says a compiler does not need to
1089 issue. Currently, this means the diagnostic for a name having multiple
1090 meanings within a class.
1093 Enable automatic template instantiation. This option also implies
1094 @samp{-fno-implicit-templates}. @xref{Template Instantiation}, for more
1097 @item -fstrict-prototype
1098 Within an @samp{extern "C"} linkage specification, treat a function
1099 declaration with no arguments, such as @samp{int foo ();}, as declaring
1100 the function to take no arguments. Normally, such a declaration means
1101 that the function @code{foo} can take any combination of arguments, as
1102 in C. @samp{-pedantic} implies @samp{-fstrict-prototype} unless
1103 overridden with @samp{-fno-strict-prototype}.
1105 Specifying this option will also suppress implicit declarations of
1108 This flag no longer affects declarations with C++ linkage.
1111 @itemx -fno-squangle
1112 @samp{-fsquangle} will enable a compressed form of name mangling for
1113 identifiers. In particular, it helps to shorten very long names by recognizing
1114 types and class names which occur more than once, replacing them with special
1115 short ID codes. This option also requires any C++ libraries being used to
1116 be compiled with this option as well. The compiler has this disabled (the
1117 equivalent of @samp{-fno-squangle}) by default.
1119 Like all options that change the ABI, all C++ code, @emph{including
1120 libgcc.a} must be built with the same setting of this option.
1122 @item -ftemplate-depth-@var{n}
1123 Set the maximum instantiation depth for template classes to @var{n}.
1124 A limit on the template instantiation depth is needed to detect
1125 endless recursions during template class instantiation. ANSI/ISO C++
1126 conforming programs must not rely on a maximum depth greater than 17.
1128 @item -fthis-is-variable
1129 Permit assignment to @code{this}. The incorporation of user-defined
1130 free store management into C++ has made assignment to @samp{this} an
1131 anachronism. Therefore, by default it is invalid to assign to
1132 @code{this} within a class member function; that is, GNU C++ treats
1133 @samp{this} in a member function of class @code{X} as a non-lvalue of
1134 type @samp{X *}. However, for backwards compatibility, you can make it
1135 valid with @samp{-fthis-is-variable}.
1137 @item -fvtable-thunks
1138 Use @samp{thunks} to implement the virtual function dispatch table
1139 (@samp{vtable}). The traditional (cfront-style) approach to
1140 implementing vtables was to store a pointer to the function and two
1141 offsets for adjusting the @samp{this} pointer at the call site. Newer
1142 implementations store a single pointer to a @samp{thunk} function which
1143 does any necessary adjustment and then calls the target function.
1145 Like all options that change the ABI, all C++ code, @emph{including
1146 libgcc.a} must be built with the same setting of this option.
1149 Do not search for header files in the standard directories specific to
1150 C++, but do still search the other standard directories. (This option
1151 is used when building the C++ library.)
1154 In addition, these optimization, warning, and code generation options
1155 have meanings only for C++ programs:
1158 @item -fno-default-inline
1159 Do not assume @samp{inline} for functions defined inside a class scope.
1160 @xref{Optimize Options,,Options That Control Optimization}. Note that these
1161 functions will have linkage like inline functions; they just won't be
1164 @item -Wno-non-template-friend
1165 @xref{Warning Options,,Options to Request or Suppress Warnings}.
1166 @item -Wold-style-cast
1167 @itemx -Woverloaded-virtual
1168 Warnings that apply only to C++ programs. @xref{Warning
1169 Options,,Options to Request or Suppress Warnings}.
1172 Warn about violation of some style rules from Effective C++ by Scott Myers.
1175 @node Warning Options
1176 @section Options to Request or Suppress Warnings
1177 @cindex options to control warnings
1178 @cindex warning messages
1179 @cindex messages, warning
1180 @cindex suppressing warnings
1182 Warnings are diagnostic messages that report constructions which
1183 are not inherently erroneous but which are risky or suggest there
1184 may have been an error.
1186 You can request many specific warnings with options beginning @samp{-W},
1187 for example @samp{-Wimplicit} to request warnings on implicit
1188 declarations. Each of these specific warning options also has a
1189 negative form beginning @samp{-Wno-} to turn off warnings;
1190 for example, @samp{-Wno-implicit}. This manual lists only one of the
1191 two forms, whichever is not the default.
1193 These options control the amount and kinds of warnings produced by GNU
1197 @cindex syntax checking
1199 Check the code for syntax errors, but don't do anything beyond that.
1202 Issue all the warnings demanded by strict ANSI C and ISO C++;
1203 reject all programs that use forbidden extensions.
1205 Valid ANSI C and ISO C++ programs should compile properly with or without
1206 this option (though a rare few will require @samp{-ansi}). However,
1207 without this option, certain GNU extensions and traditional C and C++
1208 features are supported as well. With this option, they are rejected.
1210 @samp{-pedantic} does not cause warning messages for use of the
1211 alternate keywords whose names begin and end with @samp{__}. Pedantic
1212 warnings are also disabled in the expression that follows
1213 @code{__extension__}. However, only system header files should use
1214 these escape routes; application programs should avoid them.
1215 @xref{Alternate Keywords}.
1217 This option is not intended to be @i{useful}; it exists only to satisfy
1218 pedants who would otherwise claim that GNU CC fails to support the ANSI
1221 Some users try to use @samp{-pedantic} to check programs for strict ANSI
1222 C conformance. They soon find that it does not do quite what they want:
1223 it finds some non-ANSI practices, but not all---only those for which
1224 ANSI C @emph{requires} a diagnostic.
1226 A feature to report any failure to conform to ANSI C might be useful in
1227 some instances, but would require considerable additional work and would
1228 be quite different from @samp{-pedantic}. We don't have plans to
1229 support such a feature in the near future.
1231 @item -pedantic-errors
1232 Like @samp{-pedantic}, except that errors are produced rather than
1236 Inhibit all warning messages.
1239 Inhibit warning messages about the use of @samp{#import}.
1241 @item -Wchar-subscripts
1242 Warn if an array subscript has type @code{char}. This is a common cause
1243 of error, as programmers often forget that this type is signed on some
1247 Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
1248 comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
1251 Check calls to @code{printf} and @code{scanf}, etc., to make sure that
1252 the arguments supplied have types appropriate to the format string
1255 @item -Wimplicit-int
1256 Warn when a declaration does not specify a type.
1258 @item -Wimplicit-function-declaration
1259 @itemx -Werror-implicit-function-declaration
1260 Give a warning (or error) whenever a function is used before being
1264 Same as @samp{-Wimplicit-int} and @samp{-Wimplicit-function-}@*
1268 Warn if the type of @samp{main} is suspicious. @samp{main} should be a
1269 function with external linkage, returning int, taking either zero
1270 arguments, two, or three arguments of appropriate types.
1273 Warn if a multicharacter constant (@samp{'FOOF'}) is used. Usually they
1274 indicate a typo in the user's code, as they have implementation-defined
1275 values, and should not be used in portable code.
1278 Warn if parentheses are omitted in certain contexts, such
1279 as when there is an assignment in a context where a truth value
1280 is expected, or when operators are nested whose precedence people
1281 often get confused about.
1283 Also warn about constructions where there may be confusion to which
1284 @code{if} statement an @code{else} branch belongs. Here is an example of
1297 In C, every @code{else} branch belongs to the innermost possible @code{if}
1298 statement, which in this example is @code{if (b)}. This is often not
1299 what the programmer expected, as illustrated in the above example by
1300 indentation the programmer chose. When there is the potential for this
1301 confusion, GNU C will issue a warning when this flag is specified.
1302 To eliminate the warning, add explicit braces around the innermost
1303 @code{if} statement so there is no way the @code{else} could belong to
1304 the enclosing @code{if}. The resulting code would look like this:
1319 Warn whenever a function is defined with a return-type that defaults
1320 to @code{int}. Also warn about any @code{return} statement with no
1321 return-value in a function whose return-type is not @code{void}.
1324 Warn whenever a @code{switch} statement has an index of enumeral type
1325 and lacks a @code{case} for one or more of the named codes of that
1326 enumeration. (The presence of a @code{default} label prevents this
1327 warning.) @code{case} labels outside the enumeration range also
1328 provoke warnings when this option is used.
1331 Warn if any trigraphs are encountered (assuming they are enabled).
1334 Warn whenever a variable is unused aside from its declaration,
1335 whenever a function is declared static but never defined, whenever a
1336 label is declared but not used, and whenever a statement computes a
1337 result that is explicitly not used.
1339 In order to get a warning about an unused function parameter, you must
1340 specify both @samp{-W} and @samp{-Wunused}.
1342 To suppress this warning for an expression, simply cast it to void. For
1343 unused variables and parameters, use the @samp{unused} attribute
1344 (@pxref{Variable Attributes}).
1346 @item -Wuninitialized
1347 An automatic variable is used without first being initialized.
1349 These warnings are possible only in optimizing compilation,
1350 because they require data flow information that is computed only
1351 when optimizing. If you don't specify @samp{-O}, you simply won't
1354 These warnings occur only for variables that are candidates for
1355 register allocation. Therefore, they do not occur for a variable that
1356 is declared @code{volatile}, or whose address is taken, or whose size
1357 is other than 1, 2, 4 or 8 bytes. Also, they do not occur for
1358 structures, unions or arrays, even when they are in registers.
1360 Note that there may be no warning about a variable that is used only
1361 to compute a value that itself is never used, because such
1362 computations may be deleted by data flow analysis before the warnings
1365 These warnings are made optional because GNU CC is not smart
1366 enough to see all the reasons why the code might be correct
1367 despite appearing to have an error. Here is one example of how
1386 If the value of @code{y} is always 1, 2 or 3, then @code{x} is
1387 always initialized, but GNU CC doesn't know this. Here is
1388 another common case:
1393 if (change_y) save_y = y, y = new_y;
1395 if (change_y) y = save_y;
1400 This has no bug because @code{save_y} is used only if it is set.
1402 Some spurious warnings can be avoided if you declare all the functions
1403 you use that never return as @code{noreturn}. @xref{Function
1406 @item -Wreorder (C++ only)
1407 @cindex reordering, warning
1408 @cindex warning for reordering of member initializers
1409 Warn when the order of member initializers given in the code does not
1410 match the order in which they must be executed. For instance:
1416 A(): j (0), i (1) @{ @}
1420 Here the compiler will warn that the member initializers for @samp{i}
1421 and @samp{j} will be rearranged to match the declaration order of the
1424 @item -Wtemplate-debugging
1425 @cindex template debugging
1426 When using templates in a C++ program, warn if debugging is not yet
1427 fully available (C++ only).
1429 @item -Wunknown-pragmas
1430 @cindex warning for unknown pragmas
1431 @cindex unknown pragmas, warning
1432 @cindex pragmas, warning of unknown
1433 Warn when a #pragma directive is encountered which is not understood by
1434 GCC. If this command line option is used, warnings will even be issued
1435 for unknown pragmas in system header files. This is not the case if
1436 the warnings were only enabled by the @samp{-Wall} command line option.
1439 All of the above @samp{-W} options combined. This enables all the
1440 warnings about constructions that some users consider questionable, and
1441 that are easy to avoid (or modify to prevent the warning), even in
1442 conjunction with macros.
1445 The following @samp{-W@dots{}} options are not implied by @samp{-Wall}.
1446 Some of them warn about constructions that users generally do not
1447 consider questionable, but which occasionally you might wish to check
1448 for; others warn about constructions that are necessary or hard to avoid
1449 in some cases, and there is no simple way to modify the code to suppress
1454 Print extra warning messages for these events:
1457 @cindex @code{longjmp} warnings
1459 A nonvolatile automatic variable might be changed by a call to
1460 @code{longjmp}. These warnings as well are possible only in
1461 optimizing compilation.
1463 The compiler sees only the calls to @code{setjmp}. It cannot know
1464 where @code{longjmp} will be called; in fact, a signal handler could
1465 call it at any point in the code. As a result, you may get a warning
1466 even when there is in fact no problem because @code{longjmp} cannot
1467 in fact be called at the place which would cause a problem.
1470 A function can return either with or without a value. (Falling
1471 off the end of the function body is considered returning without
1472 a value.) For example, this function would evoke such a
1486 An expression-statement or the left-hand side of a comma expression
1487 contains no side effects.
1488 To suppress the warning, cast the unused expression to void.
1489 For example, an expression such as @samp{x[i,j]} will cause a warning,
1490 but @samp{x[(void)i,j]} will not.
1493 An unsigned value is compared against zero with @samp{<} or @samp{<=}.
1496 A comparison like @samp{x<=y<=z} appears; this is equivalent to
1497 @samp{(x<=y ? 1 : 0) <= z}, which is a different interpretation from
1498 that of ordinary mathematical notation.
1501 Storage-class specifiers like @code{static} are not the first things in
1502 a declaration. According to the C Standard, this usage is obsolescent.
1505 If @samp{-Wall} or @samp{-Wunused} is also specified, warn about unused
1509 A comparison between signed and unsigned values could produce an
1510 incorrect result when the signed value is converted to unsigned.
1511 (But don't warn if @samp{-Wno-sign-compare} is also specified.)
1514 An aggregate has a partly bracketed initializer.
1515 For example, the following code would evoke such a warning,
1516 because braces are missing around the initializer for @code{x.h}:
1519 struct s @{ int f, g; @};
1520 struct t @{ struct s h; int i; @};
1521 struct t x = @{ 1, 2, 3 @};
1525 An aggregate has an initializer which does not initialize all members.
1526 For example, the following code would cause such a warning, because
1527 @code{x.h} would be implicitly initialized to zero:
1530 struct s @{ int f, g, h; @};
1531 struct s x = @{ 3, 4 @};
1536 Warn about certain constructs that behave differently in traditional and
1541 Macro arguments occurring within string constants in the macro body.
1542 These would substitute the argument in traditional C, but are part of
1543 the constant in ANSI C.
1546 A function declared external in one block and then used after the end of
1550 A @code{switch} statement has an operand of type @code{long}.
1554 Warn if an undefined identifier is evaluated in an @samp{#if} directive.
1557 Warn whenever a local variable shadows another local variable.
1559 @item -Wid-clash-@var{len}
1560 Warn whenever two distinct identifiers match in the first @var{len}
1561 characters. This may help you prepare a program that will compile
1562 with certain obsolete, brain-damaged compilers.
1564 @item -Wlarger-than-@var{len}
1565 Warn whenever an object of larger than @var{len} bytes is defined.
1567 @item -Wpointer-arith
1568 Warn about anything that depends on the ``size of'' a function type or
1569 of @code{void}. GNU C assigns these types a size of 1, for
1570 convenience in calculations with @code{void *} pointers and pointers
1573 @item -Wbad-function-cast
1574 Warn whenever a function call is cast to a non-matching type.
1575 For example, warn if @code{int malloc()} is cast to @code{anything *}.
1578 Warn whenever a pointer is cast so as to remove a type qualifier from
1579 the target type. For example, warn if a @code{const char *} is cast
1580 to an ordinary @code{char *}.
1583 Warn whenever a pointer is cast such that the required alignment of the
1584 target is increased. For example, warn if a @code{char *} is cast to
1585 an @code{int *} on machines where integers can only be accessed at
1586 two- or four-byte boundaries.
1588 @item -Wwrite-strings
1589 Give string constants the type @code{const char[@var{length}]} so that
1590 copying the address of one into a non-@code{const} @code{char *}
1591 pointer will get a warning. These warnings will help you find at
1592 compile time code that can try to write into a string constant, but
1593 only if you have been very careful about using @code{const} in
1594 declarations and prototypes. Otherwise, it will just be a nuisance;
1595 this is why we did not make @samp{-Wall} request these warnings.
1598 Warn if a prototype causes a type conversion that is different from what
1599 would happen to the same argument in the absence of a prototype. This
1600 includes conversions of fixed point to floating and vice versa, and
1601 conversions changing the width or signedness of a fixed point argument
1602 except when the same as the default promotion.
1604 Also, warn if a negative integer constant expression is implicitly
1605 converted to an unsigned type. For example, warn about the assignment
1606 @code{x = -1} if @code{x} is unsigned. But do not warn about explicit
1607 casts like @code{(unsigned) -1}.
1609 @item -Wsign-compare
1610 @cindex warning for comparison of signed and unsigned values
1611 @cindex comparison of signed and unsigned values, warning
1612 @cindex signed and unsigned values, comparison warning
1613 Warn when a comparison between signed and unsigned values could produce
1614 an incorrect result when the signed value is converted to unsigned.
1615 This warning is also enabled by @samp{-W}; to get the other warnings
1616 of @samp{-W} without this warning, use @samp{-W -Wno-sign-compare}.
1618 @item -Waggregate-return
1619 Warn if any functions that return structures or unions are defined or
1620 called. (In languages where you can return an array, this also elicits
1623 @item -Wstrict-prototypes
1624 Warn if a function is declared or defined without specifying the
1625 argument types. (An old-style function definition is permitted without
1626 a warning if preceded by a declaration which specifies the argument
1629 @item -Wmissing-prototypes
1630 Warn if a global function is defined without a previous prototype
1631 declaration. This warning is issued even if the definition itself
1632 provides a prototype. The aim is to detect global functions that fail
1633 to be declared in header files.
1635 @item -Wmissing-declarations
1636 Warn if a global function is defined without a previous declaration.
1637 Do so even if the definition itself provides a prototype.
1638 Use this option to detect global functions that are not declared in
1641 @item -Wmissing-noreturn
1642 Warn about functions which might be candidates for attribute @code{noreturn}.
1643 Note these are only possible candidates, not absolute ones. Care should
1644 be taken to manually verify functions actually do not ever return before
1645 adding the @code{noreturn} attribute, otherwise subtle code generation
1646 bugs could be introduced.
1648 @item -Wredundant-decls
1649 Warn if anything is declared more than once in the same scope, even in
1650 cases where multiple declaration is valid and changes nothing.
1652 @item -Wnested-externs
1653 Warn if an @code{extern} declaration is encountered within an function.
1655 @item -Wno-non-template-friend
1656 Disable warnings when non-templatized friend functions are declared
1657 within a template. With the advent of explicit template specification
1658 support in g++, if the name of the friend is an unqualified-id (ie,
1659 @samp{friend foo(int)}), the C++ language specification demands that the
1660 friend declare or define an ordinary, nontemplate function. (Section
1661 14.5.3). Before g++ implemented explicit specification, unqualified-ids
1662 could be interpreted as a particular specialization of a templatized
1663 function. Because this non-conforming behavior is no longer the default
1664 behavior for g++, @samp{-Wnon-template-friend} allows the compiler to
1665 check existing code for potential trouble spots, and is on by default.
1666 This new compiler behavior can also be turned off with the flag
1667 @samp{-fguiding-decls}, which activates the older, non-specification
1668 compiler code, or with @samp{-Wno-non-template-friend} which keeps the
1669 conformant compiler code but disables the helpful warning.
1672 Warn if a function can not be inlined, and either it was declared as inline,
1673 or else the @samp{-finline-functions} option was given.
1675 @item -Wold-style-cast
1676 Warn if an old-style (C-style) cast is used within a program.
1678 @item -Woverloaded-virtual
1679 @cindex overloaded virtual fn, warning
1680 @cindex warning for overloaded virtual fn
1681 Warn when a derived class function declaration may be an error in
1682 defining a virtual function (C++ only). In a derived class, the
1683 definitions of virtual functions must match the type signature of a
1684 virtual function declared in the base class. With this option, the
1685 compiler warns when you define a function with the same name as a
1686 virtual function, but with a type signature that does not match any
1687 declarations from the base class.
1689 @item -Wsynth (C++ only)
1690 @cindex warning for synthesized methods
1691 @cindex synthesized methods, warning
1692 Warn when g++'s synthesis behavior does not match that of cfront. For
1698 A& operator = (int);
1708 In this example, g++ will synthesize a default @samp{A& operator =
1709 (const A&);}, while cfront will use the user-defined @samp{operator =}.
1712 Warn if @samp{long long} type is used. This is default. To inhibit
1713 the warning messages, use @samp{-Wno-long-long}. Flags
1714 @samp{-Wlong-long} and @samp{-Wno-long-long} are taken into account
1715 only when @samp{-pedantic} flag is used.
1718 Make all warnings into errors.
1721 @node Debugging Options
1722 @section Options for Debugging Your Program or GNU CC
1723 @cindex options, debugging
1724 @cindex debugging information options
1726 GNU CC has various special options that are used for debugging
1727 either your program or GCC:
1731 Produce debugging information in the operating system's native format
1732 (stabs, COFF, XCOFF, or DWARF). GDB can work with this debugging
1735 On most systems that use stabs format, @samp{-g} enables use of extra
1736 debugging information that only GDB can use; this extra information
1737 makes debugging work better in GDB but will probably make other debuggers
1739 refuse to read the program. If you want to control for certain whether
1740 to generate the extra information, use @samp{-gstabs+}, @samp{-gstabs},
1741 @samp{-gxcoff+}, @samp{-gxcoff}, @samp{-gdwarf-1+}, or @samp{-gdwarf-1}
1744 Unlike most other C compilers, GNU CC allows you to use @samp{-g} with
1745 @samp{-O}. The shortcuts taken by optimized code may occasionally
1746 produce surprising results: some variables you declared may not exist
1747 at all; flow of control may briefly move where you did not expect it;
1748 some statements may not be executed because they compute constant
1749 results or their values were already at hand; some statements may
1750 execute in different places because they were moved out of loops.
1752 Nevertheless it proves possible to debug optimized output. This makes
1753 it reasonable to use the optimizer for programs that might have bugs.
1755 The following options are useful when GNU CC is generated with the
1756 capability for more than one debugging format.
1759 Produce debugging information for use by GDB. This means to use the
1760 most expressive format available (DWARF 2, stabs, or the native format
1761 if neither of those are supported), including GDB extensions if at all
1765 Produce debugging information in stabs format (if that is supported),
1766 without GDB extensions. This is the format used by DBX on most BSD
1767 systems. On MIPS, Alpha and System V Release 4 systems this option
1768 produces stabs debugging output which is not understood by DBX or SDB.
1769 On System V Release 4 systems this option requires the GNU assembler.
1772 Produce debugging information in stabs format (if that is supported),
1773 using GNU extensions understood only by the GNU debugger (GDB). The
1774 use of these extensions is likely to make other debuggers crash or
1775 refuse to read the program.
1778 Produce debugging information in COFF format (if that is supported).
1779 This is the format used by SDB on most System V systems prior to
1783 Produce debugging information in XCOFF format (if that is supported).
1784 This is the format used by the DBX debugger on IBM RS/6000 systems.
1787 Produce debugging information in XCOFF format (if that is supported),
1788 using GNU extensions understood only by the GNU debugger (GDB). The
1789 use of these extensions is likely to make other debuggers crash or
1790 refuse to read the program, and may cause assemblers other than the GNU
1791 assembler (GAS) to fail with an error.
1794 Produce debugging information in DWARF version 1 format (if that is
1795 supported). This is the format used by SDB on most System V Release 4
1799 Produce debugging information in DWARF version 1 format (if that is
1800 supported), using GNU extensions understood only by the GNU debugger
1801 (GDB). The use of these extensions is likely to make other debuggers
1802 crash or refuse to read the program.
1805 Produce debugging information in DWARF version 2 format (if that is
1806 supported). This is the format used by DBX on IRIX 6.
1809 @itemx -ggdb@var{level}
1810 @itemx -gstabs@var{level}
1811 @itemx -gcoff@var{level}
1812 @itemx -gxcoff@var{level}
1813 @itemx -gdwarf@var{level}
1814 @itemx -gdwarf-2@var{level}
1815 Request debugging information and also use @var{level} to specify how
1816 much information. The default level is 2.
1818 Level 1 produces minimal information, enough for making backtraces in
1819 parts of the program that you don't plan to debug. This includes
1820 descriptions of functions and external variables, but no information
1821 about local variables and no line numbers.
1823 Level 3 includes extra information, such as all the macro definitions
1824 present in the program. Some debuggers support macro expansion when
1829 Generate extra code to write profile information suitable for the
1830 analysis program @code{prof}. You must use this option when compiling
1831 the source files you want data about, and you must also use it when
1834 @cindex @code{gprof}
1836 Generate extra code to write profile information suitable for the
1837 analysis program @code{gprof}. You must use this option when compiling
1838 the source files you want data about, and you must also use it when
1843 Generate extra code to write profile information for basic blocks, which will
1844 record the number of times each basic block is executed, the basic block start
1845 address, and the function name containing the basic block. If @samp{-g} is
1846 used, the line number and filename of the start of the basic block will also be
1847 recorded. If not overridden by the machine description, the default action is
1848 to append to the text file @file{bb.out}.
1850 This data could be analyzed by a program like @code{tcov}. Note,
1851 however, that the format of the data is not what @code{tcov} expects.
1852 Eventually GNU @code{gprof} should be extended to process this data.
1855 Makes the compiler print out each function name as it is compiled, and
1856 print some statistics about each pass when it finishes.
1859 Generate extra code to profile basic blocks. Your executable will
1860 produce output that is a superset of that produced when @samp{-a} is
1861 used. Additional output is the source and target address of the basic
1862 blocks where a jump takes place, the number of times a jump is executed,
1863 and (optionally) the complete sequence of basic blocks being executed.
1864 The output is appended to file @file{bb.out}.
1866 You can examine different profiling aspects without recompilation. Your
1867 executable will read a list of function names from file @file{bb.in}.
1868 Profiling starts when a function on the list is entered and stops when
1869 that invocation is exited. To exclude a function from profiling, prefix
1870 its name with `-'. If a function name is not unique, you can
1871 disambiguate it by writing it in the form
1872 @samp{/path/filename.d:functionname}. Your executable will write the
1873 available paths and filenames in file @file{bb.out}.
1875 Several function names have a special meaning:
1878 Write source, target and frequency of jumps to file @file{bb.out}.
1879 @item __bb_hidecall__
1880 Exclude function calls from frequency count.
1881 @item __bb_showret__
1882 Include function returns in frequency count.
1884 Write the sequence of basic blocks executed to file @file{bbtrace.gz}.
1885 The file will be compressed using the program @samp{gzip}, which must
1886 exist in your @code{PATH}. On systems without the @samp{popen}
1887 function, the file will be named @file{bbtrace} and will not be
1888 compressed. @strong{Profiling for even a few seconds on these systems
1889 will produce a very large file.} Note: @code{__bb_hidecall__} and
1890 @code{__bb_showret__} will not affect the sequence written to
1894 Here's a short example using different profiling parameters
1895 in file @file{bb.in}. Assume function @code{foo} consists of basic blocks
1896 1 and 2 and is called twice from block 3 of function @code{main}. After
1897 the calls, block 3 transfers control to block 4 of @code{main}.
1899 With @code{__bb_trace__} and @code{main} contained in file @file{bb.in},
1900 the following sequence of blocks is written to file @file{bbtrace.gz}:
1901 0 3 1 2 1 2 4. The return from block 2 to block 3 is not shown, because
1902 the return is to a point inside the block and not to the top. The
1903 block address 0 always indicates, that control is transferred
1904 to the trace from somewhere outside the observed functions. With
1905 @samp{-foo} added to @file{bb.in}, the blocks of function
1906 @code{foo} are removed from the trace, so only 0 3 4 remains.
1908 With @code{__bb_jumps__} and @code{main} contained in file @file{bb.in},
1909 jump frequencies will be written to file @file{bb.out}. The
1910 frequencies are obtained by constructing a trace of blocks
1911 and incrementing a counter for every neighbouring pair of blocks
1912 in the trace. The trace 0 3 1 2 1 2 4 displays the following
1916 Jump from block 0x0 to block 0x3 executed 1 time(s)
1917 Jump from block 0x3 to block 0x1 executed 1 time(s)
1918 Jump from block 0x1 to block 0x2 executed 2 time(s)
1919 Jump from block 0x2 to block 0x1 executed 1 time(s)
1920 Jump from block 0x2 to block 0x4 executed 1 time(s)
1923 With @code{__bb_hidecall__}, control transfer due to call instructions
1924 is removed from the trace, that is the trace is cut into three parts: 0
1925 3 4, 0 1 2 and 0 1 2. With @code{__bb_showret__}, control transfer due
1926 to return instructions is added to the trace. The trace becomes: 0 3 1
1927 2 3 1 2 3 4. Note, that this trace is not the same, as the sequence
1928 written to @file{bbtrace.gz}. It is solely used for counting jump
1931 @item -fprofile-arcs
1932 Instrument @dfn{arcs} during compilation. For each function of your
1933 program, GNU CC creates a program flow graph, then finds a spanning tree
1934 for the graph. Only arcs that are not on the spanning tree have to be
1935 instrumented: the compiler adds code to count the number of times that these
1936 arcs are executed. When an arc is the only exit or only entrance to a
1937 block, the instrumentation code can be added to the block; otherwise, a
1938 new basic block must be created to hold the instrumentation code.
1940 Since not every arc in the program must be instrumented, programs
1941 compiled with this option run faster than programs compiled with
1942 @samp{-a}, which adds instrumentation code to every basic block in the
1943 program. The tradeoff: since @code{gcov} does not have
1944 execution counts for all branches, it must start with the execution
1945 counts for the instrumented branches, and then iterate over the program
1946 flow graph until the entire graph has been solved. Hence, @code{gcov}
1947 runs a little more slowly than a program which uses information from
1950 @samp{-fprofile-arcs} also makes it possible to estimate branch
1951 probabilities, and to calculate basic block execution counts. In
1952 general, basic block execution counts do not give enough information to
1953 estimate all branch probabilities. When the compiled program exits, it
1954 saves the arc execution counts to a file called
1955 @file{@var{sourcename}.da}. Use the compiler option
1956 @samp{-fbranch-probabilities} (@pxref{Optimize Options,,Options that
1957 Control Optimization}) when recompiling, to optimize using estimated
1958 branch probabilities.
1961 @item -ftest-coverage
1962 Create data files for the @code{gcov} code-coverage utility
1963 (@pxref{Gcov,, @code{gcov}: a GNU CC Test Coverage Program}).
1964 The data file names begin with the name of your source file:
1967 @item @var{sourcename}.bb
1968 A mapping from basic blocks to line numbers, which @code{gcov} uses to
1969 associate basic block execution counts with line numbers.
1971 @item @var{sourcename}.bbg
1972 A list of all arcs in the program flow graph. This allows @code{gcov}
1973 to reconstruct the program flow graph, so that it can compute all basic
1974 block and arc execution counts from the information in the
1975 @code{@var{sourcename}.da} file (this last file is the output from
1976 @samp{-fprofile-arcs}).
1980 Makes the compiler print out each function name as it is compiled, and
1981 print some statistics about each pass when it finishes.
1983 @item -d@var{letters}
1984 Says to make debugging dumps during compilation at times specified by
1985 @var{letters}. This is used for debugging the compiler. The file names
1986 for most of the dumps are made by appending a word to the source file
1987 name (e.g. @file{foo.c.rtl} or @file{foo.c.jump}). Here are the
1988 possible letters for use in @var{letters}, and their meanings:
1992 Dump after computing branch probabilities, to @file{@var{file}.bp}.
1994 Dump after instruction combination, to the file @file{@var{file}.combine}.
1996 Dump after delayed branch scheduling, to @file{@var{file}.dbr}.
1998 Dump all macro definitions, at the end of preprocessing, in addition to
2001 Dump debugging information during parsing, to standard error.
2003 Dump after RTL generation, to @file{@var{file}.rtl}.
2005 Just generate RTL for a function instead of compiling it. Usually used
2008 Dump after first jump optimization, to @file{@var{file}.jump}.
2010 Dump after CSE (including the jump optimization that sometimes
2011 follows CSE), to @file{@var{file}.cse}.
2013 Dump after purging ADDRESSOF, to @file{@var{file}.addressof}.
2015 Dump after flow analysis, to @file{@var{file}.flow}.
2017 Dump after global register allocation, to @file{@var{file}.greg}.
2019 Dump after GCSE, to @file{@var{file}.gcse}.
2021 Dump after first jump optimization, to @file{@var{file}.jump}.
2023 Dump after last jump optimization, to @file{@var{file}.jump2}.
2025 Dump after conversion from registers to stack, to @file{@var{file}.stack}.
2027 Dump after local register allocation, to @file{@var{file}.lreg}.
2029 Dump after loop optimization, to @file{@var{file}.loop}.
2031 Dump after performing the machine dependent reorganisation pass, to
2032 @file{@var{file}.mach}.
2034 Dump after the register move pass, to @file{@var{file}.regmove}.
2036 Dump after RTL generation, to @file{@var{file}.rtl}.
2038 Dump after the second instruction scheduling pass, to @file{@var{file}.sched2}.
2040 Dump after CSE (including the jump optimization that sometimes follows
2041 CSE), to @file{@var{file}.cse}.
2043 Dump after the first instruction scheduling pass, to @file{@var{file}.sched}.
2045 Dump after the second CSE pass (including the jump optimization that
2046 sometimes follows CSE), to @file{@var{file}.cse2}.
2048 Just generate RTL for a function instead of compiling it. Usually used
2051 Produce all the dumps listed above.
2053 Print statistics on memory usage, at the end of the run, to
2056 Annotate the assembler output with a comment indicating which
2057 pattern and alternative was used.
2059 Dump debugging information during parsing, to standard error.
2061 Annotate the assembler output with miscellaneous debugging information.
2064 @item -fdump-unnumbered
2065 When doing debugging dumps (see -d option above), suppress instruction
2066 numbers and line number note output. This makes it more feasible to
2067 use diff on debugging dumps for compiler invokations with different
2068 options, in particular with and without -g.
2070 @item -fpretend-float
2071 When running a cross-compiler, pretend that the target machine uses the
2072 same floating point format as the host machine. This causes incorrect
2073 output of the actual floating constants, but the actual instruction
2074 sequence will probably be the same as GNU CC would make when running on
2078 Store the usual ``temporary'' intermediate files permanently; place them
2079 in the current directory and name them based on the source file. Thus,
2080 compiling @file{foo.c} with @samp{-c -save-temps} would produce files
2081 @file{foo.i} and @file{foo.s}, as well as @file{foo.o}.
2083 @item -print-file-name=@var{library}
2084 Print the full absolute name of the library file @var{library} that
2085 would be used when linking---and don't do anything else. With this
2086 option, GNU CC does not compile or link anything; it just prints the
2089 @item -print-prog-name=@var{program}
2090 Like @samp{-print-file-name}, but searches for a program such as @samp{cpp}.
2092 @item -print-libgcc-file-name
2093 Same as @samp{-print-file-name=libgcc.a}.
2095 This is useful when you use @samp{-nostdlib} or @samp{-nodefaultlibs}
2096 but you do want to link with @file{libgcc.a}. You can do
2099 gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
2102 @item -print-search-dirs
2103 Print the name of the configured installation directory and a list of
2104 program and library directories gcc will search---and don't do anything else.
2106 This is useful when gcc prints the error message
2107 @samp{installation problem, cannot exec cpp: No such file or directory}.
2108 To resolve this you either need to put @file{cpp} and the other compiler
2109 components where gcc expects to find them, or you can set the environment
2110 variable @code{GCC_EXEC_PREFIX} to the directory where you installed them.
2111 Don't forget the trailing '/'.
2112 @xref{Environment Variables}.
2115 @node Optimize Options
2116 @section Options That Control Optimization
2117 @cindex optimize options
2118 @cindex options, optimization
2120 These options control various sorts of optimizations:
2125 Optimize. Optimizing compilation takes somewhat more time, and a lot
2126 more memory for a large function.
2128 Without @samp{-O}, the compiler's goal is to reduce the cost of
2129 compilation and to make debugging produce the expected results.
2130 Statements are independent: if you stop the program with a breakpoint
2131 between statements, you can then assign a new value to any variable or
2132 change the program counter to any other statement in the function and
2133 get exactly the results you would expect from the source code.
2135 Without @samp{-O}, the compiler only allocates variables declared
2136 @code{register} in registers. The resulting compiled code is a little
2137 worse than produced by PCC without @samp{-O}.
2139 With @samp{-O}, the compiler tries to reduce code size and execution
2142 When you specify @samp{-O}, the compiler turns on @samp{-fthread-jumps}
2143 and @samp{-fdefer-pop} on all machines. The compiler turns on
2144 @samp{-fdelayed-branch} on machines that have delay slots, and
2145 @samp{-fomit-frame-pointer} on machines that can support debugging even
2146 without a frame pointer. On some machines the compiler also turns
2147 on other flags.@refill
2150 Optimize even more. GNU CC performs nearly all supported optimizations
2151 that do not involve a space-speed tradeoff. The compiler does not
2152 perform loop unrolling or function inlining when you specify @samp{-O2}.
2153 As compared to @samp{-O}, this option increases both compilation time
2154 and the performance of the generated code.
2156 @samp{-O2} turns on all optional optimizations except for loop unrolling
2157 and function inlining. It also turns on the @samp{-fforce-mem} option
2158 on all machines and frame pointer elimination on machines where doing so
2159 does not interfere with debugging.
2162 Optimize yet more. @samp{-O3} turns on all optimizations specified by
2163 @samp{-O2} and also turns on the @samp{inline-functions} option.
2169 Optimize for size. @samp{-Os} enables all @samp{-O2} optimizations that
2170 do not typically increase code size. It also performs further
2171 optimizations designed to reduce code size.
2173 If you use multiple @samp{-O} options, with or without level numbers,
2174 the last such option is the one that is effective.
2177 Options of the form @samp{-f@var{flag}} specify machine-independent
2178 flags. Most flags have both positive and negative forms; the negative
2179 form of @samp{-ffoo} would be @samp{-fno-foo}. In the table below,
2180 only one of the forms is listed---the one which is not the default.
2181 You can figure out the other form by either removing @samp{no-} or
2186 Do not store floating point variables in registers, and inhibit other
2187 options that might change whether a floating point value is taken from a
2190 @cindex floating point precision
2191 This option prevents undesirable excess precision on machines such as
2192 the 68000 where the floating registers (of the 68881) keep more
2193 precision than a @code{double} is supposed to have. Similarly for the
2194 x86 architecture. For most programs, the excess precision does only
2195 good, but a few programs rely on the precise definition of IEEE floating
2196 point. Use @samp{-ffloat-store} for such programs, after modifying
2197 them to store all pertinent intermediate computations into variables.
2199 @item -fno-default-inline
2200 Do not make member functions inline by default merely because they are
2201 defined inside the class scope (C++ only). Otherwise, when you specify
2202 @w{@samp{-O}}, member functions defined inside class scope are compiled
2203 inline by default; i.e., you don't need to add @samp{inline} in front of
2204 the member function name.
2206 @item -fno-defer-pop
2207 Always pop the arguments to each function call as soon as that function
2208 returns. For machines which must pop arguments after a function call,
2209 the compiler normally lets arguments accumulate on the stack for several
2210 function calls and pops them all at once.
2213 Force memory operands to be copied into registers before doing
2214 arithmetic on them. This produces better code by making all memory
2215 references potential common subexpressions. When they are not common
2216 subexpressions, instruction combination should eliminate the separate
2217 register-load. The @samp{-O2} option turns on this option.
2220 Force memory address constants to be copied into registers before
2221 doing arithmetic on them. This may produce better code just as
2222 @samp{-fforce-mem} may.
2224 @item -fomit-frame-pointer
2225 Don't keep the frame pointer in a register for functions that
2226 don't need one. This avoids the instructions to save, set up and
2227 restore frame pointers; it also makes an extra register available
2228 in many functions. @strong{It also makes debugging impossible on
2232 On some machines, such as the Vax, this flag has no effect, because
2233 the standard calling sequence automatically handles the frame pointer
2234 and nothing is saved by pretending it doesn't exist. The
2235 machine-description macro @code{FRAME_POINTER_REQUIRED} controls
2236 whether a target machine supports this flag. @xref{Registers}.@refill
2239 On some machines, such as the Vax, this flag has no effect, because
2240 the standard calling sequence automatically handles the frame pointer
2241 and nothing is saved by pretending it doesn't exist. The
2242 machine-description macro @code{FRAME_POINTER_REQUIRED} controls
2243 whether a target machine supports this flag. @xref{Registers,,Register
2244 Usage, gcc.info, Using and Porting GCC}.@refill
2248 Don't pay attention to the @code{inline} keyword. Normally this option
2249 is used to keep the compiler from expanding any functions inline.
2250 Note that if you are not optimizing, no functions can be expanded inline.
2252 @item -finline-functions
2253 Integrate all simple functions into their callers. The compiler
2254 heuristically decides which functions are simple enough to be worth
2255 integrating in this way.
2257 If all calls to a given function are integrated, and the function is
2258 declared @code{static}, then the function is normally not output as
2259 assembler code in its own right.
2261 @item -fkeep-inline-functions
2262 Even if all calls to a given function are integrated, and the function
2263 is declared @code{static}, nevertheless output a separate run-time
2264 callable version of the function. This switch does not affect
2265 @code{extern inline} functions.
2267 @item -fkeep-static-consts
2268 Emit variables declared @code{static const} when optimization isn't turned
2269 on, even if the variables aren't referenced.
2271 GNU CC enables this option by default. If you want to force the compiler to
2272 check if the variable was referenced, regardless of whether or not
2273 optimization is turned on, use the @samp{-fno-keep-static-consts} option.
2275 @item -fno-function-cse
2276 Do not put function addresses in registers; make each instruction that
2277 calls a constant function contain the function's address explicitly.
2279 This option results in less efficient code, but some strange hacks
2280 that alter the assembler output may be confused by the optimizations
2281 performed when this option is not used.
2284 This option allows GCC to violate some ANSI or IEEE rules and/or
2285 specifications in the interest of optimizing code for speed. For
2286 example, it allows the compiler to assume arguments to the @code{sqrt}
2287 function are non-negative numbers and that no floating-point values
2290 This option should never be turned on by any @samp{-O} option since
2291 it can result in incorrect output for programs which depend on
2292 an exact implementation of IEEE or ANSI rules/specifications for
2296 @c following causes underfulls.. they don't look great, but we deal.
2298 The following options control specific optimizations. The @samp{-O2}
2299 option turns on all of these optimizations except @samp{-funroll-loops}
2300 and @samp{-funroll-all-loops}. On most machines, the @samp{-O} option
2301 turns on the @samp{-fthread-jumps} and @samp{-fdelayed-branch} options,
2302 but specific machines may handle it differently.
2304 You can use the following flags in the rare cases when ``fine-tuning''
2305 of optimizations to be performed is desired.
2308 @item -fstrength-reduce
2309 Perform the optimizations of loop strength reduction and
2310 elimination of iteration variables.
2312 @item -fthread-jumps
2313 Perform optimizations where we check to see if a jump branches to a
2314 location where another comparison subsumed by the first is found. If
2315 so, the first branch is redirected to either the destination of the
2316 second branch or a point immediately following it, depending on whether
2317 the condition is known to be true or false.
2319 @item -fcse-follow-jumps
2320 In common subexpression elimination, scan through jump instructions
2321 when the target of the jump is not reached by any other path. For
2322 example, when CSE encounters an @code{if} statement with an
2323 @code{else} clause, CSE will follow the jump when the condition
2326 @item -fcse-skip-blocks
2327 This is similar to @samp{-fcse-follow-jumps}, but causes CSE to
2328 follow jumps which conditionally skip over blocks. When CSE
2329 encounters a simple @code{if} statement with no else clause,
2330 @samp{-fcse-skip-blocks} causes CSE to follow the jump around the
2331 body of the @code{if}.
2333 @item -frerun-cse-after-loop
2334 Re-run common subexpression elimination after loop optimizations has been
2337 @item -frerun-loop-opt
2338 Run the loop optimizer twice.
2341 Perform a global common subexpression elimination pass.
2342 This pass also performs global constant and copy propagation.
2344 @item -fexpensive-optimizations
2345 Perform a number of minor optimizations that are relatively expensive.
2347 @item -foptimize-register-moves
2349 Attempt to reassign register numbers in move instructions and as
2350 operands of other simple instructions in order to maximize the amount of
2351 register tying. This is especially helpful on machines with two-operand
2352 instructions. GNU CC enables this optimization by default with @samp{-O2}
2355 Note @code{-fregmove} and @code{-foptimize-register-moves} are the same
2358 @item -fdelayed-branch
2359 If supported for the target machine, attempt to reorder instructions
2360 to exploit instruction slots available after delayed branch
2363 @item -fschedule-insns
2364 If supported for the target machine, attempt to reorder instructions to
2365 eliminate execution stalls due to required data being unavailable. This
2366 helps machines that have slow floating point or memory load instructions
2367 by allowing other instructions to be issued until the result of the load
2368 or floating point instruction is required.
2370 @item -fschedule-insns2
2371 Similar to @samp{-fschedule-insns}, but requests an additional pass of
2372 instruction scheduling after register allocation has been done. This is
2373 especially useful on machines with a relatively small number of
2374 registers and where memory load instructions take more than one cycle.
2376 @item -ffunction-sections
2377 @item -fdata-sections
2378 Place each function or data item into its own section in the output
2379 file if the target supports arbitrary sections. The name of the
2380 function or the name of the data item determines the section's name
2383 Use these options on systems where the linker can perform optimizations
2384 to improve locality of reference in the instruction space. HPPA
2385 processors running HP-UX and Sparc processors running Solaris 2 have
2386 linkers with such optimizations. Other systems using the ELF object format
2387 as well as AIX may have these optimizations in the future.
2389 Only use these options when there are significant benefits from doing
2390 so. When you specify these options, the assembler and linker will
2391 create larger object and executable files and will also be slower.
2392 You will not be able to use @code{gprof} on all systems if you
2393 specify this option and you may have problems with debugging if
2394 you specify both this option and @samp{-g}.
2396 @item -fcaller-saves
2397 Enable values to be allocated in registers that will be clobbered by
2398 function calls, by emitting extra instructions to save and restore the
2399 registers around such calls. Such allocation is done only when it
2400 seems to result in better code than would otherwise be produced.
2402 This option is always enabled by default on certain machines, usually
2403 those which have no call-preserved registers to use instead.
2405 For all machines, optimization level 2 and higher enables this flag by
2408 @item -funroll-loops
2409 Perform the optimization of loop unrolling. This is only done for loops
2410 whose number of iterations can be determined at compile time or run time.
2411 @samp{-funroll-loop} implies both @samp{-fstrength-reduce} and
2412 @samp{-frerun-cse-after-loop}.
2414 @item -funroll-all-loops
2415 Perform the optimization of loop unrolling. This is done for all loops
2416 and usually makes programs run more slowly. @samp{-funroll-all-loops}
2417 implies @samp{-fstrength-reduce} as well as @samp{-frerun-cse-after-loop}.
2419 @item -fmove-all-movables
2420 Forces all invariant computations in loops to be moved
2423 @item -freduce-all-givs
2424 Forces all general-induction variables in loops to be
2427 @emph{Note:} When compiling programs written in Fortran,
2428 @samp{-fmove-all-moveables} and @samp{-freduce-all-givs} are enabled
2429 by default when you use the optimizer.
2431 These options may generate better or worse code; results are highly
2432 dependent on the structure of loops within the source code.
2434 These two options are intended to be removed someday, once
2435 they have helped determine the efficacy of various
2436 approaches to improving loop optimizations.
2438 Please let us (@code{egcs@@cygnus.com} and @code{fortran@@gnu.org})
2439 know how use of these options affects
2440 the performance of your production code.
2441 We're very interested in code that runs @emph{slower}
2442 when these options are @emph{enabled}.
2445 Disable any machine-specific peephole optimizations.
2447 @item -fbranch-probabilities
2448 After running a program compiled with @samp{-fprofile-arcs}
2449 (@pxref{Debugging Options,, Options for Debugging Your Program or
2450 @code{gcc}}), you can compile it a second time using
2451 @samp{-fbranch-probabilities}, to improve optimizations based on
2452 guessing the path a branch might take.
2455 With @samp{-fbranch-probabilities}, GCC puts a @samp{REG_EXEC_COUNT}
2456 note on the first instruction of each basic block, and a
2457 @samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}.
2458 These can be used to improve optimization. Currently, they are only
2459 used in one place: in @file{reorg.c}, instead of guessing which path a
2460 branch is mostly to take, the @samp{REG_BR_PROB} values are used to
2461 exactly determine which path is taken more often.
2464 @item -fstrict-aliasing
2465 Allows the compiler to assume the strictest aliasing rules applicable to
2466 the language being compiled. For C (and C++), this activates
2467 optimizations based on the type of expressions. In particular, an
2468 object of one type is assumed never to reside at the same address as an
2469 object of a different type, unless the types are almost the same. For
2470 example, an @code{unsigned int} can alias an @code{int}, but not a
2471 @code{void*} or a @code{double}. A character type may alias any other
2474 Pay special attention to code like this:
2487 The practice of reading from a different union member than the one most
2488 recently written to (called ``type-punning'') is common. Even with
2489 @samp{-fstrict-aliasing}, type-punning is allowed, provided the memory
2490 is accessed through the union type. So, the code above will work as
2491 expected. However, this code might not:
2503 Every language that wishes to perform language-specific alias analysis
2504 should define a function that computes, given an @code{tree}
2505 node, an alias set for the node. Nodes in different alias sets are not
2506 allowed to alias. For an example, see the C front-end function
2507 @code{c_get_alias_set}.
2512 @node Preprocessor Options
2513 @section Options Controlling the Preprocessor
2514 @cindex preprocessor options
2515 @cindex options, preprocessor
2517 These options control the C preprocessor, which is run on each C source
2518 file before actual compilation.
2520 If you use the @samp{-E} option, nothing is done except preprocessing.
2521 Some of these options make sense only together with @samp{-E} because
2522 they cause the preprocessor output to be unsuitable for actual
2526 @item -include @var{file}
2527 Process @var{file} as input before processing the regular input file.
2528 In effect, the contents of @var{file} are compiled first. Any @samp{-D}
2529 and @samp{-U} options on the command line are always processed before
2530 @samp{-include @var{file}}, regardless of the order in which they are
2531 written. All the @samp{-include} and @samp{-imacros} options are
2532 processed in the order in which they are written.
2534 @item -imacros @var{file}
2535 Process @var{file} as input, discarding the resulting output, before
2536 processing the regular input file. Because the output generated from
2537 @var{file} is discarded, the only effect of @samp{-imacros @var{file}}
2538 is to make the macros defined in @var{file} available for use in the
2541 Any @samp{-D} and @samp{-U} options on the command line are always
2542 processed before @samp{-imacros @var{file}}, regardless of the order in
2543 which they are written. All the @samp{-include} and @samp{-imacros}
2544 options are processed in the order in which they are written.
2546 @item -idirafter @var{dir}
2547 @cindex second include path
2548 Add the directory @var{dir} to the second include path. The directories
2549 on the second include path are searched when a header file is not found
2550 in any of the directories in the main include path (the one that
2553 @item -iprefix @var{prefix}
2554 Specify @var{prefix} as the prefix for subsequent @samp{-iwithprefix}
2557 @item -iwithprefix @var{dir}
2558 Add a directory to the second include path. The directory's name is
2559 made by concatenating @var{prefix} and @var{dir}, where @var{prefix} was
2560 specified previously with @samp{-iprefix}. If you have not specified a
2561 prefix yet, the directory containing the installed passes of the
2562 compiler is used as the default.
2564 @item -iwithprefixbefore @var{dir}
2565 Add a directory to the main include path. The directory's name is made
2566 by concatenating @var{prefix} and @var{dir}, as in the case of
2567 @samp{-iwithprefix}.
2569 @item -isystem @var{dir}
2570 Add a directory to the beginning of the second include path, marking it
2571 as a system directory, so that it gets the same special treatment as
2572 is applied to the standard system directories.
2575 Do not search the standard system directories for header files. Only
2576 the directories you have specified with @samp{-I} options (and the
2577 current directory, if appropriate) are searched. @xref{Directory
2578 Options}, for information on @samp{-I}.
2580 By using both @samp{-nostdinc} and @samp{-I-}, you can limit the include-file
2581 search path to only those directories you specify explicitly.
2584 Do not predefine any nonstandard macros. (Including architecture flags).
2587 Run only the C preprocessor. Preprocess all the C source files
2588 specified and output the results to standard output or to the
2589 specified output file.
2592 Tell the preprocessor not to discard comments. Used with the
2596 Tell the preprocessor not to generate @samp{#line} directives.
2597 Used with the @samp{-E} option.
2600 @cindex dependencies, make
2602 Tell the preprocessor to output a rule suitable for @code{make}
2603 describing the dependencies of each object file. For each source file,
2604 the preprocessor outputs one @code{make}-rule whose target is the object
2605 file name for that source file and whose dependencies are all the
2606 @code{#include} header files it uses. This rule may be a single line or
2607 may be continued with @samp{\}-newline if it is long. The list of rules
2608 is printed on standard output instead of the preprocessed C program.
2610 @samp{-M} implies @samp{-E}.
2612 Another way to specify output of a @code{make} rule is by setting
2613 the environment variable @code{DEPENDENCIES_OUTPUT} (@pxref{Environment
2617 Like @samp{-M} but the output mentions only the user header files
2618 included with @samp{#include "@var{file}"}. System header files
2619 included with @samp{#include <@var{file}>} are omitted.
2622 Like @samp{-M} but the dependency information is written to a file made by
2623 replacing ".c" with ".d" at the end of the input file names.
2624 This is in addition to compiling the file as specified---@samp{-MD} does
2625 not inhibit ordinary compilation the way @samp{-M} does.
2627 In Mach, you can use the utility @code{md} to merge multiple dependency
2628 files into a single dependency file suitable for using with the @samp{make}
2632 Like @samp{-MD} except mention only user header files, not system
2636 Treat missing header files as generated files and assume they live in the
2637 same directory as the source file. If you specify @samp{-MG}, you
2638 must also specify either @samp{-M} or @samp{-MM}. @samp{-MG} is not
2639 supported with @samp{-MD} or @samp{-MMD}.
2642 Print the name of each header file used, in addition to other normal
2645 @item -A@var{question}(@var{answer})
2646 Assert the answer @var{answer} for @var{question}, in case it is tested
2647 with a preprocessing conditional such as @samp{#if
2648 #@var{question}(@var{answer})}. @samp{-A-} disables the standard
2649 assertions that normally describe the target machine.
2652 Define macro @var{macro} with the string @samp{1} as its definition.
2654 @item -D@var{macro}=@var{defn}
2655 Define macro @var{macro} as @var{defn}. All instances of @samp{-D} on
2656 the command line are processed before any @samp{-U} options.
2659 Undefine macro @var{macro}. @samp{-U} options are evaluated after all
2660 @samp{-D} options, but before any @samp{-include} and @samp{-imacros}
2664 Tell the preprocessor to output only a list of the macro definitions
2665 that are in effect at the end of preprocessing. Used with the @samp{-E}
2669 Tell the preprocessing to pass all macro definitions into the output, in
2670 their proper sequence in the rest of the output.
2673 Like @samp{-dD} except that the macro arguments and contents are omitted.
2674 Only @samp{#define @var{name}} is included in the output.
2677 Support ANSI C trigraphs. The @samp{-ansi} option also has this effect.
2679 @item -Wp,@var{option}
2680 Pass @var{option} as an option to the preprocessor. If @var{option}
2681 contains commas, it is split into multiple options at the commas.
2684 @node Assembler Options
2685 @section Passing Options to the Assembler
2687 @c prevent bad page break with this line
2688 You can pass options to the assembler.
2691 @item -Wa,@var{option}
2692 Pass @var{option} as an option to the assembler. If @var{option}
2693 contains commas, it is split into multiple options at the commas.
2697 @section Options for Linking
2698 @cindex link options
2699 @cindex options, linking
2701 These options come into play when the compiler links object files into
2702 an executable output file. They are meaningless if the compiler is
2703 not doing a link step.
2707 @item @var{object-file-name}
2708 A file name that does not end in a special recognized suffix is
2709 considered to name an object file or library. (Object files are
2710 distinguished from libraries by the linker according to the file
2711 contents.) If linking is done, these object files are used as input
2717 If any of these options is used, then the linker is not run, and
2718 object file names should not be used as arguments. @xref{Overall
2722 @item -l@var{library}
2723 Search the library named @var{library} when linking.
2725 It makes a difference where in the command you write this option; the
2726 linker searches processes libraries and object files in the order they
2727 are specified. Thus, @samp{foo.o -lz bar.o} searches library @samp{z}
2728 after file @file{foo.o} but before @file{bar.o}. If @file{bar.o} refers
2729 to functions in @samp{z}, those functions may not be loaded.
2731 The linker searches a standard list of directories for the library,
2732 which is actually a file named @file{lib@var{library}.a}. The linker
2733 then uses this file as if it had been specified precisely by name.
2735 The directories searched include several standard system directories
2736 plus any that you specify with @samp{-L}.
2738 Normally the files found this way are library files---archive files
2739 whose members are object files. The linker handles an archive file by
2740 scanning through it for members which define symbols that have so far
2741 been referenced but not defined. But if the file that is found is an
2742 ordinary object file, it is linked in the usual fashion. The only
2743 difference between using an @samp{-l} option and specifying a file name
2744 is that @samp{-l} surrounds @var{library} with @samp{lib} and @samp{.a}
2745 and searches several directories.
2748 You need this special case of the @samp{-l} option in order to
2749 link an Objective C program.
2752 Do not use the standard system startup files when linking.
2753 The standard system libraries are used normally, unless @code{-nostdlib}
2754 or @code{-nodefaultlibs} is used.
2756 @item -nodefaultlibs
2757 Do not use the standard system libraries when linking.
2758 Only the libraries you specify will be passed to the linker.
2759 The standard startup files are used normally, unless @code{-nostartfiles}
2760 is used. The compiler may generate calls to memcmp, memset, and memcpy
2761 for System V (and ANSI C) environments or to bcopy and bzero for
2762 BSD environments. These entries are usually resolved by entries in
2763 libc. These entry points should be supplied through some other
2764 mechanism when this option is specified.
2767 Do not use the standard system startup files or libraries when linking.
2768 No startup files and only the libraries you specify will be passed to
2769 the linker. The compiler may generate calls to memcmp, memset, and memcpy
2770 for System V (and ANSI C) environments or to bcopy and bzero for
2771 BSD environments. These entries are usually resolved by entries in
2772 libc. These entry points should be supplied through some other
2773 mechanism when this option is specified.
2775 @cindex @code{-lgcc}, use with @code{-nostdlib}
2776 @cindex @code{-nostdlib} and unresolved references
2777 @cindex unresolved references and @code{-nostdlib}
2778 @cindex @code{-lgcc}, use with @code{-nodefaultlibs}
2779 @cindex @code{-nodefaultlibs} and unresolved references
2780 @cindex unresolved references and @code{-nodefaultlibs}
2781 One of the standard libraries bypassed by @samp{-nostdlib} and
2782 @samp{-nodefaultlibs} is @file{libgcc.a}, a library of internal subroutines
2783 that GNU CC uses to overcome shortcomings of particular machines, or special
2784 needs for some languages.
2786 (@xref{Interface,,Interfacing to GNU CC Output}, for more discussion of
2790 (@xref{Interface,,Interfacing to GNU CC Output,gcc.info,Porting GNU CC},
2791 for more discussion of @file{libgcc.a}.)
2793 In most cases, you need @file{libgcc.a} even when you want to avoid
2794 other standard libraries. In other words, when you specify @samp{-nostdlib}
2795 or @samp{-nodefaultlibs} you should usually specify @samp{-lgcc} as well.
2796 This ensures that you have no unresolved references to internal GNU CC
2797 library subroutines. (For example, @samp{__main}, used to ensure C++
2798 constructors will be called; @pxref{Collect2,,@code{collect2}}.)
2801 Remove all symbol table and relocation information from the executable.
2804 On systems that support dynamic linking, this prevents linking with the shared
2805 libraries. On other systems, this option has no effect.
2808 Produce a shared object which can then be linked with other objects to
2809 form an executable. Not all systems support this option. You must
2810 also specify @samp{-fpic} or @samp{-fPIC} on some systems when
2811 you specify this option.
2814 Bind references to global symbols when building a shared object. Warn
2815 about any unresolved references (unless overridden by the link editor
2816 option @samp{-Xlinker -z -Xlinker defs}). Only a few systems support
2819 @item -Xlinker @var{option}
2820 Pass @var{option} as an option to the linker. You can use this to
2821 supply system-specific linker options which GNU CC does not know how to
2824 If you want to pass an option that takes an argument, you must use
2825 @samp{-Xlinker} twice, once for the option and once for the argument.
2826 For example, to pass @samp{-assert definitions}, you must write
2827 @samp{-Xlinker -assert -Xlinker definitions}. It does not work to write
2828 @samp{-Xlinker "-assert definitions"}, because this passes the entire
2829 string as a single argument, which is not what the linker expects.
2831 @item -Wl,@var{option}
2832 Pass @var{option} as an option to the linker. If @var{option} contains
2833 commas, it is split into multiple options at the commas.
2835 @item -u @var{symbol}
2836 Pretend the symbol @var{symbol} is undefined, to force linking of
2837 library modules to define it. You can use @samp{-u} multiple times with
2838 different symbols to force loading of additional library modules.
2841 @node Directory Options
2842 @section Options for Directory Search
2843 @cindex directory options
2844 @cindex options, directory search
2847 These options specify directories to search for header files, for
2848 libraries and for parts of the compiler:
2852 Add the directory @var{dir} to the head of the list of directories to be
2853 searched for header files. This can be used to override a system header
2854 file, substituting your own version, since these directories are
2855 searched before the system header file directories. If you use more
2856 than one @samp{-I} option, the directories are scanned in left-to-right
2857 order; the standard system directories come after.
2860 Any directories you specify with @samp{-I} options before the @samp{-I-}
2861 option are searched only for the case of @samp{#include "@var{file}"};
2862 they are not searched for @samp{#include <@var{file}>}.
2864 If additional directories are specified with @samp{-I} options after
2865 the @samp{-I-}, these directories are searched for all @samp{#include}
2866 directives. (Ordinarily @emph{all} @samp{-I} directories are used
2869 In addition, the @samp{-I-} option inhibits the use of the current
2870 directory (where the current input file came from) as the first search
2871 directory for @samp{#include "@var{file}"}. There is no way to
2872 override this effect of @samp{-I-}. With @samp{-I.} you can specify
2873 searching the directory which was current when the compiler was
2874 invoked. That is not exactly the same as what the preprocessor does
2875 by default, but it is often satisfactory.
2877 @samp{-I-} does not inhibit the use of the standard system directories
2878 for header files. Thus, @samp{-I-} and @samp{-nostdinc} are
2882 Add directory @var{dir} to the list of directories to be searched
2885 @item -B@var{prefix}
2886 This option specifies where to find the executables, libraries,
2887 include files, and data files of the compiler itself.
2889 The compiler driver program runs one or more of the subprograms
2890 @file{cpp}, @file{cc1}, @file{as} and @file{ld}. It tries
2891 @var{prefix} as a prefix for each program it tries to run, both with and
2892 without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}).
2894 For each subprogram to be run, the compiler driver first tries the
2895 @samp{-B} prefix, if any. If that name is not found, or if @samp{-B}
2896 was not specified, the driver tries two standard prefixes, which are
2897 @file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc-lib/}. If neither of
2898 those results in a file name that is found, the unmodified program
2899 name is searched for using the directories specified in your
2900 @samp{PATH} environment variable.
2902 @samp{-B} prefixes that effectively specify directory names also apply
2903 to libraries in the linker, because the compiler translates these
2904 options into @samp{-L} options for the linker. They also apply to
2905 includes files in the preprocessor, because the compiler translates these
2906 options into @samp{-isystem} options for the preprocessor. In this case,
2907 the compiler appends @samp{include} to the prefix.
2909 The run-time support file @file{libgcc.a} can also be searched for using
2910 the @samp{-B} prefix, if needed. If it is not found there, the two
2911 standard prefixes above are tried, and that is all. The file is left
2912 out of the link if it is not found by those means.
2914 Another way to specify a prefix much like the @samp{-B} prefix is to use
2915 the environment variable @code{GCC_EXEC_PREFIX}. @xref{Environment
2918 @item -specs=@var{file}
2919 Process @var{file} after the compiler reads in the standard @file{specs}
2920 file, in order to override the defaults that the @file{gcc} driver
2921 program uses when determining what switches to pass to @file{cc1},
2922 @file{cc1plus}, @file{as}, @file{ld}, etc. More than one
2923 @samp{-specs=}@var{file} can be specified on the command line, and they
2924 are processed in order, from left to right.
2927 @node Target Options
2928 @section Specifying Target Machine and Compiler Version
2929 @cindex target options
2930 @cindex cross compiling
2931 @cindex specifying machine version
2932 @cindex specifying compiler version and target machine
2933 @cindex compiler version, specifying
2934 @cindex target machine, specifying
2936 By default, GNU CC compiles code for the same type of machine that you
2937 are using. However, it can also be installed as a cross-compiler, to
2938 compile for some other type of machine. In fact, several different
2939 configurations of GNU CC, for different target machines, can be
2940 installed side by side. Then you specify which one to use with the
2943 In addition, older and newer versions of GNU CC can be installed side
2944 by side. One of them (probably the newest) will be the default, but
2945 you may sometimes wish to use another.
2948 @item -b @var{machine}
2949 The argument @var{machine} specifies the target machine for compilation.
2950 This is useful when you have installed GNU CC as a cross-compiler.
2952 The value to use for @var{machine} is the same as was specified as the
2953 machine type when configuring GNU CC as a cross-compiler. For
2954 example, if a cross-compiler was configured with @samp{configure
2955 i386v}, meaning to compile for an 80386 running System V, then you
2956 would specify @samp{-b i386v} to run that cross compiler.
2958 When you do not specify @samp{-b}, it normally means to compile for
2959 the same type of machine that you are using.
2961 @item -V @var{version}
2962 The argument @var{version} specifies which version of GNU CC to run.
2963 This is useful when multiple versions are installed. For example,
2964 @var{version} might be @samp{2.0}, meaning to run GNU CC version 2.0.
2966 The default version, when you do not specify @samp{-V}, is the last
2967 version of GNU CC that you installed.
2970 The @samp{-b} and @samp{-V} options actually work by controlling part of
2971 the file name used for the executable files and libraries used for
2972 compilation. A given version of GNU CC, for a given target machine, is
2973 normally kept in the directory @file{/usr/local/lib/gcc-lib/@var{machine}/@var{version}}.@refill
2975 Thus, sites can customize the effect of @samp{-b} or @samp{-V} either by
2976 changing the names of these directories or adding alternate names (or
2977 symbolic links). If in directory @file{/usr/local/lib/gcc-lib/} the
2978 file @file{80386} is a link to the file @file{i386v}, then @samp{-b
2979 80386} becomes an alias for @samp{-b i386v}.
2981 In one respect, the @samp{-b} or @samp{-V} do not completely change
2982 to a different compiler: the top-level driver program @code{gcc}
2983 that you originally invoked continues to run and invoke the other
2984 executables (preprocessor, compiler per se, assembler and linker)
2985 that do the real work. However, since no real work is done in the
2986 driver program, it usually does not matter that the driver program
2987 in use is not the one for the specified target and version.
2989 The only way that the driver program depends on the target machine is
2990 in the parsing and handling of special machine-specific options.
2991 However, this is controlled by a file which is found, along with the
2992 other executables, in the directory for the specified version and
2993 target machine. As a result, a single installed driver program adapts
2994 to any specified target machine and compiler version.
2996 The driver program executable does control one significant thing,
2997 however: the default version and target machine. Therefore, you can
2998 install different instances of the driver program, compiled for
2999 different targets or versions, under different names.
3001 For example, if the driver for version 2.0 is installed as @code{ogcc}
3002 and that for version 2.1 is installed as @code{gcc}, then the command
3003 @code{gcc} will use version 2.1 by default, while @code{ogcc} will use
3004 2.0 by default. However, you can choose either version with either
3005 command with the @samp{-V} option.
3007 @node Submodel Options
3008 @section Hardware Models and Configurations
3009 @cindex submodel options
3010 @cindex specifying hardware config
3011 @cindex hardware models and configurations, specifying
3012 @cindex machine dependent options
3014 Earlier we discussed the standard option @samp{-b} which chooses among
3015 different installed compilers for completely different target
3016 machines, such as Vax vs. 68000 vs. 80386.
3018 In addition, each of these target machine types can have its own
3019 special options, starting with @samp{-m}, to choose among various
3020 hardware models or configurations---for example, 68010 vs 68020,
3021 floating coprocessor or none. A single installed version of the
3022 compiler can compile for any model or configuration, according to the
3025 Some configurations of the compiler also support additional special
3026 options, usually for compatibility with other compilers on the same
3030 These options are defined by the macro @code{TARGET_SWITCHES} in the
3031 machine description. The default for the options is also defined by
3032 that macro, which enables you to change the defaults.
3047 * RS/6000 and PowerPC Options::
3052 * Intel 960 Options::
3053 * DEC Alpha Options::
3057 * System V Options::
3063 @node M680x0 Options
3064 @subsection M680x0 Options
3065 @cindex M680x0 options
3067 These are the @samp{-m} options defined for the 68000 series. The default
3068 values for these options depends on which style of 68000 was selected when
3069 the compiler was configured; the defaults for the most common choices are
3075 Generate output for a 68000. This is the default
3076 when the compiler is configured for 68000-based systems.
3078 Use this option for microcontrollers with a 68000 or EC000 core,
3079 including the 68008, 68302, 68306, 68307, 68322, 68328 and 68356.
3083 Generate output for a 68020. This is the default
3084 when the compiler is configured for 68020-based systems.
3087 Generate output containing 68881 instructions for floating point.
3088 This is the default for most 68020 systems unless @samp{-nfp} was
3089 specified when the compiler was configured.
3092 Generate output for a 68030. This is the default when the compiler is
3093 configured for 68030-based systems.
3096 Generate output for a 68040. This is the default when the compiler is
3097 configured for 68040-based systems.
3099 This option inhibits the use of 68881/68882 instructions that have to be
3100 emulated by software on the 68040. Use this option if your 68040 does not
3101 have code to emulate those instructions.
3104 Generate output for a 68060. This is the default when the compiler is
3105 configured for 68060-based systems.
3107 This option inhibits the use of 68020 and 68881/68882 instructions that
3108 have to be emulated by software on the 68060. Use this option if your 68060
3109 does not have code to emulate those instructions.
3112 Generate output for a CPU32. This is the default
3113 when the compiler is configured for CPU32-based systems.
3115 Use this option for microcontrollers with a
3116 CPU32 or CPU32+ core, including the 68330, 68331, 68332, 68333, 68334,
3117 68336, 68340, 68341, 68349 and 68360.
3120 Generate output for a 520X "coldfire" family cpu. This is the default
3121 when the compiler is configured for 520X-based systems.
3123 Use this option for microcontroller with a 5200 core, including
3124 the MCF5202, MCF5203, MCF5204 and MCF5202.
3128 Generate output for a 68040, without using any of the new instructions.
3129 This results in code which can run relatively efficiently on either a
3130 68020/68881 or a 68030 or a 68040. The generated code does use the
3131 68881 instructions that are emulated on the 68040.
3134 Generate output for a 68060, without using any of the new instructions.
3135 This results in code which can run relatively efficiently on either a
3136 68020/68881 or a 68030 or a 68040. The generated code does use the
3137 68881 instructions that are emulated on the 68060.
3140 Generate output containing Sun FPA instructions for floating point.
3143 Generate output containing library calls for floating point.
3144 @strong{Warning:} the requisite libraries are not available for all m68k
3145 targets. Normally the facilities of the machine's usual C compiler are
3146 used, but this can't be done directly in cross-compilation. You must
3147 make your own arrangements to provide suitable library functions for
3148 cross-compilation. The embedded targets @samp{m68k-*-aout} and
3149 @samp{m68k-*-coff} do provide software floating point support.
3152 Consider type @code{int} to be 16 bits wide, like @code{short int}.
3155 Do not use the bit-field instructions. The @samp{-m68000}, @samp{-mcpu32}
3156 and @samp{-m5200} options imply @w{@samp{-mnobitfield}}.
3159 Do use the bit-field instructions. The @samp{-m68020} option implies
3160 @samp{-mbitfield}. This is the default if you use a configuration
3161 designed for a 68020.
3164 Use a different function-calling convention, in which functions
3165 that take a fixed number of arguments return with the @code{rtd}
3166 instruction, which pops their arguments while returning. This
3167 saves one instruction in the caller since there is no need to pop
3168 the arguments there.
3170 This calling convention is incompatible with the one normally
3171 used on Unix, so you cannot use it if you need to call libraries
3172 compiled with the Unix compiler.
3174 Also, you must provide function prototypes for all functions that
3175 take variable numbers of arguments (including @code{printf});
3176 otherwise incorrect code will be generated for calls to those
3179 In addition, seriously incorrect code will result if you call a
3180 function with too many arguments. (Normally, extra arguments are
3181 harmlessly ignored.)
3183 The @code{rtd} instruction is supported by the 68010, 68020, 68030,
3184 68040, 68060 and CPU32 processors, but not by the 68000 or 5200.
3187 @itemx -mno-align-int
3188 Control whether GNU CC aligns @code{int}, @code{long}, @code{long long},
3189 @code{float}, @code{double}, and @code{long double} variables on a 32-bit
3190 boundary (@samp{-malign-int}) or a 16-bit boundary (@samp{-mno-align-int}).
3191 Aligning variables on 32-bit boundaries produces code that runs somewhat
3192 faster on processors with 32-bit busses at the expense of more memory.
3194 @strong{Warning:} if you use the @samp{-malign-int} switch, GNU CC will
3195 align structures containing the above types differently than
3196 most published application binary interface specifications for the m68k.
3201 @subsection VAX Options
3204 These @samp{-m} options are defined for the Vax:
3208 Do not output certain jump instructions (@code{aobleq} and so on)
3209 that the Unix assembler for the Vax cannot handle across long
3213 Do output those jump instructions, on the assumption that you
3214 will assemble with the GNU assembler.
3217 Output code for g-format floating point numbers instead of d-format.
3221 @subsection SPARC Options
3222 @cindex SPARC options
3224 These @samp{-m} switches are supported on the SPARC:
3229 Specify @samp{-mapp-regs} to generate output using the global registers
3230 2 through 4, which the SPARC SVR4 ABI reserves for applications. This
3233 To be fully SVR4 ABI compliant at the cost of some performance loss,
3234 specify @samp{-mno-app-regs}. You should compile libraries and system
3235 software with this option.
3239 Generate output containing floating point instructions. This is the
3244 Generate output containing library calls for floating point.
3245 @strong{Warning:} the requisite libraries are not available for all SPARC
3246 targets. Normally the facilities of the machine's usual C compiler are
3247 used, but this cannot be done directly in cross-compilation. You must make
3248 your own arrangements to provide suitable library functions for
3249 cross-compilation. The embedded targets @samp{sparc-*-aout} and
3250 @samp{sparclite-*-*} do provide software floating point support.
3252 @samp{-msoft-float} changes the calling convention in the output file;
3253 therefore, it is only useful if you compile @emph{all} of a program with
3254 this option. In particular, you need to compile @file{libgcc.a}, the
3255 library that comes with GNU CC, with @samp{-msoft-float} in order for
3258 @item -mhard-quad-float
3259 Generate output containing quad-word (long double) floating point
3262 @item -msoft-quad-float
3263 Generate output containing library calls for quad-word (long double)
3264 floating point instructions. The functions called are those specified
3265 in the SPARC ABI. This is the default.
3267 As of this writing, there are no sparc implementations that have hardware
3268 support for the quad-word floating point instructions. They all invoke
3269 a trap handler for one of these instructions, and then the trap handler
3270 emulates the effect of the instruction. Because of the trap handler overhead,
3271 this is much slower than calling the ABI library routines. Thus the
3272 @samp{-msoft-quad-float} option is the default.
3276 With @samp{-mepilogue} (the default), the compiler always emits code for
3277 function exit at the end of each function. Any function exit in
3278 the middle of the function (such as a return statement in C) will
3279 generate a jump to the exit code at the end of the function.
3281 With @samp{-mno-epilogue}, the compiler tries to emit exit code inline
3282 at every function exit.
3286 With @samp{-mflat}, the compiler does not generate save/restore instructions
3287 and will use a "flat" or single register window calling convention.
3288 This model uses %i7 as the frame pointer and is compatible with the normal
3289 register window model. Code from either may be intermixed.
3290 The local registers and the input registers (0-5) are still treated as
3291 "call saved" registers and will be saved on the stack as necessary.
3293 With @samp{-mno-flat} (the default), the compiler emits save/restore
3294 instructions (except for leaf functions) and is the normal mode of operation.
3296 @item -mno-unaligned-doubles
3297 @itemx -munaligned-doubles
3298 Assume that doubles have 8 byte alignment. This is the default.
3300 With @samp{-munaligned-doubles}, GNU CC assumes that doubles have 8 byte
3301 alignment only if they are contained in another type, or if they have an
3302 absolute address. Otherwise, it assumes they have 4 byte alignment.
3303 Specifying this option avoids some rare compatibility problems with code
3304 generated by other compilers. It is not the default because it results
3305 in a performance loss, especially for floating point code.
3309 These two options select variations on the SPARC architecture.
3311 By default (unless specifically configured for the Fujitsu SPARClite),
3312 GCC generates code for the v7 variant of the SPARC architecture.
3314 @samp{-mv8} will give you SPARC v8 code. The only difference from v7
3315 code is that the compiler emits the integer multiply and integer
3316 divide instructions which exist in SPARC v8 but not in SPARC v7.
3318 @samp{-msparclite} will give you SPARClite code. This adds the integer
3319 multiply, integer divide step and scan (@code{ffs}) instructions which
3320 exist in SPARClite but not in SPARC v7.
3322 These options are deprecated and will be deleted in GNU CC 2.9.
3323 They have been replaced with @samp{-mcpu=xxx}.
3327 These two options select the processor for which the code is optimised.
3329 With @samp{-mcypress} (the default), the compiler optimizes code for the
3330 Cypress CY7C602 chip, as used in the SparcStation/SparcServer 3xx series.
3331 This is also appropriate for the older SparcStation 1, 2, IPX etc.
3333 With @samp{-msupersparc} the compiler optimizes code for the SuperSparc cpu, as
3334 used in the SparcStation 10, 1000 and 2000 series. This flag also enables use
3335 of the full SPARC v8 instruction set.
3337 These options are deprecated and will be deleted in GNU CC 2.9.
3338 They have been replaced with @samp{-mcpu=xxx}.
3340 @item -mcpu=@var{cpu_type}
3341 Set the instruction set, register set, and instruction scheduling parameters
3342 for machine type @var{cpu_type}. Supported values for @var{cpu_type} are
3343 @samp{v7}, @samp{cypress}, @samp{v8}, @samp{supersparc}, @samp{sparclite},
3344 @samp{f930}, @samp{f934}, @samp{sparclet}, @samp{tsc701}, @samp{v9}, and
3347 Default instruction scheduling parameters are used for values that select
3348 an architecture and not an implementation. These are @samp{v7}, @samp{v8},
3349 @samp{sparclite}, @samp{sparclet}, @samp{v9}.
3351 Here is a list of each supported architecture and their supported
3357 sparclite: f930, f934
3362 @item -mtune=@var{cpu_type}
3363 Set the instruction scheduling parameters for machine type
3364 @var{cpu_type}, but do not set the instruction set or register set that the
3365 option @samp{-mcpu=}@var{cpu_type} would.
3367 The same values for @samp{-mcpu=}@var{cpu_type} are used for
3368 @samp{-mtune=}@*@var{cpu_type}, though the only useful values are those that
3369 select a particular cpu implementation: @samp{cypress}, @samp{supersparc},
3370 @samp{f930}, @samp{f934}, @samp{tsc701}, @samp{ultrasparc}.
3372 @item -malign-loops=@var{num}
3373 Align loops to a 2 raised to a @var{num} byte boundary. If
3374 @samp{-malign-loops} is not specified, the default is 2.
3376 @item -malign-jumps=@var{num}
3377 Align instructions that are only jumped to to a 2 raised to a @var{num}
3378 byte boundary. If @samp{-malign-jumps} is not specified, the default is 2.
3380 @item -malign-functions=@var{num}
3381 Align the start of functions to a 2 raised to @var{num} byte boundary.
3382 If @samp{-malign-functions} is not specified, the default is 2 if compiling
3383 for 32 bit sparc, and 5 if compiling for 64 bit sparc.
3387 These @samp{-m} switches are supported in addition to the above
3388 on the SPARCLET processor.
3391 @item -mlittle-endian
3392 Generate code for a processor running in little-endian mode.
3395 Treat register @code{%g0} as a normal register.
3396 GCC will continue to clobber it as necessary but will not assume
3397 it always reads as 0.
3399 @item -mbroken-saverestore
3400 Generate code that does not use non-trivial forms of the @code{save} and
3401 @code{restore} instructions. Early versions of the SPARCLET processor do
3402 not correctly handle @code{save} and @code{restore} instructions used with
3403 arguments. They correctly handle them used without arguments. A @code{save}
3404 instruction used without arguments increments the current window pointer
3405 but does not allocate a new stack frame. It is assumed that the window
3406 overflow trap handler will properly handle this case as will interrupt
3410 These @samp{-m} switches are supported in addition to the above
3411 on SPARC V9 processors in 64 bit environments.
3414 @item -mlittle-endian
3415 Generate code for a processor running in little-endian mode.
3419 Generate code for a 32 bit or 64 bit environment.
3420 The 32 bit environment sets int, long and pointer to 32 bits.
3421 The 64 bit environment sets int to 32 bits and long and pointer
3424 @item -mcmodel=medlow
3425 Generate code for the Medium/Low code model: the program must be linked
3426 in the low 32 bits of the address space. Pointers are 64 bits.
3427 Programs can be statically or dynamically linked.
3429 @item -mcmodel=medmid
3430 Generate code for the Medium/Middle code model: the program must be linked
3431 in the low 44 bits of the address space, the text segment must be less than
3432 2G bytes, and data segment must be within 2G of the text segment.
3433 Pointers are 64 bits.
3435 @item -mcmodel=medany
3436 Generate code for the Medium/Anywhere code model: the program may be linked
3437 anywhere in the address space, the text segment must be less than
3438 2G bytes, and data segment must be within 2G of the text segment.
3439 Pointers are 64 bits.
3441 @item -mcmodel=embmedany
3442 Generate code for the Medium/Anywhere code model for embedded systems:
3443 assume a 32 bit text and a 32 bit data segment, both starting anywhere
3444 (determined at link time). Register %g4 points to the base of the
3445 data segment. Pointers still 64 bits.
3446 Programs are statically linked, PIC is not supported.
3449 @itemx -mno-stack-bias
3450 With @samp{-mstack-bias}, GNU CC assumes that the stack pointer, and
3451 frame pointer if present, are offset by -2047 which must be added back
3452 when making stack frame references.
3453 Otherwise, assume no such offset is present.
3456 @node Convex Options
3457 @subsection Convex Options
3458 @cindex Convex options
3460 These @samp{-m} options are defined for Convex:
3464 Generate output for C1. The code will run on any Convex machine.
3465 The preprocessor symbol @code{__convex__c1__} is defined.
3468 Generate output for C2. Uses instructions not available on C1.
3469 Scheduling and other optimizations are chosen for max performance on C2.
3470 The preprocessor symbol @code{__convex_c2__} is defined.
3473 Generate output for C32xx. Uses instructions not available on C1.
3474 Scheduling and other optimizations are chosen for max performance on C32.
3475 The preprocessor symbol @code{__convex_c32__} is defined.
3478 Generate output for C34xx. Uses instructions not available on C1.
3479 Scheduling and other optimizations are chosen for max performance on C34.
3480 The preprocessor symbol @code{__convex_c34__} is defined.
3483 Generate output for C38xx. Uses instructions not available on C1.
3484 Scheduling and other optimizations are chosen for max performance on C38.
3485 The preprocessor symbol @code{__convex_c38__} is defined.
3488 Generate code which puts an argument count in the word preceding each
3489 argument list. This is compatible with regular CC, and a few programs
3490 may need the argument count word. GDB and other source-level debuggers
3491 do not need it; this info is in the symbol table.
3494 Omit the argument count word. This is the default.
3496 @item -mvolatile-cache
3497 Allow volatile references to be cached. This is the default.
3499 @item -mvolatile-nocache
3500 Volatile references bypass the data cache, going all the way to memory.
3501 This is only needed for multi-processor code that does not use standard
3502 synchronization instructions. Making non-volatile references to volatile
3503 locations will not necessarily work.
3506 Type long is 32 bits, the same as type int. This is the default.
3509 Type long is 64 bits, the same as type long long. This option is useless,
3510 because no library support exists for it.
3513 @node AMD29K Options
3514 @subsection AMD29K Options
3515 @cindex AMD29K options
3517 These @samp{-m} options are defined for the AMD Am29000:
3522 @cindex DW bit (29k)
3523 Generate code that assumes the @code{DW} bit is set, i.e., that byte and
3524 halfword operations are directly supported by the hardware. This is the
3529 Generate code that assumes the @code{DW} bit is not set.
3533 @cindex byte writes (29k)
3534 Generate code that assumes the system supports byte and halfword write
3535 operations. This is the default.
3539 Generate code that assumes the systems does not support byte and
3540 halfword write operations. @samp{-mnbw} implies @samp{-mndw}.
3544 @cindex memory model (29k)
3545 Use a small memory model that assumes that all function addresses are
3546 either within a single 256 KB segment or at an absolute address of less
3547 than 256k. This allows the @code{call} instruction to be used instead
3548 of a @code{const}, @code{consth}, @code{calli} sequence.
3552 Use the normal memory model: Generate @code{call} instructions only when
3553 calling functions in the same file and @code{calli} instructions
3554 otherwise. This works if each file occupies less than 256 KB but allows
3555 the entire executable to be larger than 256 KB. This is the default.
3558 Always use @code{calli} instructions. Specify this option if you expect
3559 a single file to compile into more than 256 KB of code.
3563 @cindex processor selection (29k)
3564 Generate code for the Am29050.
3568 Generate code for the Am29000. This is the default.
3570 @item -mkernel-registers
3571 @kindex -mkernel-registers
3572 @cindex kernel and user registers (29k)
3573 Generate references to registers @code{gr64-gr95} instead of to
3574 registers @code{gr96-gr127}. This option can be used when compiling
3575 kernel code that wants a set of global registers disjoint from that used
3578 Note that when this option is used, register names in @samp{-f} flags
3579 must use the normal, user-mode, names.
3581 @item -muser-registers
3582 @kindex -muser-registers
3583 Use the normal set of global registers, @code{gr96-gr127}. This is the
3587 @itemx -mno-stack-check
3588 @kindex -mstack-check
3589 @cindex stack checks (29k)
3590 Insert (or do not insert) a call to @code{__msp_check} after each stack
3591 adjustment. This is often used for kernel code.
3594 @itemx -mno-storem-bug
3595 @kindex -mstorem-bug
3596 @cindex storem bug (29k)
3597 @samp{-mstorem-bug} handles 29k processors which cannot handle the
3598 separation of a mtsrim insn and a storem instruction (most 29000 chips
3599 to date, but not the 29050).
3601 @item -mno-reuse-arg-regs
3602 @itemx -mreuse-arg-regs
3603 @kindex -mreuse-arg-regs
3604 @samp{-mno-reuse-arg-regs} tells the compiler to only use incoming argument
3605 registers for copying out arguments. This helps detect calling a function
3606 with fewer arguments than it was declared with.
3608 @item -mno-impure-text
3609 @itemx -mimpure-text
3610 @kindex -mimpure-text
3611 @samp{-mimpure-text}, used in addition to @samp{-shared}, tells the compiler to
3612 not pass @samp{-assert pure-text} to the linker when linking a shared object.
3615 @kindex -msoft-float
3616 Generate output containing library calls for floating point.
3617 @strong{Warning:} the requisite libraries are not part of GNU CC.
3618 Normally the facilities of the machine's usual C compiler are used, but
3619 this can't be done directly in cross-compilation. You must make your
3620 own arrangements to provide suitable library functions for
3625 @subsection ARM Options
3628 These @samp{-m} options are defined for Advanced RISC Machines (ARM)
3633 @kindex -mapcs-frame
3634 Generate a stack frame that is compliant with the ARM Procedure Call
3635 Standard for all functions, even if this is not strictly necessary for
3636 correct execution of the code. Specifying @samp{-fomit-frame-pointer}
3637 with this option will cause the stack frames not to be generated for
3638 leaf functions. The default is @samp{-mno-apcs-frame}.
3642 This is a synonym for @samp{-mapcs-frame}.
3646 Generate code for a processor running with a 26-bit program counter,
3647 and conforming to the function calling standards for the APCS 26-bit
3648 option. This option replaces the @samp{-m2} and @samp{-m3} options
3649 of previous releases of the compiler.
3653 Generate code for a processor running with a 32-bit program counter,
3654 and conforming to the function calling standards for the APCS 32-bit
3655 option. This option replaces the @samp{-m6} option of previous releases
3658 @item -mapcs-stack-check
3659 @kindex -mapcs-stack-check
3660 @kindex -mno-apcs-stack-check
3661 Generate code to check the amount of stack space available upon entry to
3662 every function (that actually uses some stack space). If there is
3663 insufficient space available then either the function
3664 @samp{__rt_stkovf_split_small} or @samp{__rt_stkovf_split_big} will be
3665 called, depending upon the amount of stack space required. The run time
3666 system is required to provide these functions. The default is
3667 @samp{-mno-apcs-stack-check}, since this produces smaller code.
3670 @kindex -mapcs-float
3671 @kindex -mno-apcs-float
3672 Pass floating point arguments using the float point registers. This is
3673 one of the variants of the APCS. This option is reccommended if the
3674 target hardware has a floating point unit or if a lot of floating point
3675 arithmetic is going to be performed by the code. The default is
3676 @samp{-mno-apcs-float}, since integer only code is slightly increased in
3677 size if @samp{-mapcs-float} is used.
3679 @item -mapcs-reentrant
3680 @kindex -mapcs-reentrant
3681 @kindex -mno-apcs-reentrant
3682 Generate reentrant, position independent code. This is the equivalent
3683 to specifying the @samp{-fpic} option. The default is
3684 @samp{-mno-apcs-reentrant}.
3686 @item -mthumb-interwork
3687 @kindex -mthumb-interwork
3688 @kindex -mno-thumb-interwork
3689 Generate code which supports calling between the ARM and THUMB
3690 instruction sets. Without this option the two instruction sets cannot
3691 be reliably used inside one program. The default is
3692 @samp{-mno-thumb-interwork}, since slightly larger code is generated
3693 when @samp{-mthumb-interwork} is specified.
3695 @item -mno-sched-prolog
3696 @kindex -mno-sched-prolog
3697 @kindex -msched-prolog
3698 Prevent the reordering of instructions in the function prolog, or the
3699 merging of those instruction with the instructions in the function's
3700 body. This means that all functions will start with a recognisable set
3701 of instructions (or in fact one of a chioce from a small set of
3702 different function prologues), and this information can be used to
3703 locate the start if functions inside an executable piece of code. The
3704 default is @samp{-msched-prolog}.
3707 Generate output containing floating point instructions. This is the
3711 Generate output containing library calls for floating point.
3712 @strong{Warning:} the requisite libraries are not available for all ARM
3713 targets. Normally the facilities of the machine's usual C compiler are
3714 used, but this cannot be done directly in cross-compilation. You must make
3715 your own arrangements to provide suitable library functions for
3718 @samp{-msoft-float} changes the calling convention in the output file;
3719 therefore, it is only useful if you compile @emph{all} of a program with
3720 this option. In particular, you need to compile @file{libgcc.a}, the
3721 library that comes with GNU CC, with @samp{-msoft-float} in order for
3724 @item -mlittle-endian
3725 Generate code for a processor running in little-endian mode. This is
3726 the default for all standard configurations.
3729 Generate code for a processor running in big-endian mode; the default is
3730 to compile code for a little-endian processor.
3732 @item -mwords-little-endian
3733 This option only applies when generating code for big-endian processors.
3734 Generate code for a little-endian word order but a big-endian byte
3735 order. That is, a byte order of the form @samp{32107654}. Note: this
3736 option should only be used if you require compatibility with code for
3737 big-endian ARM processors generated by versions of the compiler prior to
3740 @item -mshort-load-bytes
3741 @kindex -mshort-load-bytes
3742 Do not try to load half-words (eg @samp{short}s) by loading a word from
3743 an unaligned address. For some targets the MMU is configured to trap
3744 unaligned loads; use this option to generate code that is safe in these
3747 @item -mno-short-load-bytes
3748 @kindex -mno-short-load-bytes
3749 Use unaligned word loads to load half-words (eg @samp{short}s). This
3750 option produces more efficient code, but the MMU is sometimes configured
3751 to trap these instructions.
3753 @item -mshort-load-words
3754 @kindex -mshort-load-words
3755 This is a synonym for the @samp{-mno-short-load-bytes}.
3757 @item -mno-short-load-words
3758 @kindex -mno-short-load-words
3759 This is a synonym for the @samp{-mshort-load-bytes}.
3763 This option only applies to RISC iX. Emulate the native BSD-mode
3764 compiler. This is the default if @samp{-ansi} is not specified.
3768 This option only applies to RISC iX. Emulate the native X/Open-mode
3771 @item -mno-symrename
3772 @kindex -mno-symrename
3773 This option only applies to RISC iX. Do not run the assembler
3774 post-processor, @samp{symrename}, after code has been assembled.
3775 Normally it is necessary to modify some of the standard symbols in
3776 preparation for linking with the RISC iX C library; this option
3777 suppresses this pass. The post-processor is never run when the
3778 compiler is built for cross-compilation.
3782 This specifies the name of the target ARM processor. GCC uses this name
3783 to determine what kind of instructions it can use when generating
3784 assembly code. Permissable names are: arm2, arm250, arm3, arm6, arm60,
3785 arm600, arm610, arm620, arm7, arm7m, arm7d, arm7dm, arm7di, arm7dmi,
3786 arm70, arm700, arm700i, arm710, arm710c, arm7100, arm7500, arm7500fe,
3787 arm7tdmi, arm8, strongarm, strongarm110
3791 This specifies the name of the target ARM architecture. GCC uses this
3792 name to determine what kind of instructions it can use when generating
3793 assembly code. This option can be used in conjunction with or instead
3794 of the @samp{-mcpu=} option. Permissable names are: armv2, armv2a,
3795 armv3, armv3m, armv4, armv4t
3797 @item -mfpe=<number>
3799 This specifes the version of the floating point emulation available on
3800 the target. Permissable values are 2 and 3.
3802 @item -mstructure-size-boundary=<n>
3803 @kindex -mstructure-size-boundary
3804 The size of all structures and unions will be rounded up to a multiple
3805 of the number of bits set by this option. Permissable values are 8 and
3806 32. The default value varies for different toolchains. For the COFF
3807 targeted toolchain the default value is 8. Specifying the larger number
3808 can produced faster, more efficient code, but can also increase the size
3809 of the program. The two values are potentially incompatible. Code
3810 compiled with one value cannot necessarily expect to work with code or
3811 libraries compiled with the other value, if they exchange information
3812 using structures or unions. Programmers are encouraged to use the 32
3813 value as future versions of the toolchain may default to this value.
3818 @subsection Thumb Options
3819 @cindex Thumb Options
3823 @item -mthumb-interwork
3824 @kindex -mthumb-interwork
3825 @kindex -mno-thumb-interwork
3826 Generate code which supports calling between the THUMB and ARM
3827 instruction sets. Without this option the two instruction sets cannot
3828 be reliably used inside one program. The default is
3829 @samp{-mno-thumb-interwork}, since slightly smaller code is generated
3833 @kindex -mtpcs-frame
3834 @kindex -mno-tpcs-frame
3835 Generate a stack frame that is compliant with the Thumb Procedure Call
3836 Standard for all non-leaf functions. (A leaf function is one that does
3837 not call any other functions). The default is @samp{-mno-apcs-frame}.
3839 @item -mtpcs-leaf-frame
3840 @kindex -mtpcs-leaf-frame
3841 @kindex -mno-tpcs-leaf-frame
3842 Generate a stack frame that is compliant with the Thumb Procedure Call
3843 Standard for all leaf functions. (A leaf function is one that does
3844 not call any other functions). The default is @samp{-mno-apcs-leaf-frame}.
3846 @item -mlittle-endian
3847 @kindex -mlittle-endian
3848 Generate code for a processor running in little-endian mode. This is
3849 the default for all standard configurations.
3852 @kindex -mbig-endian
3853 Generate code for a processor running in big-endian mode.
3855 @item -mstructure-size-boundary=<n>
3856 @kindex -mstructure-size-boundary
3857 The size of all structures and unions will be rounded up to a multiple
3858 of the number of bits set by this option. Permissable values are 8 and
3859 32. The default value varies for different toolchains. For the COFF
3860 targeted toolchain the default value is 8. Specifying the larger number
3861 can produced faster, more efficient code, but can also increase the size
3862 of the program. The two values are potentially incompatible. Code
3863 compiled with one value cannot necessarily expect to work with code or
3864 libraries compiled with the other value, if they exchange information
3865 using structures or unions. Programmers are encouraged to use the 32
3866 value as future versions of the toolchain may default to this value.
3870 @node MN10200 Options
3871 @subsection MN10200 Options
3872 @cindex MN10200 options
3873 These @samp{-m} options are defined for Matsushita MN10200 architectures:
3877 Indicate to the linker that it should perform a relaxation optimization pass
3878 to shorten branches, calls and absolute memory addresses. This option only
3879 has an effect when used on the command line for the final link step.
3881 This option makes symbolic debugging impossible.
3884 @node MN10300 Options
3885 @subsection MN10300 Options
3886 @cindex MN10300 options
3887 These @samp{-m} options are defined for Matsushita MN10300 architectures:
3891 Generate code to avoid bugs in the multiply instructions for the MN10300
3892 processors. This is the default.
3895 Do not generate code to avoid bugs in the multiply instructions for the
3899 Indicate to the linker that it should perform a relaxation optimization pass
3900 to shorten branches, calls and absolute memory addresses. This option only
3901 has an effect when used on the command line for the final link step.
3903 This option makes symbolic debugging impossible.
3907 @node M32R/D Options
3908 @subsection M32R/D Options
3909 @cindex M32R/D options
3911 These @samp{-m} options are defined for Mitsubishi M32R/D architectures:
3914 @item -mcode-model=small
3915 Assume all objects live in the lower 16MB of memory (so that their addresses
3916 can be loaded with the @code{ld24} instruction), and assume all subroutines
3917 are reachable with the @code{bl} instruction.
3918 This is the default.
3920 The addressability of a particular object can be set with the
3921 @code{model} attribute.
3923 @item -mcode-model=medium
3924 Assume objects may be anywhere in the 32 bit address space (the compiler
3925 will generate @code{seth/add3} instructions to load their addresses), and
3926 assume all subroutines are reachable with the @code{bl} instruction.
3928 @item -mcode-model=large
3929 Assume objects may be anywhere in the 32 bit address space (the compiler
3930 will generate @code{seth/add3} instructions to load their addresses), and
3931 assume subroutines may not be reachable with the @code{bl} instruction
3932 (the compiler will generate the much slower @code{seth/add3/jl}
3933 instruction sequence).
3936 Disable use of the small data area. Variables will be put into
3937 one of @samp{.data}, @samp{bss}, or @samp{.rodata} (unless the
3938 @code{section} attribute has been specified).
3939 This is the default.
3941 The small data area consists of sections @samp{.sdata} and @samp{.sbss}.
3942 Objects may be explicitly put in the small data area with the
3943 @code{section} attribute using one of these sections.
3946 Put small global and static data in the small data area, but do not
3947 generate special code to reference them.
3950 Put small global and static data in the small data area, and generate
3951 special instructions to reference them.
3954 @cindex smaller data references
3955 Put global and static objects less than or equal to @var{num} bytes
3956 into the small data or bss sections instead of the normal data or bss
3957 sections. The default value of @var{num} is 8.
3958 The @samp{-msdata} option must be set to one of @samp{sdata} or @samp{use}
3959 for this option to have any effect.
3961 All modules should be compiled with the same @samp{-G @var{num}} value.
3962 Compiling with different values of @var{num} may or may not work; if it
3963 doesn't the linker will give an error message - incorrect code will not be
3969 @subsection M88K Options
3970 @cindex M88k options
3972 These @samp{-m} options are defined for Motorola 88k architectures:
3977 Generate code that works well on both the m88100 and the
3982 Generate code that works best for the m88100, but that also
3987 Generate code that works best for the m88110, and may not run
3992 Obsolete option to be removed from the next revision.
3995 @item -midentify-revision
3996 @kindex -midentify-revision
3998 @cindex identifying source, compiler (88k)
3999 Include an @code{ident} directive in the assembler output recording the
4000 source file name, compiler name and version, timestamp, and compilation
4003 @item -mno-underscores
4004 @kindex -mno-underscores
4005 @cindex underscores, avoiding (88k)
4006 In assembler output, emit symbol names without adding an underscore
4007 character at the beginning of each name. The default is to use an
4008 underscore as prefix on each name.
4010 @item -mocs-debug-info
4011 @itemx -mno-ocs-debug-info
4012 @kindex -mocs-debug-info
4013 @kindex -mno-ocs-debug-info
4015 @cindex debugging, 88k OCS
4016 Include (or omit) additional debugging information (about registers used
4017 in each stack frame) as specified in the 88open Object Compatibility
4018 Standard, ``OCS''. This extra information allows debugging of code that
4019 has had the frame pointer eliminated. The default for DG/UX, SVr4, and
4020 Delta 88 SVr3.2 is to include this information; other 88k configurations
4021 omit this information by default.
4023 @item -mocs-frame-position
4024 @kindex -mocs-frame-position
4025 @cindex register positions in frame (88k)
4026 When emitting COFF debugging information for automatic variables and
4027 parameters stored on the stack, use the offset from the canonical frame
4028 address, which is the stack pointer (register 31) on entry to the
4029 function. The DG/UX, SVr4, Delta88 SVr3.2, and BCS configurations use
4030 @samp{-mocs-frame-position}; other 88k configurations have the default
4031 @samp{-mno-ocs-frame-position}.
4033 @item -mno-ocs-frame-position
4034 @kindex -mno-ocs-frame-position
4035 @cindex register positions in frame (88k)
4036 When emitting COFF debugging information for automatic variables and
4037 parameters stored on the stack, use the offset from the frame pointer
4038 register (register 30). When this option is in effect, the frame
4039 pointer is not eliminated when debugging information is selected by the
4042 @item -moptimize-arg-area
4043 @itemx -mno-optimize-arg-area
4044 @kindex -moptimize-arg-area
4045 @kindex -mno-optimize-arg-area
4046 @cindex arguments in frame (88k)
4047 Control how function arguments are stored in stack frames.
4048 @samp{-moptimize-arg-area} saves space by optimizing them, but this
4049 conflicts with the 88open specifications. The opposite alternative,
4050 @samp{-mno-optimize-arg-area}, agrees with 88open standards. By default
4051 GNU CC does not optimize the argument area.
4053 @item -mshort-data-@var{num}
4054 @kindex -mshort-data-@var{num}
4055 @cindex smaller data references (88k)
4056 @cindex r0-relative references (88k)
4057 Generate smaller data references by making them relative to @code{r0},
4058 which allows loading a value using a single instruction (rather than the
4059 usual two). You control which data references are affected by
4060 specifying @var{num} with this option. For example, if you specify
4061 @samp{-mshort-data-512}, then the data references affected are those
4062 involving displacements of less than 512 bytes.
4063 @samp{-mshort-data-@var{num}} is not effective for @var{num} greater
4066 @item -mserialize-volatile
4067 @kindex -mserialize-volatile
4068 @itemx -mno-serialize-volatile
4069 @kindex -mno-serialize-volatile
4070 @cindex sequential consistency on 88k
4071 Do, or don't, generate code to guarantee sequential consistency
4072 of volatile memory references. By default, consistency is
4075 The order of memory references made by the MC88110 processor does
4076 not always match the order of the instructions requesting those
4077 references. In particular, a load instruction may execute before
4078 a preceding store instruction. Such reordering violates
4079 sequential consistency of volatile memory references, when there
4080 are multiple processors. When consistency must be guaranteed,
4081 GNU C generates special instructions, as needed, to force
4082 execution in the proper order.
4084 The MC88100 processor does not reorder memory references and so
4085 always provides sequential consistency. However, by default, GNU
4086 C generates the special instructions to guarantee consistency
4087 even when you use @samp{-m88100}, so that the code may be run on an
4088 MC88110 processor. If you intend to run your code only on the
4089 MC88100 processor, you may use @samp{-mno-serialize-volatile}.
4091 The extra code generated to guarantee consistency may affect the
4092 performance of your application. If you know that you can safely
4093 forgo this guarantee, you may use @samp{-mno-serialize-volatile}.
4099 @cindex assembler syntax, 88k
4101 Turn on (@samp{-msvr4}) or off (@samp{-msvr3}) compiler extensions
4102 related to System V release 4 (SVr4). This controls the following:
4106 Which variant of the assembler syntax to emit.
4108 @samp{-msvr4} makes the C preprocessor recognize @samp{#pragma weak}
4109 that is used on System V release 4.
4111 @samp{-msvr4} makes GNU CC issue additional declaration directives used in
4115 @samp{-msvr4} is the default for the m88k-motorola-sysv4 and
4116 m88k-dg-dgux m88k configurations. @samp{-msvr3} is the default for all
4117 other m88k configurations.
4119 @item -mversion-03.00
4120 @kindex -mversion-03.00
4121 This option is obsolete, and is ignored.
4122 @c ??? which asm syntax better for GAS? option there too?
4124 @item -mno-check-zero-division
4125 @itemx -mcheck-zero-division
4126 @kindex -mno-check-zero-division
4127 @kindex -mcheck-zero-division
4128 @cindex zero division on 88k
4129 Do, or don't, generate code to guarantee that integer division by
4130 zero will be detected. By default, detection is guaranteed.
4132 Some models of the MC88100 processor fail to trap upon integer
4133 division by zero under certain conditions. By default, when
4134 compiling code that might be run on such a processor, GNU C
4135 generates code that explicitly checks for zero-valued divisors
4136 and traps with exception number 503 when one is detected. Use of
4137 mno-check-zero-division suppresses such checking for code
4138 generated to run on an MC88100 processor.
4140 GNU C assumes that the MC88110 processor correctly detects all
4141 instances of integer division by zero. When @samp{-m88110} is
4142 specified, both @samp{-mcheck-zero-division} and
4143 @samp{-mno-check-zero-division} are ignored, and no explicit checks for
4144 zero-valued divisors are generated.
4146 @item -muse-div-instruction
4147 @kindex -muse-div-instruction
4148 @cindex divide instruction, 88k
4149 Use the div instruction for signed integer division on the
4150 MC88100 processor. By default, the div instruction is not used.
4152 On the MC88100 processor the signed integer division instruction
4153 div) traps to the operating system on a negative operand. The
4154 operating system transparently completes the operation, but at a
4155 large cost in execution time. By default, when compiling code
4156 that might be run on an MC88100 processor, GNU C emulates signed
4157 integer division using the unsigned integer division instruction
4158 divu), thereby avoiding the large penalty of a trap to the
4159 operating system. Such emulation has its own, smaller, execution
4160 cost in both time and space. To the extent that your code's
4161 important signed integer division operations are performed on two
4162 nonnegative operands, it may be desirable to use the div
4163 instruction directly.
4165 On the MC88110 processor the div instruction (also known as the
4166 divs instruction) processes negative operands without trapping to
4167 the operating system. When @samp{-m88110} is specified,
4168 @samp{-muse-div-instruction} is ignored, and the div instruction is used
4169 for signed integer division.
4171 Note that the result of dividing INT_MIN by -1 is undefined. In
4172 particular, the behavior of such a division with and without
4173 @samp{-muse-div-instruction} may differ.
4175 @item -mtrap-large-shift
4176 @itemx -mhandle-large-shift
4177 @kindex -mtrap-large-shift
4178 @kindex -mhandle-large-shift
4179 @cindex bit shift overflow (88k)
4180 @cindex large bit shifts (88k)
4181 Include code to detect bit-shifts of more than 31 bits; respectively,
4182 trap such shifts or emit code to handle them properly. By default GNU CC
4183 makes no special provision for large bit shifts.
4185 @item -mwarn-passed-structs
4186 @kindex -mwarn-passed-structs
4187 @cindex structure passing (88k)
4188 Warn when a function passes a struct as an argument or result.
4189 Structure-passing conventions have changed during the evolution of the C
4190 language, and are often the source of portability problems. By default,
4191 GNU CC issues no such warning.
4194 @node RS/6000 and PowerPC Options
4195 @subsection IBM RS/6000 and PowerPC Options
4196 @cindex RS/6000 and PowerPC Options
4197 @cindex IBM RS/6000 and PowerPC Options
4199 These @samp{-m} options are defined for the IBM RS/6000 and PowerPC:
4207 @itemx -mpowerpc-gpopt
4208 @itemx -mno-powerpc-gpopt
4209 @itemx -mpowerpc-gfxopt
4210 @itemx -mno-powerpc-gfxopt
4212 @itemx -mno-powerpc64
4216 @kindex -mpowerpc-gpopt
4217 @kindex -mpowerpc-gfxopt
4219 GNU CC supports two related instruction set architectures for the
4220 RS/6000 and PowerPC. The @dfn{POWER} instruction set are those
4221 instructions supported by the @samp{rios} chip set used in the original
4222 RS/6000 systems and the @dfn{PowerPC} instruction set is the
4223 architecture of the Motorola MPC5xx, MPC6xx, MPC8xx microprocessors, and
4224 the IBM 4xx microprocessors.
4226 Neither architecture is a subset of the other. However there is a
4227 large common subset of instructions supported by both. An MQ
4228 register is included in processors supporting the POWER architecture.
4230 You use these options to specify which instructions are available on the
4231 processor you are using. The default value of these options is
4232 determined when configuring GNU CC. Specifying the
4233 @samp{-mcpu=@var{cpu_type}} overrides the specification of these
4234 options. We recommend you use the @samp{-mcpu=@var{cpu_type}} option
4235 rather than the options listed above.
4237 The @samp{-mpower} option allows GNU CC to generate instructions that
4238 are found only in the POWER architecture and to use the MQ register.
4239 Specifying @samp{-mpower2} implies @samp{-power} and also allows GNU CC
4240 to generate instructions that are present in the POWER2 architecture but
4241 not the original POWER architecture.
4243 The @samp{-mpowerpc} option allows GNU CC to generate instructions that
4244 are found only in the 32-bit subset of the PowerPC architecture.
4245 Specifying @samp{-mpowerpc-gpopt} implies @samp{-mpowerpc} and also allows
4246 GNU CC to use the optional PowerPC architecture instructions in the
4247 General Purpose group, including floating-point square root. Specifying
4248 @samp{-mpowerpc-gfxopt} implies @samp{-mpowerpc} and also allows GNU CC to
4249 use the optional PowerPC architecture instructions in the Graphics
4250 group, including floating-point select.
4252 The @samp{-mpowerpc64} option allows GNU CC to generate the additional
4253 64-bit instructions that are found in the full PowerPC64 architecture
4254 and to treat GPRs as 64-bit, doubleword quantities. GNU CC defaults to
4255 @samp{-mno-powerpc64}.
4257 If you specify both @samp{-mno-power} and @samp{-mno-powerpc}, GNU CC
4258 will use only the instructions in the common subset of both
4259 architectures plus some special AIX common-mode calls, and will not use
4260 the MQ register. Specifying both @samp{-mpower} and @samp{-mpowerpc}
4261 permits GNU CC to use any instruction from either architecture and to
4262 allow use of the MQ register; specify this for the Motorola MPC601.
4264 @item -mnew-mnemonics
4265 @itemx -mold-mnemonics
4266 @kindex -mnew-mnemonics
4267 @kindex -mold-mnemonics
4268 Select which mnemonics to use in the generated assembler code.
4269 @samp{-mnew-mnemonics} requests output that uses the assembler mnemonics
4270 defined for the PowerPC architecture, while @samp{-mold-mnemonics}
4271 requests the assembler mnemonics defined for the POWER architecture.
4272 Instructions defined in only one architecture have only one mnemonic;
4273 GNU CC uses that mnemonic irrespective of which of these options is
4276 GNU CC defaults to the mnemonics appropriate for the architecture in
4277 use. Specifying @samp{-mcpu=@var{cpu_type}} sometimes overrides the
4278 value of these option. Unless you are building a cross-compiler, you
4279 should normally not specify either @samp{-mnew-mnemonics} or
4280 @samp{-mold-mnemonics}, but should instead accept the default.
4282 @item -mcpu=@var{cpu_type}
4284 Set architecture type, register usage, choice of mnemonics, and
4285 instruction scheduling parameters for machine type @var{cpu_type}.
4286 Supported values for @var{cpu_type} are @samp{rs6000}, @samp{rios1},
4287 @samp{rios2}, @samp{rsc}, @samp{601}, @samp{602}, @samp{603},
4288 @samp{603e}, @samp{604}, @samp{604e}, @samp{620}, @samp{power},
4289 @samp{power2}, @samp{powerpc}, @samp{403}, @samp{505}, @samp{801},
4290 @samp{821}, @samp{823}, and @samp{860} and @samp{common}.
4291 @samp{-mcpu=power}, @samp{-mcpu=power2}, and @samp{-mcpu=powerpc}
4292 specify generic POWER, POWER2 and pure PowerPC (i.e., not MPC601)
4293 architecture machine types, with an appropriate, generic processor model
4294 assumed for scheduling purposes.@refill
4296 @c overfull hbox here --bob 22 jul96
4297 @c original text between ignore ... end ignore
4299 Specifying any of the @samp{-mcpu=rios1}, @samp{-mcpu=rios2},
4300 @samp{-mcpu=rsc}, @samp{-mcpu=power}, or @samp{-mcpu=power2} options
4301 enables the @samp{-mpower} option and disables the @samp{-mpowerpc}
4302 option; @samp{-mcpu=601} enables both the @samp{-mpower} and
4303 @samp{-mpowerpc} options; all of @samp{-mcpu=602}, @samp{-mcpu=603},
4304 @samp{-mcpu=603e}, @samp{-mcpu=604}, @samp{-mcpu=604e},
4305 @samp{-mcpu=620}, @samp{-mcpu=403}, @samp{-mcpu=505}, @samp{-mcpu=801},
4306 @samp{-mcpu=821}, @samp{-mcpu=823}, @samp{-mcpu=860} and
4307 @samp{-mcpu=powerpc} enable the @samp{-mpowerpc} option and disable the
4308 @samp{-mpower} option; @samp{-mcpu=common} disables both the
4309 @samp{-mpower} and @samp{-mpowerpc} options.@refill
4311 @c changed paragraph
4312 Specifying any of the following options:
4313 @samp{-mcpu=rios1}, @samp{-mcpu=rios2}, @samp{-mcpu=rsc},
4314 @samp{-mcpu=power}, or @samp{-mcpu=power2}
4315 enables the @samp{-mpower} option and disables the @samp{-mpowerpc} option;
4316 @samp{-mcpu=601} enables both the @samp{-mpower} and @samp{-mpowerpc} options.
4317 All of @samp{-mcpu=602}, @samp{-mcpu=603}, @samp{-mcpu=603e},
4318 @samp{-mcpu=604}, @samp{-mcpu=620},
4319 enable the @samp{-mpowerpc} option and disable the @samp{-mpower} option.
4320 Exactly similarly, all of @samp{-mcpu=403},
4321 @samp{-mcpu=505}, @samp{-mcpu=821}, @samp{-mcpu=860} and @samp{-mcpu=powerpc}
4322 enable the @samp{-mpowerpc} option and disable the @samp{-mpower} option.
4323 @samp{-mcpu=common} disables both the
4324 @samp{-mpower} and @samp{-mpowerpc} options.@refill
4325 @c end changes to prevent overfull hboxes
4327 AIX versions 4 or greater selects @samp{-mcpu=common} by default, so
4328 that code will operate on all members of the RS/6000 and PowerPC
4329 families. In that case, GNU CC will use only the instructions in the
4330 common subset of both architectures plus some special AIX common-mode
4331 calls, and will not use the MQ register. GNU CC assumes a generic
4332 processor model for scheduling purposes.
4334 Specifying any of the options @samp{-mcpu=rios1}, @samp{-mcpu=rios2},
4335 @samp{-mcpu=rsc}, @samp{-mcpu=power}, or @samp{-mcpu=power2} also
4336 disables the @samp{new-mnemonics} option. Specifying @samp{-mcpu=601},
4337 @samp{-mcpu=602}, @samp{-mcpu=603}, @samp{-mcpu=603e}, @samp{-mcpu=604},
4338 @samp{620}, @samp{403}, or @samp{-mcpu=powerpc} also enables the
4339 @samp{new-mnemonics} option.@refill
4341 Specifying @samp{-mcpu=403}, @samp{-mcpu=821}, or @samp{-mcpu=860} also
4342 enables the @samp{-msoft-float} option.
4344 @item -mtune=@var{cpu_type}
4345 Set the instruction scheduling parameters for machine type
4346 @var{cpu_type}, but do not set the architecture type, register usage,
4347 choice of mnemonics like @samp{-mcpu=}@var{cpu_type} would. The same
4348 values for @var{cpu_type} are used for @samp{-mtune=}@var{cpu_type} as
4349 for @samp{-mcpu=}@var{cpu_type}. The @samp{-mtune=}@var{cpu_type}
4350 option overrides the @samp{-mcpu=}@var{cpu_type} option in terms of
4351 instruction scheduling parameters.
4354 @itemx -mno-fp-in-toc
4355 @itemx -mno-sum-in-toc
4356 @itemx -mminimal-toc
4357 @kindex -mminimal-toc
4358 Modify generation of the TOC (Table Of Contents), which is created for
4359 every executable file. The @samp{-mfull-toc} option is selected by
4360 default. In that case, GNU CC will allocate at least one TOC entry for
4361 each unique non-automatic variable reference in your program. GNU CC
4362 will also place floating-point constants in the TOC. However, only
4363 16,384 entries are available in the TOC.
4365 If you receive a linker error message that saying you have overflowed
4366 the available TOC space, you can reduce the amount of TOC space used
4367 with the @samp{-mno-fp-in-toc} and @samp{-mno-sum-in-toc} options.
4368 @samp{-mno-fp-in-toc} prevents GNU CC from putting floating-point
4369 constants in the TOC and @samp{-mno-sum-in-toc} forces GNU CC to
4370 generate code to calculate the sum of an address and a constant at
4371 run-time instead of putting that sum into the TOC. You may specify one
4372 or both of these options. Each causes GNU CC to produce very slightly
4373 slower and larger code at the expense of conserving TOC space.
4375 If you still run out of space in the TOC even when you specify both of
4376 these options, specify @samp{-mminimal-toc} instead. This option causes
4377 GNU CC to make only one TOC entry for every file. When you specify this
4378 option, GNU CC will produce code that is slower and larger but which
4379 uses extremely little TOC space. You may wish to use this option
4380 only on files that contain less frequently executed code. @refill
4386 Enable AIX 64-bit ABI and calling convention: 64-bit pointers, 64-bit
4387 @code{long} type, and the infrastructure needed to support them.
4388 Specifying @samp{-maix64} implies @samp{-mpowerpc64} and
4389 @samp{-mpowerpc}, while @samp{-maix32} disables the 64-bit ABI and
4390 implies @samp{-mno-powerpc64}. GNU CC defaults to @samp{-maix32}.
4395 On AIX, pass floating-point arguments to prototyped functions beyond the
4396 register save area (RSA) on the stack in addition to argument FPRs. The
4397 AIX calling convention was extended but not initially documented to
4398 handle an obscure K&R C case of calling a function that takes the
4399 address of its arguments with fewer arguments than declared. AIX XL
4400 compilers access floating point arguments which do not fit in the
4401 RSA from the stack when a subroutine is compiled without
4402 optimization. Because always storing floating-point arguments on the
4403 stack is inefficient and rarely needed, this option is not enabled by
4404 default and only is necessary when calling subroutines compiled by AIX
4405 XL compilers without optimization.
4409 Support @dfn{AIX Threads}. Link an application written to use
4410 @dfn{pthreads} with special libraries and startup code to enable the
4415 Support @dfn{IBM RS/6000 SP} @dfn{Parallel Environment} (PE). Link an
4416 application written to use message passing with special startup code to
4417 enable the application to run. The system must have PE installed in the
4418 standard location (@file{/usr/lpp/ppe.poe/}), or the @file{specs} file
4419 must be overridden with the @samp{-specs=} option to specify the
4420 appropriate directory location. The Parallel Environment does not
4421 support threads, so the @samp{-mpe} option and the @samp{-mthreads}
4422 option are incompatible.
4426 @kindex -msoft-float
4427 Generate code that does not use (uses) the floating-point register set.
4428 Software floating point emulation is provided if you use the
4429 @samp{-msoft-float} option, and pass the option to GNU CC when linking.
4432 @itemx -mno-multiple
4433 Generate code that uses (does not use) the load multiple word
4434 instructions and the store multiple word instructions. These
4435 instructions are generated by default on POWER systems, and not
4436 generated on PowerPC systems. Do not use @samp{-mmultiple} on little
4437 endian PowerPC systems, since those instructions do not work when the
4438 processor is in little endian mode.
4443 Generate code that uses (does not use) the load string instructions and the
4444 store string word instructions to save multiple registers and do small block
4445 moves. These instructions are generated by default on POWER systems, and not
4446 generated on PowerPC systems. Do not use @samp{-mstring} on little endian
4447 PowerPC systems, since those instructions do not work when the processor is in
4453 Generate code that uses (does not use) the load or store instructions
4454 that update the base register to the address of the calculated memory
4455 location. These instructions are generated by default. If you use
4456 @samp{-mno-update}, there is a small window between the time that the
4457 stack pointer is updated and the address of the previous frame is
4458 stored, which means code that walks the stack frame across interrupts or
4459 signals may get corrupted data.
4462 @itemx -mno-fused-madd
4463 @kindex -mfused-madd
4464 Generate code that uses (does not use) the floating point multiply and
4465 accumulate instructions. These instructions are generated by default if
4466 hardware floating is used.
4468 @item -mno-bit-align
4471 On System V.4 and embedded PowerPC systems do not (do) force structures
4472 and unions that contain bit fields to be aligned to the base type of the
4475 For example, by default a structure containing nothing but 8
4476 @code{unsigned} bitfields of length 1 would be aligned to a 4 byte
4477 boundary and have a size of 4 bytes. By using @samp{-mno-bit-align},
4478 the structure would be aligned to a 1 byte boundary and be one byte in
4481 @item -mno-strict-align
4482 @itemx -mstrict-align
4483 @kindex -mstrict-align
4484 On System V.4 and embedded PowerPC systems do not (do) assume that
4485 unaligned memory references will be handled by the system.
4488 @itemx -mno-relocatable
4489 @kindex -mrelocatable
4490 On embedded PowerPC systems generate code that allows (does not allow)
4491 the program to be relocated to a different address at runtime. If you
4492 use @samp{-mrelocatable} on any module, all objects linked together must
4493 be compiled with @samp{-mrelocatable} or @samp{-mrelocatable-lib}.
4495 @item -mrelocatable-lib
4496 @itemx -mno-relocatable-lib
4497 On embedded PowerPC systems generate code that allows (does not allow)
4498 the program to be relocated to a different address at runtime. Modules
4499 compiled with @samp{-mrelocatable-lib} can be linked with either modules
4500 compiled without @samp{-mrelocatable} and @samp{-mrelocatable-lib} or
4501 with modules compiled with the @samp{-mrelocatable} options.
4505 On System V.4 and embedded PowerPC systems do not (do) assume that
4506 register 2 contains a pointer to a global area pointing to the addresses
4507 used in the program.
4510 @itemx -mlittle-endian
4511 On System V.4 and embedded PowerPC systems compile code for the
4512 processor in little endian mode. The @samp{-mlittle-endian} option is
4513 the same as @samp{-mlittle}.
4517 On System V.4 and embedded PowerPC systems compile code for the
4518 processor in big endian mode. The @samp{-mbig-endian} option is
4519 the same as @samp{-mbig}.
4522 On System V.4 and embedded PowerPC systems compile code using calling
4523 conventions that adheres to the March 1995 draft of the System V
4524 Application Binary Interface, PowerPC processor supplement. This is the
4525 default unless you configured GCC using @samp{powerpc-*-eabiaix}.
4527 @item -mcall-sysv-eabi
4528 Specify both @samp{-mcall-sysv} and @samp{-meabi} options.
4530 @item -mcall-sysv-noeabi
4531 Specify both @samp{-mcall-sysv} and @samp{-mno-eabi} options.
4534 On System V.4 and embedded PowerPC systems compile code using calling
4535 conventions that are similar to those used on AIX. This is the
4536 default if you configured GCC using @samp{powerpc-*-eabiaix}.
4538 @item -mcall-solaris
4539 On System V.4 and embedded PowerPC systems compile code for the Solaris
4543 On System V.4 and embedded PowerPC systems compile code for the
4544 Linux-based GNU system.
4547 @itemx -mno-prototype
4548 On System V.4 and embedded PowerPC systems assume that all calls to
4549 variable argument functions are properly prototyped. Otherwise, the
4550 compiler must insert an instruction before every non prototyped call to
4551 set or clear bit 6 of the condition code register (@var{CR}) to
4552 indicate whether floating point values were passed in the floating point
4553 registers in case the function takes a variable arguments. With
4554 @samp{-mprototype}, only calls to prototyped variable argument functions
4555 will set or clear the bit.
4558 On embedded PowerPC systems, assume that the startup module is called
4559 @file{sim-crt0.o} and that the standard C libraries are @file{libsim.a} and
4560 @file{libc.a}. This is the default for @samp{powerpc-*-eabisim}.
4564 On embedded PowerPC systems, assume that the startup module is called
4565 @file{crt0.o} and the standard C libraries are @file{libmvme.a} and
4569 On embedded PowerPC systems, assume that the startup module is called
4570 @file{crt0.o} and the standard C libraries are @file{libads.a} and
4574 On embedded PowerPC systems, assume that the startup module is called
4575 @file{crt0.o} and the standard C libraries are @file{libyk.a} and
4579 On embedded PowerPC systems, set the @var{PPC_EMB} bit in the ELF flags
4580 header to indicate that @samp{eabi} extended relocations are used.
4584 On System V.4 and embedded PowerPC systems do (do not) adhere to the
4585 Embedded Applications Binary Interface (eabi) which is a set of
4586 modifications to the System V.4 specifications. Selecting @code{-meabi}
4587 means that the stack is aligned to an 8 byte boundary, a function
4588 @code{__eabi} is called to from @code{main} to set up the eabi
4589 environment, and the @samp{-msdata} option can use both @code{r2} and
4590 @code{r13} to point to two separate small data areas. Selecting
4591 @code{-mno-eabi} means that the stack is aligned to a 16 byte boundary,
4592 do not call an initialization function from @code{main}, and the
4593 @samp{-msdata} option will only use @code{r13} to point to a single
4594 small data area. The @samp{-meabi} option is on by default if you
4595 configured GCC using one of the @samp{powerpc*-*-eabi*} options.
4598 On System V.4 and embedded PowerPC systems, put small initialized
4599 @code{const} global and static data in the @samp{.sdata2} section, which
4600 is pointed to by register @code{r2}. Put small initialized
4601 non-@code{const} global and static data in the @samp{.sdata} section,
4602 which is pointed to by register @code{r13}. Put small uninitialized
4603 global and static data in the @samp{.sbss} section, which is adjacent to
4604 the @samp{.sdata} section. The @samp{-msdata=eabi} option is
4605 incompatible with the @samp{-mrelocatable} option. The
4606 @samp{-msdata=eabi} option also sets the @samp{-memb} option.
4609 On System V.4 and embedded PowerPC systems, put small global and static
4610 data in the @samp{.sdata} section, which is pointed to by register
4611 @code{r13}. Put small uninitialized global and static data in the
4612 @samp{.sbss} section, which is adjacent to the @samp{.sdata} section.
4613 The @samp{-msdata=sysv} option is incompatible with the
4614 @samp{-mrelocatable} option.
4616 @item -msdata=default
4618 On System V.4 and embedded PowerPC systems, if @samp{-meabi} is used,
4619 compile code the same as @samp{-msdata=eabi}, otherwise compile code the
4620 same as @samp{-msdata=sysv}.
4623 On System V.4 and embedded PowerPC systems, put small global and static
4624 data in the @samp{.sdata} section. Put small uninitialized global and
4625 static data in the @samp{.sbss} section. Do not use register @code{r13}
4626 to address small data however. This is the default behavior unless
4627 other @samp{-msdata} options are used.
4631 On embedded PowerPC systems, put all initialized global and static data
4632 in the @samp{.data} section, and all uninitialized data in the
4633 @samp{.bss} section.
4636 @cindex smaller data references (PowerPC)
4637 @cindex .sdata/.sdata2 references (PowerPC)
4638 On embedded PowerPC systems, put global and static items less than or
4639 equal to @var{num} bytes into the small data or bss sections instead of
4640 the normal data or bss section. By default, @var{num} is 8. The
4641 @samp{-G @var{num}} switch is also passed to the linker.
4642 All modules should be compiled with the same @samp{-G @var{num}} value.
4645 @itemx -mno-regnames
4646 On System V.4 and embedded PowerPC systems do (do not) emit register
4647 names in the assembly language output using symbolic forms.
4650 @subsection IBM RT Options
4652 @cindex IBM RT options
4654 These @samp{-m} options are defined for the IBM RT PC:
4658 Use an in-line code sequence for integer multiplies. This is the
4661 @item -mcall-lib-mul
4662 Call @code{lmul$$} for integer multiples.
4664 @item -mfull-fp-blocks
4665 Generate full-size floating point data blocks, including the minimum
4666 amount of scratch space recommended by IBM. This is the default.
4668 @item -mminimum-fp-blocks
4669 Do not include extra scratch space in floating point data blocks. This
4670 results in smaller code, but slower execution, since scratch space must
4671 be allocated dynamically.
4673 @cindex @file{varargs.h} and RT PC
4674 @cindex @file{stdarg.h} and RT PC
4675 @item -mfp-arg-in-fpregs
4676 Use a calling sequence incompatible with the IBM calling convention in
4677 which floating point arguments are passed in floating point registers.
4678 Note that @code{varargs.h} and @code{stdargs.h} will not work with
4679 floating point operands if this option is specified.
4681 @item -mfp-arg-in-gregs
4682 Use the normal calling convention for floating point arguments. This is
4685 @item -mhc-struct-return
4686 Return structures of more than one word in memory, rather than in a
4687 register. This provides compatibility with the MetaWare HighC (hc)
4688 compiler. Use the option @samp{-fpcc-struct-return} for compatibility
4689 with the Portable C Compiler (pcc).
4691 @item -mnohc-struct-return
4692 Return some structures of more than one word in registers, when
4693 convenient. This is the default. For compatibility with the
4694 IBM-supplied compilers, use the option @samp{-fpcc-struct-return} or the
4695 option @samp{-mhc-struct-return}.
4699 @subsection MIPS Options
4700 @cindex MIPS options
4702 These @samp{-m} options are defined for the MIPS family of computers:
4705 @item -mcpu=@var{cpu type}
4706 Assume the defaults for the machine type @var{cpu type} when scheduling
4707 instructions. The choices for @var{cpu type} are @samp{r2000}, @samp{r3000},
4708 @samp{r4000}, @samp{r4400}, @samp{r4600}, and @samp{r6000}. While picking a
4709 specific @var{cpu type} will schedule things appropriately for that
4710 particular chip, the compiler will not generate any code that does not
4711 meet level 1 of the MIPS ISA (instruction set architecture) without
4712 the @samp{-mips2} or @samp{-mips3} switches being used.
4715 Issue instructions from level 1 of the MIPS ISA. This is the default.
4716 @samp{r3000} is the default @var{cpu type} at this ISA level.
4719 Issue instructions from level 2 of the MIPS ISA (branch likely, square
4720 root instructions). @samp{r6000} is the default @var{cpu type} at this
4724 Issue instructions from level 3 of the MIPS ISA (64 bit instructions).
4725 @samp{r4000} is the default @var{cpu type} at this ISA level.
4726 This option does not change the sizes of any of the C data types.
4729 Issue instructions from level 4 of the MIPS ISA. @samp{r8000} is the
4730 default @var{cpu type} at this ISA level.
4733 Assume that 32 32-bit floating point registers are available. This is
4737 Assume that 32 64-bit floating point registers are available. This is
4738 the default when the @samp{-mips3} option is used.
4741 Assume that 32 32-bit general purpose registers are available. This is
4745 Assume that 32 64-bit general purpose registers are available. This is
4746 the default when the @samp{-mips3} option is used.
4749 Types long, int, and pointer are 64 bits. This works only if @samp{-mips3}
4753 Types long and pointer are 64 bits, and type int is 32 bits.
4754 This works only if @samp{-mips3} is also specified.
4760 Generate code for the indicated ABI.
4763 Generate code for the MIPS assembler, and invoke @file{mips-tfile} to
4764 add normal debug information. This is the default for all
4765 platforms except for the OSF/1 reference platform, using the OSF/rose
4766 object format. If the either of the @samp{-gstabs} or @samp{-gstabs+}
4767 switches are used, the @file{mips-tfile} program will encapsulate the
4768 stabs within MIPS ECOFF.
4771 Generate code for the GNU assembler. This is the default on the OSF/1
4772 reference platform, using the OSF/rose object format. Also, this is
4773 the default if the configure option @samp{--with-gnu-as} is used.
4775 @item -msplit-addresses
4776 @itemx -mno-split-addresses
4777 Generate code to load the high and low parts of address constants separately.
4778 This allows @code{gcc} to optimize away redundant loads of the high order
4779 bits of addresses. This optimization requires GNU as and GNU ld.
4780 This optimization is enabled by default for some embedded targets where
4781 GNU as and GNU ld are standard.
4785 The @samp{-mrnames} switch says to output code using the MIPS software
4786 names for the registers, instead of the hardware names (ie, @var{a0}
4787 instead of @var{$4}). The only known assembler that supports this option
4788 is the Algorithmics assembler.
4792 The @samp{-mgpopt} switch says to write all of the data declarations
4793 before the instructions in the text section, this allows the MIPS
4794 assembler to generate one word memory references instead of using two
4795 words for short global or static data items. This is on by default if
4796 optimization is selected.
4800 For each non-inline function processed, the @samp{-mstats} switch
4801 causes the compiler to emit one line to the standard error file to
4802 print statistics about the program (number of registers saved, stack
4807 The @samp{-mmemcpy} switch makes all block moves call the appropriate
4808 string function (@samp{memcpy} or @samp{bcopy}) instead of possibly
4809 generating inline code.
4812 @itemx -mno-mips-tfile
4813 The @samp{-mno-mips-tfile} switch causes the compiler not
4814 postprocess the object file with the @file{mips-tfile} program,
4815 after the MIPS assembler has generated it to add debug support. If
4816 @file{mips-tfile} is not run, then no local variables will be
4817 available to the debugger. In addition, @file{stage2} and
4818 @file{stage3} objects will have the temporary file names passed to the
4819 assembler embedded in the object file, which means the objects will
4820 not compare the same. The @samp{-mno-mips-tfile} switch should only
4821 be used when there are bugs in the @file{mips-tfile} program that
4822 prevents compilation.
4825 Generate output containing library calls for floating point.
4826 @strong{Warning:} the requisite libraries are not part of GNU CC.
4827 Normally the facilities of the machine's usual C compiler are used, but
4828 this can't be done directly in cross-compilation. You must make your
4829 own arrangements to provide suitable library functions for
4833 Generate output containing floating point instructions. This is the
4834 default if you use the unmodified sources.
4837 @itemx -mno-abicalls
4838 Emit (or do not emit) the pseudo operations @samp{.abicalls},
4839 @samp{.cpload}, and @samp{.cprestore} that some System V.4 ports use for
4840 position independent code.
4843 @itemx -mno-long-calls
4844 Do all calls with the @samp{JALR} instruction, which requires
4845 loading up a function's address into a register before the call.
4846 You need to use this switch, if you call outside of the current
4847 512 megabyte segment to functions that are not through pointers.
4850 @itemx -mno-half-pic
4851 Put pointers to extern references into the data section and load them
4852 up, rather than put the references in the text section.
4854 @item -membedded-pic
4855 @itemx -mno-embedded-pic
4856 Generate PIC code suitable for some embedded systems. All calls are
4857 made using PC relative address, and all data is addressed using the $gp
4858 register. No more than 65536 bytes of global data may be used. This
4859 requires GNU as and GNU ld which do most of the work. This currently
4860 only works on targets which use ECOFF; it does not work with ELF.
4862 @item -membedded-data
4863 @itemx -mno-embedded-data
4864 Allocate variables to the read-only data section first if possible, then
4865 next in the small data section if possible, otherwise in data. This gives
4866 slightly slower code than the default, but reduces the amount of RAM required
4867 when executing, and thus may be preferred for some embedded systems.
4869 @item -msingle-float
4870 @itemx -mdouble-float
4871 The @samp{-msingle-float} switch tells gcc to assume that the floating
4872 point coprocessor only supports single precision operations, as on the
4873 @samp{r4650} chip. The @samp{-mdouble-float} switch permits gcc to use
4874 double precision operations. This is the default.
4878 Permit use of the @samp{mad}, @samp{madu} and @samp{mul} instructions,
4879 as on the @samp{r4650} chip.
4882 Turns on @samp{-msingle-float}, @samp{-mmad}, and, at least for now,
4886 Compile code for the processor in little endian mode.
4887 The requisite libraries are assumed to exist.
4890 Compile code for the processor in big endian mode.
4891 The requisite libraries are assumed to exist.
4894 @cindex smaller data references (MIPS)
4895 @cindex gp-relative references (MIPS)
4896 Put global and static items less than or equal to @var{num} bytes into
4897 the small data or bss sections instead of the normal data or bss
4898 section. This allows the assembler to emit one word memory reference
4899 instructions based on the global pointer (@var{gp} or @var{$28}),
4900 instead of the normal two words used. By default, @var{num} is 8 when
4901 the MIPS assembler is used, and 0 when the GNU assembler is used. The
4902 @samp{-G @var{num}} switch is also passed to the assembler and linker.
4903 All modules should be compiled with the same @samp{-G @var{num}}
4907 Tell the MIPS assembler to not run its preprocessor over user
4908 assembler files (with a @samp{.s} suffix) when assembling them.
4912 These options are defined by the macro
4913 @code{TARGET_SWITCHES} in the machine description. The default for the
4914 options is also defined by that macro, which enables you to change the
4919 @subsection Intel 386 Options
4920 @cindex i386 Options
4921 @cindex Intel 386 Options
4923 These @samp{-m} options are defined for the i386 family of computers:
4926 @item -mcpu=@var{cpu type}
4927 Assume the defaults for the machine type @var{cpu type} when scheduling
4928 instructions. The choices for @var{cpu type} are: @samp{i386},
4929 @samp{i486}, @samp{i586} (@samp{pentium}), @samp{pentium}, @samp{i686}
4930 (@samp{pentiumpro}) and @samp{pentiumpro}. While picking a specific
4931 @var{cpu type} will schedule things appropriately for that particular
4932 chip, the compiler will not generate any code that does not run on the
4933 i386 without the @samp{-march=@var{cpu type}} option being used.
4935 @item -march=@var{cpu type}
4936 Generate instructions for the machine type @var{cpu type}. The choices
4937 for @var{cpu type} are: @samp{i386}, @samp{i486}, @samp{pentium}, and
4938 @samp{pentiumpro}. Specifying @samp{-march=@var{cpu type}} implies
4939 @samp{-mcpu=@var{cpu type}}.
4945 Synonyms for -mcpu=i386, -mcpu=i486, -mcpu=pentium, and -mcpu=pentiumpro
4950 Control whether or not the compiler uses IEEE floating point
4951 comparisons. These handle correctly the case where the result of a
4952 comparison is unordered.
4955 Generate output containing library calls for floating point.
4956 @strong{Warning:} the requisite libraries are not part of GNU CC.
4957 Normally the facilities of the machine's usual C compiler are used, but
4958 this can't be done directly in cross-compilation. You must make your
4959 own arrangements to provide suitable library functions for
4962 On machines where a function returns floating point results in the 80387
4963 register stack, some floating point opcodes may be emitted even if
4964 @samp{-msoft-float} is used.
4966 @item -mno-fp-ret-in-387
4967 Do not use the FPU registers for return values of functions.
4969 The usual calling convention has functions return values of types
4970 @code{float} and @code{double} in an FPU register, even if there
4971 is no FPU. The idea is that the operating system should emulate
4974 The option @samp{-mno-fp-ret-in-387} causes such values to be returned
4975 in ordinary CPU registers instead.
4977 @item -mno-fancy-math-387
4978 Some 387 emulators do not support the @code{sin}, @code{cos} and
4979 @code{sqrt} instructions for the 387. Specify this option to avoid
4980 generating those instructions. This option is the default on FreeBSD.
4981 As of revision 2.6.1, these instructions are not generated unless you
4982 also use the @samp{-ffast-math} switch.
4984 @item -malign-double
4985 @itemx -mno-align-double
4986 Control whether GNU CC aligns @code{double}, @code{long double}, and
4987 @code{long long} variables on a two word boundary or a one word
4988 boundary. Aligning @code{double} variables on a two word boundary will
4989 produce code that runs somewhat faster on a @samp{Pentium} at the
4990 expense of more memory.
4992 @strong{Warning:} if you use the @samp{-malign-double} switch,
4993 structures containing the above types will be aligned differently than
4994 the published application binary interface specifications for the 386.
4997 @itemx -mno-svr3-shlib
4998 Control whether GNU CC places uninitialized locals into @code{bss} or
4999 @code{data}. @samp{-msvr3-shlib} places these locals into @code{bss}.
5000 These options are meaningful only on System V Release 3.
5002 @item -mno-wide-multiply
5003 @itemx -mwide-multiply
5004 Control whether GNU CC uses the @code{mul} and @code{imul} that produce
5005 64 bit results in @code{eax:edx} from 32 bit operands to do @code{long
5006 long} multiplies and 32-bit division by constants.
5009 Use a different function-calling convention, in which functions that
5010 take a fixed number of arguments return with the @code{ret} @var{num}
5011 instruction, which pops their arguments while returning. This saves one
5012 instruction in the caller since there is no need to pop the arguments
5015 You can specify that an individual function is called with this calling
5016 sequence with the function attribute @samp{stdcall}. You can also
5017 override the @samp{-mrtd} option by using the function attribute
5018 @samp{cdecl}. @xref{Function Attributes}
5020 @strong{Warning:} this calling convention is incompatible with the one
5021 normally used on Unix, so you cannot use it if you need to call
5022 libraries compiled with the Unix compiler.
5024 Also, you must provide function prototypes for all functions that
5025 take variable numbers of arguments (including @code{printf});
5026 otherwise incorrect code will be generated for calls to those
5029 In addition, seriously incorrect code will result if you call a
5030 function with too many arguments. (Normally, extra arguments are
5031 harmlessly ignored.)
5033 @item -mreg-alloc=@var{regs}
5034 Control the default allocation order of integer registers. The
5035 string @var{regs} is a series of letters specifying a register. The
5036 supported letters are: @code{a} allocate EAX; @code{b} allocate EBX;
5037 @code{c} allocate ECX; @code{d} allocate EDX; @code{S} allocate ESI;
5038 @code{D} allocate EDI; @code{B} allocate EBP.
5040 @item -mregparm=@var{num}
5041 Control how many registers are used to pass integer arguments. By
5042 default, no registers are used to pass arguments, and at most 3
5043 registers can be used. You can control this behavior for a specific
5044 function by using the function attribute @samp{regparm}. @xref{Function Attributes}
5046 @strong{Warning:} if you use this switch, and
5047 @var{num} is nonzero, then you must build all modules with the same
5048 value, including any libraries. This includes the system libraries and
5051 @item -malign-loops=@var{num}
5052 Align loops to a 2 raised to a @var{num} byte boundary. If
5053 @samp{-malign-loops} is not specified, the default is 2 unless
5054 gas 2.8 (or later) is being used in which case the default is
5055 to align the loop on a 16 byte boundary if it is less than 8
5058 @item -malign-jumps=@var{num}
5059 Align instructions that are only jumped to to a 2 raised to a @var{num}
5060 byte boundary. If @samp{-malign-jumps} is not specified, the default is
5061 2 if optimizing for a 386, and 4 if optimizing for a 486 unless
5062 gas 2.8 (or later) is being used in which case the default is
5063 to align the instruction on a 16 byte boundary if it is less
5066 @item -malign-functions=@var{num}
5067 Align the start of functions to a 2 raised to @var{num} byte boundary.
5068 If @samp{-malign-functions} is not specified, the default is 2 if optimizing
5069 for a 386, and 4 if optimizing for a 486.
5073 @subsection HPPA Options
5074 @cindex HPPA Options
5076 These @samp{-m} options are defined for the HPPA family of computers:
5080 Generate code for a PA 1.0 processor.
5083 Generate code for a PA 1.1 processor.
5086 Generate code suitable for big switch tables. Use this option only if
5087 the assembler/linker complain about out of range branches within a switch
5090 @item -mjump-in-delay
5091 Fill delay slots of function calls with unconditional jump instructions
5092 by modifying the return pointer for the function call to be the target
5093 of the conditional jump.
5095 @item -mdisable-fpregs
5096 Prevent floating point registers from being used in any manner. This is
5097 necessary for compiling kernels which perform lazy context switching of
5098 floating point registers. If you use this option and attempt to perform
5099 floating point operations, the compiler will abort.
5101 @item -mdisable-indexing
5102 Prevent the compiler from using indexing address modes. This avoids some
5103 rather obscure problems when compiling MIG generated code under MACH.
5105 @item -mno-space-regs
5106 Generate code that assumes the target has no space registers. This allows
5107 GCC to generate faster indirect calls and use unscaled index address modes.
5109 Such code is suitable for level 0 PA systems and kernels.
5111 @item -mfast-indirect-calls
5112 Generate code that assumes calls never cross space boundaries. This
5113 allows GCC to emit code which performs faster indirect calls.
5115 This option will not work in the presense of shared libraries or nested
5119 Optimize for space rather than execution time. Currently this only
5120 enables out of line function prologues and epilogues. This option is
5121 incompatible with PIC code generation and profiling.
5123 @item -mlong-load-store
5124 Generate 3-instruction load and store sequences as sometimes required by
5125 the HP-UX 10 linker. This is equivalent to the @samp{+k} option to
5128 @item -mportable-runtime
5129 Use the portable calling conventions proposed by HP for ELF systems.
5132 Enable the use of assembler directives only GAS understands.
5134 @item -mschedule=@var{cpu type}
5135 Schedule code according to the constraints for the machine type
5136 @var{cpu type}. The choices for @var{cpu type} are @samp{700} for
5137 7@var{n}0 machines, @samp{7100} for 7@var{n}5 machines, and @samp{7100LC}
5138 for 7@var{n}2 machines. @samp{7100} is the default for @var{cpu type}.
5140 Note the @samp{7100LC} scheduling information is incomplete and using
5141 @samp{7100LC} often leads to bad schedules. For now it's probably best
5142 to use @samp{7100} instead of @samp{7100LC} for the 7@var{n}2 machines.
5145 Enable the optimization pass in the HPUX linker. Note this makes symbolic
5146 debugging impossible. It also triggers a bug in the HPUX 8 and HPUX 9 linkers
5147 in which they give bogus error messages when linking some programs.
5150 Generate output containing library calls for floating point.
5151 @strong{Warning:} the requisite libraries are not available for all HPPA
5152 targets. Normally the facilities of the machine's usual C compiler are
5153 used, but this cannot be done directly in cross-compilation. You must make
5154 your own arrangements to provide suitable library functions for
5155 cross-compilation. The embedded target @samp{hppa1.1-*-pro}
5156 does provide software floating point support.
5158 @samp{-msoft-float} changes the calling convention in the output file;
5159 therefore, it is only useful if you compile @emph{all} of a program with
5160 this option. In particular, you need to compile @file{libgcc.a}, the
5161 library that comes with GNU CC, with @samp{-msoft-float} in order for
5165 @node Intel 960 Options
5166 @subsection Intel 960 Options
5168 These @samp{-m} options are defined for the Intel 960 implementations:
5171 @item -m@var{cpu type}
5172 Assume the defaults for the machine type @var{cpu type} for some of
5173 the other options, including instruction scheduling, floating point
5174 support, and addressing modes. The choices for @var{cpu type} are
5175 @samp{ka}, @samp{kb}, @samp{mc}, @samp{ca}, @samp{cf},
5176 @samp{sa}, and @samp{sb}.
5182 The @samp{-mnumerics} option indicates that the processor does support
5183 floating-point instructions. The @samp{-msoft-float} option indicates
5184 that floating-point support should not be assumed.
5186 @item -mleaf-procedures
5187 @itemx -mno-leaf-procedures
5188 Do (or do not) attempt to alter leaf procedures to be callable with the
5189 @code{bal} instruction as well as @code{call}. This will result in more
5190 efficient code for explicit calls when the @code{bal} instruction can be
5191 substituted by the assembler or linker, but less efficient code in other
5192 cases, such as calls via function pointers, or using a linker that doesn't
5193 support this optimization.
5196 @itemx -mno-tail-call
5197 Do (or do not) make additional attempts (beyond those of the
5198 machine-independent portions of the compiler) to optimize tail-recursive
5199 calls into branches. You may not want to do this because the detection of
5200 cases where this is not valid is not totally complete. The default is
5201 @samp{-mno-tail-call}.
5203 @item -mcomplex-addr
5204 @itemx -mno-complex-addr
5205 Assume (or do not assume) that the use of a complex addressing mode is a
5206 win on this implementation of the i960. Complex addressing modes may not
5207 be worthwhile on the K-series, but they definitely are on the C-series.
5208 The default is currently @samp{-mcomplex-addr} for all processors except
5212 @itemx -mno-code-align
5213 Align code to 8-byte boundaries for faster fetching (or don't bother).
5214 Currently turned on by default for C-series implementations only.
5217 @item -mclean-linkage
5218 @itemx -mno-clean-linkage
5219 These options are not fully implemented.
5223 @itemx -mic2.0-compat
5224 @itemx -mic3.0-compat
5225 Enable compatibility with iC960 v2.0 or v3.0.
5229 Enable compatibility with the iC960 assembler.
5231 @item -mstrict-align
5232 @itemx -mno-strict-align
5233 Do not permit (do permit) unaligned accesses.
5236 Enable structure-alignment compatibility with Intel's gcc release version
5237 1.3 (based on gcc 1.37). This option implies @samp{-mstrict-align}.
5240 @node DEC Alpha Options
5241 @subsection DEC Alpha Options
5243 These @samp{-m} options are defined for the DEC Alpha implementations:
5246 @item -mno-soft-float
5248 Use (do not use) the hardware floating-point instructions for
5249 floating-point operations. When @code{-msoft-float} is specified,
5250 functions in @file{libgcc1.c} will be used to perform floating-point
5251 operations. Unless they are replaced by routines that emulate the
5252 floating-point operations, or compiled in such a way as to call such
5253 emulations routines, these routines will issue floating-point
5254 operations. If you are compiling for an Alpha without floating-point
5255 operations, you must ensure that the library is built so as not to call
5258 Note that Alpha implementations without floating-point operations are
5259 required to have floating-point registers.
5263 Generate code that uses (does not use) the floating-point register set.
5264 @code{-mno-fp-regs} implies @code{-msoft-float}. If the floating-point
5265 register set is not used, floating point operands are passed in integer
5266 registers as if they were integers and floating-point results are passed
5267 in $0 instead of $f0. This is a non-standard calling sequence, so any
5268 function with a floating-point argument or return value called by code
5269 compiled with @code{-mno-fp-regs} must also be compiled with that
5272 A typical use of this option is building a kernel that does not use,
5273 and hence need not save and restore, any floating-point registers.
5276 The Alpha architecture implements floating-point hardware optimized for
5277 maximum performance. It is mostly compliant with the IEEE floating
5278 point standard. However, for full compliance, software assistance is
5279 required. This option generates code fully IEEE compliant code
5280 @emph{except} that the @var{inexact flag} is not maintained (see below).
5281 If this option is turned on, the CPP macro @code{_IEEE_FP} is defined
5282 during compilation. The option is a shorthand for: @samp{-D_IEEE_FP
5283 -mfp-trap-mode=su -mtrap-precision=i -mieee-conformant}. The resulting
5284 code is less efficient but is able to correctly support denormalized
5285 numbers and exceptional IEEE values such as not-a-number and plus/minus
5286 infinity. Other Alpha compilers call this option
5287 @code{-ieee_with_no_inexact}.
5289 @item -mieee-with-inexact
5290 @c overfull hbox here --bob 22 jul96
5291 @c original text between ignore ... end ignore
5293 This is like @samp{-mieee} except the generated code also maintains the
5294 IEEE @var{inexact flag}. Turning on this option causes the generated
5295 code to implement fully-compliant IEEE math. The option is a shorthand
5296 for @samp{-D_IEEE_FP -D_IEEE_FP_INEXACT} plus @samp{-mieee-conformant},
5297 @samp{-mfp-trap-mode=sui}, and @samp{-mtrap-precision=i}. On some Alpha
5298 implementations the resulting code may execute significantly slower than
5299 the code generated by default. Since there is very little code that
5300 depends on the @var{inexact flag}, you should normally not specify this
5301 option. Other Alpha compilers call this option
5302 @samp{-ieee_with_inexact}.
5304 @c changed paragraph
5305 This is like @samp{-mieee} except the generated code also maintains the
5306 IEEE @var{inexact flag}. Turning on this option causes the generated
5307 code to implement fully-compliant IEEE math. The option is a shorthand
5308 for @samp{-D_IEEE_FP -D_IEEE_FP_INEXACT} plus the three following:
5309 @samp{-mieee-conformant},
5310 @samp{-mfp-trap-mode=sui},
5311 and @samp{-mtrap-precision=i}.
5312 On some Alpha implementations the resulting code may execute
5313 significantly slower than the code generated by default. Since there
5314 is very little code that depends on the @var{inexact flag}, you should
5315 normally not specify this option. Other Alpha compilers call this
5316 option @samp{-ieee_with_inexact}.
5317 @c end changes to prevent overfull hboxes
5319 @item -mfp-trap-mode=@var{trap mode}
5320 This option controls what floating-point related traps are enabled.
5321 Other Alpha compilers call this option @samp{-fptm }@var{trap mode}.
5322 The trap mode can be set to one of four values:
5326 This is the default (normal) setting. The only traps that are enabled
5327 are the ones that cannot be disabled in software (e.g., division by zero
5331 In addition to the traps enabled by @samp{n}, underflow traps are enabled
5335 Like @samp{su}, but the instructions are marked to be safe for software
5336 completion (see Alpha architecture manual for details).
5339 Like @samp{su}, but inexact traps are enabled as well.
5342 @item -mfp-rounding-mode=@var{rounding mode}
5343 Selects the IEEE rounding mode. Other Alpha compilers call this option
5344 @samp{-fprm }@var{rounding mode}. The @var{rounding mode} can be one
5349 Normal IEEE rounding mode. Floating point numbers are rounded towards
5350 the nearest machine number or towards the even machine number in case
5354 Round towards minus infinity.
5357 Chopped rounding mode. Floating point numbers are rounded towards zero.
5360 Dynamic rounding mode. A field in the floating point control register
5361 (@var{fpcr}, see Alpha architecture reference manual) controls the
5362 rounding mode in effect. The C library initializes this register for
5363 rounding towards plus infinity. Thus, unless your program modifies the
5364 @var{fpcr}, @samp{d} corresponds to round towards plus infinity.@end table
5366 @item -mtrap-precision=@var{trap precision}
5367 In the Alpha architecture, floating point traps are imprecise. This
5368 means without software assistance it is impossible to recover from a
5369 floating trap and program execution normally needs to be terminated.
5370 GNU CC can generate code that can assist operating system trap handlers
5371 in determining the exact location that caused a floating point trap.
5372 Depending on the requirements of an application, different levels of
5373 precisions can be selected:
5377 Program precision. This option is the default and means a trap handler
5378 can only identify which program caused a floating point exception.
5381 Function precision. The trap handler can determine the function that
5382 caused a floating point exception.
5385 Instruction precision. The trap handler can determine the exact
5386 instruction that caused a floating point exception.
5389 Other Alpha compilers provide the equivalent options called
5390 @samp{-scope_safe} and @samp{-resumption_safe}.
5392 @item -mieee-conformant
5393 This option marks the generated code as IEEE conformant. You must not
5394 use this option unless you also specify @samp{-mtrap-precision=i} and either
5395 @samp{-mfp-trap-mode=su} or @samp{-mfp-trap-mode=sui}. Its only effect
5396 is to emit the line @samp{.eflag 48} in the function prologue of the
5397 generated assembly file. Under DEC Unix, this has the effect that
5398 IEEE-conformant math library routines will be linked in.
5400 @item -mbuild-constants
5401 Normally GNU CC examines a 32- or 64-bit integer constant to
5402 see if it can construct it from smaller constants in two or three
5403 instructions. If it cannot, it will output the constant as a literal and
5404 generate code to load it from the data segment at runtime.
5406 Use this option to require GNU CC to construct @emph{all} integer constants
5407 using code, even if it takes more instructions (the maximum is six).
5409 You would typically use this option to build a shared library dynamic
5410 loader. Itself a shared library, it must relocate itself in memory
5411 before it can find the variables and constants in its own data segment.
5415 Select whether to generate code to be assembled by the vendor-supplied
5416 assembler (@samp{-malpha-as}) or by the GNU assembler @samp{-mgas}.
5424 Indicate whether GNU CC should generate code to use the optional BWX,
5425 CIX, and MAX instruction sets. The default is to use the instruction sets
5426 supported by the CPU type specified via @samp{-mcpu=} option or that
5427 of the CPU on which GNU CC was built if none was specified.
5429 @item -mcpu=@var{cpu_type}
5430 Set the instruction set, register set, and instruction scheduling
5431 parameters for machine type @var{cpu_type}. You can specify either the
5432 @samp{EV} style name or the corresponding chip number. GNU CC
5433 supports scheduling parameters for the EV4 and EV5 family of processors
5434 and will choose the default values for the instruction set from
5435 the processor you specify. If you do not specify a processor type,
5436 GNU CC will default to the processor on which the compiler was built.
5438 Supported values for @var{cpu_type} are
5443 Schedules as an EV4 and has no instruction set extensions.
5447 Schedules as an EV5 and has no instruction set extensions.
5451 Schedules as an EV5 and supports the BWX extension.
5456 Schedules as an EV5 and supports the BWX and MAX extensions.
5460 Schedules as an EV5 (until Digital releases the scheduling parameters
5461 for the EV6) and supports the BWX, CIX, and MAX extensions.
5464 @item -mmemory-latency=@var{time}
5465 Sets the latency the scheduler should assume for typical memory
5466 references as seen by the application. This number is highly
5467 dependant on the memory access patterns used by the application
5468 and the size of the external cache on the machine.
5470 Valid options for @var{time} are
5474 A decimal number representing clock cycles.
5480 The compiler contains estimates of the number of clock cycles for
5481 ``typical'' EV4 & EV5 hardware for the Level 1, 2 & 3 caches
5482 (also called Dcache, Scache, and Bcache), as well as to main memory.
5483 Note that L3 is only valid for EV5.
5488 @node Clipper Options
5489 @subsection Clipper Options
5491 These @samp{-m} options are defined for the Clipper implementations:
5495 Produce code for a C300 Clipper processor. This is the default.
5498 Produce code for a C400 Clipper processor i.e. use floating point
5502 @node H8/300 Options
5503 @subsection H8/300 Options
5505 These @samp{-m} options are defined for the H8/300 implementations:
5509 Shorten some address references at link time, when possible; uses the
5510 linker option @samp{-relax}. @xref{H8/300,, @code{ld} and the H8/300,
5511 ld.info, Using ld}, for a fuller description.
5514 Generate code for the H8/300H.
5517 Generate code for the H8/S.
5520 Make @code{int} data 32 bits by default.
5523 On the h8/300h, use the same alignment rules as for the h8/300.
5524 The default for the h8/300h is to align longs and floats on 4 byte boundaries.
5525 @samp{-malign-300} causes them to be aligned on 2 byte boundaries.
5526 This option has no effect on the h8/300.
5530 @subsection SH Options
5532 These @samp{-m} options are defined for the SH implementations:
5536 Generate code for the SH1.
5539 Generate code for the SH2.
5542 Generate code for the SH3.
5545 Generate code for the SH3e.
5548 Compile code for the processor in big endian mode.
5551 Compile code for the processor in little endian mode.
5554 Align doubles at 64 bit boundaries. Note that this changes the calling
5555 conventions, and thus some functions from the standard C library will
5556 not work unless you recompile it first with -mdalign.
5559 Shorten some address references at link time, when possible; uses the
5560 linker option @samp{-relax}.
5563 @node System V Options
5564 @subsection Options for System V
5566 These additional options are available on System V Release 4 for
5567 compatibility with other compilers on those systems:
5571 Create a shared object.
5572 It is recommended that @samp{-symbolic} or @samp{-shared} be used instead.
5575 Identify the versions of each tool used by the compiler, in a
5576 @code{.ident} assembler directive in the output.
5579 Refrain from adding @code{.ident} directives to the output file (this is
5582 @item -YP,@var{dirs}
5583 Search the directories @var{dirs}, and no others, for libraries
5584 specified with @samp{-l}.
5587 Look in the directory @var{dir} to find the M4 preprocessor.
5588 The assembler uses this option.
5589 @c This is supposed to go with a -Yd for predefined M4 macro files, but
5590 @c the generic assembler that comes with Solaris takes just -Ym.
5594 @subsection V850 Options
5595 @cindex V850 Options
5597 These @samp{-m} options are defined for V850 implementations:
5601 @itemx -mno-long-calls
5602 Treat all calls as being far away (near). If calls are assumed to be
5603 far away, the compiler will always load the functions address up into a
5604 register, and call indirect through the pointer.
5608 Do not optimize (do optimize) basic blocks that use the same index
5609 pointer 4 or more times to copy pointer into the @code{ep} register, and
5610 use the shorter @code{sld} and @code{sst} instructions. The @samp{-mep}
5611 option is on by default if you optimize.
5613 @item -mno-prolog-function
5614 @itemx -mprolog-function
5615 Do not use (do use) external functions to save and restore registers at
5616 the prolog and epilog of a function. The external functions are slower,
5617 but use less code space if more than one function saves the same number
5618 of registers. The @samp{-mprolog-function} option is on by default if
5622 Try to make the code as small as possible. At present, this just turns
5623 on the @samp{-mep} and @samp{-mprolog-function} options.
5626 Put static or global variables whose size is @var{n} bytes or less into
5627 the tiny data area that register @code{ep} points to. The tiny data
5628 area can hold up to 256 bytes in total (128 bytes for byte references).
5631 Put static or global variables whose size is @var{n} bytes or less into
5632 the small data area that register @code{gp} points to. The small data
5633 area can hold up to 64 kilobytes.
5636 Put static or global variables whose size is @var{n} bytes or less into
5637 the first 32 kilobytes of memory.
5640 Specify that the target processor is the V850.
5643 Generate code suitable for big switch tables. Use this option only if
5644 the assembler/linker complain about out of range branches within a switch
5649 @subsection ARC Options
5652 These options are defined for ARC implementations:
5656 Compile code for little endian mode. This is the default.
5659 Compile code for big endian mode.
5662 Prepend the name of the cpu to all public symbol names.
5663 In multiple-processor systems, there are many ARC variants with different
5664 instruction and register set characteristics. This flag prevents code
5665 compiled for one cpu to be linked with code compiled for another.
5666 No facility exists for handling variants that are "almost identical".
5667 This is an all or nothing option.
5669 @item -mcpu=@var{cpu}
5670 Compile code for ARC variant @var{cpu}.
5671 Which variants are supported depend on the configuration.
5672 All variants support @samp{-mcpu=base}, this is the default.
5674 @item -mtext=@var{text section}
5675 @item -mdata=@var{data section}
5676 @item -mrodata=@var{readonly data section}
5677 Put functions, data, and readonly data in @var{text section},
5678 @var{data section}, and @var{readonly data section} respectively
5679 by default. This can be overridden with the @code{section} attribute.
5680 @xref{Variable Attributes}
5685 @subsection NS32K Options
5686 @cindex NS32K options
5688 These are the @samp{-m} options defined for the 32000 series. The default
5689 values for these options depends on which style of 32000 was selected when
5690 the compiler was configured; the defaults for the most common choices are
5696 Generate output for a 32032. This is the default
5697 when the compiler is configured for 32032 and 32016 based systems.
5701 Generate output for a 32332. This is the default
5702 when the compiler is configured for 32332-based systems.
5706 Generate output for a 32532. This is the default
5707 when the compiler is configured for 32532-based systems.
5710 Generate output containing 32081 instructions for floating point.
5711 This is the default for all systems.
5714 Generate output containing 32381 instructions for floating point. This
5715 also implies @samp{-m32081}. The 32381 is only compatible with the 32332
5716 and 32532 cpus. This is the default for the pc532-netbsd configuration.
5719 Try and generate multiply-add floating point instructions @code{polyF}
5720 and @code{dotF}. This option is only available if the @samp{-m32381}
5721 option is in effect. Using these instructions requires changes to to
5722 register allocation which generally has a negative impact on
5723 performance. This option should only be enabled when compiling code
5724 particularly likely to make heavy use of multiply-add instructions.
5727 Do not try and generate multiply-add floating point instructions
5728 @code{polyF} and @code{dotF}. This is the default on all platforms.
5731 Generate output containing library calls for floating point.
5732 @strong{Warning:} the requisite libraries may not be available.
5735 Do not use the bit-field instructions. On some machines it is faster to
5736 use shifting and masking operations. This is the default for the pc532.
5739 Do use the bit-field instructions. This is the default for all platforms
5743 Use a different function-calling convention, in which functions
5744 that take a fixed number of arguments return pop their
5745 arguments on return with the @code{ret} instruction.
5747 This calling convention is incompatible with the one normally
5748 used on Unix, so you cannot use it if you need to call libraries
5749 compiled with the Unix compiler.
5751 Also, you must provide function prototypes for all functions that
5752 take variable numbers of arguments (including @code{printf});
5753 otherwise incorrect code will be generated for calls to those
5756 In addition, seriously incorrect code will result if you call a
5757 function with too many arguments. (Normally, extra arguments are
5758 harmlessly ignored.)
5760 This option takes its name from the 680x0 @code{rtd} instruction.
5764 Use a different function-calling convention where the first two arguments
5765 are passed in registers.
5767 This calling convention is incompatible with the one normally
5768 used on Unix, so you cannot use it if you need to call libraries
5769 compiled with the Unix compiler.
5772 Do not pass any arguments in registers. This is the default for all
5776 It is OK to use the sb as an index register which is always loaded with
5777 zero. This is the default for the pc532-netbsd target.
5780 The sb register is not available for use or has not been initialized to
5781 zero by the run time system. This is the default for all targets except
5782 the pc532-netbsd. It is also implied whenever @samp{-mhimem} or
5783 @samp{-fpic} is set.
5786 Many ns32000 series addressing modes use displacements of up to 512MB.
5787 If an address is above 512MB then displacements from zero can not be used.
5788 This option causes code to be generated which can be loaded above 512MB.
5789 This may be useful for operating systems or ROM code.
5792 Assume code will be loaded in the first 512MB of virtual address space.
5793 This is the default for all platforms.
5800 @node Code Gen Options
5801 @section Options for Code Generation Conventions
5802 @cindex code generation conventions
5803 @cindex options, code generation
5804 @cindex run-time options
5806 These machine-independent options control the interface conventions
5807 used in code generation.
5809 Most of them have both positive and negative forms; the negative form
5810 of @samp{-ffoo} would be @samp{-fno-foo}. In the table below, only
5811 one of the forms is listed---the one which is not the default. You
5812 can figure out the other form by either removing @samp{no-} or adding
5817 Enable exception handling. Generates extra code needed to propagate
5818 exceptions. For some targets, this implies generation of frame unwind
5819 information for all functions. This can produce significant data size
5820 overhead, although it does not affect execution.
5821 If you do not specify this option, it is enabled by
5822 default for languages like C++ which normally require exception handling,
5823 and disabled for languages like C that do not normally require it.
5824 However, when compiling C code that needs to interoperate properly with
5825 exception handlers written in C++, you may need to enable this option.
5826 You may also wish to disable this option is you are compiling older C++
5827 programs that don't use exception handling.
5829 @item -fpcc-struct-return
5830 Return ``short'' @code{struct} and @code{union} values in memory like
5831 longer ones, rather than in registers. This convention is less
5832 efficient, but it has the advantage of allowing intercallability between
5833 GNU CC-compiled files and files compiled with other compilers.
5835 The precise convention for returning structures in memory depends
5836 on the target configuration macros.
5838 Short structures and unions are those whose size and alignment match
5839 that of some integer type.
5841 @item -freg-struct-return
5842 Use the convention that @code{struct} and @code{union} values are
5843 returned in registers when possible. This is more efficient for small
5844 structures than @samp{-fpcc-struct-return}.
5846 If you specify neither @samp{-fpcc-struct-return} nor its contrary
5847 @samp{-freg-struct-return}, GNU CC defaults to whichever convention is
5848 standard for the target. If there is no standard convention, GNU CC
5849 defaults to @samp{-fpcc-struct-return}, except on targets where GNU CC
5850 is the principal compiler. In those cases, we can choose the standard,
5851 and we chose the more efficient register return alternative.
5854 Allocate to an @code{enum} type only as many bytes as it needs for the
5855 declared range of possible values. Specifically, the @code{enum} type
5856 will be equivalent to the smallest integer type which has enough room.
5858 @item -fshort-double
5859 Use the same size for @code{double} as for @code{float}.
5862 Requests that the data and non-@code{const} variables of this
5863 compilation be shared data rather than private data. The distinction
5864 makes sense only on certain operating systems, where shared data is
5865 shared between processes running the same program, while private data
5866 exists in one copy per process.
5869 Allocate even uninitialized global variables in the bss section of the
5870 object file, rather than generating them as common blocks. This has the
5871 effect that if the same variable is declared (without @code{extern}) in
5872 two different compilations, you will get an error when you link them.
5873 The only reason this might be useful is if you wish to verify that the
5874 program will work on other systems which always work this way.
5877 Ignore the @samp{#ident} directive.
5879 @item -fno-gnu-linker
5880 Do not output global initializations (such as C++ constructors and
5881 destructors) in the form used by the GNU linker (on systems where the GNU
5882 linker is the standard method of handling them). Use this option when
5883 you want to use a non-GNU linker, which also requires using the
5884 @code{collect2} program to make sure the system linker includes
5885 constructors and destructors. (@code{collect2} is included in the GNU CC
5886 distribution.) For systems which @emph{must} use @code{collect2}, the
5887 compiler driver @code{gcc} is configured to do this automatically.
5889 @item -finhibit-size-directive
5890 Don't output a @code{.size} assembler directive, or anything else that
5891 would cause trouble if the function is split in the middle, and the
5892 two halves are placed at locations far apart in memory. This option is
5893 used when compiling @file{crtstuff.c}; you should not need to use it
5897 Put extra commentary information in the generated assembly code to
5898 make it more readable. This option is generally only of use to those
5899 who actually need to read the generated assembly code (perhaps while
5900 debugging the compiler itself).
5902 @samp{-fno-verbose-asm}, the default, causes the
5903 extra information to be omitted and is useful when comparing two assembler
5907 Consider all memory references through pointers to be volatile.
5909 @item -fvolatile-global
5910 Consider all memory references to extern and global data items to
5914 @cindex global offset table
5916 Generate position-independent code (PIC) suitable for use in a shared
5917 library, if supported for the target machine. Such code accesses all
5918 constant addresses through a global offset table (GOT). The dynamic
5919 loader resolves the GOT entries when the program starts (the dynamic
5920 loader is not part of GNU CC; it is part of the operating system). If
5921 the GOT size for the linked executable exceeds a machine-specific
5922 maximum size, you get an error message from the linker indicating that
5923 @samp{-fpic} does not work; in that case, recompile with @samp{-fPIC}
5924 instead. (These maximums are 16k on the m88k, 8k on the Sparc, and 32k
5925 on the m68k and RS/6000. The 386 has no such limit.)
5927 Position-independent code requires special support, and therefore works
5928 only on certain machines. For the 386, GNU CC supports PIC for System V
5929 but not for the Sun 386i. Code generated for the IBM RS/6000 is always
5930 position-independent.
5933 If supported for the target machine, emit position-independent code,
5934 suitable for dynamic linking and avoiding any limit on the size of the
5935 global offset table. This option makes a difference on the m68k, m88k,
5938 Position-independent code requires special support, and therefore works
5939 only on certain machines.
5941 @item -ffixed-@var{reg}
5942 Treat the register named @var{reg} as a fixed register; generated code
5943 should never refer to it (except perhaps as a stack pointer, frame
5944 pointer or in some other fixed role).
5946 @var{reg} must be the name of a register. The register names accepted
5947 are machine-specific and are defined in the @code{REGISTER_NAMES}
5948 macro in the machine description macro file.
5950 This flag does not have a negative form, because it specifies a
5953 @item -fcall-used-@var{reg}
5954 Treat the register named @var{reg} as an allocable register that is
5955 clobbered by function calls. It may be allocated for temporaries or
5956 variables that do not live across a call. Functions compiled this way
5957 will not save and restore the register @var{reg}.
5959 It is an error to used this flag with the frame pointer or stack pointer.
5960 Use of this flag for other registers that have fixed pervasive roles in
5961 the machine's execution model will produce disastrous results.
5963 This flag does not have a negative form, because it specifies a
5966 @item -fcall-saved-@var{reg}
5967 Treat the register named @var{reg} as an allocable register saved by
5968 functions. It may be allocated even for temporaries or variables that
5969 live across a call. Functions compiled this way will save and restore
5970 the register @var{reg} if they use it.
5972 It is an error to used this flag with the frame pointer or stack pointer.
5973 Use of this flag for other registers that have fixed pervasive roles in
5974 the machine's execution model will produce disastrous results.
5976 A different sort of disaster will result from the use of this flag for
5977 a register in which function values may be returned.
5979 This flag does not have a negative form, because it specifies a
5983 Pack all structure members together without holes. Usually you would
5984 not want to use this option, since it makes the code suboptimal, and
5985 the offsets of structure members won't agree with system libraries.
5987 @item -fcheck-memory-usage
5988 Generate extra code to check each memory access. GNU CC will generate
5989 code that is suitable for a detector of bad memory accesses such as
5992 You must also specify this option when you compile functions you call that
5993 have side effects. If you do not, you may get erroneous messages from
5994 the detector. Normally, you should compile all your code with this option.
5995 If you use functions from a library that have side-effects (such as
5996 @code{read}), you may not be able to recompile the library and
5997 specify this option. In that case, you can enable the
5998 @samp{-fprefix-function-name} option, which requests GNU CC to encapsulate
5999 your code and make other functions look as if they were compiled with
6000 @samp{-fcheck-memory-usage}. This is done by calling ``stubs'',
6001 which are provided by the detector. If you cannot find or build
6002 stubs for every function you call, you may have to specify
6003 @samp{-fcheck-memory-usage} without @samp{-fprefix-function-name}.
6005 If you specify this option, you can not use the @code{asm} or
6006 @code{__asm__} keywords in functions with memory checking enabled. The
6007 compiler cannot understand what the @code{asm} statement will do, and
6008 therefore cannot generate the appropriate code, so it is rejected.
6009 However, the function attribute @code{no_check_memory_usage} will
6010 disable memory checking within a function, and @code{asm} statements can
6011 be put inside such functions. Inline expansion of a non-checked
6012 function within a checked function is permitted; the inline function's
6013 memory accesses won't be checked, but the rest will.
6015 If you move your @code{asm} statements to non-checked inline functions,
6016 but they do access memory, you can add calls to the support code in your
6017 inline function, to indicate any reads, writes, or copies being done.
6018 These calls would be similar to those done in the stubs described above.
6020 @c FIXME: The support-routine interface is defined by the compiler and
6021 @c should be documented!
6023 @item -fprefix-function-name
6024 Request GNU CC to add a prefix to the symbols generated for function names.
6025 GNU CC adds a prefix to the names of functions defined as well as
6026 functions called. Code compiled with this option and code compiled
6027 without the option can't be linked together, unless or stubs are used.
6029 If you compile the following code with @samp{-fprefix-function-name}
6031 extern void bar (int);
6041 GNU CC will compile the code as if it was written:
6043 extern void prefix_bar (int);
6047 return prefix_bar (a + 5);
6050 This option is designed to be used with @samp{-fcheck-memory-usage}.
6052 @item -finstrument-functions
6053 Generate instrumentation calls for entry and exit to functions. Just
6054 after function entry and just before function exit, the following
6055 profiling functions will be called with the address of the current
6056 function and its call site. (On some platforms,
6057 @code{__builtin_return_address} does not work beyond the current
6058 function, so the call site information may not be available to the
6059 profiling functions otherwise.)
6062 void __cyg_profile_func_enter (void *this_fn, void *call_site);
6063 void __cyg_profile_func_exit (void *this_fn, void *call_site);
6066 The first argument is the address of the start of the current function,
6067 which may be looked up exactly in the symbol table.
6069 This instrumentation is also done for functions expanded inline in other
6070 functions. The profiling calls will indicate where, conceptually, the
6071 inline function is entered and exited. This means that addressable
6072 versions of such functions must be available. If all your uses of a
6073 function are expanded inline, this may mean an additional expansion of
6074 code size. If you use @samp{extern inline} in your C code, an
6075 addressable version of such functions must be provided. (This is
6076 normally the case anyways, but if you get lucky and the optimizer always
6077 expands the functions inline, you might have gotten away without
6078 providing static copies.)
6080 A function may be given the attribute @code{no_instrument_function}, in
6081 which case this instrumentation will not be done. This can be used, for
6082 example, for the profiling functions listed above, high-priority
6083 interrupt routines, and any functions from which the profiling functions
6084 cannot safely be called (perhaps signal handlers, if the profiling
6085 routines generate output or allocate memory).
6088 Generate code to verify that you do not go beyond the boundary of the
6089 stack. You should specify this flag if you are running in an
6090 environment with multiple threads, but only rarely need to specify it in
6091 a single-threaded environment since stack overflow is automatically
6092 detected on nearly all systems if there is only one stack.
6094 @cindex aliasing of parameters
6095 @cindex parameters, aliased
6096 @item -fargument-alias
6097 @itemx -fargument-noalias
6098 @itemx -fargument-noalias-global
6099 Specify the possible relationships among parameters and between
6100 parameters and global data.
6102 @samp{-fargument-alias} specifies that arguments (parameters) may
6103 alias each other and may alias global storage.
6104 @samp{-fargument-noalias} specifies that arguments do not alias
6105 each other, but may alias global storage.
6106 @samp{-fargument-noalias-global} specifies that arguments do not
6107 alias each other and do not alias global storage.
6109 Each language will automatically use whatever option is required by
6110 the language standard. You should not need to use these options yourself.
6112 @item -fleading-underscore
6113 This option and its counterpart, -fno-leading-underscore, forcibly
6114 change the way C symbols are represented in the object file. One use
6115 is to help link with legacy assembly code.
6117 Be warned that you should know what you are doing when invoking this
6118 option, and that not all targets provide complete support for it.
6121 @node Environment Variables
6122 @section Environment Variables Affecting GNU CC
6123 @cindex environment variables
6125 This section describes several environment variables that affect how GNU
6126 CC operates. Some of them work by specifying directories or prefixes to use
6127 when searching for various kinds of files. Some are used to specify other
6128 aspects of the compilation environment.
6131 Note that you can also specify places to search using options such as
6132 @samp{-B}, @samp{-I} and @samp{-L} (@pxref{Directory Options}). These
6133 take precedence over places specified using environment variables, which
6134 in turn take precedence over those specified by the configuration of GNU
6138 Note that you can also specify places to search using options such as
6139 @samp{-B}, @samp{-I} and @samp{-L} (@pxref{Directory Options}). These
6140 take precedence over places specified using environment variables, which
6141 in turn take precedence over those specified by the configuration of GNU
6148 If @code{TMPDIR} is set, it specifies the directory to use for temporary
6149 files. GNU CC uses temporary files to hold the output of one stage of
6150 compilation which is to be used as input to the next stage: for example,
6151 the output of the preprocessor, which is the input to the compiler
6154 @item GCC_EXEC_PREFIX
6155 @findex GCC_EXEC_PREFIX
6156 If @code{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the
6157 names of the subprograms executed by the compiler. No slash is added
6158 when this prefix is combined with the name of a subprogram, but you can
6159 specify a prefix that ends with a slash if you wish.
6161 If GNU CC cannot find the subprogram using the specified prefix, it
6162 tries looking in the usual places for the subprogram.
6164 The default value of @code{GCC_EXEC_PREFIX} is
6165 @file{@var{prefix}/lib/gcc-lib/} where @var{prefix} is the value
6166 of @code{prefix} when you ran the @file{configure} script.
6168 Other prefixes specified with @samp{-B} take precedence over this prefix.
6170 This prefix is also used for finding files such as @file{crt0.o} that are
6173 In addition, the prefix is used in an unusual way in finding the
6174 directories to search for header files. For each of the standard
6175 directories whose name normally begins with @samp{/usr/local/lib/gcc-lib}
6176 (more precisely, with the value of @code{GCC_INCLUDE_DIR}), GNU CC tries
6177 replacing that beginning with the specified prefix to produce an
6178 alternate directory name. Thus, with @samp{-Bfoo/}, GNU CC will search
6179 @file{foo/bar} where it would normally search @file{/usr/local/lib/bar}.
6180 These alternate directories are searched first; the standard directories
6184 @findex COMPILER_PATH
6185 The value of @code{COMPILER_PATH} is a colon-separated list of
6186 directories, much like @code{PATH}. GNU CC tries the directories thus
6187 specified when searching for subprograms, if it can't find the
6188 subprograms using @code{GCC_EXEC_PREFIX}.
6191 @findex LIBRARY_PATH
6192 The value of @code{LIBRARY_PATH} is a colon-separated list of
6193 directories, much like @code{PATH}. When configured as a native compiler,
6194 GNU CC tries the directories thus specified when searching for special
6195 linker files, if it can't find them using @code{GCC_EXEC_PREFIX}. Linking
6196 using GNU CC also uses these directories when searching for ordinary
6197 libraries for the @samp{-l} option (but directories specified with
6198 @samp{-L} come first).
6200 @item C_INCLUDE_PATH
6201 @itemx CPLUS_INCLUDE_PATH
6202 @itemx OBJC_INCLUDE_PATH
6203 @findex C_INCLUDE_PATH
6204 @findex CPLUS_INCLUDE_PATH
6205 @findex OBJC_INCLUDE_PATH
6206 @c @itemx OBJCPLUS_INCLUDE_PATH
6207 These environment variables pertain to particular languages. Each
6208 variable's value is a colon-separated list of directories, much like
6209 @code{PATH}. When GNU CC searches for header files, it tries the
6210 directories listed in the variable for the language you are using, after
6211 the directories specified with @samp{-I} but before the standard header
6214 @item DEPENDENCIES_OUTPUT
6215 @findex DEPENDENCIES_OUTPUT
6216 @cindex dependencies for make as output
6217 If this variable is set, its value specifies how to output dependencies
6218 for Make based on the header files processed by the compiler. This
6219 output looks much like the output from the @samp{-M} option
6220 (@pxref{Preprocessor Options}), but it goes to a separate file, and is
6221 in addition to the usual results of compilation.
6223 The value of @code{DEPENDENCIES_OUTPUT} can be just a file name, in
6224 which case the Make rules are written to that file, guessing the target
6225 name from the source file name. Or the value can have the form
6226 @samp{@var{file} @var{target}}, in which case the rules are written to
6227 file @var{file} using @var{target} as the target name.
6231 @cindex locale definition
6232 This variable is used to pass locale information to the compiler. One way in
6233 which this information is used is to determine the character set to be used
6234 when character literals, string literals and comments are parsed in C and C++.
6235 When the compiler is configured to allow multibyte characters,
6236 the following values for @code{LANG} are recognized:
6240 Recognize JIS characters.
6242 Recognize SJIS characters.
6244 Recognize EUCJP characters.
6247 If @code{LANG} is not defined, or if it has some other value, then the
6248 compiler will use mblen and mbtowc as defined by the default locale to
6249 recognize and translate multibyte characters.
6252 @node Running Protoize
6253 @section Running Protoize
6255 The program @code{protoize} is an optional part of GNU C. You can use
6256 it to add prototypes to a program, thus converting the program to ANSI
6257 C in one respect. The companion program @code{unprotoize} does the
6258 reverse: it removes argument types from any prototypes that are found.
6260 When you run these programs, you must specify a set of source files as
6261 command line arguments. The conversion programs start out by compiling
6262 these files to see what functions they define. The information gathered
6263 about a file @var{foo} is saved in a file named @file{@var{foo}.X}.
6265 After scanning comes actual conversion. The specified files are all
6266 eligible to be converted; any files they include (whether sources or
6267 just headers) are eligible as well.
6269 But not all the eligible files are converted. By default,
6270 @code{protoize} and @code{unprotoize} convert only source and header
6271 files in the current directory. You can specify additional directories
6272 whose files should be converted with the @samp{-d @var{directory}}
6273 option. You can also specify particular files to exclude with the
6274 @samp{-x @var{file}} option. A file is converted if it is eligible, its
6275 directory name matches one of the specified directory names, and its
6276 name within the directory has not been excluded.
6278 Basic conversion with @code{protoize} consists of rewriting most
6279 function definitions and function declarations to specify the types of
6280 the arguments. The only ones not rewritten are those for varargs
6283 @code{protoize} optionally inserts prototype declarations at the
6284 beginning of the source file, to make them available for any calls that
6285 precede the function's definition. Or it can insert prototype
6286 declarations with block scope in the blocks where undeclared functions
6289 Basic conversion with @code{unprotoize} consists of rewriting most
6290 function declarations to remove any argument types, and rewriting
6291 function definitions to the old-style pre-ANSI form.
6293 Both conversion programs print a warning for any function declaration or
6294 definition that they can't convert. You can suppress these warnings
6297 The output from @code{protoize} or @code{unprotoize} replaces the
6298 original source file. The original file is renamed to a name ending
6299 with @samp{.save}. If the @samp{.save} file already exists, then
6300 the source file is simply discarded.
6302 @code{protoize} and @code{unprotoize} both depend on GNU CC itself to
6303 scan the program and collect information about the functions it uses.
6304 So neither of these programs will work until GNU CC is installed.
6306 Here is a table of the options you can use with @code{protoize} and
6307 @code{unprotoize}. Each option works with both programs unless
6311 @item -B @var{directory}
6312 Look for the file @file{SYSCALLS.c.X} in @var{directory}, instead of the
6313 usual directory (normally @file{/usr/local/lib}). This file contains
6314 prototype information about standard system functions. This option
6315 applies only to @code{protoize}.
6317 @item -c @var{compilation-options}
6318 Use @var{compilation-options} as the options when running @code{gcc} to
6319 produce the @samp{.X} files. The special option @samp{-aux-info} is
6320 always passed in addition, to tell @code{gcc} to write a @samp{.X} file.
6322 Note that the compilation options must be given as a single argument to
6323 @code{protoize} or @code{unprotoize}. If you want to specify several
6324 @code{gcc} options, you must quote the entire set of compilation options
6325 to make them a single word in the shell.
6327 There are certain @code{gcc} arguments that you cannot use, because they
6328 would produce the wrong kind of output. These include @samp{-g},
6329 @samp{-O}, @samp{-c}, @samp{-S}, and @samp{-o} If you include these in
6330 the @var{compilation-options}, they are ignored.
6333 Rename files to end in @samp{.C} instead of @samp{.c}.
6334 This is convenient if you are converting a C program to C++.
6335 This option applies only to @code{protoize}.
6338 Add explicit global declarations. This means inserting explicit
6339 declarations at the beginning of each source file for each function
6340 that is called in the file and was not declared. These declarations
6341 precede the first function definition that contains a call to an
6342 undeclared function. This option applies only to @code{protoize}.
6344 @item -i @var{string}
6345 Indent old-style parameter declarations with the string @var{string}.
6346 This option applies only to @code{protoize}.
6348 @code{unprotoize} converts prototyped function definitions to old-style
6349 function definitions, where the arguments are declared between the
6350 argument list and the initial @samp{@{}. By default, @code{unprotoize}
6351 uses five spaces as the indentation. If you want to indent with just
6352 one space instead, use @samp{-i " "}.
6355 Keep the @samp{.X} files. Normally, they are deleted after conversion
6359 Add explicit local declarations. @code{protoize} with @samp{-l} inserts
6360 a prototype declaration for each function in each block which calls the
6361 function without any declaration. This option applies only to
6365 Make no real changes. This mode just prints information about the conversions
6366 that would have been done without @samp{-n}.
6369 Make no @samp{.save} files. The original files are simply deleted.
6370 Use this option with caution.
6372 @item -p @var{program}
6373 Use the program @var{program} as the compiler. Normally, the name
6377 Work quietly. Most warnings are suppressed.
6380 Print the version number, just like @samp{-v} for @code{gcc}.
6383 If you need special compiler options to compile one of your program's
6384 source files, then you should generate that file's @samp{.X} file
6385 specially, by running @code{gcc} on that source file with the
6386 appropriate options and the option @samp{-aux-info}. Then run
6387 @code{protoize} on the entire set of files. @code{protoize} will use
6388 the existing @samp{.X} file because it is newer than the source file.
6392 gcc -Dfoo=bar file1.c -aux-info
6397 You need to include the special files along with the rest in the
6398 @code{protoize} command, even though their @samp{.X} files already
6399 exist, because otherwise they won't get converted.
6401 @xref{Protoize Caveats}, for more information on how to use
6402 @code{protoize} successfully.