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 -x @var{language}
93 @item C Language Options
94 @xref{C Dialect Options,,Options Controlling C Dialect}.
96 -ansi -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 @item Code Generation Options
399 @xref{Code Gen Options,,Options for Code Generation Conventions}.
401 -fcall-saved-@var{reg} -fcall-used-@var{reg}
402 -fexceptions -ffixed-@var{reg} -finhibit-size-directive
403 -fcheck-memory-usage -fprefix-function-name
404 -fno-common -fno-ident -fno-gnu-linker
405 -fpcc-struct-return -fpic -fPIC
406 -freg-struct-return -fshared-data -fshort-enums
407 -fshort-double -fvolatile -fvolatile-global
408 -fverbose-asm -fpack-struct -fstack-check
409 -fargument-alias -fargument-noalias
410 -fargument-noalias-global
415 * Overall Options:: Controlling the kind of output:
416 an executable, object files, assembler files,
417 or preprocessed source.
418 * C Dialect Options:: Controlling the variant of C language compiled.
419 * C++ Dialect Options:: Variations on C++.
420 * Warning Options:: How picky should the compiler be?
421 * Debugging Options:: Symbol tables, measurements, and debugging dumps.
422 * Optimize Options:: How much optimization?
423 * Preprocessor Options:: Controlling header files and macro definitions.
424 Also, getting dependency information for Make.
425 * Assembler Options:: Passing options to the assembler.
426 * Link Options:: Specifying libraries and so on.
427 * Directory Options:: Where to find header files and libraries.
428 Where to find the compiler executable files.
429 * Target Options:: Running a cross-compiler, or an old version of GNU CC.
432 @node Overall Options
433 @section Options Controlling the Kind of Output
435 Compilation can involve up to four stages: preprocessing, compilation
436 proper, assembly and linking, always in that order. The first three
437 stages apply to an individual source file, and end by producing an
438 object file; linking combines all the object files (those newly
439 compiled, and those specified as input) into an executable file.
441 @cindex file name suffix
442 For any given input file, the file name suffix determines what kind of
447 C source code which must be preprocessed.
450 C source code which should not be preprocessed.
453 C++ source code which should not be preprocessed.
456 Objective-C source code. Note that you must link with the library
457 @file{libobjc.a} to make an Objective-C program work.
460 C header file (not to be compiled or linked).
463 @itemx @var{file}.cxx
464 @itemx @var{file}.cpp
466 C++ source code which must be preprocessed. Note that in @samp{.cxx},
467 the last two letters must both be literally @samp{x}. Likewise,
468 @samp{.C} refers to a literal capital C.
474 Assembler code which must be preprocessed.
477 An object file to be fed straight into linking.
478 Any file name with no recognized suffix is treated this way.
481 You can specify the input language explicitly with the @samp{-x} option:
484 @item -x @var{language}
485 Specify explicitly the @var{language} for the following input files
486 (rather than letting the compiler choose a default based on the file
487 name suffix). This option applies to all following input files until
488 the next @samp{-x} option. Possible values for @var{language} are:
491 c-header cpp-output c++-cpp-output
492 assembler assembler-with-cpp
496 Turn off any specification of a language, so that subsequent files are
497 handled according to their file name suffixes (as they are if @samp{-x}
498 has not been used at all).
501 If you only want some of the stages of compilation, you can use
502 @samp{-x} (or filename suffixes) to tell @code{gcc} where to start, and
503 one of the options @samp{-c}, @samp{-S}, or @samp{-E} to say where
504 @code{gcc} is to stop. Note that some combinations (for example,
505 @samp{-x cpp-output -E} instruct @code{gcc} to do nothing at all.
509 Compile or assemble the source files, but do not link. The linking
510 stage simply is not done. The ultimate output is in the form of an
511 object file for each source file.
513 By default, the object file name for a source file is made by replacing
514 the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}.
516 Unrecognized input files, not requiring compilation or assembly, are
520 Stop after the stage of compilation proper; do not assemble. The output
521 is in the form of an assembler code file for each non-assembler input
524 By default, the assembler file name for a source file is made by
525 replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}.
527 Input files that don't require compilation are ignored.
530 Stop after the preprocessing stage; do not run the compiler proper. The
531 output is in the form of preprocessed source code, which is sent to the
534 Input files which don't require preprocessing are ignored.
536 @cindex output file option
538 Place output in file @var{file}. This applies regardless to whatever
539 sort of output is being produced, whether it be an executable file,
540 an object file, an assembler file or preprocessed C code.
542 Since only one output file can be specified, it does not make sense to
543 use @samp{-o} when compiling more than one input file, unless you are
544 producing an executable file as output.
546 If @samp{-o} is not specified, the default is to put an executable file
547 in @file{a.out}, the object file for @file{@var{source}.@var{suffix}} in
548 @file{@var{source}.o}, its assembler file in @file{@var{source}.s}, and
549 all preprocessed C source on standard output.@refill
552 Print (on standard error output) the commands executed to run the stages
553 of compilation. Also print the version number of the compiler driver
554 program and of the preprocessor and the compiler proper.
557 Use pipes rather than temporary files for communication between the
558 various stages of compilation. This fails to work on some systems where
559 the assembler is unable to read from a pipe; but the GNU assembler has
564 @section Compiling C++ Programs
566 @cindex suffixes for C++ source
567 @cindex C++ source file suffixes
568 C++ source files conventionally use one of the suffixes @samp{.C},
569 @samp{.cc}, @samp{cpp}, or @samp{.cxx}; preprocessed C++ files use the
570 suffix @samp{.ii}. GNU CC recognizes files with these names and
571 compiles them as C++ programs even if you call the compiler the same way
572 as for compiling C programs (usually with the name @code{gcc}).
576 However, C++ programs often require class libraries as well as a
577 compiler that understands the C++ language---and under some
578 circumstances, you might want to compile programs from standard input,
579 or otherwise without a suffix that flags them as C++ programs.
580 @code{g++} is a program that calls GNU CC with the default language
581 set to C++, and automatically specifies linking against the C++
583 @cindex @code{g++ 1.@var{xx}}
584 @cindex @code{g++}, separate compiler
585 @cindex @code{g++} older version
586 @footnote{Prior to release 2 of the compiler,
587 there was a separate @code{g++} compiler. That version was based on GNU
588 CC, but not integrated with it. Versions of @code{g++} with a
589 @samp{1.@var{xx}} version number---for example, @code{g++} version 1.37
590 or 1.42---are much less reliable than the versions integrated with GCC
591 2. Moreover, combining G++ @samp{1.@var{xx}} with a version 2 GCC will
592 simply not work.} On many systems, the script @code{g++} is also
593 installed with the name @code{c++}.
595 @cindex invoking @code{g++}
596 When you compile C++ programs, you may specify many of the same
597 command-line options that you use for compiling programs in any
598 language; or command-line options meaningful for C and related
599 languages; or options that are meaningful only for C++ programs.
600 @xref{C Dialect Options,,Options Controlling C Dialect}, for
601 explanations of options for languages related to C.
602 @xref{C++ Dialect Options,,Options Controlling C++ Dialect}, for
603 explanations of options that are meaningful only for C++ programs.
605 @node C Dialect Options
606 @section Options Controlling C Dialect
607 @cindex dialect options
608 @cindex language dialect options
609 @cindex options, dialect
611 The following options control the dialect of C (or languages derived
612 from C, such as C++ and Objective C) that the compiler accepts:
617 Support all ANSI standard C programs.
619 This turns off certain features of GNU C that are incompatible with ANSI
620 C, such as the @code{asm}, @code{inline} and @code{typeof} keywords, and
621 predefined macros such as @code{unix} and @code{vax} that identify the
622 type of system you are using. It also enables the undesirable and
623 rarely used ANSI trigraph feature, and it disables recognition of C++
624 style @samp{//} comments.
626 The alternate keywords @code{__asm__}, @code{__extension__},
627 @code{__inline__} and @code{__typeof__} continue to work despite
628 @samp{-ansi}. You would not want to use them in an ANSI C program, of
629 course, but it is useful to put them in header files that might be included
630 in compilations done with @samp{-ansi}. Alternate predefined macros
631 such as @code{__unix__} and @code{__vax__} are also available, with or
632 without @samp{-ansi}.
634 The @samp{-ansi} option does not cause non-ANSI programs to be
635 rejected gratuitously. For that, @samp{-pedantic} is required in
636 addition to @samp{-ansi}. @xref{Warning Options}.
638 The macro @code{__STRICT_ANSI__} is predefined when the @samp{-ansi}
639 option is used. Some header files may notice this macro and refrain
640 from declaring certain functions or defining certain macros that the
641 ANSI standard doesn't call for; this is to avoid interfering with any
642 programs that might use these names for other things.
644 The functions @code{alloca}, @code{abort}, @code{exit}, and
645 @code{_exit} are not builtin functions when @samp{-ansi} is used.
648 Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
649 keyword, so that code can use these words as identifiers. You can use
650 the keywords @code{__asm__}, @code{__inline__} and @code{__typeof__}
651 instead. @samp{-ansi} implies @samp{-fno-asm}.
653 In C++, this switch only affects the @code{typeof} keyword, since
654 @code{asm} and @code{inline} are standard keywords. You may want to
655 use the @samp{-fno-gnu-keywords} flag instead, as it also disables the
656 other, C++-specific, extension keywords such as @code{headof}.
659 @cindex builtin functions
675 Don't recognize builtin functions that do not begin with `__builtin_'
676 as prefix. Currently, the functions affected include @code{abort},
677 @code{abs}, @code{alloca}, @code{cos}, @code{exit}, @code{fabs},
678 @code{ffs}, @code{labs}, @code{memcmp}, @code{memcpy}, @code{sin},
679 @code{sqrt}, @code{strcmp}, @code{strcpy}, and @code{strlen}.
681 GCC normally generates special code to handle certain builtin functions
682 more efficiently; for instance, calls to @code{alloca} may become single
683 instructions that adjust the stack directly, and calls to @code{memcpy}
684 may become inline copy loops. The resulting code is often both smaller
685 and faster, but since the function calls no longer appear as such, you
686 cannot set a breakpoint on those calls, nor can you change the behavior
687 of the functions by linking with a different library.
689 The @samp{-ansi} option prevents @code{alloca} and @code{ffs} from being
690 builtin functions, since these functions do not have an ANSI standard
694 @cindex hosted environment
696 Assert that compilation takes place in a hosted environment. This implies
697 @samp{-fbuiltin}. A hosted environment is one in which the
698 entire standard library is available, and in which @code{main} has a return
699 type of @code{int}. Examples are nearly everything except a kernel.
700 This is equivalent to @samp{-fno-freestanding}.
703 @cindex hosted environment
705 Assert that compilation takes place in a freestanding environment. This
706 implies @samp{-fno-builtin}. A freestanding environment
707 is one in which the standard library may not exist, and program startup may
708 not necessarily be at @code{main}. The most obvious example is an OS kernel.
709 This is equivalent to @samp{-fno-hosted}.
712 Support ANSI C trigraphs. You don't want to know about this
713 brain-damage. The @samp{-ansi} option implies @samp{-trigraphs}.
715 @cindex traditional C language
716 @cindex C language, traditional
718 Attempt to support some aspects of traditional C compilers.
723 All @code{extern} declarations take effect globally even if they
724 are written inside of a function definition. This includes implicit
725 declarations of functions.
728 The newer keywords @code{typeof}, @code{inline}, @code{signed}, @code{const}
729 and @code{volatile} are not recognized. (You can still use the
730 alternative keywords such as @code{__typeof__}, @code{__inline__}, and
734 Comparisons between pointers and integers are always allowed.
737 Integer types @code{unsigned short} and @code{unsigned char} promote
738 to @code{unsigned int}.
741 Out-of-range floating point literals are not an error.
744 Certain constructs which ANSI regards as a single invalid preprocessing
745 number, such as @samp{0xe-0xd}, are treated as expressions instead.
748 String ``constants'' are not necessarily constant; they are stored in
749 writable space, and identical looking constants are allocated
750 separately. (This is the same as the effect of
751 @samp{-fwritable-strings}.)
753 @cindex @code{longjmp} and automatic variables
755 All automatic variables not declared @code{register} are preserved by
756 @code{longjmp}. Ordinarily, GNU C follows ANSI C: automatic variables
757 not declared @code{volatile} may be clobbered.
762 @cindex escape sequences, traditional
763 The character escape sequences @samp{\x} and @samp{\a} evaluate as the
764 literal characters @samp{x} and @samp{a} respectively. Without
765 @w{@samp{-traditional}}, @samp{\x} is a prefix for the hexadecimal
766 representation of a character, and @samp{\a} produces a bell.
769 You may wish to use @samp{-fno-builtin} as well as @samp{-traditional}
770 if your program uses names that are normally GNU C builtin functions for
771 other purposes of its own.
773 You cannot use @samp{-traditional} if you include any header files that
774 rely on ANSI C features. Some vendors are starting to ship systems with
775 ANSI C header files and you cannot use @samp{-traditional} on such
776 systems to compile files that include any system headers.
778 The @samp{-traditional} option also enables @samp{-traditional-cpp},
779 which is described next.
781 @item -traditional-cpp
782 Attempt to support some aspects of traditional C preprocessors.
787 Comments convert to nothing at all, rather than to a space. This allows
788 traditional token concatenation.
791 In a preprocessing directive, the @samp{#} symbol must appear as the first
795 Macro arguments are recognized within string constants in a macro
796 definition (and their values are stringified, though without additional
797 quote marks, when they appear in such a context). The preprocessor
798 always considers a string constant to end at a newline.
801 @cindex detecting @w{@samp{-traditional}}
802 The predefined macro @code{__STDC__} is not defined when you use
803 @samp{-traditional}, but @code{__GNUC__} is (since the GNU extensions
804 which @code{__GNUC__} indicates are not affected by
805 @samp{-traditional}). If you need to write header files that work
806 differently depending on whether @samp{-traditional} is in use, by
807 testing both of these predefined macros you can distinguish four
808 situations: GNU C, traditional GNU C, other ANSI C compilers, and other
809 old C compilers. The predefined macro @code{__STDC_VERSION__} is also
810 not defined when you use @samp{-traditional}. @xref{Standard
811 Predefined,,Standard Predefined Macros,cpp.info,The C Preprocessor},
812 for more discussion of these and other predefined macros.
815 @cindex string constants vs newline
816 @cindex newline vs string constants
817 The preprocessor considers a string constant to end at a newline (unless
818 the newline is escaped with @samp{\}). (Without @w{@samp{-traditional}},
819 string constants can contain the newline character as typed.)
822 @item -fcond-mismatch
823 Allow conditional expressions with mismatched types in the second and
824 third arguments. The value of such an expression is void.
826 @item -funsigned-char
827 Let the type @code{char} be unsigned, like @code{unsigned char}.
829 Each kind of machine has a default for what @code{char} should
830 be. It is either like @code{unsigned char} by default or like
831 @code{signed char} by default.
833 Ideally, a portable program should always use @code{signed char} or
834 @code{unsigned char} when it depends on the signedness of an object.
835 But many programs have been written to use plain @code{char} and
836 expect it to be signed, or expect it to be unsigned, depending on the
837 machines they were written for. This option, and its inverse, let you
838 make such a program work with the opposite default.
840 The type @code{char} is always a distinct type from each of
841 @code{signed char} or @code{unsigned char}, even though its behavior
842 is always just like one of those two.
845 Let the type @code{char} be signed, like @code{signed char}.
847 Note that this is equivalent to @samp{-fno-unsigned-char}, which is
848 the negative form of @samp{-funsigned-char}. Likewise, the option
849 @samp{-fno-signed-char} is equivalent to @samp{-funsigned-char}.
851 You may wish to use @samp{-fno-builtin} as well as @samp{-traditional}
852 if your program uses names that are normally GNU C builtin functions for
853 other purposes of its own.
855 You cannot use @samp{-traditional} if you include any header files that
856 rely on ANSI C features. Some vendors are starting to ship systems with
857 ANSI C header files and you cannot use @samp{-traditional} on such
858 systems to compile files that include any system headers.
860 @item -fsigned-bitfields
861 @itemx -funsigned-bitfields
862 @itemx -fno-signed-bitfields
863 @itemx -fno-unsigned-bitfields
864 These options control whether a bitfield is signed or unsigned, when the
865 declaration does not use either @code{signed} or @code{unsigned}. By
866 default, such a bitfield is signed, because this is consistent: the
867 basic integer types such as @code{int} are signed types.
869 However, when @samp{-traditional} is used, bitfields are all unsigned
872 @item -fwritable-strings
873 Store string constants in the writable data segment and don't uniquize
874 them. This is for compatibility with old programs which assume they can
875 write into string constants. The option @samp{-traditional} also has
878 Writing into string constants is a very bad idea; ``constants'' should
881 @item -fallow-single-precision
882 Do not promote single precision math operations to double precision,
883 even when compiling with @samp{-traditional}.
885 Traditional K&R C promotes all floating point operations to double
886 precision, regardless of the sizes of the operands. On the
887 architecture for which you are compiling, single precision may be faster
888 than double precision. If you must use @samp{-traditional}, but want
889 to use single precision operations when the operands are single
890 precision, use this option. This option has no effect when compiling
891 with ANSI or GNU C conventions (the default).
895 @node C++ Dialect Options
896 @section Options Controlling C++ Dialect
898 @cindex compiler options, C++
899 @cindex C++ options, command line
901 This section describes the command-line options that are only meaningful
902 for C++ programs; but you can also use most of the GNU compiler options
903 regardless of what language your program is in. For example, you
904 might compile a file @code{firstClass.C} like this:
907 g++ -g -frepo -O -c firstClass.C
911 In this example, only @samp{-frepo} is an option meant
912 only for C++ programs; you can use the other options with any
913 language supported by GNU CC.
915 Here is a list of options that are @emph{only} for compiling C++ programs:
918 @item -fno-access-control
919 Turn off all access checking. This switch is mainly useful for working
920 around bugs in the access control code.
923 Check that the pointer returned by @code{operator new} is non-null
924 before attempting to modify the storage allocated. The current Working
925 Paper requires that @code{operator new} never return a null pointer, so
926 this check is normally unnecessary.
928 An alternative to using this option is to specify that your
929 @code{operator new} does not throw any exceptions; if you declare it
930 @samp{throw()}, g++ will check the return value. See also @samp{new
933 @item -fconserve-space
934 Put uninitialized or runtime-initialized global variables into the
935 common segment, as C does. This saves space in the executable at the
936 cost of not diagnosing duplicate definitions. If you compile with this
937 flag and your program mysteriously crashes after @code{main()} has
938 completed, you may have an object that is being destroyed twice because
939 two definitions were merged.
941 This option is no longer useful on most targets, now that support has
942 been added for putting variables into BSS without making them common.
944 @item -fdollars-in-identifiers
945 Accept @samp{$} in identifiers. You can also explicitly prohibit use of
946 @samp{$} with the option @samp{-fno-dollars-in-identifiers}. (GNU C allows
947 @samp{$} by default on most target systems, but there are a few exceptions.)
948 Traditional C allowed the character @samp{$} to form part of
949 identifiers. However, ANSI C and C++ forbid @samp{$} in identifiers.
951 @item -fno-elide-constructors
952 The C++ standard allows an implementation to omit creating a temporary
953 which is only used to initialize another object of the same type.
954 Specifying this option disables that optimization, and forces g++ to
955 call the copy constructor in all cases.
957 @item -fexternal-templates
958 Cause template instantiations to obey @samp{#pragma interface} and
959 @samp{implementation}; template instances are emitted or not according
960 to the location of the template definition. @xref{Template
961 Instantiation}, for more information.
963 This option is deprecated.
965 @item -falt-external-templates
966 Similar to -fexternal-templates, but template instances are emitted or
967 not according to the place where they are first instantiated.
968 @xref{Template Instantiation}, for more information.
970 This option is deprecated.
973 @itemx -fno-for-scope
974 If -ffor-scope is specified, the scope of variables declared in
975 a @i{for-init-statement} is limited to the @samp{for} loop itself,
976 as specified by the draft C++ standard.
977 If -fno-for-scope is specified, the scope of variables declared in
978 a @i{for-init-statement} extends to the end of the enclosing scope,
979 as was the case in old versions of gcc, and other (traditional)
980 implementations of C++.
982 The default if neither flag is given to follow the standard,
983 but to allow and give a warning for old-style code that would
984 otherwise be invalid, or have different behavior.
986 @item -fno-gnu-keywords
987 Do not recognize @code{classof}, @code{headof}, @code{signature},
988 @code{sigof} or @code{typeof} as a keyword, so that code can use these
989 words as identifiers. You can use the keywords @code{__classof__},
990 @code{__headof__}, @code{__signature__}, @code{__sigof__}, and
991 @code{__typeof__} instead. @samp{-ansi} implies
992 @samp{-fno-gnu-keywords}.
994 @item -fguiding-decls
995 Treat a function declaration with the same type as a potential function
996 template instantiation as though it declares that instantiation, not a
997 normal function. If a definition is given for the function later in the
998 translation unit (or another translation unit if the target supports
999 weak symbols), that definition will be used; otherwise the template will
1000 be instantiated. This behavior reflects the C++ language prior to
1001 September 1996, when guiding declarations were removed.
1003 This option implies @samp{-fname-mangling-version-0}, and will not work
1004 with other name mangling versions. Like all options that change the
1005 ABI, all C++ code, @emph{including libgcc.a} must be built with the same
1006 setting of this option.
1008 @item -fhandle-signatures
1009 Recognize the @code{signature} and @code{sigof} keywords for specifying
1010 abstract types. The default (@samp{-fno-handle-signatures}) is not to
1011 recognize them. @xref{C++ Signatures, Type Abstraction using
1015 Treat the @code{namespace std} as a namespace, instead of ignoring
1016 it. For compatibility with earlier versions of g++, the compiler will,
1017 by default, ignore @code{namespace-declarations},
1018 @code{using-declarations}, @code{using-directives}, and
1019 @code{namespace-names}, if they involve @code{std}.
1021 @item -fhuge-objects
1022 Support virtual function calls for objects that exceed the size
1023 representable by a @samp{short int}. Users should not use this flag by
1024 default; if you need to use it, the compiler will tell you so.
1026 This flag is not useful when compiling with -fvtable-thunks.
1028 Like all options that change the ABI, all C++ code, @emph{including
1029 libgcc} must be built with the same setting of this option.
1031 @item -fno-implicit-templates
1032 Never emit code for templates which are instantiated implicitly (i.e. by
1033 use); only emit code for explicit instantiations. @xref{Template
1034 Instantiation}, for more information.
1036 @item -finit-priority
1037 Support @samp{__attribute__ ((init_priority (n)))} for controlling the
1038 order of initialization of file-scope objects. On ELF targets, this
1039 requires GNU ld 2.10 or later.
1041 @item -fno-implement-inlines
1042 To save space, do not emit out-of-line copies of inline functions
1043 controlled by @samp{#pragma implementation}. This will cause linker
1044 errors if these functions are not inlined everywhere they are called.
1046 @item -fname-mangling-version-@var{n}
1047 Control the way in which names are mangled. Version 0 is compatible
1048 with versions of g++ before 2.8. Version 1 is the default. Version 1
1049 will allow correct mangling of function templates. For example,
1050 version 0 mangling does not mangle foo<int, double> and foo<int, char>
1051 given this declaration:
1054 template <class T, class U> void foo(T t);
1057 @item -foperator-names
1058 Recognize the operator name keywords @code{and}, @code{bitand},
1059 @code{bitor}, @code{compl}, @code{not}, @code{or} and @code{xor} as
1060 synonyms for the symbols they refer to. @samp{-ansi} implies
1061 @samp{-foperator-names}.
1063 @item -fno-optional-diags
1064 Disable diagnostics that the standard says a compiler does not need to
1065 issue. Currently, this means the diagnostic for a name having multiple
1066 meanings within a class.
1069 Enable automatic template instantiation. This option also implies
1070 @samp{-fno-implicit-templates}. @xref{Template Instantiation}, for more
1073 @item -fstrict-prototype
1074 Within an @samp{extern "C"} linkage specification, treat a function
1075 declaration with no arguments, such as @samp{int foo ();}, as declaring
1076 the function to take no arguments. Normally, such a declaration means
1077 that the function @code{foo} can take any combination of arguments, as
1078 in C. @samp{-pedantic} implies @samp{-fstrict-prototype} unless
1079 overridden with @samp{-fno-strict-prototype}.
1081 Specifying this option will also suppress implicit declarations of
1084 This flag no longer affects declarations with C++ linkage.
1087 @itemx -fno-squangle
1088 @samp{-fsquangle} will enable a compressed form of name mangling for
1089 identifiers. In particular, it helps to shorten very long names by recognizing
1090 types and class names which occur more than once, replacing them with special
1091 short ID codes. This option also requires any C++ libraries being used to
1092 be compiled with this option as well. The compiler has this disabled (the
1093 equivalent of @samp{-fno-squangle}) by default.
1095 Like all options that change the ABI, all C++ code, @emph{including
1096 libgcc.a} must be built with the same setting of this option.
1098 @item -ftemplate-depth-@var{n}
1099 Set the maximum instantiation depth for template classes to @var{n}.
1100 A limit on the template instantiation depth is needed to detect
1101 endless recursions during template class instantiation. ANSI/ISO C++
1102 conforming programs must not rely on a maximum depth greater than 17.
1104 @item -fthis-is-variable
1105 Permit assignment to @code{this}. The incorporation of user-defined
1106 free store management into C++ has made assignment to @samp{this} an
1107 anachronism. Therefore, by default it is invalid to assign to
1108 @code{this} within a class member function; that is, GNU C++ treats
1109 @samp{this} in a member function of class @code{X} as a non-lvalue of
1110 type @samp{X *}. However, for backwards compatibility, you can make it
1111 valid with @samp{-fthis-is-variable}.
1113 @item -fvtable-thunks
1114 Use @samp{thunks} to implement the virtual function dispatch table
1115 (@samp{vtable}). The traditional (cfront-style) approach to
1116 implementing vtables was to store a pointer to the function and two
1117 offsets for adjusting the @samp{this} pointer at the call site. Newer
1118 implementations store a single pointer to a @samp{thunk} function which
1119 does any necessary adjustment and then calls the target function.
1121 Like all options that change the ABI, all C++ code, @emph{including
1122 libgcc.a} must be built with the same setting of this option.
1125 Do not search for header files in the standard directories specific to
1126 C++, but do still search the other standard directories. (This option
1127 is used when building the C++ library.)
1130 In addition, these optimization, warning, and code generation options
1131 have meanings only for C++ programs:
1134 @item -fno-default-inline
1135 Do not assume @samp{inline} for functions defined inside a class scope.
1136 @xref{Optimize Options,,Options That Control Optimization}. Note that these
1137 functions will have linkage like inline functions; they just won't be
1140 @item -Wno-non-template-friend
1141 @xref{Warning Options,,Options to Request or Suppress Warnings}.
1142 @item -Wold-style-cast
1143 @itemx -Woverloaded-virtual
1144 Warnings that apply only to C++ programs. @xref{Warning
1145 Options,,Options to Request or Suppress Warnings}.
1148 Warn about violation of some style rules from Effective C++ by Scott Myers.
1151 @node Warning Options
1152 @section Options to Request or Suppress Warnings
1153 @cindex options to control warnings
1154 @cindex warning messages
1155 @cindex messages, warning
1156 @cindex suppressing warnings
1158 Warnings are diagnostic messages that report constructions which
1159 are not inherently erroneous but which are risky or suggest there
1160 may have been an error.
1162 You can request many specific warnings with options beginning @samp{-W},
1163 for example @samp{-Wimplicit} to request warnings on implicit
1164 declarations. Each of these specific warning options also has a
1165 negative form beginning @samp{-Wno-} to turn off warnings;
1166 for example, @samp{-Wno-implicit}. This manual lists only one of the
1167 two forms, whichever is not the default.
1169 These options control the amount and kinds of warnings produced by GNU
1173 @cindex syntax checking
1175 Check the code for syntax errors, but don't do anything beyond that.
1178 Issue all the warnings demanded by strict ANSI C and ISO C++;
1179 reject all programs that use forbidden extensions.
1181 Valid ANSI C and ISO C++ programs should compile properly with or without
1182 this option (though a rare few will require @samp{-ansi}). However,
1183 without this option, certain GNU extensions and traditional C and C++
1184 features are supported as well. With this option, they are rejected.
1186 @samp{-pedantic} does not cause warning messages for use of the
1187 alternate keywords whose names begin and end with @samp{__}. Pedantic
1188 warnings are also disabled in the expression that follows
1189 @code{__extension__}. However, only system header files should use
1190 these escape routes; application programs should avoid them.
1191 @xref{Alternate Keywords}.
1193 This option is not intended to be @i{useful}; it exists only to satisfy
1194 pedants who would otherwise claim that GNU CC fails to support the ANSI
1197 Some users try to use @samp{-pedantic} to check programs for strict ANSI
1198 C conformance. They soon find that it does not do quite what they want:
1199 it finds some non-ANSI practices, but not all---only those for which
1200 ANSI C @emph{requires} a diagnostic.
1202 A feature to report any failure to conform to ANSI C might be useful in
1203 some instances, but would require considerable additional work and would
1204 be quite different from @samp{-pedantic}. We recommend, rather, that
1205 users take advantage of the extensions of GNU C and disregard the
1206 limitations of other compilers. Aside from certain supercomputers and
1207 obsolete small machines, there is less and less reason ever to use any
1208 other C compiler other than for bootstrapping GNU CC.
1210 @item -pedantic-errors
1211 Like @samp{-pedantic}, except that errors are produced rather than
1215 Inhibit all warning messages.
1218 Inhibit warning messages about the use of @samp{#import}.
1220 @item -Wchar-subscripts
1221 Warn if an array subscript has type @code{char}. This is a common cause
1222 of error, as programmers often forget that this type is signed on some
1226 Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
1227 comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
1230 Check calls to @code{printf} and @code{scanf}, etc., to make sure that
1231 the arguments supplied have types appropriate to the format string
1234 @item -Wimplicit-int
1235 Warn when a declaration does not specify a type.
1237 @item -Wimplicit-function-declaration
1238 @itemx -Werror-implicit-function-declaration
1239 Give a warning (or error) whenever a function is used before being
1243 Same as @samp{-Wimplicit-int} and @samp{-Wimplicit-function-}@*
1247 Warn if the type of @samp{main} is suspicious. @samp{main} should be a
1248 function with external linkage, returning int, taking either zero
1249 arguments, two, or three arguments of appropriate types.
1252 Warn if a multicharacter constant (@samp{'FOOF'}) is used. Usually they
1253 indicate a typo in the user's code, as they have implementation-defined
1254 values, and should not be used in portable code.
1257 Warn if parentheses are omitted in certain contexts, such
1258 as when there is an assignment in a context where a truth value
1259 is expected, or when operators are nested whose precedence people
1260 often get confused about.
1262 Also warn about constructions where there may be confusion to which
1263 @code{if} statement an @code{else} branch belongs. Here is an example of
1276 In C, every @code{else} branch belongs to the innermost possible @code{if}
1277 statement, which in this example is @code{if (b)}. This is often not
1278 what the programmer expected, as illustrated in the above example by
1279 indentation the programmer chose. When there is the potential for this
1280 confusion, GNU C will issue a warning when this flag is specified.
1281 To eliminate the warning, add explicit braces around the innermost
1282 @code{if} statement so there is no way the @code{else} could belong to
1283 the enclosing @code{if}. The resulting code would look like this:
1298 Warn whenever a function is defined with a return-type that defaults
1299 to @code{int}. Also warn about any @code{return} statement with no
1300 return-value in a function whose return-type is not @code{void}.
1303 Warn whenever a @code{switch} statement has an index of enumeral type
1304 and lacks a @code{case} for one or more of the named codes of that
1305 enumeration. (The presence of a @code{default} label prevents this
1306 warning.) @code{case} labels outside the enumeration range also
1307 provoke warnings when this option is used.
1310 Warn if any trigraphs are encountered (assuming they are enabled).
1313 Warn whenever a variable is unused aside from its declaration,
1314 whenever a function is declared static but never defined, whenever a
1315 label is declared but not used, and whenever a statement computes a
1316 result that is explicitly not used.
1318 In order to get a warning about an unused function parameter, you must
1319 specify both @samp{-W} and @samp{-Wunused}.
1321 To suppress this warning for an expression, simply cast it to void. For
1322 unused variables and parameters, use the @samp{unused} attribute
1323 (@pxref{Variable Attributes}).
1325 @item -Wuninitialized
1326 An automatic variable is used without first being initialized.
1328 These warnings are possible only in optimizing compilation,
1329 because they require data flow information that is computed only
1330 when optimizing. If you don't specify @samp{-O}, you simply won't
1333 These warnings occur only for variables that are candidates for
1334 register allocation. Therefore, they do not occur for a variable that
1335 is declared @code{volatile}, or whose address is taken, or whose size
1336 is other than 1, 2, 4 or 8 bytes. Also, they do not occur for
1337 structures, unions or arrays, even when they are in registers.
1339 Note that there may be no warning about a variable that is used only
1340 to compute a value that itself is never used, because such
1341 computations may be deleted by data flow analysis before the warnings
1344 These warnings are made optional because GNU CC is not smart
1345 enough to see all the reasons why the code might be correct
1346 despite appearing to have an error. Here is one example of how
1365 If the value of @code{y} is always 1, 2 or 3, then @code{x} is
1366 always initialized, but GNU CC doesn't know this. Here is
1367 another common case:
1372 if (change_y) save_y = y, y = new_y;
1374 if (change_y) y = save_y;
1379 This has no bug because @code{save_y} is used only if it is set.
1381 Some spurious warnings can be avoided if you declare all the functions
1382 you use that never return as @code{noreturn}. @xref{Function
1385 @item -Wreorder (C++ only)
1386 @cindex reordering, warning
1387 @cindex warning for reordering of member initializers
1388 Warn when the order of member initializers given in the code does not
1389 match the order in which they must be executed. For instance:
1395 A(): j (0), i (1) @{ @}
1399 Here the compiler will warn that the member initializers for @samp{i}
1400 and @samp{j} will be rearranged to match the declaration order of the
1403 @item -Wtemplate-debugging
1404 @cindex template debugging
1405 When using templates in a C++ program, warn if debugging is not yet
1406 fully available (C++ only).
1408 @item -Wunknown-pragmas
1409 @cindex warning for unknown pragmas
1410 @cindex unknown pragmas, warning
1411 @cindex pragmas, warning of unknown
1412 Warn when a #pragma directive is encountered which is not understood by
1413 GCC. If this command line option is used, warnings will even be issued
1414 for unknown pragmas in system header files. This is not the case if
1415 the warnings were only enabled by the @samp{-Wall} command line option.
1418 All of the above @samp{-W} options combined. This enables all the
1419 warnings about constructions that some users consider questionable, and
1420 that are easy to avoid (or modify to prevent the warning), even in
1421 conjunction with macros.
1424 The following @samp{-W@dots{}} options are not implied by @samp{-Wall}.
1425 Some of them warn about constructions that users generally do not
1426 consider questionable, but which occasionally you might wish to check
1427 for; others warn about constructions that are necessary or hard to avoid
1428 in some cases, and there is no simple way to modify the code to suppress
1433 Print extra warning messages for these events:
1436 @cindex @code{longjmp} warnings
1438 A nonvolatile automatic variable might be changed by a call to
1439 @code{longjmp}. These warnings as well are possible only in
1440 optimizing compilation.
1442 The compiler sees only the calls to @code{setjmp}. It cannot know
1443 where @code{longjmp} will be called; in fact, a signal handler could
1444 call it at any point in the code. As a result, you may get a warning
1445 even when there is in fact no problem because @code{longjmp} cannot
1446 in fact be called at the place which would cause a problem.
1449 A function can return either with or without a value. (Falling
1450 off the end of the function body is considered returning without
1451 a value.) For example, this function would evoke such a
1465 An expression-statement or the left-hand side of a comma expression
1466 contains no side effects.
1467 To suppress the warning, cast the unused expression to void.
1468 For example, an expression such as @samp{x[i,j]} will cause a warning,
1469 but @samp{x[(void)i,j]} will not.
1472 An unsigned value is compared against zero with @samp{<} or @samp{<=}.
1475 A comparison like @samp{x<=y<=z} appears; this is equivalent to
1476 @samp{(x<=y ? 1 : 0) <= z}, which is a different interpretation from
1477 that of ordinary mathematical notation.
1480 Storage-class specifiers like @code{static} are not the first things in
1481 a declaration. According to the C Standard, this usage is obsolescent.
1484 If @samp{-Wall} or @samp{-Wunused} is also specified, warn about unused
1488 A comparison between signed and unsigned values could produce an
1489 incorrect result when the signed value is converted to unsigned.
1490 (But don't warn if @samp{-Wno-sign-compare} is also specified.)
1493 An aggregate has a partly bracketed initializer.
1494 For example, the following code would evoke such a warning,
1495 because braces are missing around the initializer for @code{x.h}:
1498 struct s @{ int f, g; @};
1499 struct t @{ struct s h; int i; @};
1500 struct t x = @{ 1, 2, 3 @};
1504 An aggregate has an initializer which does not initialize all members.
1505 For example, the following code would cause such a warning, because
1506 @code{x.h} would be implicitly initialized to zero:
1509 struct s @{ int f, g, h; @};
1510 struct s x = @{ 3, 4 @};
1515 Warn about certain constructs that behave differently in traditional and
1520 Macro arguments occurring within string constants in the macro body.
1521 These would substitute the argument in traditional C, but are part of
1522 the constant in ANSI C.
1525 A function declared external in one block and then used after the end of
1529 A @code{switch} statement has an operand of type @code{long}.
1533 Warn if an undefined identifier is evaluated in an @samp{#if} directive.
1536 Warn whenever a local variable shadows another local variable.
1538 @item -Wid-clash-@var{len}
1539 Warn whenever two distinct identifiers match in the first @var{len}
1540 characters. This may help you prepare a program that will compile
1541 with certain obsolete, brain-damaged compilers.
1543 @item -Wlarger-than-@var{len}
1544 Warn whenever an object of larger than @var{len} bytes is defined.
1546 @item -Wpointer-arith
1547 Warn about anything that depends on the ``size of'' a function type or
1548 of @code{void}. GNU C assigns these types a size of 1, for
1549 convenience in calculations with @code{void *} pointers and pointers
1552 @item -Wbad-function-cast
1553 Warn whenever a function call is cast to a non-matching type.
1554 For example, warn if @code{int malloc()} is cast to @code{anything *}.
1557 Warn whenever a pointer is cast so as to remove a type qualifier from
1558 the target type. For example, warn if a @code{const char *} is cast
1559 to an ordinary @code{char *}.
1562 Warn whenever a pointer is cast such that the required alignment of the
1563 target is increased. For example, warn if a @code{char *} is cast to
1564 an @code{int *} on machines where integers can only be accessed at
1565 two- or four-byte boundaries.
1567 @item -Wwrite-strings
1568 Give string constants the type @code{const char[@var{length}]} so that
1569 copying the address of one into a non-@code{const} @code{char *}
1570 pointer will get a warning. These warnings will help you find at
1571 compile time code that can try to write into a string constant, but
1572 only if you have been very careful about using @code{const} in
1573 declarations and prototypes. Otherwise, it will just be a nuisance;
1574 this is why we did not make @samp{-Wall} request these warnings.
1577 Warn if a prototype causes a type conversion that is different from what
1578 would happen to the same argument in the absence of a prototype. This
1579 includes conversions of fixed point to floating and vice versa, and
1580 conversions changing the width or signedness of a fixed point argument
1581 except when the same as the default promotion.
1583 Also, warn if a negative integer constant expression is implicitly
1584 converted to an unsigned type. For example, warn about the assignment
1585 @code{x = -1} if @code{x} is unsigned. But do not warn about explicit
1586 casts like @code{(unsigned) -1}.
1588 @item -Wsign-compare
1589 @cindex warning for comparison of signed and unsigned values
1590 @cindex comparison of signed and unsigned values, warning
1591 @cindex signed and unsigned values, comparison warning
1592 Warn when a comparison between signed and unsigned values could produce
1593 an incorrect result when the signed value is converted to unsigned.
1594 This warning is also enabled by @samp{-W}; to get the other warnings
1595 of @samp{-W} without this warning, use @samp{-W -Wno-sign-compare}.
1597 @item -Waggregate-return
1598 Warn if any functions that return structures or unions are defined or
1599 called. (In languages where you can return an array, this also elicits
1602 @item -Wstrict-prototypes
1603 Warn if a function is declared or defined without specifying the
1604 argument types. (An old-style function definition is permitted without
1605 a warning if preceded by a declaration which specifies the argument
1608 @item -Wmissing-prototypes
1609 Warn if a global function is defined without a previous prototype
1610 declaration. This warning is issued even if the definition itself
1611 provides a prototype. The aim is to detect global functions that fail
1612 to be declared in header files.
1614 @item -Wmissing-declarations
1615 Warn if a global function is defined without a previous declaration.
1616 Do so even if the definition itself provides a prototype.
1617 Use this option to detect global functions that are not declared in
1620 @item -Wmissing-noreturn
1621 Warn about functions which might be candidates for attribute @code{noreturn}.
1622 Note these are only possible candidates, not absolute ones. Care should
1623 be taken to manually verify functions actually do not ever return before
1624 adding the @code{noreturn} attribute, otherwise subtle code generation
1625 bugs could be introduced.
1627 @item -Wredundant-decls
1628 Warn if anything is declared more than once in the same scope, even in
1629 cases where multiple declaration is valid and changes nothing.
1631 @item -Wnested-externs
1632 Warn if an @code{extern} declaration is encountered within an function.
1634 @item -Wno-non-template-friend
1635 Disable warnings when non-templatized friend functions are declared
1636 within a template. With the advent of explicit template specification
1637 support in g++, if the name of the friend is an unqualified-id (ie,
1638 @samp{friend foo(int)}), the C++ language specification demands that the
1639 friend declare or define an ordinary, nontemplate function. (Section
1640 14.5.3). Before g++ implemented explicit specification, unqualified-ids
1641 could be interpreted as a particular specialization of a templatized
1642 function. Because this non-conforming behavior is no longer the default
1643 behavior for g++, @samp{-Wnon-template-friend} allows the compiler to
1644 check existing code for potential trouble spots, and is on by default.
1645 This new compiler behavior can also be turned off with the flag
1646 @samp{-fguiding-decls}, which activates the older, non-specification
1647 compiler code, or with @samp{-Wno-non-template-friend} which keeps the
1648 conformant compiler code but disables the helpful warning.
1651 Warn if a function can not be inlined, and either it was declared as inline,
1652 or else the @samp{-finline-functions} option was given.
1654 @item -Wold-style-cast
1655 Warn if an old-style (C-style) cast is used within a program.
1657 @item -Woverloaded-virtual
1658 @cindex overloaded virtual fn, warning
1659 @cindex warning for overloaded virtual fn
1660 Warn when a derived class function declaration may be an error in
1661 defining a virtual function (C++ only). In a derived class, the
1662 definitions of virtual functions must match the type signature of a
1663 virtual function declared in the base class. With this option, the
1664 compiler warns when you define a function with the same name as a
1665 virtual function, but with a type signature that does not match any
1666 declarations from the base class.
1668 @item -Wsynth (C++ only)
1669 @cindex warning for synthesized methods
1670 @cindex synthesized methods, warning
1671 Warn when g++'s synthesis behavior does not match that of cfront. For
1677 A& operator = (int);
1687 In this example, g++ will synthesize a default @samp{A& operator =
1688 (const A&);}, while cfront will use the user-defined @samp{operator =}.
1691 Warn if @samp{long long} type is used. This is default. To inhibit
1692 the warning messages, use @samp{-Wno-long-long}. Flags
1693 @samp{-Wlong-long} and @samp{-Wno-long-long} are taken into account
1694 only when @samp{-pedantic} flag is used.
1697 Make all warnings into errors.
1700 @node Debugging Options
1701 @section Options for Debugging Your Program or GNU CC
1702 @cindex options, debugging
1703 @cindex debugging information options
1705 GNU CC has various special options that are used for debugging
1706 either your program or GCC:
1710 Produce debugging information in the operating system's native format
1711 (stabs, COFF, XCOFF, or DWARF). GDB can work with this debugging
1714 On most systems that use stabs format, @samp{-g} enables use of extra
1715 debugging information that only GDB can use; this extra information
1716 makes debugging work better in GDB but will probably make other debuggers
1718 refuse to read the program. If you want to control for certain whether
1719 to generate the extra information, use @samp{-gstabs+}, @samp{-gstabs},
1720 @samp{-gxcoff+}, @samp{-gxcoff}, @samp{-gdwarf-1+}, or @samp{-gdwarf-1}
1723 Unlike most other C compilers, GNU CC allows you to use @samp{-g} with
1724 @samp{-O}. The shortcuts taken by optimized code may occasionally
1725 produce surprising results: some variables you declared may not exist
1726 at all; flow of control may briefly move where you did not expect it;
1727 some statements may not be executed because they compute constant
1728 results or their values were already at hand; some statements may
1729 execute in different places because they were moved out of loops.
1731 Nevertheless it proves possible to debug optimized output. This makes
1732 it reasonable to use the optimizer for programs that might have bugs.
1734 The following options are useful when GNU CC is generated with the
1735 capability for more than one debugging format.
1738 Produce debugging information for use by GDB. This means to use the
1739 most expressive format available (DWARF 2, stabs, or the native format
1740 if neither of those are supported), including GDB extensions if at all
1744 Produce debugging information in stabs format (if that is supported),
1745 without GDB extensions. This is the format used by DBX on most BSD
1746 systems. On MIPS, Alpha and System V Release 4 systems this option
1747 produces stabs debugging output which is not understood by DBX or SDB.
1748 On System V Release 4 systems this option requires the GNU assembler.
1751 Produce debugging information in stabs format (if that is supported),
1752 using GNU extensions understood only by the GNU debugger (GDB). The
1753 use of these extensions is likely to make other debuggers crash or
1754 refuse to read the program.
1757 Produce debugging information in COFF format (if that is supported).
1758 This is the format used by SDB on most System V systems prior to
1762 Produce debugging information in XCOFF format (if that is supported).
1763 This is the format used by the DBX debugger on IBM RS/6000 systems.
1766 Produce debugging information in XCOFF format (if that is supported),
1767 using GNU extensions understood only by the GNU debugger (GDB). The
1768 use of these extensions is likely to make other debuggers crash or
1769 refuse to read the program, and may cause assemblers other than the GNU
1770 assembler (GAS) to fail with an error.
1773 Produce debugging information in DWARF version 1 format (if that is
1774 supported). This is the format used by SDB on most System V Release 4
1778 Produce debugging information in DWARF version 1 format (if that is
1779 supported), using GNU extensions understood only by the GNU debugger
1780 (GDB). The use of these extensions is likely to make other debuggers
1781 crash or refuse to read the program.
1784 Produce debugging information in DWARF version 2 format (if that is
1785 supported). This is the format used by DBX on IRIX 6.
1788 @itemx -ggdb@var{level}
1789 @itemx -gstabs@var{level}
1790 @itemx -gcoff@var{level}
1791 @itemx -gxcoff@var{level}
1792 @itemx -gdwarf@var{level}
1793 @itemx -gdwarf-2@var{level}
1794 Request debugging information and also use @var{level} to specify how
1795 much information. The default level is 2.
1797 Level 1 produces minimal information, enough for making backtraces in
1798 parts of the program that you don't plan to debug. This includes
1799 descriptions of functions and external variables, but no information
1800 about local variables and no line numbers.
1802 Level 3 includes extra information, such as all the macro definitions
1803 present in the program. Some debuggers support macro expansion when
1808 Generate extra code to write profile information suitable for the
1809 analysis program @code{prof}. You must use this option when compiling
1810 the source files you want data about, and you must also use it when
1813 @cindex @code{gprof}
1815 Generate extra code to write profile information suitable for the
1816 analysis program @code{gprof}. You must use this option when compiling
1817 the source files you want data about, and you must also use it when
1822 Generate extra code to write profile information for basic blocks, which will
1823 record the number of times each basic block is executed, the basic block start
1824 address, and the function name containing the basic block. If @samp{-g} is
1825 used, the line number and filename of the start of the basic block will also be
1826 recorded. If not overridden by the machine description, the default action is
1827 to append to the text file @file{bb.out}.
1829 This data could be analyzed by a program like @code{tcov}. Note,
1830 however, that the format of the data is not what @code{tcov} expects.
1831 Eventually GNU @code{gprof} should be extended to process this data.
1834 Makes the compiler print out each function name as it is compiled, and
1835 print some statistics about each pass when it finishes.
1838 Generate extra code to profile basic blocks. Your executable will
1839 produce output that is a superset of that produced when @samp{-a} is
1840 used. Additional output is the source and target address of the basic
1841 blocks where a jump takes place, the number of times a jump is executed,
1842 and (optionally) the complete sequence of basic blocks being executed.
1843 The output is appended to file @file{bb.out}.
1845 You can examine different profiling aspects without recompilation. Your
1846 executable will read a list of function names from file @file{bb.in}.
1847 Profiling starts when a function on the list is entered and stops when
1848 that invocation is exited. To exclude a function from profiling, prefix
1849 its name with `-'. If a function name is not unique, you can
1850 disambiguate it by writing it in the form
1851 @samp{/path/filename.d:functionname}. Your executable will write the
1852 available paths and filenames in file @file{bb.out}.
1854 Several function names have a special meaning:
1857 Write source, target and frequency of jumps to file @file{bb.out}.
1858 @item __bb_hidecall__
1859 Exclude function calls from frequency count.
1860 @item __bb_showret__
1861 Include function returns in frequency count.
1863 Write the sequence of basic blocks executed to file @file{bbtrace.gz}.
1864 The file will be compressed using the program @samp{gzip}, which must
1865 exist in your @code{PATH}. On systems without the @samp{popen}
1866 function, the file will be named @file{bbtrace} and will not be
1867 compressed. @strong{Profiling for even a few seconds on these systems
1868 will produce a very large file.} Note: @code{__bb_hidecall__} and
1869 @code{__bb_showret__} will not affect the sequence written to
1873 Here's a short example using different profiling parameters
1874 in file @file{bb.in}. Assume function @code{foo} consists of basic blocks
1875 1 and 2 and is called twice from block 3 of function @code{main}. After
1876 the calls, block 3 transfers control to block 4 of @code{main}.
1878 With @code{__bb_trace__} and @code{main} contained in file @file{bb.in},
1879 the following sequence of blocks is written to file @file{bbtrace.gz}:
1880 0 3 1 2 1 2 4. The return from block 2 to block 3 is not shown, because
1881 the return is to a point inside the block and not to the top. The
1882 block address 0 always indicates, that control is transferred
1883 to the trace from somewhere outside the observed functions. With
1884 @samp{-foo} added to @file{bb.in}, the blocks of function
1885 @code{foo} are removed from the trace, so only 0 3 4 remains.
1887 With @code{__bb_jumps__} and @code{main} contained in file @file{bb.in},
1888 jump frequencies will be written to file @file{bb.out}. The
1889 frequencies are obtained by constructing a trace of blocks
1890 and incrementing a counter for every neighbouring pair of blocks
1891 in the trace. The trace 0 3 1 2 1 2 4 displays the following
1895 Jump from block 0x0 to block 0x3 executed 1 time(s)
1896 Jump from block 0x3 to block 0x1 executed 1 time(s)
1897 Jump from block 0x1 to block 0x2 executed 2 time(s)
1898 Jump from block 0x2 to block 0x1 executed 1 time(s)
1899 Jump from block 0x2 to block 0x4 executed 1 time(s)
1902 With @code{__bb_hidecall__}, control transfer due to call instructions
1903 is removed from the trace, that is the trace is cut into three parts: 0
1904 3 4, 0 1 2 and 0 1 2. With @code{__bb_showret__}, control transfer due
1905 to return instructions is added to the trace. The trace becomes: 0 3 1
1906 2 3 1 2 3 4. Note, that this trace is not the same, as the sequence
1907 written to @file{bbtrace.gz}. It is solely used for counting jump
1910 @item -fprofile-arcs
1911 Instrument @dfn{arcs} during compilation. For each function of your
1912 program, GNU CC creates a program flow graph, then finds a spanning tree
1913 for the graph. Only arcs that are not on the spanning tree have to be
1914 instrumented: the compiler adds code to count the number of times that these
1915 arcs are executed. When an arc is the only exit or only entrance to a
1916 block, the instrumentation code can be added to the block; otherwise, a
1917 new basic block must be created to hold the instrumentation code.
1919 Since not every arc in the program must be instrumented, programs
1920 compiled with this option run faster than programs compiled with
1921 @samp{-a}, which adds instrumentation code to every basic block in the
1922 program. The tradeoff: since @code{gcov} does not have
1923 execution counts for all branches, it must start with the execution
1924 counts for the instrumented branches, and then iterate over the program
1925 flow graph until the entire graph has been solved. Hence, @code{gcov}
1926 runs a little more slowly than a program which uses information from
1929 @samp{-fprofile-arcs} also makes it possible to estimate branch
1930 probabilities, and to calculate basic block execution counts. In
1931 general, basic block execution counts do not give enough information to
1932 estimate all branch probabilities. When the compiled program exits, it
1933 saves the arc execution counts to a file called
1934 @file{@var{sourcename}.da}. Use the compiler option
1935 @samp{-fbranch-probabilities} (@pxref{Optimize Options,,Options that
1936 Control Optimization}) when recompiling, to optimize using estimated
1937 branch probabilities.
1940 @item -ftest-coverage
1941 Create data files for the @code{gcov} code-coverage utility
1942 (@pxref{Gcov,, @code{gcov}: a GNU CC Test Coverage Program}).
1943 The data file names begin with the name of your source file:
1946 @item @var{sourcename}.bb
1947 A mapping from basic blocks to line numbers, which @code{gcov} uses to
1948 associate basic block execution counts with line numbers.
1950 @item @var{sourcename}.bbg
1951 A list of all arcs in the program flow graph. This allows @code{gcov}
1952 to reconstruct the program flow graph, so that it can compute all basic
1953 block and arc execution counts from the information in the
1954 @code{@var{sourcename}.da} file (this last file is the output from
1955 @samp{-fprofile-arcs}).
1959 Makes the compiler print out each function name as it is compiled, and
1960 print some statistics about each pass when it finishes.
1962 @item -d@var{letters}
1963 Says to make debugging dumps during compilation at times specified by
1964 @var{letters}. This is used for debugging the compiler. The file names
1965 for most of the dumps are made by appending a word to the source file
1966 name (e.g. @file{foo.c.rtl} or @file{foo.c.jump}). Here are the
1967 possible letters for use in @var{letters}, and their meanings:
1971 Dump after computing branch probabilities, to @file{@var{file}.bp}.
1973 Dump after instruction combination, to the file @file{@var{file}.combine}.
1975 Dump after delayed branch scheduling, to @file{@var{file}.dbr}.
1977 Dump all macro definitions, at the end of preprocessing, in addition to
1980 Dump debugging information during parsing, to standard error.
1982 Dump after RTL generation, to @file{@var{file}.rtl}.
1984 Just generate RTL for a function instead of compiling it. Usually used
1987 Dump after first jump optimization, to @file{@var{file}.jump}.
1989 Dump after CSE (including the jump optimization that sometimes
1990 follows CSE), to @file{@var{file}.cse}.
1992 Dump after purging ADDRESSOF, to @file{@var{file}.addressof}.
1994 Dump after flow analysis, to @file{@var{file}.flow}.
1996 Dump after global register allocation, to @file{@var{file}.greg}.
1998 Dump after GCSE, to @file{@var{file}.gcse}.
2000 Dump after first jump optimization, to @file{@var{file}.jump}.
2002 Dump after last jump optimization, to @file{@var{file}.jump2}.
2004 Dump after conversion from registers to stack, to @file{@var{file}.stack}.
2006 Dump after local register allocation, to @file{@var{file}.lreg}.
2008 Dump after loop optimization, to @file{@var{file}.loop}.
2010 Dump after performing the machine dependent reorganisation pass, to
2011 @file{@var{file}.mach}.
2013 Dump after the register move pass, to @file{@var{file}.regmove}.
2015 Dump after RTL generation, to @file{@var{file}.rtl}.
2017 Dump after the second instruction scheduling pass, to @file{@var{file}.sched2}.
2019 Dump after CSE (including the jump optimization that sometimes follows
2020 CSE), to @file{@var{file}.cse}.
2022 Dump after the first instruction scheduling pass, to @file{@var{file}.sched}.
2024 Dump after the second CSE pass (including the jump optimization that
2025 sometimes follows CSE), to @file{@var{file}.cse2}.
2027 Just generate RTL for a function instead of compiling it. Usually used
2030 Produce all the dumps listed above.
2032 Print statistics on memory usage, at the end of the run, to
2035 Annotate the assembler output with a comment indicating which
2036 pattern and alternative was used.
2038 Dump debugging information during parsing, to standard error.
2040 Annotate the assembler output with miscellaneous debugging information.
2043 @item -fdump-unnumbered
2044 When doing debugging dumps (see -d option above), suppress instruction
2045 numbers and line number note output. This makes it more feasible to
2046 use diff on debugging dumps for compiler invokations with different
2047 options, in particular with and without -g.
2049 @item -fpretend-float
2050 When running a cross-compiler, pretend that the target machine uses the
2051 same floating point format as the host machine. This causes incorrect
2052 output of the actual floating constants, but the actual instruction
2053 sequence will probably be the same as GNU CC would make when running on
2057 Store the usual ``temporary'' intermediate files permanently; place them
2058 in the current directory and name them based on the source file. Thus,
2059 compiling @file{foo.c} with @samp{-c -save-temps} would produce files
2060 @file{foo.i} and @file{foo.s}, as well as @file{foo.o}.
2062 @item -print-file-name=@var{library}
2063 Print the full absolute name of the library file @var{library} that
2064 would be used when linking---and don't do anything else. With this
2065 option, GNU CC does not compile or link anything; it just prints the
2068 @item -print-prog-name=@var{program}
2069 Like @samp{-print-file-name}, but searches for a program such as @samp{cpp}.
2071 @item -print-libgcc-file-name
2072 Same as @samp{-print-file-name=libgcc.a}.
2074 This is useful when you use @samp{-nostdlib} or @samp{-nodefaultlibs}
2075 but you do want to link with @file{libgcc.a}. You can do
2078 gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
2081 @item -print-search-dirs
2082 Print the name of the configured installation directory and a list of
2083 program and library directories gcc will search---and don't do anything else.
2085 This is useful when gcc prints the error message
2086 @samp{installation problem, cannot exec cpp: No such file or directory}.
2087 To resolve this you either need to put @file{cpp} and the other compiler
2088 components where gcc expects to find them, or you can set the environment
2089 variable @code{GCC_EXEC_PREFIX} to the directory where you installed them.
2090 Don't forget the trailing '/'.
2091 @xref{Environment Variables}.
2094 @node Optimize Options
2095 @section Options That Control Optimization
2096 @cindex optimize options
2097 @cindex options, optimization
2099 These options control various sorts of optimizations:
2104 Optimize. Optimizing compilation takes somewhat more time, and a lot
2105 more memory for a large function.
2107 Without @samp{-O}, the compiler's goal is to reduce the cost of
2108 compilation and to make debugging produce the expected results.
2109 Statements are independent: if you stop the program with a breakpoint
2110 between statements, you can then assign a new value to any variable or
2111 change the program counter to any other statement in the function and
2112 get exactly the results you would expect from the source code.
2114 Without @samp{-O}, the compiler only allocates variables declared
2115 @code{register} in registers. The resulting compiled code is a little
2116 worse than produced by PCC without @samp{-O}.
2118 With @samp{-O}, the compiler tries to reduce code size and execution
2121 When you specify @samp{-O}, the compiler turns on @samp{-fthread-jumps}
2122 and @samp{-fdefer-pop} on all machines. The compiler turns on
2123 @samp{-fdelayed-branch} on machines that have delay slots, and
2124 @samp{-fomit-frame-pointer} on machines that can support debugging even
2125 without a frame pointer. On some machines the compiler also turns
2126 on other flags.@refill
2129 Optimize even more. GNU CC performs nearly all supported optimizations
2130 that do not involve a space-speed tradeoff. The compiler does not
2131 perform loop unrolling or function inlining when you specify @samp{-O2}.
2132 As compared to @samp{-O}, this option increases both compilation time
2133 and the performance of the generated code.
2135 @samp{-O2} turns on all optional optimizations except for loop unrolling
2136 and function inlining. It also turns on the @samp{-fforce-mem} option
2137 on all machines and frame pointer elimination on machines where doing so
2138 does not interfere with debugging.
2141 Optimize yet more. @samp{-O3} turns on all optimizations specified by
2142 @samp{-O2} and also turns on the @samp{inline-functions} option.
2148 Optimize for size. @samp{-Os} enables all @samp{-O2} optimizations that
2149 do not typically increase code size. It also performs further
2150 optimizations designed to reduce code size.
2152 If you use multiple @samp{-O} options, with or without level numbers,
2153 the last such option is the one that is effective.
2156 Options of the form @samp{-f@var{flag}} specify machine-independent
2157 flags. Most flags have both positive and negative forms; the negative
2158 form of @samp{-ffoo} would be @samp{-fno-foo}. In the table below,
2159 only one of the forms is listed---the one which is not the default.
2160 You can figure out the other form by either removing @samp{no-} or
2165 Do not store floating point variables in registers, and inhibit other
2166 options that might change whether a floating point value is taken from a
2169 @cindex floating point precision
2170 This option prevents undesirable excess precision on machines such as
2171 the 68000 where the floating registers (of the 68881) keep more
2172 precision than a @code{double} is supposed to have. Similarly for the
2173 x86 architecture. For most programs, the excess precision does only
2174 good, but a few programs rely on the precise definition of IEEE floating
2175 point. Use @samp{-ffloat-store} for such programs, after modifying
2176 them to store all pertinent intermediate computations into variables.
2178 @item -fno-default-inline
2179 Do not make member functions inline by default merely because they are
2180 defined inside the class scope (C++ only). Otherwise, when you specify
2181 @w{@samp{-O}}, member functions defined inside class scope are compiled
2182 inline by default; i.e., you don't need to add @samp{inline} in front of
2183 the member function name.
2185 @item -fno-defer-pop
2186 Always pop the arguments to each function call as soon as that function
2187 returns. For machines which must pop arguments after a function call,
2188 the compiler normally lets arguments accumulate on the stack for several
2189 function calls and pops them all at once.
2192 Force memory operands to be copied into registers before doing
2193 arithmetic on them. This produces better code by making all memory
2194 references potential common subexpressions. When they are not common
2195 subexpressions, instruction combination should eliminate the separate
2196 register-load. The @samp{-O2} option turns on this option.
2199 Force memory address constants to be copied into registers before
2200 doing arithmetic on them. This may produce better code just as
2201 @samp{-fforce-mem} may.
2203 @item -fomit-frame-pointer
2204 Don't keep the frame pointer in a register for functions that
2205 don't need one. This avoids the instructions to save, set up and
2206 restore frame pointers; it also makes an extra register available
2207 in many functions. @strong{It also makes debugging impossible on
2211 On some machines, such as the Vax, this flag has no effect, because
2212 the standard calling sequence automatically handles the frame pointer
2213 and nothing is saved by pretending it doesn't exist. The
2214 machine-description macro @code{FRAME_POINTER_REQUIRED} controls
2215 whether a target machine supports this flag. @xref{Registers}.@refill
2218 On some machines, such as the Vax, this flag has no effect, because
2219 the standard calling sequence automatically handles the frame pointer
2220 and nothing is saved by pretending it doesn't exist. The
2221 machine-description macro @code{FRAME_POINTER_REQUIRED} controls
2222 whether a target machine supports this flag. @xref{Registers,,Register
2223 Usage, gcc.info, Using and Porting GCC}.@refill
2227 Don't pay attention to the @code{inline} keyword. Normally this option
2228 is used to keep the compiler from expanding any functions inline.
2229 Note that if you are not optimizing, no functions can be expanded inline.
2231 @item -finline-functions
2232 Integrate all simple functions into their callers. The compiler
2233 heuristically decides which functions are simple enough to be worth
2234 integrating in this way.
2236 If all calls to a given function are integrated, and the function is
2237 declared @code{static}, then the function is normally not output as
2238 assembler code in its own right.
2240 @item -fkeep-inline-functions
2241 Even if all calls to a given function are integrated, and the function
2242 is declared @code{static}, nevertheless output a separate run-time
2243 callable version of the function. This switch does not affect
2244 @code{extern inline} functions.
2246 @item -fkeep-static-consts
2247 Emit variables declared @code{static const} when optimization isn't turned
2248 on, even if the variables aren't referenced.
2250 GNU CC enables this option by default. If you want to force the compiler to
2251 check if the variable was referenced, regardless of whether or not
2252 optimization is turned on, use the @samp{-fno-keep-static-consts} option.
2254 @item -fno-function-cse
2255 Do not put function addresses in registers; make each instruction that
2256 calls a constant function contain the function's address explicitly.
2258 This option results in less efficient code, but some strange hacks
2259 that alter the assembler output may be confused by the optimizations
2260 performed when this option is not used.
2263 This option allows GCC to violate some ANSI or IEEE rules and/or
2264 specifications in the interest of optimizing code for speed. For
2265 example, it allows the compiler to assume arguments to the @code{sqrt}
2266 function are non-negative numbers and that no floating-point values
2269 This option should never be turned on by any @samp{-O} option since
2270 it can result in incorrect output for programs which depend on
2271 an exact implementation of IEEE or ANSI rules/specifications for
2275 @c following causes underfulls.. they don't look great, but we deal.
2277 The following options control specific optimizations. The @samp{-O2}
2278 option turns on all of these optimizations except @samp{-funroll-loops}
2279 and @samp{-funroll-all-loops}. On most machines, the @samp{-O} option
2280 turns on the @samp{-fthread-jumps} and @samp{-fdelayed-branch} options,
2281 but specific machines may handle it differently.
2283 You can use the following flags in the rare cases when ``fine-tuning''
2284 of optimizations to be performed is desired.
2287 @item -fstrength-reduce
2288 Perform the optimizations of loop strength reduction and
2289 elimination of iteration variables.
2291 @item -fthread-jumps
2292 Perform optimizations where we check to see if a jump branches to a
2293 location where another comparison subsumed by the first is found. If
2294 so, the first branch is redirected to either the destination of the
2295 second branch or a point immediately following it, depending on whether
2296 the condition is known to be true or false.
2298 @item -fcse-follow-jumps
2299 In common subexpression elimination, scan through jump instructions
2300 when the target of the jump is not reached by any other path. For
2301 example, when CSE encounters an @code{if} statement with an
2302 @code{else} clause, CSE will follow the jump when the condition
2305 @item -fcse-skip-blocks
2306 This is similar to @samp{-fcse-follow-jumps}, but causes CSE to
2307 follow jumps which conditionally skip over blocks. When CSE
2308 encounters a simple @code{if} statement with no else clause,
2309 @samp{-fcse-skip-blocks} causes CSE to follow the jump around the
2310 body of the @code{if}.
2312 @item -frerun-cse-after-loop
2313 Re-run common subexpression elimination after loop optimizations has been
2316 @item -frerun-loop-opt
2317 Run the loop optimizer twice.
2320 Perform a global common subexpression elimination pass.
2321 This pass also performs global constant and copy propagation.
2323 @item -fexpensive-optimizations
2324 Perform a number of minor optimizations that are relatively expensive.
2326 @item -foptimize-register-moves
2328 Attempt to reassign register numbers in move instructions and as
2329 operands of other simple instructions in order to maximize the amount of
2330 register tying. This is especially helpful on machines with two-operand
2331 instructions. GNU CC enables this optimization by default with @samp{-O2}
2334 Note @code{-fregmove} and @code{-foptimize-register-moves} are the same
2337 @item -fdelayed-branch
2338 If supported for the target machine, attempt to reorder instructions
2339 to exploit instruction slots available after delayed branch
2342 @item -fschedule-insns
2343 If supported for the target machine, attempt to reorder instructions to
2344 eliminate execution stalls due to required data being unavailable. This
2345 helps machines that have slow floating point or memory load instructions
2346 by allowing other instructions to be issued until the result of the load
2347 or floating point instruction is required.
2349 @item -fschedule-insns2
2350 Similar to @samp{-fschedule-insns}, but requests an additional pass of
2351 instruction scheduling after register allocation has been done. This is
2352 especially useful on machines with a relatively small number of
2353 registers and where memory load instructions take more than one cycle.
2355 @item -ffunction-sections
2356 @item -fdata-sections
2357 Place each function or data item into its own section in the output
2358 file if the target supports arbitrary sections. The name of the
2359 function or the name of the data item determines the section's name
2362 Use these options on systems where the linker can perform optimizations
2363 to improve locality of reference in the instruction space. HPPA
2364 processors running HP-UX and Sparc processors running Solaris 2 have
2365 linkers with such optimizations. Other systems using the ELF object format
2366 as well as AIX may have these optimizations in the future.
2368 Only use these options when there are significant benefits from doing
2369 so. When you specify these options, the assembler and linker will
2370 create larger object and executable files and will also be slower.
2371 You will not be able to use @code{gprof} on all systems if you
2372 specify this option and you may have problems with debugging if
2373 you specify both this option and @samp{-g}.
2375 @item -fcaller-saves
2376 Enable values to be allocated in registers that will be clobbered by
2377 function calls, by emitting extra instructions to save and restore the
2378 registers around such calls. Such allocation is done only when it
2379 seems to result in better code than would otherwise be produced.
2381 This option is always enabled by default on certain machines, usually
2382 those which have no call-preserved registers to use instead.
2384 For all machines, optimization level 2 and higher enables this flag by
2387 @item -funroll-loops
2388 Perform the optimization of loop unrolling. This is only done for loops
2389 whose number of iterations can be determined at compile time or run time.
2390 @samp{-funroll-loop} implies both @samp{-fstrength-reduce} and
2391 @samp{-frerun-cse-after-loop}.
2393 @item -funroll-all-loops
2394 Perform the optimization of loop unrolling. This is done for all loops
2395 and usually makes programs run more slowly. @samp{-funroll-all-loops}
2396 implies @samp{-fstrength-reduce} as well as @samp{-frerun-cse-after-loop}.
2398 @item -fmove-all-movables
2399 Forces all invariant computations in loops to be moved
2402 @item -freduce-all-givs
2403 Forces all general-induction variables in loops to be
2406 @emph{Note:} When compiling programs written in Fortran,
2407 @samp{-fmove-all-moveables} and @samp{-freduce-all-givs} are enabled
2408 by default when you use the optimizer.
2410 These options may generate better or worse code; results are highly
2411 dependent on the structure of loops within the source code.
2413 These two options are intended to be removed someday, once
2414 they have helped determine the efficacy of various
2415 approaches to improving loop optimizations.
2417 Please let us (@code{egcs@@cygnus.com} and @code{fortran@@gnu.org})
2418 know how use of these options affects
2419 the performance of your production code.
2420 We're very interested in code that runs @emph{slower}
2421 when these options are @emph{enabled}.
2424 Disable any machine-specific peephole optimizations.
2426 @item -fbranch-probabilities
2427 After running a program compiled with @samp{-fprofile-arcs}
2428 (@pxref{Debugging Options,, Options for Debugging Your Program or
2429 @code{gcc}}), you can compile it a second time using
2430 @samp{-fbranch-probabilities}, to improve optimizations based on
2431 guessing the path a branch might take.
2434 With @samp{-fbranch-probabilities}, GCC puts a @samp{REG_EXEC_COUNT}
2435 note on the first instruction of each basic block, and a
2436 @samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}.
2437 These can be used to improve optimization. Currently, they are only
2438 used in one place: in @file{reorg.c}, instead of guessing which path a
2439 branch is mostly to take, the @samp{REG_BR_PROB} values are used to
2440 exactly determine which path is taken more often.
2443 @item -fstrict-aliasing
2444 Allows the compiler to assume the strictest aliasing rules applicable to
2445 the language being compiled. For C (and C++), this activates
2446 optimizations based on the type of expressions. In particular, an
2447 object of one type is assumed never to reside at the same address as an
2448 object of a different type, unless the types are almost the same. For
2449 example, an @code{unsigned int} can alias an @code{int}, but not a
2450 @code{void*} or a @code{double}. A character type may alias any other
2453 Pay special attention to code like this:
2466 The practice of reading from a different union member than the one most
2467 recently written to (called ``type-punning'') is common. Even with
2468 @samp{-fstrict-aliasing}, type-punning is allowed, provided the memory
2469 is accessed through the union type. So, the code above will work as
2470 expected. However, this code might not:
2482 Every language that wishes to perform language-specific alias analysis
2483 should define a function that computes, given an @code{tree}
2484 node, an alias set for the node. Nodes in different alias sets are not
2485 allowed to alias. For an example, see the C front-end function
2486 @code{c_get_alias_set}.
2491 @node Preprocessor Options
2492 @section Options Controlling the Preprocessor
2493 @cindex preprocessor options
2494 @cindex options, preprocessor
2496 These options control the C preprocessor, which is run on each C source
2497 file before actual compilation.
2499 If you use the @samp{-E} option, nothing is done except preprocessing.
2500 Some of these options make sense only together with @samp{-E} because
2501 they cause the preprocessor output to be unsuitable for actual
2505 @item -include @var{file}
2506 Process @var{file} as input before processing the regular input file.
2507 In effect, the contents of @var{file} are compiled first. Any @samp{-D}
2508 and @samp{-U} options on the command line are always processed before
2509 @samp{-include @var{file}}, regardless of the order in which they are
2510 written. All the @samp{-include} and @samp{-imacros} options are
2511 processed in the order in which they are written.
2513 @item -imacros @var{file}
2514 Process @var{file} as input, discarding the resulting output, before
2515 processing the regular input file. Because the output generated from
2516 @var{file} is discarded, the only effect of @samp{-imacros @var{file}}
2517 is to make the macros defined in @var{file} available for use in the
2520 Any @samp{-D} and @samp{-U} options on the command line are always
2521 processed before @samp{-imacros @var{file}}, regardless of the order in
2522 which they are written. All the @samp{-include} and @samp{-imacros}
2523 options are processed in the order in which they are written.
2525 @item -idirafter @var{dir}
2526 @cindex second include path
2527 Add the directory @var{dir} to the second include path. The directories
2528 on the second include path are searched when a header file is not found
2529 in any of the directories in the main include path (the one that
2532 @item -iprefix @var{prefix}
2533 Specify @var{prefix} as the prefix for subsequent @samp{-iwithprefix}
2536 @item -iwithprefix @var{dir}
2537 Add a directory to the second include path. The directory's name is
2538 made by concatenating @var{prefix} and @var{dir}, where @var{prefix} was
2539 specified previously with @samp{-iprefix}. If you have not specified a
2540 prefix yet, the directory containing the installed passes of the
2541 compiler is used as the default.
2543 @item -iwithprefixbefore @var{dir}
2544 Add a directory to the main include path. The directory's name is made
2545 by concatenating @var{prefix} and @var{dir}, as in the case of
2546 @samp{-iwithprefix}.
2548 @item -isystem @var{dir}
2549 Add a directory to the beginning of the second include path, marking it
2550 as a system directory, so that it gets the same special treatment as
2551 is applied to the standard system directories.
2554 Do not search the standard system directories for header files. Only
2555 the directories you have specified with @samp{-I} options (and the
2556 current directory, if appropriate) are searched. @xref{Directory
2557 Options}, for information on @samp{-I}.
2559 By using both @samp{-nostdinc} and @samp{-I-}, you can limit the include-file
2560 search path to only those directories you specify explicitly.
2563 Do not predefine any nonstandard macros. (Including architecture flags).
2566 Run only the C preprocessor. Preprocess all the C source files
2567 specified and output the results to standard output or to the
2568 specified output file.
2571 Tell the preprocessor not to discard comments. Used with the
2575 Tell the preprocessor not to generate @samp{#line} directives.
2576 Used with the @samp{-E} option.
2579 @cindex dependencies, make
2581 Tell the preprocessor to output a rule suitable for @code{make}
2582 describing the dependencies of each object file. For each source file,
2583 the preprocessor outputs one @code{make}-rule whose target is the object
2584 file name for that source file and whose dependencies are all the
2585 @code{#include} header files it uses. This rule may be a single line or
2586 may be continued with @samp{\}-newline if it is long. The list of rules
2587 is printed on standard output instead of the preprocessed C program.
2589 @samp{-M} implies @samp{-E}.
2591 Another way to specify output of a @code{make} rule is by setting
2592 the environment variable @code{DEPENDENCIES_OUTPUT} (@pxref{Environment
2596 Like @samp{-M} but the output mentions only the user header files
2597 included with @samp{#include "@var{file}"}. System header files
2598 included with @samp{#include <@var{file}>} are omitted.
2601 Like @samp{-M} but the dependency information is written to a file made by
2602 replacing ".c" with ".d" at the end of the input file names.
2603 This is in addition to compiling the file as specified---@samp{-MD} does
2604 not inhibit ordinary compilation the way @samp{-M} does.
2606 In Mach, you can use the utility @code{md} to merge multiple dependency
2607 files into a single dependency file suitable for using with the @samp{make}
2611 Like @samp{-MD} except mention only user header files, not system
2615 Treat missing header files as generated files and assume they live in the
2616 same directory as the source file. If you specify @samp{-MG}, you
2617 must also specify either @samp{-M} or @samp{-MM}. @samp{-MG} is not
2618 supported with @samp{-MD} or @samp{-MMD}.
2621 Print the name of each header file used, in addition to other normal
2624 @item -A@var{question}(@var{answer})
2625 Assert the answer @var{answer} for @var{question}, in case it is tested
2626 with a preprocessing conditional such as @samp{#if
2627 #@var{question}(@var{answer})}. @samp{-A-} disables the standard
2628 assertions that normally describe the target machine.
2631 Define macro @var{macro} with the string @samp{1} as its definition.
2633 @item -D@var{macro}=@var{defn}
2634 Define macro @var{macro} as @var{defn}. All instances of @samp{-D} on
2635 the command line are processed before any @samp{-U} options.
2638 Undefine macro @var{macro}. @samp{-U} options are evaluated after all
2639 @samp{-D} options, but before any @samp{-include} and @samp{-imacros}
2643 Tell the preprocessor to output only a list of the macro definitions
2644 that are in effect at the end of preprocessing. Used with the @samp{-E}
2648 Tell the preprocessing to pass all macro definitions into the output, in
2649 their proper sequence in the rest of the output.
2652 Like @samp{-dD} except that the macro arguments and contents are omitted.
2653 Only @samp{#define @var{name}} is included in the output.
2656 Support ANSI C trigraphs. The @samp{-ansi} option also has this effect.
2658 @item -Wp,@var{option}
2659 Pass @var{option} as an option to the preprocessor. If @var{option}
2660 contains commas, it is split into multiple options at the commas.
2663 @node Assembler Options
2664 @section Passing Options to the Assembler
2666 @c prevent bad page break with this line
2667 You can pass options to the assembler.
2670 @item -Wa,@var{option}
2671 Pass @var{option} as an option to the assembler. If @var{option}
2672 contains commas, it is split into multiple options at the commas.
2676 @section Options for Linking
2677 @cindex link options
2678 @cindex options, linking
2680 These options come into play when the compiler links object files into
2681 an executable output file. They are meaningless if the compiler is
2682 not doing a link step.
2686 @item @var{object-file-name}
2687 A file name that does not end in a special recognized suffix is
2688 considered to name an object file or library. (Object files are
2689 distinguished from libraries by the linker according to the file
2690 contents.) If linking is done, these object files are used as input
2696 If any of these options is used, then the linker is not run, and
2697 object file names should not be used as arguments. @xref{Overall
2701 @item -l@var{library}
2702 Search the library named @var{library} when linking.
2704 It makes a difference where in the command you write this option; the
2705 linker searches processes libraries and object files in the order they
2706 are specified. Thus, @samp{foo.o -lz bar.o} searches library @samp{z}
2707 after file @file{foo.o} but before @file{bar.o}. If @file{bar.o} refers
2708 to functions in @samp{z}, those functions may not be loaded.
2710 The linker searches a standard list of directories for the library,
2711 which is actually a file named @file{lib@var{library}.a}. The linker
2712 then uses this file as if it had been specified precisely by name.
2714 The directories searched include several standard system directories
2715 plus any that you specify with @samp{-L}.
2717 Normally the files found this way are library files---archive files
2718 whose members are object files. The linker handles an archive file by
2719 scanning through it for members which define symbols that have so far
2720 been referenced but not defined. But if the file that is found is an
2721 ordinary object file, it is linked in the usual fashion. The only
2722 difference between using an @samp{-l} option and specifying a file name
2723 is that @samp{-l} surrounds @var{library} with @samp{lib} and @samp{.a}
2724 and searches several directories.
2727 You need this special case of the @samp{-l} option in order to
2728 link an Objective C program.
2731 Do not use the standard system startup files when linking.
2732 The standard system libraries are used normally, unless @code{-nostdlib}
2733 or @code{-nodefaultlibs} is used.
2735 @item -nodefaultlibs
2736 Do not use the standard system libraries when linking.
2737 Only the libraries you specify will be passed to the linker.
2738 The standard startup files are used normally, unless @code{-nostartfiles}
2739 is used. The compiler may generate calls to memcmp, memset, and memcpy
2740 for System V (and ANSI C) environments or to bcopy and bzero for
2741 BSD environments. These entries are usually resolved by entries in
2742 libc. These entry points should be supplied through some other
2743 mechanism when this option is specified.
2746 Do not use the standard system startup files or libraries when linking.
2747 No startup files and only the libraries you specify will be passed to
2748 the linker. The compiler may generate calls to memcmp, memset, and memcpy
2749 for System V (and ANSI C) environments or to bcopy and bzero for
2750 BSD environments. These entries are usually resolved by entries in
2751 libc. These entry points should be supplied through some other
2752 mechanism when this option is specified.
2754 @cindex @code{-lgcc}, use with @code{-nostdlib}
2755 @cindex @code{-nostdlib} and unresolved references
2756 @cindex unresolved references and @code{-nostdlib}
2757 @cindex @code{-lgcc}, use with @code{-nodefaultlibs}
2758 @cindex @code{-nodefaultlibs} and unresolved references
2759 @cindex unresolved references and @code{-nodefaultlibs}
2760 One of the standard libraries bypassed by @samp{-nostdlib} and
2761 @samp{-nodefaultlibs} is @file{libgcc.a}, a library of internal subroutines
2762 that GNU CC uses to overcome shortcomings of particular machines, or special
2763 needs for some languages.
2765 (@xref{Interface,,Interfacing to GNU CC Output}, for more discussion of
2769 (@xref{Interface,,Interfacing to GNU CC Output,gcc.info,Porting GNU CC},
2770 for more discussion of @file{libgcc.a}.)
2772 In most cases, you need @file{libgcc.a} even when you want to avoid
2773 other standard libraries. In other words, when you specify @samp{-nostdlib}
2774 or @samp{-nodefaultlibs} you should usually specify @samp{-lgcc} as well.
2775 This ensures that you have no unresolved references to internal GNU CC
2776 library subroutines. (For example, @samp{__main}, used to ensure C++
2777 constructors will be called; @pxref{Collect2,,@code{collect2}}.)
2780 Remove all symbol table and relocation information from the executable.
2783 On systems that support dynamic linking, this prevents linking with the shared
2784 libraries. On other systems, this option has no effect.
2787 Produce a shared object which can then be linked with other objects to
2788 form an executable. Not all systems support this option. You must
2789 also specify @samp{-fpic} or @samp{-fPIC} on some systems when
2790 you specify this option.
2793 Bind references to global symbols when building a shared object. Warn
2794 about any unresolved references (unless overridden by the link editor
2795 option @samp{-Xlinker -z -Xlinker defs}). Only a few systems support
2798 @item -Xlinker @var{option}
2799 Pass @var{option} as an option to the linker. You can use this to
2800 supply system-specific linker options which GNU CC does not know how to
2803 If you want to pass an option that takes an argument, you must use
2804 @samp{-Xlinker} twice, once for the option and once for the argument.
2805 For example, to pass @samp{-assert definitions}, you must write
2806 @samp{-Xlinker -assert -Xlinker definitions}. It does not work to write
2807 @samp{-Xlinker "-assert definitions"}, because this passes the entire
2808 string as a single argument, which is not what the linker expects.
2810 @item -Wl,@var{option}
2811 Pass @var{option} as an option to the linker. If @var{option} contains
2812 commas, it is split into multiple options at the commas.
2814 @item -u @var{symbol}
2815 Pretend the symbol @var{symbol} is undefined, to force linking of
2816 library modules to define it. You can use @samp{-u} multiple times with
2817 different symbols to force loading of additional library modules.
2820 @node Directory Options
2821 @section Options for Directory Search
2822 @cindex directory options
2823 @cindex options, directory search
2826 These options specify directories to search for header files, for
2827 libraries and for parts of the compiler:
2831 Add the directory @var{dir} to the head of the list of directories to be
2832 searched for header files. This can be used to override a system header
2833 file, substituting your own version, since these directories are
2834 searched before the system header file directories. If you use more
2835 than one @samp{-I} option, the directories are scanned in left-to-right
2836 order; the standard system directories come after.
2839 Any directories you specify with @samp{-I} options before the @samp{-I-}
2840 option are searched only for the case of @samp{#include "@var{file}"};
2841 they are not searched for @samp{#include <@var{file}>}.
2843 If additional directories are specified with @samp{-I} options after
2844 the @samp{-I-}, these directories are searched for all @samp{#include}
2845 directives. (Ordinarily @emph{all} @samp{-I} directories are used
2848 In addition, the @samp{-I-} option inhibits the use of the current
2849 directory (where the current input file came from) as the first search
2850 directory for @samp{#include "@var{file}"}. There is no way to
2851 override this effect of @samp{-I-}. With @samp{-I.} you can specify
2852 searching the directory which was current when the compiler was
2853 invoked. That is not exactly the same as what the preprocessor does
2854 by default, but it is often satisfactory.
2856 @samp{-I-} does not inhibit the use of the standard system directories
2857 for header files. Thus, @samp{-I-} and @samp{-nostdinc} are
2861 Add directory @var{dir} to the list of directories to be searched
2864 @item -B@var{prefix}
2865 This option specifies where to find the executables, libraries,
2866 include files, and data files of the compiler itself.
2868 The compiler driver program runs one or more of the subprograms
2869 @file{cpp}, @file{cc1}, @file{as} and @file{ld}. It tries
2870 @var{prefix} as a prefix for each program it tries to run, both with and
2871 without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}).
2873 For each subprogram to be run, the compiler driver first tries the
2874 @samp{-B} prefix, if any. If that name is not found, or if @samp{-B}
2875 was not specified, the driver tries two standard prefixes, which are
2876 @file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc-lib/}. If neither of
2877 those results in a file name that is found, the unmodified program
2878 name is searched for using the directories specified in your
2879 @samp{PATH} environment variable.
2881 @samp{-B} prefixes that effectively specify directory names also apply
2882 to libraries in the linker, because the compiler translates these
2883 options into @samp{-L} options for the linker. They also apply to
2884 includes files in the preprocessor, because the compiler translates these
2885 options into @samp{-isystem} options for the preprocessor. In this case,
2886 the compiler appends @samp{include} to the prefix.
2888 The run-time support file @file{libgcc.a} can also be searched for using
2889 the @samp{-B} prefix, if needed. If it is not found there, the two
2890 standard prefixes above are tried, and that is all. The file is left
2891 out of the link if it is not found by those means.
2893 Another way to specify a prefix much like the @samp{-B} prefix is to use
2894 the environment variable @code{GCC_EXEC_PREFIX}. @xref{Environment
2897 @item -specs=@var{file}
2898 Process @var{file} after the compiler reads in the standard @file{specs}
2899 file, in order to override the defaults that the @file{gcc} driver
2900 program uses when determining what switches to pass to @file{cc1},
2901 @file{cc1plus}, @file{as}, @file{ld}, etc. More than one
2902 @samp{-specs=}@var{file} can be specified on the command line, and they
2903 are processed in order, from left to right.
2906 @node Target Options
2907 @section Specifying Target Machine and Compiler Version
2908 @cindex target options
2909 @cindex cross compiling
2910 @cindex specifying machine version
2911 @cindex specifying compiler version and target machine
2912 @cindex compiler version, specifying
2913 @cindex target machine, specifying
2915 By default, GNU CC compiles code for the same type of machine that you
2916 are using. However, it can also be installed as a cross-compiler, to
2917 compile for some other type of machine. In fact, several different
2918 configurations of GNU CC, for different target machines, can be
2919 installed side by side. Then you specify which one to use with the
2922 In addition, older and newer versions of GNU CC can be installed side
2923 by side. One of them (probably the newest) will be the default, but
2924 you may sometimes wish to use another.
2927 @item -b @var{machine}
2928 The argument @var{machine} specifies the target machine for compilation.
2929 This is useful when you have installed GNU CC as a cross-compiler.
2931 The value to use for @var{machine} is the same as was specified as the
2932 machine type when configuring GNU CC as a cross-compiler. For
2933 example, if a cross-compiler was configured with @samp{configure
2934 i386v}, meaning to compile for an 80386 running System V, then you
2935 would specify @samp{-b i386v} to run that cross compiler.
2937 When you do not specify @samp{-b}, it normally means to compile for
2938 the same type of machine that you are using.
2940 @item -V @var{version}
2941 The argument @var{version} specifies which version of GNU CC to run.
2942 This is useful when multiple versions are installed. For example,
2943 @var{version} might be @samp{2.0}, meaning to run GNU CC version 2.0.
2945 The default version, when you do not specify @samp{-V}, is the last
2946 version of GNU CC that you installed.
2949 The @samp{-b} and @samp{-V} options actually work by controlling part of
2950 the file name used for the executable files and libraries used for
2951 compilation. A given version of GNU CC, for a given target machine, is
2952 normally kept in the directory @file{/usr/local/lib/gcc-lib/@var{machine}/@var{version}}.@refill
2954 Thus, sites can customize the effect of @samp{-b} or @samp{-V} either by
2955 changing the names of these directories or adding alternate names (or
2956 symbolic links). If in directory @file{/usr/local/lib/gcc-lib/} the
2957 file @file{80386} is a link to the file @file{i386v}, then @samp{-b
2958 80386} becomes an alias for @samp{-b i386v}.
2960 In one respect, the @samp{-b} or @samp{-V} do not completely change
2961 to a different compiler: the top-level driver program @code{gcc}
2962 that you originally invoked continues to run and invoke the other
2963 executables (preprocessor, compiler per se, assembler and linker)
2964 that do the real work. However, since no real work is done in the
2965 driver program, it usually does not matter that the driver program
2966 in use is not the one for the specified target and version.
2968 The only way that the driver program depends on the target machine is
2969 in the parsing and handling of special machine-specific options.
2970 However, this is controlled by a file which is found, along with the
2971 other executables, in the directory for the specified version and
2972 target machine. As a result, a single installed driver program adapts
2973 to any specified target machine and compiler version.
2975 The driver program executable does control one significant thing,
2976 however: the default version and target machine. Therefore, you can
2977 install different instances of the driver program, compiled for
2978 different targets or versions, under different names.
2980 For example, if the driver for version 2.0 is installed as @code{ogcc}
2981 and that for version 2.1 is installed as @code{gcc}, then the command
2982 @code{gcc} will use version 2.1 by default, while @code{ogcc} will use
2983 2.0 by default. However, you can choose either version with either
2984 command with the @samp{-V} option.
2986 @node Submodel Options
2987 @section Hardware Models and Configurations
2988 @cindex submodel options
2989 @cindex specifying hardware config
2990 @cindex hardware models and configurations, specifying
2991 @cindex machine dependent options
2993 Earlier we discussed the standard option @samp{-b} which chooses among
2994 different installed compilers for completely different target
2995 machines, such as Vax vs. 68000 vs. 80386.
2997 In addition, each of these target machine types can have its own
2998 special options, starting with @samp{-m}, to choose among various
2999 hardware models or configurations---for example, 68010 vs 68020,
3000 floating coprocessor or none. A single installed version of the
3001 compiler can compile for any model or configuration, according to the
3004 Some configurations of the compiler also support additional special
3005 options, usually for compatibility with other compilers on the same
3009 These options are defined by the macro @code{TARGET_SWITCHES} in the
3010 machine description. The default for the options is also defined by
3011 that macro, which enables you to change the defaults.
3026 * RS/6000 and PowerPC Options::
3031 * Intel 960 Options::
3032 * DEC Alpha Options::
3036 * System V Options::
3041 @node M680x0 Options
3042 @subsection M680x0 Options
3043 @cindex M680x0 options
3045 These are the @samp{-m} options defined for the 68000 series. The default
3046 values for these options depends on which style of 68000 was selected when
3047 the compiler was configured; the defaults for the most common choices are
3053 Generate output for a 68000. This is the default
3054 when the compiler is configured for 68000-based systems.
3056 Use this option for microcontrollers with a 68000 or EC000 core,
3057 including the 68008, 68302, 68306, 68307, 68322, 68328 and 68356.
3061 Generate output for a 68020. This is the default
3062 when the compiler is configured for 68020-based systems.
3065 Generate output containing 68881 instructions for floating point.
3066 This is the default for most 68020 systems unless @samp{-nfp} was
3067 specified when the compiler was configured.
3070 Generate output for a 68030. This is the default when the compiler is
3071 configured for 68030-based systems.
3074 Generate output for a 68040. This is the default when the compiler is
3075 configured for 68040-based systems.
3077 This option inhibits the use of 68881/68882 instructions that have to be
3078 emulated by software on the 68040. Use this option if your 68040 does not
3079 have code to emulate those instructions.
3082 Generate output for a 68060. This is the default when the compiler is
3083 configured for 68060-based systems.
3085 This option inhibits the use of 68020 and 68881/68882 instructions that
3086 have to be emulated by software on the 68060. Use this option if your 68060
3087 does not have code to emulate those instructions.
3090 Generate output for a CPU32. This is the default
3091 when the compiler is configured for CPU32-based systems.
3093 Use this option for microcontrollers with a
3094 CPU32 or CPU32+ core, including the 68330, 68331, 68332, 68333, 68334,
3095 68336, 68340, 68341, 68349 and 68360.
3098 Generate output for a 520X "coldfire" family cpu. This is the default
3099 when the compiler is configured for 520X-based systems.
3101 Use this option for microcontroller with a 5200 core, including
3102 the MCF5202, MCF5203, MCF5204 and MCF5202.
3106 Generate output for a 68040, without using any of the new instructions.
3107 This results in code which can run relatively efficiently on either a
3108 68020/68881 or a 68030 or a 68040. The generated code does use the
3109 68881 instructions that are emulated on the 68040.
3112 Generate output for a 68060, without using any of the new instructions.
3113 This results in code which can run relatively efficiently on either a
3114 68020/68881 or a 68030 or a 68040. The generated code does use the
3115 68881 instructions that are emulated on the 68060.
3118 Generate output containing Sun FPA instructions for floating point.
3121 Generate output containing library calls for floating point.
3122 @strong{Warning:} the requisite libraries are not available for all m68k
3123 targets. Normally the facilities of the machine's usual C compiler are
3124 used, but this can't be done directly in cross-compilation. You must
3125 make your own arrangements to provide suitable library functions for
3126 cross-compilation. The embedded targets @samp{m68k-*-aout} and
3127 @samp{m68k-*-coff} do provide software floating point support.
3130 Consider type @code{int} to be 16 bits wide, like @code{short int}.
3133 Do not use the bit-field instructions. The @samp{-m68000}, @samp{-mcpu32}
3134 and @samp{-m5200} options imply @w{@samp{-mnobitfield}}.
3137 Do use the bit-field instructions. The @samp{-m68020} option implies
3138 @samp{-mbitfield}. This is the default if you use a configuration
3139 designed for a 68020.
3142 Use a different function-calling convention, in which functions
3143 that take a fixed number of arguments return with the @code{rtd}
3144 instruction, which pops their arguments while returning. This
3145 saves one instruction in the caller since there is no need to pop
3146 the arguments there.
3148 This calling convention is incompatible with the one normally
3149 used on Unix, so you cannot use it if you need to call libraries
3150 compiled with the Unix compiler.
3152 Also, you must provide function prototypes for all functions that
3153 take variable numbers of arguments (including @code{printf});
3154 otherwise incorrect code will be generated for calls to those
3157 In addition, seriously incorrect code will result if you call a
3158 function with too many arguments. (Normally, extra arguments are
3159 harmlessly ignored.)
3161 The @code{rtd} instruction is supported by the 68010, 68020, 68030,
3162 68040, 68060 and CPU32 processors, but not by the 68000 or 5200.
3165 @itemx -mno-align-int
3166 Control whether GNU CC aligns @code{int}, @code{long}, @code{long long},
3167 @code{float}, @code{double}, and @code{long double} variables on a 32-bit
3168 boundary (@samp{-malign-int}) or a 16-bit boundary (@samp{-mno-align-int}).
3169 Aligning variables on 32-bit boundaries produces code that runs somewhat
3170 faster on processors with 32-bit busses at the expense of more memory.
3172 @strong{Warning:} if you use the @samp{-malign-int} switch, GNU CC will
3173 align structures containing the above types differently than
3174 most published application binary interface specifications for the m68k.
3179 @subsection VAX Options
3182 These @samp{-m} options are defined for the Vax:
3186 Do not output certain jump instructions (@code{aobleq} and so on)
3187 that the Unix assembler for the Vax cannot handle across long
3191 Do output those jump instructions, on the assumption that you
3192 will assemble with the GNU assembler.
3195 Output code for g-format floating point numbers instead of d-format.
3199 @subsection SPARC Options
3200 @cindex SPARC options
3202 These @samp{-m} switches are supported on the SPARC:
3207 Specify @samp{-mapp-regs} to generate output using the global registers
3208 2 through 4, which the SPARC SVR4 ABI reserves for applications. This
3211 To be fully SVR4 ABI compliant at the cost of some performance loss,
3212 specify @samp{-mno-app-regs}. You should compile libraries and system
3213 software with this option.
3217 Generate output containing floating point instructions. This is the
3222 Generate output containing library calls for floating point.
3223 @strong{Warning:} the requisite libraries are not available for all SPARC
3224 targets. Normally the facilities of the machine's usual C compiler are
3225 used, but this cannot be done directly in cross-compilation. You must make
3226 your own arrangements to provide suitable library functions for
3227 cross-compilation. The embedded targets @samp{sparc-*-aout} and
3228 @samp{sparclite-*-*} do provide software floating point support.
3230 @samp{-msoft-float} changes the calling convention in the output file;
3231 therefore, it is only useful if you compile @emph{all} of a program with
3232 this option. In particular, you need to compile @file{libgcc.a}, the
3233 library that comes with GNU CC, with @samp{-msoft-float} in order for
3236 @item -mhard-quad-float
3237 Generate output containing quad-word (long double) floating point
3240 @item -msoft-quad-float
3241 Generate output containing library calls for quad-word (long double)
3242 floating point instructions. The functions called are those specified
3243 in the SPARC ABI. This is the default.
3245 As of this writing, there are no sparc implementations that have hardware
3246 support for the quad-word floating point instructions. They all invoke
3247 a trap handler for one of these instructions, and then the trap handler
3248 emulates the effect of the instruction. Because of the trap handler overhead,
3249 this is much slower than calling the ABI library routines. Thus the
3250 @samp{-msoft-quad-float} option is the default.
3254 With @samp{-mepilogue} (the default), the compiler always emits code for
3255 function exit at the end of each function. Any function exit in
3256 the middle of the function (such as a return statement in C) will
3257 generate a jump to the exit code at the end of the function.
3259 With @samp{-mno-epilogue}, the compiler tries to emit exit code inline
3260 at every function exit.
3264 With @samp{-mflat}, the compiler does not generate save/restore instructions
3265 and will use a "flat" or single register window calling convention.
3266 This model uses %i7 as the frame pointer and is compatible with the normal
3267 register window model. Code from either may be intermixed.
3268 The local registers and the input registers (0-5) are still treated as
3269 "call saved" registers and will be saved on the stack as necessary.
3271 With @samp{-mno-flat} (the default), the compiler emits save/restore
3272 instructions (except for leaf functions) and is the normal mode of operation.
3274 @item -mno-unaligned-doubles
3275 @itemx -munaligned-doubles
3276 Assume that doubles have 8 byte alignment. This is the default.
3278 With @samp{-munaligned-doubles}, GNU CC assumes that doubles have 8 byte
3279 alignment only if they are contained in another type, or if they have an
3280 absolute address. Otherwise, it assumes they have 4 byte alignment.
3281 Specifying this option avoids some rare compatibility problems with code
3282 generated by other compilers. It is not the default because it results
3283 in a performance loss, especially for floating point code.
3287 These two options select variations on the SPARC architecture.
3289 By default (unless specifically configured for the Fujitsu SPARClite),
3290 GCC generates code for the v7 variant of the SPARC architecture.
3292 @samp{-mv8} will give you SPARC v8 code. The only difference from v7
3293 code is that the compiler emits the integer multiply and integer
3294 divide instructions which exist in SPARC v8 but not in SPARC v7.
3296 @samp{-msparclite} will give you SPARClite code. This adds the integer
3297 multiply, integer divide step and scan (@code{ffs}) instructions which
3298 exist in SPARClite but not in SPARC v7.
3300 These options are deprecated and will be deleted in GNU CC 2.9.
3301 They have been replaced with @samp{-mcpu=xxx}.
3305 These two options select the processor for which the code is optimised.
3307 With @samp{-mcypress} (the default), the compiler optimizes code for the
3308 Cypress CY7C602 chip, as used in the SparcStation/SparcServer 3xx series.
3309 This is also appropriate for the older SparcStation 1, 2, IPX etc.
3311 With @samp{-msupersparc} the compiler optimizes code for the SuperSparc cpu, as
3312 used in the SparcStation 10, 1000 and 2000 series. This flag also enables use
3313 of the full SPARC v8 instruction set.
3315 These options are deprecated and will be deleted in GNU CC 2.9.
3316 They have been replaced with @samp{-mcpu=xxx}.
3318 @item -mcpu=@var{cpu_type}
3319 Set the instruction set, register set, and instruction scheduling parameters
3320 for machine type @var{cpu_type}. Supported values for @var{cpu_type} are
3321 @samp{v7}, @samp{cypress}, @samp{v8}, @samp{supersparc}, @samp{sparclite},
3322 @samp{f930}, @samp{f934}, @samp{sparclet}, @samp{tsc701}, @samp{v9}, and
3325 Default instruction scheduling parameters are used for values that select
3326 an architecture and not an implementation. These are @samp{v7}, @samp{v8},
3327 @samp{sparclite}, @samp{sparclet}, @samp{v9}.
3329 Here is a list of each supported architecture and their supported
3335 sparclite: f930, f934
3340 @item -mtune=@var{cpu_type}
3341 Set the instruction scheduling parameters for machine type
3342 @var{cpu_type}, but do not set the instruction set or register set that the
3343 option @samp{-mcpu=}@var{cpu_type} would.
3345 The same values for @samp{-mcpu=}@var{cpu_type} are used for
3346 @samp{-mtune=}@*@var{cpu_type}, though the only useful values are those that
3347 select a particular cpu implementation: @samp{cypress}, @samp{supersparc},
3348 @samp{f930}, @samp{f934}, @samp{tsc701}, @samp{ultrasparc}.
3350 @item -malign-loops=@var{num}
3351 Align loops to a 2 raised to a @var{num} byte boundary. If
3352 @samp{-malign-loops} is not specified, the default is 2.
3354 @item -malign-jumps=@var{num}
3355 Align instructions that are only jumped to to a 2 raised to a @var{num}
3356 byte boundary. If @samp{-malign-jumps} is not specified, the default is 2.
3358 @item -malign-functions=@var{num}
3359 Align the start of functions to a 2 raised to @var{num} byte boundary.
3360 If @samp{-malign-functions} is not specified, the default is 2 if compiling
3361 for 32 bit sparc, and 5 if compiling for 64 bit sparc.
3365 These @samp{-m} switches are supported in addition to the above
3366 on the SPARCLET processor.
3369 @item -mlittle-endian
3370 Generate code for a processor running in little-endian mode.
3373 Treat register @code{%g0} as a normal register.
3374 GCC will continue to clobber it as necessary but will not assume
3375 it always reads as 0.
3377 @item -mbroken-saverestore
3378 Generate code that does not use non-trivial forms of the @code{save} and
3379 @code{restore} instructions. Early versions of the SPARCLET processor do
3380 not correctly handle @code{save} and @code{restore} instructions used with
3381 arguments. They correctly handle them used without arguments. A @code{save}
3382 instruction used without arguments increments the current window pointer
3383 but does not allocate a new stack frame. It is assumed that the window
3384 overflow trap handler will properly handle this case as will interrupt
3388 These @samp{-m} switches are supported in addition to the above
3389 on SPARC V9 processors in 64 bit environments.
3392 @item -mlittle-endian
3393 Generate code for a processor running in little-endian mode.
3397 Generate code for a 32 bit or 64 bit environment.
3398 The 32 bit environment sets int, long and pointer to 32 bits.
3399 The 64 bit environment sets int to 32 bits and long and pointer
3402 @item -mcmodel=medlow
3403 Generate code for the Medium/Low code model: the program must be linked
3404 in the low 32 bits of the address space. Pointers are 64 bits.
3405 Programs can be statically or dynamically linked.
3407 @item -mcmodel=medmid
3408 Generate code for the Medium/Middle code model: the program must be linked
3409 in the low 44 bits of the address space, the text segment must be less than
3410 2G bytes, and data segment must be within 2G of the text segment.
3411 Pointers are 64 bits.
3413 @item -mcmodel=medany
3414 Generate code for the Medium/Anywhere code model: the program may be linked
3415 anywhere in the address space, the text segment must be less than
3416 2G bytes, and data segment must be within 2G of the text segment.
3417 Pointers are 64 bits.
3419 @item -mcmodel=embmedany
3420 Generate code for the Medium/Anywhere code model for embedded systems:
3421 assume a 32 bit text and a 32 bit data segment, both starting anywhere
3422 (determined at link time). Register %g4 points to the base of the
3423 data segment. Pointers still 64 bits.
3424 Programs are statically linked, PIC is not supported.
3427 @itemx -mno-stack-bias
3428 With @samp{-mstack-bias}, GNU CC assumes that the stack pointer, and
3429 frame pointer if present, are offset by -2047 which must be added back
3430 when making stack frame references.
3431 Otherwise, assume no such offset is present.
3434 @node Convex Options
3435 @subsection Convex Options
3436 @cindex Convex options
3438 These @samp{-m} options are defined for Convex:
3442 Generate output for C1. The code will run on any Convex machine.
3443 The preprocessor symbol @code{__convex__c1__} is defined.
3446 Generate output for C2. Uses instructions not available on C1.
3447 Scheduling and other optimizations are chosen for max performance on C2.
3448 The preprocessor symbol @code{__convex_c2__} is defined.
3451 Generate output for C32xx. Uses instructions not available on C1.
3452 Scheduling and other optimizations are chosen for max performance on C32.
3453 The preprocessor symbol @code{__convex_c32__} is defined.
3456 Generate output for C34xx. Uses instructions not available on C1.
3457 Scheduling and other optimizations are chosen for max performance on C34.
3458 The preprocessor symbol @code{__convex_c34__} is defined.
3461 Generate output for C38xx. Uses instructions not available on C1.
3462 Scheduling and other optimizations are chosen for max performance on C38.
3463 The preprocessor symbol @code{__convex_c38__} is defined.
3466 Generate code which puts an argument count in the word preceding each
3467 argument list. This is compatible with regular CC, and a few programs
3468 may need the argument count word. GDB and other source-level debuggers
3469 do not need it; this info is in the symbol table.
3472 Omit the argument count word. This is the default.
3474 @item -mvolatile-cache
3475 Allow volatile references to be cached. This is the default.
3477 @item -mvolatile-nocache
3478 Volatile references bypass the data cache, going all the way to memory.
3479 This is only needed for multi-processor code that does not use standard
3480 synchronization instructions. Making non-volatile references to volatile
3481 locations will not necessarily work.
3484 Type long is 32 bits, the same as type int. This is the default.
3487 Type long is 64 bits, the same as type long long. This option is useless,
3488 because no library support exists for it.
3491 @node AMD29K Options
3492 @subsection AMD29K Options
3493 @cindex AMD29K options
3495 These @samp{-m} options are defined for the AMD Am29000:
3500 @cindex DW bit (29k)
3501 Generate code that assumes the @code{DW} bit is set, i.e., that byte and
3502 halfword operations are directly supported by the hardware. This is the
3507 Generate code that assumes the @code{DW} bit is not set.
3511 @cindex byte writes (29k)
3512 Generate code that assumes the system supports byte and halfword write
3513 operations. This is the default.
3517 Generate code that assumes the systems does not support byte and
3518 halfword write operations. @samp{-mnbw} implies @samp{-mndw}.
3522 @cindex memory model (29k)
3523 Use a small memory model that assumes that all function addresses are
3524 either within a single 256 KB segment or at an absolute address of less
3525 than 256k. This allows the @code{call} instruction to be used instead
3526 of a @code{const}, @code{consth}, @code{calli} sequence.
3530 Use the normal memory model: Generate @code{call} instructions only when
3531 calling functions in the same file and @code{calli} instructions
3532 otherwise. This works if each file occupies less than 256 KB but allows
3533 the entire executable to be larger than 256 KB. This is the default.
3536 Always use @code{calli} instructions. Specify this option if you expect
3537 a single file to compile into more than 256 KB of code.
3541 @cindex processor selection (29k)
3542 Generate code for the Am29050.
3546 Generate code for the Am29000. This is the default.
3548 @item -mkernel-registers
3549 @kindex -mkernel-registers
3550 @cindex kernel and user registers (29k)
3551 Generate references to registers @code{gr64-gr95} instead of to
3552 registers @code{gr96-gr127}. This option can be used when compiling
3553 kernel code that wants a set of global registers disjoint from that used
3556 Note that when this option is used, register names in @samp{-f} flags
3557 must use the normal, user-mode, names.
3559 @item -muser-registers
3560 @kindex -muser-registers
3561 Use the normal set of global registers, @code{gr96-gr127}. This is the
3565 @itemx -mno-stack-check
3566 @kindex -mstack-check
3567 @cindex stack checks (29k)
3568 Insert (or do not insert) a call to @code{__msp_check} after each stack
3569 adjustment. This is often used for kernel code.
3572 @itemx -mno-storem-bug
3573 @kindex -mstorem-bug
3574 @cindex storem bug (29k)
3575 @samp{-mstorem-bug} handles 29k processors which cannot handle the
3576 separation of a mtsrim insn and a storem instruction (most 29000 chips
3577 to date, but not the 29050).
3579 @item -mno-reuse-arg-regs
3580 @itemx -mreuse-arg-regs
3581 @kindex -mreuse-arg-regs
3582 @samp{-mno-reuse-arg-regs} tells the compiler to only use incoming argument
3583 registers for copying out arguments. This helps detect calling a function
3584 with fewer arguments than it was declared with.
3586 @item -mno-impure-text
3587 @itemx -mimpure-text
3588 @kindex -mimpure-text
3589 @samp{-mimpure-text}, used in addition to @samp{-shared}, tells the compiler to
3590 not pass @samp{-assert pure-text} to the linker when linking a shared object.
3593 @kindex -msoft-float
3594 Generate output containing library calls for floating point.
3595 @strong{Warning:} the requisite libraries are not part of GNU CC.
3596 Normally the facilities of the machine's usual C compiler are used, but
3597 this can't be done directly in cross-compilation. You must make your
3598 own arrangements to provide suitable library functions for
3603 @subsection ARM Options
3606 These @samp{-m} options are defined for Advanced RISC Machines (ARM)
3611 @kindex -mapcs-frame
3612 Generate a stack frame that is compliant with the ARM Procedure Call
3613 Standard for all functions, even if this is not strictly necessary for
3614 correct execution of the code. Specifying @samp{-fomit-frame-pointer}
3615 with this option will cause the stack frames not to be generated for
3616 leaf functions. The default is @samp{-mno-apcs-frame}.
3620 This is a synonym for @samp{-mapcs-frame}.
3624 Generate code for a processor running with a 26-bit program counter,
3625 and conforming to the function calling standards for the APCS 26-bit
3626 option. This option replaces the @samp{-m2} and @samp{-m3} options
3627 of previous releases of the compiler.
3631 Generate code for a processor running with a 32-bit program counter,
3632 and conforming to the function calling standards for the APCS 32-bit
3633 option. This option replaces the @samp{-m6} option of previous releases
3636 @item -mapcs-stack-check
3637 @kindex -mapcs-stack-check
3638 @kindex -mno-apcs-stack-check
3639 Generate code to check the amount of stack space available upon entry to
3640 every function (that actually uses some stack space). If there is
3641 insufficient space available then either the function
3642 @samp{__rt_stkovf_split_small} or @samp{__rt_stkovf_split_big} will be
3643 called, depending upon the amount of stack space required. The run time
3644 system is required to provide these functions. The default is
3645 @samp{-mno-apcs-stack-check}, since this produces smaller code.
3648 @kindex -mapcs-float
3649 @kindex -mno-apcs-float
3650 Pass floating point arguments using the float point registers. This is
3651 one of the variants of the APCS. This option is reccommended if the
3652 target hardware has a floating point unit or if a lot of floating point
3653 arithmetic is going to be performed by the code. The default is
3654 @samp{-mno-apcs-float}, since integer only code is slightly increased in
3655 size if @samp{-mapcs-float} is used.
3657 @item -mapcs-reentrant
3658 @kindex -mapcs-reentrant
3659 @kindex -mno-apcs-reentrant
3660 Generate reentrant, position independent code. This is the equivalent
3661 to specifying the @samp{-fpic} option. The default is
3662 @samp{-mno-apcs-reentrant}.
3664 @item -mthumb-interwork
3665 @kindex -mthumb-interwork
3666 @kindex -mno-thumb-interwork
3667 Generate code which supports calling between the ARM and THUMB
3668 instruction sets. Without this option the two instruction sets cannot
3669 be reliably used inside one program. The default is
3670 @samp{-mno-thumb-interwork}, since slightly larger code is generated
3671 when @samp{-mthumb-interwork} is specified.
3673 @item -mno-sched-prolog
3674 @kindex -mno-sched-prolog
3675 @kindex -msched-prolog
3676 Prevent the reordering of instructions in the function prolog, or the
3677 merging of those instruction with the instructions in the function's
3678 body. This means that all functions will start with a recognisable set
3679 of instructions (or in fact one of a chioce from a small set of
3680 different function prologues), and this information can be used to
3681 locate the start if functions inside an executable piece of code. The
3682 default is @samp{-msched-prolog}.
3685 Generate output containing floating point instructions. This is the
3689 Generate output containing library calls for floating point.
3690 @strong{Warning:} the requisite libraries are not available for all ARM
3691 targets. Normally the facilities of the machine's usual C compiler are
3692 used, but this cannot be done directly in cross-compilation. You must make
3693 your own arrangements to provide suitable library functions for
3696 @samp{-msoft-float} changes the calling convention in the output file;
3697 therefore, it is only useful if you compile @emph{all} of a program with
3698 this option. In particular, you need to compile @file{libgcc.a}, the
3699 library that comes with GNU CC, with @samp{-msoft-float} in order for
3702 @item -mlittle-endian
3703 Generate code for a processor running in little-endian mode. This is
3704 the default for all standard configurations.
3707 Generate code for a processor running in big-endian mode; the default is
3708 to compile code for a little-endian processor.
3710 @item -mwords-little-endian
3711 This option only applies when generating code for big-endian processors.
3712 Generate code for a little-endian word order but a big-endian byte
3713 order. That is, a byte order of the form @samp{32107654}. Note: this
3714 option should only be used if you require compatibility with code for
3715 big-endian ARM processors generated by versions of the compiler prior to
3718 @item -mshort-load-bytes
3719 @kindex -mshort-load-bytes
3720 Do not try to load half-words (eg @samp{short}s) by loading a word from
3721 an unaligned address. For some targets the MMU is configured to trap
3722 unaligned loads; use this option to generate code that is safe in these
3725 @item -mno-short-load-bytes
3726 @kindex -mno-short-load-bytes
3727 Use unaligned word loads to load half-words (eg @samp{short}s). This
3728 option produces more efficient code, but the MMU is sometimes configured
3729 to trap these instructions.
3731 @item -mshort-load-words
3732 @kindex -mshort-load-words
3733 This is a synonym for the @samp{-mno-short-load-bytes}.
3735 @item -mno-short-load-words
3736 @kindex -mno-short-load-words
3737 This is a synonym for the @samp{-mshort-load-bytes}.
3741 This option only applies to RISC iX. Emulate the native BSD-mode
3742 compiler. This is the default if @samp{-ansi} is not specified.
3746 This option only applies to RISC iX. Emulate the native X/Open-mode
3749 @item -mno-symrename
3750 @kindex -mno-symrename
3751 This option only applies to RISC iX. Do not run the assembler
3752 post-processor, @samp{symrename}, after code has been assembled.
3753 Normally it is necessary to modify some of the standard symbols in
3754 preparation for linking with the RISC iX C library; this option
3755 suppresses this pass. The post-processor is never run when the
3756 compiler is built for cross-compilation.
3760 This specifies the name of the target ARM processor. GCC uses this name
3761 to determine what kind of instructions it can use when generating
3762 assembly code. Permissable names are: arm2, arm250, arm3, arm6, arm60,
3763 arm600, arm610, arm620, arm7, arm7m, arm7d, arm7dm, arm7di, arm7dmi,
3764 arm70, arm700, arm700i, arm710, arm710c, arm7100, arm7500, arm7500fe,
3765 arm7tdmi, arm8, strongarm, strongarm110
3769 This specifies the name of the target ARM architecture. GCC uses this
3770 name to determine what kind of instructions it can use when generating
3771 assembly code. This option can be used in conjunction with or instead
3772 of the @samp{-mcpu=} option. Permissable names are: armv2, armv2a,
3773 armv3, armv3m, armv4, armv4t
3775 @item -mfpe=<number>
3777 This specifes the version of the floating point emulation available on
3778 the target. Permissable values are 2 and 3.
3780 @item -mstructure-size-boundary=<n>
3781 @kindex -mstructure-size-boundary
3782 The size of all structures and unions will be rounded up to a multiple
3783 of the number of bits set by this option. Permissable values are 8 and
3784 32. The default value varies for different toolchains. For the COFF
3785 targeted toolchain the default value is 8. Specifying the larger number
3786 can produced faster, more efficient code, but can also increase the size
3787 of the program. The two values are potentially incompatible. Code
3788 compiled with one value cannot necessarily expect to work with code or
3789 libraries compiled with the other value, if they exchange information
3790 using structures or unions. Programmers are encouraged to use the 32
3791 value as future versions of the toolchain may default to this value.
3796 @subsection Thumb Options
3797 @cindex Thumb Options
3801 @item -mthumb-interwork
3802 @kindex -mthumb-interwork
3803 @kindex -mno-thumb-interwork
3804 Generate code which supports calling between the THUMB and ARM
3805 instruction sets. Without this option the two instruction sets cannot
3806 be reliably used inside one program. The default is
3807 @samp{-mno-thumb-interwork}, since slightly smaller code is generated
3811 @kindex -mtpcs-frame
3812 @kindex -mno-tpcs-frame
3813 Generate a stack frame that is compliant with the Thumb Procedure Call
3814 Standard for all non-leaf functions. (A leaf function is one that does
3815 not call any other functions). The default is @samp{-mno-apcs-frame}.
3817 @item -mtpcs-leaf-frame
3818 @kindex -mtpcs-leaf-frame
3819 @kindex -mno-tpcs-leaf-frame
3820 Generate a stack frame that is compliant with the Thumb Procedure Call
3821 Standard for all leaf functions. (A leaf function is one that does
3822 not call any other functions). The default is @samp{-mno-apcs-leaf-frame}.
3824 @item -mlittle-endian
3825 @kindex -mlittle-endian
3826 Generate code for a processor running in little-endian mode. This is
3827 the default for all standard configurations.
3830 @kindex -mbig-endian
3831 Generate code for a processor running in big-endian mode.
3833 @item -mstructure-size-boundary=<n>
3834 @kindex -mstructure-size-boundary
3835 The size of all structures and unions will be rounded up to a multiple
3836 of the number of bits set by this option. Permissable values are 8 and
3837 32. The default value varies for different toolchains. For the COFF
3838 targeted toolchain the default value is 8. Specifying the larger number
3839 can produced faster, more efficient code, but can also increase the size
3840 of the program. The two values are potentially incompatible. Code
3841 compiled with one value cannot necessarily expect to work with code or
3842 libraries compiled with the other value, if they exchange information
3843 using structures or unions. Programmers are encouraged to use the 32
3844 value as future versions of the toolchain may default to this value.
3848 @node MN10200 Options
3849 @subsection MN10200 Options
3850 @cindex MN10200 options
3851 These @samp{-m} options are defined for Matsushita MN10200 architectures:
3855 Indicate to the linker that it should perform a relaxation optimization pass
3856 to shorten branches, calls and absolute memory addresses. This option only
3857 has an effect when used on the command line for the final link step.
3859 This option makes symbolic debugging impossible.
3862 @node MN10300 Options
3863 @subsection MN10300 Options
3864 @cindex MN10300 options
3865 These @samp{-m} options are defined for Matsushita MN10300 architectures:
3869 Generate code to avoid bugs in the multiply instructions for the MN10300
3870 processors. This is the default.
3873 Do not generate code to avoid bugs in the multiply instructions for the
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.
3885 @node M32R/D Options
3886 @subsection M32R/D Options
3887 @cindex M32R/D options
3889 These @samp{-m} options are defined for Mitsubishi M32R/D architectures:
3892 @item -mcode-model=small
3893 Assume all objects live in the lower 16MB of memory (so that their addresses
3894 can be loaded with the @code{ld24} instruction), and assume all subroutines
3895 are reachable with the @code{bl} instruction.
3896 This is the default.
3898 The addressability of a particular object can be set with the
3899 @code{model} attribute.
3901 @item -mcode-model=medium
3902 Assume objects may be anywhere in the 32 bit address space (the compiler
3903 will generate @code{seth/add3} instructions to load their addresses), and
3904 assume all subroutines are reachable with the @code{bl} instruction.
3906 @item -mcode-model=large
3907 Assume objects may be anywhere in the 32 bit address space (the compiler
3908 will generate @code{seth/add3} instructions to load their addresses), and
3909 assume subroutines may not be reachable with the @code{bl} instruction
3910 (the compiler will generate the much slower @code{seth/add3/jl}
3911 instruction sequence).
3914 Disable use of the small data area. Variables will be put into
3915 one of @samp{.data}, @samp{bss}, or @samp{.rodata} (unless the
3916 @code{section} attribute has been specified).
3917 This is the default.
3919 The small data area consists of sections @samp{.sdata} and @samp{.sbss}.
3920 Objects may be explicitly put in the small data area with the
3921 @code{section} attribute using one of these sections.
3924 Put small global and static data in the small data area, but do not
3925 generate special code to reference them.
3928 Put small global and static data in the small data area, and generate
3929 special instructions to reference them.
3932 @cindex smaller data references
3933 Put global and static objects less than or equal to @var{num} bytes
3934 into the small data or bss sections instead of the normal data or bss
3935 sections. The default value of @var{num} is 8.
3936 The @samp{-msdata} option must be set to one of @samp{sdata} or @samp{use}
3937 for this option to have any effect.
3939 All modules should be compiled with the same @samp{-G @var{num}} value.
3940 Compiling with different values of @var{num} may or may not work; if it
3941 doesn't the linker will give an error message - incorrect code will not be
3947 @subsection M88K Options
3948 @cindex M88k options
3950 These @samp{-m} options are defined for Motorola 88k architectures:
3955 Generate code that works well on both the m88100 and the
3960 Generate code that works best for the m88100, but that also
3965 Generate code that works best for the m88110, and may not run
3970 Obsolete option to be removed from the next revision.
3973 @item -midentify-revision
3974 @kindex -midentify-revision
3976 @cindex identifying source, compiler (88k)
3977 Include an @code{ident} directive in the assembler output recording the
3978 source file name, compiler name and version, timestamp, and compilation
3981 @item -mno-underscores
3982 @kindex -mno-underscores
3983 @cindex underscores, avoiding (88k)
3984 In assembler output, emit symbol names without adding an underscore
3985 character at the beginning of each name. The default is to use an
3986 underscore as prefix on each name.
3988 @item -mocs-debug-info
3989 @itemx -mno-ocs-debug-info
3990 @kindex -mocs-debug-info
3991 @kindex -mno-ocs-debug-info
3993 @cindex debugging, 88k OCS
3994 Include (or omit) additional debugging information (about registers used
3995 in each stack frame) as specified in the 88open Object Compatibility
3996 Standard, ``OCS''. This extra information allows debugging of code that
3997 has had the frame pointer eliminated. The default for DG/UX, SVr4, and
3998 Delta 88 SVr3.2 is to include this information; other 88k configurations
3999 omit this information by default.
4001 @item -mocs-frame-position
4002 @kindex -mocs-frame-position
4003 @cindex register positions in frame (88k)
4004 When emitting COFF debugging information for automatic variables and
4005 parameters stored on the stack, use the offset from the canonical frame
4006 address, which is the stack pointer (register 31) on entry to the
4007 function. The DG/UX, SVr4, Delta88 SVr3.2, and BCS configurations use
4008 @samp{-mocs-frame-position}; other 88k configurations have the default
4009 @samp{-mno-ocs-frame-position}.
4011 @item -mno-ocs-frame-position
4012 @kindex -mno-ocs-frame-position
4013 @cindex register positions in frame (88k)
4014 When emitting COFF debugging information for automatic variables and
4015 parameters stored on the stack, use the offset from the frame pointer
4016 register (register 30). When this option is in effect, the frame
4017 pointer is not eliminated when debugging information is selected by the
4020 @item -moptimize-arg-area
4021 @itemx -mno-optimize-arg-area
4022 @kindex -moptimize-arg-area
4023 @kindex -mno-optimize-arg-area
4024 @cindex arguments in frame (88k)
4025 Control how function arguments are stored in stack frames.
4026 @samp{-moptimize-arg-area} saves space by optimizing them, but this
4027 conflicts with the 88open specifications. The opposite alternative,
4028 @samp{-mno-optimize-arg-area}, agrees with 88open standards. By default
4029 GNU CC does not optimize the argument area.
4031 @item -mshort-data-@var{num}
4032 @kindex -mshort-data-@var{num}
4033 @cindex smaller data references (88k)
4034 @cindex r0-relative references (88k)
4035 Generate smaller data references by making them relative to @code{r0},
4036 which allows loading a value using a single instruction (rather than the
4037 usual two). You control which data references are affected by
4038 specifying @var{num} with this option. For example, if you specify
4039 @samp{-mshort-data-512}, then the data references affected are those
4040 involving displacements of less than 512 bytes.
4041 @samp{-mshort-data-@var{num}} is not effective for @var{num} greater
4044 @item -mserialize-volatile
4045 @kindex -mserialize-volatile
4046 @itemx -mno-serialize-volatile
4047 @kindex -mno-serialize-volatile
4048 @cindex sequential consistency on 88k
4049 Do, or don't, generate code to guarantee sequential consistency
4050 of volatile memory references. By default, consistency is
4053 The order of memory references made by the MC88110 processor does
4054 not always match the order of the instructions requesting those
4055 references. In particular, a load instruction may execute before
4056 a preceding store instruction. Such reordering violates
4057 sequential consistency of volatile memory references, when there
4058 are multiple processors. When consistency must be guaranteed,
4059 GNU C generates special instructions, as needed, to force
4060 execution in the proper order.
4062 The MC88100 processor does not reorder memory references and so
4063 always provides sequential consistency. However, by default, GNU
4064 C generates the special instructions to guarantee consistency
4065 even when you use @samp{-m88100}, so that the code may be run on an
4066 MC88110 processor. If you intend to run your code only on the
4067 MC88100 processor, you may use @samp{-mno-serialize-volatile}.
4069 The extra code generated to guarantee consistency may affect the
4070 performance of your application. If you know that you can safely
4071 forgo this guarantee, you may use @samp{-mno-serialize-volatile}.
4077 @cindex assembler syntax, 88k
4079 Turn on (@samp{-msvr4}) or off (@samp{-msvr3}) compiler extensions
4080 related to System V release 4 (SVr4). This controls the following:
4084 Which variant of the assembler syntax to emit.
4086 @samp{-msvr4} makes the C preprocessor recognize @samp{#pragma weak}
4087 that is used on System V release 4.
4089 @samp{-msvr4} makes GNU CC issue additional declaration directives used in
4093 @samp{-msvr4} is the default for the m88k-motorola-sysv4 and
4094 m88k-dg-dgux m88k configurations. @samp{-msvr3} is the default for all
4095 other m88k configurations.
4097 @item -mversion-03.00
4098 @kindex -mversion-03.00
4099 This option is obsolete, and is ignored.
4100 @c ??? which asm syntax better for GAS? option there too?
4102 @item -mno-check-zero-division
4103 @itemx -mcheck-zero-division
4104 @kindex -mno-check-zero-division
4105 @kindex -mcheck-zero-division
4106 @cindex zero division on 88k
4107 Do, or don't, generate code to guarantee that integer division by
4108 zero will be detected. By default, detection is guaranteed.
4110 Some models of the MC88100 processor fail to trap upon integer
4111 division by zero under certain conditions. By default, when
4112 compiling code that might be run on such a processor, GNU C
4113 generates code that explicitly checks for zero-valued divisors
4114 and traps with exception number 503 when one is detected. Use of
4115 mno-check-zero-division suppresses such checking for code
4116 generated to run on an MC88100 processor.
4118 GNU C assumes that the MC88110 processor correctly detects all
4119 instances of integer division by zero. When @samp{-m88110} is
4120 specified, both @samp{-mcheck-zero-division} and
4121 @samp{-mno-check-zero-division} are ignored, and no explicit checks for
4122 zero-valued divisors are generated.
4124 @item -muse-div-instruction
4125 @kindex -muse-div-instruction
4126 @cindex divide instruction, 88k
4127 Use the div instruction for signed integer division on the
4128 MC88100 processor. By default, the div instruction is not used.
4130 On the MC88100 processor the signed integer division instruction
4131 div) traps to the operating system on a negative operand. The
4132 operating system transparently completes the operation, but at a
4133 large cost in execution time. By default, when compiling code
4134 that might be run on an MC88100 processor, GNU C emulates signed
4135 integer division using the unsigned integer division instruction
4136 divu), thereby avoiding the large penalty of a trap to the
4137 operating system. Such emulation has its own, smaller, execution
4138 cost in both time and space. To the extent that your code's
4139 important signed integer division operations are performed on two
4140 nonnegative operands, it may be desirable to use the div
4141 instruction directly.
4143 On the MC88110 processor the div instruction (also known as the
4144 divs instruction) processes negative operands without trapping to
4145 the operating system. When @samp{-m88110} is specified,
4146 @samp{-muse-div-instruction} is ignored, and the div instruction is used
4147 for signed integer division.
4149 Note that the result of dividing INT_MIN by -1 is undefined. In
4150 particular, the behavior of such a division with and without
4151 @samp{-muse-div-instruction} may differ.
4153 @item -mtrap-large-shift
4154 @itemx -mhandle-large-shift
4155 @kindex -mtrap-large-shift
4156 @kindex -mhandle-large-shift
4157 @cindex bit shift overflow (88k)
4158 @cindex large bit shifts (88k)
4159 Include code to detect bit-shifts of more than 31 bits; respectively,
4160 trap such shifts or emit code to handle them properly. By default GNU CC
4161 makes no special provision for large bit shifts.
4163 @item -mwarn-passed-structs
4164 @kindex -mwarn-passed-structs
4165 @cindex structure passing (88k)
4166 Warn when a function passes a struct as an argument or result.
4167 Structure-passing conventions have changed during the evolution of the C
4168 language, and are often the source of portability problems. By default,
4169 GNU CC issues no such warning.
4172 @node RS/6000 and PowerPC Options
4173 @subsection IBM RS/6000 and PowerPC Options
4174 @cindex RS/6000 and PowerPC Options
4175 @cindex IBM RS/6000 and PowerPC Options
4177 These @samp{-m} options are defined for the IBM RS/6000 and PowerPC:
4185 @itemx -mpowerpc-gpopt
4186 @itemx -mno-powerpc-gpopt
4187 @itemx -mpowerpc-gfxopt
4188 @itemx -mno-powerpc-gfxopt
4190 @itemx -mno-powerpc64
4194 @kindex -mpowerpc-gpopt
4195 @kindex -mpowerpc-gfxopt
4197 GNU CC supports two related instruction set architectures for the
4198 RS/6000 and PowerPC. The @dfn{POWER} instruction set are those
4199 instructions supported by the @samp{rios} chip set used in the original
4200 RS/6000 systems and the @dfn{PowerPC} instruction set is the
4201 architecture of the Motorola MPC5xx, MPC6xx, MPC8xx microprocessors, and
4202 the IBM 4xx microprocessors.
4204 Neither architecture is a subset of the other. However there is a
4205 large common subset of instructions supported by both. An MQ
4206 register is included in processors supporting the POWER architecture.
4208 You use these options to specify which instructions are available on the
4209 processor you are using. The default value of these options is
4210 determined when configuring GNU CC. Specifying the
4211 @samp{-mcpu=@var{cpu_type}} overrides the specification of these
4212 options. We recommend you use the @samp{-mcpu=@var{cpu_type}} option
4213 rather than the options listed above.
4215 The @samp{-mpower} option allows GNU CC to generate instructions that
4216 are found only in the POWER architecture and to use the MQ register.
4217 Specifying @samp{-mpower2} implies @samp{-power} and also allows GNU CC
4218 to generate instructions that are present in the POWER2 architecture but
4219 not the original POWER architecture.
4221 The @samp{-mpowerpc} option allows GNU CC to generate instructions that
4222 are found only in the 32-bit subset of the PowerPC architecture.
4223 Specifying @samp{-mpowerpc-gpopt} implies @samp{-mpowerpc} and also allows
4224 GNU CC to use the optional PowerPC architecture instructions in the
4225 General Purpose group, including floating-point square root. Specifying
4226 @samp{-mpowerpc-gfxopt} implies @samp{-mpowerpc} and also allows GNU CC to
4227 use the optional PowerPC architecture instructions in the Graphics
4228 group, including floating-point select.
4230 The @samp{-mpowerpc64} option allows GNU CC to generate the additional
4231 64-bit instructions that are found in the full PowerPC64 architecture
4232 and to treat GPRs as 64-bit, doubleword quantities. GNU CC defaults to
4233 @samp{-mno-powerpc64}.
4235 If you specify both @samp{-mno-power} and @samp{-mno-powerpc}, GNU CC
4236 will use only the instructions in the common subset of both
4237 architectures plus some special AIX common-mode calls, and will not use
4238 the MQ register. Specifying both @samp{-mpower} and @samp{-mpowerpc}
4239 permits GNU CC to use any instruction from either architecture and to
4240 allow use of the MQ register; specify this for the Motorola MPC601.
4242 @item -mnew-mnemonics
4243 @itemx -mold-mnemonics
4244 @kindex -mnew-mnemonics
4245 @kindex -mold-mnemonics
4246 Select which mnemonics to use in the generated assembler code.
4247 @samp{-mnew-mnemonics} requests output that uses the assembler mnemonics
4248 defined for the PowerPC architecture, while @samp{-mold-mnemonics}
4249 requests the assembler mnemonics defined for the POWER architecture.
4250 Instructions defined in only one architecture have only one mnemonic;
4251 GNU CC uses that mnemonic irrespective of which of these options is
4254 GNU CC defaults to the mnemonics appropriate for the architecture in
4255 use. Specifying @samp{-mcpu=@var{cpu_type}} sometimes overrides the
4256 value of these option. Unless you are building a cross-compiler, you
4257 should normally not specify either @samp{-mnew-mnemonics} or
4258 @samp{-mold-mnemonics}, but should instead accept the default.
4260 @item -mcpu=@var{cpu_type}
4262 Set architecture type, register usage, choice of mnemonics, and
4263 instruction scheduling parameters for machine type @var{cpu_type}.
4264 Supported values for @var{cpu_type} are @samp{rs6000}, @samp{rios1},
4265 @samp{rios2}, @samp{rsc}, @samp{601}, @samp{602}, @samp{603},
4266 @samp{603e}, @samp{604}, @samp{604e}, @samp{620}, @samp{power},
4267 @samp{power2}, @samp{powerpc}, @samp{403}, @samp{505}, @samp{801},
4268 @samp{821}, @samp{823}, and @samp{860} and @samp{common}.
4269 @samp{-mcpu=power}, @samp{-mcpu=power2}, and @samp{-mcpu=powerpc}
4270 specify generic POWER, POWER2 and pure PowerPC (i.e., not MPC601)
4271 architecture machine types, with an appropriate, generic processor model
4272 assumed for scheduling purposes.@refill
4274 @c overfull hbox here --bob 22 jul96
4275 @c original text between ignore ... end ignore
4277 Specifying any of the @samp{-mcpu=rios1}, @samp{-mcpu=rios2},
4278 @samp{-mcpu=rsc}, @samp{-mcpu=power}, or @samp{-mcpu=power2} options
4279 enables the @samp{-mpower} option and disables the @samp{-mpowerpc}
4280 option; @samp{-mcpu=601} enables both the @samp{-mpower} and
4281 @samp{-mpowerpc} options; all of @samp{-mcpu=602}, @samp{-mcpu=603},
4282 @samp{-mcpu=603e}, @samp{-mcpu=604}, @samp{-mcpu=604e},
4283 @samp{-mcpu=620}, @samp{-mcpu=403}, @samp{-mcpu=505}, @samp{-mcpu=801},
4284 @samp{-mcpu=821}, @samp{-mcpu=823}, @samp{-mcpu=860} and
4285 @samp{-mcpu=powerpc} enable the @samp{-mpowerpc} option and disable the
4286 @samp{-mpower} option; @samp{-mcpu=common} disables both the
4287 @samp{-mpower} and @samp{-mpowerpc} options.@refill
4289 @c changed paragraph
4290 Specifying any of the following options:
4291 @samp{-mcpu=rios1}, @samp{-mcpu=rios2}, @samp{-mcpu=rsc},
4292 @samp{-mcpu=power}, or @samp{-mcpu=power2}
4293 enables the @samp{-mpower} option and disables the @samp{-mpowerpc} option;
4294 @samp{-mcpu=601} enables both the @samp{-mpower} and @samp{-mpowerpc} options.
4295 All of @samp{-mcpu=602}, @samp{-mcpu=603}, @samp{-mcpu=603e},
4296 @samp{-mcpu=604}, @samp{-mcpu=620},
4297 enable the @samp{-mpowerpc} option and disable the @samp{-mpower} option.
4298 Exactly similarly, all of @samp{-mcpu=403},
4299 @samp{-mcpu=505}, @samp{-mcpu=821}, @samp{-mcpu=860} and @samp{-mcpu=powerpc}
4300 enable the @samp{-mpowerpc} option and disable the @samp{-mpower} option.
4301 @samp{-mcpu=common} disables both the
4302 @samp{-mpower} and @samp{-mpowerpc} options.@refill
4303 @c end changes to prevent overfull hboxes
4305 AIX versions 4 or greater selects @samp{-mcpu=common} by default, so
4306 that code will operate on all members of the RS/6000 and PowerPC
4307 families. In that case, GNU CC will use only the instructions in the
4308 common subset of both architectures plus some special AIX common-mode
4309 calls, and will not use the MQ register. GNU CC assumes a generic
4310 processor model for scheduling purposes.
4312 Specifying any of the options @samp{-mcpu=rios1}, @samp{-mcpu=rios2},
4313 @samp{-mcpu=rsc}, @samp{-mcpu=power}, or @samp{-mcpu=power2} also
4314 disables the @samp{new-mnemonics} option. Specifying @samp{-mcpu=601},
4315 @samp{-mcpu=602}, @samp{-mcpu=603}, @samp{-mcpu=603e}, @samp{-mcpu=604},
4316 @samp{620}, @samp{403}, or @samp{-mcpu=powerpc} also enables the
4317 @samp{new-mnemonics} option.@refill
4319 Specifying @samp{-mcpu=403}, @samp{-mcpu=821}, or @samp{-mcpu=860} also
4320 enables the @samp{-msoft-float} option.
4322 @item -mtune=@var{cpu_type}
4323 Set the instruction scheduling parameters for machine type
4324 @var{cpu_type}, but do not set the architecture type, register usage,
4325 choice of mnemonics like @samp{-mcpu=}@var{cpu_type} would. The same
4326 values for @var{cpu_type} are used for @samp{-mtune=}@var{cpu_type} as
4327 for @samp{-mcpu=}@var{cpu_type}. The @samp{-mtune=}@var{cpu_type}
4328 option overrides the @samp{-mcpu=}@var{cpu_type} option in terms of
4329 instruction scheduling parameters.
4332 @itemx -mno-fp-in-toc
4333 @itemx -mno-sum-in-toc
4334 @itemx -mminimal-toc
4335 @kindex -mminimal-toc
4336 Modify generation of the TOC (Table Of Contents), which is created for
4337 every executable file. The @samp{-mfull-toc} option is selected by
4338 default. In that case, GNU CC will allocate at least one TOC entry for
4339 each unique non-automatic variable reference in your program. GNU CC
4340 will also place floating-point constants in the TOC. However, only
4341 16,384 entries are available in the TOC.
4343 If you receive a linker error message that saying you have overflowed
4344 the available TOC space, you can reduce the amount of TOC space used
4345 with the @samp{-mno-fp-in-toc} and @samp{-mno-sum-in-toc} options.
4346 @samp{-mno-fp-in-toc} prevents GNU CC from putting floating-point
4347 constants in the TOC and @samp{-mno-sum-in-toc} forces GNU CC to
4348 generate code to calculate the sum of an address and a constant at
4349 run-time instead of putting that sum into the TOC. You may specify one
4350 or both of these options. Each causes GNU CC to produce very slightly
4351 slower and larger code at the expense of conserving TOC space.
4353 If you still run out of space in the TOC even when you specify both of
4354 these options, specify @samp{-mminimal-toc} instead. This option causes
4355 GNU CC to make only one TOC entry for every file. When you specify this
4356 option, GNU CC will produce code that is slower and larger but which
4357 uses extremely little TOC space. You may wish to use this option
4358 only on files that contain less frequently executed code. @refill
4364 Enable AIX 64-bit ABI and calling convention: 64-bit pointers, 64-bit
4365 @code{long} type, and the infrastructure needed to support them.
4366 Specifying @samp{-maix64} implies @samp{-mpowerpc64} and
4367 @samp{-mpowerpc}, while @samp{-maix32} disables the 64-bit ABI and
4368 implies @samp{-mno-powerpc64}. GNU CC defaults to @samp{-maix32}.
4373 On AIX, pass floating-point arguments to prototyped functions beyond the
4374 register save area (RSA) on the stack in addition to argument FPRs. The
4375 AIX calling convention was extended but not initially documented to
4376 handle an obscure K&R C case of calling a function that takes the
4377 address of its arguments with fewer arguments than declared. AIX XL
4378 compilers access floating point arguments which do not fit in the
4379 RSA from the stack when a subroutine is compiled without
4380 optimization. Because always storing floating-point arguments on the
4381 stack is inefficient and rarely needed, this option is not enabled by
4382 default and only is necessary when calling subroutines compiled by AIX
4383 XL compilers without optimization.
4387 Support @dfn{AIX Threads}. Link an application written to use
4388 @dfn{pthreads} with special libraries and startup code to enable the
4393 Support @dfn{IBM RS/6000 SP} @dfn{Parallel Environment} (PE). Link an
4394 application written to use message passing with special startup code to
4395 enable the application to run. The system must have PE installed in the
4396 standard location (@file{/usr/lpp/ppe.poe/}), or the @file{specs} file
4397 must be overridden with the @samp{-specs=} option to specify the
4398 appropriate directory location. The Parallel Environment does not
4399 support threads, so the @samp{-mpe} option and the @samp{-mthreads}
4400 option are incompatible.
4404 @kindex -msoft-float
4405 Generate code that does not use (uses) the floating-point register set.
4406 Software floating point emulation is provided if you use the
4407 @samp{-msoft-float} option, and pass the option to GNU CC when linking.
4410 @itemx -mno-multiple
4411 Generate code that uses (does not use) the load multiple word
4412 instructions and the store multiple word instructions. These
4413 instructions are generated by default on POWER systems, and not
4414 generated on PowerPC systems. Do not use @samp{-mmultiple} on little
4415 endian PowerPC systems, since those instructions do not work when the
4416 processor is in little endian mode.
4421 Generate code that uses (does not use) the load string instructions and the
4422 store string word instructions to save multiple registers and do small block
4423 moves. These instructions are generated by default on POWER systems, and not
4424 generated on PowerPC systems. Do not use @samp{-mstring} on little endian
4425 PowerPC systems, since those instructions do not work when the processor is in
4431 Generate code that uses (does not use) the load or store instructions
4432 that update the base register to the address of the calculated memory
4433 location. These instructions are generated by default. If you use
4434 @samp{-mno-update}, there is a small window between the time that the
4435 stack pointer is updated and the address of the previous frame is
4436 stored, which means code that walks the stack frame across interrupts or
4437 signals may get corrupted data.
4440 @itemx -mno-fused-madd
4441 @kindex -mfused-madd
4442 Generate code that uses (does not use) the floating point multiply and
4443 accumulate instructions. These instructions are generated by default if
4444 hardware floating is used.
4446 @item -mno-bit-align
4449 On System V.4 and embedded PowerPC systems do not (do) force structures
4450 and unions that contain bit fields to be aligned to the base type of the
4453 For example, by default a structure containing nothing but 8
4454 @code{unsigned} bitfields of length 1 would be aligned to a 4 byte
4455 boundary and have a size of 4 bytes. By using @samp{-mno-bit-align},
4456 the structure would be aligned to a 1 byte boundary and be one byte in
4459 @item -mno-strict-align
4460 @itemx -mstrict-align
4461 @kindex -mstrict-align
4462 On System V.4 and embedded PowerPC systems do not (do) assume that
4463 unaligned memory references will be handled by the system.
4466 @itemx -mno-relocatable
4467 @kindex -mrelocatable
4468 On embedded PowerPC systems generate code that allows (does not allow)
4469 the program to be relocated to a different address at runtime. If you
4470 use @samp{-mrelocatable} on any module, all objects linked together must
4471 be compiled with @samp{-mrelocatable} or @samp{-mrelocatable-lib}.
4473 @item -mrelocatable-lib
4474 @itemx -mno-relocatable-lib
4475 On embedded PowerPC systems generate code that allows (does not allow)
4476 the program to be relocated to a different address at runtime. Modules
4477 compiled with @samp{-mrelocatable-lib} can be linked with either modules
4478 compiled without @samp{-mrelocatable} and @samp{-mrelocatable-lib} or
4479 with modules compiled with the @samp{-mrelocatable} options.
4483 On System V.4 and embedded PowerPC systems do not (do) assume that
4484 register 2 contains a pointer to a global area pointing to the addresses
4485 used in the program.
4488 @itemx -mlittle-endian
4489 On System V.4 and embedded PowerPC systems compile code for the
4490 processor in little endian mode. The @samp{-mlittle-endian} option is
4491 the same as @samp{-mlittle}.
4495 On System V.4 and embedded PowerPC systems compile code for the
4496 processor in big endian mode. The @samp{-mbig-endian} option is
4497 the same as @samp{-mbig}.
4500 On System V.4 and embedded PowerPC systems compile code using calling
4501 conventions that adheres to the March 1995 draft of the System V
4502 Application Binary Interface, PowerPC processor supplement. This is the
4503 default unless you configured GCC using @samp{powerpc-*-eabiaix}.
4505 @item -mcall-sysv-eabi
4506 Specify both @samp{-mcall-sysv} and @samp{-meabi} options.
4508 @item -mcall-sysv-noeabi
4509 Specify both @samp{-mcall-sysv} and @samp{-mno-eabi} options.
4512 On System V.4 and embedded PowerPC systems compile code using calling
4513 conventions that are similar to those used on AIX. This is the
4514 default if you configured GCC using @samp{powerpc-*-eabiaix}.
4516 @item -mcall-solaris
4517 On System V.4 and embedded PowerPC systems compile code for the Solaris
4521 On System V.4 and embedded PowerPC systems compile code for the
4522 Linux-based GNU system.
4525 @itemx -mno-prototype
4526 On System V.4 and embedded PowerPC systems assume that all calls to
4527 variable argument functions are properly prototyped. Otherwise, the
4528 compiler must insert an instruction before every non prototyped call to
4529 set or clear bit 6 of the condition code register (@var{CR}) to
4530 indicate whether floating point values were passed in the floating point
4531 registers in case the function takes a variable arguments. With
4532 @samp{-mprototype}, only calls to prototyped variable argument functions
4533 will set or clear the bit.
4536 On embedded PowerPC systems, assume that the startup module is called
4537 @file{sim-crt0.o} and that the standard C libraries are @file{libsim.a} and
4538 @file{libc.a}. This is the default for @samp{powerpc-*-eabisim}.
4542 On embedded PowerPC systems, assume that the startup module is called
4543 @file{crt0.o} and the standard C libraries are @file{libmvme.a} and
4547 On embedded PowerPC systems, assume that the startup module is called
4548 @file{crt0.o} and the standard C libraries are @file{libads.a} and
4552 On embedded PowerPC systems, assume that the startup module is called
4553 @file{crt0.o} and the standard C libraries are @file{libyk.a} and
4557 On embedded PowerPC systems, set the @var{PPC_EMB} bit in the ELF flags
4558 header to indicate that @samp{eabi} extended relocations are used.
4562 On System V.4 and embedded PowerPC systems do (do not) adhere to the
4563 Embedded Applications Binary Interface (eabi) which is a set of
4564 modifications to the System V.4 specifications. Selecting @code{-meabi}
4565 means that the stack is aligned to an 8 byte boundary, a function
4566 @code{__eabi} is called to from @code{main} to set up the eabi
4567 environment, and the @samp{-msdata} option can use both @code{r2} and
4568 @code{r13} to point to two separate small data areas. Selecting
4569 @code{-mno-eabi} means that the stack is aligned to a 16 byte boundary,
4570 do not call an initialization function from @code{main}, and the
4571 @samp{-msdata} option will only use @code{r13} to point to a single
4572 small data area. The @samp{-meabi} option is on by default if you
4573 configured GCC using one of the @samp{powerpc*-*-eabi*} options.
4576 On System V.4 and embedded PowerPC systems, put small initialized
4577 @code{const} global and static data in the @samp{.sdata2} section, which
4578 is pointed to by register @code{r2}. Put small initialized
4579 non-@code{const} global and static data in the @samp{.sdata} section,
4580 which is pointed to by register @code{r13}. Put small uninitialized
4581 global and static data in the @samp{.sbss} section, which is adjacent to
4582 the @samp{.sdata} section. The @samp{-msdata=eabi} option is
4583 incompatible with the @samp{-mrelocatable} option. The
4584 @samp{-msdata=eabi} option also sets the @samp{-memb} option.
4587 On System V.4 and embedded PowerPC systems, put small global and static
4588 data in the @samp{.sdata} section, which is pointed to by register
4589 @code{r13}. Put small uninitialized global and static data in the
4590 @samp{.sbss} section, which is adjacent to the @samp{.sdata} section.
4591 The @samp{-msdata=sysv} option is incompatible with the
4592 @samp{-mrelocatable} option.
4594 @item -msdata=default
4596 On System V.4 and embedded PowerPC systems, if @samp{-meabi} is used,
4597 compile code the same as @samp{-msdata=eabi}, otherwise compile code the
4598 same as @samp{-msdata=sysv}.
4601 On System V.4 and embedded PowerPC systems, put small global and static
4602 data in the @samp{.sdata} section. Put small uninitialized global and
4603 static data in the @samp{.sbss} section. Do not use register @code{r13}
4604 to address small data however. This is the default behavior unless
4605 other @samp{-msdata} options are used.
4609 On embedded PowerPC systems, put all initialized global and static data
4610 in the @samp{.data} section, and all uninitialized data in the
4611 @samp{.bss} section.
4614 @cindex smaller data references (PowerPC)
4615 @cindex .sdata/.sdata2 references (PowerPC)
4616 On embedded PowerPC systems, put global and static items less than or
4617 equal to @var{num} bytes into the small data or bss sections instead of
4618 the normal data or bss section. By default, @var{num} is 8. The
4619 @samp{-G @var{num}} switch is also passed to the linker.
4620 All modules should be compiled with the same @samp{-G @var{num}} value.
4623 @itemx -mno-regnames
4624 On System V.4 and embedded PowerPC systems do (do not) emit register
4625 names in the assembly language output using symbolic forms.
4628 @subsection IBM RT Options
4630 @cindex IBM RT options
4632 These @samp{-m} options are defined for the IBM RT PC:
4636 Use an in-line code sequence for integer multiplies. This is the
4639 @item -mcall-lib-mul
4640 Call @code{lmul$$} for integer multiples.
4642 @item -mfull-fp-blocks
4643 Generate full-size floating point data blocks, including the minimum
4644 amount of scratch space recommended by IBM. This is the default.
4646 @item -mminimum-fp-blocks
4647 Do not include extra scratch space in floating point data blocks. This
4648 results in smaller code, but slower execution, since scratch space must
4649 be allocated dynamically.
4651 @cindex @file{varargs.h} and RT PC
4652 @cindex @file{stdarg.h} and RT PC
4653 @item -mfp-arg-in-fpregs
4654 Use a calling sequence incompatible with the IBM calling convention in
4655 which floating point arguments are passed in floating point registers.
4656 Note that @code{varargs.h} and @code{stdargs.h} will not work with
4657 floating point operands if this option is specified.
4659 @item -mfp-arg-in-gregs
4660 Use the normal calling convention for floating point arguments. This is
4663 @item -mhc-struct-return
4664 Return structures of more than one word in memory, rather than in a
4665 register. This provides compatibility with the MetaWare HighC (hc)
4666 compiler. Use the option @samp{-fpcc-struct-return} for compatibility
4667 with the Portable C Compiler (pcc).
4669 @item -mnohc-struct-return
4670 Return some structures of more than one word in registers, when
4671 convenient. This is the default. For compatibility with the
4672 IBM-supplied compilers, use the option @samp{-fpcc-struct-return} or the
4673 option @samp{-mhc-struct-return}.
4677 @subsection MIPS Options
4678 @cindex MIPS options
4680 These @samp{-m} options are defined for the MIPS family of computers:
4683 @item -mcpu=@var{cpu type}
4684 Assume the defaults for the machine type @var{cpu type} when scheduling
4685 instructions. The choices for @var{cpu type} are @samp{r2000}, @samp{r3000},
4686 @samp{r4000}, @samp{r4400}, @samp{r4600}, and @samp{r6000}. While picking a
4687 specific @var{cpu type} will schedule things appropriately for that
4688 particular chip, the compiler will not generate any code that does not
4689 meet level 1 of the MIPS ISA (instruction set architecture) without
4690 the @samp{-mips2} or @samp{-mips3} switches being used.
4693 Issue instructions from level 1 of the MIPS ISA. This is the default.
4694 @samp{r3000} is the default @var{cpu type} at this ISA level.
4697 Issue instructions from level 2 of the MIPS ISA (branch likely, square
4698 root instructions). @samp{r6000} is the default @var{cpu type} at this
4702 Issue instructions from level 3 of the MIPS ISA (64 bit instructions).
4703 @samp{r4000} is the default @var{cpu type} at this ISA level.
4704 This option does not change the sizes of any of the C data types.
4707 Issue instructions from level 4 of the MIPS ISA. @samp{r8000} is the
4708 default @var{cpu type} at this ISA level.
4711 Assume that 32 32-bit floating point registers are available. This is
4715 Assume that 32 64-bit floating point registers are available. This is
4716 the default when the @samp{-mips3} option is used.
4719 Assume that 32 32-bit general purpose registers are available. This is
4723 Assume that 32 64-bit general purpose registers are available. This is
4724 the default when the @samp{-mips3} option is used.
4727 Types long, int, and pointer are 64 bits. This works only if @samp{-mips3}
4731 Types long and pointer are 64 bits, and type int is 32 bits.
4732 This works only if @samp{-mips3} is also specified.
4738 Generate code for the indicated ABI.
4741 Generate code for the MIPS assembler, and invoke @file{mips-tfile} to
4742 add normal debug information. This is the default for all
4743 platforms except for the OSF/1 reference platform, using the OSF/rose
4744 object format. If the either of the @samp{-gstabs} or @samp{-gstabs+}
4745 switches are used, the @file{mips-tfile} program will encapsulate the
4746 stabs within MIPS ECOFF.
4749 Generate code for the GNU assembler. This is the default on the OSF/1
4750 reference platform, using the OSF/rose object format. Also, this is
4751 the default if the configure option @samp{--with-gnu-as} is used.
4753 @item -msplit-addresses
4754 @itemx -mno-split-addresses
4755 Generate code to load the high and low parts of address constants separately.
4756 This allows @code{gcc} to optimize away redundant loads of the high order
4757 bits of addresses. This optimization requires GNU as and GNU ld.
4758 This optimization is enabled by default for some embedded targets where
4759 GNU as and GNU ld are standard.
4763 The @samp{-mrnames} switch says to output code using the MIPS software
4764 names for the registers, instead of the hardware names (ie, @var{a0}
4765 instead of @var{$4}). The only known assembler that supports this option
4766 is the Algorithmics assembler.
4770 The @samp{-mgpopt} switch says to write all of the data declarations
4771 before the instructions in the text section, this allows the MIPS
4772 assembler to generate one word memory references instead of using two
4773 words for short global or static data items. This is on by default if
4774 optimization is selected.
4778 For each non-inline function processed, the @samp{-mstats} switch
4779 causes the compiler to emit one line to the standard error file to
4780 print statistics about the program (number of registers saved, stack
4785 The @samp{-mmemcpy} switch makes all block moves call the appropriate
4786 string function (@samp{memcpy} or @samp{bcopy}) instead of possibly
4787 generating inline code.
4790 @itemx -mno-mips-tfile
4791 The @samp{-mno-mips-tfile} switch causes the compiler not
4792 postprocess the object file with the @file{mips-tfile} program,
4793 after the MIPS assembler has generated it to add debug support. If
4794 @file{mips-tfile} is not run, then no local variables will be
4795 available to the debugger. In addition, @file{stage2} and
4796 @file{stage3} objects will have the temporary file names passed to the
4797 assembler embedded in the object file, which means the objects will
4798 not compare the same. The @samp{-mno-mips-tfile} switch should only
4799 be used when there are bugs in the @file{mips-tfile} program that
4800 prevents compilation.
4803 Generate output containing library calls for floating point.
4804 @strong{Warning:} the requisite libraries are not part of GNU CC.
4805 Normally the facilities of the machine's usual C compiler are used, but
4806 this can't be done directly in cross-compilation. You must make your
4807 own arrangements to provide suitable library functions for
4811 Generate output containing floating point instructions. This is the
4812 default if you use the unmodified sources.
4815 @itemx -mno-abicalls
4816 Emit (or do not emit) the pseudo operations @samp{.abicalls},
4817 @samp{.cpload}, and @samp{.cprestore} that some System V.4 ports use for
4818 position independent code.
4821 @itemx -mno-long-calls
4822 Do all calls with the @samp{JALR} instruction, which requires
4823 loading up a function's address into a register before the call.
4824 You need to use this switch, if you call outside of the current
4825 512 megabyte segment to functions that are not through pointers.
4828 @itemx -mno-half-pic
4829 Put pointers to extern references into the data section and load them
4830 up, rather than put the references in the text section.
4832 @item -membedded-pic
4833 @itemx -mno-embedded-pic
4834 Generate PIC code suitable for some embedded systems. All calls are
4835 made using PC relative address, and all data is addressed using the $gp
4836 register. No more than 65536 bytes of global data may be used. This
4837 requires GNU as and GNU ld which do most of the work. This currently
4838 only works on targets which use ECOFF; it does not work with ELF.
4840 @item -membedded-data
4841 @itemx -mno-embedded-data
4842 Allocate variables to the read-only data section first if possible, then
4843 next in the small data section if possible, otherwise in data. This gives
4844 slightly slower code than the default, but reduces the amount of RAM required
4845 when executing, and thus may be preferred for some embedded systems.
4847 @item -msingle-float
4848 @itemx -mdouble-float
4849 The @samp{-msingle-float} switch tells gcc to assume that the floating
4850 point coprocessor only supports single precision operations, as on the
4851 @samp{r4650} chip. The @samp{-mdouble-float} switch permits gcc to use
4852 double precision operations. This is the default.
4856 Permit use of the @samp{mad}, @samp{madu} and @samp{mul} instructions,
4857 as on the @samp{r4650} chip.
4860 Turns on @samp{-msingle-float}, @samp{-mmad}, and, at least for now,
4864 Compile code for the processor in little endian mode.
4865 The requisite libraries are assumed to exist.
4868 Compile code for the processor in big endian mode.
4869 The requisite libraries are assumed to exist.
4872 @cindex smaller data references (MIPS)
4873 @cindex gp-relative references (MIPS)
4874 Put global and static items less than or equal to @var{num} bytes into
4875 the small data or bss sections instead of the normal data or bss
4876 section. This allows the assembler to emit one word memory reference
4877 instructions based on the global pointer (@var{gp} or @var{$28}),
4878 instead of the normal two words used. By default, @var{num} is 8 when
4879 the MIPS assembler is used, and 0 when the GNU assembler is used. The
4880 @samp{-G @var{num}} switch is also passed to the assembler and linker.
4881 All modules should be compiled with the same @samp{-G @var{num}}
4885 Tell the MIPS assembler to not run its preprocessor over user
4886 assembler files (with a @samp{.s} suffix) when assembling them.
4890 These options are defined by the macro
4891 @code{TARGET_SWITCHES} in the machine description. The default for the
4892 options is also defined by that macro, which enables you to change the
4897 @subsection Intel 386 Options
4898 @cindex i386 Options
4899 @cindex Intel 386 Options
4901 These @samp{-m} options are defined for the i386 family of computers:
4904 @item -mcpu=@var{cpu type}
4905 Assume the defaults for the machine type @var{cpu type} when scheduling
4906 instructions. The choices for @var{cpu type} are: @samp{i386},
4907 @samp{i486}, @samp{i586} (@samp{pentium}), @samp{pentium}, @samp{i686}
4908 (@samp{pentiumpro}) and @samp{pentiumpro}. While picking a specific
4909 @var{cpu type} will schedule things appropriately for that particular
4910 chip, the compiler will not generate any code that does not run on the
4911 i386 without the @samp{-march=@var{cpu type}} option being used.
4913 @item -march=@var{cpu type}
4914 Generate instructions for the machine type @var{cpu type}. The choices
4915 for @var{cpu type} are: @samp{i386}, @samp{i486}, @samp{pentium}, and
4916 @samp{pentiumpro}. Specifying @samp{-march=@var{cpu type}} implies
4917 @samp{-mcpu=@var{cpu type}}.
4923 Synonyms for -mcpu=i386, -mcpu=i486, -mcpu=pentium, and -mcpu=pentiumpro
4928 Control whether or not the compiler uses IEEE floating point
4929 comparisons. These handle correctly the case where the result of a
4930 comparison is unordered.
4933 Generate output containing library calls for floating point.
4934 @strong{Warning:} the requisite libraries are not part of GNU CC.
4935 Normally the facilities of the machine's usual C compiler are used, but
4936 this can't be done directly in cross-compilation. You must make your
4937 own arrangements to provide suitable library functions for
4940 On machines where a function returns floating point results in the 80387
4941 register stack, some floating point opcodes may be emitted even if
4942 @samp{-msoft-float} is used.
4944 @item -mno-fp-ret-in-387
4945 Do not use the FPU registers for return values of functions.
4947 The usual calling convention has functions return values of types
4948 @code{float} and @code{double} in an FPU register, even if there
4949 is no FPU. The idea is that the operating system should emulate
4952 The option @samp{-mno-fp-ret-in-387} causes such values to be returned
4953 in ordinary CPU registers instead.
4955 @item -mno-fancy-math-387
4956 Some 387 emulators do not support the @code{sin}, @code{cos} and
4957 @code{sqrt} instructions for the 387. Specify this option to avoid
4958 generating those instructions. This option is the default on FreeBSD.
4959 As of revision 2.6.1, these instructions are not generated unless you
4960 also use the @samp{-ffast-math} switch.
4962 @item -malign-double
4963 @itemx -mno-align-double
4964 Control whether GNU CC aligns @code{double}, @code{long double}, and
4965 @code{long long} variables on a two word boundary or a one word
4966 boundary. Aligning @code{double} variables on a two word boundary will
4967 produce code that runs somewhat faster on a @samp{Pentium} at the
4968 expense of more memory.
4970 @strong{Warning:} if you use the @samp{-malign-double} switch,
4971 structures containing the above types will be aligned differently than
4972 the published application binary interface specifications for the 386.
4975 @itemx -mno-svr3-shlib
4976 Control whether GNU CC places uninitialized locals into @code{bss} or
4977 @code{data}. @samp{-msvr3-shlib} places these locals into @code{bss}.
4978 These options are meaningful only on System V Release 3.
4980 @item -mno-wide-multiply
4981 @itemx -mwide-multiply
4982 Control whether GNU CC uses the @code{mul} and @code{imul} that produce
4983 64 bit results in @code{eax:edx} from 32 bit operands to do @code{long
4984 long} multiplies and 32-bit division by constants.
4987 Use a different function-calling convention, in which functions that
4988 take a fixed number of arguments return with the @code{ret} @var{num}
4989 instruction, which pops their arguments while returning. This saves one
4990 instruction in the caller since there is no need to pop the arguments
4993 You can specify that an individual function is called with this calling
4994 sequence with the function attribute @samp{stdcall}. You can also
4995 override the @samp{-mrtd} option by using the function attribute
4996 @samp{cdecl}. @xref{Function Attributes}
4998 @strong{Warning:} this calling convention is incompatible with the one
4999 normally used on Unix, so you cannot use it if you need to call
5000 libraries compiled with the Unix compiler.
5002 Also, you must provide function prototypes for all functions that
5003 take variable numbers of arguments (including @code{printf});
5004 otherwise incorrect code will be generated for calls to those
5007 In addition, seriously incorrect code will result if you call a
5008 function with too many arguments. (Normally, extra arguments are
5009 harmlessly ignored.)
5011 @item -mreg-alloc=@var{regs}
5012 Control the default allocation order of integer registers. The
5013 string @var{regs} is a series of letters specifying a register. The
5014 supported letters are: @code{a} allocate EAX; @code{b} allocate EBX;
5015 @code{c} allocate ECX; @code{d} allocate EDX; @code{S} allocate ESI;
5016 @code{D} allocate EDI; @code{B} allocate EBP.
5018 @item -mregparm=@var{num}
5019 Control how many registers are used to pass integer arguments. By
5020 default, no registers are used to pass arguments, and at most 3
5021 registers can be used. You can control this behavior for a specific
5022 function by using the function attribute @samp{regparm}. @xref{Function Attributes}
5024 @strong{Warning:} if you use this switch, and
5025 @var{num} is nonzero, then you must build all modules with the same
5026 value, including any libraries. This includes the system libraries and
5029 @item -malign-loops=@var{num}
5030 Align loops to a 2 raised to a @var{num} byte boundary. If
5031 @samp{-malign-loops} is not specified, the default is 2 unless
5032 gas 2.8 (or later) is being used in which case the default is
5033 to align the loop on a 16 byte boundary if it is less than 8
5036 @item -malign-jumps=@var{num}
5037 Align instructions that are only jumped to to a 2 raised to a @var{num}
5038 byte boundary. If @samp{-malign-jumps} is not specified, the default is
5039 2 if optimizing for a 386, and 4 if optimizing for a 486 unless
5040 gas 2.8 (or later) is being used in which case the default is
5041 to align the instruction on a 16 byte boundary if it is less
5044 @item -malign-functions=@var{num}
5045 Align the start of functions to a 2 raised to @var{num} byte boundary.
5046 If @samp{-malign-functions} is not specified, the default is 2 if optimizing
5047 for a 386, and 4 if optimizing for a 486.
5051 @subsection HPPA Options
5052 @cindex HPPA Options
5054 These @samp{-m} options are defined for the HPPA family of computers:
5058 Generate code for a PA 1.0 processor.
5061 Generate code for a PA 1.1 processor.
5064 Generate code suitable for big switch tables. Use this option only if
5065 the assembler/linker complain about out of range branches within a switch
5068 @item -mjump-in-delay
5069 Fill delay slots of function calls with unconditional jump instructions
5070 by modifying the return pointer for the function call to be the target
5071 of the conditional jump.
5073 @item -mdisable-fpregs
5074 Prevent floating point registers from being used in any manner. This is
5075 necessary for compiling kernels which perform lazy context switching of
5076 floating point registers. If you use this option and attempt to perform
5077 floating point operations, the compiler will abort.
5079 @item -mdisable-indexing
5080 Prevent the compiler from using indexing address modes. This avoids some
5081 rather obscure problems when compiling MIG generated code under MACH.
5083 @item -mno-space-regs
5084 Generate code that assumes the target has no space registers. This allows
5085 GCC to generate faster indirect calls and use unscaled index address modes.
5087 Such code is suitable for level 0 PA systems and kernels.
5089 @item -mfast-indirect-calls
5090 Generate code that assumes calls never cross space boundaries. This
5091 allows GCC to emit code which performs faster indirect calls.
5093 This option will not work in the presense of shared libraries or nested
5097 Optimize for space rather than execution time. Currently this only
5098 enables out of line function prologues and epilogues. This option is
5099 incompatible with PIC code generation and profiling.
5101 @item -mlong-load-store
5102 Generate 3-instruction load and store sequences as sometimes required by
5103 the HP-UX 10 linker. This is equivalent to the @samp{+k} option to
5106 @item -mportable-runtime
5107 Use the portable calling conventions proposed by HP for ELF systems.
5110 Enable the use of assembler directives only GAS understands.
5112 @item -mschedule=@var{cpu type}
5113 Schedule code according to the constraints for the machine type
5114 @var{cpu type}. The choices for @var{cpu type} are @samp{700} for
5115 7@var{n}0 machines, @samp{7100} for 7@var{n}5 machines, and @samp{7100LC}
5116 for 7@var{n}2 machines. @samp{7100} is the default for @var{cpu type}.
5118 Note the @samp{7100LC} scheduling information is incomplete and using
5119 @samp{7100LC} often leads to bad schedules. For now it's probably best
5120 to use @samp{7100} instead of @samp{7100LC} for the 7@var{n}2 machines.
5123 Enable the optimization pass in the HPUX linker. Note this makes symbolic
5124 debugging impossible. It also triggers a bug in the HPUX 8 and HPUX 9 linkers
5125 in which they give bogus error messages when linking some programs.
5128 Generate output containing library calls for floating point.
5129 @strong{Warning:} the requisite libraries are not available for all HPPA
5130 targets. Normally the facilities of the machine's usual C compiler are
5131 used, but this cannot be done directly in cross-compilation. You must make
5132 your own arrangements to provide suitable library functions for
5133 cross-compilation. The embedded target @samp{hppa1.1-*-pro}
5134 does provide software floating point support.
5136 @samp{-msoft-float} changes the calling convention in the output file;
5137 therefore, it is only useful if you compile @emph{all} of a program with
5138 this option. In particular, you need to compile @file{libgcc.a}, the
5139 library that comes with GNU CC, with @samp{-msoft-float} in order for
5143 @node Intel 960 Options
5144 @subsection Intel 960 Options
5146 These @samp{-m} options are defined for the Intel 960 implementations:
5149 @item -m@var{cpu type}
5150 Assume the defaults for the machine type @var{cpu type} for some of
5151 the other options, including instruction scheduling, floating point
5152 support, and addressing modes. The choices for @var{cpu type} are
5153 @samp{ka}, @samp{kb}, @samp{mc}, @samp{ca}, @samp{cf},
5154 @samp{sa}, and @samp{sb}.
5160 The @samp{-mnumerics} option indicates that the processor does support
5161 floating-point instructions. The @samp{-msoft-float} option indicates
5162 that floating-point support should not be assumed.
5164 @item -mleaf-procedures
5165 @itemx -mno-leaf-procedures
5166 Do (or do not) attempt to alter leaf procedures to be callable with the
5167 @code{bal} instruction as well as @code{call}. This will result in more
5168 efficient code for explicit calls when the @code{bal} instruction can be
5169 substituted by the assembler or linker, but less efficient code in other
5170 cases, such as calls via function pointers, or using a linker that doesn't
5171 support this optimization.
5174 @itemx -mno-tail-call
5175 Do (or do not) make additional attempts (beyond those of the
5176 machine-independent portions of the compiler) to optimize tail-recursive
5177 calls into branches. You may not want to do this because the detection of
5178 cases where this is not valid is not totally complete. The default is
5179 @samp{-mno-tail-call}.
5181 @item -mcomplex-addr
5182 @itemx -mno-complex-addr
5183 Assume (or do not assume) that the use of a complex addressing mode is a
5184 win on this implementation of the i960. Complex addressing modes may not
5185 be worthwhile on the K-series, but they definitely are on the C-series.
5186 The default is currently @samp{-mcomplex-addr} for all processors except
5190 @itemx -mno-code-align
5191 Align code to 8-byte boundaries for faster fetching (or don't bother).
5192 Currently turned on by default for C-series implementations only.
5195 @item -mclean-linkage
5196 @itemx -mno-clean-linkage
5197 These options are not fully implemented.
5201 @itemx -mic2.0-compat
5202 @itemx -mic3.0-compat
5203 Enable compatibility with iC960 v2.0 or v3.0.
5207 Enable compatibility with the iC960 assembler.
5209 @item -mstrict-align
5210 @itemx -mno-strict-align
5211 Do not permit (do permit) unaligned accesses.
5214 Enable structure-alignment compatibility with Intel's gcc release version
5215 1.3 (based on gcc 1.37). This option implies @samp{-mstrict-align}.
5218 @node DEC Alpha Options
5219 @subsection DEC Alpha Options
5221 These @samp{-m} options are defined for the DEC Alpha implementations:
5224 @item -mno-soft-float
5226 Use (do not use) the hardware floating-point instructions for
5227 floating-point operations. When @code{-msoft-float} is specified,
5228 functions in @file{libgcc1.c} will be used to perform floating-point
5229 operations. Unless they are replaced by routines that emulate the
5230 floating-point operations, or compiled in such a way as to call such
5231 emulations routines, these routines will issue floating-point
5232 operations. If you are compiling for an Alpha without floating-point
5233 operations, you must ensure that the library is built so as not to call
5236 Note that Alpha implementations without floating-point operations are
5237 required to have floating-point registers.
5241 Generate code that uses (does not use) the floating-point register set.
5242 @code{-mno-fp-regs} implies @code{-msoft-float}. If the floating-point
5243 register set is not used, floating point operands are passed in integer
5244 registers as if they were integers and floating-point results are passed
5245 in $0 instead of $f0. This is a non-standard calling sequence, so any
5246 function with a floating-point argument or return value called by code
5247 compiled with @code{-mno-fp-regs} must also be compiled with that
5250 A typical use of this option is building a kernel that does not use,
5251 and hence need not save and restore, any floating-point registers.
5254 The Alpha architecture implements floating-point hardware optimized for
5255 maximum performance. It is mostly compliant with the IEEE floating
5256 point standard. However, for full compliance, software assistance is
5257 required. This option generates code fully IEEE compliant code
5258 @emph{except} that the @var{inexact flag} is not maintained (see below).
5259 If this option is turned on, the CPP macro @code{_IEEE_FP} is defined
5260 during compilation. The option is a shorthand for: @samp{-D_IEEE_FP
5261 -mfp-trap-mode=su -mtrap-precision=i -mieee-conformant}. The resulting
5262 code is less efficient but is able to correctly support denormalized
5263 numbers and exceptional IEEE values such as not-a-number and plus/minus
5264 infinity. Other Alpha compilers call this option
5265 @code{-ieee_with_no_inexact}.
5267 @item -mieee-with-inexact
5268 @c overfull hbox here --bob 22 jul96
5269 @c original text between ignore ... end ignore
5271 This is like @samp{-mieee} except the generated code also maintains the
5272 IEEE @var{inexact flag}. Turning on this option causes the generated
5273 code to implement fully-compliant IEEE math. The option is a shorthand
5274 for @samp{-D_IEEE_FP -D_IEEE_FP_INEXACT} plus @samp{-mieee-conformant},
5275 @samp{-mfp-trap-mode=sui}, and @samp{-mtrap-precision=i}. On some Alpha
5276 implementations the resulting code may execute significantly slower than
5277 the code generated by default. Since there is very little code that
5278 depends on the @var{inexact flag}, you should normally not specify this
5279 option. Other Alpha compilers call this option
5280 @samp{-ieee_with_inexact}.
5282 @c changed paragraph
5283 This is like @samp{-mieee} except the generated code also maintains the
5284 IEEE @var{inexact flag}. Turning on this option causes the generated
5285 code to implement fully-compliant IEEE math. The option is a shorthand
5286 for @samp{-D_IEEE_FP -D_IEEE_FP_INEXACT} plus the three following:
5287 @samp{-mieee-conformant},
5288 @samp{-mfp-trap-mode=sui},
5289 and @samp{-mtrap-precision=i}.
5290 On some Alpha implementations the resulting code may execute
5291 significantly slower than the code generated by default. Since there
5292 is very little code that depends on the @var{inexact flag}, you should
5293 normally not specify this option. Other Alpha compilers call this
5294 option @samp{-ieee_with_inexact}.
5295 @c end changes to prevent overfull hboxes
5297 @item -mfp-trap-mode=@var{trap mode}
5298 This option controls what floating-point related traps are enabled.
5299 Other Alpha compilers call this option @samp{-fptm }@var{trap mode}.
5300 The trap mode can be set to one of four values:
5304 This is the default (normal) setting. The only traps that are enabled
5305 are the ones that cannot be disabled in software (e.g., division by zero
5309 In addition to the traps enabled by @samp{n}, underflow traps are enabled
5313 Like @samp{su}, but the instructions are marked to be safe for software
5314 completion (see Alpha architecture manual for details).
5317 Like @samp{su}, but inexact traps are enabled as well.
5320 @item -mfp-rounding-mode=@var{rounding mode}
5321 Selects the IEEE rounding mode. Other Alpha compilers call this option
5322 @samp{-fprm }@var{rounding mode}. The @var{rounding mode} can be one
5327 Normal IEEE rounding mode. Floating point numbers are rounded towards
5328 the nearest machine number or towards the even machine number in case
5332 Round towards minus infinity.
5335 Chopped rounding mode. Floating point numbers are rounded towards zero.
5338 Dynamic rounding mode. A field in the floating point control register
5339 (@var{fpcr}, see Alpha architecture reference manual) controls the
5340 rounding mode in effect. The C library initializes this register for
5341 rounding towards plus infinity. Thus, unless your program modifies the
5342 @var{fpcr}, @samp{d} corresponds to round towards plus infinity.@end table
5344 @item -mtrap-precision=@var{trap precision}
5345 In the Alpha architecture, floating point traps are imprecise. This
5346 means without software assistance it is impossible to recover from a
5347 floating trap and program execution normally needs to be terminated.
5348 GNU CC can generate code that can assist operating system trap handlers
5349 in determining the exact location that caused a floating point trap.
5350 Depending on the requirements of an application, different levels of
5351 precisions can be selected:
5355 Program precision. This option is the default and means a trap handler
5356 can only identify which program caused a floating point exception.
5359 Function precision. The trap handler can determine the function that
5360 caused a floating point exception.
5363 Instruction precision. The trap handler can determine the exact
5364 instruction that caused a floating point exception.
5367 Other Alpha compilers provide the equivalent options called
5368 @samp{-scope_safe} and @samp{-resumption_safe}.
5370 @item -mieee-conformant
5371 This option marks the generated code as IEEE conformant. You must not
5372 use this option unless you also specify @samp{-mtrap-precision=i} and either
5373 @samp{-mfp-trap-mode=su} or @samp{-mfp-trap-mode=sui}. Its only effect
5374 is to emit the line @samp{.eflag 48} in the function prologue of the
5375 generated assembly file. Under DEC Unix, this has the effect that
5376 IEEE-conformant math library routines will be linked in.
5378 @item -mbuild-constants
5379 Normally GNU CC examines a 32- or 64-bit integer constant to
5380 see if it can construct it from smaller constants in two or three
5381 instructions. If it cannot, it will output the constant as a literal and
5382 generate code to load it from the data segment at runtime.
5384 Use this option to require GNU CC to construct @emph{all} integer constants
5385 using code, even if it takes more instructions (the maximum is six).
5387 You would typically use this option to build a shared library dynamic
5388 loader. Itself a shared library, it must relocate itself in memory
5389 before it can find the variables and constants in its own data segment.
5393 Select whether to generate code to be assembled by the vendor-supplied
5394 assembler (@samp{-malpha-as}) or by the GNU assembler @samp{-mgas}.
5402 Indicate whether GNU CC should generate code to use the optional BWX,
5403 CIX, and MAX instruction sets. The default is to use the instruction sets
5404 supported by the CPU type specified via @samp{-mcpu=} option or that
5405 of the CPU on which GNU CC was built if none was specified.
5407 @item -mcpu=@var{cpu_type}
5408 Set the instruction set, register set, and instruction scheduling
5409 parameters for machine type @var{cpu_type}. You can specify either the
5410 @samp{EV} style name or the corresponding chip number. GNU CC
5411 supports scheduling parameters for the EV4 and EV5 family of processors
5412 and will choose the default values for the instruction set from
5413 the processor you specify. If you do not specify a processor type,
5414 GNU CC will default to the processor on which the compiler was built.
5416 Supported values for @var{cpu_type} are
5421 Schedules as an EV4 and has no instruction set extensions.
5425 Schedules as an EV5 and has no instruction set extensions.
5429 Schedules as an EV5 and supports the BWX extension.
5434 Schedules as an EV5 and supports the BWX and MAX extensions.
5438 Schedules as an EV5 (until Digital releases the scheduling parameters
5439 for the EV6) and supports the BWX, CIX, and MAX extensions.
5442 @item -mmemory-latency=@var{time}
5443 Sets the latency the scheduler should assume for typical memory
5444 references as seen by the application. This number is highly
5445 dependant on the memory access patterns used by the application
5446 and the size of the external cache on the machine.
5448 Valid options for @var{time} are
5452 A decimal number representing clock cycles.
5458 The compiler contains estimates of the number of clock cycles for
5459 ``typical'' EV4 & EV5 hardware for the Level 1, 2 & 3 caches
5460 (also called Dcache, Scache, and Bcache), as well as to main memory.
5461 Note that L3 is only valid for EV5.
5466 @node Clipper Options
5467 @subsection Clipper Options
5469 These @samp{-m} options are defined for the Clipper implementations:
5473 Produce code for a C300 Clipper processor. This is the default.
5476 Produce code for a C400 Clipper processor i.e. use floating point
5480 @node H8/300 Options
5481 @subsection H8/300 Options
5483 These @samp{-m} options are defined for the H8/300 implementations:
5487 Shorten some address references at link time, when possible; uses the
5488 linker option @samp{-relax}. @xref{H8/300,, @code{ld} and the H8/300,
5489 ld.info, Using ld}, for a fuller description.
5492 Generate code for the H8/300H.
5495 Generate code for the H8/S.
5498 Make @code{int} data 32 bits by default.
5501 On the h8/300h, use the same alignment rules as for the h8/300.
5502 The default for the h8/300h is to align longs and floats on 4 byte boundaries.
5503 @samp{-malign-300} causes them to be aligned on 2 byte boundaries.
5504 This option has no effect on the h8/300.
5508 @subsection SH Options
5510 These @samp{-m} options are defined for the SH implementations:
5514 Generate code for the SH1.
5517 Generate code for the SH2.
5520 Generate code for the SH3.
5523 Generate code for the SH3e.
5526 Compile code for the processor in big endian mode.
5529 Compile code for the processor in little endian mode.
5532 Align doubles at 64 bit boundaries. Note that this changes the calling
5533 conventions, and thus some functions from the standard C library will
5534 not work unless you recompile it first with -mdalign.
5537 Shorten some address references at link time, when possible; uses the
5538 linker option @samp{-relax}.
5541 @node System V Options
5542 @subsection Options for System V
5544 These additional options are available on System V Release 4 for
5545 compatibility with other compilers on those systems:
5549 Create a shared object.
5550 It is recommended that @samp{-symbolic} or @samp{-shared} be used instead.
5553 Identify the versions of each tool used by the compiler, in a
5554 @code{.ident} assembler directive in the output.
5557 Refrain from adding @code{.ident} directives to the output file (this is
5560 @item -YP,@var{dirs}
5561 Search the directories @var{dirs}, and no others, for libraries
5562 specified with @samp{-l}.
5565 Look in the directory @var{dir} to find the M4 preprocessor.
5566 The assembler uses this option.
5567 @c This is supposed to go with a -Yd for predefined M4 macro files, but
5568 @c the generic assembler that comes with Solaris takes just -Ym.
5572 @subsection V850 Options
5573 @cindex V850 Options
5575 These @samp{-m} options are defined for V850 implementations:
5579 @itemx -mno-long-calls
5580 Treat all calls as being far away (near). If calls are assumed to be
5581 far away, the compiler will always load the functions address up into a
5582 register, and call indirect through the pointer.
5586 Do not optimize (do optimize) basic blocks that use the same index
5587 pointer 4 or more times to copy pointer into the @code{ep} register, and
5588 use the shorter @code{sld} and @code{sst} instructions. The @samp{-mep}
5589 option is on by default if you optimize.
5591 @item -mno-prolog-function
5592 @itemx -mprolog-function
5593 Do not use (do use) external functions to save and restore registers at
5594 the prolog and epilog of a function. The external functions are slower,
5595 but use less code space if more than one function saves the same number
5596 of registers. The @samp{-mprolog-function} option is on by default if
5600 Try to make the code as small as possible. At present, this just turns
5601 on the @samp{-mep} and @samp{-mprolog-function} options.
5604 Put static or global variables whose size is @var{n} bytes or less into
5605 the tiny data area that register @code{ep} points to. The tiny data
5606 area can hold up to 256 bytes in total (128 bytes for byte references).
5609 Put static or global variables whose size is @var{n} bytes or less into
5610 the small data area that register @code{gp} points to. The small data
5611 area can hold up to 64 kilobytes.
5614 Put static or global variables whose size is @var{n} bytes or less into
5615 the first 32 kilobytes of memory.
5618 Specify that the target processor is the V850.
5621 Generate code suitable for big switch tables. Use this option only if
5622 the assembler/linker complain about out of range branches within a switch
5627 @subsection ARC Options
5630 These options are defined for ARC implementations:
5634 Compile code for little endian mode. This is the default.
5637 Compile code for big endian mode.
5640 Prepend the name of the cpu to all public symbol names.
5641 In multiple-processor systems, there are many ARC variants with different
5642 instruction and register set characteristics. This flag prevents code
5643 compiled for one cpu to be linked with code compiled for another.
5644 No facility exists for handling variants that are "almost identical".
5645 This is an all or nothing option.
5647 @item -mcpu=@var{cpu}
5648 Compile code for ARC variant @var{cpu}.
5649 Which variants are supported depend on the configuration.
5650 All variants support @samp{-mcpu=base}, this is the default.
5652 @item -mtext=@var{text section}
5653 @item -mdata=@var{data section}
5654 @item -mrodata=@var{readonly data section}
5655 Put functions, data, and readonly data in @var{text section},
5656 @var{data section}, and @var{readonly data section} respectively
5657 by default. This can be overridden with the @code{section} attribute.
5658 @xref{Variable Attributes}
5663 @node Code Gen Options
5664 @section Options for Code Generation Conventions
5665 @cindex code generation conventions
5666 @cindex options, code generation
5667 @cindex run-time options
5669 These machine-independent options control the interface conventions
5670 used in code generation.
5672 Most of them have both positive and negative forms; the negative form
5673 of @samp{-ffoo} would be @samp{-fno-foo}. In the table below, only
5674 one of the forms is listed---the one which is not the default. You
5675 can figure out the other form by either removing @samp{no-} or adding
5680 Enable exception handling. Generates extra code needed to propagate
5681 exceptions. For some targets, this implies generation of frame unwind
5682 information for all functions. This can produce significant data size
5683 overhead, although it does not affect execution.
5684 If you do not specify this option, it is enabled by
5685 default for languages like C++ which normally require exception handling,
5686 and disabled for languages like C that do not normally require it.
5687 However, when compiling C code that needs to interoperate properly with
5688 exception handlers written in C++, you may need to enable this option.
5689 You may also wish to disable this option is you are compiling older C++
5690 programs that don't use exception handling.
5692 @item -fpcc-struct-return
5693 Return ``short'' @code{struct} and @code{union} values in memory like
5694 longer ones, rather than in registers. This convention is less
5695 efficient, but it has the advantage of allowing intercallability between
5696 GNU CC-compiled files and files compiled with other compilers.
5698 The precise convention for returning structures in memory depends
5699 on the target configuration macros.
5701 Short structures and unions are those whose size and alignment match
5702 that of some integer type.
5704 @item -freg-struct-return
5705 Use the convention that @code{struct} and @code{union} values are
5706 returned in registers when possible. This is more efficient for small
5707 structures than @samp{-fpcc-struct-return}.
5709 If you specify neither @samp{-fpcc-struct-return} nor its contrary
5710 @samp{-freg-struct-return}, GNU CC defaults to whichever convention is
5711 standard for the target. If there is no standard convention, GNU CC
5712 defaults to @samp{-fpcc-struct-return}, except on targets where GNU CC
5713 is the principal compiler. In those cases, we can choose the standard,
5714 and we chose the more efficient register return alternative.
5717 Allocate to an @code{enum} type only as many bytes as it needs for the
5718 declared range of possible values. Specifically, the @code{enum} type
5719 will be equivalent to the smallest integer type which has enough room.
5721 @item -fshort-double
5722 Use the same size for @code{double} as for @code{float}.
5725 Requests that the data and non-@code{const} variables of this
5726 compilation be shared data rather than private data. The distinction
5727 makes sense only on certain operating systems, where shared data is
5728 shared between processes running the same program, while private data
5729 exists in one copy per process.
5732 Allocate even uninitialized global variables in the bss section of the
5733 object file, rather than generating them as common blocks. This has the
5734 effect that if the same variable is declared (without @code{extern}) in
5735 two different compilations, you will get an error when you link them.
5736 The only reason this might be useful is if you wish to verify that the
5737 program will work on other systems which always work this way.
5740 Ignore the @samp{#ident} directive.
5742 @item -fno-gnu-linker
5743 Do not output global initializations (such as C++ constructors and
5744 destructors) in the form used by the GNU linker (on systems where the GNU
5745 linker is the standard method of handling them). Use this option when
5746 you want to use a non-GNU linker, which also requires using the
5747 @code{collect2} program to make sure the system linker includes
5748 constructors and destructors. (@code{collect2} is included in the GNU CC
5749 distribution.) For systems which @emph{must} use @code{collect2}, the
5750 compiler driver @code{gcc} is configured to do this automatically.
5752 @item -finhibit-size-directive
5753 Don't output a @code{.size} assembler directive, or anything else that
5754 would cause trouble if the function is split in the middle, and the
5755 two halves are placed at locations far apart in memory. This option is
5756 used when compiling @file{crtstuff.c}; you should not need to use it
5760 Put extra commentary information in the generated assembly code to
5761 make it more readable. This option is generally only of use to those
5762 who actually need to read the generated assembly code (perhaps while
5763 debugging the compiler itself).
5765 @samp{-fno-verbose-asm}, the default, causes the
5766 extra information to be omitted and is useful when comparing two assembler
5770 Consider all memory references through pointers to be volatile.
5772 @item -fvolatile-global
5773 Consider all memory references to extern and global data items to
5777 @cindex global offset table
5779 Generate position-independent code (PIC) suitable for use in a shared
5780 library, if supported for the target machine. Such code accesses all
5781 constant addresses through a global offset table (GOT). The dynamic
5782 loader resolves the GOT entries when the program starts (the dynamic
5783 loader is not part of GNU CC; it is part of the operating system). If
5784 the GOT size for the linked executable exceeds a machine-specific
5785 maximum size, you get an error message from the linker indicating that
5786 @samp{-fpic} does not work; in that case, recompile with @samp{-fPIC}
5787 instead. (These maximums are 16k on the m88k, 8k on the Sparc, and 32k
5788 on the m68k and RS/6000. The 386 has no such limit.)
5790 Position-independent code requires special support, and therefore works
5791 only on certain machines. For the 386, GNU CC supports PIC for System V
5792 but not for the Sun 386i. Code generated for the IBM RS/6000 is always
5793 position-independent.
5796 If supported for the target machine, emit position-independent code,
5797 suitable for dynamic linking and avoiding any limit on the size of the
5798 global offset table. This option makes a difference on the m68k, m88k,
5801 Position-independent code requires special support, and therefore works
5802 only on certain machines.
5804 @item -ffixed-@var{reg}
5805 Treat the register named @var{reg} as a fixed register; generated code
5806 should never refer to it (except perhaps as a stack pointer, frame
5807 pointer or in some other fixed role).
5809 @var{reg} must be the name of a register. The register names accepted
5810 are machine-specific and are defined in the @code{REGISTER_NAMES}
5811 macro in the machine description macro file.
5813 This flag does not have a negative form, because it specifies a
5816 @item -fcall-used-@var{reg}
5817 Treat the register named @var{reg} as an allocable register that is
5818 clobbered by function calls. It may be allocated for temporaries or
5819 variables that do not live across a call. Functions compiled this way
5820 will not save and restore the register @var{reg}.
5822 It is an error to used this flag with the frame pointer or stack pointer.
5823 Use of this flag for other registers that have fixed pervasive roles in
5824 the machine's execution model will produce disastrous results.
5826 This flag does not have a negative form, because it specifies a
5829 @item -fcall-saved-@var{reg}
5830 Treat the register named @var{reg} as an allocable register saved by
5831 functions. It may be allocated even for temporaries or variables that
5832 live across a call. Functions compiled this way will save and restore
5833 the register @var{reg} if they use it.
5835 It is an error to used this flag with the frame pointer or stack pointer.
5836 Use of this flag for other registers that have fixed pervasive roles in
5837 the machine's execution model will produce disastrous results.
5839 A different sort of disaster will result from the use of this flag for
5840 a register in which function values may be returned.
5842 This flag does not have a negative form, because it specifies a
5846 Pack all structure members together without holes. Usually you would
5847 not want to use this option, since it makes the code suboptimal, and
5848 the offsets of structure members won't agree with system libraries.
5850 @item -fcheck-memory-usage
5851 Generate extra code to check each memory access. GNU CC will generate
5852 code that is suitable for a detector of bad memory accesses such as
5855 You must also specify this option when you compile functions you call that
5856 have side effects. If you do not, you may get erroneous messages from
5857 the detector. Normally, you should compile all your code with this option.
5858 If you use functions from a library that have side-effects (such as
5859 @code{read}), you may not be able to recompile the library and
5860 specify this option. In that case, you can enable the
5861 @samp{-fprefix-function-name} option, which requests GNU CC to encapsulate
5862 your code and make other functions look as if they were compiled with
5863 @samp{-fcheck-memory-usage}. This is done by calling ``stubs'',
5864 which are provided by the detector. If you cannot find or build
5865 stubs for every function you call, you may have to specify
5866 @samp{-fcheck-memory-usage} without @samp{-fprefix-function-name}.
5868 If you specify this option, you can not use the @code{asm} or
5869 @code{__asm__} keywords in functions with memory checking enabled. The
5870 compiler cannot understand what the @code{asm} statement will do, and
5871 therefore cannot generate the appropriate code, so it is rejected.
5872 However, the function attribute @code{no_check_memory_usage} will
5873 disable memory checking within a function, and @code{asm} statements can
5874 be put inside such functions. Inline expansion of a non-checked
5875 function within a checked function is permitted; the inline function's
5876 memory accesses won't be checked, but the rest will.
5878 If you move your @code{asm} statements to non-checked inline functions,
5879 but they do access memory, you can add calls to the support code in your
5880 inline function, to indicate any reads, writes, or copies being done.
5881 These calls would be similar to those done in the stubs described above.
5883 @c FIXME: The support-routine interface is defined by the compiler and
5884 @c should be documented!
5886 @item -fprefix-function-name
5887 Request GNU CC to add a prefix to the symbols generated for function names.
5888 GNU CC adds a prefix to the names of functions defined as well as
5889 functions called. Code compiled with this option and code compiled
5890 without the option can't be linked together, unless or stubs are used.
5892 If you compile the following code with @samp{-fprefix-function-name}
5894 extern void bar (int);
5904 GNU CC will compile the code as if it was written:
5906 extern void prefix_bar (int);
5910 return prefix_bar (a + 5);
5913 This option is designed to be used with @samp{-fcheck-memory-usage}.
5915 @item -finstrument-functions
5916 Generate instrumentation calls for entry and exit to functions. Just
5917 after function entry and just before function exit, the following
5918 profiling functions will be called with the address of the current
5919 function and its call site. (On some platforms,
5920 @code{__builtin_return_address} does not work beyond the current
5921 function, so the call site information may not be available to the
5922 profiling functions otherwise.)
5925 void __cyg_profile_func_enter (void *this_fn, void *call_site);
5926 void __cyg_profile_func_exit (void *this_fn, void *call_site);
5929 The first argument is the address of the start of the current function,
5930 which may be looked up exactly in the symbol table.
5932 This instrumentation is also done for functions expanded inline in other
5933 functions. The profiling calls will indicate where, conceptually, the
5934 inline function is entered and exited. This means that addressable
5935 versions of such functions must be available. If all your uses of a
5936 function are expanded inline, this may mean an additional expansion of
5937 code size. If you use @samp{extern inline} in your C code, an
5938 addressable version of such functions must be provided. (This is
5939 normally the case anyways, but if you get lucky and the optimizer always
5940 expands the functions inline, you might have gotten away without
5941 providing static copies.)
5943 A function may be given the attribute @code{no_instrument_function}, in
5944 which case this instrumentation will not be done. This can be used, for
5945 example, for the profiling functions listed above, high-priority
5946 interrupt routines, and any functions from which the profiling functions
5947 cannot safely be called (perhaps signal handlers, if the profiling
5948 routines generate output or allocate memory).
5951 Generate code to verify that you do not go beyond the boundary of the
5952 stack. You should specify this flag if you are running in an
5953 environment with multiple threads, but only rarely need to specify it in
5954 a single-threaded environment since stack overflow is automatically
5955 detected on nearly all systems if there is only one stack.
5957 @cindex aliasing of parameters
5958 @cindex parameters, aliased
5959 @item -fargument-alias
5960 @itemx -fargument-noalias
5961 @itemx -fargument-noalias-global
5962 Specify the possible relationships among parameters and between
5963 parameters and global data.
5965 @samp{-fargument-alias} specifies that arguments (parameters) may
5966 alias each other and may alias global storage.
5967 @samp{-fargument-noalias} specifies that arguments do not alias
5968 each other, but may alias global storage.
5969 @samp{-fargument-noalias-global} specifies that arguments do not
5970 alias each other and do not alias global storage.
5972 Each language will automatically use whatever option is required by
5973 the language standard. You should not need to use these options yourself.
5976 @node Environment Variables
5977 @section Environment Variables Affecting GNU CC
5978 @cindex environment variables
5980 This section describes several environment variables that affect how GNU
5981 CC operates. Some of them work by specifying directories or prefixes to use
5982 when searching for various kinds of files. Some are used to specify other
5983 aspects of the compilation environment.
5986 Note that you can also specify places to search using options such as
5987 @samp{-B}, @samp{-I} and @samp{-L} (@pxref{Directory Options}). These
5988 take precedence over places specified using environment variables, which
5989 in turn take precedence over those specified by the configuration of GNU
5993 Note that you can also specify places to search using options such as
5994 @samp{-B}, @samp{-I} and @samp{-L} (@pxref{Directory Options}). These
5995 take precedence over places specified using environment variables, which
5996 in turn take precedence over those specified by the configuration of GNU
6003 If @code{TMPDIR} is set, it specifies the directory to use for temporary
6004 files. GNU CC uses temporary files to hold the output of one stage of
6005 compilation which is to be used as input to the next stage: for example,
6006 the output of the preprocessor, which is the input to the compiler
6009 @item GCC_EXEC_PREFIX
6010 @findex GCC_EXEC_PREFIX
6011 If @code{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the
6012 names of the subprograms executed by the compiler. No slash is added
6013 when this prefix is combined with the name of a subprogram, but you can
6014 specify a prefix that ends with a slash if you wish.
6016 If GNU CC cannot find the subprogram using the specified prefix, it
6017 tries looking in the usual places for the subprogram.
6019 The default value of @code{GCC_EXEC_PREFIX} is
6020 @file{@var{prefix}/lib/gcc-lib/} where @var{prefix} is the value
6021 of @code{prefix} when you ran the @file{configure} script.
6023 Other prefixes specified with @samp{-B} take precedence over this prefix.
6025 This prefix is also used for finding files such as @file{crt0.o} that are
6028 In addition, the prefix is used in an unusual way in finding the
6029 directories to search for header files. For each of the standard
6030 directories whose name normally begins with @samp{/usr/local/lib/gcc-lib}
6031 (more precisely, with the value of @code{GCC_INCLUDE_DIR}), GNU CC tries
6032 replacing that beginning with the specified prefix to produce an
6033 alternate directory name. Thus, with @samp{-Bfoo/}, GNU CC will search
6034 @file{foo/bar} where it would normally search @file{/usr/local/lib/bar}.
6035 These alternate directories are searched first; the standard directories
6039 @findex COMPILER_PATH
6040 The value of @code{COMPILER_PATH} is a colon-separated list of
6041 directories, much like @code{PATH}. GNU CC tries the directories thus
6042 specified when searching for subprograms, if it can't find the
6043 subprograms using @code{GCC_EXEC_PREFIX}.
6046 @findex LIBRARY_PATH
6047 The value of @code{LIBRARY_PATH} is a colon-separated list of
6048 directories, much like @code{PATH}. When configured as a native compiler,
6049 GNU CC tries the directories thus specified when searching for special
6050 linker files, if it can't find them using @code{GCC_EXEC_PREFIX}. Linking
6051 using GNU CC also uses these directories when searching for ordinary
6052 libraries for the @samp{-l} option (but directories specified with
6053 @samp{-L} come first).
6055 @item C_INCLUDE_PATH
6056 @itemx CPLUS_INCLUDE_PATH
6057 @itemx OBJC_INCLUDE_PATH
6058 @findex C_INCLUDE_PATH
6059 @findex CPLUS_INCLUDE_PATH
6060 @findex OBJC_INCLUDE_PATH
6061 @c @itemx OBJCPLUS_INCLUDE_PATH
6062 These environment variables pertain to particular languages. Each
6063 variable's value is a colon-separated list of directories, much like
6064 @code{PATH}. When GNU CC searches for header files, it tries the
6065 directories listed in the variable for the language you are using, after
6066 the directories specified with @samp{-I} but before the standard header
6069 @item DEPENDENCIES_OUTPUT
6070 @findex DEPENDENCIES_OUTPUT
6071 @cindex dependencies for make as output
6072 If this variable is set, its value specifies how to output dependencies
6073 for Make based on the header files processed by the compiler. This
6074 output looks much like the output from the @samp{-M} option
6075 (@pxref{Preprocessor Options}), but it goes to a separate file, and is
6076 in addition to the usual results of compilation.
6078 The value of @code{DEPENDENCIES_OUTPUT} can be just a file name, in
6079 which case the Make rules are written to that file, guessing the target
6080 name from the source file name. Or the value can have the form
6081 @samp{@var{file} @var{target}}, in which case the rules are written to
6082 file @var{file} using @var{target} as the target name.
6086 @cindex locale definition
6087 This variable is used to pass locale information to the compiler. One way in
6088 which this information is used is to determine the character set to be used
6089 when character literals, string literals and comments are parsed in C and C++.
6090 When the compiler is configured to allow multibyte characters,
6091 the following values for @code{LANG} are recognized:
6095 Recognize JIS characters.
6097 Recognize SJIS characters.
6099 Recognize EUCJP characters.
6102 If @code{LANG} is not defined, or if it has some other value, then the
6103 compiler will use mblen and mbtowc as defined by the default locale to
6104 recognize and translate multibyte characters.
6107 @node Running Protoize
6108 @section Running Protoize
6110 The program @code{protoize} is an optional part of GNU C. You can use
6111 it to add prototypes to a program, thus converting the program to ANSI
6112 C in one respect. The companion program @code{unprotoize} does the
6113 reverse: it removes argument types from any prototypes that are found.
6115 When you run these programs, you must specify a set of source files as
6116 command line arguments. The conversion programs start out by compiling
6117 these files to see what functions they define. The information gathered
6118 about a file @var{foo} is saved in a file named @file{@var{foo}.X}.
6120 After scanning comes actual conversion. The specified files are all
6121 eligible to be converted; any files they include (whether sources or
6122 just headers) are eligible as well.
6124 But not all the eligible files are converted. By default,
6125 @code{protoize} and @code{unprotoize} convert only source and header
6126 files in the current directory. You can specify additional directories
6127 whose files should be converted with the @samp{-d @var{directory}}
6128 option. You can also specify particular files to exclude with the
6129 @samp{-x @var{file}} option. A file is converted if it is eligible, its
6130 directory name matches one of the specified directory names, and its
6131 name within the directory has not been excluded.
6133 Basic conversion with @code{protoize} consists of rewriting most
6134 function definitions and function declarations to specify the types of
6135 the arguments. The only ones not rewritten are those for varargs
6138 @code{protoize} optionally inserts prototype declarations at the
6139 beginning of the source file, to make them available for any calls that
6140 precede the function's definition. Or it can insert prototype
6141 declarations with block scope in the blocks where undeclared functions
6144 Basic conversion with @code{unprotoize} consists of rewriting most
6145 function declarations to remove any argument types, and rewriting
6146 function definitions to the old-style pre-ANSI form.
6148 Both conversion programs print a warning for any function declaration or
6149 definition that they can't convert. You can suppress these warnings
6152 The output from @code{protoize} or @code{unprotoize} replaces the
6153 original source file. The original file is renamed to a name ending
6154 with @samp{.save}. If the @samp{.save} file already exists, then
6155 the source file is simply discarded.
6157 @code{protoize} and @code{unprotoize} both depend on GNU CC itself to
6158 scan the program and collect information about the functions it uses.
6159 So neither of these programs will work until GNU CC is installed.
6161 Here is a table of the options you can use with @code{protoize} and
6162 @code{unprotoize}. Each option works with both programs unless
6166 @item -B @var{directory}
6167 Look for the file @file{SYSCALLS.c.X} in @var{directory}, instead of the
6168 usual directory (normally @file{/usr/local/lib}). This file contains
6169 prototype information about standard system functions. This option
6170 applies only to @code{protoize}.
6172 @item -c @var{compilation-options}
6173 Use @var{compilation-options} as the options when running @code{gcc} to
6174 produce the @samp{.X} files. The special option @samp{-aux-info} is
6175 always passed in addition, to tell @code{gcc} to write a @samp{.X} file.
6177 Note that the compilation options must be given as a single argument to
6178 @code{protoize} or @code{unprotoize}. If you want to specify several
6179 @code{gcc} options, you must quote the entire set of compilation options
6180 to make them a single word in the shell.
6182 There are certain @code{gcc} arguments that you cannot use, because they
6183 would produce the wrong kind of output. These include @samp{-g},
6184 @samp{-O}, @samp{-c}, @samp{-S}, and @samp{-o} If you include these in
6185 the @var{compilation-options}, they are ignored.
6188 Rename files to end in @samp{.C} instead of @samp{.c}.
6189 This is convenient if you are converting a C program to C++.
6190 This option applies only to @code{protoize}.
6193 Add explicit global declarations. This means inserting explicit
6194 declarations at the beginning of each source file for each function
6195 that is called in the file and was not declared. These declarations
6196 precede the first function definition that contains a call to an
6197 undeclared function. This option applies only to @code{protoize}.
6199 @item -i @var{string}
6200 Indent old-style parameter declarations with the string @var{string}.
6201 This option applies only to @code{protoize}.
6203 @code{unprotoize} converts prototyped function definitions to old-style
6204 function definitions, where the arguments are declared between the
6205 argument list and the initial @samp{@{}. By default, @code{unprotoize}
6206 uses five spaces as the indentation. If you want to indent with just
6207 one space instead, use @samp{-i " "}.
6210 Keep the @samp{.X} files. Normally, they are deleted after conversion
6214 Add explicit local declarations. @code{protoize} with @samp{-l} inserts
6215 a prototype declaration for each function in each block which calls the
6216 function without any declaration. This option applies only to
6220 Make no real changes. This mode just prints information about the conversions
6221 that would have been done without @samp{-n}.
6224 Make no @samp{.save} files. The original files are simply deleted.
6225 Use this option with caution.
6227 @item -p @var{program}
6228 Use the program @var{program} as the compiler. Normally, the name
6232 Work quietly. Most warnings are suppressed.
6235 Print the version number, just like @samp{-v} for @code{gcc}.
6238 If you need special compiler options to compile one of your program's
6239 source files, then you should generate that file's @samp{.X} file
6240 specially, by running @code{gcc} on that source file with the
6241 appropriate options and the option @samp{-aux-info}. Then run
6242 @code{protoize} on the entire set of files. @code{protoize} will use
6243 the existing @samp{.X} file because it is newer than the source file.
6247 gcc -Dfoo=bar file1.c -aux-info
6252 You need to include the special files along with the rest in the
6253 @code{protoize} command, even though their @samp{.X} files already
6254 exist, because otherwise they won't get converted.
6256 @xref{Protoize Caveats}, for more information on how to use
6257 @code{protoize} successfully.