1 @c Copyright (C) 1988,89,92,93,94,95,96,97,1998 Free Software Foundation, Inc.
2 @c This is part of the GCC manual.
3 @c For copying conditions, see the file gcc.texi.
6 @chapter GNU CC Command Options
7 @cindex GNU CC command options
8 @cindex command options
9 @cindex options, GNU CC command
11 When you invoke GNU CC, it normally does preprocessing, compilation,
12 assembly and linking. The ``overall options'' allow you to stop this
13 process at an intermediate stage. For example, the @samp{-c} option
14 says not to run the linker. Then the output consists of object files
15 output by the assembler.
17 Other options are passed on to one stage of processing. Some options
18 control the preprocessor and others the compiler itself. Yet other
19 options control the assembler and linker; most of these are not
20 documented here, since you rarely need to use any of them.
22 @cindex C compilation options
23 Most of the command line options that you can use with GNU CC are useful
24 for C programs; when an option is only useful with another language
25 (usually C++), the explanation says so explicitly. If the description
26 for a particular option does not mention a source language, you can use
27 that option with all supported languages.
29 @cindex C++ compilation options
30 @xref{Invoking G++,,Compiling C++ Programs}, for a summary of special
31 options for compiling C++ programs.
33 @cindex grouping options
34 @cindex options, grouping
35 The @code{gcc} program accepts options and file names as operands. Many
36 options have multiletter names; therefore multiple single-letter options
37 may @emph{not} be grouped: @samp{-dr} is very different from @w{@samp{-d
40 @cindex order of options
41 @cindex options, order
42 You can mix options and other arguments. For the most part, the order
43 you use doesn't matter. Order does matter when you use several options
44 of the same kind; for example, if you specify @samp{-L} more than once,
45 the directories are searched in the order specified.
47 Many options have long names starting with @samp{-f} or with
48 @samp{-W}---for example, @samp{-fforce-mem},
49 @samp{-fstrength-reduce}, @samp{-Wformat} and so on. Most of
50 these have both positive and negative forms; the negative form of
51 @samp{-ffoo} would be @samp{-fno-foo}. This manual documents
52 only one of these two forms, whichever one is not the default.
55 * Option Summary:: Brief list of all options, without explanations.
56 * Overall Options:: Controlling the kind of output:
57 an executable, object files, assembler files,
58 or preprocessed source.
59 * Invoking G++:: Compiling C++ programs.
60 * C Dialect Options:: Controlling the variant of C language compiled.
61 * C++ Dialect Options:: Variations on C++.
62 * Warning Options:: How picky should the compiler be?
63 * Debugging Options:: Symbol tables, measurements, and debugging dumps.
64 * Optimize Options:: How much optimization?
65 * Preprocessor Options:: Controlling header files and macro definitions.
66 Also, getting dependency information for Make.
67 * Assembler Options:: Passing options to the assembler.
68 * Link Options:: Specifying libraries and so on.
69 * Directory Options:: Where to find header files and libraries.
70 Where to find the compiler executable files.
71 * Target Options:: Running a cross-compiler, or an old version of GNU CC.
72 * Submodel Options:: Specifying minor hardware or convention variations,
73 such as 68010 vs 68020.
74 * Code Gen Options:: Specifying conventions for function calls, data layout
76 * Environment Variables:: Env vars that affect GNU CC.
77 * Running Protoize:: Automatically adding or removing function prototypes.
81 @section Option Summary
83 Here is a summary of all the options, grouped by type. Explanations are
84 in the following sections.
88 @xref{Overall Options,,Options Controlling the Kind of Output}.
90 -c -S -E -o @var{file} -pipe -v --help -x @var{language}
93 @item C Language Options
94 @xref{C Dialect Options,,Options Controlling C Dialect}.
96 -ansi -flang-isoc9x -fallow-single-precision -fcond-mismatch -fno-asm
97 -fno-builtin -ffreestanding -fhosted -fsigned-bitfields -fsigned-char
98 -funsigned-bitfields -funsigned-char -fwritable-strings
99 -traditional -traditional-cpp -trigraphs
102 @item C++ Language Options
103 @xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
105 -fno-access-control -fcheck-new -fconserve-space -fdollars-in-identifiers
106 -fno-elide-constructors -fexternal-templates -ffor-scope
107 -fno-for-scope -fno-gnu-keywords -fguiding-decls -fhandle-signatures
108 -fhonor-std -fhuge-objects -fno-implicit-templates -finit-priority
109 -fno-implement-inlines -fname-mangling-version-@var{n} -fno-default-inline
110 -foperator-names -fno-optional-diags -frepo -fstrict-prototype
111 -fsquangle -ftemplate-depth-@var{n} -fthis-is-variable -fvtable-thunks
115 @item Warning Options
116 @xref{Warning Options,,Options to Request or Suppress Warnings}.
118 -fsyntax-only -pedantic -pedantic-errors
119 -w -W -Wall -Waggregate-return -Wbad-function-cast
120 -Wcast-align -Wcast-qual -Wchar-subscript -Wcomment
121 -Wconversion -Werror -Wformat
122 -Wid-clash-@var{len} -Wimplicit -Wimplicit-int
123 -Wimplicit-function-declaration -Wimport
124 -Werror-implicit-function-declaration -Winline
125 -Wlarger-than-@var{len} -Wlong-long
126 -Wmain -Wmissing-declarations -Wmissing-noreturn
127 -Wmissing-prototypes -Wmultichar -Wnested-externs -Wno-import
128 -Wno-non-template-friend -Wold-style-cast -Woverloaded-virtual
129 -Wparentheses -Wpointer-arith -Wredundant-decls -Wreorder
130 -Wreturn-type -Wshadow -Wsign-compare -Wstrict-prototypes
131 -Wswitch -Wsynth -Wtraditional
132 -Wtrigraphs -Wundef -Wuninitialized -Wunused -Wwrite-strings
136 @item Debugging Options
137 @xref{Debugging Options,,Options for Debugging Your Program or GCC}.
139 -a -ax -d@var{letters} -fdump-unnumbered -fpretend-float
140 -fprofile-arcs -ftest-coverage
141 -g -g@var{level} -gcoff -gdwarf -gdwarf-1 -gdwarf-1+ -gdwarf-2
142 -ggdb -gstabs -gstabs+ -gxcoff -gxcoff+
143 -p -pg -print-file-name=@var{library} -print-libgcc-file-name
144 -print-prog-name=@var{program} -print-search-dirs -save-temps
147 @item Optimization Options
148 @xref{Optimize Options,,Options that Control Optimization}.
150 -fbranch-probabilities -foptimize-register-moves
151 -fcaller-saves -fcse-follow-jumps -fcse-skip-blocks
152 -fdelayed-branch -fexpensive-optimizations
153 -ffast-math -ffloat-store -fforce-addr -fforce-mem
154 -fdata-sections -ffunction-sections -fgcse
155 -finline-functions -fkeep-inline-functions
156 -fno-default-inline -fno-defer-pop -fno-function-cse
157 -fno-inline -fno-peephole -fomit-frame-pointer -fregmove
158 -frerun-cse-after-loop -frerun-loop-opt -fschedule-insns
159 -fschedule-insns2 -fstrength-reduce -fthread-jumps
160 -funroll-all-loops -funroll-loops
161 -fmove-all-movables -freduce-all-givs -fstrict-aliasing
162 -O -O0 -O1 -O2 -O3 -Os
165 @item Preprocessor Options
166 @xref{Preprocessor Options,,Options Controlling the Preprocessor}.
168 -A@var{question}(@var{answer}) -C -dD -dM -dN
169 -D@var{macro}@r{[}=@var{defn}@r{]} -E -H
171 -include @var{file} -imacros @var{file}
172 -iprefix @var{file} -iwithprefix @var{dir}
173 -iwithprefixbefore @var{dir} -isystem @var{dir}
174 -M -MD -MM -MMD -MG -nostdinc -P -trigraphs
175 -undef -U@var{macro} -Wp,@var{option}
178 @item Assembler Option
179 @xref{Assembler Options,,Passing Options to the Assembler}.
185 @xref{Link Options,,Options for Linking}.
187 @var{object-file-name} -l@var{library}
188 -nostartfiles -nodefaultlibs -nostdlib
189 -s -static -shared -symbolic
190 -Wl,@var{option} -Xlinker @var{option}
194 @item Directory Options
195 @xref{Directory Options,,Options for Directory Search}.
197 -B@var{prefix} -I@var{dir} -I- -L@var{dir} -specs=@var{file}
201 @c I wrote this xref this way to avoid overfull hbox. -- rms
202 @xref{Target Options}.
204 -b @var{machine} -V @var{version}
207 @item Machine Dependent Options
208 @xref{Submodel Options,,Hardware Models and Configurations}.
210 @emph{M680x0 Options}
211 -m68000 -m68020 -m68020-40 -m68020-60 -m68030 -m68040
212 -m68060 -mcpu32 -m5200 -m68881 -mbitfield -mc68000 -mc68020
213 -mfpa -mnobitfield -mrtd -mshort -msoft-float
221 -mtune=@var{cpu type}
222 -mcmodel=@var{code model}
223 -malign-jumps=@var{num} -malign-loops=@var{num}
224 -malign-functions=@var{num}
226 -mapp-regs -mbroken-saverestore -mcypress -mepilogue
227 -mflat -mfpu -mhard-float -mhard-quad-float
228 -mimpure-text -mlive-g0 -mno-app-regs -mno-epilogue
229 -mno-flat -mno-fpu -mno-impure-text
230 -mno-stack-bias -mno-unaligned-doubles
231 -msoft-float -msoft-quad-float -msparclite -mstack-bias
232 -msupersparc -munaligned-doubles -mv8
234 @emph{Convex Options}
235 -mc1 -mc2 -mc32 -mc34 -mc38
236 -margcount -mnoargcount
238 -mvolatile-cache -mvolatile-nocache
240 @emph{AMD29K Options}
241 -m29000 -m29050 -mbw -mnbw -mdw -mndw
242 -mlarge -mnormal -msmall
243 -mkernel-registers -mno-reuse-arg-regs
244 -mno-stack-check -mno-storem-bug
245 -mreuse-arg-regs -msoft-float -mstack-check
246 -mstorem-bug -muser-registers
249 -mapcs-frame -mno-apcs-frame
251 -mapcs-stack-check -mno-apcs-stack-check
252 -mapcs-float -mno-apcs-float
253 -mapcs-reentrant -mno-apcs-reentrant
254 -msched-prolog -mno-sched-prolog
255 -mlittle-endian -mbig-endian -mwords-little-endian
256 -mshort-load-bytes -mno-short-load-bytes -mshort-load-words -mno-short-load-words
257 -msoft-float -mhard-float -mfpe
258 -mthumb-interwork -mno-thumb-interwork
259 -mcpu= -march= -mfpe=
260 -mstructure-size-boundary=
261 -mbsd -mxopen -mno-symrename
264 -mtpcs-frame -mno-tpcs-frame
265 -mtpcs-leaf-frame -mno-tpcs-leaf-frame
266 -mlittle-endian -mbig-endian
267 -mthumb-interwork -mno-thumb-interwork
268 -mstructure-size-boundary=
270 @emph{MN10200 Options}
273 @emph{MN10300 Options}
278 @emph{M32R/D Options}
279 -mcode-model=@var{model type} -msdata=@var{sdata type}
283 -m88000 -m88100 -m88110 -mbig-pic
284 -mcheck-zero-division -mhandle-large-shift
285 -midentify-revision -mno-check-zero-division
286 -mno-ocs-debug-info -mno-ocs-frame-position
287 -mno-optimize-arg-area -mno-serialize-volatile
288 -mno-underscores -mocs-debug-info
289 -mocs-frame-position -moptimize-arg-area
290 -mserialize-volatile -mshort-data-@var{num} -msvr3
291 -msvr4 -mtrap-large-shift -muse-div-instruction
292 -mversion-03.00 -mwarn-passed-structs
294 @emph{RS/6000 and PowerPC Options}
296 -mtune=@var{cpu type}
297 -mpower -mno-power -mpower2 -mno-power2
298 -mpowerpc -mno-powerpc
299 -mpowerpc-gpopt -mno-powerpc-gpopt
300 -mpowerpc-gfxopt -mno-powerpc-gfxopt
301 -mnew-mnemonics -mno-new-mnemonics
302 -mfull-toc -mminimal-toc -mno-fop-in-toc -mno-sum-in-toc
303 -maix64 -maix32 -mxl-call -mno-xl-call -mthreads -mpe
304 -msoft-float -mhard-float -mmultiple -mno-multiple
305 -mstring -mno-string -mupdate -mno-update
306 -mfused-madd -mno-fused-madd -mbit-align -mno-bit-align
307 -mstrict-align -mno-strict-align -mrelocatable
308 -mno-relocatable -mrelocatable-lib -mno-relocatable-lib
309 -mtoc -mno-toc -mlittle -mlittle-endian -mbig -mbig-endian
310 -mcall-aix -mcall-sysv -mprototype -mno-prototype
311 -msim -mmvme -mads -myellowknife -memb -msdata
312 -msdata=@var{opt} -G @var{num}
315 -mcall-lib-mul -mfp-arg-in-fpregs -mfp-arg-in-gregs
316 -mfull-fp-blocks -mhc-struct-return -min-line-mul
317 -mminimum-fp-blocks -mnohc-struct-return
320 -mabicalls -mcpu=@var{cpu type} -membedded-data
321 -membedded-pic -mfp32 -mfp64 -mgas -mgp32 -mgp64
322 -mgpopt -mhalf-pic -mhard-float -mint64 -mips1
323 -mips2 -mips3 -mips4 -mlong64 -mlong-calls -mmemcpy
324 -mmips-as -mmips-tfile -mno-abicalls
325 -mno-embedded-data -mno-embedded-pic
326 -mno-gpopt -mno-long-calls
327 -mno-memcpy -mno-mips-tfile -mno-rnames -mno-stats
328 -mrnames -msoft-float
329 -m4650 -msingle-float -mmad
330 -mstats -EL -EB -G @var{num} -nocpp
331 -mabi=32 -mabi=n32 -mabi=64 -mabi=eabi
335 -march=@var{cpu type}
336 -mieee-fp -mno-fancy-math-387
337 -mno-fp-ret-in-387 -msoft-float -msvr3-shlib
338 -mno-wide-multiply -mrtd -malign-double
339 -mreg-alloc=@var{list} -mregparm=@var{num}
340 -malign-jumps=@var{num} -malign-loops=@var{num}
341 -malign-functions=@var{num}
344 -mbig-switch -mdisable-fpregs -mdisable-indexing
345 -mfast-indirect-calls -mgas -mjump-in-delay
346 -mlong-load-store -mno-big-switch -mno-disable-fpregs
347 -mno-disable-indexing -mno-fast-indirect-calls -mno-gas
348 -mno-jump-in-delay -mno-long-load-store
349 -mno-portable-runtime -mno-soft-float -mno-space
350 -mno-space-regs -msoft-float -mpa-risc-1-0
351 -mpa-risc-1-1 -mportable-runtime
352 -mschedule=@var{list} -mspace -mspace-regs
354 @emph{Intel 960 Options}
355 -m@var{cpu type} -masm-compat -mclean-linkage
356 -mcode-align -mcomplex-addr -mleaf-procedures
357 -mic-compat -mic2.0-compat -mic3.0-compat
358 -mintel-asm -mno-clean-linkage -mno-code-align
359 -mno-complex-addr -mno-leaf-procedures
360 -mno-old-align -mno-strict-align -mno-tail-call
361 -mnumerics -mold-align -msoft-float -mstrict-align
364 @emph{DEC Alpha Options}
365 -mfp-regs -mno-fp-regs -mno-soft-float -msoft-float
367 -mieee -mieee-with-inexact -mieee-conformant
368 -mfp-trap-mode=@var{mode} -mfp-rounding-mode=@var{mode}
369 -mtrap-precision=@var{mode} -mbuild-constants
371 -mbwx -mno-bwx -mcix -mno-cix -mmax -mno-max
372 -mmemory-latency=@var{time}
374 @emph{Clipper Options}
377 @emph{H8/300 Options}
378 -mrelax -mh -ms -mint32 -malign-300
381 -m1 -m2 -m3 -m3e -mb -ml -mdalign -mrelax
383 @emph{System V Options}
384 -Qy -Qn -YP,@var{paths} -Ym,@var{dir}
388 -mmangle-cpu -mcpu=@var{cpu} -mtext=@var{text section}
389 -mdata=@var{data section} -mrodata=@var{readonly data section}
392 -mlong-calls -mno-long-calls -mep -mno-ep
393 -mprolog-function -mno-prolog-function -mspace
394 -mtda=@var{n} -msda=@var{n} -mzda=@var{n}
398 @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
416 * Overall Options:: Controlling the kind of output:
417 an executable, object files, assembler files,
418 or preprocessed source.
419 * C Dialect Options:: Controlling the variant of C language compiled.
420 * C++ Dialect Options:: Variations on C++.
421 * Warning Options:: How picky should the compiler be?
422 * Debugging Options:: Symbol tables, measurements, and debugging dumps.
423 * Optimize Options:: How much optimization?
424 * Preprocessor Options:: Controlling header files and macro definitions.
425 Also, getting dependency information for Make.
426 * Assembler Options:: Passing options to the assembler.
427 * Link Options:: Specifying libraries and so on.
428 * Directory Options:: Where to find header files and libraries.
429 Where to find the compiler executable files.
430 * Target Options:: Running a cross-compiler, or an old version of GNU CC.
433 @node Overall Options
434 @section Options Controlling the Kind of Output
436 Compilation can involve up to four stages: preprocessing, compilation
437 proper, assembly and linking, always in that order. The first three
438 stages apply to an individual source file, and end by producing an
439 object file; linking combines all the object files (those newly
440 compiled, and those specified as input) into an executable file.
442 @cindex file name suffix
443 For any given input file, the file name suffix determines what kind of
448 C source code which must be preprocessed.
451 C source code which should not be preprocessed.
454 C++ source code which should not be preprocessed.
457 Objective-C source code. Note that you must link with the library
458 @file{libobjc.a} to make an Objective-C program work.
461 C header file (not to be compiled or linked).
464 @itemx @var{file}.cxx
465 @itemx @var{file}.cpp
467 C++ source code which must be preprocessed. Note that in @samp{.cxx},
468 the last two letters must both be literally @samp{x}. Likewise,
469 @samp{.C} refers to a literal capital C.
475 Assembler code which must be preprocessed.
478 An object file to be fed straight into linking.
479 Any file name with no recognized suffix is treated this way.
482 You can specify the input language explicitly with the @samp{-x} option:
485 @item -x @var{language}
486 Specify explicitly the @var{language} for the following input files
487 (rather than letting the compiler choose a default based on the file
488 name suffix). This option applies to all following input files until
489 the next @samp{-x} option. Possible values for @var{language} are:
492 c-header cpp-output c++-cpp-output
493 assembler assembler-with-cpp
497 Turn off any specification of a language, so that subsequent files are
498 handled according to their file name suffixes (as they are if @samp{-x}
499 has not been used at all).
502 If you only want some of the stages of compilation, you can use
503 @samp{-x} (or filename suffixes) to tell @code{gcc} where to start, and
504 one of the options @samp{-c}, @samp{-S}, or @samp{-E} to say where
505 @code{gcc} is to stop. Note that some combinations (for example,
506 @samp{-x cpp-output -E} instruct @code{gcc} to do nothing at all.
510 Compile or assemble the source files, but do not link. The linking
511 stage simply is not done. The ultimate output is in the form of an
512 object file for each source file.
514 By default, the object file name for a source file is made by replacing
515 the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}.
517 Unrecognized input files, not requiring compilation or assembly, are
521 Stop after the stage of compilation proper; do not assemble. The output
522 is in the form of an assembler code file for each non-assembler input
525 By default, the assembler file name for a source file is made by
526 replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}.
528 Input files that don't require compilation are ignored.
531 Stop after the preprocessing stage; do not run the compiler proper. The
532 output is in the form of preprocessed source code, which is sent to the
535 Input files which don't require preprocessing are ignored.
537 @cindex output file option
539 Place output in file @var{file}. This applies regardless to whatever
540 sort of output is being produced, whether it be an executable file,
541 an object file, an assembler file or preprocessed C code.
543 Since only one output file can be specified, it does not make sense to
544 use @samp{-o} when compiling more than one input file, unless you are
545 producing an executable file as output.
547 If @samp{-o} is not specified, the default is to put an executable file
548 in @file{a.out}, the object file for @file{@var{source}.@var{suffix}} in
549 @file{@var{source}.o}, its assembler file in @file{@var{source}.s}, and
550 all preprocessed C source on standard output.@refill
553 Print (on standard error output) the commands executed to run the stages
554 of compilation. Also print the version number of the compiler driver
555 program and of the preprocessor and the compiler proper.
558 Use pipes rather than temporary files for communication between the
559 various stages of compilation. This fails to work on some systems where
560 the assembler is unable to read from a pipe; but the GNU assembler has
564 Print (on the standard output) a description of the command line options
565 understood by @code{gcc}. If the @code{-v} option is also specified
566 then @code{--help} will also be passed on to the various processes
567 invoked by @code{gcc}, so that they can display the command line options
568 they accept. If the @code{-W} option is also specified then command
569 line options which have no documentation associated with them will also
574 @section Compiling C++ Programs
576 @cindex suffixes for C++ source
577 @cindex C++ source file suffixes
578 C++ source files conventionally use one of the suffixes @samp{.C},
579 @samp{.cc}, @samp{cpp}, or @samp{.cxx}; preprocessed C++ files use the
580 suffix @samp{.ii}. GNU CC recognizes files with these names and
581 compiles them as C++ programs even if you call the compiler the same way
582 as for compiling C programs (usually with the name @code{gcc}).
586 However, C++ programs often require class libraries as well as a
587 compiler that understands the C++ language---and under some
588 circumstances, you might want to compile programs from standard input,
589 or otherwise without a suffix that flags them as C++ programs.
590 @code{g++} is a program that calls GNU CC with the default language
591 set to C++, and automatically specifies linking against the C++
593 @cindex @code{g++ 1.@var{xx}}
594 @cindex @code{g++}, separate compiler
595 @cindex @code{g++} older version
596 @footnote{Prior to release 2 of the compiler,
597 there was a separate @code{g++} compiler. That version was based on GNU
598 CC, but not integrated with it. Versions of @code{g++} with a
599 @samp{1.@var{xx}} version number---for example, @code{g++} version 1.37
600 or 1.42---are much less reliable than the versions integrated with GCC
601 2. Moreover, combining G++ @samp{1.@var{xx}} with a version 2 GCC will
602 simply not work.} On many systems, the script @code{g++} is also
603 installed with the name @code{c++}.
605 @cindex invoking @code{g++}
606 When you compile C++ programs, you may specify many of the same
607 command-line options that you use for compiling programs in any
608 language; or command-line options meaningful for C and related
609 languages; or options that are meaningful only for C++ programs.
610 @xref{C Dialect Options,,Options Controlling C Dialect}, for
611 explanations of options for languages related to C.
612 @xref{C++ Dialect Options,,Options Controlling C++ Dialect}, for
613 explanations of options that are meaningful only for C++ programs.
615 @node C Dialect Options
616 @section Options Controlling C Dialect
617 @cindex dialect options
618 @cindex language dialect options
619 @cindex options, dialect
621 The following options control the dialect of C (or languages derived
622 from C, such as C++ and Objective C) that the compiler accepts:
627 Support all ANSI standard C programs.
629 This turns off certain features of GNU C that are incompatible with ANSI
630 C, such as the @code{asm}, @code{inline} and @code{typeof} keywords, and
631 predefined macros such as @code{unix} and @code{vax} that identify the
632 type of system you are using. It also enables the undesirable and
633 rarely used ANSI trigraph feature, and it disables recognition of C++
634 style @samp{//} comments.
636 The alternate keywords @code{__asm__}, @code{__extension__},
637 @code{__inline__} and @code{__typeof__} continue to work despite
638 @samp{-ansi}. You would not want to use them in an ANSI C program, of
639 course, but it is useful to put them in header files that might be included
640 in compilations done with @samp{-ansi}. Alternate predefined macros
641 such as @code{__unix__} and @code{__vax__} are also available, with or
642 without @samp{-ansi}.
644 The @samp{-ansi} option does not cause non-ANSI programs to be
645 rejected gratuitously. For that, @samp{-pedantic} is required in
646 addition to @samp{-ansi}. @xref{Warning Options}.
648 The macro @code{__STRICT_ANSI__} is predefined when the @samp{-ansi}
649 option is used. Some header files may notice this macro and refrain
650 from declaring certain functions or defining certain macros that the
651 ANSI standard doesn't call for; this is to avoid interfering with any
652 programs that might use these names for other things.
654 The functions @code{alloca}, @code{abort}, @code{exit}, and
655 @code{_exit} are not builtin functions when @samp{-ansi} is used.
658 Enable support for features found in the C9X standard. In particular,
659 enable support for the C9X @code{restrict} keyword.
661 Even when this option is not specified, you can still use some C9X
662 features in so far as they do not conflict with previous C standards.
663 For example, you may use @code{__restrict__} even when -flang-isoc9x
667 Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
668 keyword, so that code can use these words as identifiers. You can use
669 the keywords @code{__asm__}, @code{__inline__} and @code{__typeof__}
670 instead. @samp{-ansi} implies @samp{-fno-asm}.
672 In C++, this switch only affects the @code{typeof} keyword, since
673 @code{asm} and @code{inline} are standard keywords. You may want to
674 use the @samp{-fno-gnu-keywords} flag instead, as it also disables the
675 other, C++-specific, extension keywords such as @code{headof}.
678 @cindex builtin functions
694 Don't recognize builtin functions that do not begin with `__builtin_'
695 as prefix. Currently, the functions affected include @code{abort},
696 @code{abs}, @code{alloca}, @code{cos}, @code{exit}, @code{fabs},
697 @code{ffs}, @code{labs}, @code{memcmp}, @code{memcpy}, @code{sin},
698 @code{sqrt}, @code{strcmp}, @code{strcpy}, and @code{strlen}.
700 GCC normally generates special code to handle certain builtin functions
701 more efficiently; for instance, calls to @code{alloca} may become single
702 instructions that adjust the stack directly, and calls to @code{memcpy}
703 may become inline copy loops. The resulting code is often both smaller
704 and faster, but since the function calls no longer appear as such, you
705 cannot set a breakpoint on those calls, nor can you change the behavior
706 of the functions by linking with a different library.
708 The @samp{-ansi} option prevents @code{alloca} and @code{ffs} from being
709 builtin functions, since these functions do not have an ANSI standard
713 @cindex hosted environment
715 Assert that compilation takes place in a hosted environment. This implies
716 @samp{-fbuiltin}. A hosted environment is one in which the
717 entire standard library is available, and in which @code{main} has a return
718 type of @code{int}. Examples are nearly everything except a kernel.
719 This is equivalent to @samp{-fno-freestanding}.
722 @cindex hosted environment
724 Assert that compilation takes place in a freestanding environment. This
725 implies @samp{-fno-builtin}. A freestanding environment
726 is one in which the standard library may not exist, and program startup may
727 not necessarily be at @code{main}. The most obvious example is an OS kernel.
728 This is equivalent to @samp{-fno-hosted}.
731 Support ANSI C trigraphs. You don't want to know about this
732 brain-damage. The @samp{-ansi} option implies @samp{-trigraphs}.
734 @cindex traditional C language
735 @cindex C language, traditional
737 Attempt to support some aspects of traditional C compilers.
742 All @code{extern} declarations take effect globally even if they
743 are written inside of a function definition. This includes implicit
744 declarations of functions.
747 The newer keywords @code{typeof}, @code{inline}, @code{signed}, @code{const}
748 and @code{volatile} are not recognized. (You can still use the
749 alternative keywords such as @code{__typeof__}, @code{__inline__}, and
753 Comparisons between pointers and integers are always allowed.
756 Integer types @code{unsigned short} and @code{unsigned char} promote
757 to @code{unsigned int}.
760 Out-of-range floating point literals are not an error.
763 Certain constructs which ANSI regards as a single invalid preprocessing
764 number, such as @samp{0xe-0xd}, are treated as expressions instead.
767 String ``constants'' are not necessarily constant; they are stored in
768 writable space, and identical looking constants are allocated
769 separately. (This is the same as the effect of
770 @samp{-fwritable-strings}.)
772 @cindex @code{longjmp} and automatic variables
774 All automatic variables not declared @code{register} are preserved by
775 @code{longjmp}. Ordinarily, GNU C follows ANSI C: automatic variables
776 not declared @code{volatile} may be clobbered.
781 @cindex escape sequences, traditional
782 The character escape sequences @samp{\x} and @samp{\a} evaluate as the
783 literal characters @samp{x} and @samp{a} respectively. Without
784 @w{@samp{-traditional}}, @samp{\x} is a prefix for the hexadecimal
785 representation of a character, and @samp{\a} produces a bell.
788 You may wish to use @samp{-fno-builtin} as well as @samp{-traditional}
789 if your program uses names that are normally GNU C builtin functions for
790 other purposes of its own.
792 You cannot use @samp{-traditional} if you include any header files that
793 rely on ANSI C features. Some vendors are starting to ship systems with
794 ANSI C header files and you cannot use @samp{-traditional} on such
795 systems to compile files that include any system headers.
797 The @samp{-traditional} option also enables @samp{-traditional-cpp},
798 which is described next.
800 @item -traditional-cpp
801 Attempt to support some aspects of traditional C preprocessors.
806 Comments convert to nothing at all, rather than to a space. This allows
807 traditional token concatenation.
810 In a preprocessing directive, the @samp{#} symbol must appear as the first
814 Macro arguments are recognized within string constants in a macro
815 definition (and their values are stringified, though without additional
816 quote marks, when they appear in such a context). The preprocessor
817 always considers a string constant to end at a newline.
820 @cindex detecting @w{@samp{-traditional}}
821 The predefined macro @code{__STDC__} is not defined when you use
822 @samp{-traditional}, but @code{__GNUC__} is (since the GNU extensions
823 which @code{__GNUC__} indicates are not affected by
824 @samp{-traditional}). If you need to write header files that work
825 differently depending on whether @samp{-traditional} is in use, by
826 testing both of these predefined macros you can distinguish four
827 situations: GNU C, traditional GNU C, other ANSI C compilers, and other
828 old C compilers. The predefined macro @code{__STDC_VERSION__} is also
829 not defined when you use @samp{-traditional}. @xref{Standard
830 Predefined,,Standard Predefined Macros,cpp.info,The C Preprocessor},
831 for more discussion of these and other predefined macros.
834 @cindex string constants vs newline
835 @cindex newline vs string constants
836 The preprocessor considers a string constant to end at a newline (unless
837 the newline is escaped with @samp{\}). (Without @w{@samp{-traditional}},
838 string constants can contain the newline character as typed.)
841 @item -fcond-mismatch
842 Allow conditional expressions with mismatched types in the second and
843 third arguments. The value of such an expression is void.
845 @item -funsigned-char
846 Let the type @code{char} be unsigned, like @code{unsigned char}.
848 Each kind of machine has a default for what @code{char} should
849 be. It is either like @code{unsigned char} by default or like
850 @code{signed char} by default.
852 Ideally, a portable program should always use @code{signed char} or
853 @code{unsigned char} when it depends on the signedness of an object.
854 But many programs have been written to use plain @code{char} and
855 expect it to be signed, or expect it to be unsigned, depending on the
856 machines they were written for. This option, and its inverse, let you
857 make such a program work with the opposite default.
859 The type @code{char} is always a distinct type from each of
860 @code{signed char} or @code{unsigned char}, even though its behavior
861 is always just like one of those two.
864 Let the type @code{char} be signed, like @code{signed char}.
866 Note that this is equivalent to @samp{-fno-unsigned-char}, which is
867 the negative form of @samp{-funsigned-char}. Likewise, the option
868 @samp{-fno-signed-char} is equivalent to @samp{-funsigned-char}.
870 You may wish to use @samp{-fno-builtin} as well as @samp{-traditional}
871 if your program uses names that are normally GNU C builtin functions for
872 other purposes of its own.
874 You cannot use @samp{-traditional} if you include any header files that
875 rely on ANSI C features. Some vendors are starting to ship systems with
876 ANSI C header files and you cannot use @samp{-traditional} on such
877 systems to compile files that include any system headers.
879 @item -fsigned-bitfields
880 @itemx -funsigned-bitfields
881 @itemx -fno-signed-bitfields
882 @itemx -fno-unsigned-bitfields
883 These options control whether a bitfield is signed or unsigned, when the
884 declaration does not use either @code{signed} or @code{unsigned}. By
885 default, such a bitfield is signed, because this is consistent: the
886 basic integer types such as @code{int} are signed types.
888 However, when @samp{-traditional} is used, bitfields are all unsigned
891 @item -fwritable-strings
892 Store string constants in the writable data segment and don't uniquize
893 them. This is for compatibility with old programs which assume they can
894 write into string constants. The option @samp{-traditional} also has
897 Writing into string constants is a very bad idea; ``constants'' should
900 @item -fallow-single-precision
901 Do not promote single precision math operations to double precision,
902 even when compiling with @samp{-traditional}.
904 Traditional K&R C promotes all floating point operations to double
905 precision, regardless of the sizes of the operands. On the
906 architecture for which you are compiling, single precision may be faster
907 than double precision. If you must use @samp{-traditional}, but want
908 to use single precision operations when the operands are single
909 precision, use this option. This option has no effect when compiling
910 with ANSI or GNU C conventions (the default).
914 @node C++ Dialect Options
915 @section Options Controlling C++ Dialect
917 @cindex compiler options, C++
918 @cindex C++ options, command line
920 This section describes the command-line options that are only meaningful
921 for C++ programs; but you can also use most of the GNU compiler options
922 regardless of what language your program is in. For example, you
923 might compile a file @code{firstClass.C} like this:
926 g++ -g -frepo -O -c firstClass.C
930 In this example, only @samp{-frepo} is an option meant
931 only for C++ programs; you can use the other options with any
932 language supported by GNU CC.
934 Here is a list of options that are @emph{only} for compiling C++ programs:
937 @item -fno-access-control
938 Turn off all access checking. This switch is mainly useful for working
939 around bugs in the access control code.
942 Check that the pointer returned by @code{operator new} is non-null
943 before attempting to modify the storage allocated. The current Working
944 Paper requires that @code{operator new} never return a null pointer, so
945 this check is normally unnecessary.
947 An alternative to using this option is to specify that your
948 @code{operator new} does not throw any exceptions; if you declare it
949 @samp{throw()}, g++ will check the return value. See also @samp{new
952 @item -fconserve-space
953 Put uninitialized or runtime-initialized global variables into the
954 common segment, as C does. This saves space in the executable at the
955 cost of not diagnosing duplicate definitions. If you compile with this
956 flag and your program mysteriously crashes after @code{main()} has
957 completed, you may have an object that is being destroyed twice because
958 two definitions were merged.
960 This option is no longer useful on most targets, now that support has
961 been added for putting variables into BSS without making them common.
963 @item -fdollars-in-identifiers
964 Accept @samp{$} in identifiers. You can also explicitly prohibit use of
965 @samp{$} with the option @samp{-fno-dollars-in-identifiers}. (GNU C allows
966 @samp{$} by default on most target systems, but there are a few exceptions.)
967 Traditional C allowed the character @samp{$} to form part of
968 identifiers. However, ANSI C and C++ forbid @samp{$} in identifiers.
970 @item -fno-elide-constructors
971 The C++ standard allows an implementation to omit creating a temporary
972 which is only used to initialize another object of the same type.
973 Specifying this option disables that optimization, and forces g++ to
974 call the copy constructor in all cases.
976 @item -fexternal-templates
977 Cause template instantiations to obey @samp{#pragma interface} and
978 @samp{implementation}; template instances are emitted or not according
979 to the location of the template definition. @xref{Template
980 Instantiation}, for more information.
982 This option is deprecated.
984 @item -falt-external-templates
985 Similar to -fexternal-templates, but template instances are emitted or
986 not according to the place where they are first instantiated.
987 @xref{Template Instantiation}, for more information.
989 This option is deprecated.
992 @itemx -fno-for-scope
993 If -ffor-scope is specified, the scope of variables declared in
994 a @i{for-init-statement} is limited to the @samp{for} loop itself,
995 as specified by the draft C++ standard.
996 If -fno-for-scope is specified, the scope of variables declared in
997 a @i{for-init-statement} extends to the end of the enclosing scope,
998 as was the case in old versions of gcc, and other (traditional)
999 implementations of C++.
1001 The default if neither flag is given to follow the standard,
1002 but to allow and give a warning for old-style code that would
1003 otherwise be invalid, or have different behavior.
1005 @item -fno-gnu-keywords
1006 Do not recognize @code{classof}, @code{headof}, @code{signature},
1007 @code{sigof} or @code{typeof} as a keyword, so that code can use these
1008 words as identifiers. You can use the keywords @code{__classof__},
1009 @code{__headof__}, @code{__signature__}, @code{__sigof__}, and
1010 @code{__typeof__} instead. @samp{-ansi} implies
1011 @samp{-fno-gnu-keywords}.
1013 @item -fguiding-decls
1014 Treat a function declaration with the same type as a potential function
1015 template instantiation as though it declares that instantiation, not a
1016 normal function. If a definition is given for the function later in the
1017 translation unit (or another translation unit if the target supports
1018 weak symbols), that definition will be used; otherwise the template will
1019 be instantiated. This behavior reflects the C++ language prior to
1020 September 1996, when guiding declarations were removed.
1022 This option implies @samp{-fname-mangling-version-0}, and will not work
1023 with other name mangling versions. Like all options that change the
1024 ABI, all C++ code, @emph{including libgcc.a} must be built with the same
1025 setting of this option.
1027 @item -fhandle-signatures
1028 Recognize the @code{signature} and @code{sigof} keywords for specifying
1029 abstract types. The default (@samp{-fno-handle-signatures}) is not to
1030 recognize them. @xref{C++ Signatures, Type Abstraction using
1034 Treat the @code{namespace std} as a namespace, instead of ignoring
1035 it. For compatibility with earlier versions of g++, the compiler will,
1036 by default, ignore @code{namespace-declarations},
1037 @code{using-declarations}, @code{using-directives}, and
1038 @code{namespace-names}, if they involve @code{std}.
1040 @item -fhuge-objects
1041 Support virtual function calls for objects that exceed the size
1042 representable by a @samp{short int}. Users should not use this flag by
1043 default; if you need to use it, the compiler will tell you so.
1045 This flag is not useful when compiling with -fvtable-thunks.
1047 Like all options that change the ABI, all C++ code, @emph{including
1048 libgcc} must be built with the same setting of this option.
1050 @item -fno-implicit-templates
1051 Never emit code for templates which are instantiated implicitly (i.e. by
1052 use); only emit code for explicit instantiations. @xref{Template
1053 Instantiation}, for more information.
1055 @item -finit-priority
1056 Support @samp{__attribute__ ((init_priority (n)))} for controlling the
1057 order of initialization of file-scope objects. On ELF targets, this
1058 requires GNU ld 2.10 or later.
1060 @item -fno-implement-inlines
1061 To save space, do not emit out-of-line copies of inline functions
1062 controlled by @samp{#pragma implementation}. This will cause linker
1063 errors if these functions are not inlined everywhere they are called.
1065 @item -fname-mangling-version-@var{n}
1066 Control the way in which names are mangled. Version 0 is compatible
1067 with versions of g++ before 2.8. Version 1 is the default. Version 1
1068 will allow correct mangling of function templates. For example,
1069 version 0 mangling does not mangle foo<int, double> and foo<int, char>
1070 given this declaration:
1073 template <class T, class U> void foo(T t);
1076 @item -foperator-names
1077 Recognize the operator name keywords @code{and}, @code{bitand},
1078 @code{bitor}, @code{compl}, @code{not}, @code{or} and @code{xor} as
1079 synonyms for the symbols they refer to. @samp{-ansi} implies
1080 @samp{-foperator-names}.
1082 @item -fno-optional-diags
1083 Disable diagnostics that the standard says a compiler does not need to
1084 issue. Currently, this means the diagnostic for a name having multiple
1085 meanings within a class.
1088 Enable automatic template instantiation. This option also implies
1089 @samp{-fno-implicit-templates}. @xref{Template Instantiation}, for more
1092 @item -fstrict-prototype
1093 Within an @samp{extern "C"} linkage specification, treat a function
1094 declaration with no arguments, such as @samp{int foo ();}, as declaring
1095 the function to take no arguments. Normally, such a declaration means
1096 that the function @code{foo} can take any combination of arguments, as
1097 in C. @samp{-pedantic} implies @samp{-fstrict-prototype} unless
1098 overridden with @samp{-fno-strict-prototype}.
1100 Specifying this option will also suppress implicit declarations of
1103 This flag no longer affects declarations with C++ linkage.
1106 @itemx -fno-squangle
1107 @samp{-fsquangle} will enable a compressed form of name mangling for
1108 identifiers. In particular, it helps to shorten very long names by recognizing
1109 types and class names which occur more than once, replacing them with special
1110 short ID codes. This option also requires any C++ libraries being used to
1111 be compiled with this option as well. The compiler has this disabled (the
1112 equivalent of @samp{-fno-squangle}) by default.
1114 Like all options that change the ABI, all C++ code, @emph{including
1115 libgcc.a} must be built with the same setting of this option.
1117 @item -ftemplate-depth-@var{n}
1118 Set the maximum instantiation depth for template classes to @var{n}.
1119 A limit on the template instantiation depth is needed to detect
1120 endless recursions during template class instantiation. ANSI/ISO C++
1121 conforming programs must not rely on a maximum depth greater than 17.
1123 @item -fthis-is-variable
1124 Permit assignment to @code{this}. The incorporation of user-defined
1125 free store management into C++ has made assignment to @samp{this} an
1126 anachronism. Therefore, by default it is invalid to assign to
1127 @code{this} within a class member function; that is, GNU C++ treats
1128 @samp{this} in a member function of class @code{X} as a non-lvalue of
1129 type @samp{X *}. However, for backwards compatibility, you can make it
1130 valid with @samp{-fthis-is-variable}.
1132 @item -fvtable-thunks
1133 Use @samp{thunks} to implement the virtual function dispatch table
1134 (@samp{vtable}). The traditional (cfront-style) approach to
1135 implementing vtables was to store a pointer to the function and two
1136 offsets for adjusting the @samp{this} pointer at the call site. Newer
1137 implementations store a single pointer to a @samp{thunk} function which
1138 does any necessary adjustment and then calls the target function.
1140 Like all options that change the ABI, all C++ code, @emph{including
1141 libgcc.a} must be built with the same setting of this option.
1144 Do not search for header files in the standard directories specific to
1145 C++, but do still search the other standard directories. (This option
1146 is used when building the C++ library.)
1149 In addition, these optimization, warning, and code generation options
1150 have meanings only for C++ programs:
1153 @item -fno-default-inline
1154 Do not assume @samp{inline} for functions defined inside a class scope.
1155 @xref{Optimize Options,,Options That Control Optimization}. Note that these
1156 functions will have linkage like inline functions; they just won't be
1159 @item -Wno-non-template-friend
1160 @xref{Warning Options,,Options to Request or Suppress Warnings}.
1161 @item -Wold-style-cast
1162 @itemx -Woverloaded-virtual
1163 Warnings that apply only to C++ programs. @xref{Warning
1164 Options,,Options to Request or Suppress Warnings}.
1167 Warn about violation of some style rules from Effective C++ by Scott Myers.
1170 @node Warning Options
1171 @section Options to Request or Suppress Warnings
1172 @cindex options to control warnings
1173 @cindex warning messages
1174 @cindex messages, warning
1175 @cindex suppressing warnings
1177 Warnings are diagnostic messages that report constructions which
1178 are not inherently erroneous but which are risky or suggest there
1179 may have been an error.
1181 You can request many specific warnings with options beginning @samp{-W},
1182 for example @samp{-Wimplicit} to request warnings on implicit
1183 declarations. Each of these specific warning options also has a
1184 negative form beginning @samp{-Wno-} to turn off warnings;
1185 for example, @samp{-Wno-implicit}. This manual lists only one of the
1186 two forms, whichever is not the default.
1188 These options control the amount and kinds of warnings produced by GNU
1192 @cindex syntax checking
1194 Check the code for syntax errors, but don't do anything beyond that.
1197 Issue all the warnings demanded by strict ANSI C and ISO C++;
1198 reject all programs that use forbidden extensions.
1200 Valid ANSI C and ISO C++ programs should compile properly with or without
1201 this option (though a rare few will require @samp{-ansi}). However,
1202 without this option, certain GNU extensions and traditional C and C++
1203 features are supported as well. With this option, they are rejected.
1205 @samp{-pedantic} does not cause warning messages for use of the
1206 alternate keywords whose names begin and end with @samp{__}. Pedantic
1207 warnings are also disabled in the expression that follows
1208 @code{__extension__}. However, only system header files should use
1209 these escape routes; application programs should avoid them.
1210 @xref{Alternate Keywords}.
1212 This option is not intended to be @i{useful}; it exists only to satisfy
1213 pedants who would otherwise claim that GNU CC fails to support the ANSI
1216 Some users try to use @samp{-pedantic} to check programs for strict ANSI
1217 C conformance. They soon find that it does not do quite what they want:
1218 it finds some non-ANSI practices, but not all---only those for which
1219 ANSI C @emph{requires} a diagnostic.
1221 A feature to report any failure to conform to ANSI C might be useful in
1222 some instances, but would require considerable additional work and would
1223 be quite different from @samp{-pedantic}. We recommend, rather, that
1224 users take advantage of the extensions of GNU C and disregard the
1225 limitations of other compilers. Aside from certain supercomputers and
1226 obsolete small machines, there is less and less reason ever to use any
1227 other C compiler other than for bootstrapping GNU CC.
1229 @item -pedantic-errors
1230 Like @samp{-pedantic}, except that errors are produced rather than
1234 Inhibit all warning messages.
1237 Inhibit warning messages about the use of @samp{#import}.
1239 @item -Wchar-subscripts
1240 Warn if an array subscript has type @code{char}. This is a common cause
1241 of error, as programmers often forget that this type is signed on some
1245 Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
1246 comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
1249 Check calls to @code{printf} and @code{scanf}, etc., to make sure that
1250 the arguments supplied have types appropriate to the format string
1253 @item -Wimplicit-int
1254 Warn when a declaration does not specify a type.
1256 @item -Wimplicit-function-declaration
1257 @itemx -Werror-implicit-function-declaration
1258 Give a warning (or error) whenever a function is used before being
1262 Same as @samp{-Wimplicit-int} and @samp{-Wimplicit-function-}@*
1266 Warn if the type of @samp{main} is suspicious. @samp{main} should be a
1267 function with external linkage, returning int, taking either zero
1268 arguments, two, or three arguments of appropriate types.
1271 Warn if a multicharacter constant (@samp{'FOOF'}) is used. Usually they
1272 indicate a typo in the user's code, as they have implementation-defined
1273 values, and should not be used in portable code.
1276 Warn if parentheses are omitted in certain contexts, such
1277 as when there is an assignment in a context where a truth value
1278 is expected, or when operators are nested whose precedence people
1279 often get confused about.
1281 Also warn about constructions where there may be confusion to which
1282 @code{if} statement an @code{else} branch belongs. Here is an example of
1295 In C, every @code{else} branch belongs to the innermost possible @code{if}
1296 statement, which in this example is @code{if (b)}. This is often not
1297 what the programmer expected, as illustrated in the above example by
1298 indentation the programmer chose. When there is the potential for this
1299 confusion, GNU C will issue a warning when this flag is specified.
1300 To eliminate the warning, add explicit braces around the innermost
1301 @code{if} statement so there is no way the @code{else} could belong to
1302 the enclosing @code{if}. The resulting code would look like this:
1317 Warn whenever a function is defined with a return-type that defaults
1318 to @code{int}. Also warn about any @code{return} statement with no
1319 return-value in a function whose return-type is not @code{void}.
1322 Warn whenever a @code{switch} statement has an index of enumeral type
1323 and lacks a @code{case} for one or more of the named codes of that
1324 enumeration. (The presence of a @code{default} label prevents this
1325 warning.) @code{case} labels outside the enumeration range also
1326 provoke warnings when this option is used.
1329 Warn if any trigraphs are encountered (assuming they are enabled).
1332 Warn whenever a variable is unused aside from its declaration,
1333 whenever a function is declared static but never defined, whenever a
1334 label is declared but not used, and whenever a statement computes a
1335 result that is explicitly not used.
1337 In order to get a warning about an unused function parameter, you must
1338 specify both @samp{-W} and @samp{-Wunused}.
1340 To suppress this warning for an expression, simply cast it to void. For
1341 unused variables and parameters, use the @samp{unused} attribute
1342 (@pxref{Variable Attributes}).
1344 @item -Wuninitialized
1345 An automatic variable is used without first being initialized.
1347 These warnings are possible only in optimizing compilation,
1348 because they require data flow information that is computed only
1349 when optimizing. If you don't specify @samp{-O}, you simply won't
1352 These warnings occur only for variables that are candidates for
1353 register allocation. Therefore, they do not occur for a variable that
1354 is declared @code{volatile}, or whose address is taken, or whose size
1355 is other than 1, 2, 4 or 8 bytes. Also, they do not occur for
1356 structures, unions or arrays, even when they are in registers.
1358 Note that there may be no warning about a variable that is used only
1359 to compute a value that itself is never used, because such
1360 computations may be deleted by data flow analysis before the warnings
1363 These warnings are made optional because GNU CC is not smart
1364 enough to see all the reasons why the code might be correct
1365 despite appearing to have an error. Here is one example of how
1384 If the value of @code{y} is always 1, 2 or 3, then @code{x} is
1385 always initialized, but GNU CC doesn't know this. Here is
1386 another common case:
1391 if (change_y) save_y = y, y = new_y;
1393 if (change_y) y = save_y;
1398 This has no bug because @code{save_y} is used only if it is set.
1400 Some spurious warnings can be avoided if you declare all the functions
1401 you use that never return as @code{noreturn}. @xref{Function
1404 @item -Wreorder (C++ only)
1405 @cindex reordering, warning
1406 @cindex warning for reordering of member initializers
1407 Warn when the order of member initializers given in the code does not
1408 match the order in which they must be executed. For instance:
1414 A(): j (0), i (1) @{ @}
1418 Here the compiler will warn that the member initializers for @samp{i}
1419 and @samp{j} will be rearranged to match the declaration order of the
1422 @item -Wtemplate-debugging
1423 @cindex template debugging
1424 When using templates in a C++ program, warn if debugging is not yet
1425 fully available (C++ only).
1427 @item -Wunknown-pragmas
1428 @cindex warning for unknown pragmas
1429 @cindex unknown pragmas, warning
1430 @cindex pragmas, warning of unknown
1431 Warn when a #pragma directive is encountered which is not understood by
1432 GCC. If this command line option is used, warnings will even be issued
1433 for unknown pragmas in system header files. This is not the case if
1434 the warnings were only enabled by the @samp{-Wall} command line option.
1437 All of the above @samp{-W} options combined. This enables all the
1438 warnings about constructions that some users consider questionable, and
1439 that are easy to avoid (or modify to prevent the warning), even in
1440 conjunction with macros.
1443 The following @samp{-W@dots{}} options are not implied by @samp{-Wall}.
1444 Some of them warn about constructions that users generally do not
1445 consider questionable, but which occasionally you might wish to check
1446 for; others warn about constructions that are necessary or hard to avoid
1447 in some cases, and there is no simple way to modify the code to suppress
1452 Print extra warning messages for these events:
1455 @cindex @code{longjmp} warnings
1457 A nonvolatile automatic variable might be changed by a call to
1458 @code{longjmp}. These warnings as well are possible only in
1459 optimizing compilation.
1461 The compiler sees only the calls to @code{setjmp}. It cannot know
1462 where @code{longjmp} will be called; in fact, a signal handler could
1463 call it at any point in the code. As a result, you may get a warning
1464 even when there is in fact no problem because @code{longjmp} cannot
1465 in fact be called at the place which would cause a problem.
1468 A function can return either with or without a value. (Falling
1469 off the end of the function body is considered returning without
1470 a value.) For example, this function would evoke such a
1484 An expression-statement or the left-hand side of a comma expression
1485 contains no side effects.
1486 To suppress the warning, cast the unused expression to void.
1487 For example, an expression such as @samp{x[i,j]} will cause a warning,
1488 but @samp{x[(void)i,j]} will not.
1491 An unsigned value is compared against zero with @samp{<} or @samp{<=}.
1494 A comparison like @samp{x<=y<=z} appears; this is equivalent to
1495 @samp{(x<=y ? 1 : 0) <= z}, which is a different interpretation from
1496 that of ordinary mathematical notation.
1499 Storage-class specifiers like @code{static} are not the first things in
1500 a declaration. According to the C Standard, this usage is obsolescent.
1503 If @samp{-Wall} or @samp{-Wunused} is also specified, warn about unused
1507 A comparison between signed and unsigned values could produce an
1508 incorrect result when the signed value is converted to unsigned.
1509 (But don't warn if @samp{-Wno-sign-compare} is also specified.)
1512 An aggregate has a partly bracketed initializer.
1513 For example, the following code would evoke such a warning,
1514 because braces are missing around the initializer for @code{x.h}:
1517 struct s @{ int f, g; @};
1518 struct t @{ struct s h; int i; @};
1519 struct t x = @{ 1, 2, 3 @};
1523 An aggregate has an initializer which does not initialize all members.
1524 For example, the following code would cause such a warning, because
1525 @code{x.h} would be implicitly initialized to zero:
1528 struct s @{ int f, g, h; @};
1529 struct s x = @{ 3, 4 @};
1534 Warn about certain constructs that behave differently in traditional and
1539 Macro arguments occurring within string constants in the macro body.
1540 These would substitute the argument in traditional C, but are part of
1541 the constant in ANSI C.
1544 A function declared external in one block and then used after the end of
1548 A @code{switch} statement has an operand of type @code{long}.
1552 Warn if an undefined identifier is evaluated in an @samp{#if} directive.
1555 Warn whenever a local variable shadows another local variable.
1557 @item -Wid-clash-@var{len}
1558 Warn whenever two distinct identifiers match in the first @var{len}
1559 characters. This may help you prepare a program that will compile
1560 with certain obsolete, brain-damaged compilers.
1562 @item -Wlarger-than-@var{len}
1563 Warn whenever an object of larger than @var{len} bytes is defined.
1565 @item -Wpointer-arith
1566 Warn about anything that depends on the ``size of'' a function type or
1567 of @code{void}. GNU C assigns these types a size of 1, for
1568 convenience in calculations with @code{void *} pointers and pointers
1571 @item -Wbad-function-cast
1572 Warn whenever a function call is cast to a non-matching type.
1573 For example, warn if @code{int malloc()} is cast to @code{anything *}.
1576 Warn whenever a pointer is cast so as to remove a type qualifier from
1577 the target type. For example, warn if a @code{const char *} is cast
1578 to an ordinary @code{char *}.
1581 Warn whenever a pointer is cast such that the required alignment of the
1582 target is increased. For example, warn if a @code{char *} is cast to
1583 an @code{int *} on machines where integers can only be accessed at
1584 two- or four-byte boundaries.
1586 @item -Wwrite-strings
1587 Give string constants the type @code{const char[@var{length}]} so that
1588 copying the address of one into a non-@code{const} @code{char *}
1589 pointer will get a warning. These warnings will help you find at
1590 compile time code that can try to write into a string constant, but
1591 only if you have been very careful about using @code{const} in
1592 declarations and prototypes. Otherwise, it will just be a nuisance;
1593 this is why we did not make @samp{-Wall} request these warnings.
1596 Warn if a prototype causes a type conversion that is different from what
1597 would happen to the same argument in the absence of a prototype. This
1598 includes conversions of fixed point to floating and vice versa, and
1599 conversions changing the width or signedness of a fixed point argument
1600 except when the same as the default promotion.
1602 Also, warn if a negative integer constant expression is implicitly
1603 converted to an unsigned type. For example, warn about the assignment
1604 @code{x = -1} if @code{x} is unsigned. But do not warn about explicit
1605 casts like @code{(unsigned) -1}.
1607 @item -Wsign-compare
1608 @cindex warning for comparison of signed and unsigned values
1609 @cindex comparison of signed and unsigned values, warning
1610 @cindex signed and unsigned values, comparison warning
1611 Warn when a comparison between signed and unsigned values could produce
1612 an incorrect result when the signed value is converted to unsigned.
1613 This warning is also enabled by @samp{-W}; to get the other warnings
1614 of @samp{-W} without this warning, use @samp{-W -Wno-sign-compare}.
1616 @item -Waggregate-return
1617 Warn if any functions that return structures or unions are defined or
1618 called. (In languages where you can return an array, this also elicits
1621 @item -Wstrict-prototypes
1622 Warn if a function is declared or defined without specifying the
1623 argument types. (An old-style function definition is permitted without
1624 a warning if preceded by a declaration which specifies the argument
1627 @item -Wmissing-prototypes
1628 Warn if a global function is defined without a previous prototype
1629 declaration. This warning is issued even if the definition itself
1630 provides a prototype. The aim is to detect global functions that fail
1631 to be declared in header files.
1633 @item -Wmissing-declarations
1634 Warn if a global function is defined without a previous declaration.
1635 Do so even if the definition itself provides a prototype.
1636 Use this option to detect global functions that are not declared in
1639 @item -Wmissing-noreturn
1640 Warn about functions which might be candidates for attribute @code{noreturn}.
1641 Note these are only possible candidates, not absolute ones. Care should
1642 be taken to manually verify functions actually do not ever return before
1643 adding the @code{noreturn} attribute, otherwise subtle code generation
1644 bugs could be introduced.
1646 @item -Wredundant-decls
1647 Warn if anything is declared more than once in the same scope, even in
1648 cases where multiple declaration is valid and changes nothing.
1650 @item -Wnested-externs
1651 Warn if an @code{extern} declaration is encountered within an function.
1653 @item -Wno-non-template-friend
1654 Disable warnings when non-templatized friend functions are declared
1655 within a template. With the advent of explicit template specification
1656 support in g++, if the name of the friend is an unqualified-id (ie,
1657 @samp{friend foo(int)}), the C++ language specification demands that the
1658 friend declare or define an ordinary, nontemplate function. (Section
1659 14.5.3). Before g++ implemented explicit specification, unqualified-ids
1660 could be interpreted as a particular specialization of a templatized
1661 function. Because this non-conforming behavior is no longer the default
1662 behavior for g++, @samp{-Wnon-template-friend} allows the compiler to
1663 check existing code for potential trouble spots, and is on by default.
1664 This new compiler behavior can also be turned off with the flag
1665 @samp{-fguiding-decls}, which activates the older, non-specification
1666 compiler code, or with @samp{-Wno-non-template-friend} which keeps the
1667 conformant compiler code but disables the helpful warning.
1670 Warn if a function can not be inlined, and either it was declared as inline,
1671 or else the @samp{-finline-functions} option was given.
1673 @item -Wold-style-cast
1674 Warn if an old-style (C-style) cast is used within a program.
1676 @item -Woverloaded-virtual
1677 @cindex overloaded virtual fn, warning
1678 @cindex warning for overloaded virtual fn
1679 Warn when a derived class function declaration may be an error in
1680 defining a virtual function (C++ only). In a derived class, the
1681 definitions of virtual functions must match the type signature of a
1682 virtual function declared in the base class. With this option, the
1683 compiler warns when you define a function with the same name as a
1684 virtual function, but with a type signature that does not match any
1685 declarations from the base class.
1687 @item -Wsynth (C++ only)
1688 @cindex warning for synthesized methods
1689 @cindex synthesized methods, warning
1690 Warn when g++'s synthesis behavior does not match that of cfront. For
1696 A& operator = (int);
1706 In this example, g++ will synthesize a default @samp{A& operator =
1707 (const A&);}, while cfront will use the user-defined @samp{operator =}.
1710 Warn if @samp{long long} type is used. This is default. To inhibit
1711 the warning messages, use @samp{-Wno-long-long}. Flags
1712 @samp{-Wlong-long} and @samp{-Wno-long-long} are taken into account
1713 only when @samp{-pedantic} flag is used.
1716 Make all warnings into errors.
1719 @node Debugging Options
1720 @section Options for Debugging Your Program or GNU CC
1721 @cindex options, debugging
1722 @cindex debugging information options
1724 GNU CC has various special options that are used for debugging
1725 either your program or GCC:
1729 Produce debugging information in the operating system's native format
1730 (stabs, COFF, XCOFF, or DWARF). GDB can work with this debugging
1733 On most systems that use stabs format, @samp{-g} enables use of extra
1734 debugging information that only GDB can use; this extra information
1735 makes debugging work better in GDB but will probably make other debuggers
1737 refuse to read the program. If you want to control for certain whether
1738 to generate the extra information, use @samp{-gstabs+}, @samp{-gstabs},
1739 @samp{-gxcoff+}, @samp{-gxcoff}, @samp{-gdwarf-1+}, or @samp{-gdwarf-1}
1742 Unlike most other C compilers, GNU CC allows you to use @samp{-g} with
1743 @samp{-O}. The shortcuts taken by optimized code may occasionally
1744 produce surprising results: some variables you declared may not exist
1745 at all; flow of control may briefly move where you did not expect it;
1746 some statements may not be executed because they compute constant
1747 results or their values were already at hand; some statements may
1748 execute in different places because they were moved out of loops.
1750 Nevertheless it proves possible to debug optimized output. This makes
1751 it reasonable to use the optimizer for programs that might have bugs.
1753 The following options are useful when GNU CC is generated with the
1754 capability for more than one debugging format.
1757 Produce debugging information for use by GDB. This means to use the
1758 most expressive format available (DWARF 2, stabs, or the native format
1759 if neither of those are supported), including GDB extensions if at all
1763 Produce debugging information in stabs format (if that is supported),
1764 without GDB extensions. This is the format used by DBX on most BSD
1765 systems. On MIPS, Alpha and System V Release 4 systems this option
1766 produces stabs debugging output which is not understood by DBX or SDB.
1767 On System V Release 4 systems this option requires the GNU assembler.
1770 Produce debugging information in stabs format (if that is supported),
1771 using GNU extensions understood only by the GNU debugger (GDB). The
1772 use of these extensions is likely to make other debuggers crash or
1773 refuse to read the program.
1776 Produce debugging information in COFF format (if that is supported).
1777 This is the format used by SDB on most System V systems prior to
1781 Produce debugging information in XCOFF format (if that is supported).
1782 This is the format used by the DBX debugger on IBM RS/6000 systems.
1785 Produce debugging information in XCOFF format (if that is supported),
1786 using GNU extensions understood only by the GNU debugger (GDB). The
1787 use of these extensions is likely to make other debuggers crash or
1788 refuse to read the program, and may cause assemblers other than the GNU
1789 assembler (GAS) to fail with an error.
1792 Produce debugging information in DWARF version 1 format (if that is
1793 supported). This is the format used by SDB on most System V Release 4
1797 Produce debugging information in DWARF version 1 format (if that is
1798 supported), using GNU extensions understood only by the GNU debugger
1799 (GDB). The use of these extensions is likely to make other debuggers
1800 crash or refuse to read the program.
1803 Produce debugging information in DWARF version 2 format (if that is
1804 supported). This is the format used by DBX on IRIX 6.
1807 @itemx -ggdb@var{level}
1808 @itemx -gstabs@var{level}
1809 @itemx -gcoff@var{level}
1810 @itemx -gxcoff@var{level}
1811 @itemx -gdwarf@var{level}
1812 @itemx -gdwarf-2@var{level}
1813 Request debugging information and also use @var{level} to specify how
1814 much information. The default level is 2.
1816 Level 1 produces minimal information, enough for making backtraces in
1817 parts of the program that you don't plan to debug. This includes
1818 descriptions of functions and external variables, but no information
1819 about local variables and no line numbers.
1821 Level 3 includes extra information, such as all the macro definitions
1822 present in the program. Some debuggers support macro expansion when
1827 Generate extra code to write profile information suitable for the
1828 analysis program @code{prof}. You must use this option when compiling
1829 the source files you want data about, and you must also use it when
1832 @cindex @code{gprof}
1834 Generate extra code to write profile information suitable for the
1835 analysis program @code{gprof}. You must use this option when compiling
1836 the source files you want data about, and you must also use it when
1841 Generate extra code to write profile information for basic blocks, which will
1842 record the number of times each basic block is executed, the basic block start
1843 address, and the function name containing the basic block. If @samp{-g} is
1844 used, the line number and filename of the start of the basic block will also be
1845 recorded. If not overridden by the machine description, the default action is
1846 to append to the text file @file{bb.out}.
1848 This data could be analyzed by a program like @code{tcov}. Note,
1849 however, that the format of the data is not what @code{tcov} expects.
1850 Eventually GNU @code{gprof} should be extended to process this data.
1853 Makes the compiler print out each function name as it is compiled, and
1854 print some statistics about each pass when it finishes.
1857 Generate extra code to profile basic blocks. Your executable will
1858 produce output that is a superset of that produced when @samp{-a} is
1859 used. Additional output is the source and target address of the basic
1860 blocks where a jump takes place, the number of times a jump is executed,
1861 and (optionally) the complete sequence of basic blocks being executed.
1862 The output is appended to file @file{bb.out}.
1864 You can examine different profiling aspects without recompilation. Your
1865 executable will read a list of function names from file @file{bb.in}.
1866 Profiling starts when a function on the list is entered and stops when
1867 that invocation is exited. To exclude a function from profiling, prefix
1868 its name with `-'. If a function name is not unique, you can
1869 disambiguate it by writing it in the form
1870 @samp{/path/filename.d:functionname}. Your executable will write the
1871 available paths and filenames in file @file{bb.out}.
1873 Several function names have a special meaning:
1876 Write source, target and frequency of jumps to file @file{bb.out}.
1877 @item __bb_hidecall__
1878 Exclude function calls from frequency count.
1879 @item __bb_showret__
1880 Include function returns in frequency count.
1882 Write the sequence of basic blocks executed to file @file{bbtrace.gz}.
1883 The file will be compressed using the program @samp{gzip}, which must
1884 exist in your @code{PATH}. On systems without the @samp{popen}
1885 function, the file will be named @file{bbtrace} and will not be
1886 compressed. @strong{Profiling for even a few seconds on these systems
1887 will produce a very large file.} Note: @code{__bb_hidecall__} and
1888 @code{__bb_showret__} will not affect the sequence written to
1892 Here's a short example using different profiling parameters
1893 in file @file{bb.in}. Assume function @code{foo} consists of basic blocks
1894 1 and 2 and is called twice from block 3 of function @code{main}. After
1895 the calls, block 3 transfers control to block 4 of @code{main}.
1897 With @code{__bb_trace__} and @code{main} contained in file @file{bb.in},
1898 the following sequence of blocks is written to file @file{bbtrace.gz}:
1899 0 3 1 2 1 2 4. The return from block 2 to block 3 is not shown, because
1900 the return is to a point inside the block and not to the top. The
1901 block address 0 always indicates, that control is transferred
1902 to the trace from somewhere outside the observed functions. With
1903 @samp{-foo} added to @file{bb.in}, the blocks of function
1904 @code{foo} are removed from the trace, so only 0 3 4 remains.
1906 With @code{__bb_jumps__} and @code{main} contained in file @file{bb.in},
1907 jump frequencies will be written to file @file{bb.out}. The
1908 frequencies are obtained by constructing a trace of blocks
1909 and incrementing a counter for every neighbouring pair of blocks
1910 in the trace. The trace 0 3 1 2 1 2 4 displays the following
1914 Jump from block 0x0 to block 0x3 executed 1 time(s)
1915 Jump from block 0x3 to block 0x1 executed 1 time(s)
1916 Jump from block 0x1 to block 0x2 executed 2 time(s)
1917 Jump from block 0x2 to block 0x1 executed 1 time(s)
1918 Jump from block 0x2 to block 0x4 executed 1 time(s)
1921 With @code{__bb_hidecall__}, control transfer due to call instructions
1922 is removed from the trace, that is the trace is cut into three parts: 0
1923 3 4, 0 1 2 and 0 1 2. With @code{__bb_showret__}, control transfer due
1924 to return instructions is added to the trace. The trace becomes: 0 3 1
1925 2 3 1 2 3 4. Note, that this trace is not the same, as the sequence
1926 written to @file{bbtrace.gz}. It is solely used for counting jump
1929 @item -fprofile-arcs
1930 Instrument @dfn{arcs} during compilation. For each function of your
1931 program, GNU CC creates a program flow graph, then finds a spanning tree
1932 for the graph. Only arcs that are not on the spanning tree have to be
1933 instrumented: the compiler adds code to count the number of times that these
1934 arcs are executed. When an arc is the only exit or only entrance to a
1935 block, the instrumentation code can be added to the block; otherwise, a
1936 new basic block must be created to hold the instrumentation code.
1938 Since not every arc in the program must be instrumented, programs
1939 compiled with this option run faster than programs compiled with
1940 @samp{-a}, which adds instrumentation code to every basic block in the
1941 program. The tradeoff: since @code{gcov} does not have
1942 execution counts for all branches, it must start with the execution
1943 counts for the instrumented branches, and then iterate over the program
1944 flow graph until the entire graph has been solved. Hence, @code{gcov}
1945 runs a little more slowly than a program which uses information from
1948 @samp{-fprofile-arcs} also makes it possible to estimate branch
1949 probabilities, and to calculate basic block execution counts. In
1950 general, basic block execution counts do not give enough information to
1951 estimate all branch probabilities. When the compiled program exits, it
1952 saves the arc execution counts to a file called
1953 @file{@var{sourcename}.da}. Use the compiler option
1954 @samp{-fbranch-probabilities} (@pxref{Optimize Options,,Options that
1955 Control Optimization}) when recompiling, to optimize using estimated
1956 branch probabilities.
1959 @item -ftest-coverage
1960 Create data files for the @code{gcov} code-coverage utility
1961 (@pxref{Gcov,, @code{gcov}: a GNU CC Test Coverage Program}).
1962 The data file names begin with the name of your source file:
1965 @item @var{sourcename}.bb
1966 A mapping from basic blocks to line numbers, which @code{gcov} uses to
1967 associate basic block execution counts with line numbers.
1969 @item @var{sourcename}.bbg
1970 A list of all arcs in the program flow graph. This allows @code{gcov}
1971 to reconstruct the program flow graph, so that it can compute all basic
1972 block and arc execution counts from the information in the
1973 @code{@var{sourcename}.da} file (this last file is the output from
1974 @samp{-fprofile-arcs}).
1978 Makes the compiler print out each function name as it is compiled, and
1979 print some statistics about each pass when it finishes.
1981 @item -d@var{letters}
1982 Says to make debugging dumps during compilation at times specified by
1983 @var{letters}. This is used for debugging the compiler. The file names
1984 for most of the dumps are made by appending a word to the source file
1985 name (e.g. @file{foo.c.rtl} or @file{foo.c.jump}). Here are the
1986 possible letters for use in @var{letters}, and their meanings:
1990 Dump after computing branch probabilities, to @file{@var{file}.bp}.
1992 Dump after instruction combination, to the file @file{@var{file}.combine}.
1994 Dump after delayed branch scheduling, to @file{@var{file}.dbr}.
1996 Dump all macro definitions, at the end of preprocessing, in addition to
1999 Dump debugging information during parsing, to standard error.
2001 Dump after RTL generation, to @file{@var{file}.rtl}.
2003 Just generate RTL for a function instead of compiling it. Usually used
2006 Dump after first jump optimization, to @file{@var{file}.jump}.
2008 Dump after CSE (including the jump optimization that sometimes
2009 follows CSE), to @file{@var{file}.cse}.
2011 Dump after purging ADDRESSOF, to @file{@var{file}.addressof}.
2013 Dump after flow analysis, to @file{@var{file}.flow}.
2015 Dump after global register allocation, to @file{@var{file}.greg}.
2017 Dump after GCSE, to @file{@var{file}.gcse}.
2019 Dump after first jump optimization, to @file{@var{file}.jump}.
2021 Dump after last jump optimization, to @file{@var{file}.jump2}.
2023 Dump after conversion from registers to stack, to @file{@var{file}.stack}.
2025 Dump after local register allocation, to @file{@var{file}.lreg}.
2027 Dump after loop optimization, to @file{@var{file}.loop}.
2029 Dump after performing the machine dependent reorganisation pass, to
2030 @file{@var{file}.mach}.
2032 Dump after the register move pass, to @file{@var{file}.regmove}.
2034 Dump after RTL generation, to @file{@var{file}.rtl}.
2036 Dump after the second instruction scheduling pass, to @file{@var{file}.sched2}.
2038 Dump after CSE (including the jump optimization that sometimes follows
2039 CSE), to @file{@var{file}.cse}.
2041 Dump after the first instruction scheduling pass, to @file{@var{file}.sched}.
2043 Dump after the second CSE pass (including the jump optimization that
2044 sometimes follows CSE), to @file{@var{file}.cse2}.
2046 Just generate RTL for a function instead of compiling it. Usually used
2049 Produce all the dumps listed above.
2051 Print statistics on memory usage, at the end of the run, to
2054 Annotate the assembler output with a comment indicating which
2055 pattern and alternative was used.
2057 Dump debugging information during parsing, to standard error.
2059 Annotate the assembler output with miscellaneous debugging information.
2062 @item -fdump-unnumbered
2063 When doing debugging dumps (see -d option above), suppress instruction
2064 numbers and line number note output. This makes it more feasible to
2065 use diff on debugging dumps for compiler invokations with different
2066 options, in particular with and without -g.
2068 @item -fpretend-float
2069 When running a cross-compiler, pretend that the target machine uses the
2070 same floating point format as the host machine. This causes incorrect
2071 output of the actual floating constants, but the actual instruction
2072 sequence will probably be the same as GNU CC would make when running on
2076 Store the usual ``temporary'' intermediate files permanently; place them
2077 in the current directory and name them based on the source file. Thus,
2078 compiling @file{foo.c} with @samp{-c -save-temps} would produce files
2079 @file{foo.i} and @file{foo.s}, as well as @file{foo.o}.
2081 @item -print-file-name=@var{library}
2082 Print the full absolute name of the library file @var{library} that
2083 would be used when linking---and don't do anything else. With this
2084 option, GNU CC does not compile or link anything; it just prints the
2087 @item -print-prog-name=@var{program}
2088 Like @samp{-print-file-name}, but searches for a program such as @samp{cpp}.
2090 @item -print-libgcc-file-name
2091 Same as @samp{-print-file-name=libgcc.a}.
2093 This is useful when you use @samp{-nostdlib} or @samp{-nodefaultlibs}
2094 but you do want to link with @file{libgcc.a}. You can do
2097 gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
2100 @item -print-search-dirs
2101 Print the name of the configured installation directory and a list of
2102 program and library directories gcc will search---and don't do anything else.
2104 This is useful when gcc prints the error message
2105 @samp{installation problem, cannot exec cpp: No such file or directory}.
2106 To resolve this you either need to put @file{cpp} and the other compiler
2107 components where gcc expects to find them, or you can set the environment
2108 variable @code{GCC_EXEC_PREFIX} to the directory where you installed them.
2109 Don't forget the trailing '/'.
2110 @xref{Environment Variables}.
2113 @node Optimize Options
2114 @section Options That Control Optimization
2115 @cindex optimize options
2116 @cindex options, optimization
2118 These options control various sorts of optimizations:
2123 Optimize. Optimizing compilation takes somewhat more time, and a lot
2124 more memory for a large function.
2126 Without @samp{-O}, the compiler's goal is to reduce the cost of
2127 compilation and to make debugging produce the expected results.
2128 Statements are independent: if you stop the program with a breakpoint
2129 between statements, you can then assign a new value to any variable or
2130 change the program counter to any other statement in the function and
2131 get exactly the results you would expect from the source code.
2133 Without @samp{-O}, the compiler only allocates variables declared
2134 @code{register} in registers. The resulting compiled code is a little
2135 worse than produced by PCC without @samp{-O}.
2137 With @samp{-O}, the compiler tries to reduce code size and execution
2140 When you specify @samp{-O}, the compiler turns on @samp{-fthread-jumps}
2141 and @samp{-fdefer-pop} on all machines. The compiler turns on
2142 @samp{-fdelayed-branch} on machines that have delay slots, and
2143 @samp{-fomit-frame-pointer} on machines that can support debugging even
2144 without a frame pointer. On some machines the compiler also turns
2145 on other flags.@refill
2148 Optimize even more. GNU CC performs nearly all supported optimizations
2149 that do not involve a space-speed tradeoff. The compiler does not
2150 perform loop unrolling or function inlining when you specify @samp{-O2}.
2151 As compared to @samp{-O}, this option increases both compilation time
2152 and the performance of the generated code.
2154 @samp{-O2} turns on all optional optimizations except for loop unrolling
2155 and function inlining. It also turns on the @samp{-fforce-mem} option
2156 on all machines and frame pointer elimination on machines where doing so
2157 does not interfere with debugging.
2160 Optimize yet more. @samp{-O3} turns on all optimizations specified by
2161 @samp{-O2} and also turns on the @samp{inline-functions} option.
2167 Optimize for size. @samp{-Os} enables all @samp{-O2} optimizations that
2168 do not typically increase code size. It also performs further
2169 optimizations designed to reduce code size.
2171 If you use multiple @samp{-O} options, with or without level numbers,
2172 the last such option is the one that is effective.
2175 Options of the form @samp{-f@var{flag}} specify machine-independent
2176 flags. Most flags have both positive and negative forms; the negative
2177 form of @samp{-ffoo} would be @samp{-fno-foo}. In the table below,
2178 only one of the forms is listed---the one which is not the default.
2179 You can figure out the other form by either removing @samp{no-} or
2184 Do not store floating point variables in registers, and inhibit other
2185 options that might change whether a floating point value is taken from a
2188 @cindex floating point precision
2189 This option prevents undesirable excess precision on machines such as
2190 the 68000 where the floating registers (of the 68881) keep more
2191 precision than a @code{double} is supposed to have. Similarly for the
2192 x86 architecture. For most programs, the excess precision does only
2193 good, but a few programs rely on the precise definition of IEEE floating
2194 point. Use @samp{-ffloat-store} for such programs, after modifying
2195 them to store all pertinent intermediate computations into variables.
2197 @item -fno-default-inline
2198 Do not make member functions inline by default merely because they are
2199 defined inside the class scope (C++ only). Otherwise, when you specify
2200 @w{@samp{-O}}, member functions defined inside class scope are compiled
2201 inline by default; i.e., you don't need to add @samp{inline} in front of
2202 the member function name.
2204 @item -fno-defer-pop
2205 Always pop the arguments to each function call as soon as that function
2206 returns. For machines which must pop arguments after a function call,
2207 the compiler normally lets arguments accumulate on the stack for several
2208 function calls and pops them all at once.
2211 Force memory operands to be copied into registers before doing
2212 arithmetic on them. This produces better code by making all memory
2213 references potential common subexpressions. When they are not common
2214 subexpressions, instruction combination should eliminate the separate
2215 register-load. The @samp{-O2} option turns on this option.
2218 Force memory address constants to be copied into registers before
2219 doing arithmetic on them. This may produce better code just as
2220 @samp{-fforce-mem} may.
2222 @item -fomit-frame-pointer
2223 Don't keep the frame pointer in a register for functions that
2224 don't need one. This avoids the instructions to save, set up and
2225 restore frame pointers; it also makes an extra register available
2226 in many functions. @strong{It also makes debugging impossible on
2230 On some machines, such as the Vax, this flag has no effect, because
2231 the standard calling sequence automatically handles the frame pointer
2232 and nothing is saved by pretending it doesn't exist. The
2233 machine-description macro @code{FRAME_POINTER_REQUIRED} controls
2234 whether a target machine supports this flag. @xref{Registers}.@refill
2237 On some machines, such as the Vax, this flag has no effect, because
2238 the standard calling sequence automatically handles the frame pointer
2239 and nothing is saved by pretending it doesn't exist. The
2240 machine-description macro @code{FRAME_POINTER_REQUIRED} controls
2241 whether a target machine supports this flag. @xref{Registers,,Register
2242 Usage, gcc.info, Using and Porting GCC}.@refill
2246 Don't pay attention to the @code{inline} keyword. Normally this option
2247 is used to keep the compiler from expanding any functions inline.
2248 Note that if you are not optimizing, no functions can be expanded inline.
2250 @item -finline-functions
2251 Integrate all simple functions into their callers. The compiler
2252 heuristically decides which functions are simple enough to be worth
2253 integrating in this way.
2255 If all calls to a given function are integrated, and the function is
2256 declared @code{static}, then the function is normally not output as
2257 assembler code in its own right.
2259 @item -fkeep-inline-functions
2260 Even if all calls to a given function are integrated, and the function
2261 is declared @code{static}, nevertheless output a separate run-time
2262 callable version of the function. This switch does not affect
2263 @code{extern inline} functions.
2265 @item -fkeep-static-consts
2266 Emit variables declared @code{static const} when optimization isn't turned
2267 on, even if the variables aren't referenced.
2269 GNU CC enables this option by default. If you want to force the compiler to
2270 check if the variable was referenced, regardless of whether or not
2271 optimization is turned on, use the @samp{-fno-keep-static-consts} option.
2273 @item -fno-function-cse
2274 Do not put function addresses in registers; make each instruction that
2275 calls a constant function contain the function's address explicitly.
2277 This option results in less efficient code, but some strange hacks
2278 that alter the assembler output may be confused by the optimizations
2279 performed when this option is not used.
2282 This option allows GCC to violate some ANSI or IEEE rules and/or
2283 specifications in the interest of optimizing code for speed. For
2284 example, it allows the compiler to assume arguments to the @code{sqrt}
2285 function are non-negative numbers and that no floating-point values
2288 This option should never be turned on by any @samp{-O} option since
2289 it can result in incorrect output for programs which depend on
2290 an exact implementation of IEEE or ANSI rules/specifications for
2294 @c following causes underfulls.. they don't look great, but we deal.
2296 The following options control specific optimizations. The @samp{-O2}
2297 option turns on all of these optimizations except @samp{-funroll-loops}
2298 and @samp{-funroll-all-loops}. On most machines, the @samp{-O} option
2299 turns on the @samp{-fthread-jumps} and @samp{-fdelayed-branch} options,
2300 but specific machines may handle it differently.
2302 You can use the following flags in the rare cases when ``fine-tuning''
2303 of optimizations to be performed is desired.
2306 @item -fstrength-reduce
2307 Perform the optimizations of loop strength reduction and
2308 elimination of iteration variables.
2310 @item -fthread-jumps
2311 Perform optimizations where we check to see if a jump branches to a
2312 location where another comparison subsumed by the first is found. If
2313 so, the first branch is redirected to either the destination of the
2314 second branch or a point immediately following it, depending on whether
2315 the condition is known to be true or false.
2317 @item -fcse-follow-jumps
2318 In common subexpression elimination, scan through jump instructions
2319 when the target of the jump is not reached by any other path. For
2320 example, when CSE encounters an @code{if} statement with an
2321 @code{else} clause, CSE will follow the jump when the condition
2324 @item -fcse-skip-blocks
2325 This is similar to @samp{-fcse-follow-jumps}, but causes CSE to
2326 follow jumps which conditionally skip over blocks. When CSE
2327 encounters a simple @code{if} statement with no else clause,
2328 @samp{-fcse-skip-blocks} causes CSE to follow the jump around the
2329 body of the @code{if}.
2331 @item -frerun-cse-after-loop
2332 Re-run common subexpression elimination after loop optimizations has been
2335 @item -frerun-loop-opt
2336 Run the loop optimizer twice.
2339 Perform a global common subexpression elimination pass.
2340 This pass also performs global constant and copy propagation.
2342 @item -fexpensive-optimizations
2343 Perform a number of minor optimizations that are relatively expensive.
2345 @item -foptimize-register-moves
2347 Attempt to reassign register numbers in move instructions and as
2348 operands of other simple instructions in order to maximize the amount of
2349 register tying. This is especially helpful on machines with two-operand
2350 instructions. GNU CC enables this optimization by default with @samp{-O2}
2353 Note @code{-fregmove} and @code{-foptimize-register-moves} are the same
2356 @item -fdelayed-branch
2357 If supported for the target machine, attempt to reorder instructions
2358 to exploit instruction slots available after delayed branch
2361 @item -fschedule-insns
2362 If supported for the target machine, attempt to reorder instructions to
2363 eliminate execution stalls due to required data being unavailable. This
2364 helps machines that have slow floating point or memory load instructions
2365 by allowing other instructions to be issued until the result of the load
2366 or floating point instruction is required.
2368 @item -fschedule-insns2
2369 Similar to @samp{-fschedule-insns}, but requests an additional pass of
2370 instruction scheduling after register allocation has been done. This is
2371 especially useful on machines with a relatively small number of
2372 registers and where memory load instructions take more than one cycle.
2374 @item -ffunction-sections
2375 @item -fdata-sections
2376 Place each function or data item into its own section in the output
2377 file if the target supports arbitrary sections. The name of the
2378 function or the name of the data item determines the section's name
2381 Use these options on systems where the linker can perform optimizations
2382 to improve locality of reference in the instruction space. HPPA
2383 processors running HP-UX and Sparc processors running Solaris 2 have
2384 linkers with such optimizations. Other systems using the ELF object format
2385 as well as AIX may have these optimizations in the future.
2387 Only use these options when there are significant benefits from doing
2388 so. When you specify these options, the assembler and linker will
2389 create larger object and executable files and will also be slower.
2390 You will not be able to use @code{gprof} on all systems if you
2391 specify this option and you may have problems with debugging if
2392 you specify both this option and @samp{-g}.
2394 @item -fcaller-saves
2395 Enable values to be allocated in registers that will be clobbered by
2396 function calls, by emitting extra instructions to save and restore the
2397 registers around such calls. Such allocation is done only when it
2398 seems to result in better code than would otherwise be produced.
2400 This option is always enabled by default on certain machines, usually
2401 those which have no call-preserved registers to use instead.
2403 For all machines, optimization level 2 and higher enables this flag by
2406 @item -funroll-loops
2407 Perform the optimization of loop unrolling. This is only done for loops
2408 whose number of iterations can be determined at compile time or run time.
2409 @samp{-funroll-loop} implies both @samp{-fstrength-reduce} and
2410 @samp{-frerun-cse-after-loop}.
2412 @item -funroll-all-loops
2413 Perform the optimization of loop unrolling. This is done for all loops
2414 and usually makes programs run more slowly. @samp{-funroll-all-loops}
2415 implies @samp{-fstrength-reduce} as well as @samp{-frerun-cse-after-loop}.
2417 @item -fmove-all-movables
2418 Forces all invariant computations in loops to be moved
2421 @item -freduce-all-givs
2422 Forces all general-induction variables in loops to be
2425 @emph{Note:} When compiling programs written in Fortran,
2426 @samp{-fmove-all-moveables} and @samp{-freduce-all-givs} are enabled
2427 by default when you use the optimizer.
2429 These options may generate better or worse code; results are highly
2430 dependent on the structure of loops within the source code.
2432 These two options are intended to be removed someday, once
2433 they have helped determine the efficacy of various
2434 approaches to improving loop optimizations.
2436 Please let us (@code{egcs@@cygnus.com} and @code{fortran@@gnu.org})
2437 know how use of these options affects
2438 the performance of your production code.
2439 We're very interested in code that runs @emph{slower}
2440 when these options are @emph{enabled}.
2443 Disable any machine-specific peephole optimizations.
2445 @item -fbranch-probabilities
2446 After running a program compiled with @samp{-fprofile-arcs}
2447 (@pxref{Debugging Options,, Options for Debugging Your Program or
2448 @code{gcc}}), you can compile it a second time using
2449 @samp{-fbranch-probabilities}, to improve optimizations based on
2450 guessing the path a branch might take.
2453 With @samp{-fbranch-probabilities}, GCC puts a @samp{REG_EXEC_COUNT}
2454 note on the first instruction of each basic block, and a
2455 @samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}.
2456 These can be used to improve optimization. Currently, they are only
2457 used in one place: in @file{reorg.c}, instead of guessing which path a
2458 branch is mostly to take, the @samp{REG_BR_PROB} values are used to
2459 exactly determine which path is taken more often.
2462 @item -fstrict-aliasing
2463 Allows the compiler to assume the strictest aliasing rules applicable to
2464 the language being compiled. For C (and C++), this activates
2465 optimizations based on the type of expressions. In particular, an
2466 object of one type is assumed never to reside at the same address as an
2467 object of a different type, unless the types are almost the same. For
2468 example, an @code{unsigned int} can alias an @code{int}, but not a
2469 @code{void*} or a @code{double}. A character type may alias any other
2472 Pay special attention to code like this:
2485 The practice of reading from a different union member than the one most
2486 recently written to (called ``type-punning'') is common. Even with
2487 @samp{-fstrict-aliasing}, type-punning is allowed, provided the memory
2488 is accessed through the union type. So, the code above will work as
2489 expected. However, this code might not:
2501 Every language that wishes to perform language-specific alias analysis
2502 should define a function that computes, given an @code{tree}
2503 node, an alias set for the node. Nodes in different alias sets are not
2504 allowed to alias. For an example, see the C front-end function
2505 @code{c_get_alias_set}.
2510 @node Preprocessor Options
2511 @section Options Controlling the Preprocessor
2512 @cindex preprocessor options
2513 @cindex options, preprocessor
2515 These options control the C preprocessor, which is run on each C source
2516 file before actual compilation.
2518 If you use the @samp{-E} option, nothing is done except preprocessing.
2519 Some of these options make sense only together with @samp{-E} because
2520 they cause the preprocessor output to be unsuitable for actual
2524 @item -include @var{file}
2525 Process @var{file} as input before processing the regular input file.
2526 In effect, the contents of @var{file} are compiled first. Any @samp{-D}
2527 and @samp{-U} options on the command line are always processed before
2528 @samp{-include @var{file}}, regardless of the order in which they are
2529 written. All the @samp{-include} and @samp{-imacros} options are
2530 processed in the order in which they are written.
2532 @item -imacros @var{file}
2533 Process @var{file} as input, discarding the resulting output, before
2534 processing the regular input file. Because the output generated from
2535 @var{file} is discarded, the only effect of @samp{-imacros @var{file}}
2536 is to make the macros defined in @var{file} available for use in the
2539 Any @samp{-D} and @samp{-U} options on the command line are always
2540 processed before @samp{-imacros @var{file}}, regardless of the order in
2541 which they are written. All the @samp{-include} and @samp{-imacros}
2542 options are processed in the order in which they are written.
2544 @item -idirafter @var{dir}
2545 @cindex second include path
2546 Add the directory @var{dir} to the second include path. The directories
2547 on the second include path are searched when a header file is not found
2548 in any of the directories in the main include path (the one that
2551 @item -iprefix @var{prefix}
2552 Specify @var{prefix} as the prefix for subsequent @samp{-iwithprefix}
2555 @item -iwithprefix @var{dir}
2556 Add a directory to the second include path. The directory's name is
2557 made by concatenating @var{prefix} and @var{dir}, where @var{prefix} was
2558 specified previously with @samp{-iprefix}. If you have not specified a
2559 prefix yet, the directory containing the installed passes of the
2560 compiler is used as the default.
2562 @item -iwithprefixbefore @var{dir}
2563 Add a directory to the main include path. The directory's name is made
2564 by concatenating @var{prefix} and @var{dir}, as in the case of
2565 @samp{-iwithprefix}.
2567 @item -isystem @var{dir}
2568 Add a directory to the beginning of the second include path, marking it
2569 as a system directory, so that it gets the same special treatment as
2570 is applied to the standard system directories.
2573 Do not search the standard system directories for header files. Only
2574 the directories you have specified with @samp{-I} options (and the
2575 current directory, if appropriate) are searched. @xref{Directory
2576 Options}, for information on @samp{-I}.
2578 By using both @samp{-nostdinc} and @samp{-I-}, you can limit the include-file
2579 search path to only those directories you specify explicitly.
2582 Do not predefine any nonstandard macros. (Including architecture flags).
2585 Run only the C preprocessor. Preprocess all the C source files
2586 specified and output the results to standard output or to the
2587 specified output file.
2590 Tell the preprocessor not to discard comments. Used with the
2594 Tell the preprocessor not to generate @samp{#line} directives.
2595 Used with the @samp{-E} option.
2598 @cindex dependencies, make
2600 Tell the preprocessor to output a rule suitable for @code{make}
2601 describing the dependencies of each object file. For each source file,
2602 the preprocessor outputs one @code{make}-rule whose target is the object
2603 file name for that source file and whose dependencies are all the
2604 @code{#include} header files it uses. This rule may be a single line or
2605 may be continued with @samp{\}-newline if it is long. The list of rules
2606 is printed on standard output instead of the preprocessed C program.
2608 @samp{-M} implies @samp{-E}.
2610 Another way to specify output of a @code{make} rule is by setting
2611 the environment variable @code{DEPENDENCIES_OUTPUT} (@pxref{Environment
2615 Like @samp{-M} but the output mentions only the user header files
2616 included with @samp{#include "@var{file}"}. System header files
2617 included with @samp{#include <@var{file}>} are omitted.
2620 Like @samp{-M} but the dependency information is written to a file made by
2621 replacing ".c" with ".d" at the end of the input file names.
2622 This is in addition to compiling the file as specified---@samp{-MD} does
2623 not inhibit ordinary compilation the way @samp{-M} does.
2625 In Mach, you can use the utility @code{md} to merge multiple dependency
2626 files into a single dependency file suitable for using with the @samp{make}
2630 Like @samp{-MD} except mention only user header files, not system
2634 Treat missing header files as generated files and assume they live in the
2635 same directory as the source file. If you specify @samp{-MG}, you
2636 must also specify either @samp{-M} or @samp{-MM}. @samp{-MG} is not
2637 supported with @samp{-MD} or @samp{-MMD}.
2640 Print the name of each header file used, in addition to other normal
2643 @item -A@var{question}(@var{answer})
2644 Assert the answer @var{answer} for @var{question}, in case it is tested
2645 with a preprocessing conditional such as @samp{#if
2646 #@var{question}(@var{answer})}. @samp{-A-} disables the standard
2647 assertions that normally describe the target machine.
2650 Define macro @var{macro} with the string @samp{1} as its definition.
2652 @item -D@var{macro}=@var{defn}
2653 Define macro @var{macro} as @var{defn}. All instances of @samp{-D} on
2654 the command line are processed before any @samp{-U} options.
2657 Undefine macro @var{macro}. @samp{-U} options are evaluated after all
2658 @samp{-D} options, but before any @samp{-include} and @samp{-imacros}
2662 Tell the preprocessor to output only a list of the macro definitions
2663 that are in effect at the end of preprocessing. Used with the @samp{-E}
2667 Tell the preprocessing to pass all macro definitions into the output, in
2668 their proper sequence in the rest of the output.
2671 Like @samp{-dD} except that the macro arguments and contents are omitted.
2672 Only @samp{#define @var{name}} is included in the output.
2675 Support ANSI C trigraphs. The @samp{-ansi} option also has this effect.
2677 @item -Wp,@var{option}
2678 Pass @var{option} as an option to the preprocessor. If @var{option}
2679 contains commas, it is split into multiple options at the commas.
2682 @node Assembler Options
2683 @section Passing Options to the Assembler
2685 @c prevent bad page break with this line
2686 You can pass options to the assembler.
2689 @item -Wa,@var{option}
2690 Pass @var{option} as an option to the assembler. If @var{option}
2691 contains commas, it is split into multiple options at the commas.
2695 @section Options for Linking
2696 @cindex link options
2697 @cindex options, linking
2699 These options come into play when the compiler links object files into
2700 an executable output file. They are meaningless if the compiler is
2701 not doing a link step.
2705 @item @var{object-file-name}
2706 A file name that does not end in a special recognized suffix is
2707 considered to name an object file or library. (Object files are
2708 distinguished from libraries by the linker according to the file
2709 contents.) If linking is done, these object files are used as input
2715 If any of these options is used, then the linker is not run, and
2716 object file names should not be used as arguments. @xref{Overall
2720 @item -l@var{library}
2721 Search the library named @var{library} when linking.
2723 It makes a difference where in the command you write this option; the
2724 linker searches processes libraries and object files in the order they
2725 are specified. Thus, @samp{foo.o -lz bar.o} searches library @samp{z}
2726 after file @file{foo.o} but before @file{bar.o}. If @file{bar.o} refers
2727 to functions in @samp{z}, those functions may not be loaded.
2729 The linker searches a standard list of directories for the library,
2730 which is actually a file named @file{lib@var{library}.a}. The linker
2731 then uses this file as if it had been specified precisely by name.
2733 The directories searched include several standard system directories
2734 plus any that you specify with @samp{-L}.
2736 Normally the files found this way are library files---archive files
2737 whose members are object files. The linker handles an archive file by
2738 scanning through it for members which define symbols that have so far
2739 been referenced but not defined. But if the file that is found is an
2740 ordinary object file, it is linked in the usual fashion. The only
2741 difference between using an @samp{-l} option and specifying a file name
2742 is that @samp{-l} surrounds @var{library} with @samp{lib} and @samp{.a}
2743 and searches several directories.
2746 You need this special case of the @samp{-l} option in order to
2747 link an Objective C program.
2750 Do not use the standard system startup files when linking.
2751 The standard system libraries are used normally, unless @code{-nostdlib}
2752 or @code{-nodefaultlibs} is used.
2754 @item -nodefaultlibs
2755 Do not use the standard system libraries when linking.
2756 Only the libraries you specify will be passed to the linker.
2757 The standard startup files are used normally, unless @code{-nostartfiles}
2758 is used. The compiler may generate calls to memcmp, memset, and memcpy
2759 for System V (and ANSI C) environments or to bcopy and bzero for
2760 BSD environments. These entries are usually resolved by entries in
2761 libc. These entry points should be supplied through some other
2762 mechanism when this option is specified.
2765 Do not use the standard system startup files or libraries when linking.
2766 No startup files and only the libraries you specify will be passed to
2767 the linker. The compiler may generate calls to memcmp, memset, and memcpy
2768 for System V (and ANSI C) environments or to bcopy and bzero for
2769 BSD environments. These entries are usually resolved by entries in
2770 libc. These entry points should be supplied through some other
2771 mechanism when this option is specified.
2773 @cindex @code{-lgcc}, use with @code{-nostdlib}
2774 @cindex @code{-nostdlib} and unresolved references
2775 @cindex unresolved references and @code{-nostdlib}
2776 @cindex @code{-lgcc}, use with @code{-nodefaultlibs}
2777 @cindex @code{-nodefaultlibs} and unresolved references
2778 @cindex unresolved references and @code{-nodefaultlibs}
2779 One of the standard libraries bypassed by @samp{-nostdlib} and
2780 @samp{-nodefaultlibs} is @file{libgcc.a}, a library of internal subroutines
2781 that GNU CC uses to overcome shortcomings of particular machines, or special
2782 needs for some languages.
2784 (@xref{Interface,,Interfacing to GNU CC Output}, for more discussion of
2788 (@xref{Interface,,Interfacing to GNU CC Output,gcc.info,Porting GNU CC},
2789 for more discussion of @file{libgcc.a}.)
2791 In most cases, you need @file{libgcc.a} even when you want to avoid
2792 other standard libraries. In other words, when you specify @samp{-nostdlib}
2793 or @samp{-nodefaultlibs} you should usually specify @samp{-lgcc} as well.
2794 This ensures that you have no unresolved references to internal GNU CC
2795 library subroutines. (For example, @samp{__main}, used to ensure C++
2796 constructors will be called; @pxref{Collect2,,@code{collect2}}.)
2799 Remove all symbol table and relocation information from the executable.
2802 On systems that support dynamic linking, this prevents linking with the shared
2803 libraries. On other systems, this option has no effect.
2806 Produce a shared object which can then be linked with other objects to
2807 form an executable. Not all systems support this option. You must
2808 also specify @samp{-fpic} or @samp{-fPIC} on some systems when
2809 you specify this option.
2812 Bind references to global symbols when building a shared object. Warn
2813 about any unresolved references (unless overridden by the link editor
2814 option @samp{-Xlinker -z -Xlinker defs}). Only a few systems support
2817 @item -Xlinker @var{option}
2818 Pass @var{option} as an option to the linker. You can use this to
2819 supply system-specific linker options which GNU CC does not know how to
2822 If you want to pass an option that takes an argument, you must use
2823 @samp{-Xlinker} twice, once for the option and once for the argument.
2824 For example, to pass @samp{-assert definitions}, you must write
2825 @samp{-Xlinker -assert -Xlinker definitions}. It does not work to write
2826 @samp{-Xlinker "-assert definitions"}, because this passes the entire
2827 string as a single argument, which is not what the linker expects.
2829 @item -Wl,@var{option}
2830 Pass @var{option} as an option to the linker. If @var{option} contains
2831 commas, it is split into multiple options at the commas.
2833 @item -u @var{symbol}
2834 Pretend the symbol @var{symbol} is undefined, to force linking of
2835 library modules to define it. You can use @samp{-u} multiple times with
2836 different symbols to force loading of additional library modules.
2839 @node Directory Options
2840 @section Options for Directory Search
2841 @cindex directory options
2842 @cindex options, directory search
2845 These options specify directories to search for header files, for
2846 libraries and for parts of the compiler:
2850 Add the directory @var{dir} to the head of the list of directories to be
2851 searched for header files. This can be used to override a system header
2852 file, substituting your own version, since these directories are
2853 searched before the system header file directories. If you use more
2854 than one @samp{-I} option, the directories are scanned in left-to-right
2855 order; the standard system directories come after.
2858 Any directories you specify with @samp{-I} options before the @samp{-I-}
2859 option are searched only for the case of @samp{#include "@var{file}"};
2860 they are not searched for @samp{#include <@var{file}>}.
2862 If additional directories are specified with @samp{-I} options after
2863 the @samp{-I-}, these directories are searched for all @samp{#include}
2864 directives. (Ordinarily @emph{all} @samp{-I} directories are used
2867 In addition, the @samp{-I-} option inhibits the use of the current
2868 directory (where the current input file came from) as the first search
2869 directory for @samp{#include "@var{file}"}. There is no way to
2870 override this effect of @samp{-I-}. With @samp{-I.} you can specify
2871 searching the directory which was current when the compiler was
2872 invoked. That is not exactly the same as what the preprocessor does
2873 by default, but it is often satisfactory.
2875 @samp{-I-} does not inhibit the use of the standard system directories
2876 for header files. Thus, @samp{-I-} and @samp{-nostdinc} are
2880 Add directory @var{dir} to the list of directories to be searched
2883 @item -B@var{prefix}
2884 This option specifies where to find the executables, libraries,
2885 include files, and data files of the compiler itself.
2887 The compiler driver program runs one or more of the subprograms
2888 @file{cpp}, @file{cc1}, @file{as} and @file{ld}. It tries
2889 @var{prefix} as a prefix for each program it tries to run, both with and
2890 without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}).
2892 For each subprogram to be run, the compiler driver first tries the
2893 @samp{-B} prefix, if any. If that name is not found, or if @samp{-B}
2894 was not specified, the driver tries two standard prefixes, which are
2895 @file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc-lib/}. If neither of
2896 those results in a file name that is found, the unmodified program
2897 name is searched for using the directories specified in your
2898 @samp{PATH} environment variable.
2900 @samp{-B} prefixes that effectively specify directory names also apply
2901 to libraries in the linker, because the compiler translates these
2902 options into @samp{-L} options for the linker. They also apply to
2903 includes files in the preprocessor, because the compiler translates these
2904 options into @samp{-isystem} options for the preprocessor. In this case,
2905 the compiler appends @samp{include} to the prefix.
2907 The run-time support file @file{libgcc.a} can also be searched for using
2908 the @samp{-B} prefix, if needed. If it is not found there, the two
2909 standard prefixes above are tried, and that is all. The file is left
2910 out of the link if it is not found by those means.
2912 Another way to specify a prefix much like the @samp{-B} prefix is to use
2913 the environment variable @code{GCC_EXEC_PREFIX}. @xref{Environment
2916 @item -specs=@var{file}
2917 Process @var{file} after the compiler reads in the standard @file{specs}
2918 file, in order to override the defaults that the @file{gcc} driver
2919 program uses when determining what switches to pass to @file{cc1},
2920 @file{cc1plus}, @file{as}, @file{ld}, etc. More than one
2921 @samp{-specs=}@var{file} can be specified on the command line, and they
2922 are processed in order, from left to right.
2925 @node Target Options
2926 @section Specifying Target Machine and Compiler Version
2927 @cindex target options
2928 @cindex cross compiling
2929 @cindex specifying machine version
2930 @cindex specifying compiler version and target machine
2931 @cindex compiler version, specifying
2932 @cindex target machine, specifying
2934 By default, GNU CC compiles code for the same type of machine that you
2935 are using. However, it can also be installed as a cross-compiler, to
2936 compile for some other type of machine. In fact, several different
2937 configurations of GNU CC, for different target machines, can be
2938 installed side by side. Then you specify which one to use with the
2941 In addition, older and newer versions of GNU CC can be installed side
2942 by side. One of them (probably the newest) will be the default, but
2943 you may sometimes wish to use another.
2946 @item -b @var{machine}
2947 The argument @var{machine} specifies the target machine for compilation.
2948 This is useful when you have installed GNU CC as a cross-compiler.
2950 The value to use for @var{machine} is the same as was specified as the
2951 machine type when configuring GNU CC as a cross-compiler. For
2952 example, if a cross-compiler was configured with @samp{configure
2953 i386v}, meaning to compile for an 80386 running System V, then you
2954 would specify @samp{-b i386v} to run that cross compiler.
2956 When you do not specify @samp{-b}, it normally means to compile for
2957 the same type of machine that you are using.
2959 @item -V @var{version}
2960 The argument @var{version} specifies which version of GNU CC to run.
2961 This is useful when multiple versions are installed. For example,
2962 @var{version} might be @samp{2.0}, meaning to run GNU CC version 2.0.
2964 The default version, when you do not specify @samp{-V}, is the last
2965 version of GNU CC that you installed.
2968 The @samp{-b} and @samp{-V} options actually work by controlling part of
2969 the file name used for the executable files and libraries used for
2970 compilation. A given version of GNU CC, for a given target machine, is
2971 normally kept in the directory @file{/usr/local/lib/gcc-lib/@var{machine}/@var{version}}.@refill
2973 Thus, sites can customize the effect of @samp{-b} or @samp{-V} either by
2974 changing the names of these directories or adding alternate names (or
2975 symbolic links). If in directory @file{/usr/local/lib/gcc-lib/} the
2976 file @file{80386} is a link to the file @file{i386v}, then @samp{-b
2977 80386} becomes an alias for @samp{-b i386v}.
2979 In one respect, the @samp{-b} or @samp{-V} do not completely change
2980 to a different compiler: the top-level driver program @code{gcc}
2981 that you originally invoked continues to run and invoke the other
2982 executables (preprocessor, compiler per se, assembler and linker)
2983 that do the real work. However, since no real work is done in the
2984 driver program, it usually does not matter that the driver program
2985 in use is not the one for the specified target and version.
2987 The only way that the driver program depends on the target machine is
2988 in the parsing and handling of special machine-specific options.
2989 However, this is controlled by a file which is found, along with the
2990 other executables, in the directory for the specified version and
2991 target machine. As a result, a single installed driver program adapts
2992 to any specified target machine and compiler version.
2994 The driver program executable does control one significant thing,
2995 however: the default version and target machine. Therefore, you can
2996 install different instances of the driver program, compiled for
2997 different targets or versions, under different names.
2999 For example, if the driver for version 2.0 is installed as @code{ogcc}
3000 and that for version 2.1 is installed as @code{gcc}, then the command
3001 @code{gcc} will use version 2.1 by default, while @code{ogcc} will use
3002 2.0 by default. However, you can choose either version with either
3003 command with the @samp{-V} option.
3005 @node Submodel Options
3006 @section Hardware Models and Configurations
3007 @cindex submodel options
3008 @cindex specifying hardware config
3009 @cindex hardware models and configurations, specifying
3010 @cindex machine dependent options
3012 Earlier we discussed the standard option @samp{-b} which chooses among
3013 different installed compilers for completely different target
3014 machines, such as Vax vs. 68000 vs. 80386.
3016 In addition, each of these target machine types can have its own
3017 special options, starting with @samp{-m}, to choose among various
3018 hardware models or configurations---for example, 68010 vs 68020,
3019 floating coprocessor or none. A single installed version of the
3020 compiler can compile for any model or configuration, according to the
3023 Some configurations of the compiler also support additional special
3024 options, usually for compatibility with other compilers on the same
3028 These options are defined by the macro @code{TARGET_SWITCHES} in the
3029 machine description. The default for the options is also defined by
3030 that macro, which enables you to change the defaults.
3045 * RS/6000 and PowerPC Options::
3050 * Intel 960 Options::
3051 * DEC Alpha Options::
3055 * System V Options::
3060 @node M680x0 Options
3061 @subsection M680x0 Options
3062 @cindex M680x0 options
3064 These are the @samp{-m} options defined for the 68000 series. The default
3065 values for these options depends on which style of 68000 was selected when
3066 the compiler was configured; the defaults for the most common choices are
3072 Generate output for a 68000. This is the default
3073 when the compiler is configured for 68000-based systems.
3075 Use this option for microcontrollers with a 68000 or EC000 core,
3076 including the 68008, 68302, 68306, 68307, 68322, 68328 and 68356.
3080 Generate output for a 68020. This is the default
3081 when the compiler is configured for 68020-based systems.
3084 Generate output containing 68881 instructions for floating point.
3085 This is the default for most 68020 systems unless @samp{-nfp} was
3086 specified when the compiler was configured.
3089 Generate output for a 68030. This is the default when the compiler is
3090 configured for 68030-based systems.
3093 Generate output for a 68040. This is the default when the compiler is
3094 configured for 68040-based systems.
3096 This option inhibits the use of 68881/68882 instructions that have to be
3097 emulated by software on the 68040. Use this option if your 68040 does not
3098 have code to emulate those instructions.
3101 Generate output for a 68060. This is the default when the compiler is
3102 configured for 68060-based systems.
3104 This option inhibits the use of 68020 and 68881/68882 instructions that
3105 have to be emulated by software on the 68060. Use this option if your 68060
3106 does not have code to emulate those instructions.
3109 Generate output for a CPU32. This is the default
3110 when the compiler is configured for CPU32-based systems.
3112 Use this option for microcontrollers with a
3113 CPU32 or CPU32+ core, including the 68330, 68331, 68332, 68333, 68334,
3114 68336, 68340, 68341, 68349 and 68360.
3117 Generate output for a 520X "coldfire" family cpu. This is the default
3118 when the compiler is configured for 520X-based systems.
3120 Use this option for microcontroller with a 5200 core, including
3121 the MCF5202, MCF5203, MCF5204 and MCF5202.
3125 Generate output for a 68040, without using any of the new instructions.
3126 This results in code which can run relatively efficiently on either a
3127 68020/68881 or a 68030 or a 68040. The generated code does use the
3128 68881 instructions that are emulated on the 68040.
3131 Generate output for a 68060, without using any of the new instructions.
3132 This results in code which can run relatively efficiently on either a
3133 68020/68881 or a 68030 or a 68040. The generated code does use the
3134 68881 instructions that are emulated on the 68060.
3137 Generate output containing Sun FPA instructions for floating point.
3140 Generate output containing library calls for floating point.
3141 @strong{Warning:} the requisite libraries are not available for all m68k
3142 targets. Normally the facilities of the machine's usual C compiler are
3143 used, but this can't be done directly in cross-compilation. You must
3144 make your own arrangements to provide suitable library functions for
3145 cross-compilation. The embedded targets @samp{m68k-*-aout} and
3146 @samp{m68k-*-coff} do provide software floating point support.
3149 Consider type @code{int} to be 16 bits wide, like @code{short int}.
3152 Do not use the bit-field instructions. The @samp{-m68000}, @samp{-mcpu32}
3153 and @samp{-m5200} options imply @w{@samp{-mnobitfield}}.
3156 Do use the bit-field instructions. The @samp{-m68020} option implies
3157 @samp{-mbitfield}. This is the default if you use a configuration
3158 designed for a 68020.
3161 Use a different function-calling convention, in which functions
3162 that take a fixed number of arguments return with the @code{rtd}
3163 instruction, which pops their arguments while returning. This
3164 saves one instruction in the caller since there is no need to pop
3165 the arguments there.
3167 This calling convention is incompatible with the one normally
3168 used on Unix, so you cannot use it if you need to call libraries
3169 compiled with the Unix compiler.
3171 Also, you must provide function prototypes for all functions that
3172 take variable numbers of arguments (including @code{printf});
3173 otherwise incorrect code will be generated for calls to those
3176 In addition, seriously incorrect code will result if you call a
3177 function with too many arguments. (Normally, extra arguments are
3178 harmlessly ignored.)
3180 The @code{rtd} instruction is supported by the 68010, 68020, 68030,
3181 68040, 68060 and CPU32 processors, but not by the 68000 or 5200.
3184 @itemx -mno-align-int
3185 Control whether GNU CC aligns @code{int}, @code{long}, @code{long long},
3186 @code{float}, @code{double}, and @code{long double} variables on a 32-bit
3187 boundary (@samp{-malign-int}) or a 16-bit boundary (@samp{-mno-align-int}).
3188 Aligning variables on 32-bit boundaries produces code that runs somewhat
3189 faster on processors with 32-bit busses at the expense of more memory.
3191 @strong{Warning:} if you use the @samp{-malign-int} switch, GNU CC will
3192 align structures containing the above types differently than
3193 most published application binary interface specifications for the m68k.
3198 @subsection VAX Options
3201 These @samp{-m} options are defined for the Vax:
3205 Do not output certain jump instructions (@code{aobleq} and so on)
3206 that the Unix assembler for the Vax cannot handle across long
3210 Do output those jump instructions, on the assumption that you
3211 will assemble with the GNU assembler.
3214 Output code for g-format floating point numbers instead of d-format.
3218 @subsection SPARC Options
3219 @cindex SPARC options
3221 These @samp{-m} switches are supported on the SPARC:
3226 Specify @samp{-mapp-regs} to generate output using the global registers
3227 2 through 4, which the SPARC SVR4 ABI reserves for applications. This
3230 To be fully SVR4 ABI compliant at the cost of some performance loss,
3231 specify @samp{-mno-app-regs}. You should compile libraries and system
3232 software with this option.
3236 Generate output containing floating point instructions. This is the
3241 Generate output containing library calls for floating point.
3242 @strong{Warning:} the requisite libraries are not available for all SPARC
3243 targets. Normally the facilities of the machine's usual C compiler are
3244 used, but this cannot be done directly in cross-compilation. You must make
3245 your own arrangements to provide suitable library functions for
3246 cross-compilation. The embedded targets @samp{sparc-*-aout} and
3247 @samp{sparclite-*-*} do provide software floating point support.
3249 @samp{-msoft-float} changes the calling convention in the output file;
3250 therefore, it is only useful if you compile @emph{all} of a program with
3251 this option. In particular, you need to compile @file{libgcc.a}, the
3252 library that comes with GNU CC, with @samp{-msoft-float} in order for
3255 @item -mhard-quad-float
3256 Generate output containing quad-word (long double) floating point
3259 @item -msoft-quad-float
3260 Generate output containing library calls for quad-word (long double)
3261 floating point instructions. The functions called are those specified
3262 in the SPARC ABI. This is the default.
3264 As of this writing, there are no sparc implementations that have hardware
3265 support for the quad-word floating point instructions. They all invoke
3266 a trap handler for one of these instructions, and then the trap handler
3267 emulates the effect of the instruction. Because of the trap handler overhead,
3268 this is much slower than calling the ABI library routines. Thus the
3269 @samp{-msoft-quad-float} option is the default.
3273 With @samp{-mepilogue} (the default), the compiler always emits code for
3274 function exit at the end of each function. Any function exit in
3275 the middle of the function (such as a return statement in C) will
3276 generate a jump to the exit code at the end of the function.
3278 With @samp{-mno-epilogue}, the compiler tries to emit exit code inline
3279 at every function exit.
3283 With @samp{-mflat}, the compiler does not generate save/restore instructions
3284 and will use a "flat" or single register window calling convention.
3285 This model uses %i7 as the frame pointer and is compatible with the normal
3286 register window model. Code from either may be intermixed.
3287 The local registers and the input registers (0-5) are still treated as
3288 "call saved" registers and will be saved on the stack as necessary.
3290 With @samp{-mno-flat} (the default), the compiler emits save/restore
3291 instructions (except for leaf functions) and is the normal mode of operation.
3293 @item -mno-unaligned-doubles
3294 @itemx -munaligned-doubles
3295 Assume that doubles have 8 byte alignment. This is the default.
3297 With @samp{-munaligned-doubles}, GNU CC assumes that doubles have 8 byte
3298 alignment only if they are contained in another type, or if they have an
3299 absolute address. Otherwise, it assumes they have 4 byte alignment.
3300 Specifying this option avoids some rare compatibility problems with code
3301 generated by other compilers. It is not the default because it results
3302 in a performance loss, especially for floating point code.
3306 These two options select variations on the SPARC architecture.
3308 By default (unless specifically configured for the Fujitsu SPARClite),
3309 GCC generates code for the v7 variant of the SPARC architecture.
3311 @samp{-mv8} will give you SPARC v8 code. The only difference from v7
3312 code is that the compiler emits the integer multiply and integer
3313 divide instructions which exist in SPARC v8 but not in SPARC v7.
3315 @samp{-msparclite} will give you SPARClite code. This adds the integer
3316 multiply, integer divide step and scan (@code{ffs}) instructions which
3317 exist in SPARClite but not in SPARC v7.
3319 These options are deprecated and will be deleted in GNU CC 2.9.
3320 They have been replaced with @samp{-mcpu=xxx}.
3324 These two options select the processor for which the code is optimised.
3326 With @samp{-mcypress} (the default), the compiler optimizes code for the
3327 Cypress CY7C602 chip, as used in the SparcStation/SparcServer 3xx series.
3328 This is also appropriate for the older SparcStation 1, 2, IPX etc.
3330 With @samp{-msupersparc} the compiler optimizes code for the SuperSparc cpu, as
3331 used in the SparcStation 10, 1000 and 2000 series. This flag also enables use
3332 of the full SPARC v8 instruction set.
3334 These options are deprecated and will be deleted in GNU CC 2.9.
3335 They have been replaced with @samp{-mcpu=xxx}.
3337 @item -mcpu=@var{cpu_type}
3338 Set the instruction set, register set, and instruction scheduling parameters
3339 for machine type @var{cpu_type}. Supported values for @var{cpu_type} are
3340 @samp{v7}, @samp{cypress}, @samp{v8}, @samp{supersparc}, @samp{sparclite},
3341 @samp{f930}, @samp{f934}, @samp{sparclet}, @samp{tsc701}, @samp{v9}, and
3344 Default instruction scheduling parameters are used for values that select
3345 an architecture and not an implementation. These are @samp{v7}, @samp{v8},
3346 @samp{sparclite}, @samp{sparclet}, @samp{v9}.
3348 Here is a list of each supported architecture and their supported
3354 sparclite: f930, f934
3359 @item -mtune=@var{cpu_type}
3360 Set the instruction scheduling parameters for machine type
3361 @var{cpu_type}, but do not set the instruction set or register set that the
3362 option @samp{-mcpu=}@var{cpu_type} would.
3364 The same values for @samp{-mcpu=}@var{cpu_type} are used for
3365 @samp{-mtune=}@*@var{cpu_type}, though the only useful values are those that
3366 select a particular cpu implementation: @samp{cypress}, @samp{supersparc},
3367 @samp{f930}, @samp{f934}, @samp{tsc701}, @samp{ultrasparc}.
3369 @item -malign-loops=@var{num}
3370 Align loops to a 2 raised to a @var{num} byte boundary. If
3371 @samp{-malign-loops} is not specified, the default is 2.
3373 @item -malign-jumps=@var{num}
3374 Align instructions that are only jumped to to a 2 raised to a @var{num}
3375 byte boundary. If @samp{-malign-jumps} is not specified, the default is 2.
3377 @item -malign-functions=@var{num}
3378 Align the start of functions to a 2 raised to @var{num} byte boundary.
3379 If @samp{-malign-functions} is not specified, the default is 2 if compiling
3380 for 32 bit sparc, and 5 if compiling for 64 bit sparc.
3384 These @samp{-m} switches are supported in addition to the above
3385 on the SPARCLET processor.
3388 @item -mlittle-endian
3389 Generate code for a processor running in little-endian mode.
3392 Treat register @code{%g0} as a normal register.
3393 GCC will continue to clobber it as necessary but will not assume
3394 it always reads as 0.
3396 @item -mbroken-saverestore
3397 Generate code that does not use non-trivial forms of the @code{save} and
3398 @code{restore} instructions. Early versions of the SPARCLET processor do
3399 not correctly handle @code{save} and @code{restore} instructions used with
3400 arguments. They correctly handle them used without arguments. A @code{save}
3401 instruction used without arguments increments the current window pointer
3402 but does not allocate a new stack frame. It is assumed that the window
3403 overflow trap handler will properly handle this case as will interrupt
3407 These @samp{-m} switches are supported in addition to the above
3408 on SPARC V9 processors in 64 bit environments.
3411 @item -mlittle-endian
3412 Generate code for a processor running in little-endian mode.
3416 Generate code for a 32 bit or 64 bit environment.
3417 The 32 bit environment sets int, long and pointer to 32 bits.
3418 The 64 bit environment sets int to 32 bits and long and pointer
3421 @item -mcmodel=medlow
3422 Generate code for the Medium/Low code model: the program must be linked
3423 in the low 32 bits of the address space. Pointers are 64 bits.
3424 Programs can be statically or dynamically linked.
3426 @item -mcmodel=medmid
3427 Generate code for the Medium/Middle code model: the program must be linked
3428 in the low 44 bits of the address space, the text segment must be less than
3429 2G bytes, and data segment must be within 2G of the text segment.
3430 Pointers are 64 bits.
3432 @item -mcmodel=medany
3433 Generate code for the Medium/Anywhere code model: the program may be linked
3434 anywhere in the address space, the text segment must be less than
3435 2G bytes, and data segment must be within 2G of the text segment.
3436 Pointers are 64 bits.
3438 @item -mcmodel=embmedany
3439 Generate code for the Medium/Anywhere code model for embedded systems:
3440 assume a 32 bit text and a 32 bit data segment, both starting anywhere
3441 (determined at link time). Register %g4 points to the base of the
3442 data segment. Pointers still 64 bits.
3443 Programs are statically linked, PIC is not supported.
3446 @itemx -mno-stack-bias
3447 With @samp{-mstack-bias}, GNU CC assumes that the stack pointer, and
3448 frame pointer if present, are offset by -2047 which must be added back
3449 when making stack frame references.
3450 Otherwise, assume no such offset is present.
3453 @node Convex Options
3454 @subsection Convex Options
3455 @cindex Convex options
3457 These @samp{-m} options are defined for Convex:
3461 Generate output for C1. The code will run on any Convex machine.
3462 The preprocessor symbol @code{__convex__c1__} is defined.
3465 Generate output for C2. Uses instructions not available on C1.
3466 Scheduling and other optimizations are chosen for max performance on C2.
3467 The preprocessor symbol @code{__convex_c2__} is defined.
3470 Generate output for C32xx. Uses instructions not available on C1.
3471 Scheduling and other optimizations are chosen for max performance on C32.
3472 The preprocessor symbol @code{__convex_c32__} is defined.
3475 Generate output for C34xx. Uses instructions not available on C1.
3476 Scheduling and other optimizations are chosen for max performance on C34.
3477 The preprocessor symbol @code{__convex_c34__} is defined.
3480 Generate output for C38xx. Uses instructions not available on C1.
3481 Scheduling and other optimizations are chosen for max performance on C38.
3482 The preprocessor symbol @code{__convex_c38__} is defined.
3485 Generate code which puts an argument count in the word preceding each
3486 argument list. This is compatible with regular CC, and a few programs
3487 may need the argument count word. GDB and other source-level debuggers
3488 do not need it; this info is in the symbol table.
3491 Omit the argument count word. This is the default.
3493 @item -mvolatile-cache
3494 Allow volatile references to be cached. This is the default.
3496 @item -mvolatile-nocache
3497 Volatile references bypass the data cache, going all the way to memory.
3498 This is only needed for multi-processor code that does not use standard
3499 synchronization instructions. Making non-volatile references to volatile
3500 locations will not necessarily work.
3503 Type long is 32 bits, the same as type int. This is the default.
3506 Type long is 64 bits, the same as type long long. This option is useless,
3507 because no library support exists for it.
3510 @node AMD29K Options
3511 @subsection AMD29K Options
3512 @cindex AMD29K options
3514 These @samp{-m} options are defined for the AMD Am29000:
3519 @cindex DW bit (29k)
3520 Generate code that assumes the @code{DW} bit is set, i.e., that byte and
3521 halfword operations are directly supported by the hardware. This is the
3526 Generate code that assumes the @code{DW} bit is not set.
3530 @cindex byte writes (29k)
3531 Generate code that assumes the system supports byte and halfword write
3532 operations. This is the default.
3536 Generate code that assumes the systems does not support byte and
3537 halfword write operations. @samp{-mnbw} implies @samp{-mndw}.
3541 @cindex memory model (29k)
3542 Use a small memory model that assumes that all function addresses are
3543 either within a single 256 KB segment or at an absolute address of less
3544 than 256k. This allows the @code{call} instruction to be used instead
3545 of a @code{const}, @code{consth}, @code{calli} sequence.
3549 Use the normal memory model: Generate @code{call} instructions only when
3550 calling functions in the same file and @code{calli} instructions
3551 otherwise. This works if each file occupies less than 256 KB but allows
3552 the entire executable to be larger than 256 KB. This is the default.
3555 Always use @code{calli} instructions. Specify this option if you expect
3556 a single file to compile into more than 256 KB of code.
3560 @cindex processor selection (29k)
3561 Generate code for the Am29050.
3565 Generate code for the Am29000. This is the default.
3567 @item -mkernel-registers
3568 @kindex -mkernel-registers
3569 @cindex kernel and user registers (29k)
3570 Generate references to registers @code{gr64-gr95} instead of to
3571 registers @code{gr96-gr127}. This option can be used when compiling
3572 kernel code that wants a set of global registers disjoint from that used
3575 Note that when this option is used, register names in @samp{-f} flags
3576 must use the normal, user-mode, names.
3578 @item -muser-registers
3579 @kindex -muser-registers
3580 Use the normal set of global registers, @code{gr96-gr127}. This is the
3584 @itemx -mno-stack-check
3585 @kindex -mstack-check
3586 @cindex stack checks (29k)
3587 Insert (or do not insert) a call to @code{__msp_check} after each stack
3588 adjustment. This is often used for kernel code.
3591 @itemx -mno-storem-bug
3592 @kindex -mstorem-bug
3593 @cindex storem bug (29k)
3594 @samp{-mstorem-bug} handles 29k processors which cannot handle the
3595 separation of a mtsrim insn and a storem instruction (most 29000 chips
3596 to date, but not the 29050).
3598 @item -mno-reuse-arg-regs
3599 @itemx -mreuse-arg-regs
3600 @kindex -mreuse-arg-regs
3601 @samp{-mno-reuse-arg-regs} tells the compiler to only use incoming argument
3602 registers for copying out arguments. This helps detect calling a function
3603 with fewer arguments than it was declared with.
3605 @item -mno-impure-text
3606 @itemx -mimpure-text
3607 @kindex -mimpure-text
3608 @samp{-mimpure-text}, used in addition to @samp{-shared}, tells the compiler to
3609 not pass @samp{-assert pure-text} to the linker when linking a shared object.
3612 @kindex -msoft-float
3613 Generate output containing library calls for floating point.
3614 @strong{Warning:} the requisite libraries are not part of GNU CC.
3615 Normally the facilities of the machine's usual C compiler are used, but
3616 this can't be done directly in cross-compilation. You must make your
3617 own arrangements to provide suitable library functions for
3622 @subsection ARM Options
3625 These @samp{-m} options are defined for Advanced RISC Machines (ARM)
3630 @kindex -mapcs-frame
3631 Generate a stack frame that is compliant with the ARM Procedure Call
3632 Standard for all functions, even if this is not strictly necessary for
3633 correct execution of the code. Specifying @samp{-fomit-frame-pointer}
3634 with this option will cause the stack frames not to be generated for
3635 leaf functions. The default is @samp{-mno-apcs-frame}.
3639 This is a synonym for @samp{-mapcs-frame}.
3643 Generate code for a processor running with a 26-bit program counter,
3644 and conforming to the function calling standards for the APCS 26-bit
3645 option. This option replaces the @samp{-m2} and @samp{-m3} options
3646 of previous releases of the compiler.
3650 Generate code for a processor running with a 32-bit program counter,
3651 and conforming to the function calling standards for the APCS 32-bit
3652 option. This option replaces the @samp{-m6} option of previous releases
3655 @item -mapcs-stack-check
3656 @kindex -mapcs-stack-check
3657 @kindex -mno-apcs-stack-check
3658 Generate code to check the amount of stack space available upon entry to
3659 every function (that actually uses some stack space). If there is
3660 insufficient space available then either the function
3661 @samp{__rt_stkovf_split_small} or @samp{__rt_stkovf_split_big} will be
3662 called, depending upon the amount of stack space required. The run time
3663 system is required to provide these functions. The default is
3664 @samp{-mno-apcs-stack-check}, since this produces smaller code.
3667 @kindex -mapcs-float
3668 @kindex -mno-apcs-float
3669 Pass floating point arguments using the float point registers. This is
3670 one of the variants of the APCS. This option is reccommended if the
3671 target hardware has a floating point unit or if a lot of floating point
3672 arithmetic is going to be performed by the code. The default is
3673 @samp{-mno-apcs-float}, since integer only code is slightly increased in
3674 size if @samp{-mapcs-float} is used.
3676 @item -mapcs-reentrant
3677 @kindex -mapcs-reentrant
3678 @kindex -mno-apcs-reentrant
3679 Generate reentrant, position independent code. This is the equivalent
3680 to specifying the @samp{-fpic} option. The default is
3681 @samp{-mno-apcs-reentrant}.
3683 @item -mthumb-interwork
3684 @kindex -mthumb-interwork
3685 @kindex -mno-thumb-interwork
3686 Generate code which supports calling between the ARM and THUMB
3687 instruction sets. Without this option the two instruction sets cannot
3688 be reliably used inside one program. The default is
3689 @samp{-mno-thumb-interwork}, since slightly larger code is generated
3690 when @samp{-mthumb-interwork} is specified.
3692 @item -mno-sched-prolog
3693 @kindex -mno-sched-prolog
3694 @kindex -msched-prolog
3695 Prevent the reordering of instructions in the function prolog, or the
3696 merging of those instruction with the instructions in the function's
3697 body. This means that all functions will start with a recognisable set
3698 of instructions (or in fact one of a chioce from a small set of
3699 different function prologues), and this information can be used to
3700 locate the start if functions inside an executable piece of code. The
3701 default is @samp{-msched-prolog}.
3704 Generate output containing floating point instructions. This is the
3708 Generate output containing library calls for floating point.
3709 @strong{Warning:} the requisite libraries are not available for all ARM
3710 targets. Normally the facilities of the machine's usual C compiler are
3711 used, but this cannot be done directly in cross-compilation. You must make
3712 your own arrangements to provide suitable library functions for
3715 @samp{-msoft-float} changes the calling convention in the output file;
3716 therefore, it is only useful if you compile @emph{all} of a program with
3717 this option. In particular, you need to compile @file{libgcc.a}, the
3718 library that comes with GNU CC, with @samp{-msoft-float} in order for
3721 @item -mlittle-endian
3722 Generate code for a processor running in little-endian mode. This is
3723 the default for all standard configurations.
3726 Generate code for a processor running in big-endian mode; the default is
3727 to compile code for a little-endian processor.
3729 @item -mwords-little-endian
3730 This option only applies when generating code for big-endian processors.
3731 Generate code for a little-endian word order but a big-endian byte
3732 order. That is, a byte order of the form @samp{32107654}. Note: this
3733 option should only be used if you require compatibility with code for
3734 big-endian ARM processors generated by versions of the compiler prior to
3737 @item -mshort-load-bytes
3738 @kindex -mshort-load-bytes
3739 Do not try to load half-words (eg @samp{short}s) by loading a word from
3740 an unaligned address. For some targets the MMU is configured to trap
3741 unaligned loads; use this option to generate code that is safe in these
3744 @item -mno-short-load-bytes
3745 @kindex -mno-short-load-bytes
3746 Use unaligned word loads to load half-words (eg @samp{short}s). This
3747 option produces more efficient code, but the MMU is sometimes configured
3748 to trap these instructions.
3750 @item -mshort-load-words
3751 @kindex -mshort-load-words
3752 This is a synonym for the @samp{-mno-short-load-bytes}.
3754 @item -mno-short-load-words
3755 @kindex -mno-short-load-words
3756 This is a synonym for the @samp{-mshort-load-bytes}.
3760 This option only applies to RISC iX. Emulate the native BSD-mode
3761 compiler. This is the default if @samp{-ansi} is not specified.
3765 This option only applies to RISC iX. Emulate the native X/Open-mode
3768 @item -mno-symrename
3769 @kindex -mno-symrename
3770 This option only applies to RISC iX. Do not run the assembler
3771 post-processor, @samp{symrename}, after code has been assembled.
3772 Normally it is necessary to modify some of the standard symbols in
3773 preparation for linking with the RISC iX C library; this option
3774 suppresses this pass. The post-processor is never run when the
3775 compiler is built for cross-compilation.
3779 This specifies the name of the target ARM processor. GCC uses this name
3780 to determine what kind of instructions it can use when generating
3781 assembly code. Permissable names are: arm2, arm250, arm3, arm6, arm60,
3782 arm600, arm610, arm620, arm7, arm7m, arm7d, arm7dm, arm7di, arm7dmi,
3783 arm70, arm700, arm700i, arm710, arm710c, arm7100, arm7500, arm7500fe,
3784 arm7tdmi, arm8, strongarm, strongarm110
3788 This specifies the name of the target ARM architecture. GCC uses this
3789 name to determine what kind of instructions it can use when generating
3790 assembly code. This option can be used in conjunction with or instead
3791 of the @samp{-mcpu=} option. Permissable names are: armv2, armv2a,
3792 armv3, armv3m, armv4, armv4t
3794 @item -mfpe=<number>
3796 This specifes the version of the floating point emulation available on
3797 the target. Permissable values are 2 and 3.
3799 @item -mstructure-size-boundary=<n>
3800 @kindex -mstructure-size-boundary
3801 The size of all structures and unions will be rounded up to a multiple
3802 of the number of bits set by this option. Permissable values are 8 and
3803 32. The default value varies for different toolchains. For the COFF
3804 targeted toolchain the default value is 8. Specifying the larger number
3805 can produced faster, more efficient code, but can also increase the size
3806 of the program. The two values are potentially incompatible. Code
3807 compiled with one value cannot necessarily expect to work with code or
3808 libraries compiled with the other value, if they exchange information
3809 using structures or unions. Programmers are encouraged to use the 32
3810 value as future versions of the toolchain may default to this value.
3815 @subsection Thumb Options
3816 @cindex Thumb Options
3820 @item -mthumb-interwork
3821 @kindex -mthumb-interwork
3822 @kindex -mno-thumb-interwork
3823 Generate code which supports calling between the THUMB and ARM
3824 instruction sets. Without this option the two instruction sets cannot
3825 be reliably used inside one program. The default is
3826 @samp{-mno-thumb-interwork}, since slightly smaller code is generated
3830 @kindex -mtpcs-frame
3831 @kindex -mno-tpcs-frame
3832 Generate a stack frame that is compliant with the Thumb Procedure Call
3833 Standard for all non-leaf functions. (A leaf function is one that does
3834 not call any other functions). The default is @samp{-mno-apcs-frame}.
3836 @item -mtpcs-leaf-frame
3837 @kindex -mtpcs-leaf-frame
3838 @kindex -mno-tpcs-leaf-frame
3839 Generate a stack frame that is compliant with the Thumb Procedure Call
3840 Standard for all leaf functions. (A leaf function is one that does
3841 not call any other functions). The default is @samp{-mno-apcs-leaf-frame}.
3843 @item -mlittle-endian
3844 @kindex -mlittle-endian
3845 Generate code for a processor running in little-endian mode. This is
3846 the default for all standard configurations.
3849 @kindex -mbig-endian
3850 Generate code for a processor running in big-endian mode.
3852 @item -mstructure-size-boundary=<n>
3853 @kindex -mstructure-size-boundary
3854 The size of all structures and unions will be rounded up to a multiple
3855 of the number of bits set by this option. Permissable values are 8 and
3856 32. The default value varies for different toolchains. For the COFF
3857 targeted toolchain the default value is 8. Specifying the larger number
3858 can produced faster, more efficient code, but can also increase the size
3859 of the program. The two values are potentially incompatible. Code
3860 compiled with one value cannot necessarily expect to work with code or
3861 libraries compiled with the other value, if they exchange information
3862 using structures or unions. Programmers are encouraged to use the 32
3863 value as future versions of the toolchain may default to this value.
3867 @node MN10200 Options
3868 @subsection MN10200 Options
3869 @cindex MN10200 options
3870 These @samp{-m} options are defined for Matsushita MN10200 architectures:
3874 Indicate to the linker that it should perform a relaxation optimization pass
3875 to shorten branches, calls and absolute memory addresses. This option only
3876 has an effect when used on the command line for the final link step.
3878 This option makes symbolic debugging impossible.
3881 @node MN10300 Options
3882 @subsection MN10300 Options
3883 @cindex MN10300 options
3884 These @samp{-m} options are defined for Matsushita MN10300 architectures:
3888 Generate code to avoid bugs in the multiply instructions for the MN10300
3889 processors. This is the default.
3892 Do not generate code to avoid bugs in the multiply instructions for the
3896 Indicate to the linker that it should perform a relaxation optimization pass
3897 to shorten branches, calls and absolute memory addresses. This option only
3898 has an effect when used on the command line for the final link step.
3900 This option makes symbolic debugging impossible.
3904 @node M32R/D Options
3905 @subsection M32R/D Options
3906 @cindex M32R/D options
3908 These @samp{-m} options are defined for Mitsubishi M32R/D architectures:
3911 @item -mcode-model=small
3912 Assume all objects live in the lower 16MB of memory (so that their addresses
3913 can be loaded with the @code{ld24} instruction), and assume all subroutines
3914 are reachable with the @code{bl} instruction.
3915 This is the default.
3917 The addressability of a particular object can be set with the
3918 @code{model} attribute.
3920 @item -mcode-model=medium
3921 Assume objects may be anywhere in the 32 bit address space (the compiler
3922 will generate @code{seth/add3} instructions to load their addresses), and
3923 assume all subroutines are reachable with the @code{bl} instruction.
3925 @item -mcode-model=large
3926 Assume objects may be anywhere in the 32 bit address space (the compiler
3927 will generate @code{seth/add3} instructions to load their addresses), and
3928 assume subroutines may not be reachable with the @code{bl} instruction
3929 (the compiler will generate the much slower @code{seth/add3/jl}
3930 instruction sequence).
3933 Disable use of the small data area. Variables will be put into
3934 one of @samp{.data}, @samp{bss}, or @samp{.rodata} (unless the
3935 @code{section} attribute has been specified).
3936 This is the default.
3938 The small data area consists of sections @samp{.sdata} and @samp{.sbss}.
3939 Objects may be explicitly put in the small data area with the
3940 @code{section} attribute using one of these sections.
3943 Put small global and static data in the small data area, but do not
3944 generate special code to reference them.
3947 Put small global and static data in the small data area, and generate
3948 special instructions to reference them.
3951 @cindex smaller data references
3952 Put global and static objects less than or equal to @var{num} bytes
3953 into the small data or bss sections instead of the normal data or bss
3954 sections. The default value of @var{num} is 8.
3955 The @samp{-msdata} option must be set to one of @samp{sdata} or @samp{use}
3956 for this option to have any effect.
3958 All modules should be compiled with the same @samp{-G @var{num}} value.
3959 Compiling with different values of @var{num} may or may not work; if it
3960 doesn't the linker will give an error message - incorrect code will not be
3966 @subsection M88K Options
3967 @cindex M88k options
3969 These @samp{-m} options are defined for Motorola 88k architectures:
3974 Generate code that works well on both the m88100 and the
3979 Generate code that works best for the m88100, but that also
3984 Generate code that works best for the m88110, and may not run
3989 Obsolete option to be removed from the next revision.
3992 @item -midentify-revision
3993 @kindex -midentify-revision
3995 @cindex identifying source, compiler (88k)
3996 Include an @code{ident} directive in the assembler output recording the
3997 source file name, compiler name and version, timestamp, and compilation
4000 @item -mno-underscores
4001 @kindex -mno-underscores
4002 @cindex underscores, avoiding (88k)
4003 In assembler output, emit symbol names without adding an underscore
4004 character at the beginning of each name. The default is to use an
4005 underscore as prefix on each name.
4007 @item -mocs-debug-info
4008 @itemx -mno-ocs-debug-info
4009 @kindex -mocs-debug-info
4010 @kindex -mno-ocs-debug-info
4012 @cindex debugging, 88k OCS
4013 Include (or omit) additional debugging information (about registers used
4014 in each stack frame) as specified in the 88open Object Compatibility
4015 Standard, ``OCS''. This extra information allows debugging of code that
4016 has had the frame pointer eliminated. The default for DG/UX, SVr4, and
4017 Delta 88 SVr3.2 is to include this information; other 88k configurations
4018 omit this information by default.
4020 @item -mocs-frame-position
4021 @kindex -mocs-frame-position
4022 @cindex register positions in frame (88k)
4023 When emitting COFF debugging information for automatic variables and
4024 parameters stored on the stack, use the offset from the canonical frame
4025 address, which is the stack pointer (register 31) on entry to the
4026 function. The DG/UX, SVr4, Delta88 SVr3.2, and BCS configurations use
4027 @samp{-mocs-frame-position}; other 88k configurations have the default
4028 @samp{-mno-ocs-frame-position}.
4030 @item -mno-ocs-frame-position
4031 @kindex -mno-ocs-frame-position
4032 @cindex register positions in frame (88k)
4033 When emitting COFF debugging information for automatic variables and
4034 parameters stored on the stack, use the offset from the frame pointer
4035 register (register 30). When this option is in effect, the frame
4036 pointer is not eliminated when debugging information is selected by the
4039 @item -moptimize-arg-area
4040 @itemx -mno-optimize-arg-area
4041 @kindex -moptimize-arg-area
4042 @kindex -mno-optimize-arg-area
4043 @cindex arguments in frame (88k)
4044 Control how function arguments are stored in stack frames.
4045 @samp{-moptimize-arg-area} saves space by optimizing them, but this
4046 conflicts with the 88open specifications. The opposite alternative,
4047 @samp{-mno-optimize-arg-area}, agrees with 88open standards. By default
4048 GNU CC does not optimize the argument area.
4050 @item -mshort-data-@var{num}
4051 @kindex -mshort-data-@var{num}
4052 @cindex smaller data references (88k)
4053 @cindex r0-relative references (88k)
4054 Generate smaller data references by making them relative to @code{r0},
4055 which allows loading a value using a single instruction (rather than the
4056 usual two). You control which data references are affected by
4057 specifying @var{num} with this option. For example, if you specify
4058 @samp{-mshort-data-512}, then the data references affected are those
4059 involving displacements of less than 512 bytes.
4060 @samp{-mshort-data-@var{num}} is not effective for @var{num} greater
4063 @item -mserialize-volatile
4064 @kindex -mserialize-volatile
4065 @itemx -mno-serialize-volatile
4066 @kindex -mno-serialize-volatile
4067 @cindex sequential consistency on 88k
4068 Do, or don't, generate code to guarantee sequential consistency
4069 of volatile memory references. By default, consistency is
4072 The order of memory references made by the MC88110 processor does
4073 not always match the order of the instructions requesting those
4074 references. In particular, a load instruction may execute before
4075 a preceding store instruction. Such reordering violates
4076 sequential consistency of volatile memory references, when there
4077 are multiple processors. When consistency must be guaranteed,
4078 GNU C generates special instructions, as needed, to force
4079 execution in the proper order.
4081 The MC88100 processor does not reorder memory references and so
4082 always provides sequential consistency. However, by default, GNU
4083 C generates the special instructions to guarantee consistency
4084 even when you use @samp{-m88100}, so that the code may be run on an
4085 MC88110 processor. If you intend to run your code only on the
4086 MC88100 processor, you may use @samp{-mno-serialize-volatile}.
4088 The extra code generated to guarantee consistency may affect the
4089 performance of your application. If you know that you can safely
4090 forgo this guarantee, you may use @samp{-mno-serialize-volatile}.
4096 @cindex assembler syntax, 88k
4098 Turn on (@samp{-msvr4}) or off (@samp{-msvr3}) compiler extensions
4099 related to System V release 4 (SVr4). This controls the following:
4103 Which variant of the assembler syntax to emit.
4105 @samp{-msvr4} makes the C preprocessor recognize @samp{#pragma weak}
4106 that is used on System V release 4.
4108 @samp{-msvr4} makes GNU CC issue additional declaration directives used in
4112 @samp{-msvr4} is the default for the m88k-motorola-sysv4 and
4113 m88k-dg-dgux m88k configurations. @samp{-msvr3} is the default for all
4114 other m88k configurations.
4116 @item -mversion-03.00
4117 @kindex -mversion-03.00
4118 This option is obsolete, and is ignored.
4119 @c ??? which asm syntax better for GAS? option there too?
4121 @item -mno-check-zero-division
4122 @itemx -mcheck-zero-division
4123 @kindex -mno-check-zero-division
4124 @kindex -mcheck-zero-division
4125 @cindex zero division on 88k
4126 Do, or don't, generate code to guarantee that integer division by
4127 zero will be detected. By default, detection is guaranteed.
4129 Some models of the MC88100 processor fail to trap upon integer
4130 division by zero under certain conditions. By default, when
4131 compiling code that might be run on such a processor, GNU C
4132 generates code that explicitly checks for zero-valued divisors
4133 and traps with exception number 503 when one is detected. Use of
4134 mno-check-zero-division suppresses such checking for code
4135 generated to run on an MC88100 processor.
4137 GNU C assumes that the MC88110 processor correctly detects all
4138 instances of integer division by zero. When @samp{-m88110} is
4139 specified, both @samp{-mcheck-zero-division} and
4140 @samp{-mno-check-zero-division} are ignored, and no explicit checks for
4141 zero-valued divisors are generated.
4143 @item -muse-div-instruction
4144 @kindex -muse-div-instruction
4145 @cindex divide instruction, 88k
4146 Use the div instruction for signed integer division on the
4147 MC88100 processor. By default, the div instruction is not used.
4149 On the MC88100 processor the signed integer division instruction
4150 div) traps to the operating system on a negative operand. The
4151 operating system transparently completes the operation, but at a
4152 large cost in execution time. By default, when compiling code
4153 that might be run on an MC88100 processor, GNU C emulates signed
4154 integer division using the unsigned integer division instruction
4155 divu), thereby avoiding the large penalty of a trap to the
4156 operating system. Such emulation has its own, smaller, execution
4157 cost in both time and space. To the extent that your code's
4158 important signed integer division operations are performed on two
4159 nonnegative operands, it may be desirable to use the div
4160 instruction directly.
4162 On the MC88110 processor the div instruction (also known as the
4163 divs instruction) processes negative operands without trapping to
4164 the operating system. When @samp{-m88110} is specified,
4165 @samp{-muse-div-instruction} is ignored, and the div instruction is used
4166 for signed integer division.
4168 Note that the result of dividing INT_MIN by -1 is undefined. In
4169 particular, the behavior of such a division with and without
4170 @samp{-muse-div-instruction} may differ.
4172 @item -mtrap-large-shift
4173 @itemx -mhandle-large-shift
4174 @kindex -mtrap-large-shift
4175 @kindex -mhandle-large-shift
4176 @cindex bit shift overflow (88k)
4177 @cindex large bit shifts (88k)
4178 Include code to detect bit-shifts of more than 31 bits; respectively,
4179 trap such shifts or emit code to handle them properly. By default GNU CC
4180 makes no special provision for large bit shifts.
4182 @item -mwarn-passed-structs
4183 @kindex -mwarn-passed-structs
4184 @cindex structure passing (88k)
4185 Warn when a function passes a struct as an argument or result.
4186 Structure-passing conventions have changed during the evolution of the C
4187 language, and are often the source of portability problems. By default,
4188 GNU CC issues no such warning.
4191 @node RS/6000 and PowerPC Options
4192 @subsection IBM RS/6000 and PowerPC Options
4193 @cindex RS/6000 and PowerPC Options
4194 @cindex IBM RS/6000 and PowerPC Options
4196 These @samp{-m} options are defined for the IBM RS/6000 and PowerPC:
4204 @itemx -mpowerpc-gpopt
4205 @itemx -mno-powerpc-gpopt
4206 @itemx -mpowerpc-gfxopt
4207 @itemx -mno-powerpc-gfxopt
4209 @itemx -mno-powerpc64
4213 @kindex -mpowerpc-gpopt
4214 @kindex -mpowerpc-gfxopt
4216 GNU CC supports two related instruction set architectures for the
4217 RS/6000 and PowerPC. The @dfn{POWER} instruction set are those
4218 instructions supported by the @samp{rios} chip set used in the original
4219 RS/6000 systems and the @dfn{PowerPC} instruction set is the
4220 architecture of the Motorola MPC5xx, MPC6xx, MPC8xx microprocessors, and
4221 the IBM 4xx microprocessors.
4223 Neither architecture is a subset of the other. However there is a
4224 large common subset of instructions supported by both. An MQ
4225 register is included in processors supporting the POWER architecture.
4227 You use these options to specify which instructions are available on the
4228 processor you are using. The default value of these options is
4229 determined when configuring GNU CC. Specifying the
4230 @samp{-mcpu=@var{cpu_type}} overrides the specification of these
4231 options. We recommend you use the @samp{-mcpu=@var{cpu_type}} option
4232 rather than the options listed above.
4234 The @samp{-mpower} option allows GNU CC to generate instructions that
4235 are found only in the POWER architecture and to use the MQ register.
4236 Specifying @samp{-mpower2} implies @samp{-power} and also allows GNU CC
4237 to generate instructions that are present in the POWER2 architecture but
4238 not the original POWER architecture.
4240 The @samp{-mpowerpc} option allows GNU CC to generate instructions that
4241 are found only in the 32-bit subset of the PowerPC architecture.
4242 Specifying @samp{-mpowerpc-gpopt} implies @samp{-mpowerpc} and also allows
4243 GNU CC to use the optional PowerPC architecture instructions in the
4244 General Purpose group, including floating-point square root. Specifying
4245 @samp{-mpowerpc-gfxopt} implies @samp{-mpowerpc} and also allows GNU CC to
4246 use the optional PowerPC architecture instructions in the Graphics
4247 group, including floating-point select.
4249 The @samp{-mpowerpc64} option allows GNU CC to generate the additional
4250 64-bit instructions that are found in the full PowerPC64 architecture
4251 and to treat GPRs as 64-bit, doubleword quantities. GNU CC defaults to
4252 @samp{-mno-powerpc64}.
4254 If you specify both @samp{-mno-power} and @samp{-mno-powerpc}, GNU CC
4255 will use only the instructions in the common subset of both
4256 architectures plus some special AIX common-mode calls, and will not use
4257 the MQ register. Specifying both @samp{-mpower} and @samp{-mpowerpc}
4258 permits GNU CC to use any instruction from either architecture and to
4259 allow use of the MQ register; specify this for the Motorola MPC601.
4261 @item -mnew-mnemonics
4262 @itemx -mold-mnemonics
4263 @kindex -mnew-mnemonics
4264 @kindex -mold-mnemonics
4265 Select which mnemonics to use in the generated assembler code.
4266 @samp{-mnew-mnemonics} requests output that uses the assembler mnemonics
4267 defined for the PowerPC architecture, while @samp{-mold-mnemonics}
4268 requests the assembler mnemonics defined for the POWER architecture.
4269 Instructions defined in only one architecture have only one mnemonic;
4270 GNU CC uses that mnemonic irrespective of which of these options is
4273 GNU CC defaults to the mnemonics appropriate for the architecture in
4274 use. Specifying @samp{-mcpu=@var{cpu_type}} sometimes overrides the
4275 value of these option. Unless you are building a cross-compiler, you
4276 should normally not specify either @samp{-mnew-mnemonics} or
4277 @samp{-mold-mnemonics}, but should instead accept the default.
4279 @item -mcpu=@var{cpu_type}
4281 Set architecture type, register usage, choice of mnemonics, and
4282 instruction scheduling parameters for machine type @var{cpu_type}.
4283 Supported values for @var{cpu_type} are @samp{rs6000}, @samp{rios1},
4284 @samp{rios2}, @samp{rsc}, @samp{601}, @samp{602}, @samp{603},
4285 @samp{603e}, @samp{604}, @samp{604e}, @samp{620}, @samp{power},
4286 @samp{power2}, @samp{powerpc}, @samp{403}, @samp{505}, @samp{801},
4287 @samp{821}, @samp{823}, and @samp{860} and @samp{common}.
4288 @samp{-mcpu=power}, @samp{-mcpu=power2}, and @samp{-mcpu=powerpc}
4289 specify generic POWER, POWER2 and pure PowerPC (i.e., not MPC601)
4290 architecture machine types, with an appropriate, generic processor model
4291 assumed for scheduling purposes.@refill
4293 @c overfull hbox here --bob 22 jul96
4294 @c original text between ignore ... end ignore
4296 Specifying any of the @samp{-mcpu=rios1}, @samp{-mcpu=rios2},
4297 @samp{-mcpu=rsc}, @samp{-mcpu=power}, or @samp{-mcpu=power2} options
4298 enables the @samp{-mpower} option and disables the @samp{-mpowerpc}
4299 option; @samp{-mcpu=601} enables both the @samp{-mpower} and
4300 @samp{-mpowerpc} options; all of @samp{-mcpu=602}, @samp{-mcpu=603},
4301 @samp{-mcpu=603e}, @samp{-mcpu=604}, @samp{-mcpu=604e},
4302 @samp{-mcpu=620}, @samp{-mcpu=403}, @samp{-mcpu=505}, @samp{-mcpu=801},
4303 @samp{-mcpu=821}, @samp{-mcpu=823}, @samp{-mcpu=860} and
4304 @samp{-mcpu=powerpc} enable the @samp{-mpowerpc} option and disable the
4305 @samp{-mpower} option; @samp{-mcpu=common} disables both the
4306 @samp{-mpower} and @samp{-mpowerpc} options.@refill
4308 @c changed paragraph
4309 Specifying any of the following options:
4310 @samp{-mcpu=rios1}, @samp{-mcpu=rios2}, @samp{-mcpu=rsc},
4311 @samp{-mcpu=power}, or @samp{-mcpu=power2}
4312 enables the @samp{-mpower} option and disables the @samp{-mpowerpc} option;
4313 @samp{-mcpu=601} enables both the @samp{-mpower} and @samp{-mpowerpc} options.
4314 All of @samp{-mcpu=602}, @samp{-mcpu=603}, @samp{-mcpu=603e},
4315 @samp{-mcpu=604}, @samp{-mcpu=620},
4316 enable the @samp{-mpowerpc} option and disable the @samp{-mpower} option.
4317 Exactly similarly, all of @samp{-mcpu=403},
4318 @samp{-mcpu=505}, @samp{-mcpu=821}, @samp{-mcpu=860} and @samp{-mcpu=powerpc}
4319 enable the @samp{-mpowerpc} option and disable the @samp{-mpower} option.
4320 @samp{-mcpu=common} disables both the
4321 @samp{-mpower} and @samp{-mpowerpc} options.@refill
4322 @c end changes to prevent overfull hboxes
4324 AIX versions 4 or greater selects @samp{-mcpu=common} by default, so
4325 that code will operate on all members of the RS/6000 and PowerPC
4326 families. In that case, GNU CC will use only the instructions in the
4327 common subset of both architectures plus some special AIX common-mode
4328 calls, and will not use the MQ register. GNU CC assumes a generic
4329 processor model for scheduling purposes.
4331 Specifying any of the options @samp{-mcpu=rios1}, @samp{-mcpu=rios2},
4332 @samp{-mcpu=rsc}, @samp{-mcpu=power}, or @samp{-mcpu=power2} also
4333 disables the @samp{new-mnemonics} option. Specifying @samp{-mcpu=601},
4334 @samp{-mcpu=602}, @samp{-mcpu=603}, @samp{-mcpu=603e}, @samp{-mcpu=604},
4335 @samp{620}, @samp{403}, or @samp{-mcpu=powerpc} also enables the
4336 @samp{new-mnemonics} option.@refill
4338 Specifying @samp{-mcpu=403}, @samp{-mcpu=821}, or @samp{-mcpu=860} also
4339 enables the @samp{-msoft-float} option.
4341 @item -mtune=@var{cpu_type}
4342 Set the instruction scheduling parameters for machine type
4343 @var{cpu_type}, but do not set the architecture type, register usage,
4344 choice of mnemonics like @samp{-mcpu=}@var{cpu_type} would. The same
4345 values for @var{cpu_type} are used for @samp{-mtune=}@var{cpu_type} as
4346 for @samp{-mcpu=}@var{cpu_type}. The @samp{-mtune=}@var{cpu_type}
4347 option overrides the @samp{-mcpu=}@var{cpu_type} option in terms of
4348 instruction scheduling parameters.
4351 @itemx -mno-fp-in-toc
4352 @itemx -mno-sum-in-toc
4353 @itemx -mminimal-toc
4354 @kindex -mminimal-toc
4355 Modify generation of the TOC (Table Of Contents), which is created for
4356 every executable file. The @samp{-mfull-toc} option is selected by
4357 default. In that case, GNU CC will allocate at least one TOC entry for
4358 each unique non-automatic variable reference in your program. GNU CC
4359 will also place floating-point constants in the TOC. However, only
4360 16,384 entries are available in the TOC.
4362 If you receive a linker error message that saying you have overflowed
4363 the available TOC space, you can reduce the amount of TOC space used
4364 with the @samp{-mno-fp-in-toc} and @samp{-mno-sum-in-toc} options.
4365 @samp{-mno-fp-in-toc} prevents GNU CC from putting floating-point
4366 constants in the TOC and @samp{-mno-sum-in-toc} forces GNU CC to
4367 generate code to calculate the sum of an address and a constant at
4368 run-time instead of putting that sum into the TOC. You may specify one
4369 or both of these options. Each causes GNU CC to produce very slightly
4370 slower and larger code at the expense of conserving TOC space.
4372 If you still run out of space in the TOC even when you specify both of
4373 these options, specify @samp{-mminimal-toc} instead. This option causes
4374 GNU CC to make only one TOC entry for every file. When you specify this
4375 option, GNU CC will produce code that is slower and larger but which
4376 uses extremely little TOC space. You may wish to use this option
4377 only on files that contain less frequently executed code. @refill
4383 Enable AIX 64-bit ABI and calling convention: 64-bit pointers, 64-bit
4384 @code{long} type, and the infrastructure needed to support them.
4385 Specifying @samp{-maix64} implies @samp{-mpowerpc64} and
4386 @samp{-mpowerpc}, while @samp{-maix32} disables the 64-bit ABI and
4387 implies @samp{-mno-powerpc64}. GNU CC defaults to @samp{-maix32}.
4392 On AIX, pass floating-point arguments to prototyped functions beyond the
4393 register save area (RSA) on the stack in addition to argument FPRs. The
4394 AIX calling convention was extended but not initially documented to
4395 handle an obscure K&R C case of calling a function that takes the
4396 address of its arguments with fewer arguments than declared. AIX XL
4397 compilers access floating point arguments which do not fit in the
4398 RSA from the stack when a subroutine is compiled without
4399 optimization. Because always storing floating-point arguments on the
4400 stack is inefficient and rarely needed, this option is not enabled by
4401 default and only is necessary when calling subroutines compiled by AIX
4402 XL compilers without optimization.
4406 Support @dfn{AIX Threads}. Link an application written to use
4407 @dfn{pthreads} with special libraries and startup code to enable the
4412 Support @dfn{IBM RS/6000 SP} @dfn{Parallel Environment} (PE). Link an
4413 application written to use message passing with special startup code to
4414 enable the application to run. The system must have PE installed in the
4415 standard location (@file{/usr/lpp/ppe.poe/}), or the @file{specs} file
4416 must be overridden with the @samp{-specs=} option to specify the
4417 appropriate directory location. The Parallel Environment does not
4418 support threads, so the @samp{-mpe} option and the @samp{-mthreads}
4419 option are incompatible.
4423 @kindex -msoft-float
4424 Generate code that does not use (uses) the floating-point register set.
4425 Software floating point emulation is provided if you use the
4426 @samp{-msoft-float} option, and pass the option to GNU CC when linking.
4429 @itemx -mno-multiple
4430 Generate code that uses (does not use) the load multiple word
4431 instructions and the store multiple word instructions. These
4432 instructions are generated by default on POWER systems, and not
4433 generated on PowerPC systems. Do not use @samp{-mmultiple} on little
4434 endian PowerPC systems, since those instructions do not work when the
4435 processor is in little endian mode.
4440 Generate code that uses (does not use) the load string instructions and the
4441 store string word instructions to save multiple registers and do small block
4442 moves. These instructions are generated by default on POWER systems, and not
4443 generated on PowerPC systems. Do not use @samp{-mstring} on little endian
4444 PowerPC systems, since those instructions do not work when the processor is in
4450 Generate code that uses (does not use) the load or store instructions
4451 that update the base register to the address of the calculated memory
4452 location. These instructions are generated by default. If you use
4453 @samp{-mno-update}, there is a small window between the time that the
4454 stack pointer is updated and the address of the previous frame is
4455 stored, which means code that walks the stack frame across interrupts or
4456 signals may get corrupted data.
4459 @itemx -mno-fused-madd
4460 @kindex -mfused-madd
4461 Generate code that uses (does not use) the floating point multiply and
4462 accumulate instructions. These instructions are generated by default if
4463 hardware floating is used.
4465 @item -mno-bit-align
4468 On System V.4 and embedded PowerPC systems do not (do) force structures
4469 and unions that contain bit fields to be aligned to the base type of the
4472 For example, by default a structure containing nothing but 8
4473 @code{unsigned} bitfields of length 1 would be aligned to a 4 byte
4474 boundary and have a size of 4 bytes. By using @samp{-mno-bit-align},
4475 the structure would be aligned to a 1 byte boundary and be one byte in
4478 @item -mno-strict-align
4479 @itemx -mstrict-align
4480 @kindex -mstrict-align
4481 On System V.4 and embedded PowerPC systems do not (do) assume that
4482 unaligned memory references will be handled by the system.
4485 @itemx -mno-relocatable
4486 @kindex -mrelocatable
4487 On embedded PowerPC systems generate code that allows (does not allow)
4488 the program to be relocated to a different address at runtime. If you
4489 use @samp{-mrelocatable} on any module, all objects linked together must
4490 be compiled with @samp{-mrelocatable} or @samp{-mrelocatable-lib}.
4492 @item -mrelocatable-lib
4493 @itemx -mno-relocatable-lib
4494 On embedded PowerPC systems generate code that allows (does not allow)
4495 the program to be relocated to a different address at runtime. Modules
4496 compiled with @samp{-mrelocatable-lib} can be linked with either modules
4497 compiled without @samp{-mrelocatable} and @samp{-mrelocatable-lib} or
4498 with modules compiled with the @samp{-mrelocatable} options.
4502 On System V.4 and embedded PowerPC systems do not (do) assume that
4503 register 2 contains a pointer to a global area pointing to the addresses
4504 used in the program.
4507 @itemx -mlittle-endian
4508 On System V.4 and embedded PowerPC systems compile code for the
4509 processor in little endian mode. The @samp{-mlittle-endian} option is
4510 the same as @samp{-mlittle}.
4514 On System V.4 and embedded PowerPC systems compile code for the
4515 processor in big endian mode. The @samp{-mbig-endian} option is
4516 the same as @samp{-mbig}.
4519 On System V.4 and embedded PowerPC systems compile code using calling
4520 conventions that adheres to the March 1995 draft of the System V
4521 Application Binary Interface, PowerPC processor supplement. This is the
4522 default unless you configured GCC using @samp{powerpc-*-eabiaix}.
4524 @item -mcall-sysv-eabi
4525 Specify both @samp{-mcall-sysv} and @samp{-meabi} options.
4527 @item -mcall-sysv-noeabi
4528 Specify both @samp{-mcall-sysv} and @samp{-mno-eabi} options.
4531 On System V.4 and embedded PowerPC systems compile code using calling
4532 conventions that are similar to those used on AIX. This is the
4533 default if you configured GCC using @samp{powerpc-*-eabiaix}.
4535 @item -mcall-solaris
4536 On System V.4 and embedded PowerPC systems compile code for the Solaris
4540 On System V.4 and embedded PowerPC systems compile code for the
4541 Linux-based GNU system.
4544 @itemx -mno-prototype
4545 On System V.4 and embedded PowerPC systems assume that all calls to
4546 variable argument functions are properly prototyped. Otherwise, the
4547 compiler must insert an instruction before every non prototyped call to
4548 set or clear bit 6 of the condition code register (@var{CR}) to
4549 indicate whether floating point values were passed in the floating point
4550 registers in case the function takes a variable arguments. With
4551 @samp{-mprototype}, only calls to prototyped variable argument functions
4552 will set or clear the bit.
4555 On embedded PowerPC systems, assume that the startup module is called
4556 @file{sim-crt0.o} and that the standard C libraries are @file{libsim.a} and
4557 @file{libc.a}. This is the default for @samp{powerpc-*-eabisim}.
4561 On embedded PowerPC systems, assume that the startup module is called
4562 @file{crt0.o} and the standard C libraries are @file{libmvme.a} and
4566 On embedded PowerPC systems, assume that the startup module is called
4567 @file{crt0.o} and the standard C libraries are @file{libads.a} and
4571 On embedded PowerPC systems, assume that the startup module is called
4572 @file{crt0.o} and the standard C libraries are @file{libyk.a} and
4576 On embedded PowerPC systems, set the @var{PPC_EMB} bit in the ELF flags
4577 header to indicate that @samp{eabi} extended relocations are used.
4581 On System V.4 and embedded PowerPC systems do (do not) adhere to the
4582 Embedded Applications Binary Interface (eabi) which is a set of
4583 modifications to the System V.4 specifications. Selecting @code{-meabi}
4584 means that the stack is aligned to an 8 byte boundary, a function
4585 @code{__eabi} is called to from @code{main} to set up the eabi
4586 environment, and the @samp{-msdata} option can use both @code{r2} and
4587 @code{r13} to point to two separate small data areas. Selecting
4588 @code{-mno-eabi} means that the stack is aligned to a 16 byte boundary,
4589 do not call an initialization function from @code{main}, and the
4590 @samp{-msdata} option will only use @code{r13} to point to a single
4591 small data area. The @samp{-meabi} option is on by default if you
4592 configured GCC using one of the @samp{powerpc*-*-eabi*} options.
4595 On System V.4 and embedded PowerPC systems, put small initialized
4596 @code{const} global and static data in the @samp{.sdata2} section, which
4597 is pointed to by register @code{r2}. Put small initialized
4598 non-@code{const} global and static data in the @samp{.sdata} section,
4599 which is pointed to by register @code{r13}. Put small uninitialized
4600 global and static data in the @samp{.sbss} section, which is adjacent to
4601 the @samp{.sdata} section. The @samp{-msdata=eabi} option is
4602 incompatible with the @samp{-mrelocatable} option. The
4603 @samp{-msdata=eabi} option also sets the @samp{-memb} option.
4606 On System V.4 and embedded PowerPC systems, put small global and static
4607 data in the @samp{.sdata} section, which is pointed to by register
4608 @code{r13}. Put small uninitialized global and static data in the
4609 @samp{.sbss} section, which is adjacent to the @samp{.sdata} section.
4610 The @samp{-msdata=sysv} option is incompatible with the
4611 @samp{-mrelocatable} option.
4613 @item -msdata=default
4615 On System V.4 and embedded PowerPC systems, if @samp{-meabi} is used,
4616 compile code the same as @samp{-msdata=eabi}, otherwise compile code the
4617 same as @samp{-msdata=sysv}.
4620 On System V.4 and embedded PowerPC systems, put small global and static
4621 data in the @samp{.sdata} section. Put small uninitialized global and
4622 static data in the @samp{.sbss} section. Do not use register @code{r13}
4623 to address small data however. This is the default behavior unless
4624 other @samp{-msdata} options are used.
4628 On embedded PowerPC systems, put all initialized global and static data
4629 in the @samp{.data} section, and all uninitialized data in the
4630 @samp{.bss} section.
4633 @cindex smaller data references (PowerPC)
4634 @cindex .sdata/.sdata2 references (PowerPC)
4635 On embedded PowerPC systems, put global and static items less than or
4636 equal to @var{num} bytes into the small data or bss sections instead of
4637 the normal data or bss section. By default, @var{num} is 8. The
4638 @samp{-G @var{num}} switch is also passed to the linker.
4639 All modules should be compiled with the same @samp{-G @var{num}} value.
4642 @itemx -mno-regnames
4643 On System V.4 and embedded PowerPC systems do (do not) emit register
4644 names in the assembly language output using symbolic forms.
4647 @subsection IBM RT Options
4649 @cindex IBM RT options
4651 These @samp{-m} options are defined for the IBM RT PC:
4655 Use an in-line code sequence for integer multiplies. This is the
4658 @item -mcall-lib-mul
4659 Call @code{lmul$$} for integer multiples.
4661 @item -mfull-fp-blocks
4662 Generate full-size floating point data blocks, including the minimum
4663 amount of scratch space recommended by IBM. This is the default.
4665 @item -mminimum-fp-blocks
4666 Do not include extra scratch space in floating point data blocks. This
4667 results in smaller code, but slower execution, since scratch space must
4668 be allocated dynamically.
4670 @cindex @file{varargs.h} and RT PC
4671 @cindex @file{stdarg.h} and RT PC
4672 @item -mfp-arg-in-fpregs
4673 Use a calling sequence incompatible with the IBM calling convention in
4674 which floating point arguments are passed in floating point registers.
4675 Note that @code{varargs.h} and @code{stdargs.h} will not work with
4676 floating point operands if this option is specified.
4678 @item -mfp-arg-in-gregs
4679 Use the normal calling convention for floating point arguments. This is
4682 @item -mhc-struct-return
4683 Return structures of more than one word in memory, rather than in a
4684 register. This provides compatibility with the MetaWare HighC (hc)
4685 compiler. Use the option @samp{-fpcc-struct-return} for compatibility
4686 with the Portable C Compiler (pcc).
4688 @item -mnohc-struct-return
4689 Return some structures of more than one word in registers, when
4690 convenient. This is the default. For compatibility with the
4691 IBM-supplied compilers, use the option @samp{-fpcc-struct-return} or the
4692 option @samp{-mhc-struct-return}.
4696 @subsection MIPS Options
4697 @cindex MIPS options
4699 These @samp{-m} options are defined for the MIPS family of computers:
4702 @item -mcpu=@var{cpu type}
4703 Assume the defaults for the machine type @var{cpu type} when scheduling
4704 instructions. The choices for @var{cpu type} are @samp{r2000}, @samp{r3000},
4705 @samp{r4000}, @samp{r4400}, @samp{r4600}, and @samp{r6000}. While picking a
4706 specific @var{cpu type} will schedule things appropriately for that
4707 particular chip, the compiler will not generate any code that does not
4708 meet level 1 of the MIPS ISA (instruction set architecture) without
4709 the @samp{-mips2} or @samp{-mips3} switches being used.
4712 Issue instructions from level 1 of the MIPS ISA. This is the default.
4713 @samp{r3000} is the default @var{cpu type} at this ISA level.
4716 Issue instructions from level 2 of the MIPS ISA (branch likely, square
4717 root instructions). @samp{r6000} is the default @var{cpu type} at this
4721 Issue instructions from level 3 of the MIPS ISA (64 bit instructions).
4722 @samp{r4000} is the default @var{cpu type} at this ISA level.
4723 This option does not change the sizes of any of the C data types.
4726 Issue instructions from level 4 of the MIPS ISA. @samp{r8000} is the
4727 default @var{cpu type} at this ISA level.
4730 Assume that 32 32-bit floating point registers are available. This is
4734 Assume that 32 64-bit floating point registers are available. This is
4735 the default when the @samp{-mips3} option is used.
4738 Assume that 32 32-bit general purpose registers are available. This is
4742 Assume that 32 64-bit general purpose registers are available. This is
4743 the default when the @samp{-mips3} option is used.
4746 Types long, int, and pointer are 64 bits. This works only if @samp{-mips3}
4750 Types long and pointer are 64 bits, and type int is 32 bits.
4751 This works only if @samp{-mips3} is also specified.
4757 Generate code for the indicated ABI.
4760 Generate code for the MIPS assembler, and invoke @file{mips-tfile} to
4761 add normal debug information. This is the default for all
4762 platforms except for the OSF/1 reference platform, using the OSF/rose
4763 object format. If the either of the @samp{-gstabs} or @samp{-gstabs+}
4764 switches are used, the @file{mips-tfile} program will encapsulate the
4765 stabs within MIPS ECOFF.
4768 Generate code for the GNU assembler. This is the default on the OSF/1
4769 reference platform, using the OSF/rose object format. Also, this is
4770 the default if the configure option @samp{--with-gnu-as} is used.
4772 @item -msplit-addresses
4773 @itemx -mno-split-addresses
4774 Generate code to load the high and low parts of address constants separately.
4775 This allows @code{gcc} to optimize away redundant loads of the high order
4776 bits of addresses. This optimization requires GNU as and GNU ld.
4777 This optimization is enabled by default for some embedded targets where
4778 GNU as and GNU ld are standard.
4782 The @samp{-mrnames} switch says to output code using the MIPS software
4783 names for the registers, instead of the hardware names (ie, @var{a0}
4784 instead of @var{$4}). The only known assembler that supports this option
4785 is the Algorithmics assembler.
4789 The @samp{-mgpopt} switch says to write all of the data declarations
4790 before the instructions in the text section, this allows the MIPS
4791 assembler to generate one word memory references instead of using two
4792 words for short global or static data items. This is on by default if
4793 optimization is selected.
4797 For each non-inline function processed, the @samp{-mstats} switch
4798 causes the compiler to emit one line to the standard error file to
4799 print statistics about the program (number of registers saved, stack
4804 The @samp{-mmemcpy} switch makes all block moves call the appropriate
4805 string function (@samp{memcpy} or @samp{bcopy}) instead of possibly
4806 generating inline code.
4809 @itemx -mno-mips-tfile
4810 The @samp{-mno-mips-tfile} switch causes the compiler not
4811 postprocess the object file with the @file{mips-tfile} program,
4812 after the MIPS assembler has generated it to add debug support. If
4813 @file{mips-tfile} is not run, then no local variables will be
4814 available to the debugger. In addition, @file{stage2} and
4815 @file{stage3} objects will have the temporary file names passed to the
4816 assembler embedded in the object file, which means the objects will
4817 not compare the same. The @samp{-mno-mips-tfile} switch should only
4818 be used when there are bugs in the @file{mips-tfile} program that
4819 prevents compilation.
4822 Generate output containing library calls for floating point.
4823 @strong{Warning:} the requisite libraries are not part of GNU CC.
4824 Normally the facilities of the machine's usual C compiler are used, but
4825 this can't be done directly in cross-compilation. You must make your
4826 own arrangements to provide suitable library functions for
4830 Generate output containing floating point instructions. This is the
4831 default if you use the unmodified sources.
4834 @itemx -mno-abicalls
4835 Emit (or do not emit) the pseudo operations @samp{.abicalls},
4836 @samp{.cpload}, and @samp{.cprestore} that some System V.4 ports use for
4837 position independent code.
4840 @itemx -mno-long-calls
4841 Do all calls with the @samp{JALR} instruction, which requires
4842 loading up a function's address into a register before the call.
4843 You need to use this switch, if you call outside of the current
4844 512 megabyte segment to functions that are not through pointers.
4847 @itemx -mno-half-pic
4848 Put pointers to extern references into the data section and load them
4849 up, rather than put the references in the text section.
4851 @item -membedded-pic
4852 @itemx -mno-embedded-pic
4853 Generate PIC code suitable for some embedded systems. All calls are
4854 made using PC relative address, and all data is addressed using the $gp
4855 register. No more than 65536 bytes of global data may be used. This
4856 requires GNU as and GNU ld which do most of the work. This currently
4857 only works on targets which use ECOFF; it does not work with ELF.
4859 @item -membedded-data
4860 @itemx -mno-embedded-data
4861 Allocate variables to the read-only data section first if possible, then
4862 next in the small data section if possible, otherwise in data. This gives
4863 slightly slower code than the default, but reduces the amount of RAM required
4864 when executing, and thus may be preferred for some embedded systems.
4866 @item -msingle-float
4867 @itemx -mdouble-float
4868 The @samp{-msingle-float} switch tells gcc to assume that the floating
4869 point coprocessor only supports single precision operations, as on the
4870 @samp{r4650} chip. The @samp{-mdouble-float} switch permits gcc to use
4871 double precision operations. This is the default.
4875 Permit use of the @samp{mad}, @samp{madu} and @samp{mul} instructions,
4876 as on the @samp{r4650} chip.
4879 Turns on @samp{-msingle-float}, @samp{-mmad}, and, at least for now,
4883 Compile code for the processor in little endian mode.
4884 The requisite libraries are assumed to exist.
4887 Compile code for the processor in big endian mode.
4888 The requisite libraries are assumed to exist.
4891 @cindex smaller data references (MIPS)
4892 @cindex gp-relative references (MIPS)
4893 Put global and static items less than or equal to @var{num} bytes into
4894 the small data or bss sections instead of the normal data or bss
4895 section. This allows the assembler to emit one word memory reference
4896 instructions based on the global pointer (@var{gp} or @var{$28}),
4897 instead of the normal two words used. By default, @var{num} is 8 when
4898 the MIPS assembler is used, and 0 when the GNU assembler is used. The
4899 @samp{-G @var{num}} switch is also passed to the assembler and linker.
4900 All modules should be compiled with the same @samp{-G @var{num}}
4904 Tell the MIPS assembler to not run its preprocessor over user
4905 assembler files (with a @samp{.s} suffix) when assembling them.
4909 These options are defined by the macro
4910 @code{TARGET_SWITCHES} in the machine description. The default for the
4911 options is also defined by that macro, which enables you to change the
4916 @subsection Intel 386 Options
4917 @cindex i386 Options
4918 @cindex Intel 386 Options
4920 These @samp{-m} options are defined for the i386 family of computers:
4923 @item -mcpu=@var{cpu type}
4924 Assume the defaults for the machine type @var{cpu type} when scheduling
4925 instructions. The choices for @var{cpu type} are: @samp{i386},
4926 @samp{i486}, @samp{i586} (@samp{pentium}), @samp{pentium}, @samp{i686}
4927 (@samp{pentiumpro}) and @samp{pentiumpro}. While picking a specific
4928 @var{cpu type} will schedule things appropriately for that particular
4929 chip, the compiler will not generate any code that does not run on the
4930 i386 without the @samp{-march=@var{cpu type}} option being used.
4932 @item -march=@var{cpu type}
4933 Generate instructions for the machine type @var{cpu type}. The choices
4934 for @var{cpu type} are: @samp{i386}, @samp{i486}, @samp{pentium}, and
4935 @samp{pentiumpro}. Specifying @samp{-march=@var{cpu type}} implies
4936 @samp{-mcpu=@var{cpu type}}.
4942 Synonyms for -mcpu=i386, -mcpu=i486, -mcpu=pentium, and -mcpu=pentiumpro
4947 Control whether or not the compiler uses IEEE floating point
4948 comparisons. These handle correctly the case where the result of a
4949 comparison is unordered.
4952 Generate output containing library calls for floating point.
4953 @strong{Warning:} the requisite libraries are not part of GNU CC.
4954 Normally the facilities of the machine's usual C compiler are used, but
4955 this can't be done directly in cross-compilation. You must make your
4956 own arrangements to provide suitable library functions for
4959 On machines where a function returns floating point results in the 80387
4960 register stack, some floating point opcodes may be emitted even if
4961 @samp{-msoft-float} is used.
4963 @item -mno-fp-ret-in-387
4964 Do not use the FPU registers for return values of functions.
4966 The usual calling convention has functions return values of types
4967 @code{float} and @code{double} in an FPU register, even if there
4968 is no FPU. The idea is that the operating system should emulate
4971 The option @samp{-mno-fp-ret-in-387} causes such values to be returned
4972 in ordinary CPU registers instead.
4974 @item -mno-fancy-math-387
4975 Some 387 emulators do not support the @code{sin}, @code{cos} and
4976 @code{sqrt} instructions for the 387. Specify this option to avoid
4977 generating those instructions. This option is the default on FreeBSD.
4978 As of revision 2.6.1, these instructions are not generated unless you
4979 also use the @samp{-ffast-math} switch.
4981 @item -malign-double
4982 @itemx -mno-align-double
4983 Control whether GNU CC aligns @code{double}, @code{long double}, and
4984 @code{long long} variables on a two word boundary or a one word
4985 boundary. Aligning @code{double} variables on a two word boundary will
4986 produce code that runs somewhat faster on a @samp{Pentium} at the
4987 expense of more memory.
4989 @strong{Warning:} if you use the @samp{-malign-double} switch,
4990 structures containing the above types will be aligned differently than
4991 the published application binary interface specifications for the 386.
4994 @itemx -mno-svr3-shlib
4995 Control whether GNU CC places uninitialized locals into @code{bss} or
4996 @code{data}. @samp{-msvr3-shlib} places these locals into @code{bss}.
4997 These options are meaningful only on System V Release 3.
4999 @item -mno-wide-multiply
5000 @itemx -mwide-multiply
5001 Control whether GNU CC uses the @code{mul} and @code{imul} that produce
5002 64 bit results in @code{eax:edx} from 32 bit operands to do @code{long
5003 long} multiplies and 32-bit division by constants.
5006 Use a different function-calling convention, in which functions that
5007 take a fixed number of arguments return with the @code{ret} @var{num}
5008 instruction, which pops their arguments while returning. This saves one
5009 instruction in the caller since there is no need to pop the arguments
5012 You can specify that an individual function is called with this calling
5013 sequence with the function attribute @samp{stdcall}. You can also
5014 override the @samp{-mrtd} option by using the function attribute
5015 @samp{cdecl}. @xref{Function Attributes}
5017 @strong{Warning:} this calling convention is incompatible with the one
5018 normally used on Unix, so you cannot use it if you need to call
5019 libraries compiled with the Unix compiler.
5021 Also, you must provide function prototypes for all functions that
5022 take variable numbers of arguments (including @code{printf});
5023 otherwise incorrect code will be generated for calls to those
5026 In addition, seriously incorrect code will result if you call a
5027 function with too many arguments. (Normally, extra arguments are
5028 harmlessly ignored.)
5030 @item -mreg-alloc=@var{regs}
5031 Control the default allocation order of integer registers. The
5032 string @var{regs} is a series of letters specifying a register. The
5033 supported letters are: @code{a} allocate EAX; @code{b} allocate EBX;
5034 @code{c} allocate ECX; @code{d} allocate EDX; @code{S} allocate ESI;
5035 @code{D} allocate EDI; @code{B} allocate EBP.
5037 @item -mregparm=@var{num}
5038 Control how many registers are used to pass integer arguments. By
5039 default, no registers are used to pass arguments, and at most 3
5040 registers can be used. You can control this behavior for a specific
5041 function by using the function attribute @samp{regparm}. @xref{Function Attributes}
5043 @strong{Warning:} if you use this switch, and
5044 @var{num} is nonzero, then you must build all modules with the same
5045 value, including any libraries. This includes the system libraries and
5048 @item -malign-loops=@var{num}
5049 Align loops to a 2 raised to a @var{num} byte boundary. If
5050 @samp{-malign-loops} is not specified, the default is 2 unless
5051 gas 2.8 (or later) is being used in which case the default is
5052 to align the loop on a 16 byte boundary if it is less than 8
5055 @item -malign-jumps=@var{num}
5056 Align instructions that are only jumped to to a 2 raised to a @var{num}
5057 byte boundary. If @samp{-malign-jumps} is not specified, the default is
5058 2 if optimizing for a 386, and 4 if optimizing for a 486 unless
5059 gas 2.8 (or later) is being used in which case the default is
5060 to align the instruction on a 16 byte boundary if it is less
5063 @item -malign-functions=@var{num}
5064 Align the start of functions to a 2 raised to @var{num} byte boundary.
5065 If @samp{-malign-functions} is not specified, the default is 2 if optimizing
5066 for a 386, and 4 if optimizing for a 486.
5070 @subsection HPPA Options
5071 @cindex HPPA Options
5073 These @samp{-m} options are defined for the HPPA family of computers:
5077 Generate code for a PA 1.0 processor.
5080 Generate code for a PA 1.1 processor.
5083 Generate code suitable for big switch tables. Use this option only if
5084 the assembler/linker complain about out of range branches within a switch
5087 @item -mjump-in-delay
5088 Fill delay slots of function calls with unconditional jump instructions
5089 by modifying the return pointer for the function call to be the target
5090 of the conditional jump.
5092 @item -mdisable-fpregs
5093 Prevent floating point registers from being used in any manner. This is
5094 necessary for compiling kernels which perform lazy context switching of
5095 floating point registers. If you use this option and attempt to perform
5096 floating point operations, the compiler will abort.
5098 @item -mdisable-indexing
5099 Prevent the compiler from using indexing address modes. This avoids some
5100 rather obscure problems when compiling MIG generated code under MACH.
5102 @item -mno-space-regs
5103 Generate code that assumes the target has no space registers. This allows
5104 GCC to generate faster indirect calls and use unscaled index address modes.
5106 Such code is suitable for level 0 PA systems and kernels.
5108 @item -mfast-indirect-calls
5109 Generate code that assumes calls never cross space boundaries. This
5110 allows GCC to emit code which performs faster indirect calls.
5112 This option will not work in the presense of shared libraries or nested
5116 Optimize for space rather than execution time. Currently this only
5117 enables out of line function prologues and epilogues. This option is
5118 incompatible with PIC code generation and profiling.
5120 @item -mlong-load-store
5121 Generate 3-instruction load and store sequences as sometimes required by
5122 the HP-UX 10 linker. This is equivalent to the @samp{+k} option to
5125 @item -mportable-runtime
5126 Use the portable calling conventions proposed by HP for ELF systems.
5129 Enable the use of assembler directives only GAS understands.
5131 @item -mschedule=@var{cpu type}
5132 Schedule code according to the constraints for the machine type
5133 @var{cpu type}. The choices for @var{cpu type} are @samp{700} for
5134 7@var{n}0 machines, @samp{7100} for 7@var{n}5 machines, and @samp{7100LC}
5135 for 7@var{n}2 machines. @samp{7100} is the default for @var{cpu type}.
5137 Note the @samp{7100LC} scheduling information is incomplete and using
5138 @samp{7100LC} often leads to bad schedules. For now it's probably best
5139 to use @samp{7100} instead of @samp{7100LC} for the 7@var{n}2 machines.
5142 Enable the optimization pass in the HPUX linker. Note this makes symbolic
5143 debugging impossible. It also triggers a bug in the HPUX 8 and HPUX 9 linkers
5144 in which they give bogus error messages when linking some programs.
5147 Generate output containing library calls for floating point.
5148 @strong{Warning:} the requisite libraries are not available for all HPPA
5149 targets. Normally the facilities of the machine's usual C compiler are
5150 used, but this cannot be done directly in cross-compilation. You must make
5151 your own arrangements to provide suitable library functions for
5152 cross-compilation. The embedded target @samp{hppa1.1-*-pro}
5153 does provide software floating point support.
5155 @samp{-msoft-float} changes the calling convention in the output file;
5156 therefore, it is only useful if you compile @emph{all} of a program with
5157 this option. In particular, you need to compile @file{libgcc.a}, the
5158 library that comes with GNU CC, with @samp{-msoft-float} in order for
5162 @node Intel 960 Options
5163 @subsection Intel 960 Options
5165 These @samp{-m} options are defined for the Intel 960 implementations:
5168 @item -m@var{cpu type}
5169 Assume the defaults for the machine type @var{cpu type} for some of
5170 the other options, including instruction scheduling, floating point
5171 support, and addressing modes. The choices for @var{cpu type} are
5172 @samp{ka}, @samp{kb}, @samp{mc}, @samp{ca}, @samp{cf},
5173 @samp{sa}, and @samp{sb}.
5179 The @samp{-mnumerics} option indicates that the processor does support
5180 floating-point instructions. The @samp{-msoft-float} option indicates
5181 that floating-point support should not be assumed.
5183 @item -mleaf-procedures
5184 @itemx -mno-leaf-procedures
5185 Do (or do not) attempt to alter leaf procedures to be callable with the
5186 @code{bal} instruction as well as @code{call}. This will result in more
5187 efficient code for explicit calls when the @code{bal} instruction can be
5188 substituted by the assembler or linker, but less efficient code in other
5189 cases, such as calls via function pointers, or using a linker that doesn't
5190 support this optimization.
5193 @itemx -mno-tail-call
5194 Do (or do not) make additional attempts (beyond those of the
5195 machine-independent portions of the compiler) to optimize tail-recursive
5196 calls into branches. You may not want to do this because the detection of
5197 cases where this is not valid is not totally complete. The default is
5198 @samp{-mno-tail-call}.
5200 @item -mcomplex-addr
5201 @itemx -mno-complex-addr
5202 Assume (or do not assume) that the use of a complex addressing mode is a
5203 win on this implementation of the i960. Complex addressing modes may not
5204 be worthwhile on the K-series, but they definitely are on the C-series.
5205 The default is currently @samp{-mcomplex-addr} for all processors except
5209 @itemx -mno-code-align
5210 Align code to 8-byte boundaries for faster fetching (or don't bother).
5211 Currently turned on by default for C-series implementations only.
5214 @item -mclean-linkage
5215 @itemx -mno-clean-linkage
5216 These options are not fully implemented.
5220 @itemx -mic2.0-compat
5221 @itemx -mic3.0-compat
5222 Enable compatibility with iC960 v2.0 or v3.0.
5226 Enable compatibility with the iC960 assembler.
5228 @item -mstrict-align
5229 @itemx -mno-strict-align
5230 Do not permit (do permit) unaligned accesses.
5233 Enable structure-alignment compatibility with Intel's gcc release version
5234 1.3 (based on gcc 1.37). This option implies @samp{-mstrict-align}.
5237 @node DEC Alpha Options
5238 @subsection DEC Alpha Options
5240 These @samp{-m} options are defined for the DEC Alpha implementations:
5243 @item -mno-soft-float
5245 Use (do not use) the hardware floating-point instructions for
5246 floating-point operations. When @code{-msoft-float} is specified,
5247 functions in @file{libgcc1.c} will be used to perform floating-point
5248 operations. Unless they are replaced by routines that emulate the
5249 floating-point operations, or compiled in such a way as to call such
5250 emulations routines, these routines will issue floating-point
5251 operations. If you are compiling for an Alpha without floating-point
5252 operations, you must ensure that the library is built so as not to call
5255 Note that Alpha implementations without floating-point operations are
5256 required to have floating-point registers.
5260 Generate code that uses (does not use) the floating-point register set.
5261 @code{-mno-fp-regs} implies @code{-msoft-float}. If the floating-point
5262 register set is not used, floating point operands are passed in integer
5263 registers as if they were integers and floating-point results are passed
5264 in $0 instead of $f0. This is a non-standard calling sequence, so any
5265 function with a floating-point argument or return value called by code
5266 compiled with @code{-mno-fp-regs} must also be compiled with that
5269 A typical use of this option is building a kernel that does not use,
5270 and hence need not save and restore, any floating-point registers.
5273 The Alpha architecture implements floating-point hardware optimized for
5274 maximum performance. It is mostly compliant with the IEEE floating
5275 point standard. However, for full compliance, software assistance is
5276 required. This option generates code fully IEEE compliant code
5277 @emph{except} that the @var{inexact flag} is not maintained (see below).
5278 If this option is turned on, the CPP macro @code{_IEEE_FP} is defined
5279 during compilation. The option is a shorthand for: @samp{-D_IEEE_FP
5280 -mfp-trap-mode=su -mtrap-precision=i -mieee-conformant}. The resulting
5281 code is less efficient but is able to correctly support denormalized
5282 numbers and exceptional IEEE values such as not-a-number and plus/minus
5283 infinity. Other Alpha compilers call this option
5284 @code{-ieee_with_no_inexact}.
5286 @item -mieee-with-inexact
5287 @c overfull hbox here --bob 22 jul96
5288 @c original text between ignore ... end ignore
5290 This is like @samp{-mieee} except the generated code also maintains the
5291 IEEE @var{inexact flag}. Turning on this option causes the generated
5292 code to implement fully-compliant IEEE math. The option is a shorthand
5293 for @samp{-D_IEEE_FP -D_IEEE_FP_INEXACT} plus @samp{-mieee-conformant},
5294 @samp{-mfp-trap-mode=sui}, and @samp{-mtrap-precision=i}. On some Alpha
5295 implementations the resulting code may execute significantly slower than
5296 the code generated by default. Since there is very little code that
5297 depends on the @var{inexact flag}, you should normally not specify this
5298 option. Other Alpha compilers call this option
5299 @samp{-ieee_with_inexact}.
5301 @c changed paragraph
5302 This is like @samp{-mieee} except the generated code also maintains the
5303 IEEE @var{inexact flag}. Turning on this option causes the generated
5304 code to implement fully-compliant IEEE math. The option is a shorthand
5305 for @samp{-D_IEEE_FP -D_IEEE_FP_INEXACT} plus the three following:
5306 @samp{-mieee-conformant},
5307 @samp{-mfp-trap-mode=sui},
5308 and @samp{-mtrap-precision=i}.
5309 On some Alpha implementations the resulting code may execute
5310 significantly slower than the code generated by default. Since there
5311 is very little code that depends on the @var{inexact flag}, you should
5312 normally not specify this option. Other Alpha compilers call this
5313 option @samp{-ieee_with_inexact}.
5314 @c end changes to prevent overfull hboxes
5316 @item -mfp-trap-mode=@var{trap mode}
5317 This option controls what floating-point related traps are enabled.
5318 Other Alpha compilers call this option @samp{-fptm }@var{trap mode}.
5319 The trap mode can be set to one of four values:
5323 This is the default (normal) setting. The only traps that are enabled
5324 are the ones that cannot be disabled in software (e.g., division by zero
5328 In addition to the traps enabled by @samp{n}, underflow traps are enabled
5332 Like @samp{su}, but the instructions are marked to be safe for software
5333 completion (see Alpha architecture manual for details).
5336 Like @samp{su}, but inexact traps are enabled as well.
5339 @item -mfp-rounding-mode=@var{rounding mode}
5340 Selects the IEEE rounding mode. Other Alpha compilers call this option
5341 @samp{-fprm }@var{rounding mode}. The @var{rounding mode} can be one
5346 Normal IEEE rounding mode. Floating point numbers are rounded towards
5347 the nearest machine number or towards the even machine number in case
5351 Round towards minus infinity.
5354 Chopped rounding mode. Floating point numbers are rounded towards zero.
5357 Dynamic rounding mode. A field in the floating point control register
5358 (@var{fpcr}, see Alpha architecture reference manual) controls the
5359 rounding mode in effect. The C library initializes this register for
5360 rounding towards plus infinity. Thus, unless your program modifies the
5361 @var{fpcr}, @samp{d} corresponds to round towards plus infinity.@end table
5363 @item -mtrap-precision=@var{trap precision}
5364 In the Alpha architecture, floating point traps are imprecise. This
5365 means without software assistance it is impossible to recover from a
5366 floating trap and program execution normally needs to be terminated.
5367 GNU CC can generate code that can assist operating system trap handlers
5368 in determining the exact location that caused a floating point trap.
5369 Depending on the requirements of an application, different levels of
5370 precisions can be selected:
5374 Program precision. This option is the default and means a trap handler
5375 can only identify which program caused a floating point exception.
5378 Function precision. The trap handler can determine the function that
5379 caused a floating point exception.
5382 Instruction precision. The trap handler can determine the exact
5383 instruction that caused a floating point exception.
5386 Other Alpha compilers provide the equivalent options called
5387 @samp{-scope_safe} and @samp{-resumption_safe}.
5389 @item -mieee-conformant
5390 This option marks the generated code as IEEE conformant. You must not
5391 use this option unless you also specify @samp{-mtrap-precision=i} and either
5392 @samp{-mfp-trap-mode=su} or @samp{-mfp-trap-mode=sui}. Its only effect
5393 is to emit the line @samp{.eflag 48} in the function prologue of the
5394 generated assembly file. Under DEC Unix, this has the effect that
5395 IEEE-conformant math library routines will be linked in.
5397 @item -mbuild-constants
5398 Normally GNU CC examines a 32- or 64-bit integer constant to
5399 see if it can construct it from smaller constants in two or three
5400 instructions. If it cannot, it will output the constant as a literal and
5401 generate code to load it from the data segment at runtime.
5403 Use this option to require GNU CC to construct @emph{all} integer constants
5404 using code, even if it takes more instructions (the maximum is six).
5406 You would typically use this option to build a shared library dynamic
5407 loader. Itself a shared library, it must relocate itself in memory
5408 before it can find the variables and constants in its own data segment.
5412 Select whether to generate code to be assembled by the vendor-supplied
5413 assembler (@samp{-malpha-as}) or by the GNU assembler @samp{-mgas}.
5421 Indicate whether GNU CC should generate code to use the optional BWX,
5422 CIX, and MAX instruction sets. The default is to use the instruction sets
5423 supported by the CPU type specified via @samp{-mcpu=} option or that
5424 of the CPU on which GNU CC was built if none was specified.
5426 @item -mcpu=@var{cpu_type}
5427 Set the instruction set, register set, and instruction scheduling
5428 parameters for machine type @var{cpu_type}. You can specify either the
5429 @samp{EV} style name or the corresponding chip number. GNU CC
5430 supports scheduling parameters for the EV4 and EV5 family of processors
5431 and will choose the default values for the instruction set from
5432 the processor you specify. If you do not specify a processor type,
5433 GNU CC will default to the processor on which the compiler was built.
5435 Supported values for @var{cpu_type} are
5440 Schedules as an EV4 and has no instruction set extensions.
5444 Schedules as an EV5 and has no instruction set extensions.
5448 Schedules as an EV5 and supports the BWX extension.
5453 Schedules as an EV5 and supports the BWX and MAX extensions.
5457 Schedules as an EV5 (until Digital releases the scheduling parameters
5458 for the EV6) and supports the BWX, CIX, and MAX extensions.
5461 @item -mmemory-latency=@var{time}
5462 Sets the latency the scheduler should assume for typical memory
5463 references as seen by the application. This number is highly
5464 dependant on the memory access patterns used by the application
5465 and the size of the external cache on the machine.
5467 Valid options for @var{time} are
5471 A decimal number representing clock cycles.
5477 The compiler contains estimates of the number of clock cycles for
5478 ``typical'' EV4 & EV5 hardware for the Level 1, 2 & 3 caches
5479 (also called Dcache, Scache, and Bcache), as well as to main memory.
5480 Note that L3 is only valid for EV5.
5485 @node Clipper Options
5486 @subsection Clipper Options
5488 These @samp{-m} options are defined for the Clipper implementations:
5492 Produce code for a C300 Clipper processor. This is the default.
5495 Produce code for a C400 Clipper processor i.e. use floating point
5499 @node H8/300 Options
5500 @subsection H8/300 Options
5502 These @samp{-m} options are defined for the H8/300 implementations:
5506 Shorten some address references at link time, when possible; uses the
5507 linker option @samp{-relax}. @xref{H8/300,, @code{ld} and the H8/300,
5508 ld.info, Using ld}, for a fuller description.
5511 Generate code for the H8/300H.
5514 Generate code for the H8/S.
5517 Make @code{int} data 32 bits by default.
5520 On the h8/300h, use the same alignment rules as for the h8/300.
5521 The default for the h8/300h is to align longs and floats on 4 byte boundaries.
5522 @samp{-malign-300} causes them to be aligned on 2 byte boundaries.
5523 This option has no effect on the h8/300.
5527 @subsection SH Options
5529 These @samp{-m} options are defined for the SH implementations:
5533 Generate code for the SH1.
5536 Generate code for the SH2.
5539 Generate code for the SH3.
5542 Generate code for the SH3e.
5545 Compile code for the processor in big endian mode.
5548 Compile code for the processor in little endian mode.
5551 Align doubles at 64 bit boundaries. Note that this changes the calling
5552 conventions, and thus some functions from the standard C library will
5553 not work unless you recompile it first with -mdalign.
5556 Shorten some address references at link time, when possible; uses the
5557 linker option @samp{-relax}.
5560 @node System V Options
5561 @subsection Options for System V
5563 These additional options are available on System V Release 4 for
5564 compatibility with other compilers on those systems:
5568 Create a shared object.
5569 It is recommended that @samp{-symbolic} or @samp{-shared} be used instead.
5572 Identify the versions of each tool used by the compiler, in a
5573 @code{.ident} assembler directive in the output.
5576 Refrain from adding @code{.ident} directives to the output file (this is
5579 @item -YP,@var{dirs}
5580 Search the directories @var{dirs}, and no others, for libraries
5581 specified with @samp{-l}.
5584 Look in the directory @var{dir} to find the M4 preprocessor.
5585 The assembler uses this option.
5586 @c This is supposed to go with a -Yd for predefined M4 macro files, but
5587 @c the generic assembler that comes with Solaris takes just -Ym.
5591 @subsection V850 Options
5592 @cindex V850 Options
5594 These @samp{-m} options are defined for V850 implementations:
5598 @itemx -mno-long-calls
5599 Treat all calls as being far away (near). If calls are assumed to be
5600 far away, the compiler will always load the functions address up into a
5601 register, and call indirect through the pointer.
5605 Do not optimize (do optimize) basic blocks that use the same index
5606 pointer 4 or more times to copy pointer into the @code{ep} register, and
5607 use the shorter @code{sld} and @code{sst} instructions. The @samp{-mep}
5608 option is on by default if you optimize.
5610 @item -mno-prolog-function
5611 @itemx -mprolog-function
5612 Do not use (do use) external functions to save and restore registers at
5613 the prolog and epilog of a function. The external functions are slower,
5614 but use less code space if more than one function saves the same number
5615 of registers. The @samp{-mprolog-function} option is on by default if
5619 Try to make the code as small as possible. At present, this just turns
5620 on the @samp{-mep} and @samp{-mprolog-function} options.
5623 Put static or global variables whose size is @var{n} bytes or less into
5624 the tiny data area that register @code{ep} points to. The tiny data
5625 area can hold up to 256 bytes in total (128 bytes for byte references).
5628 Put static or global variables whose size is @var{n} bytes or less into
5629 the small data area that register @code{gp} points to. The small data
5630 area can hold up to 64 kilobytes.
5633 Put static or global variables whose size is @var{n} bytes or less into
5634 the first 32 kilobytes of memory.
5637 Specify that the target processor is the V850.
5640 Generate code suitable for big switch tables. Use this option only if
5641 the assembler/linker complain about out of range branches within a switch
5646 @subsection ARC Options
5649 These options are defined for ARC implementations:
5653 Compile code for little endian mode. This is the default.
5656 Compile code for big endian mode.
5659 Prepend the name of the cpu to all public symbol names.
5660 In multiple-processor systems, there are many ARC variants with different
5661 instruction and register set characteristics. This flag prevents code
5662 compiled for one cpu to be linked with code compiled for another.
5663 No facility exists for handling variants that are "almost identical".
5664 This is an all or nothing option.
5666 @item -mcpu=@var{cpu}
5667 Compile code for ARC variant @var{cpu}.
5668 Which variants are supported depend on the configuration.
5669 All variants support @samp{-mcpu=base}, this is the default.
5671 @item -mtext=@var{text section}
5672 @item -mdata=@var{data section}
5673 @item -mrodata=@var{readonly data section}
5674 Put functions, data, and readonly data in @var{text section},
5675 @var{data section}, and @var{readonly data section} respectively
5676 by default. This can be overridden with the @code{section} attribute.
5677 @xref{Variable Attributes}
5682 @node Code Gen Options
5683 @section Options for Code Generation Conventions
5684 @cindex code generation conventions
5685 @cindex options, code generation
5686 @cindex run-time options
5688 These machine-independent options control the interface conventions
5689 used in code generation.
5691 Most of them have both positive and negative forms; the negative form
5692 of @samp{-ffoo} would be @samp{-fno-foo}. In the table below, only
5693 one of the forms is listed---the one which is not the default. You
5694 can figure out the other form by either removing @samp{no-} or adding
5699 Enable exception handling. Generates extra code needed to propagate
5700 exceptions. For some targets, this implies generation of frame unwind
5701 information for all functions. This can produce significant data size
5702 overhead, although it does not affect execution.
5703 If you do not specify this option, it is enabled by
5704 default for languages like C++ which normally require exception handling,
5705 and disabled for languages like C that do not normally require it.
5706 However, when compiling C code that needs to interoperate properly with
5707 exception handlers written in C++, you may need to enable this option.
5708 You may also wish to disable this option is you are compiling older C++
5709 programs that don't use exception handling.
5711 @item -fpcc-struct-return
5712 Return ``short'' @code{struct} and @code{union} values in memory like
5713 longer ones, rather than in registers. This convention is less
5714 efficient, but it has the advantage of allowing intercallability between
5715 GNU CC-compiled files and files compiled with other compilers.
5717 The precise convention for returning structures in memory depends
5718 on the target configuration macros.
5720 Short structures and unions are those whose size and alignment match
5721 that of some integer type.
5723 @item -freg-struct-return
5724 Use the convention that @code{struct} and @code{union} values are
5725 returned in registers when possible. This is more efficient for small
5726 structures than @samp{-fpcc-struct-return}.
5728 If you specify neither @samp{-fpcc-struct-return} nor its contrary
5729 @samp{-freg-struct-return}, GNU CC defaults to whichever convention is
5730 standard for the target. If there is no standard convention, GNU CC
5731 defaults to @samp{-fpcc-struct-return}, except on targets where GNU CC
5732 is the principal compiler. In those cases, we can choose the standard,
5733 and we chose the more efficient register return alternative.
5736 Allocate to an @code{enum} type only as many bytes as it needs for the
5737 declared range of possible values. Specifically, the @code{enum} type
5738 will be equivalent to the smallest integer type which has enough room.
5740 @item -fshort-double
5741 Use the same size for @code{double} as for @code{float}.
5744 Requests that the data and non-@code{const} variables of this
5745 compilation be shared data rather than private data. The distinction
5746 makes sense only on certain operating systems, where shared data is
5747 shared between processes running the same program, while private data
5748 exists in one copy per process.
5751 Allocate even uninitialized global variables in the bss section of the
5752 object file, rather than generating them as common blocks. This has the
5753 effect that if the same variable is declared (without @code{extern}) in
5754 two different compilations, you will get an error when you link them.
5755 The only reason this might be useful is if you wish to verify that the
5756 program will work on other systems which always work this way.
5759 Ignore the @samp{#ident} directive.
5761 @item -fno-gnu-linker
5762 Do not output global initializations (such as C++ constructors and
5763 destructors) in the form used by the GNU linker (on systems where the GNU
5764 linker is the standard method of handling them). Use this option when
5765 you want to use a non-GNU linker, which also requires using the
5766 @code{collect2} program to make sure the system linker includes
5767 constructors and destructors. (@code{collect2} is included in the GNU CC
5768 distribution.) For systems which @emph{must} use @code{collect2}, the
5769 compiler driver @code{gcc} is configured to do this automatically.
5771 @item -finhibit-size-directive
5772 Don't output a @code{.size} assembler directive, or anything else that
5773 would cause trouble if the function is split in the middle, and the
5774 two halves are placed at locations far apart in memory. This option is
5775 used when compiling @file{crtstuff.c}; you should not need to use it
5779 Put extra commentary information in the generated assembly code to
5780 make it more readable. This option is generally only of use to those
5781 who actually need to read the generated assembly code (perhaps while
5782 debugging the compiler itself).
5784 @samp{-fno-verbose-asm}, the default, causes the
5785 extra information to be omitted and is useful when comparing two assembler
5789 Consider all memory references through pointers to be volatile.
5791 @item -fvolatile-global
5792 Consider all memory references to extern and global data items to
5796 @cindex global offset table
5798 Generate position-independent code (PIC) suitable for use in a shared
5799 library, if supported for the target machine. Such code accesses all
5800 constant addresses through a global offset table (GOT). The dynamic
5801 loader resolves the GOT entries when the program starts (the dynamic
5802 loader is not part of GNU CC; it is part of the operating system). If
5803 the GOT size for the linked executable exceeds a machine-specific
5804 maximum size, you get an error message from the linker indicating that
5805 @samp{-fpic} does not work; in that case, recompile with @samp{-fPIC}
5806 instead. (These maximums are 16k on the m88k, 8k on the Sparc, and 32k
5807 on the m68k and RS/6000. The 386 has no such limit.)
5809 Position-independent code requires special support, and therefore works
5810 only on certain machines. For the 386, GNU CC supports PIC for System V
5811 but not for the Sun 386i. Code generated for the IBM RS/6000 is always
5812 position-independent.
5815 If supported for the target machine, emit position-independent code,
5816 suitable for dynamic linking and avoiding any limit on the size of the
5817 global offset table. This option makes a difference on the m68k, m88k,
5820 Position-independent code requires special support, and therefore works
5821 only on certain machines.
5823 @item -ffixed-@var{reg}
5824 Treat the register named @var{reg} as a fixed register; generated code
5825 should never refer to it (except perhaps as a stack pointer, frame
5826 pointer or in some other fixed role).
5828 @var{reg} must be the name of a register. The register names accepted
5829 are machine-specific and are defined in the @code{REGISTER_NAMES}
5830 macro in the machine description macro file.
5832 This flag does not have a negative form, because it specifies a
5835 @item -fcall-used-@var{reg}
5836 Treat the register named @var{reg} as an allocable register that is
5837 clobbered by function calls. It may be allocated for temporaries or
5838 variables that do not live across a call. Functions compiled this way
5839 will not save and restore the register @var{reg}.
5841 It is an error to used this flag with the frame pointer or stack pointer.
5842 Use of this flag for other registers that have fixed pervasive roles in
5843 the machine's execution model will produce disastrous results.
5845 This flag does not have a negative form, because it specifies a
5848 @item -fcall-saved-@var{reg}
5849 Treat the register named @var{reg} as an allocable register saved by
5850 functions. It may be allocated even for temporaries or variables that
5851 live across a call. Functions compiled this way will save and restore
5852 the register @var{reg} if they use it.
5854 It is an error to used this flag with the frame pointer or stack pointer.
5855 Use of this flag for other registers that have fixed pervasive roles in
5856 the machine's execution model will produce disastrous results.
5858 A different sort of disaster will result from the use of this flag for
5859 a register in which function values may be returned.
5861 This flag does not have a negative form, because it specifies a
5865 Pack all structure members together without holes. Usually you would
5866 not want to use this option, since it makes the code suboptimal, and
5867 the offsets of structure members won't agree with system libraries.
5869 @item -fcheck-memory-usage
5870 Generate extra code to check each memory access. GNU CC will generate
5871 code that is suitable for a detector of bad memory accesses such as
5874 You must also specify this option when you compile functions you call that
5875 have side effects. If you do not, you may get erroneous messages from
5876 the detector. Normally, you should compile all your code with this option.
5877 If you use functions from a library that have side-effects (such as
5878 @code{read}), you may not be able to recompile the library and
5879 specify this option. In that case, you can enable the
5880 @samp{-fprefix-function-name} option, which requests GNU CC to encapsulate
5881 your code and make other functions look as if they were compiled with
5882 @samp{-fcheck-memory-usage}. This is done by calling ``stubs'',
5883 which are provided by the detector. If you cannot find or build
5884 stubs for every function you call, you may have to specify
5885 @samp{-fcheck-memory-usage} without @samp{-fprefix-function-name}.
5887 If you specify this option, you can not use the @code{asm} or
5888 @code{__asm__} keywords in functions with memory checking enabled. The
5889 compiler cannot understand what the @code{asm} statement will do, and
5890 therefore cannot generate the appropriate code, so it is rejected.
5891 However, the function attribute @code{no_check_memory_usage} will
5892 disable memory checking within a function, and @code{asm} statements can
5893 be put inside such functions. Inline expansion of a non-checked
5894 function within a checked function is permitted; the inline function's
5895 memory accesses won't be checked, but the rest will.
5897 If you move your @code{asm} statements to non-checked inline functions,
5898 but they do access memory, you can add calls to the support code in your
5899 inline function, to indicate any reads, writes, or copies being done.
5900 These calls would be similar to those done in the stubs described above.
5902 @c FIXME: The support-routine interface is defined by the compiler and
5903 @c should be documented!
5905 @item -fprefix-function-name
5906 Request GNU CC to add a prefix to the symbols generated for function names.
5907 GNU CC adds a prefix to the names of functions defined as well as
5908 functions called. Code compiled with this option and code compiled
5909 without the option can't be linked together, unless or stubs are used.
5911 If you compile the following code with @samp{-fprefix-function-name}
5913 extern void bar (int);
5923 GNU CC will compile the code as if it was written:
5925 extern void prefix_bar (int);
5929 return prefix_bar (a + 5);
5932 This option is designed to be used with @samp{-fcheck-memory-usage}.
5934 @item -finstrument-functions
5935 Generate instrumentation calls for entry and exit to functions. Just
5936 after function entry and just before function exit, the following
5937 profiling functions will be called with the address of the current
5938 function and its call site. (On some platforms,
5939 @code{__builtin_return_address} does not work beyond the current
5940 function, so the call site information may not be available to the
5941 profiling functions otherwise.)
5944 void __cyg_profile_func_enter (void *this_fn, void *call_site);
5945 void __cyg_profile_func_exit (void *this_fn, void *call_site);
5948 The first argument is the address of the start of the current function,
5949 which may be looked up exactly in the symbol table.
5951 This instrumentation is also done for functions expanded inline in other
5952 functions. The profiling calls will indicate where, conceptually, the
5953 inline function is entered and exited. This means that addressable
5954 versions of such functions must be available. If all your uses of a
5955 function are expanded inline, this may mean an additional expansion of
5956 code size. If you use @samp{extern inline} in your C code, an
5957 addressable version of such functions must be provided. (This is
5958 normally the case anyways, but if you get lucky and the optimizer always
5959 expands the functions inline, you might have gotten away without
5960 providing static copies.)
5962 A function may be given the attribute @code{no_instrument_function}, in
5963 which case this instrumentation will not be done. This can be used, for
5964 example, for the profiling functions listed above, high-priority
5965 interrupt routines, and any functions from which the profiling functions
5966 cannot safely be called (perhaps signal handlers, if the profiling
5967 routines generate output or allocate memory).
5970 Generate code to verify that you do not go beyond the boundary of the
5971 stack. You should specify this flag if you are running in an
5972 environment with multiple threads, but only rarely need to specify it in
5973 a single-threaded environment since stack overflow is automatically
5974 detected on nearly all systems if there is only one stack.
5976 @cindex aliasing of parameters
5977 @cindex parameters, aliased
5978 @item -fargument-alias
5979 @itemx -fargument-noalias
5980 @itemx -fargument-noalias-global
5981 Specify the possible relationships among parameters and between
5982 parameters and global data.
5984 @samp{-fargument-alias} specifies that arguments (parameters) may
5985 alias each other and may alias global storage.
5986 @samp{-fargument-noalias} specifies that arguments do not alias
5987 each other, but may alias global storage.
5988 @samp{-fargument-noalias-global} specifies that arguments do not
5989 alias each other and do not alias global storage.
5991 Each language will automatically use whatever option is required by
5992 the language standard. You should not need to use these options yourself.
5994 @item -fleading-underscore
5995 This option and its counterpart, -fno-leading-underscore, forcibly
5996 change the way C symbols are represented in the object file. One use
5997 is to help link with legacy assembly code.
5999 Be warned that you should know what you are doing when invoking this
6000 option, and that not all targets provide complete support for it.
6003 @node Environment Variables
6004 @section Environment Variables Affecting GNU CC
6005 @cindex environment variables
6007 This section describes several environment variables that affect how GNU
6008 CC operates. Some of them work by specifying directories or prefixes to use
6009 when searching for various kinds of files. Some are used to specify other
6010 aspects of the compilation environment.
6013 Note that you can also specify places to search using options such as
6014 @samp{-B}, @samp{-I} and @samp{-L} (@pxref{Directory Options}). These
6015 take precedence over places specified using environment variables, which
6016 in turn take precedence over those specified by the configuration of GNU
6020 Note that you can also specify places to search using options such as
6021 @samp{-B}, @samp{-I} and @samp{-L} (@pxref{Directory Options}). These
6022 take precedence over places specified using environment variables, which
6023 in turn take precedence over those specified by the configuration of GNU
6030 If @code{TMPDIR} is set, it specifies the directory to use for temporary
6031 files. GNU CC uses temporary files to hold the output of one stage of
6032 compilation which is to be used as input to the next stage: for example,
6033 the output of the preprocessor, which is the input to the compiler
6036 @item GCC_EXEC_PREFIX
6037 @findex GCC_EXEC_PREFIX
6038 If @code{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the
6039 names of the subprograms executed by the compiler. No slash is added
6040 when this prefix is combined with the name of a subprogram, but you can
6041 specify a prefix that ends with a slash if you wish.
6043 If GNU CC cannot find the subprogram using the specified prefix, it
6044 tries looking in the usual places for the subprogram.
6046 The default value of @code{GCC_EXEC_PREFIX} is
6047 @file{@var{prefix}/lib/gcc-lib/} where @var{prefix} is the value
6048 of @code{prefix} when you ran the @file{configure} script.
6050 Other prefixes specified with @samp{-B} take precedence over this prefix.
6052 This prefix is also used for finding files such as @file{crt0.o} that are
6055 In addition, the prefix is used in an unusual way in finding the
6056 directories to search for header files. For each of the standard
6057 directories whose name normally begins with @samp{/usr/local/lib/gcc-lib}
6058 (more precisely, with the value of @code{GCC_INCLUDE_DIR}), GNU CC tries
6059 replacing that beginning with the specified prefix to produce an
6060 alternate directory name. Thus, with @samp{-Bfoo/}, GNU CC will search
6061 @file{foo/bar} where it would normally search @file{/usr/local/lib/bar}.
6062 These alternate directories are searched first; the standard directories
6066 @findex COMPILER_PATH
6067 The value of @code{COMPILER_PATH} is a colon-separated list of
6068 directories, much like @code{PATH}. GNU CC tries the directories thus
6069 specified when searching for subprograms, if it can't find the
6070 subprograms using @code{GCC_EXEC_PREFIX}.
6073 @findex LIBRARY_PATH
6074 The value of @code{LIBRARY_PATH} is a colon-separated list of
6075 directories, much like @code{PATH}. When configured as a native compiler,
6076 GNU CC tries the directories thus specified when searching for special
6077 linker files, if it can't find them using @code{GCC_EXEC_PREFIX}. Linking
6078 using GNU CC also uses these directories when searching for ordinary
6079 libraries for the @samp{-l} option (but directories specified with
6080 @samp{-L} come first).
6082 @item C_INCLUDE_PATH
6083 @itemx CPLUS_INCLUDE_PATH
6084 @itemx OBJC_INCLUDE_PATH
6085 @findex C_INCLUDE_PATH
6086 @findex CPLUS_INCLUDE_PATH
6087 @findex OBJC_INCLUDE_PATH
6088 @c @itemx OBJCPLUS_INCLUDE_PATH
6089 These environment variables pertain to particular languages. Each
6090 variable's value is a colon-separated list of directories, much like
6091 @code{PATH}. When GNU CC searches for header files, it tries the
6092 directories listed in the variable for the language you are using, after
6093 the directories specified with @samp{-I} but before the standard header
6096 @item DEPENDENCIES_OUTPUT
6097 @findex DEPENDENCIES_OUTPUT
6098 @cindex dependencies for make as output
6099 If this variable is set, its value specifies how to output dependencies
6100 for Make based on the header files processed by the compiler. This
6101 output looks much like the output from the @samp{-M} option
6102 (@pxref{Preprocessor Options}), but it goes to a separate file, and is
6103 in addition to the usual results of compilation.
6105 The value of @code{DEPENDENCIES_OUTPUT} can be just a file name, in
6106 which case the Make rules are written to that file, guessing the target
6107 name from the source file name. Or the value can have the form
6108 @samp{@var{file} @var{target}}, in which case the rules are written to
6109 file @var{file} using @var{target} as the target name.
6113 @cindex locale definition
6114 This variable is used to pass locale information to the compiler. One way in
6115 which this information is used is to determine the character set to be used
6116 when character literals, string literals and comments are parsed in C and C++.
6117 When the compiler is configured to allow multibyte characters,
6118 the following values for @code{LANG} are recognized:
6122 Recognize JIS characters.
6124 Recognize SJIS characters.
6126 Recognize EUCJP characters.
6129 If @code{LANG} is not defined, or if it has some other value, then the
6130 compiler will use mblen and mbtowc as defined by the default locale to
6131 recognize and translate multibyte characters.
6134 @node Running Protoize
6135 @section Running Protoize
6137 The program @code{protoize} is an optional part of GNU C. You can use
6138 it to add prototypes to a program, thus converting the program to ANSI
6139 C in one respect. The companion program @code{unprotoize} does the
6140 reverse: it removes argument types from any prototypes that are found.
6142 When you run these programs, you must specify a set of source files as
6143 command line arguments. The conversion programs start out by compiling
6144 these files to see what functions they define. The information gathered
6145 about a file @var{foo} is saved in a file named @file{@var{foo}.X}.
6147 After scanning comes actual conversion. The specified files are all
6148 eligible to be converted; any files they include (whether sources or
6149 just headers) are eligible as well.
6151 But not all the eligible files are converted. By default,
6152 @code{protoize} and @code{unprotoize} convert only source and header
6153 files in the current directory. You can specify additional directories
6154 whose files should be converted with the @samp{-d @var{directory}}
6155 option. You can also specify particular files to exclude with the
6156 @samp{-x @var{file}} option. A file is converted if it is eligible, its
6157 directory name matches one of the specified directory names, and its
6158 name within the directory has not been excluded.
6160 Basic conversion with @code{protoize} consists of rewriting most
6161 function definitions and function declarations to specify the types of
6162 the arguments. The only ones not rewritten are those for varargs
6165 @code{protoize} optionally inserts prototype declarations at the
6166 beginning of the source file, to make them available for any calls that
6167 precede the function's definition. Or it can insert prototype
6168 declarations with block scope in the blocks where undeclared functions
6171 Basic conversion with @code{unprotoize} consists of rewriting most
6172 function declarations to remove any argument types, and rewriting
6173 function definitions to the old-style pre-ANSI form.
6175 Both conversion programs print a warning for any function declaration or
6176 definition that they can't convert. You can suppress these warnings
6179 The output from @code{protoize} or @code{unprotoize} replaces the
6180 original source file. The original file is renamed to a name ending
6181 with @samp{.save}. If the @samp{.save} file already exists, then
6182 the source file is simply discarded.
6184 @code{protoize} and @code{unprotoize} both depend on GNU CC itself to
6185 scan the program and collect information about the functions it uses.
6186 So neither of these programs will work until GNU CC is installed.
6188 Here is a table of the options you can use with @code{protoize} and
6189 @code{unprotoize}. Each option works with both programs unless
6193 @item -B @var{directory}
6194 Look for the file @file{SYSCALLS.c.X} in @var{directory}, instead of the
6195 usual directory (normally @file{/usr/local/lib}). This file contains
6196 prototype information about standard system functions. This option
6197 applies only to @code{protoize}.
6199 @item -c @var{compilation-options}
6200 Use @var{compilation-options} as the options when running @code{gcc} to
6201 produce the @samp{.X} files. The special option @samp{-aux-info} is
6202 always passed in addition, to tell @code{gcc} to write a @samp{.X} file.
6204 Note that the compilation options must be given as a single argument to
6205 @code{protoize} or @code{unprotoize}. If you want to specify several
6206 @code{gcc} options, you must quote the entire set of compilation options
6207 to make them a single word in the shell.
6209 There are certain @code{gcc} arguments that you cannot use, because they
6210 would produce the wrong kind of output. These include @samp{-g},
6211 @samp{-O}, @samp{-c}, @samp{-S}, and @samp{-o} If you include these in
6212 the @var{compilation-options}, they are ignored.
6215 Rename files to end in @samp{.C} instead of @samp{.c}.
6216 This is convenient if you are converting a C program to C++.
6217 This option applies only to @code{protoize}.
6220 Add explicit global declarations. This means inserting explicit
6221 declarations at the beginning of each source file for each function
6222 that is called in the file and was not declared. These declarations
6223 precede the first function definition that contains a call to an
6224 undeclared function. This option applies only to @code{protoize}.
6226 @item -i @var{string}
6227 Indent old-style parameter declarations with the string @var{string}.
6228 This option applies only to @code{protoize}.
6230 @code{unprotoize} converts prototyped function definitions to old-style
6231 function definitions, where the arguments are declared between the
6232 argument list and the initial @samp{@{}. By default, @code{unprotoize}
6233 uses five spaces as the indentation. If you want to indent with just
6234 one space instead, use @samp{-i " "}.
6237 Keep the @samp{.X} files. Normally, they are deleted after conversion
6241 Add explicit local declarations. @code{protoize} with @samp{-l} inserts
6242 a prototype declaration for each function in each block which calls the
6243 function without any declaration. This option applies only to
6247 Make no real changes. This mode just prints information about the conversions
6248 that would have been done without @samp{-n}.
6251 Make no @samp{.save} files. The original files are simply deleted.
6252 Use this option with caution.
6254 @item -p @var{program}
6255 Use the program @var{program} as the compiler. Normally, the name
6259 Work quietly. Most warnings are suppressed.
6262 Print the version number, just like @samp{-v} for @code{gcc}.
6265 If you need special compiler options to compile one of your program's
6266 source files, then you should generate that file's @samp{.X} file
6267 specially, by running @code{gcc} on that source file with the
6268 appropriate options and the option @samp{-aux-info}. Then run
6269 @code{protoize} on the entire set of files. @code{protoize} will use
6270 the existing @samp{.X} file because it is newer than the source file.
6274 gcc -Dfoo=bar file1.c -aux-info
6279 You need to include the special files along with the rest in the
6280 @code{protoize} command, even though their @samp{.X} files already
6281 exist, because otherwise they won't get converted.
6283 @xref{Protoize Caveats}, for more information on how to use
6284 @code{protoize} successfully.