1 @c Copyright (C) 1988,89,92,93,94,95,96,97,1998 Free Software Foundation, Inc.
2 @c This is part of the GCC manual.
3 @c For copying conditions, see the file gcc.texi.
6 @chapter GNU CC Command Options
7 @cindex GNU CC command options
8 @cindex command options
9 @cindex options, GNU CC command
11 When you invoke GNU CC, it normally does preprocessing, compilation,
12 assembly and linking. The ``overall options'' allow you to stop this
13 process at an intermediate stage. For example, the @samp{-c} option
14 says not to run the linker. Then the output consists of object files
15 output by the assembler.
17 Other options are passed on to one stage of processing. Some options
18 control the preprocessor and others the compiler itself. Yet other
19 options control the assembler and linker; most of these are not
20 documented here, since you rarely need to use any of them.
22 @cindex C compilation options
23 Most of the command line options that you can use with GNU CC are useful
24 for C programs; when an option is only useful with another language
25 (usually C++), the explanation says so explicitly. If the description
26 for a particular option does not mention a source language, you can use
27 that option with all supported languages.
29 @cindex C++ compilation options
30 @xref{Invoking G++,,Compiling C++ Programs}, for a summary of special
31 options for compiling C++ programs.
33 @cindex grouping options
34 @cindex options, grouping
35 The @code{gcc} program accepts options and file names as operands. Many
36 options have multiletter names; therefore multiple single-letter options
37 may @emph{not} be grouped: @samp{-dr} is very different from @w{@samp{-d
40 @cindex order of options
41 @cindex options, order
42 You can mix options and other arguments. For the most part, the order
43 you use doesn't matter. Order does matter when you use several options
44 of the same kind; for example, if you specify @samp{-L} more than once,
45 the directories are searched in the order specified.
47 Many options have long names starting with @samp{-f} or with
48 @samp{-W}---for example, @samp{-fforce-mem},
49 @samp{-fstrength-reduce}, @samp{-Wformat} and so on. Most of
50 these have both positive and negative forms; the negative form of
51 @samp{-ffoo} would be @samp{-fno-foo}. This manual documents
52 only one of these two forms, whichever one is not the default.
55 * Option Summary:: Brief list of all options, without explanations.
56 * Overall Options:: Controlling the kind of output:
57 an executable, object files, assembler files,
58 or preprocessed source.
59 * Invoking G++:: Compiling C++ programs.
60 * C Dialect Options:: Controlling the variant of C language compiled.
61 * C++ Dialect Options:: Variations on C++.
62 * Warning Options:: How picky should the compiler be?
63 * Debugging Options:: Symbol tables, measurements, and debugging dumps.
64 * Optimize Options:: How much optimization?
65 * Preprocessor Options:: Controlling header files and macro definitions.
66 Also, getting dependency information for Make.
67 * Assembler Options:: Passing options to the assembler.
68 * Link Options:: Specifying libraries and so on.
69 * Directory Options:: Where to find header files and libraries.
70 Where to find the compiler executable files.
71 * Target Options:: Running a cross-compiler, or an old version of GNU CC.
72 * Submodel Options:: Specifying minor hardware or convention variations,
73 such as 68010 vs 68020.
74 * Code Gen Options:: Specifying conventions for function calls, data layout
76 * Environment Variables:: Env vars that affect GNU CC.
77 * Running Protoize:: Automatically adding or removing function prototypes.
81 @section Option Summary
83 Here is a summary of all the options, grouped by type. Explanations are
84 in the following sections.
88 @xref{Overall Options,,Options Controlling the Kind of Output}.
90 -c -S -E -o @var{file} -pipe -v -x @var{language}
93 @item C Language Options
94 @xref{C Dialect Options,,Options Controlling C Dialect}.
96 -ansi -fallow-single-precision -fcond-mismatch -fno-asm
97 -fno-builtin -ffreestanding -fhosted -fsigned-bitfields -fsigned-char
98 -funsigned-bitfields -funsigned-char -fwritable-strings
99 -traditional -traditional-cpp -trigraphs
102 @item C++ Language Options
103 @xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
105 -fall-virtual -fdollars-in-identifiers -felide-constructors
106 -fenum-int-equiv -fexternal-templates -ffor-scope
107 -fno-for-scope -fhandle-signatures -fmemoize-lookups
108 -fname-mangling-version-@var{n} -fno-default-inline
109 -fno-gnu-keywords -fnonnull-objects -fguiding-decls
110 -foperator-names -fno-optional-diags -fstrict-prototype -fthis-is-variable
111 -ftemplate-depth-@var{n} -nostdinc++ -traditional +e@var{n}
114 @item Warning Options
115 @xref{Warning Options,,Options to Request or Suppress Warnings}.
117 -fsyntax-only -pedantic -pedantic-errors
118 -w -W -Wall -Waggregate-return -Wbad-function-cast
119 -Wcast-align -Wcast-qual -Wchar-subscript -Wcomment
120 -Wconversion -Werror -Wformat
121 -Wid-clash-@var{len} -Wimplicit -Wimplicit-int
122 -Wimplicit-function-declaration -Wimport
123 -Werror-implicit-function-declaration -Winline
124 -Wlarger-than-@var{len} -Wlong-long
125 -Wmain -Wmissing-declarations
126 -Wmissing-prototypes -Wmultichar -Wnested-externs -Wno-import
127 -Wold-style-cast -Woverloaded-virtual -Wparentheses
128 -Wpointer-arith -Wredundant-decls -Wreorder -Wreturn-type
129 -Wshadow -Wsign-compare -Wstrict-prototypes -Wswitch
130 -Wsynth -Wtemplate-debugging -Wtraditional -Wtrigraphs
131 -Wundef -Wuninitialized -Wunused -Wwrite-strings
135 @item Debugging Options
136 @xref{Debugging Options,,Options for Debugging Your Program or GCC}.
138 -a -ax -d@var{letters} -fpretend-float
139 -fprofile-arcs -ftest-coverage
140 -g -g@var{level} -gcoff -gdwarf -gdwarf-1 -gdwarf-1+ -gdwarf-2
141 -ggdb -gstabs -gstabs+ -gxcoff -gxcoff+
142 -p -pg -print-file-name=@var{library} -print-libgcc-file-name
143 -print-prog-name=@var{program} -print-search-dirs -save-temps
146 @item Optimization Options
147 @xref{Optimize Options,,Options that Control Optimization}.
149 -fbranch-probabilities -foptimize-register-moves
150 -fcaller-saves -fcse-follow-jumps -fcse-skip-blocks
151 -fdelayed-branch -fexpensive-optimizations
152 -ffast-math -ffloat-store -fforce-addr -fforce-mem
153 -ffunction-sections -fgcse -finline-functions
154 -fkeep-inline-functions -fno-default-inline
155 -fno-defer-pop -fno-function-cse
156 -fno-inline -fno-peephole -fomit-frame-pointer -fregmove
157 -frerun-cse-after-loop -frerun-loop-opt -fschedule-insns
158 -fschedule-insns2 -fstrength-reduce -fthread-jumps
159 -funroll-all-loops -funroll-loops
160 -fmove-all-movables -freduce-all-givs -fstrict-aliasing
161 -O -O0 -O1 -O2 -O3 -Os
164 @item Preprocessor Options
165 @xref{Preprocessor Options,,Options Controlling the Preprocessor}.
167 -A@var{question}(@var{answer}) -C -dD -dM -dN
168 -D@var{macro}@r{[}=@var{defn}@r{]} -E -H
170 -include @var{file} -imacros @var{file}
171 -iprefix @var{file} -iwithprefix @var{dir}
172 -iwithprefixbefore @var{dir} -isystem @var{dir}
173 -M -MD -MM -MMD -MG -nostdinc -P -trigraphs
174 -undef -U@var{macro} -Wp,@var{option}
177 @item Assembler Option
178 @xref{Assembler Options,,Passing Options to the Assembler}.
184 @xref{Link Options,,Options for Linking}.
186 @var{object-file-name} -l@var{library}
187 -nostartfiles -nodefaultlibs -nostdlib
188 -s -static -shared -symbolic
189 -Wl,@var{option} -Xlinker @var{option}
193 @item Directory Options
194 @xref{Directory Options,,Options for Directory Search}.
196 -B@var{prefix} -I@var{dir} -I- -L@var{dir} -specs=@var{file}
200 @c I wrote this xref this way to avoid overfull hbox. -- rms
201 @xref{Target Options}.
203 -b @var{machine} -V @var{version}
206 @item Machine Dependent Options
207 @xref{Submodel Options,,Hardware Models and Configurations}.
209 @emph{M680x0 Options}
210 -m68000 -m68020 -m68020-40 -m68020-60 -m68030 -m68040
211 -m68060 -mcpu32 -m5200 -m68881 -mbitfield -mc68000 -mc68020
212 -mfpa -mnobitfield -mrtd -mshort -msoft-float
220 -mtune=@var{cpu type}
221 -mcmodel=@var{code model}
222 -malign-jumps=@var{num} -malign-loops=@var{num}
223 -malign-functions=@var{num}
225 -mapp-regs -mbroken-saverestore -mcypress -mepilogue
226 -mflat -mfpu -mhard-float -mhard-quad-float
227 -mimpure-text -mlive-g0 -mno-app-regs -mno-epilogue
228 -mno-flat -mno-fpu -mno-impure-text
229 -mno-stack-bias -mno-unaligned-doubles
230 -msoft-float -msoft-quad-float -msparclite -mstack-bias
231 -msupersparc -munaligned-doubles -mv8
233 @emph{Convex Options}
234 -mc1 -mc2 -mc32 -mc34 -mc38
235 -margcount -mnoargcount
237 -mvolatile-cache -mvolatile-nocache
239 @emph{AMD29K Options}
240 -m29000 -m29050 -mbw -mnbw -mdw -mndw
241 -mlarge -mnormal -msmall
242 -mkernel-registers -mno-reuse-arg-regs
243 -mno-stack-check -mno-storem-bug
244 -mreuse-arg-regs -msoft-float -mstack-check
245 -mstorem-bug -muser-registers
248 -mapcs-frame -mno-apcs-frame
250 -mapcs-stack-check -mno-apcs-stack-check
251 -mapcs-float -mno-apcs-float
252 -mapcs-reentrant -mno-apcs-reentrant
253 -msched-prolog -mno-sched-prolog
254 -mlittle-endian -mbig-endian -mwords-little-endian
255 -mshort-load-bytes -mno-short-load-bytes -mshort-load-words -mno-short-load-words
256 -msoft-float -mhard-float -mfpe
257 -mthumb-interwork -mno-thumb-interwork
258 -mcpu= -march= -mfpe=
259 -mstructure-size-boundary=
260 -mbsd -mxopen -mno-symrename
263 -mtpcs-frame -mno-tpcs-frame
264 -mtpcs-leaf-frame -mno-tpcs-leaf-frame
265 -mlittle-endian -mbig-endian
266 -mthumb-interwork -mno-thumb-interwork
267 -mstructure-size-boundary=
269 @emph{MN10200 Options}
272 @emph{MN10300 Options}
277 @emph{M32R/D Options}
278 -mcode-model=@var{model type} -msdata=@var{sdata type}
282 -m88000 -m88100 -m88110 -mbig-pic
283 -mcheck-zero-division -mhandle-large-shift
284 -midentify-revision -mno-check-zero-division
285 -mno-ocs-debug-info -mno-ocs-frame-position
286 -mno-optimize-arg-area -mno-serialize-volatile
287 -mno-underscores -mocs-debug-info
288 -mocs-frame-position -moptimize-arg-area
289 -mserialize-volatile -mshort-data-@var{num} -msvr3
290 -msvr4 -mtrap-large-shift -muse-div-instruction
291 -mversion-03.00 -mwarn-passed-structs
293 @emph{RS/6000 and PowerPC Options}
295 -mtune=@var{cpu type}
296 -mpower -mno-power -mpower2 -mno-power2
297 -mpowerpc -mno-powerpc
298 -mpowerpc-gpopt -mno-powerpc-gpopt
299 -mpowerpc-gfxopt -mno-powerpc-gfxopt
300 -mnew-mnemonics -mno-new-mnemonics
301 -mfull-toc -mminimal-toc -mno-fop-in-toc -mno-sum-in-toc
302 -maix64 -maix32 -mxl-call -mno-xl-call -mthreads -mpe
303 -msoft-float -mhard-float -mmultiple -mno-multiple
304 -mstring -mno-string -mupdate -mno-update
305 -mfused-madd -mno-fused-madd -mbit-align -mno-bit-align
306 -mstrict-align -mno-strict-align -mrelocatable
307 -mno-relocatable -mrelocatable-lib -mno-relocatable-lib
308 -mtoc -mno-toc -mlittle -mlittle-endian -mbig -mbig-endian
309 -mcall-aix -mcall-sysv -mprototype -mno-prototype
310 -msim -mmvme -mads -myellowknife -memb -msdata
311 -msdata=@var{opt} -G @var{num}
314 -mcall-lib-mul -mfp-arg-in-fpregs -mfp-arg-in-gregs
315 -mfull-fp-blocks -mhc-struct-return -min-line-mul
316 -mminimum-fp-blocks -mnohc-struct-return
319 -mabicalls -mcpu=@var{cpu type} -membedded-data
320 -membedded-pic -mfp32 -mfp64 -mgas -mgp32 -mgp64
321 -mgpopt -mhalf-pic -mhard-float -mint64 -mips1
322 -mips2 -mips3 -mips4 -mlong64 -mlong-calls -mmemcpy
323 -mmips-as -mmips-tfile -mno-abicalls
324 -mno-embedded-data -mno-embedded-pic
325 -mno-gpopt -mno-long-calls
326 -mno-memcpy -mno-mips-tfile -mno-rnames -mno-stats
327 -mrnames -msoft-float
328 -m4650 -msingle-float -mmad
329 -mstats -EL -EB -G @var{num} -nocpp
330 -mabi=32 -mabi=n32 -mabi=64 -mabi=eabi
334 -march=@var{cpu type}
335 -mieee-fp -mno-fancy-math-387
336 -mno-fp-ret-in-387 -msoft-float -msvr3-shlib
337 -mno-wide-multiply -mrtd -malign-double
338 -mreg-alloc=@var{list} -mregparm=@var{num}
339 -malign-jumps=@var{num} -malign-loops=@var{num}
340 -malign-functions=@var{num}
343 -mbig-switch -mdisable-fpregs -mdisable-indexing
344 -mfast-indirect-calls -mgas -mjump-in-delay
345 -mlong-load-store -mno-big-switch -mno-disable-fpregs
346 -mno-disable-indexing -mno-fast-indirect-calls -mno-gas
347 -mno-jump-in-delay -mno-long-load-store
348 -mno-portable-runtime -mno-soft-float -mno-space
349 -mno-space-regs -msoft-float -mpa-risc-1-0
350 -mpa-risc-1-1 -mportable-runtime
351 -mschedule=@var{list} -mspace -mspace-regs
353 @emph{Intel 960 Options}
354 -m@var{cpu type} -masm-compat -mclean-linkage
355 -mcode-align -mcomplex-addr -mleaf-procedures
356 -mic-compat -mic2.0-compat -mic3.0-compat
357 -mintel-asm -mno-clean-linkage -mno-code-align
358 -mno-complex-addr -mno-leaf-procedures
359 -mno-old-align -mno-strict-align -mno-tail-call
360 -mnumerics -mold-align -msoft-float -mstrict-align
363 @emph{DEC Alpha Options}
364 -mfp-regs -mno-fp-regs -mno-soft-float -msoft-float
366 -mieee -mieee-with-inexact -mieee-conformant
367 -mfp-trap-mode=@var{mode} -mfp-rounding-mode=@var{mode}
368 -mtrap-precision=@var{mode} -mbuild-constants
370 -mbwx -mno-bwx -mcix -mno-cix -mmax -mno-max
371 -mmemory-latency=@var{time}
373 @emph{Clipper Options}
376 @emph{H8/300 Options}
377 -mrelax -mh -ms -mint32 -malign-300
380 -m1 -m2 -m3 -m3e -mb -ml -mdalign -mrelax
382 @emph{System V Options}
383 -Qy -Qn -YP,@var{paths} -Ym,@var{dir}
387 -mmangle-cpu -mcpu=@var{cpu} -mtext=@var{text section}
388 -mdata=@var{data section} -mrodata=@var{readonly data section}
391 -mlong-calls -mno-long-calls -mep -mno-ep
392 -mprolog-function -mno-prolog-function -mspace
393 -mtda=@var{n} -msda=@var{n} -mzda=@var{n}
397 @item Code Generation Options
398 @xref{Code Gen Options,,Options for Code Generation Conventions}.
400 -fcall-saved-@var{reg} -fcall-used-@var{reg}
401 -fexceptions -ffixed-@var{reg} -finhibit-size-directive
402 -fcheck-memory-usage -fprefix-function-name
403 -fno-common -fno-ident -fno-gnu-linker
404 -fpcc-struct-return -fpic -fPIC
405 -freg-struct-return -fshared-data -fshort-enums
406 -fshort-double -fvolatile -fvolatile-global
407 -fverbose-asm -fpack-struct -fstack-check +e0 +e1
408 -fargument-alias -fargument-noalias
409 -fargument-noalias-global
414 * Overall Options:: Controlling the kind of output:
415 an executable, object files, assembler files,
416 or preprocessed source.
417 * C Dialect Options:: Controlling the variant of C language compiled.
418 * C++ Dialect Options:: Variations on C++.
419 * Warning Options:: How picky should the compiler be?
420 * Debugging Options:: Symbol tables, measurements, and debugging dumps.
421 * Optimize Options:: How much optimization?
422 * Preprocessor Options:: Controlling header files and macro definitions.
423 Also, getting dependency information for Make.
424 * Assembler Options:: Passing options to the assembler.
425 * Link Options:: Specifying libraries and so on.
426 * Directory Options:: Where to find header files and libraries.
427 Where to find the compiler executable files.
428 * Target Options:: Running a cross-compiler, or an old version of GNU CC.
431 @node Overall Options
432 @section Options Controlling the Kind of Output
434 Compilation can involve up to four stages: preprocessing, compilation
435 proper, assembly and linking, always in that order. The first three
436 stages apply to an individual source file, and end by producing an
437 object file; linking combines all the object files (those newly
438 compiled, and those specified as input) into an executable file.
440 @cindex file name suffix
441 For any given input file, the file name suffix determines what kind of
446 C source code which must be preprocessed.
449 C source code which should not be preprocessed.
452 C++ source code which should not be preprocessed.
455 Objective-C source code. Note that you must link with the library
456 @file{libobjc.a} to make an Objective-C program work.
459 C header file (not to be compiled or linked).
462 @itemx @var{file}.cxx
463 @itemx @var{file}.cpp
465 C++ source code which must be preprocessed. Note that in @samp{.cxx},
466 the last two letters must both be literally @samp{x}. Likewise,
467 @samp{.C} refers to a literal capital C.
473 Assembler code which must be preprocessed.
476 An object file to be fed straight into linking.
477 Any file name with no recognized suffix is treated this way.
480 You can specify the input language explicitly with the @samp{-x} option:
483 @item -x @var{language}
484 Specify explicitly the @var{language} for the following input files
485 (rather than letting the compiler choose a default based on the file
486 name suffix). This option applies to all following input files until
487 the next @samp{-x} option. Possible values for @var{language} are:
490 c-header cpp-output c++-cpp-output
491 assembler assembler-with-cpp
495 Turn off any specification of a language, so that subsequent files are
496 handled according to their file name suffixes (as they are if @samp{-x}
497 has not been used at all).
500 If you only want some of the stages of compilation, you can use
501 @samp{-x} (or filename suffixes) to tell @code{gcc} where to start, and
502 one of the options @samp{-c}, @samp{-S}, or @samp{-E} to say where
503 @code{gcc} is to stop. Note that some combinations (for example,
504 @samp{-x cpp-output -E} instruct @code{gcc} to do nothing at all.
508 Compile or assemble the source files, but do not link. The linking
509 stage simply is not done. The ultimate output is in the form of an
510 object file for each source file.
512 By default, the object file name for a source file is made by replacing
513 the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}.
515 Unrecognized input files, not requiring compilation or assembly, are
519 Stop after the stage of compilation proper; do not assemble. The output
520 is in the form of an assembler code file for each non-assembler input
523 By default, the assembler file name for a source file is made by
524 replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}.
526 Input files that don't require compilation are ignored.
529 Stop after the preprocessing stage; do not run the compiler proper. The
530 output is in the form of preprocessed source code, which is sent to the
533 Input files which don't require preprocessing are ignored.
535 @cindex output file option
537 Place output in file @var{file}. This applies regardless to whatever
538 sort of output is being produced, whether it be an executable file,
539 an object file, an assembler file or preprocessed C code.
541 Since only one output file can be specified, it does not make sense to
542 use @samp{-o} when compiling more than one input file, unless you are
543 producing an executable file as output.
545 If @samp{-o} is not specified, the default is to put an executable file
546 in @file{a.out}, the object file for @file{@var{source}.@var{suffix}} in
547 @file{@var{source}.o}, its assembler file in @file{@var{source}.s}, and
548 all preprocessed C source on standard output.@refill
551 Print (on standard error output) the commands executed to run the stages
552 of compilation. Also print the version number of the compiler driver
553 program and of the preprocessor and the compiler proper.
556 Use pipes rather than temporary files for communication between the
557 various stages of compilation. This fails to work on some systems where
558 the assembler is unable to read from a pipe; but the GNU assembler has
563 @section Compiling C++ Programs
565 @cindex suffixes for C++ source
566 @cindex C++ source file suffixes
567 C++ source files conventionally use one of the suffixes @samp{.C},
568 @samp{.cc}, @samp{cpp}, or @samp{.cxx}; preprocessed C++ files use the
569 suffix @samp{.ii}. GNU CC recognizes files with these names and
570 compiles them as C++ programs even if you call the compiler the same way
571 as for compiling C programs (usually with the name @code{gcc}).
575 However, C++ programs often require class libraries as well as a
576 compiler that understands the C++ language---and under some
577 circumstances, you might want to compile programs from standard input,
578 or otherwise without a suffix that flags them as C++ programs.
579 @code{g++} is a program that calls GNU CC with the default language
580 set to C++, and automatically specifies linking against the C++
582 @cindex @code{g++ 1.@var{xx}}
583 @cindex @code{g++}, separate compiler
584 @cindex @code{g++} older version
585 @footnote{Prior to release 2 of the compiler,
586 there was a separate @code{g++} compiler. That version was based on GNU
587 CC, but not integrated with it. Versions of @code{g++} with a
588 @samp{1.@var{xx}} version number---for example, @code{g++} version 1.37
589 or 1.42---are much less reliable than the versions integrated with GCC
590 2. Moreover, combining G++ @samp{1.@var{xx}} with a version 2 GCC will
591 simply not work.} On many systems, the script @code{g++} is also
592 installed with the name @code{c++}.
594 @cindex invoking @code{g++}
595 When you compile C++ programs, you may specify many of the same
596 command-line options that you use for compiling programs in any
597 language; or command-line options meaningful for C and related
598 languages; or options that are meaningful only for C++ programs.
599 @xref{C Dialect Options,,Options Controlling C Dialect}, for
600 explanations of options for languages related to C.
601 @xref{C++ Dialect Options,,Options Controlling C++ Dialect}, for
602 explanations of options that are meaningful only for C++ programs.
604 @node C Dialect Options
605 @section Options Controlling C Dialect
606 @cindex dialect options
607 @cindex language dialect options
608 @cindex options, dialect
610 The following options control the dialect of C (or languages derived
611 from C, such as C++ and Objective C) that the compiler accepts:
616 Support all ANSI standard C programs.
618 This turns off certain features of GNU C that are incompatible with ANSI
619 C, such as the @code{asm}, @code{inline} and @code{typeof} keywords, and
620 predefined macros such as @code{unix} and @code{vax} that identify the
621 type of system you are using. It also enables the undesirable and
622 rarely used ANSI trigraph feature, and it disables recognition of C++
623 style @samp{//} comments.
625 The alternate keywords @code{__asm__}, @code{__extension__},
626 @code{__inline__} and @code{__typeof__} continue to work despite
627 @samp{-ansi}. You would not want to use them in an ANSI C program, of
628 course, but it is useful to put them in header files that might be included
629 in compilations done with @samp{-ansi}. Alternate predefined macros
630 such as @code{__unix__} and @code{__vax__} are also available, with or
631 without @samp{-ansi}.
633 The @samp{-ansi} option does not cause non-ANSI programs to be
634 rejected gratuitously. For that, @samp{-pedantic} is required in
635 addition to @samp{-ansi}. @xref{Warning Options}.
637 The macro @code{__STRICT_ANSI__} is predefined when the @samp{-ansi}
638 option is used. Some header files may notice this macro and refrain
639 from declaring certain functions or defining certain macros that the
640 ANSI standard doesn't call for; this is to avoid interfering with any
641 programs that might use these names for other things.
643 The functions @code{alloca}, @code{abort}, @code{exit}, and
644 @code{_exit} are not builtin functions when @samp{-ansi} is used.
647 Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
648 keyword, so that code can use these words as identifiers. You can use
649 the keywords @code{__asm__}, @code{__inline__} and @code{__typeof__}
650 instead. @samp{-ansi} implies @samp{-fno-asm}.
652 In C++, this switch only affects the @code{typeof} keyword, since
653 @code{asm} and @code{inline} are standard keywords. You may want to
654 use the @samp{-fno-gnu-keywords} flag instead, as it also disables the
655 other, C++-specific, extension keywords such as @code{headof}.
658 @cindex builtin functions
674 Don't recognize builtin functions that do not begin with `__builtin_'
675 as prefix. Currently, the functions affected include @code{abort},
676 @code{abs}, @code{alloca}, @code{cos}, @code{exit}, @code{fabs},
677 @code{ffs}, @code{labs}, @code{memcmp}, @code{memcpy}, @code{sin},
678 @code{sqrt}, @code{strcmp}, @code{strcpy}, and @code{strlen}.
680 GCC normally generates special code to handle certain builtin functions
681 more efficiently; for instance, calls to @code{alloca} may become single
682 instructions that adjust the stack directly, and calls to @code{memcpy}
683 may become inline copy loops. The resulting code is often both smaller
684 and faster, but since the function calls no longer appear as such, you
685 cannot set a breakpoint on those calls, nor can you change the behavior
686 of the functions by linking with a different library.
688 The @samp{-ansi} option prevents @code{alloca} and @code{ffs} from being
689 builtin functions, since these functions do not have an ANSI standard
693 @cindex hosted environment
695 Assert that compilation takes place in a hosted environment. This implies
696 @samp{-fbuiltin}. A hosted environment is one in which the
697 entire standard library is available, and in which @code{main} has a return
698 type of @code{int}. Examples are nearly everything except a kernel.
699 This is equivalent to @samp{-fno-freestanding}.
702 @cindex hosted environment
704 Assert that compilation takes place in a freestanding environment. This
705 implies @samp{-fno-builtin}. A freestanding environment
706 is one in which the standard library may not exist, and program startup may
707 not necessarily be at @code{main}. The most obvious example is an OS kernel.
708 This is equivalent to @samp{-fno-hosted}.
711 Support ANSI C trigraphs. You don't want to know about this
712 brain-damage. The @samp{-ansi} option implies @samp{-trigraphs}.
714 @cindex traditional C language
715 @cindex C language, traditional
717 Attempt to support some aspects of traditional C compilers.
722 All @code{extern} declarations take effect globally even if they
723 are written inside of a function definition. This includes implicit
724 declarations of functions.
727 The newer keywords @code{typeof}, @code{inline}, @code{signed}, @code{const}
728 and @code{volatile} are not recognized. (You can still use the
729 alternative keywords such as @code{__typeof__}, @code{__inline__}, and
733 Comparisons between pointers and integers are always allowed.
736 Integer types @code{unsigned short} and @code{unsigned char} promote
737 to @code{unsigned int}.
740 Out-of-range floating point literals are not an error.
743 Certain constructs which ANSI regards as a single invalid preprocessing
744 number, such as @samp{0xe-0xd}, are treated as expressions instead.
747 String ``constants'' are not necessarily constant; they are stored in
748 writable space, and identical looking constants are allocated
749 separately. (This is the same as the effect of
750 @samp{-fwritable-strings}.)
752 @cindex @code{longjmp} and automatic variables
754 All automatic variables not declared @code{register} are preserved by
755 @code{longjmp}. Ordinarily, GNU C follows ANSI C: automatic variables
756 not declared @code{volatile} may be clobbered.
761 @cindex escape sequences, traditional
762 The character escape sequences @samp{\x} and @samp{\a} evaluate as the
763 literal characters @samp{x} and @samp{a} respectively. Without
764 @w{@samp{-traditional}}, @samp{\x} is a prefix for the hexadecimal
765 representation of a character, and @samp{\a} produces a bell.
768 In C++ programs, assignment to @code{this} is permitted with
769 @samp{-traditional}. (The option @samp{-fthis-is-variable} also has
773 You may wish to use @samp{-fno-builtin} as well as @samp{-traditional}
774 if your program uses names that are normally GNU C builtin functions for
775 other purposes of its own.
777 You cannot use @samp{-traditional} if you include any header files that
778 rely on ANSI C features. Some vendors are starting to ship systems with
779 ANSI C header files and you cannot use @samp{-traditional} on such
780 systems to compile files that include any system headers.
782 The @samp{-traditional} option also enables @samp{-traditional-cpp},
783 which is described next.
785 @item -traditional-cpp
786 Attempt to support some aspects of traditional C preprocessors.
791 Comments convert to nothing at all, rather than to a space. This allows
792 traditional token concatenation.
795 In a preprocessing directive, the @samp{#} symbol must appear as the first
799 Macro arguments are recognized within string constants in a macro
800 definition (and their values are stringified, though without additional
801 quote marks, when they appear in such a context). The preprocessor
802 always considers a string constant to end at a newline.
805 @cindex detecting @w{@samp{-traditional}}
806 The predefined macro @code{__STDC__} is not defined when you use
807 @samp{-traditional}, but @code{__GNUC__} is (since the GNU extensions
808 which @code{__GNUC__} indicates are not affected by
809 @samp{-traditional}). If you need to write header files that work
810 differently depending on whether @samp{-traditional} is in use, by
811 testing both of these predefined macros you can distinguish four
812 situations: GNU C, traditional GNU C, other ANSI C compilers, and other
813 old C compilers. The predefined macro @code{__STDC_VERSION__} is also
814 not defined when you use @samp{-traditional}. @xref{Standard
815 Predefined,,Standard Predefined Macros,cpp.info,The C Preprocessor},
816 for more discussion of these and other predefined macros.
819 @cindex string constants vs newline
820 @cindex newline vs string constants
821 The preprocessor considers a string constant to end at a newline (unless
822 the newline is escaped with @samp{\}). (Without @w{@samp{-traditional}},
823 string constants can contain the newline character as typed.)
826 @item -fcond-mismatch
827 Allow conditional expressions with mismatched types in the second and
828 third arguments. The value of such an expression is void.
830 @item -funsigned-char
831 Let the type @code{char} be unsigned, like @code{unsigned char}.
833 Each kind of machine has a default for what @code{char} should
834 be. It is either like @code{unsigned char} by default or like
835 @code{signed char} by default.
837 Ideally, a portable program should always use @code{signed char} or
838 @code{unsigned char} when it depends on the signedness of an object.
839 But many programs have been written to use plain @code{char} and
840 expect it to be signed, or expect it to be unsigned, depending on the
841 machines they were written for. This option, and its inverse, let you
842 make such a program work with the opposite default.
844 The type @code{char} is always a distinct type from each of
845 @code{signed char} or @code{unsigned char}, even though its behavior
846 is always just like one of those two.
849 Let the type @code{char} be signed, like @code{signed char}.
851 Note that this is equivalent to @samp{-fno-unsigned-char}, which is
852 the negative form of @samp{-funsigned-char}. Likewise, the option
853 @samp{-fno-signed-char} is equivalent to @samp{-funsigned-char}.
855 You may wish to use @samp{-fno-builtin} as well as @samp{-traditional}
856 if your program uses names that are normally GNU C builtin functions for
857 other purposes of its own.
859 You cannot use @samp{-traditional} if you include any header files that
860 rely on ANSI C features. Some vendors are starting to ship systems with
861 ANSI C header files and you cannot use @samp{-traditional} on such
862 systems to compile files that include any system headers.
864 @item -fsigned-bitfields
865 @itemx -funsigned-bitfields
866 @itemx -fno-signed-bitfields
867 @itemx -fno-unsigned-bitfields
868 These options control whether a bitfield is signed or unsigned, when the
869 declaration does not use either @code{signed} or @code{unsigned}. By
870 default, such a bitfield is signed, because this is consistent: the
871 basic integer types such as @code{int} are signed types.
873 However, when @samp{-traditional} is used, bitfields are all unsigned
876 @item -fwritable-strings
877 Store string constants in the writable data segment and don't uniquize
878 them. This is for compatibility with old programs which assume they can
879 write into string constants. The option @samp{-traditional} also has
882 Writing into string constants is a very bad idea; ``constants'' should
885 @item -fallow-single-precision
886 Do not promote single precision math operations to double precision,
887 even when compiling with @samp{-traditional}.
889 Traditional K&R C promotes all floating point operations to double
890 precision, regardless of the sizes of the operands. On the
891 architecture for which you are compiling, single precision may be faster
892 than double precision. If you must use @samp{-traditional}, but want
893 to use single precision operations when the operands are single
894 precision, use this option. This option has no effect when compiling
895 with ANSI or GNU C conventions (the default).
899 @node C++ Dialect Options
900 @section Options Controlling C++ Dialect
902 @cindex compiler options, C++
903 @cindex C++ options, command line
905 This section describes the command-line options that are only meaningful
906 for C++ programs; but you can also use most of the GNU compiler options
907 regardless of what language your program is in. For example, you
908 might compile a file @code{firstClass.C} like this:
911 g++ -g -felide-constructors -O -c firstClass.C
915 In this example, only @samp{-felide-constructors} is an option meant
916 only for C++ programs; you can use the other options with any
917 language supported by GNU CC.
919 Here is a list of options that are @emph{only} for compiling C++ programs:
922 @item -fno-access-control
923 Turn off all access checking. This switch is mainly useful for working
924 around bugs in the access control code.
927 Treat all possible member functions as virtual, implicitly.
928 All member functions (except for constructor functions and @code{new} or
929 @code{delete} member operators) are treated as virtual functions of the
930 class where they appear.
932 This does not mean that all calls to these member functions will be made
933 through the internal table of virtual functions. Under some
934 circumstances, the compiler can determine that a call to a given virtual
935 function can be made directly; in these cases the calls are direct in
939 Check that the pointer returned by @code{operator new} is non-null
940 before attempting to modify the storage allocated. The current Working
941 Paper requires that @code{operator new} never return a null pointer, so
942 this check is normally unnecessary.
944 @item -fconserve-space
945 Put uninitialized or runtime-initialized global variables into the
946 common segment, as C does. This saves space in the executable at the
947 cost of not diagnosing duplicate definitions. If you compile with this
948 flag and your program mysteriously crashes after @code{main()} has
949 completed, you may have an object that is being destroyed twice because
950 two definitions were merged.
952 @item -fdollars-in-identifiers
953 Accept @samp{$} in identifiers. You can also explicitly prohibit use of
954 @samp{$} with the option @samp{-fno-dollars-in-identifiers}. (GNU C allows
955 @samp{$} by default on most target systems, but there are a few exceptions.)
956 Traditional C allowed the character @samp{$} to form part of
957 identifiers. However, ANSI C and C++ forbid @samp{$} in identifiers.
959 @item -fenum-int-equiv
960 Anachronistically permit implicit conversion of @code{int} to
961 enumeration types. Current C++ allows conversion of @code{enum} to
962 @code{int}, but not the other way around.
964 @item -fexternal-templates
965 Cause template instantiations to obey @samp{#pragma interface} and
966 @samp{implementation}; template instances are emitted or not according
967 to the location of the template definition. @xref{Template
968 Instantiation}, for more information.
970 This option is deprecated.
972 @item -falt-external-templates
973 Similar to -fexternal-templates, but template instances are emitted or
974 not according to the place where they are first instantiated.
975 @xref{Template Instantiation}, for more information.
977 This option is deprecated.
980 @itemx -fno-for-scope
981 If -ffor-scope is specified, the scope of variables declared in
982 a @i{for-init-statement} is limited to the @samp{for} loop itself,
983 as specified by the draft C++ standard.
984 If -fno-for-scope is specified, the scope of variables declared in
985 a @i{for-init-statement} extends to the end of the enclosing scope,
986 as was the case in old versions of gcc, and other (traditional)
987 implementations of C++.
989 The default if neither flag is given to follow the standard,
990 but to allow and give a warning for old-style code that would
991 otherwise be invalid, or have different behavior.
993 @item -fno-gnu-keywords
994 Do not recognize @code{classof}, @code{headof}, @code{signature},
995 @code{sigof} or @code{typeof} as a keyword, so that code can use these
996 words as identifiers. You can use the keywords @code{__classof__},
997 @code{__headof__}, @code{__signature__}, @code{__sigof__}, and
998 @code{__typeof__} instead. @samp{-ansi} implies
999 @samp{-fno-gnu-keywords}.
1001 @item -fguiding-decls
1002 Treat a function declaration with the same type as a potential function
1003 template instantiation as though it declares that instantiation, not a
1004 normal function. If a definition is given for the function later in the
1005 translation unit (or another translation unit if the target supports
1006 weak symbols), that definition will be used; otherwise the template will
1007 be instantiated. This behavior reflects the C++ language prior to
1008 September 1996, when guiding declarations were removed.
1010 This option implies @samp{-fname-mangling-version-0}, and will not work
1011 with other name mangling versions.
1013 @item -fno-implicit-templates
1014 Never emit code for templates which are instantiated implicitly (i.e. by
1015 use); only emit code for explicit instantiations. @xref{Template
1016 Instantiation}, for more information.
1018 @item -fhandle-signatures
1019 Recognize the @code{signature} and @code{sigof} keywords for specifying
1020 abstract types. The default (@samp{-fno-handle-signatures}) is not to
1021 recognize them. @xref{C++ Signatures, Type Abstraction using
1024 @item -fhuge-objects
1025 Support virtual function calls for objects that exceed the size
1026 representable by a @samp{short int}. Users should not use this flag by
1027 default; if you need to use it, the compiler will tell you so. If you
1028 compile any of your code with this flag, you must compile @emph{all} of
1029 your code with this flag (including the C++ library, if you use it).
1031 This flag is not useful when compiling with -fvtable-thunks.
1033 @item -finit-priority
1034 Support @samp{__attribute__ ((init_priority (n)))} for controlling the
1035 order of initialization of file-scope objects. On ELF targets, this
1036 requires GNU ld 2.10 or later.
1038 @item -fno-implement-inlines
1039 To save space, do not emit out-of-line copies of inline functions
1040 controlled by @samp{#pragma implementation}. This will cause linker
1041 errors if these functions are not inlined everywhere they are called.
1043 @item -fmemoize-lookups
1044 @itemx -fsave-memoized
1045 Use heuristics to compile faster. These heuristics are not enabled by
1046 default, since they are only effective for certain input files. Other
1047 input files compile more slowly.
1049 The first time the compiler must build a call to a member function (or
1050 reference to a data member), it must (1) determine whether the class
1051 implements member functions of that name; (2) resolve which member
1052 function to call (which involves figuring out what sorts of type
1053 conversions need to be made); and (3) check the visibility of the member
1054 function to the caller. All of this adds up to slower compilation.
1055 Normally, the second time a call is made to that member function (or
1056 reference to that data member), it must go through the same lengthy
1057 process again. This means that code like this:
1060 cout << "This " << p << " has " << n << " legs.\n";
1064 makes six passes through all three steps. By using a software cache, a
1065 ``hit'' significantly reduces this cost. Unfortunately, using the cache
1066 introduces another layer of mechanisms which must be implemented, and so
1067 incurs its own overhead. @samp{-fmemoize-lookups} enables the software
1070 Because access privileges (visibility) to members and member functions
1071 may differ from one function context to the next, G++ may need to flush
1072 the cache. With the @samp{-fmemoize-lookups} flag, the cache is flushed
1073 after every function that is compiled. The @samp{-fsave-memoized} flag
1074 enables the same software cache, but when the compiler determines that
1075 the context of the last function compiled would yield the same access
1076 privileges of the next function to compile, it preserves the cache.
1077 This is most helpful when defining many member functions for the same
1078 class: with the exception of member functions which are friends of other
1079 classes, each member function has exactly the same access privileges as
1080 every other, and the cache need not be flushed.
1082 The code that implements these flags has rotted; you should probably
1085 @item -fstrict-prototype
1086 Within an @samp{extern "C"} linkage specification, treat a function
1087 declaration with no arguments, such as @samp{int foo ();}, as declaring
1088 the function to take no arguments. Normally, such a declaration means
1089 that the function @code{foo} can take any combination of arguments, as
1090 in C. @samp{-pedantic} implies @samp{-fstrict-prototype} unless
1091 overridden with @samp{-fno-strict-prototype}.
1093 This flag no longer affects declarations with C++ linkage.
1095 @item -fname-mangling-version-@var{n}
1096 Control the way in which names are mangled. Version 0 is compatible
1097 with versions of g++ before 2.8. Version 1 is the default. Version 1
1098 will allow correct mangling of function templates. For example,
1099 version 0 mangling does not mangle foo<int, double> and foo<int, char>
1100 given this declaration:
1103 template <class T, class U> void foo(T t);
1106 @item -fno-nonnull-objects
1107 Don't assume that a reference is initialized to refer to a valid object.
1108 Although the current C++ Working Paper prohibits null references, some
1109 old code may rely on them, and you can use @samp{-fno-nonnull-objects}
1110 to turn on checking.
1112 At the moment, the compiler only does this checking for conversions to
1113 virtual base classes.
1115 @item -foperator-names
1116 Recognize the operator name keywords @code{and}, @code{bitand},
1117 @code{bitor}, @code{compl}, @code{not}, @code{or} and @code{xor} as
1118 synonyms for the symbols they refer to. @samp{-ansi} implies
1119 @samp{-foperator-names}.
1121 @item -fno-optional-diags
1122 Disable diagnostics that the standard says a compiler does not need to
1123 issue. Currently, this means the diagnostic for a name having multiple
1124 meanings within a class.
1127 Enable automatic template instantiation. This option also implies
1128 @samp{-fno-implicit-templates}. @xref{Template Instantiation}, for more
1132 @itemx -fno-squangle
1133 @samp{-fsquangle} will enable a compressed form of name mangling for
1134 identifiers. In particular, it helps to shorten very long names by recognizing
1135 types and class names which occur more than once, replacing them with special
1136 short ID codes. This option also requires any C++ libraries being used to
1137 be compiled with this option as well. The compiler has this disabled (the
1138 equivalent of @samp{-fno-squangle}) by default.
1140 @item -fthis-is-variable
1141 Permit assignment to @code{this}. The incorporation of user-defined
1142 free store management into C++ has made assignment to @samp{this} an
1143 anachronism. Therefore, by default it is invalid to assign to
1144 @code{this} within a class member function; that is, GNU C++ treats
1145 @samp{this} in a member function of class @code{X} as a non-lvalue of
1146 type @samp{X *}. However, for backwards compatibility, you can make it
1147 valid with @samp{-fthis-is-variable}.
1149 @item -fvtable-thunks
1150 Use @samp{thunks} to implement the virtual function dispatch table
1151 (@samp{vtable}). The traditional (cfront-style) approach to
1152 implementing vtables was to store a pointer to the function and two
1153 offsets for adjusting the @samp{this} pointer at the call site. Newer
1154 implementations store a single pointer to a @samp{thunk} function which
1155 does any necessary adjustment and then calls the target function.
1157 This option also enables a heuristic for controlling emission of
1158 vtables; if a class has any non-inline virtual functions, the vtable
1159 will be emitted in the translation unit containing the first one of
1162 @item -ftemplate-depth-@var{n}
1163 Set the maximum instantiation depth for template classes to @var{n}.
1164 A limit on the template instantiation depth is needed to detect
1165 endless recursions during template class instantiation. ANSI/ISO C++
1166 conforming programs must not rely on a maximum depth greater than 17.
1169 Do not search for header files in the standard directories specific to
1170 C++, but do still search the other standard directories. (This option
1171 is used when building the C++ library.)
1174 For C++ programs (in addition to the effects that apply to both C and
1175 C++), this has the same effect as @samp{-fthis-is-variable}.
1176 @xref{C Dialect Options,, Options Controlling C Dialect}.
1179 In addition, these optimization, warning, and code generation options
1180 have meanings only for C++ programs:
1183 @item -fno-default-inline
1184 Do not assume @samp{inline} for functions defined inside a class scope.
1185 @xref{Optimize Options,,Options That Control Optimization}.
1187 @item -Wold-style-cast
1188 @itemx -Woverloaded-virtual
1189 @itemx -Wtemplate-debugging
1190 Warnings that apply only to C++ programs. @xref{Warning
1191 Options,,Options to Request or Suppress Warnings}.
1194 Warn about violation of some style rules from Effective C++ by Scott Myers.
1197 Control how virtual function definitions are used, in a fashion
1198 compatible with @code{cfront} 1.x. @xref{Code Gen Options,,Options for
1199 Code Generation Conventions}.
1202 @node Warning Options
1203 @section Options to Request or Suppress Warnings
1204 @cindex options to control warnings
1205 @cindex warning messages
1206 @cindex messages, warning
1207 @cindex suppressing warnings
1209 Warnings are diagnostic messages that report constructions which
1210 are not inherently erroneous but which are risky or suggest there
1211 may have been an error.
1213 You can request many specific warnings with options beginning @samp{-W},
1214 for example @samp{-Wimplicit} to request warnings on implicit
1215 declarations. Each of these specific warning options also has a
1216 negative form beginning @samp{-Wno-} to turn off warnings;
1217 for example, @samp{-Wno-implicit}. This manual lists only one of the
1218 two forms, whichever is not the default.
1220 These options control the amount and kinds of warnings produced by GNU
1224 @cindex syntax checking
1226 Check the code for syntax errors, but don't do anything beyond that.
1229 Issue all the warnings demanded by strict ANSI C and ISO C++;
1230 reject all programs that use forbidden extensions.
1232 Valid ANSI C and ISO C++ programs should compile properly with or without
1233 this option (though a rare few will require @samp{-ansi}). However,
1234 without this option, certain GNU extensions and traditional C and C++
1235 features are supported as well. With this option, they are rejected.
1237 @samp{-pedantic} does not cause warning messages for use of the
1238 alternate keywords whose names begin and end with @samp{__}. Pedantic
1239 warnings are also disabled in the expression that follows
1240 @code{__extension__}. However, only system header files should use
1241 these escape routes; application programs should avoid them.
1242 @xref{Alternate Keywords}.
1244 This option is not intended to be @i{useful}; it exists only to satisfy
1245 pedants who would otherwise claim that GNU CC fails to support the ANSI
1248 Some users try to use @samp{-pedantic} to check programs for strict ANSI
1249 C conformance. They soon find that it does not do quite what they want:
1250 it finds some non-ANSI practices, but not all---only those for which
1251 ANSI C @emph{requires} a diagnostic.
1253 A feature to report any failure to conform to ANSI C might be useful in
1254 some instances, but would require considerable additional work and would
1255 be quite different from @samp{-pedantic}. We recommend, rather, that
1256 users take advantage of the extensions of GNU C and disregard the
1257 limitations of other compilers. Aside from certain supercomputers and
1258 obsolete small machines, there is less and less reason ever to use any
1259 other C compiler other than for bootstrapping GNU CC.
1261 @item -pedantic-errors
1262 Like @samp{-pedantic}, except that errors are produced rather than
1266 Inhibit all warning messages.
1269 Inhibit warning messages about the use of @samp{#import}.
1271 @item -Wchar-subscripts
1272 Warn if an array subscript has type @code{char}. This is a common cause
1273 of error, as programmers often forget that this type is signed on some
1277 Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
1278 comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
1281 Check calls to @code{printf} and @code{scanf}, etc., to make sure that
1282 the arguments supplied have types appropriate to the format string
1285 @item -Wimplicit-int
1286 Warn when a declaration does not specify a type.
1288 @item -Wimplicit-function-declaration
1289 @itemx -Werror-implicit-function-declaration
1290 Give a warning (or error) whenever a function is used before being
1294 Same as @samp{-Wimplicit-int} and @samp{-Wimplicit-function-}@*
1298 Warn if the type of @samp{main} is suspicious. @samp{main} should be a
1299 function with external linkage, returning int, taking either zero
1300 arguments, two, or three arguments of appropriate types.
1303 Warn if a multicharacter constant (@samp{'FOOF'}) is used. Usually they
1304 indicate a typo in the user's code, as they have implementation-defined
1305 values, and should not be used in portable code.
1308 Warn if parentheses are omitted in certain contexts, such
1309 as when there is an assignment in a context where a truth value
1310 is expected, or when operators are nested whose precedence people
1311 often get confused about.
1313 Also warn about constructions where there may be confusion to which
1314 @code{if} statement an @code{else} branch belongs. Here is an example of
1327 In C, every @code{else} branch belongs to the innermost possible @code{if}
1328 statement, which in this example is @code{if (b)}. This is often not
1329 what the programmer expected, as illustrated in the above example by
1330 indentation the programmer chose. When there is the potential for this
1331 confusion, GNU C will issue a warning when this flag is specified.
1332 To eliminate the warning, add explicit braces around the innermost
1333 @code{if} statement so there is no way the @code{else} could belong to
1334 the enclosing @code{if}. The resulting code would look like this:
1349 Warn whenever a function is defined with a return-type that defaults
1350 to @code{int}. Also warn about any @code{return} statement with no
1351 return-value in a function whose return-type is not @code{void}.
1354 Warn whenever a @code{switch} statement has an index of enumeral type
1355 and lacks a @code{case} for one or more of the named codes of that
1356 enumeration. (The presence of a @code{default} label prevents this
1357 warning.) @code{case} labels outside the enumeration range also
1358 provoke warnings when this option is used.
1361 Warn if any trigraphs are encountered (assuming they are enabled).
1364 Warn whenever a variable is unused aside from its declaration,
1365 whenever a function is declared static but never defined, whenever a
1366 label is declared but not used, and whenever a statement computes a
1367 result that is explicitly not used.
1369 In order to get a warning about an unused function parameter, you must
1370 specify both @samp{-W} and @samp{-Wunused}.
1372 To suppress this warning for an expression, simply cast it to void. For
1373 unused variables and parameters, use the @samp{unused} attribute
1374 (@pxref{Variable Attributes}).
1376 @item -Wuninitialized
1377 An automatic variable is used without first being initialized.
1379 These warnings are possible only in optimizing compilation,
1380 because they require data flow information that is computed only
1381 when optimizing. If you don't specify @samp{-O}, you simply won't
1384 These warnings occur only for variables that are candidates for
1385 register allocation. Therefore, they do not occur for a variable that
1386 is declared @code{volatile}, or whose address is taken, or whose size
1387 is other than 1, 2, 4 or 8 bytes. Also, they do not occur for
1388 structures, unions or arrays, even when they are in registers.
1390 Note that there may be no warning about a variable that is used only
1391 to compute a value that itself is never used, because such
1392 computations may be deleted by data flow analysis before the warnings
1395 These warnings are made optional because GNU CC is not smart
1396 enough to see all the reasons why the code might be correct
1397 despite appearing to have an error. Here is one example of how
1416 If the value of @code{y} is always 1, 2 or 3, then @code{x} is
1417 always initialized, but GNU CC doesn't know this. Here is
1418 another common case:
1423 if (change_y) save_y = y, y = new_y;
1425 if (change_y) y = save_y;
1430 This has no bug because @code{save_y} is used only if it is set.
1432 Some spurious warnings can be avoided if you declare all the functions
1433 you use that never return as @code{noreturn}. @xref{Function
1436 @item -Wreorder (C++ only)
1437 @cindex reordering, warning
1438 @cindex warning for reordering of member initializers
1439 Warn when the order of member initializers given in the code does not
1440 match the order in which they must be executed. For instance:
1446 A(): j (0), i (1) @{ @}
1450 Here the compiler will warn that the member initializers for @samp{i}
1451 and @samp{j} will be rearranged to match the declaration order of the
1454 @item -Wtemplate-debugging
1455 @cindex template debugging
1456 When using templates in a C++ program, warn if debugging is not yet
1457 fully available (C++ only).
1459 @item -Wunknown-pragmas
1460 @cindex warning for unknown pragmas
1461 @cindex unknown pragmas, warning
1462 @cindex pragmas, warning of unknown
1463 Warn when a #pragma directive is encountered which is not understood by
1464 GCC. If this command line option is used, warnings will even be issued
1465 for unknown pragmas in system header files. This is not the case if
1466 the warnings were only enabled by the @samp{-Wall} command line option.
1469 All of the above @samp{-W} options combined. This enables all the
1470 warnings about constructions that some users consider questionable, and
1471 that are easy to avoid (or modify to prevent the warning), even in
1472 conjunction with macros.
1475 The following @samp{-W@dots{}} options are not implied by @samp{-Wall}.
1476 Some of them warn about constructions that users generally do not
1477 consider questionable, but which occasionally you might wish to check
1478 for; others warn about constructions that are necessary or hard to avoid
1479 in some cases, and there is no simple way to modify the code to suppress
1484 Print extra warning messages for these events:
1487 @cindex @code{longjmp} warnings
1489 A nonvolatile automatic variable might be changed by a call to
1490 @code{longjmp}. These warnings as well are possible only in
1491 optimizing compilation.
1493 The compiler sees only the calls to @code{setjmp}. It cannot know
1494 where @code{longjmp} will be called; in fact, a signal handler could
1495 call it at any point in the code. As a result, you may get a warning
1496 even when there is in fact no problem because @code{longjmp} cannot
1497 in fact be called at the place which would cause a problem.
1500 A function can return either with or without a value. (Falling
1501 off the end of the function body is considered returning without
1502 a value.) For example, this function would evoke such a
1516 An expression-statement or the left-hand side of a comma expression
1517 contains no side effects.
1518 To suppress the warning, cast the unused expression to void.
1519 For example, an expression such as @samp{x[i,j]} will cause a warning,
1520 but @samp{x[(void)i,j]} will not.
1523 An unsigned value is compared against zero with @samp{<} or @samp{<=}.
1526 A comparison like @samp{x<=y<=z} appears; this is equivalent to
1527 @samp{(x<=y ? 1 : 0) <= z}, which is a different interpretation from
1528 that of ordinary mathematical notation.
1531 Storage-class specifiers like @code{static} are not the first things in
1532 a declaration. According to the C Standard, this usage is obsolescent.
1535 If @samp{-Wall} or @samp{-Wunused} is also specified, warn about unused
1539 A comparison between signed and unsigned values could produce an
1540 incorrect result when the signed value is converted to unsigned.
1541 (But don't warn if @samp{-Wno-sign-compare} is also specified.)
1544 An aggregate has a partly bracketed initializer.
1545 For example, the following code would evoke such a warning,
1546 because braces are missing around the initializer for @code{x.h}:
1549 struct s @{ int f, g; @};
1550 struct t @{ struct s h; int i; @};
1551 struct t x = @{ 1, 2, 3 @};
1555 An aggregate has an initializer which does not initialize all members.
1556 For example, the following code would cause such a warning, because
1557 @code{x.h} would be implicitly initialized to zero:
1560 struct s @{ int f, g, h; @};
1561 struct s x = @{ 3, 4 @};
1566 Warn about certain constructs that behave differently in traditional and
1571 Macro arguments occurring within string constants in the macro body.
1572 These would substitute the argument in traditional C, but are part of
1573 the constant in ANSI C.
1576 A function declared external in one block and then used after the end of
1580 A @code{switch} statement has an operand of type @code{long}.
1584 Warn if an undefined identifier is evaluated in an @samp{#if} directive.
1587 Warn whenever a local variable shadows another local variable.
1589 @item -Wid-clash-@var{len}
1590 Warn whenever two distinct identifiers match in the first @var{len}
1591 characters. This may help you prepare a program that will compile
1592 with certain obsolete, brain-damaged compilers.
1594 @item -Wlarger-than-@var{len}
1595 Warn whenever an object of larger than @var{len} bytes is defined.
1597 @item -Wpointer-arith
1598 Warn about anything that depends on the ``size of'' a function type or
1599 of @code{void}. GNU C assigns these types a size of 1, for
1600 convenience in calculations with @code{void *} pointers and pointers
1603 @item -Wbad-function-cast
1604 Warn whenever a function call is cast to a non-matching type.
1605 For example, warn if @code{int malloc()} is cast to @code{anything *}.
1608 Warn whenever a pointer is cast so as to remove a type qualifier from
1609 the target type. For example, warn if a @code{const char *} is cast
1610 to an ordinary @code{char *}.
1613 Warn whenever a pointer is cast such that the required alignment of the
1614 target is increased. For example, warn if a @code{char *} is cast to
1615 an @code{int *} on machines where integers can only be accessed at
1616 two- or four-byte boundaries.
1618 @item -Wwrite-strings
1619 Give string constants the type @code{const char[@var{length}]} so that
1620 copying the address of one into a non-@code{const} @code{char *}
1621 pointer will get a warning. These warnings will help you find at
1622 compile time code that can try to write into a string constant, but
1623 only if you have been very careful about using @code{const} in
1624 declarations and prototypes. Otherwise, it will just be a nuisance;
1625 this is why we did not make @samp{-Wall} request these warnings.
1628 Warn if a prototype causes a type conversion that is different from what
1629 would happen to the same argument in the absence of a prototype. This
1630 includes conversions of fixed point to floating and vice versa, and
1631 conversions changing the width or signedness of a fixed point argument
1632 except when the same as the default promotion.
1634 Also, warn if a negative integer constant expression is implicitly
1635 converted to an unsigned type. For example, warn about the assignment
1636 @code{x = -1} if @code{x} is unsigned. But do not warn about explicit
1637 casts like @code{(unsigned) -1}.
1639 @item -Wsign-compare
1640 @cindex warning for comparison of signed and unsigned values
1641 @cindex comparison of signed and unsigned values, warning
1642 @cindex signed and unsigned values, comparison warning
1643 Warn when a comparison between signed and unsigned values could produce
1644 an incorrect result when the signed value is converted to unsigned.
1645 This warning is also enabled by @samp{-W}; to get the other warnings
1646 of @samp{-W} without this warning, use @samp{-W -Wno-sign-compare}.
1648 @item -Waggregate-return
1649 Warn if any functions that return structures or unions are defined or
1650 called. (In languages where you can return an array, this also elicits
1653 @item -Wstrict-prototypes
1654 Warn if a function is declared or defined without specifying the
1655 argument types. (An old-style function definition is permitted without
1656 a warning if preceded by a declaration which specifies the argument
1659 @item -Wmissing-prototypes
1660 Warn if a global function is defined without a previous prototype
1661 declaration. This warning is issued even if the definition itself
1662 provides a prototype. The aim is to detect global functions that fail
1663 to be declared in header files.
1665 @item -Wmissing-declarations
1666 Warn if a global function is defined without a previous declaration.
1667 Do so even if the definition itself provides a prototype.
1668 Use this option to detect global functions that are not declared in
1671 @item -Wredundant-decls
1672 Warn if anything is declared more than once in the same scope, even in
1673 cases where multiple declaration is valid and changes nothing.
1675 @item -Wnested-externs
1676 Warn if an @code{extern} declaration is encountered within an function.
1679 Warn if a function can not be inlined, and either it was declared as inline,
1680 or else the @samp{-finline-functions} option was given.
1682 @item -Wold-style-cast
1683 Warn if an old-style (C-style) cast is used within a program.
1685 @item -Woverloaded-virtual
1686 @cindex overloaded virtual fn, warning
1687 @cindex warning for overloaded virtual fn
1688 Warn when a derived class function declaration may be an error in
1689 defining a virtual function (C++ only). In a derived class, the
1690 definitions of virtual functions must match the type signature of a
1691 virtual function declared in the base class. With this option, the
1692 compiler warns when you define a function with the same name as a
1693 virtual function, but with a type signature that does not match any
1694 declarations from the base class.
1696 @item -Wsynth (C++ only)
1697 @cindex warning for synthesized methods
1698 @cindex synthesized methods, warning
1699 Warn when g++'s synthesis behavior does not match that of cfront. For
1705 A& operator = (int);
1715 In this example, g++ will synthesize a default @samp{A& operator =
1716 (const A&);}, while cfront will use the user-defined @samp{operator =}.
1719 Warn if @samp{long long} type is used. This is default. To inhibit
1720 the warning messages, use @samp{-Wno-long-long}. Flags
1721 @samp{-Wlong-long} and @samp{-Wno-long-long} are taken into account
1722 only when @samp{-pedantic} flag is used.
1725 Make all warnings into errors.
1728 @node Debugging Options
1729 @section Options for Debugging Your Program or GNU CC
1730 @cindex options, debugging
1731 @cindex debugging information options
1733 GNU CC has various special options that are used for debugging
1734 either your program or GCC:
1738 Produce debugging information in the operating system's native format
1739 (stabs, COFF, XCOFF, or DWARF). GDB can work with this debugging
1742 On most systems that use stabs format, @samp{-g} enables use of extra
1743 debugging information that only GDB can use; this extra information
1744 makes debugging work better in GDB but will probably make other debuggers
1746 refuse to read the program. If you want to control for certain whether
1747 to generate the extra information, use @samp{-gstabs+}, @samp{-gstabs},
1748 @samp{-gxcoff+}, @samp{-gxcoff}, @samp{-gdwarf-1+}, or @samp{-gdwarf-1}
1751 Unlike most other C compilers, GNU CC allows you to use @samp{-g} with
1752 @samp{-O}. The shortcuts taken by optimized code may occasionally
1753 produce surprising results: some variables you declared may not exist
1754 at all; flow of control may briefly move where you did not expect it;
1755 some statements may not be executed because they compute constant
1756 results or their values were already at hand; some statements may
1757 execute in different places because they were moved out of loops.
1759 Nevertheless it proves possible to debug optimized output. This makes
1760 it reasonable to use the optimizer for programs that might have bugs.
1762 The following options are useful when GNU CC is generated with the
1763 capability for more than one debugging format.
1766 Produce debugging information for use by GDB. This means to use the
1767 most expressive format available (DWARF 2, stabs, or the native format
1768 if neither of those are supported), including GDB extensions if at all
1772 Produce debugging information in stabs format (if that is supported),
1773 without GDB extensions. This is the format used by DBX on most BSD
1774 systems. On MIPS, Alpha and System V Release 4 systems this option
1775 produces stabs debugging output which is not understood by DBX or SDB.
1776 On System V Release 4 systems this option requires the GNU assembler.
1779 Produce debugging information in stabs format (if that is supported),
1780 using GNU extensions understood only by the GNU debugger (GDB). The
1781 use of these extensions is likely to make other debuggers crash or
1782 refuse to read the program.
1785 Produce debugging information in COFF format (if that is supported).
1786 This is the format used by SDB on most System V systems prior to
1790 Produce debugging information in XCOFF format (if that is supported).
1791 This is the format used by the DBX debugger on IBM RS/6000 systems.
1794 Produce debugging information in XCOFF format (if that is supported),
1795 using GNU extensions understood only by the GNU debugger (GDB). The
1796 use of these extensions is likely to make other debuggers crash or
1797 refuse to read the program, and may cause assemblers other than the GNU
1798 assembler (GAS) to fail with an error.
1801 Produce debugging information in DWARF version 1 format (if that is
1802 supported). This is the format used by SDB on most System V Release 4
1806 Produce debugging information in DWARF version 1 format (if that is
1807 supported), using GNU extensions understood only by the GNU debugger
1808 (GDB). The use of these extensions is likely to make other debuggers
1809 crash or refuse to read the program.
1812 Produce debugging information in DWARF version 2 format (if that is
1813 supported). This is the format used by DBX on IRIX 6.
1816 @itemx -ggdb@var{level}
1817 @itemx -gstabs@var{level}
1818 @itemx -gcoff@var{level}
1819 @itemx -gxcoff@var{level}
1820 @itemx -gdwarf@var{level}
1821 @itemx -gdwarf-2@var{level}
1822 Request debugging information and also use @var{level} to specify how
1823 much information. The default level is 2.
1825 Level 1 produces minimal information, enough for making backtraces in
1826 parts of the program that you don't plan to debug. This includes
1827 descriptions of functions and external variables, but no information
1828 about local variables and no line numbers.
1830 Level 3 includes extra information, such as all the macro definitions
1831 present in the program. Some debuggers support macro expansion when
1836 Generate extra code to write profile information suitable for the
1837 analysis program @code{prof}. You must use this option when compiling
1838 the source files you want data about, and you must also use it when
1841 @cindex @code{gprof}
1843 Generate extra code to write profile information suitable for the
1844 analysis program @code{gprof}. You must use this option when compiling
1845 the source files you want data about, and you must also use it when
1850 Generate extra code to write profile information for basic blocks, which will
1851 record the number of times each basic block is executed, the basic block start
1852 address, and the function name containing the basic block. If @samp{-g} is
1853 used, the line number and filename of the start of the basic block will also be
1854 recorded. If not overridden by the machine description, the default action is
1855 to append to the text file @file{bb.out}.
1857 This data could be analyzed by a program like @code{tcov}. Note,
1858 however, that the format of the data is not what @code{tcov} expects.
1859 Eventually GNU @code{gprof} should be extended to process this data.
1862 Makes the compiler print out each function name as it is compiled, and
1863 print some statistics about each pass when it finishes.
1866 Generate extra code to profile basic blocks. Your executable will
1867 produce output that is a superset of that produced when @samp{-a} is
1868 used. Additional output is the source and target address of the basic
1869 blocks where a jump takes place, the number of times a jump is executed,
1870 and (optionally) the complete sequence of basic blocks being executed.
1871 The output is appended to file @file{bb.out}.
1873 You can examine different profiling aspects without recompilation. Your
1874 executable will read a list of function names from file @file{bb.in}.
1875 Profiling starts when a function on the list is entered and stops when
1876 that invocation is exited. To exclude a function from profiling, prefix
1877 its name with `-'. If a function name is not unique, you can
1878 disambiguate it by writing it in the form
1879 @samp{/path/filename.d:functionname}. Your executable will write the
1880 available paths and filenames in file @file{bb.out}.
1882 Several function names have a special meaning:
1885 Write source, target and frequency of jumps to file @file{bb.out}.
1886 @item __bb_hidecall__
1887 Exclude function calls from frequency count.
1888 @item __bb_showret__
1889 Include function returns in frequency count.
1891 Write the sequence of basic blocks executed to file @file{bbtrace.gz}.
1892 The file will be compressed using the program @samp{gzip}, which must
1893 exist in your @code{PATH}. On systems without the @samp{popen}
1894 function, the file will be named @file{bbtrace} and will not be
1895 compressed. @strong{Profiling for even a few seconds on these systems
1896 will produce a very large file.} Note: @code{__bb_hidecall__} and
1897 @code{__bb_showret__} will not affect the sequence written to
1901 Here's a short example using different profiling parameters
1902 in file @file{bb.in}. Assume function @code{foo} consists of basic blocks
1903 1 and 2 and is called twice from block 3 of function @code{main}. After
1904 the calls, block 3 transfers control to block 4 of @code{main}.
1906 With @code{__bb_trace__} and @code{main} contained in file @file{bb.in},
1907 the following sequence of blocks is written to file @file{bbtrace.gz}:
1908 0 3 1 2 1 2 4. The return from block 2 to block 3 is not shown, because
1909 the return is to a point inside the block and not to the top. The
1910 block address 0 always indicates, that control is transferred
1911 to the trace from somewhere outside the observed functions. With
1912 @samp{-foo} added to @file{bb.in}, the blocks of function
1913 @code{foo} are removed from the trace, so only 0 3 4 remains.
1915 With @code{__bb_jumps__} and @code{main} contained in file @file{bb.in},
1916 jump frequencies will be written to file @file{bb.out}. The
1917 frequencies are obtained by constructing a trace of blocks
1918 and incrementing a counter for every neighbouring pair of blocks
1919 in the trace. The trace 0 3 1 2 1 2 4 displays the following
1923 Jump from block 0x0 to block 0x3 executed 1 time(s)
1924 Jump from block 0x3 to block 0x1 executed 1 time(s)
1925 Jump from block 0x1 to block 0x2 executed 2 time(s)
1926 Jump from block 0x2 to block 0x1 executed 1 time(s)
1927 Jump from block 0x2 to block 0x4 executed 1 time(s)
1930 With @code{__bb_hidecall__}, control transfer due to call instructions
1931 is removed from the trace, that is the trace is cut into three parts: 0
1932 3 4, 0 1 2 and 0 1 2. With @code{__bb_showret__}, control transfer due
1933 to return instructions is added to the trace. The trace becomes: 0 3 1
1934 2 3 1 2 3 4. Note, that this trace is not the same, as the sequence
1935 written to @file{bbtrace.gz}. It is solely used for counting jump
1938 @item -fprofile-arcs
1939 Instrument @dfn{arcs} during compilation. For each function of your
1940 program, GNU CC creates a program flow graph, then finds a spanning tree
1941 for the graph. Only arcs that are not on the spanning tree have to be
1942 instrumented: the compiler adds code to count the number of times that these
1943 arcs are executed. When an arc is the only exit or only entrance to a
1944 block, the instrumentation code can be added to the block; otherwise, a
1945 new basic block must be created to hold the instrumentation code.
1947 Since not every arc in the program must be instrumented, programs
1948 compiled with this option run faster than programs compiled with
1949 @samp{-a}, which adds instrumentation code to every basic block in the
1950 program. The tradeoff: since @code{gcov} does not have
1951 execution counts for all branches, it must start with the execution
1952 counts for the instrumented branches, and then iterate over the program
1953 flow graph until the entire graph has been solved. Hence, @code{gcov}
1954 runs a little more slowly than a program which uses information from
1957 @samp{-fprofile-arcs} also makes it possible to estimate branch
1958 probabilities, and to calculate basic block execution counts. In
1959 general, basic block execution counts do not give enough information to
1960 estimate all branch probabilities. When the compiled program exits, it
1961 saves the arc execution counts to a file called
1962 @file{@var{sourcename}.da}. Use the compiler option
1963 @samp{-fbranch-probabilities} (@pxref{Optimize Options,,Options that
1964 Control Optimization}) when recompiling, to optimize using estimated
1965 branch probabilities.
1968 @item -ftest-coverage
1969 Create data files for the @code{gcov} code-coverage utility
1970 (@pxref{Gcov,, @code{gcov}: a GNU CC Test Coverage Program}).
1971 The data file names begin with the name of your source file:
1974 @item @var{sourcename}.bb
1975 A mapping from basic blocks to line numbers, which @code{gcov} uses to
1976 associate basic block execution counts with line numbers.
1978 @item @var{sourcename}.bbg
1979 A list of all arcs in the program flow graph. This allows @code{gcov}
1980 to reconstruct the program flow graph, so that it can compute all basic
1981 block and arc execution counts from the information in the
1982 @code{@var{sourcename}.da} file (this last file is the output from
1983 @samp{-fprofile-arcs}).
1987 Makes the compiler print out each function name as it is compiled, and
1988 print some statistics about each pass when it finishes.
1990 @item -d@var{letters}
1991 Says to make debugging dumps during compilation at times specified by
1992 @var{letters}. This is used for debugging the compiler. The file names
1993 for most of the dumps are made by appending a word to the source file
1994 name (e.g. @file{foo.c.rtl} or @file{foo.c.jump}). Here are the
1995 possible letters for use in @var{letters}, and their meanings:
1999 Dump after computing branch probabilities, to @file{@var{file}.bp}.
2001 Dump after instruction combination, to the file @file{@var{file}.combine}.
2003 Dump after delayed branch scheduling, to @file{@var{file}.dbr}.
2005 Dump all macro definitions, at the end of preprocessing, in addition to
2008 Dump debugging information during parsing, to standard error.
2010 Dump after RTL generation, to @file{@var{file}.rtl}.
2012 Just generate RTL for a function instead of compiling it. Usually used
2015 Dump after first jump optimization, to @file{@var{file}.jump}.
2017 Dump after CSE (including the jump optimization that sometimes
2018 follows CSE), to @file{@var{file}.cse}.
2020 Dump after purging ADDRESSOF, to @file{@var{file}.addressof}.
2022 Dump after flow analysis, to @file{@var{file}.flow}.
2024 Dump after global register allocation, to @file{@var{file}.greg}.
2026 Dump after GCSE, to @file{@var{file}.gcse}.
2028 Dump after first jump optimization, to @file{@var{file}.jump}.
2030 Dump after last jump optimization, to @file{@var{file}.jump2}.
2032 Dump after conversion from registers to stack, to @file{@var{file}.stack}.
2034 Dump after local register allocation, to @file{@var{file}.lreg}.
2036 Dump after loop optimization, to @file{@var{file}.loop}.
2038 Dump after performing the machine dependent reorganisation pass, to
2039 @file{@var{file}.mach}.
2041 Dump after the register move pass, to @file{@var{file}.regmove}.
2043 Dump after RTL generation, to @file{@var{file}.rtl}.
2045 Dump after the second instruction scheduling pass, to @file{@var{file}.sched2}.
2047 Dump after CSE (including the jump optimization that sometimes follows
2048 CSE), to @file{@var{file}.cse}.
2050 Dump after the first instruction scheduling pass, to @file{@var{file}.sched}.
2052 Dump after the second CSE pass (including the jump optimization that
2053 sometimes follows CSE), to @file{@var{file}.cse2}.
2055 Just generate RTL for a function instead of compiling it. Usually used
2058 Produce all the dumps listed above.
2060 Print statistics on memory usage, at the end of the run, to
2063 Annotate the assembler output with a comment indicating which
2064 pattern and alternative was used.
2066 Dump debugging information during parsing, to standard error.
2068 Annotate the assembler output with miscellaneous debugging information.
2071 @item -fpretend-float
2072 When running a cross-compiler, pretend that the target machine uses the
2073 same floating point format as the host machine. This causes incorrect
2074 output of the actual floating constants, but the actual instruction
2075 sequence will probably be the same as GNU CC would make when running on
2079 Store the usual ``temporary'' intermediate files permanently; place them
2080 in the current directory and name them based on the source file. Thus,
2081 compiling @file{foo.c} with @samp{-c -save-temps} would produce files
2082 @file{foo.i} and @file{foo.s}, as well as @file{foo.o}.
2084 @item -print-file-name=@var{library}
2085 Print the full absolute name of the library file @var{library} that
2086 would be used when linking---and don't do anything else. With this
2087 option, GNU CC does not compile or link anything; it just prints the
2090 @item -print-prog-name=@var{program}
2091 Like @samp{-print-file-name}, but searches for a program such as @samp{cpp}.
2093 @item -print-libgcc-file-name
2094 Same as @samp{-print-file-name=libgcc.a}.
2096 This is useful when you use @samp{-nostdlib} or @samp{-nodefaultlibs}
2097 but you do want to link with @file{libgcc.a}. You can do
2100 gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
2103 @item -print-search-dirs
2104 Print the name of the configured installation directory and a list of
2105 program and library directories gcc will search---and don't do anything else.
2107 This is useful when gcc prints the error message
2108 @samp{installation problem, cannot exec cpp: No such file or directory}.
2109 To resolve this you either need to put @file{cpp} and the other compiler
2110 components where gcc expects to find them, or you can set the environment
2111 variable @code{GCC_EXEC_PREFIX} to the directory where you installed them.
2112 Don't forget the trailing '/'.
2113 @xref{Environment Variables}.
2116 @node Optimize Options
2117 @section Options That Control Optimization
2118 @cindex optimize options
2119 @cindex options, optimization
2121 These options control various sorts of optimizations:
2126 Optimize. Optimizing compilation takes somewhat more time, and a lot
2127 more memory for a large function.
2129 Without @samp{-O}, the compiler's goal is to reduce the cost of
2130 compilation and to make debugging produce the expected results.
2131 Statements are independent: if you stop the program with a breakpoint
2132 between statements, you can then assign a new value to any variable or
2133 change the program counter to any other statement in the function and
2134 get exactly the results you would expect from the source code.
2136 Without @samp{-O}, the compiler only allocates variables declared
2137 @code{register} in registers. The resulting compiled code is a little
2138 worse than produced by PCC without @samp{-O}.
2140 With @samp{-O}, the compiler tries to reduce code size and execution
2143 When you specify @samp{-O}, the compiler turns on @samp{-fthread-jumps}
2144 and @samp{-fdefer-pop} on all machines. The compiler turns on
2145 @samp{-fdelayed-branch} on machines that have delay slots, and
2146 @samp{-fomit-frame-pointer} on machines that can support debugging even
2147 without a frame pointer. On some machines the compiler also turns
2148 on other flags.@refill
2151 Optimize even more. GNU CC performs nearly all supported optimizations
2152 that do not involve a space-speed tradeoff. The compiler does not
2153 perform loop unrolling or function inlining when you specify @samp{-O2}.
2154 As compared to @samp{-O}, this option increases both compilation time
2155 and the performance of the generated code.
2157 @samp{-O2} turns on all optional optimizations except for loop unrolling
2158 and function inlining. It also turns on the @samp{-fforce-mem} option
2159 on all machines and frame pointer elimination on machines where doing so
2160 does not interfere with debugging.
2163 Optimize yet more. @samp{-O3} turns on all optimizations specified by
2164 @samp{-O2} and also turns on the @samp{inline-functions} option.
2170 Optimize for size. @samp{-Os} enables all @samp{-O2} optimizations that
2171 do not typically increase code size. It also performs further
2172 optimizations designed to reduce code size.
2174 If you use multiple @samp{-O} options, with or without level numbers,
2175 the last such option is the one that is effective.
2178 Options of the form @samp{-f@var{flag}} specify machine-independent
2179 flags. Most flags have both positive and negative forms; the negative
2180 form of @samp{-ffoo} would be @samp{-fno-foo}. In the table below,
2181 only one of the forms is listed---the one which is not the default.
2182 You can figure out the other form by either removing @samp{no-} or
2187 Do not store floating point variables in registers, and inhibit other
2188 options that might change whether a floating point value is taken from a
2191 @cindex floating point precision
2192 This option prevents undesirable excess precision on machines such as
2193 the 68000 where the floating registers (of the 68881) keep more
2194 precision than a @code{double} is supposed to have. Similarly for the
2195 x86 architecture. For most programs, the excess precision does only
2196 good, but a few programs rely on the precise definition of IEEE floating
2197 point. Use @samp{-ffloat-store} for such programs.
2199 @item -fno-default-inline
2200 Do not make member functions inline by default merely because they are
2201 defined inside the class scope (C++ only). Otherwise, when you specify
2202 @w{@samp{-O}}, member functions defined inside class scope are compiled
2203 inline by default; i.e., you don't need to add @samp{inline} in front of
2204 the member function name.
2206 @item -fno-defer-pop
2207 Always pop the arguments to each function call as soon as that function
2208 returns. For machines which must pop arguments after a function call,
2209 the compiler normally lets arguments accumulate on the stack for several
2210 function calls and pops them all at once.
2213 Force memory operands to be copied into registers before doing
2214 arithmetic on them. This produces better code by making all memory
2215 references potential common subexpressions. When they are not common
2216 subexpressions, instruction combination should eliminate the separate
2217 register-load. The @samp{-O2} option turns on this option.
2220 Force memory address constants to be copied into registers before
2221 doing arithmetic on them. This may produce better code just as
2222 @samp{-fforce-mem} may.
2224 @item -fomit-frame-pointer
2225 Don't keep the frame pointer in a register for functions that
2226 don't need one. This avoids the instructions to save, set up and
2227 restore frame pointers; it also makes an extra register available
2228 in many functions. @strong{It also makes debugging impossible on
2232 On some machines, such as the Vax, this flag has no effect, because
2233 the standard calling sequence automatically handles the frame pointer
2234 and nothing is saved by pretending it doesn't exist. The
2235 machine-description macro @code{FRAME_POINTER_REQUIRED} controls
2236 whether a target machine supports this flag. @xref{Registers}.@refill
2239 On some machines, such as the Vax, this flag has no effect, because
2240 the standard calling sequence automatically handles the frame pointer
2241 and nothing is saved by pretending it doesn't exist. The
2242 machine-description macro @code{FRAME_POINTER_REQUIRED} controls
2243 whether a target machine supports this flag. @xref{Registers,,Register
2244 Usage, gcc.info, Using and Porting GCC}.@refill
2248 Don't pay attention to the @code{inline} keyword. Normally this option
2249 is used to keep the compiler from expanding any functions inline.
2250 Note that if you are not optimizing, no functions can be expanded inline.
2252 @item -finline-functions
2253 Integrate all simple functions into their callers. The compiler
2254 heuristically decides which functions are simple enough to be worth
2255 integrating in this way.
2257 If all calls to a given function are integrated, and the function is
2258 declared @code{static}, then the function is normally not output as
2259 assembler code in its own right.
2261 @item -fkeep-inline-functions
2262 Even if all calls to a given function are integrated, and the function
2263 is declared @code{static}, nevertheless output a separate run-time
2264 callable version of the function. This switch does not affect
2265 @code{extern inline} functions.
2267 @item -fkeep-static-consts
2268 Emit variables declared @code{static const} when optimization isn't turned
2269 on, even if the variables aren't referenced.
2271 GNU CC enables this option by default. If you want to force the compiler to
2272 check if the variable was referenced, regardless of whether or not
2273 optimization is turned on, use the @samp{-fno-keep-static-consts} option.
2275 @item -fno-function-cse
2276 Do not put function addresses in registers; make each instruction that
2277 calls a constant function contain the function's address explicitly.
2279 This option results in less efficient code, but some strange hacks
2280 that alter the assembler output may be confused by the optimizations
2281 performed when this option is not used.
2284 This option allows GCC to violate some ANSI or IEEE rules and/or
2285 specifications in the interest of optimizing code for speed. For
2286 example, it allows the compiler to assume arguments to the @code{sqrt}
2287 function are non-negative numbers and that no floating-point values
2290 This option should never be turned on by any @samp{-O} option since
2291 it can result in incorrect output for programs which depend on
2292 an exact implementation of IEEE or ANSI rules/specifications for
2296 @c following causes underfulls.. they don't look great, but we deal.
2298 The following options control specific optimizations. The @samp{-O2}
2299 option turns on all of these optimizations except @samp{-funroll-loops}
2300 and @samp{-funroll-all-loops}. On most machines, the @samp{-O} option
2301 turns on the @samp{-fthread-jumps} and @samp{-fdelayed-branch} options,
2302 but specific machines may handle it differently.
2304 You can use the following flags in the rare cases when ``fine-tuning''
2305 of optimizations to be performed is desired.
2308 @item -fstrength-reduce
2309 Perform the optimizations of loop strength reduction and
2310 elimination of iteration variables.
2312 @item -fthread-jumps
2313 Perform optimizations where we check to see if a jump branches to a
2314 location where another comparison subsumed by the first is found. If
2315 so, the first branch is redirected to either the destination of the
2316 second branch or a point immediately following it, depending on whether
2317 the condition is known to be true or false.
2319 @item -fcse-follow-jumps
2320 In common subexpression elimination, scan through jump instructions
2321 when the target of the jump is not reached by any other path. For
2322 example, when CSE encounters an @code{if} statement with an
2323 @code{else} clause, CSE will follow the jump when the condition
2326 @item -fcse-skip-blocks
2327 This is similar to @samp{-fcse-follow-jumps}, but causes CSE to
2328 follow jumps which conditionally skip over blocks. When CSE
2329 encounters a simple @code{if} statement with no else clause,
2330 @samp{-fcse-skip-blocks} causes CSE to follow the jump around the
2331 body of the @code{if}.
2333 @item -frerun-cse-after-loop
2334 Re-run common subexpression elimination after loop optimizations has been
2337 @item -frerun-loop-opt
2338 Run the loop optimizer twice.
2341 Perform a global common subexpression elimination pass.
2342 This pass also performs global constant and copy propagation.
2344 @item -fexpensive-optimizations
2345 Perform a number of minor optimizations that are relatively expensive.
2347 @item -foptimize-register-moves
2349 Attempt to reassign register numbers in move instructions and as
2350 operands of other simple instructions in order to maximize the amount of
2351 register tying. This is especially helpful on machines with two-operand
2352 instructions. GNU CC enables this optimization by default with @samp{-O2}
2355 Note @code{-fregmove} and @code{-foptimize-register-moves} are the same
2358 @item -fdelayed-branch
2359 If supported for the target machine, attempt to reorder instructions
2360 to exploit instruction slots available after delayed branch
2363 @item -fschedule-insns
2364 If supported for the target machine, attempt to reorder instructions to
2365 eliminate execution stalls due to required data being unavailable. This
2366 helps machines that have slow floating point or memory load instructions
2367 by allowing other instructions to be issued until the result of the load
2368 or floating point instruction is required.
2370 @item -fschedule-insns2
2371 Similar to @samp{-fschedule-insns}, but requests an additional pass of
2372 instruction scheduling after register allocation has been done. This is
2373 especially useful on machines with a relatively small number of
2374 registers and where memory load instructions take more than one cycle.
2376 @item -ffunction-sections
2377 Place each function into its own section in the output file if the
2378 target supports arbitrary sections. The function's name determines
2379 the section's name in the output file.
2381 Use this option 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 this option when there are significant benefits from doing
2388 so. When you specify this option, 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 enabled by default on certain machines, usually those
2401 which have no call-preserved registers to use instead.
2403 @item -funroll-loops
2404 Perform the optimization of loop unrolling. This is only done for loops
2405 whose number of iterations can be determined at compile time or run time.
2406 @samp{-funroll-loop} implies both @samp{-fstrength-reduce} and
2407 @samp{-frerun-cse-after-loop}.
2409 @item -funroll-all-loops
2410 Perform the optimization of loop unrolling. This is done for all loops
2411 and usually makes programs run more slowly. @samp{-funroll-all-loops}
2412 implies @samp{-fstrength-reduce} as well as @samp{-frerun-cse-after-loop}.
2414 @item -fmove-all-movables
2415 Forces all invariant computations in loops to be moved
2418 @item -freduce-all-givs
2419 Forces all general-induction variables in loops to be
2422 @emph{Note:} When compiling programs written in Fortran,
2423 @samp{-fmove-all-moveables} and @samp{-freduce-all-givs} are enabled
2424 by default when you use the optimizer.
2426 These options may generate better or worse code; results are highly
2427 dependent on the structure of loops within the source code.
2429 These two options are intended to be removed someday, once
2430 they have helped determine the efficacy of various
2431 approaches to improving loop optimizations.
2433 Please let us (@code{egcs@@cygnus.com} and @code{fortran@@gnu.org})
2434 know how use of these options affects
2435 the performance of your production code.
2436 We're very interested in code that runs @emph{slower}
2437 when these options are @emph{enabled}.
2440 Disable any machine-specific peephole optimizations.
2442 @item -fbranch-probabilities
2443 After running a program compiled with @samp{-fprofile-arcs}
2444 (@pxref{Debugging Options,, Options for Debugging Your Program or
2445 @code{gcc}}), you can compile it a second time using
2446 @samp{-fbranch-probabilities}, to improve optimizations based on
2447 guessing the path a branch might take.
2450 With @samp{-fbranch-probabilities}, GCC puts a @samp{REG_EXEC_COUNT}
2451 note on the first instruction of each basic block, and a
2452 @samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}.
2453 These can be used to improve optimization. Currently, they are only
2454 used in one place: in @file{reorg.c}, instead of guessing which path a
2455 branch is mostly to take, the @samp{REG_BR_PROB} values are used to
2456 exactly determine which path is taken more often.
2459 @item -fstrict-aliasing
2460 Allows the compiler to assume the strictest aliasing rules applicable to
2461 the language being compiled. For C (and C++), this activates
2462 optimizations based on the type of expressions. In particular, an
2463 object of one type is assumed never to reside at the same address as an
2464 object of a different type, unless the types are almost the same. For
2465 example, an @code{unsigned int} can alias an @code{int}, but not a
2466 @code{void*} or a @code{double}. A character type may alias any other
2469 Pay special attention to code like this:
2482 The practice of reading from a different union member than the one most
2483 recently written to (called ``type-punning'') is common. Even with
2484 @samp{-fstrict-aliasing}, type-punning is allowed, provided the memory
2485 is accessed through the union type. So, the code above will work as
2486 expected. However, this code might not:
2497 This option is not enabled by default at any optimization level because
2498 it is new and has yet to be subjected to thorough testing. You may
2499 of course enable it manually with @samp{-fstrict-aliasing}.
2502 Every language that wishes to perform language-specific alias analysis
2503 should define a function that computes, given an @code{tree}
2504 node, an alias set for the node. Nodes in different alias sets are not
2505 allowed to alias. For an example, see the C front-end function
2506 @code{c_get_alias_set}.
2511 @node Preprocessor Options
2512 @section Options Controlling the Preprocessor
2513 @cindex preprocessor options
2514 @cindex options, preprocessor
2516 These options control the C preprocessor, which is run on each C source
2517 file before actual compilation.
2519 If you use the @samp{-E} option, nothing is done except preprocessing.
2520 Some of these options make sense only together with @samp{-E} because
2521 they cause the preprocessor output to be unsuitable for actual
2525 @item -include @var{file}
2526 Process @var{file} as input before processing the regular input file.
2527 In effect, the contents of @var{file} are compiled first. Any @samp{-D}
2528 and @samp{-U} options on the command line are always processed before
2529 @samp{-include @var{file}}, regardless of the order in which they are
2530 written. All the @samp{-include} and @samp{-imacros} options are
2531 processed in the order in which they are written.
2533 @item -imacros @var{file}
2534 Process @var{file} as input, discarding the resulting output, before
2535 processing the regular input file. Because the output generated from
2536 @var{file} is discarded, the only effect of @samp{-imacros @var{file}}
2537 is to make the macros defined in @var{file} available for use in the
2540 Any @samp{-D} and @samp{-U} options on the command line are always
2541 processed before @samp{-imacros @var{file}}, regardless of the order in
2542 which they are written. All the @samp{-include} and @samp{-imacros}
2543 options are processed in the order in which they are written.
2545 @item -idirafter @var{dir}
2546 @cindex second include path
2547 Add the directory @var{dir} to the second include path. The directories
2548 on the second include path are searched when a header file is not found
2549 in any of the directories in the main include path (the one that
2552 @item -iprefix @var{prefix}
2553 Specify @var{prefix} as the prefix for subsequent @samp{-iwithprefix}
2556 @item -iwithprefix @var{dir}
2557 Add a directory to the second include path. The directory's name is
2558 made by concatenating @var{prefix} and @var{dir}, where @var{prefix} was
2559 specified previously with @samp{-iprefix}. If you have not specified a
2560 prefix yet, the directory containing the installed passes of the
2561 compiler is used as the default.
2563 @item -iwithprefixbefore @var{dir}
2564 Add a directory to the main include path. The directory's name is made
2565 by concatenating @var{prefix} and @var{dir}, as in the case of
2566 @samp{-iwithprefix}.
2568 @item -isystem @var{dir}
2569 Add a directory to the beginning of the second include path, marking it
2570 as a system directory, so that it gets the same special treatment as
2571 is applied to the standard system directories.
2574 Do not search the standard system directories for header files. Only
2575 the directories you have specified with @samp{-I} options (and the
2576 current directory, if appropriate) are searched. @xref{Directory
2577 Options}, for information on @samp{-I}.
2579 By using both @samp{-nostdinc} and @samp{-I-}, you can limit the include-file
2580 search path to only those directories you specify explicitly.
2583 Do not predefine any nonstandard macros. (Including architecture flags).
2586 Run only the C preprocessor. Preprocess all the C source files
2587 specified and output the results to standard output or to the
2588 specified output file.
2591 Tell the preprocessor not to discard comments. Used with the
2595 Tell the preprocessor not to generate @samp{#line} directives.
2596 Used with the @samp{-E} option.
2599 @cindex dependencies, make
2601 Tell the preprocessor to output a rule suitable for @code{make}
2602 describing the dependencies of each object file. For each source file,
2603 the preprocessor outputs one @code{make}-rule whose target is the object
2604 file name for that source file and whose dependencies are all the
2605 @code{#include} header files it uses. This rule may be a single line or
2606 may be continued with @samp{\}-newline if it is long. The list of rules
2607 is printed on standard output instead of the preprocessed C program.
2609 @samp{-M} implies @samp{-E}.
2611 Another way to specify output of a @code{make} rule is by setting
2612 the environment variable @code{DEPENDENCIES_OUTPUT} (@pxref{Environment
2616 Like @samp{-M} but the output mentions only the user header files
2617 included with @samp{#include "@var{file}"}. System header files
2618 included with @samp{#include <@var{file}>} are omitted.
2621 Like @samp{-M} but the dependency information is written to a file made by
2622 replacing ".c" with ".d" at the end of the input file names.
2623 This is in addition to compiling the file as specified---@samp{-MD} does
2624 not inhibit ordinary compilation the way @samp{-M} does.
2626 In Mach, you can use the utility @code{md} to merge multiple dependency
2627 files into a single dependency file suitable for using with the @samp{make}
2631 Like @samp{-MD} except mention only user header files, not system
2635 Treat missing header files as generated files and assume they live in the
2636 same directory as the source file. If you specify @samp{-MG}, you
2637 must also specify either @samp{-M} or @samp{-MM}. @samp{-MG} is not
2638 supported with @samp{-MD} or @samp{-MMD}.
2641 Print the name of each header file used, in addition to other normal
2644 @item -A@var{question}(@var{answer})
2645 Assert the answer @var{answer} for @var{question}, in case it is tested
2646 with a preprocessing conditional such as @samp{#if
2647 #@var{question}(@var{answer})}. @samp{-A-} disables the standard
2648 assertions that normally describe the target machine.
2651 Define macro @var{macro} with the string @samp{1} as its definition.
2653 @item -D@var{macro}=@var{defn}
2654 Define macro @var{macro} as @var{defn}. All instances of @samp{-D} on
2655 the command line are processed before any @samp{-U} options.
2658 Undefine macro @var{macro}. @samp{-U} options are evaluated after all
2659 @samp{-D} options, but before any @samp{-include} and @samp{-imacros}
2663 Tell the preprocessor to output only a list of the macro definitions
2664 that are in effect at the end of preprocessing. Used with the @samp{-E}
2668 Tell the preprocessing to pass all macro definitions into the output, in
2669 their proper sequence in the rest of the output.
2672 Like @samp{-dD} except that the macro arguments and contents are omitted.
2673 Only @samp{#define @var{name}} is included in the output.
2676 Support ANSI C trigraphs. The @samp{-ansi} option also has this effect.
2678 @item -Wp,@var{option}
2679 Pass @var{option} as an option to the preprocessor. If @var{option}
2680 contains commas, it is split into multiple options at the commas.
2683 @node Assembler Options
2684 @section Passing Options to the Assembler
2686 @c prevent bad page break with this line
2687 You can pass options to the assembler.
2690 @item -Wa,@var{option}
2691 Pass @var{option} as an option to the assembler. If @var{option}
2692 contains commas, it is split into multiple options at the commas.
2696 @section Options for Linking
2697 @cindex link options
2698 @cindex options, linking
2700 These options come into play when the compiler links object files into
2701 an executable output file. They are meaningless if the compiler is
2702 not doing a link step.
2706 @item @var{object-file-name}
2707 A file name that does not end in a special recognized suffix is
2708 considered to name an object file or library. (Object files are
2709 distinguished from libraries by the linker according to the file
2710 contents.) If linking is done, these object files are used as input
2716 If any of these options is used, then the linker is not run, and
2717 object file names should not be used as arguments. @xref{Overall
2721 @item -l@var{library}
2722 Search the library named @var{library} when linking.
2724 It makes a difference where in the command you write this option; the
2725 linker searches processes libraries and object files in the order they
2726 are specified. Thus, @samp{foo.o -lz bar.o} searches library @samp{z}
2727 after file @file{foo.o} but before @file{bar.o}. If @file{bar.o} refers
2728 to functions in @samp{z}, those functions may not be loaded.
2730 The linker searches a standard list of directories for the library,
2731 which is actually a file named @file{lib@var{library}.a}. The linker
2732 then uses this file as if it had been specified precisely by name.
2734 The directories searched include several standard system directories
2735 plus any that you specify with @samp{-L}.
2737 Normally the files found this way are library files---archive files
2738 whose members are object files. The linker handles an archive file by
2739 scanning through it for members which define symbols that have so far
2740 been referenced but not defined. But if the file that is found is an
2741 ordinary object file, it is linked in the usual fashion. The only
2742 difference between using an @samp{-l} option and specifying a file name
2743 is that @samp{-l} surrounds @var{library} with @samp{lib} and @samp{.a}
2744 and searches several directories.
2747 You need this special case of the @samp{-l} option in order to
2748 link an Objective C program.
2751 Do not use the standard system startup files when linking.
2752 The standard system libraries are used normally, unless @code{-nostdlib}
2753 or @code{-nodefaultlibs} is used.
2755 @item -nodefaultlibs
2756 Do not use the standard system libraries when linking.
2757 Only the libraries you specify will be passed to the linker.
2758 The standard startup files are used normally, unless @code{-nostartfiles}
2759 is used. The compiler may generate calls to memcmp, memset, and memcpy
2760 for System V (and ANSI C) environments or to bcopy and bzero for
2761 BSD environments. These entries are usually resolved by entries in
2762 libc. These entry points should be supplied through some other
2763 mechanism when this option is specified.
2766 Do not use the standard system startup files or libraries when linking.
2767 No startup files and only the libraries you specify will be passed to
2768 the linker. The compiler may generate calls to memcmp, memset, and memcpy
2769 for System V (and ANSI C) environments or to bcopy and bzero for
2770 BSD environments. These entries are usually resolved by entries in
2771 libc. These entry points should be supplied through some other
2772 mechanism when this option is specified.
2774 @cindex @code{-lgcc}, use with @code{-nostdlib}
2775 @cindex @code{-nostdlib} and unresolved references
2776 @cindex unresolved references and @code{-nostdlib}
2777 @cindex @code{-lgcc}, use with @code{-nodefaultlibs}
2778 @cindex @code{-nodefaultlibs} and unresolved references
2779 @cindex unresolved references and @code{-nodefaultlibs}
2780 One of the standard libraries bypassed by @samp{-nostdlib} and
2781 @samp{-nodefaultlibs} is @file{libgcc.a}, a library of internal subroutines
2782 that GNU CC uses to overcome shortcomings of particular machines, or special
2783 needs for some languages.
2785 (@xref{Interface,,Interfacing to GNU CC Output}, for more discussion of
2789 (@xref{Interface,,Interfacing to GNU CC Output,gcc.info,Porting GNU CC},
2790 for more discussion of @file{libgcc.a}.)
2792 In most cases, you need @file{libgcc.a} even when you want to avoid
2793 other standard libraries. In other words, when you specify @samp{-nostdlib}
2794 or @samp{-nodefaultlibs} you should usually specify @samp{-lgcc} as well.
2795 This ensures that you have no unresolved references to internal GNU CC
2796 library subroutines. (For example, @samp{__main}, used to ensure C++
2797 constructors will be called; @pxref{Collect2,,@code{collect2}}.)
2800 Remove all symbol table and relocation information from the executable.
2803 On systems that support dynamic linking, this prevents linking with the shared
2804 libraries. On other systems, this option has no effect.
2807 Produce a shared object which can then be linked with other objects to
2808 form an executable. Not all systems support this option. You must
2809 also specify @samp{-fpic} or @samp{-fPIC} on some systems when
2810 you specify this option.
2813 Bind references to global symbols when building a shared object. Warn
2814 about any unresolved references (unless overridden by the link editor
2815 option @samp{-Xlinker -z -Xlinker defs}). Only a few systems support
2818 @item -Xlinker @var{option}
2819 Pass @var{option} as an option to the linker. You can use this to
2820 supply system-specific linker options which GNU CC does not know how to
2823 If you want to pass an option that takes an argument, you must use
2824 @samp{-Xlinker} twice, once for the option and once for the argument.
2825 For example, to pass @samp{-assert definitions}, you must write
2826 @samp{-Xlinker -assert -Xlinker definitions}. It does not work to write
2827 @samp{-Xlinker "-assert definitions"}, because this passes the entire
2828 string as a single argument, which is not what the linker expects.
2830 @item -Wl,@var{option}
2831 Pass @var{option} as an option to the linker. If @var{option} contains
2832 commas, it is split into multiple options at the commas.
2834 @item -u @var{symbol}
2835 Pretend the symbol @var{symbol} is undefined, to force linking of
2836 library modules to define it. You can use @samp{-u} multiple times with
2837 different symbols to force loading of additional library modules.
2840 @node Directory Options
2841 @section Options for Directory Search
2842 @cindex directory options
2843 @cindex options, directory search
2846 These options specify directories to search for header files, for
2847 libraries and for parts of the compiler:
2851 Add the directory @var{dir} to the head of the list of directories to be
2852 searched for header files. This can be used to override a system header
2853 file, substituting your own version, since these directories are
2854 searched before the system header file directories. If you use more
2855 than one @samp{-I} option, the directories are scanned in left-to-right
2856 order; the standard system directories come after.
2859 Any directories you specify with @samp{-I} options before the @samp{-I-}
2860 option are searched only for the case of @samp{#include "@var{file}"};
2861 they are not searched for @samp{#include <@var{file}>}.
2863 If additional directories are specified with @samp{-I} options after
2864 the @samp{-I-}, these directories are searched for all @samp{#include}
2865 directives. (Ordinarily @emph{all} @samp{-I} directories are used
2868 In addition, the @samp{-I-} option inhibits the use of the current
2869 directory (where the current input file came from) as the first search
2870 directory for @samp{#include "@var{file}"}. There is no way to
2871 override this effect of @samp{-I-}. With @samp{-I.} you can specify
2872 searching the directory which was current when the compiler was
2873 invoked. That is not exactly the same as what the preprocessor does
2874 by default, but it is often satisfactory.
2876 @samp{-I-} does not inhibit the use of the standard system directories
2877 for header files. Thus, @samp{-I-} and @samp{-nostdinc} are
2881 Add directory @var{dir} to the list of directories to be searched
2884 @item -B@var{prefix}
2885 This option specifies where to find the executables, libraries,
2886 include files, and data files of the compiler itself.
2888 The compiler driver program runs one or more of the subprograms
2889 @file{cpp}, @file{cc1}, @file{as} and @file{ld}. It tries
2890 @var{prefix} as a prefix for each program it tries to run, both with and
2891 without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}).
2893 For each subprogram to be run, the compiler driver first tries the
2894 @samp{-B} prefix, if any. If that name is not found, or if @samp{-B}
2895 was not specified, the driver tries two standard prefixes, which are
2896 @file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc-lib/}. If neither of
2897 those results in a file name that is found, the unmodified program
2898 name is searched for using the directories specified in your
2899 @samp{PATH} environment variable.
2901 @samp{-B} prefixes that effectively specify directory names also apply
2902 to libraries in the linker, because the compiler translates these
2903 options into @samp{-L} options for the linker. They also apply to
2904 includes files in the preprocessor, because the compiler translates these
2905 options into @samp{-isystem} options for the preprocessor. In this case,
2906 the compiler appends @samp{include} to the prefix.
2908 The run-time support file @file{libgcc.a} can also be searched for using
2909 the @samp{-B} prefix, if needed. If it is not found there, the two
2910 standard prefixes above are tried, and that is all. The file is left
2911 out of the link if it is not found by those means.
2913 Another way to specify a prefix much like the @samp{-B} prefix is to use
2914 the environment variable @code{GCC_EXEC_PREFIX}. @xref{Environment
2917 @item -specs=@var{file}
2918 Process @var{file} after the compiler reads in the standard @file{specs}
2919 file, in order to override the defaults that the @file{gcc} driver
2920 program uses when determining what switches to pass to @file{cc1},
2921 @file{cc1plus}, @file{as}, @file{ld}, etc. More than one
2922 @samp{-specs=}@var{file} can be specified on the command line, and they
2923 are processed in order, from left to right.
2926 @node Target Options
2927 @section Specifying Target Machine and Compiler Version
2928 @cindex target options
2929 @cindex cross compiling
2930 @cindex specifying machine version
2931 @cindex specifying compiler version and target machine
2932 @cindex compiler version, specifying
2933 @cindex target machine, specifying
2935 By default, GNU CC compiles code for the same type of machine that you
2936 are using. However, it can also be installed as a cross-compiler, to
2937 compile for some other type of machine. In fact, several different
2938 configurations of GNU CC, for different target machines, can be
2939 installed side by side. Then you specify which one to use with the
2942 In addition, older and newer versions of GNU CC can be installed side
2943 by side. One of them (probably the newest) will be the default, but
2944 you may sometimes wish to use another.
2947 @item -b @var{machine}
2948 The argument @var{machine} specifies the target machine for compilation.
2949 This is useful when you have installed GNU CC as a cross-compiler.
2951 The value to use for @var{machine} is the same as was specified as the
2952 machine type when configuring GNU CC as a cross-compiler. For
2953 example, if a cross-compiler was configured with @samp{configure
2954 i386v}, meaning to compile for an 80386 running System V, then you
2955 would specify @samp{-b i386v} to run that cross compiler.
2957 When you do not specify @samp{-b}, it normally means to compile for
2958 the same type of machine that you are using.
2960 @item -V @var{version}
2961 The argument @var{version} specifies which version of GNU CC to run.
2962 This is useful when multiple versions are installed. For example,
2963 @var{version} might be @samp{2.0}, meaning to run GNU CC version 2.0.
2965 The default version, when you do not specify @samp{-V}, is the last
2966 version of GNU CC that you installed.
2969 The @samp{-b} and @samp{-V} options actually work by controlling part of
2970 the file name used for the executable files and libraries used for
2971 compilation. A given version of GNU CC, for a given target machine, is
2972 normally kept in the directory @file{/usr/local/lib/gcc-lib/@var{machine}/@var{version}}.@refill
2974 Thus, sites can customize the effect of @samp{-b} or @samp{-V} either by
2975 changing the names of these directories or adding alternate names (or
2976 symbolic links). If in directory @file{/usr/local/lib/gcc-lib/} the
2977 file @file{80386} is a link to the file @file{i386v}, then @samp{-b
2978 80386} becomes an alias for @samp{-b i386v}.
2980 In one respect, the @samp{-b} or @samp{-V} do not completely change
2981 to a different compiler: the top-level driver program @code{gcc}
2982 that you originally invoked continues to run and invoke the other
2983 executables (preprocessor, compiler per se, assembler and linker)
2984 that do the real work. However, since no real work is done in the
2985 driver program, it usually does not matter that the driver program
2986 in use is not the one for the specified target and version.
2988 The only way that the driver program depends on the target machine is
2989 in the parsing and handling of special machine-specific options.
2990 However, this is controlled by a file which is found, along with the
2991 other executables, in the directory for the specified version and
2992 target machine. As a result, a single installed driver program adapts
2993 to any specified target machine and compiler version.
2995 The driver program executable does control one significant thing,
2996 however: the default version and target machine. Therefore, you can
2997 install different instances of the driver program, compiled for
2998 different targets or versions, under different names.
3000 For example, if the driver for version 2.0 is installed as @code{ogcc}
3001 and that for version 2.1 is installed as @code{gcc}, then the command
3002 @code{gcc} will use version 2.1 by default, while @code{ogcc} will use
3003 2.0 by default. However, you can choose either version with either
3004 command with the @samp{-V} option.
3006 @node Submodel Options
3007 @section Hardware Models and Configurations
3008 @cindex submodel options
3009 @cindex specifying hardware config
3010 @cindex hardware models and configurations, specifying
3011 @cindex machine dependent options
3013 Earlier we discussed the standard option @samp{-b} which chooses among
3014 different installed compilers for completely different target
3015 machines, such as Vax vs. 68000 vs. 80386.
3017 In addition, each of these target machine types can have its own
3018 special options, starting with @samp{-m}, to choose among various
3019 hardware models or configurations---for example, 68010 vs 68020,
3020 floating coprocessor or none. A single installed version of the
3021 compiler can compile for any model or configuration, according to the
3024 Some configurations of the compiler also support additional special
3025 options, usually for compatibility with other compilers on the same
3029 These options are defined by the macro @code{TARGET_SWITCHES} in the
3030 machine description. The default for the options is also defined by
3031 that macro, which enables you to change the defaults.
3046 * RS/6000 and PowerPC Options::
3051 * Intel 960 Options::
3052 * DEC Alpha Options::
3056 * System V Options::
3061 @node M680x0 Options
3062 @subsection M680x0 Options
3063 @cindex M680x0 options
3065 These are the @samp{-m} options defined for the 68000 series. The default
3066 values for these options depends on which style of 68000 was selected when
3067 the compiler was configured; the defaults for the most common choices are
3073 Generate output for a 68000. This is the default
3074 when the compiler is configured for 68000-based systems.
3076 Use this option for microcontrollers with a 68000 or EC000 core,
3077 including the 68008, 68302, 68306, 68307, 68322, 68328 and 68356.
3081 Generate output for a 68020. This is the default
3082 when the compiler is configured for 68020-based systems.
3085 Generate output containing 68881 instructions for floating point.
3086 This is the default for most 68020 systems unless @samp{-nfp} was
3087 specified when the compiler was configured.
3090 Generate output for a 68030. This is the default when the compiler is
3091 configured for 68030-based systems.
3094 Generate output for a 68040. This is the default when the compiler is
3095 configured for 68040-based systems.
3097 This option inhibits the use of 68881/68882 instructions that have to be
3098 emulated by software on the 68040. Use this option if your 68040 does not
3099 have code to emulate those instructions.
3102 Generate output for a 68060. This is the default when the compiler is
3103 configured for 68060-based systems.
3105 This option inhibits the use of 68020 and 68881/68882 instructions that
3106 have to be emulated by software on the 68060. Use this option if your 68060
3107 does not have code to emulate those instructions.
3110 Generate output for a CPU32. This is the default
3111 when the compiler is configured for CPU32-based systems.
3113 Use this option for microcontrollers with a
3114 CPU32 or CPU32+ core, including the 68330, 68331, 68332, 68333, 68334,
3115 68336, 68340, 68341, 68349 and 68360.
3118 Generate output for a 520X "coldfire" family cpu. This is the default
3119 when the compiler is configured for 520X-based systems.
3121 Use this option for microcontroller with a 5200 core, including
3122 the MCF5202, MCF5203, MCF5204 and MCF5202.
3126 Generate output for a 68040, without using any of the new instructions.
3127 This results in code which can run relatively efficiently on either a
3128 68020/68881 or a 68030 or a 68040. The generated code does use the
3129 68881 instructions that are emulated on the 68040.
3132 Generate output for a 68060, without using any of the new instructions.
3133 This results in code which can run relatively efficiently on either a
3134 68020/68881 or a 68030 or a 68040. The generated code does use the
3135 68881 instructions that are emulated on the 68060.
3138 Generate output containing Sun FPA instructions for floating point.
3141 Generate output containing library calls for floating point.
3142 @strong{Warning:} the requisite libraries are not available for all m68k
3143 targets. Normally the facilities of the machine's usual C compiler are
3144 used, but this can't be done directly in cross-compilation. You must
3145 make your own arrangements to provide suitable library functions for
3146 cross-compilation. The embedded targets @samp{m68k-*-aout} and
3147 @samp{m68k-*-coff} do provide software floating point support.
3150 Consider type @code{int} to be 16 bits wide, like @code{short int}.
3153 Do not use the bit-field instructions. The @samp{-m68000}, @samp{-mcpu32}
3154 and @samp{-m5200} options imply @w{@samp{-mnobitfield}}.
3157 Do use the bit-field instructions. The @samp{-m68020} option implies
3158 @samp{-mbitfield}. This is the default if you use a configuration
3159 designed for a 68020.
3162 Use a different function-calling convention, in which functions
3163 that take a fixed number of arguments return with the @code{rtd}
3164 instruction, which pops their arguments while returning. This
3165 saves one instruction in the caller since there is no need to pop
3166 the arguments there.
3168 This calling convention is incompatible with the one normally
3169 used on Unix, so you cannot use it if you need to call libraries
3170 compiled with the Unix compiler.
3172 Also, you must provide function prototypes for all functions that
3173 take variable numbers of arguments (including @code{printf});
3174 otherwise incorrect code will be generated for calls to those
3177 In addition, seriously incorrect code will result if you call a
3178 function with too many arguments. (Normally, extra arguments are
3179 harmlessly ignored.)
3181 The @code{rtd} instruction is supported by the 68010, 68020, 68030,
3182 68040, 68060 and CPU32 processors, but not by the 68000 or 5200.
3185 @itemx -mno-align-int
3186 Control whether GNU CC aligns @code{int}, @code{long}, @code{long long},
3187 @code{float}, @code{double}, and @code{long double} variables on a 32-bit
3188 boundary (@samp{-malign-int}) or a 16-bit boundary (@samp{-mno-align-int}).
3189 Aligning variables on 32-bit boundaries produces code that runs somewhat
3190 faster on processors with 32-bit busses at the expense of more memory.
3192 @strong{Warning:} if you use the @samp{-malign-int} switch, GNU CC will
3193 align structures containing the above types differently than
3194 most published application binary interface specifications for the m68k.
3199 @subsection VAX Options
3202 These @samp{-m} options are defined for the Vax:
3206 Do not output certain jump instructions (@code{aobleq} and so on)
3207 that the Unix assembler for the Vax cannot handle across long
3211 Do output those jump instructions, on the assumption that you
3212 will assemble with the GNU assembler.
3215 Output code for g-format floating point numbers instead of d-format.
3219 @subsection SPARC Options
3220 @cindex SPARC options
3222 These @samp{-m} switches are supported on the SPARC:
3227 Specify @samp{-mapp-regs} to generate output using the global registers
3228 2 through 4, which the SPARC SVR4 ABI reserves for applications. This
3231 To be fully SVR4 ABI compliant at the cost of some performance loss,
3232 specify @samp{-mno-app-regs}. You should compile libraries and system
3233 software with this option.
3237 Generate output containing floating point instructions. This is the
3242 Generate output containing library calls for floating point.
3243 @strong{Warning:} the requisite libraries are not available for all SPARC
3244 targets. Normally the facilities of the machine's usual C compiler are
3245 used, but this cannot be done directly in cross-compilation. You must make
3246 your own arrangements to provide suitable library functions for
3247 cross-compilation. The embedded targets @samp{sparc-*-aout} and
3248 @samp{sparclite-*-*} do provide software floating point support.
3250 @samp{-msoft-float} changes the calling convention in the output file;
3251 therefore, it is only useful if you compile @emph{all} of a program with
3252 this option. In particular, you need to compile @file{libgcc.a}, the
3253 library that comes with GNU CC, with @samp{-msoft-float} in order for
3256 @item -mhard-quad-float
3257 Generate output containing quad-word (long double) floating point
3260 @item -msoft-quad-float
3261 Generate output containing library calls for quad-word (long double)
3262 floating point instructions. The functions called are those specified
3263 in the SPARC ABI. This is the default.
3265 As of this writing, there are no sparc implementations that have hardware
3266 support for the quad-word floating point instructions. They all invoke
3267 a trap handler for one of these instructions, and then the trap handler
3268 emulates the effect of the instruction. Because of the trap handler overhead,
3269 this is much slower than calling the ABI library routines. Thus the
3270 @samp{-msoft-quad-float} option is the default.
3274 With @samp{-mepilogue} (the default), the compiler always emits code for
3275 function exit at the end of each function. Any function exit in
3276 the middle of the function (such as a return statement in C) will
3277 generate a jump to the exit code at the end of the function.
3279 With @samp{-mno-epilogue}, the compiler tries to emit exit code inline
3280 at every function exit.
3284 With @samp{-mflat}, the compiler does not generate save/restore instructions
3285 and will use a "flat" or single register window calling convention.
3286 This model uses %i7 as the frame pointer and is compatible with the normal
3287 register window model. Code from either may be intermixed.
3288 The local registers and the input registers (0-5) are still treated as
3289 "call saved" registers and will be saved on the stack as necessary.
3291 With @samp{-mno-flat} (the default), the compiler emits save/restore
3292 instructions (except for leaf functions) and is the normal mode of operation.
3294 @item -mno-unaligned-doubles
3295 @itemx -munaligned-doubles
3296 Assume that doubles have 8 byte alignment. This is the default.
3298 With @samp{-munaligned-doubles}, GNU CC assumes that doubles have 8 byte
3299 alignment only if they are contained in another type, or if they have an
3300 absolute address. Otherwise, it assumes they have 4 byte alignment.
3301 Specifying this option avoids some rare compatibility problems with code
3302 generated by other compilers. It is not the default because it results
3303 in a performance loss, especially for floating point code.
3307 These two options select variations on the SPARC architecture.
3309 By default (unless specifically configured for the Fujitsu SPARClite),
3310 GCC generates code for the v7 variant of the SPARC architecture.
3312 @samp{-mv8} will give you SPARC v8 code. The only difference from v7
3313 code is that the compiler emits the integer multiply and integer
3314 divide instructions which exist in SPARC v8 but not in SPARC v7.
3316 @samp{-msparclite} will give you SPARClite code. This adds the integer
3317 multiply, integer divide step and scan (@code{ffs}) instructions which
3318 exist in SPARClite but not in SPARC v7.
3320 These options are deprecated and will be deleted in GNU CC 2.9.
3321 They have been replaced with @samp{-mcpu=xxx}.
3325 These two options select the processor for which the code is optimised.
3327 With @samp{-mcypress} (the default), the compiler optimizes code for the
3328 Cypress CY7C602 chip, as used in the SparcStation/SparcServer 3xx series.
3329 This is also appropriate for the older SparcStation 1, 2, IPX etc.
3331 With @samp{-msupersparc} the compiler optimizes code for the SuperSparc cpu, as
3332 used in the SparcStation 10, 1000 and 2000 series. This flag also enables use
3333 of the full SPARC v8 instruction set.
3335 These options are deprecated and will be deleted in GNU CC 2.9.
3336 They have been replaced with @samp{-mcpu=xxx}.
3338 @item -mcpu=@var{cpu_type}
3339 Set the instruction set, register set, and instruction scheduling parameters
3340 for machine type @var{cpu_type}. Supported values for @var{cpu_type} are
3341 @samp{v7}, @samp{cypress}, @samp{v8}, @samp{supersparc}, @samp{sparclite},
3342 @samp{f930}, @samp{f934}, @samp{sparclet}, @samp{tsc701}, @samp{v9}, and
3345 Default instruction scheduling parameters are used for values that select
3346 an architecture and not an implementation. These are @samp{v7}, @samp{v8},
3347 @samp{sparclite}, @samp{sparclet}, @samp{v9}.
3349 Here is a list of each supported architecture and their supported
3355 sparclite: f930, f934
3360 @item -mtune=@var{cpu_type}
3361 Set the instruction scheduling parameters for machine type
3362 @var{cpu_type}, but do not set the instruction set or register set that the
3363 option @samp{-mcpu=}@var{cpu_type} would.
3365 The same values for @samp{-mcpu=}@var{cpu_type} are used for
3366 @samp{-mtune=}@*@var{cpu_type}, though the only useful values are those that
3367 select a particular cpu implementation: @samp{cypress}, @samp{supersparc},
3368 @samp{f930}, @samp{f934}, @samp{tsc701}, @samp{ultrasparc}.
3370 @item -malign-loops=@var{num}
3371 Align loops to a 2 raised to a @var{num} byte boundary. If
3372 @samp{-malign-loops} is not specified, the default is 2.
3374 @item -malign-jumps=@var{num}
3375 Align instructions that are only jumped to to a 2 raised to a @var{num}
3376 byte boundary. If @samp{-malign-jumps} is not specified, the default is 2.
3378 @item -malign-functions=@var{num}
3379 Align the start of functions to a 2 raised to @var{num} byte boundary.
3380 If @samp{-malign-functions} is not specified, the default is 2 if compiling
3381 for 32 bit sparc, and 5 if compiling for 64 bit sparc.
3385 These @samp{-m} switches are supported in addition to the above
3386 on the SPARCLET processor.
3389 @item -mlittle-endian
3390 Generate code for a processor running in little-endian mode.
3393 Treat register @code{%g0} as a normal register.
3394 GCC will continue to clobber it as necessary but will not assume
3395 it always reads as 0.
3397 @item -mbroken-saverestore
3398 Generate code that does not use non-trivial forms of the @code{save} and
3399 @code{restore} instructions. Early versions of the SPARCLET processor do
3400 not correctly handle @code{save} and @code{restore} instructions used with
3401 arguments. They correctly handle them used without arguments. A @code{save}
3402 instruction used without arguments increments the current window pointer
3403 but does not allocate a new stack frame. It is assumed that the window
3404 overflow trap handler will properly handle this case as will interrupt
3408 These @samp{-m} switches are supported in addition to the above
3409 on SPARC V9 processors in 64 bit environments.
3412 @item -mlittle-endian
3413 Generate code for a processor running in little-endian mode.
3417 Generate code for a 32 bit or 64 bit environment.
3418 The 32 bit environment sets int, long and pointer to 32 bits.
3419 The 64 bit environment sets int to 32 bits and long and pointer
3422 @item -mcmodel=medlow
3423 Generate code for the Medium/Low code model: the program must be linked
3424 in the low 32 bits of the address space. Pointers are 64 bits.
3425 Programs can be statically or dynamically linked.
3427 @item -mcmodel=medmid
3428 Generate code for the Medium/Middle code model: the program must be linked
3429 in the low 44 bits of the address space, the text segment must be less than
3430 2G bytes, and data segment must be within 2G of the text segment.
3431 Pointers are 64 bits.
3433 @item -mcmodel=medany
3434 Generate code for the Medium/Anywhere code model: the program may be linked
3435 anywhere in the address space, the text segment must be less than
3436 2G bytes, and data segment must be within 2G of the text segment.
3437 Pointers are 64 bits.
3439 @item -mcmodel=embmedany
3440 Generate code for the Medium/Anywhere code model for embedded systems:
3441 assume a 32 bit text and a 32 bit data segment, both starting anywhere
3442 (determined at link time). Register %g4 points to the base of the
3443 data segment. Pointers still 64 bits.
3444 Programs are statically linked, PIC is not supported.
3447 @itemx -mno-stack-bias
3448 With @samp{-mstack-bias}, GNU CC assumes that the stack pointer, and
3449 frame pointer if present, are offset by -2047 which must be added back
3450 when making stack frame references.
3451 Otherwise, assume no such offset is present.
3454 @node Convex Options
3455 @subsection Convex Options
3456 @cindex Convex options
3458 These @samp{-m} options are defined for Convex:
3462 Generate output for C1. The code will run on any Convex machine.
3463 The preprocessor symbol @code{__convex__c1__} is defined.
3466 Generate output for C2. Uses instructions not available on C1.
3467 Scheduling and other optimizations are chosen for max performance on C2.
3468 The preprocessor symbol @code{__convex_c2__} is defined.
3471 Generate output for C32xx. Uses instructions not available on C1.
3472 Scheduling and other optimizations are chosen for max performance on C32.
3473 The preprocessor symbol @code{__convex_c32__} is defined.
3476 Generate output for C34xx. Uses instructions not available on C1.
3477 Scheduling and other optimizations are chosen for max performance on C34.
3478 The preprocessor symbol @code{__convex_c34__} is defined.
3481 Generate output for C38xx. Uses instructions not available on C1.
3482 Scheduling and other optimizations are chosen for max performance on C38.
3483 The preprocessor symbol @code{__convex_c38__} is defined.
3486 Generate code which puts an argument count in the word preceding each
3487 argument list. This is compatible with regular CC, and a few programs
3488 may need the argument count word. GDB and other source-level debuggers
3489 do not need it; this info is in the symbol table.
3492 Omit the argument count word. This is the default.
3494 @item -mvolatile-cache
3495 Allow volatile references to be cached. This is the default.
3497 @item -mvolatile-nocache
3498 Volatile references bypass the data cache, going all the way to memory.
3499 This is only needed for multi-processor code that does not use standard
3500 synchronization instructions. Making non-volatile references to volatile
3501 locations will not necessarily work.
3504 Type long is 32 bits, the same as type int. This is the default.
3507 Type long is 64 bits, the same as type long long. This option is useless,
3508 because no library support exists for it.
3511 @node AMD29K Options
3512 @subsection AMD29K Options
3513 @cindex AMD29K options
3515 These @samp{-m} options are defined for the AMD Am29000:
3520 @cindex DW bit (29k)
3521 Generate code that assumes the @code{DW} bit is set, i.e., that byte and
3522 halfword operations are directly supported by the hardware. This is the
3527 Generate code that assumes the @code{DW} bit is not set.
3531 @cindex byte writes (29k)
3532 Generate code that assumes the system supports byte and halfword write
3533 operations. This is the default.
3537 Generate code that assumes the systems does not support byte and
3538 halfword write operations. @samp{-mnbw} implies @samp{-mndw}.
3542 @cindex memory model (29k)
3543 Use a small memory model that assumes that all function addresses are
3544 either within a single 256 KB segment or at an absolute address of less
3545 than 256k. This allows the @code{call} instruction to be used instead
3546 of a @code{const}, @code{consth}, @code{calli} sequence.
3550 Use the normal memory model: Generate @code{call} instructions only when
3551 calling functions in the same file and @code{calli} instructions
3552 otherwise. This works if each file occupies less than 256 KB but allows
3553 the entire executable to be larger than 256 KB. This is the default.
3556 Always use @code{calli} instructions. Specify this option if you expect
3557 a single file to compile into more than 256 KB of code.
3561 @cindex processor selection (29k)
3562 Generate code for the Am29050.
3566 Generate code for the Am29000. This is the default.
3568 @item -mkernel-registers
3569 @kindex -mkernel-registers
3570 @cindex kernel and user registers (29k)
3571 Generate references to registers @code{gr64-gr95} instead of to
3572 registers @code{gr96-gr127}. This option can be used when compiling
3573 kernel code that wants a set of global registers disjoint from that used
3576 Note that when this option is used, register names in @samp{-f} flags
3577 must use the normal, user-mode, names.
3579 @item -muser-registers
3580 @kindex -muser-registers
3581 Use the normal set of global registers, @code{gr96-gr127}. This is the
3585 @itemx -mno-stack-check
3586 @kindex -mstack-check
3587 @cindex stack checks (29k)
3588 Insert (or do not insert) a call to @code{__msp_check} after each stack
3589 adjustment. This is often used for kernel code.
3592 @itemx -mno-storem-bug
3593 @kindex -mstorem-bug
3594 @cindex storem bug (29k)
3595 @samp{-mstorem-bug} handles 29k processors which cannot handle the
3596 separation of a mtsrim insn and a storem instruction (most 29000 chips
3597 to date, but not the 29050).
3599 @item -mno-reuse-arg-regs
3600 @itemx -mreuse-arg-regs
3601 @kindex -mreuse-arg-regs
3602 @samp{-mno-reuse-arg-regs} tells the compiler to only use incoming argument
3603 registers for copying out arguments. This helps detect calling a function
3604 with fewer arguments than it was declared with.
3606 @item -mno-impure-text
3607 @itemx -mimpure-text
3608 @kindex -mimpure-text
3609 @samp{-mimpure-text}, used in addition to @samp{-shared}, tells the compiler to
3610 not pass @samp{-assert pure-text} to the linker when linking a shared object.
3613 @kindex -msoft-float
3614 Generate output containing library calls for floating point.
3615 @strong{Warning:} the requisite libraries are not part of GNU CC.
3616 Normally the facilities of the machine's usual C compiler are used, but
3617 this can't be done directly in cross-compilation. You must make your
3618 own arrangements to provide suitable library functions for
3623 @subsection ARM Options
3626 These @samp{-m} options are defined for Advanced RISC Machines (ARM)
3631 @kindex -mapcs-frame
3632 Generate a stack frame that is compliant with the ARM Procedure Call
3633 Standard for all functions, even if this is not strictly necessary for
3634 correct execution of the code. Specifying @samp{-fomit-frame-pointer}
3635 with this option will cause the stack frames not to be generated for
3636 leaf functions. The default is @samp{-mno-apcs-frame}.
3640 This is a synonym for @samp{-mapcs-frame}.
3644 Generate code for a processor running with a 26-bit program counter,
3645 and conforming to the function calling standards for the APCS 26-bit
3646 option. This option replaces the @samp{-m2} and @samp{-m3} options
3647 of previous releases of the compiler.
3651 Generate code for a processor running with a 32-bit program counter,
3652 and conforming to the function calling standards for the APCS 32-bit
3653 option. This option replaces the @samp{-m6} option of previous releases
3656 @item -mapcs-stack-check
3657 @kindex -mapcs-stack-check
3658 @kindex -mno-apcs-stack-check
3659 Generate code to check the amount of stack space available upon entry to
3660 every function (that actually uses some stack space). If there is
3661 insufficient space available then either the function
3662 @samp{__rt_stkovf_split_small} or @samp{__rt_stkovf_split_big} will be
3663 called, depending upon the amount of stack space required. The run time
3664 system is required to provide these functions. The default is
3665 @samp{-mno-apcs-stack-check}, since this produces smaller code.
3668 @kindex -mapcs-float
3669 @kindex -mno-apcs-float
3670 Pass floating point arguments using the float point registers. This is
3671 one of the variants of the APCS. This option is reccommended if the
3672 target hardware has a floating point unit or if a lot of floating point
3673 arithmetic is going to be performed by the code. The default is
3674 @samp{-mno-apcs-float}, since integer only code is slightly increased in
3675 size if @samp{-mapcs-float} is used.
3677 @item -mapcs-reentrant
3678 @kindex -mapcs-reentrant
3679 @kindex -mno-apcs-reentrant
3680 Generate reentrant, position independent code. This is the equivalent
3681 to specifying the @samp{-fpic} option. The default is
3682 @samp{-mno-apcs-reentrant}.
3684 @item -mthumb-interwork
3685 @kindex -mthumb-interwork
3686 @kindex -mno-thumb-interwork
3687 Generate code which supports calling between the ARM and THUMB
3688 instruction sets. Without this option the two instruction sets cannot
3689 be reliably used inside one program. The default is
3690 @samp{-mno-thumb-interwork}, since slightly larger code is generated
3691 when @samp{-mthumb-interwork} is specified.
3693 @item -mno-sched-prolog
3694 @kindex -mno-sched-prolog
3695 @kindex -msched-prolog
3696 Prevent the reordering of instructions in the function prolog, or the
3697 merging of those instruction with the instructions in the function's
3698 body. This means that all functions will start with a recognisable set
3699 of instructions (or in fact one of a chioce from a small set of
3700 different function prologues), and this information can be used to
3701 locate the start if functions inside an executable piece of code. The
3702 default is @samp{-msched-prolog}.
3705 Generate output containing floating point instructions. This is the
3709 Generate output containing library calls for floating point.
3710 @strong{Warning:} the requisite libraries are not available for all ARM
3711 targets. Normally the facilities of the machine's usual C compiler are
3712 used, but this cannot be done directly in cross-compilation. You must make
3713 your own arrangements to provide suitable library functions for
3716 @samp{-msoft-float} changes the calling convention in the output file;
3717 therefore, it is only useful if you compile @emph{all} of a program with
3718 this option. In particular, you need to compile @file{libgcc.a}, the
3719 library that comes with GNU CC, with @samp{-msoft-float} in order for
3722 @item -mlittle-endian
3723 Generate code for a processor running in little-endian mode. This is
3724 the default for all standard configurations.
3727 Generate code for a processor running in big-endian mode; the default is
3728 to compile code for a little-endian processor.
3730 @item -mwords-little-endian
3731 This option only applies when generating code for big-endian processors.
3732 Generate code for a little-endian word order but a big-endian byte
3733 order. That is, a byte order of the form @samp{32107654}. Note: this
3734 option should only be used if you require compatibility with code for
3735 big-endian ARM processors generated by versions of the compiler prior to
3738 @item -mshort-load-bytes
3739 @kindex -mshort-load-bytes
3740 Do not try to load half-words (eg @samp{short}s) by loading a word from
3741 an unaligned address. For some targets the MMU is configured to trap
3742 unaligned loads; use this option to generate code that is safe in these
3745 @item -mno-short-load-bytes
3746 @kindex -mno-short-load-bytes
3747 Use unaligned word loads to load half-words (eg @samp{short}s). This
3748 option produces more efficient code, but the MMU is sometimes configured
3749 to trap these instructions.
3751 @item -mshort-load-words
3752 @kindex -mshort-load-words
3753 This is a synonym for the @samp{-mno-short-load-bytes}.
3755 @item -mno-short-load-words
3756 @kindex -mno-short-load-words
3757 This is a synonym for the @samp{-mshort-load-bytes}.
3761 This option only applies to RISC iX. Emulate the native BSD-mode
3762 compiler. This is the default if @samp{-ansi} is not specified.
3766 This option only applies to RISC iX. Emulate the native X/Open-mode
3769 @item -mno-symrename
3770 @kindex -mno-symrename
3771 This option only applies to RISC iX. Do not run the assembler
3772 post-processor, @samp{symrename}, after code has been assembled.
3773 Normally it is necessary to modify some of the standard symbols in
3774 preparation for linking with the RISC iX C library; this option
3775 suppresses this pass. The post-processor is never run when the
3776 compiler is built for cross-compilation.
3780 This specifies the name of the target ARM processor. GCC uses this name
3781 to determine what kind of instructions it can use when generating
3782 assembly code. Permissable names are: arm2, arm250, arm3, arm6, arm60,
3783 arm600, arm610, arm620, arm7, arm7m, arm7d, arm7dm, arm7di, arm7dmi,
3784 arm70, arm700, arm700i, arm710, arm710c, arm7100, arm7500, arm7500fe,
3785 arm7tdmi, arm8, strongarm, strongarm110
3789 This specifies the name of the target ARM architecture. GCC uses this
3790 name to determine what kind of instructions it can use when generating
3791 assembly code. This option can be used in conjunction with or instead
3792 of the @samp{-mcpu=} option. Permissable names are: armv2, armv2a,
3793 armv3, armv3m, armv4, armv4t
3795 @item -mfpe=<number>
3797 This specifes the version of the floating point emulation available on
3798 the target. Permissable values are 2 and 3.
3800 @item -mstructure-size-boundary=<n>
3801 @kindex -mstructure-size-boundary
3802 The size of all structures and unions will be rounded up to a multiple
3803 of the number of bits set by this option. Permissable values are 8 and
3804 32. The default value varies for different toolchains. For the COFF
3805 targeted toolchain the default value is 8. Specifying the larger number
3806 can produced faster, more efficient code, but can also increase the size
3807 of the program. The two values are potentially incompatible. Code
3808 compiled with one value cannot necessarily expect to work with code or
3809 libraries compiled with the other value, if they exchange information
3810 using structures or unions. Programmers are encouraged to use the 32
3811 value as future versions of the toolchain may default to this value.
3816 @subsection Thumb Options
3817 @cindex Thumb Options
3821 @item -mthumb-interwork
3822 @kindex -mthumb-interwork
3823 @kindex -mno-thumb-interwork
3824 Generate code which supports calling between the THUMB and ARM
3825 instruction sets. Without this option the two instruction sets cannot
3826 be reliably used inside one program. The default is
3827 @samp{-mno-thumb-interwork}, since slightly smaller code is generated
3831 @kindex -mtpcs-frame
3832 @kindex -mno-tpcs-frame
3833 Generate a stack frame that is compliant with the Thumb Procedure Call
3834 Standard for all non-leaf functions. (A leaf function is one that does
3835 not call any other functions). The default is @samp{-mno-apcs-frame}.
3837 @item -mtpcs-leaf-frame
3838 @kindex -mtpcs-leaf-frame
3839 @kindex -mno-tpcs-leaf-frame
3840 Generate a stack frame that is compliant with the Thumb Procedure Call
3841 Standard for all leaf functions. (A leaf function is one that does
3842 not call any other functions). The default is @samp{-mno-apcs-leaf-frame}.
3844 @item -mlittle-endian
3845 @kindex -mlittle-endian
3846 Generate code for a processor running in little-endian mode. This is
3847 the default for all standard configurations.
3850 @kindex -mbig-endian
3851 Generate code for a processor running in big-endian mode.
3853 @item -mstructure-size-boundary=<n>
3854 @kindex -mstructure-size-boundary
3855 The size of all structures and unions will be rounded up to a multiple
3856 of the number of bits set by this option. Permissable values are 8 and
3857 32. The default value varies for different toolchains. For the COFF
3858 targeted toolchain the default value is 8. Specifying the larger number
3859 can produced faster, more efficient code, but can also increase the size
3860 of the program. The two values are potentially incompatible. Code
3861 compiled with one value cannot necessarily expect to work with code or
3862 libraries compiled with the other value, if they exchange information
3863 using structures or unions. Programmers are encouraged to use the 32
3864 value as future versions of the toolchain may default to this value.
3868 @node MN10200 Options
3869 @subsection MN10200 Options
3870 @cindex MN10200 options
3871 These @samp{-m} options are defined for Matsushita MN10200 architectures:
3875 Indicate to the linker that it should perform a relaxation optimization pass
3876 to shorten branches, calls and absolute memory addresses. This option only
3877 has an effect when used on the command line for the final link step.
3879 This option makes symbolic debugging impossible.
3882 @node MN10300 Options
3883 @subsection MN10300 Options
3884 @cindex MN10300 options
3885 These @samp{-m} options are defined for Matsushita MN10300 architectures:
3889 Generate code to avoid bugs in the multiply instructions for the MN10300
3890 processors. This is the default.
3893 Do not generate code to avoid bugs in the multiply instructions for the
3897 Indicate to the linker that it should perform a relaxation optimization pass
3898 to shorten branches, calls and absolute memory addresses. This option only
3899 has an effect when used on the command line for the final link step.
3901 This option makes symbolic debugging impossible.
3905 @node M32R/D Options
3906 @subsection M32R/D Options
3907 @cindex M32R/D options
3909 These @samp{-m} options are defined for Mitsubishi M32R/D architectures:
3912 @item -mcode-model=small
3913 Assume all objects live in the lower 16MB of memory (so that their addresses
3914 can be loaded with the @code{ld24} instruction), and assume all subroutines
3915 are reachable with the @code{bl} instruction.
3916 This is the default.
3918 The addressability of a particular object can be set with the
3919 @code{model} attribute.
3921 @item -mcode-model=medium
3922 Assume objects may be anywhere in the 32 bit address space (the compiler
3923 will generate @code{seth/add3} instructions to load their addresses), and
3924 assume all subroutines are reachable with the @code{bl} instruction.
3926 @item -mcode-model=large
3927 Assume objects may be anywhere in the 32 bit address space (the compiler
3928 will generate @code{seth/add3} instructions to load their addresses), and
3929 assume subroutines may not be reachable with the @code{bl} instruction
3930 (the compiler will generate the much slower @code{seth/add3/jl}
3931 instruction sequence).
3934 Disable use of the small data area. Variables will be put into
3935 one of @samp{.data}, @samp{bss}, or @samp{.rodata} (unless the
3936 @code{section} attribute has been specified).
3937 This is the default.
3939 The small data area consists of sections @samp{.sdata} and @samp{.sbss}.
3940 Objects may be explicitly put in the small data area with the
3941 @code{section} attribute using one of these sections.
3944 Put small global and static data in the small data area, but do not
3945 generate special code to reference them.
3948 Put small global and static data in the small data area, and generate
3949 special instructions to reference them.
3952 @cindex smaller data references
3953 Put global and static objects less than or equal to @var{num} bytes
3954 into the small data or bss sections instead of the normal data or bss
3955 sections. The default value of @var{num} is 8.
3956 The @samp{-msdata} option must be set to one of @samp{sdata} or @samp{use}
3957 for this option to have any effect.
3959 All modules should be compiled with the same @samp{-G @var{num}} value.
3960 Compiling with different values of @var{num} may or may not work; if it
3961 doesn't the linker will give an error message - incorrect code will not be
3967 @subsection M88K Options
3968 @cindex M88k options
3970 These @samp{-m} options are defined for Motorola 88k architectures:
3975 Generate code that works well on both the m88100 and the
3980 Generate code that works best for the m88100, but that also
3985 Generate code that works best for the m88110, and may not run
3990 Obsolete option to be removed from the next revision.
3993 @item -midentify-revision
3994 @kindex -midentify-revision
3996 @cindex identifying source, compiler (88k)
3997 Include an @code{ident} directive in the assembler output recording the
3998 source file name, compiler name and version, timestamp, and compilation
4001 @item -mno-underscores
4002 @kindex -mno-underscores
4003 @cindex underscores, avoiding (88k)
4004 In assembler output, emit symbol names without adding an underscore
4005 character at the beginning of each name. The default is to use an
4006 underscore as prefix on each name.
4008 @item -mocs-debug-info
4009 @itemx -mno-ocs-debug-info
4010 @kindex -mocs-debug-info
4011 @kindex -mno-ocs-debug-info
4013 @cindex debugging, 88k OCS
4014 Include (or omit) additional debugging information (about registers used
4015 in each stack frame) as specified in the 88open Object Compatibility
4016 Standard, ``OCS''. This extra information allows debugging of code that
4017 has had the frame pointer eliminated. The default for DG/UX, SVr4, and
4018 Delta 88 SVr3.2 is to include this information; other 88k configurations
4019 omit this information by default.
4021 @item -mocs-frame-position
4022 @kindex -mocs-frame-position
4023 @cindex register positions in frame (88k)
4024 When emitting COFF debugging information for automatic variables and
4025 parameters stored on the stack, use the offset from the canonical frame
4026 address, which is the stack pointer (register 31) on entry to the
4027 function. The DG/UX, SVr4, Delta88 SVr3.2, and BCS configurations use
4028 @samp{-mocs-frame-position}; other 88k configurations have the default
4029 @samp{-mno-ocs-frame-position}.
4031 @item -mno-ocs-frame-position
4032 @kindex -mno-ocs-frame-position
4033 @cindex register positions in frame (88k)
4034 When emitting COFF debugging information for automatic variables and
4035 parameters stored on the stack, use the offset from the frame pointer
4036 register (register 30). When this option is in effect, the frame
4037 pointer is not eliminated when debugging information is selected by the
4040 @item -moptimize-arg-area
4041 @itemx -mno-optimize-arg-area
4042 @kindex -moptimize-arg-area
4043 @kindex -mno-optimize-arg-area
4044 @cindex arguments in frame (88k)
4045 Control how function arguments are stored in stack frames.
4046 @samp{-moptimize-arg-area} saves space by optimizing them, but this
4047 conflicts with the 88open specifications. The opposite alternative,
4048 @samp{-mno-optimize-arg-area}, agrees with 88open standards. By default
4049 GNU CC does not optimize the argument area.
4051 @item -mshort-data-@var{num}
4052 @kindex -mshort-data-@var{num}
4053 @cindex smaller data references (88k)
4054 @cindex r0-relative references (88k)
4055 Generate smaller data references by making them relative to @code{r0},
4056 which allows loading a value using a single instruction (rather than the
4057 usual two). You control which data references are affected by
4058 specifying @var{num} with this option. For example, if you specify
4059 @samp{-mshort-data-512}, then the data references affected are those
4060 involving displacements of less than 512 bytes.
4061 @samp{-mshort-data-@var{num}} is not effective for @var{num} greater
4064 @item -mserialize-volatile
4065 @kindex -mserialize-volatile
4066 @itemx -mno-serialize-volatile
4067 @kindex -mno-serialize-volatile
4068 @cindex sequential consistency on 88k
4069 Do, or don't, generate code to guarantee sequential consistency
4070 of volatile memory references. By default, consistency is
4073 The order of memory references made by the MC88110 processor does
4074 not always match the order of the instructions requesting those
4075 references. In particular, a load instruction may execute before
4076 a preceding store instruction. Such reordering violates
4077 sequential consistency of volatile memory references, when there
4078 are multiple processors. When consistency must be guaranteed,
4079 GNU C generates special instructions, as needed, to force
4080 execution in the proper order.
4082 The MC88100 processor does not reorder memory references and so
4083 always provides sequential consistency. However, by default, GNU
4084 C generates the special instructions to guarantee consistency
4085 even when you use @samp{-m88100}, so that the code may be run on an
4086 MC88110 processor. If you intend to run your code only on the
4087 MC88100 processor, you may use @samp{-mno-serialize-volatile}.
4089 The extra code generated to guarantee consistency may affect the
4090 performance of your application. If you know that you can safely
4091 forgo this guarantee, you may use @samp{-mno-serialize-volatile}.
4097 @cindex assembler syntax, 88k
4099 Turn on (@samp{-msvr4}) or off (@samp{-msvr3}) compiler extensions
4100 related to System V release 4 (SVr4). This controls the following:
4104 Which variant of the assembler syntax to emit.
4106 @samp{-msvr4} makes the C preprocessor recognize @samp{#pragma weak}
4107 that is used on System V release 4.
4109 @samp{-msvr4} makes GNU CC issue additional declaration directives used in
4113 @samp{-msvr4} is the default for the m88k-motorola-sysv4 and
4114 m88k-dg-dgux m88k configurations. @samp{-msvr3} is the default for all
4115 other m88k configurations.
4117 @item -mversion-03.00
4118 @kindex -mversion-03.00
4119 This option is obsolete, and is ignored.
4120 @c ??? which asm syntax better for GAS? option there too?
4122 @item -mno-check-zero-division
4123 @itemx -mcheck-zero-division
4124 @kindex -mno-check-zero-division
4125 @kindex -mcheck-zero-division
4126 @cindex zero division on 88k
4127 Do, or don't, generate code to guarantee that integer division by
4128 zero will be detected. By default, detection is guaranteed.
4130 Some models of the MC88100 processor fail to trap upon integer
4131 division by zero under certain conditions. By default, when
4132 compiling code that might be run on such a processor, GNU C
4133 generates code that explicitly checks for zero-valued divisors
4134 and traps with exception number 503 when one is detected. Use of
4135 mno-check-zero-division suppresses such checking for code
4136 generated to run on an MC88100 processor.
4138 GNU C assumes that the MC88110 processor correctly detects all
4139 instances of integer division by zero. When @samp{-m88110} is
4140 specified, both @samp{-mcheck-zero-division} and
4141 @samp{-mno-check-zero-division} are ignored, and no explicit checks for
4142 zero-valued divisors are generated.
4144 @item -muse-div-instruction
4145 @kindex -muse-div-instruction
4146 @cindex divide instruction, 88k
4147 Use the div instruction for signed integer division on the
4148 MC88100 processor. By default, the div instruction is not used.
4150 On the MC88100 processor the signed integer division instruction
4151 div) traps to the operating system on a negative operand. The
4152 operating system transparently completes the operation, but at a
4153 large cost in execution time. By default, when compiling code
4154 that might be run on an MC88100 processor, GNU C emulates signed
4155 integer division using the unsigned integer division instruction
4156 divu), thereby avoiding the large penalty of a trap to the
4157 operating system. Such emulation has its own, smaller, execution
4158 cost in both time and space. To the extent that your code's
4159 important signed integer division operations are performed on two
4160 nonnegative operands, it may be desirable to use the div
4161 instruction directly.
4163 On the MC88110 processor the div instruction (also known as the
4164 divs instruction) processes negative operands without trapping to
4165 the operating system. When @samp{-m88110} is specified,
4166 @samp{-muse-div-instruction} is ignored, and the div instruction is used
4167 for signed integer division.
4169 Note that the result of dividing INT_MIN by -1 is undefined. In
4170 particular, the behavior of such a division with and without
4171 @samp{-muse-div-instruction} may differ.
4173 @item -mtrap-large-shift
4174 @itemx -mhandle-large-shift
4175 @kindex -mtrap-large-shift
4176 @kindex -mhandle-large-shift
4177 @cindex bit shift overflow (88k)
4178 @cindex large bit shifts (88k)
4179 Include code to detect bit-shifts of more than 31 bits; respectively,
4180 trap such shifts or emit code to handle them properly. By default GNU CC
4181 makes no special provision for large bit shifts.
4183 @item -mwarn-passed-structs
4184 @kindex -mwarn-passed-structs
4185 @cindex structure passing (88k)
4186 Warn when a function passes a struct as an argument or result.
4187 Structure-passing conventions have changed during the evolution of the C
4188 language, and are often the source of portability problems. By default,
4189 GNU CC issues no such warning.
4192 @node RS/6000 and PowerPC Options
4193 @subsection IBM RS/6000 and PowerPC Options
4194 @cindex RS/6000 and PowerPC Options
4195 @cindex IBM RS/6000 and PowerPC Options
4197 These @samp{-m} options are defined for the IBM RS/6000 and PowerPC:
4205 @itemx -mpowerpc-gpopt
4206 @itemx -mno-powerpc-gpopt
4207 @itemx -mpowerpc-gfxopt
4208 @itemx -mno-powerpc-gfxopt
4210 @itemx -mno-powerpc64
4214 @kindex -mpowerpc-gpopt
4215 @kindex -mpowerpc-gfxopt
4217 GNU CC supports two related instruction set architectures for the
4218 RS/6000 and PowerPC. The @dfn{POWER} instruction set are those
4219 instructions supported by the @samp{rios} chip set used in the original
4220 RS/6000 systems and the @dfn{PowerPC} instruction set is the
4221 architecture of the Motorola MPC5xx, MPC6xx, MPC8xx microprocessors, and
4222 the IBM 4xx microprocessors.
4224 Neither architecture is a subset of the other. However there is a
4225 large common subset of instructions supported by both. An MQ
4226 register is included in processors supporting the POWER architecture.
4228 You use these options to specify which instructions are available on the
4229 processor you are using. The default value of these options is
4230 determined when configuring GNU CC. Specifying the
4231 @samp{-mcpu=@var{cpu_type}} overrides the specification of these
4232 options. We recommend you use the @samp{-mcpu=@var{cpu_type}} option
4233 rather than the options listed above.
4235 The @samp{-mpower} option allows GNU CC to generate instructions that
4236 are found only in the POWER architecture and to use the MQ register.
4237 Specifying @samp{-mpower2} implies @samp{-power} and also allows GNU CC
4238 to generate instructions that are present in the POWER2 architecture but
4239 not the original POWER architecture.
4241 The @samp{-mpowerpc} option allows GNU CC to generate instructions that
4242 are found only in the 32-bit subset of the PowerPC architecture.
4243 Specifying @samp{-mpowerpc-gpopt} implies @samp{-mpowerpc} and also allows
4244 GNU CC to use the optional PowerPC architecture instructions in the
4245 General Purpose group, including floating-point square root. Specifying
4246 @samp{-mpowerpc-gfxopt} implies @samp{-mpowerpc} and also allows GNU CC to
4247 use the optional PowerPC architecture instructions in the Graphics
4248 group, including floating-point select.
4250 The @samp{-mpowerpc64} option allows GNU CC to generate the additional
4251 64-bit instructions that are found in the full PowerPC64 architecture
4252 and to treat GPRs as 64-bit, doubleword quantities. GNU CC defaults to
4253 @samp{-mno-powerpc64}.
4255 If you specify both @samp{-mno-power} and @samp{-mno-powerpc}, GNU CC
4256 will use only the instructions in the common subset of both
4257 architectures plus some special AIX common-mode calls, and will not use
4258 the MQ register. Specifying both @samp{-mpower} and @samp{-mpowerpc}
4259 permits GNU CC to use any instruction from either architecture and to
4260 allow use of the MQ register; specify this for the Motorola MPC601.
4262 @item -mnew-mnemonics
4263 @itemx -mold-mnemonics
4264 @kindex -mnew-mnemonics
4265 @kindex -mold-mnemonics
4266 Select which mnemonics to use in the generated assembler code.
4267 @samp{-mnew-mnemonics} requests output that uses the assembler mnemonics
4268 defined for the PowerPC architecture, while @samp{-mold-mnemonics}
4269 requests the assembler mnemonics defined for the POWER architecture.
4270 Instructions defined in only one architecture have only one mnemonic;
4271 GNU CC uses that mnemonic irrespective of which of these options is
4274 GNU CC defaults to the mnemonics appropriate for the architecture in
4275 use. Specifying @samp{-mcpu=@var{cpu_type}} sometimes overrides the
4276 value of these option. Unless you are building a cross-compiler, you
4277 should normally not specify either @samp{-mnew-mnemonics} or
4278 @samp{-mold-mnemonics}, but should instead accept the default.
4280 @item -mcpu=@var{cpu_type}
4282 Set architecture type, register usage, choice of mnemonics, and
4283 instruction scheduling parameters for machine type @var{cpu_type}.
4284 Supported values for @var{cpu_type} are @samp{rs6000}, @samp{rios1},
4285 @samp{rios2}, @samp{rsc}, @samp{601}, @samp{602}, @samp{603},
4286 @samp{603e}, @samp{604}, @samp{604e}, @samp{620}, @samp{power},
4287 @samp{power2}, @samp{powerpc}, @samp{403}, @samp{505}, @samp{801},
4288 @samp{821}, @samp{823}, and @samp{860} and @samp{common}.
4289 @samp{-mcpu=power}, @samp{-mcpu=power2}, and @samp{-mcpu=powerpc}
4290 specify generic POWER, POWER2 and pure PowerPC (i.e., not MPC601)
4291 architecture machine types, with an appropriate, generic processor model
4292 assumed for scheduling purposes.@refill
4294 @c overfull hbox here --bob 22 jul96
4295 @c original text between ignore ... end ignore
4297 Specifying any of the @samp{-mcpu=rios1}, @samp{-mcpu=rios2},
4298 @samp{-mcpu=rsc}, @samp{-mcpu=power}, or @samp{-mcpu=power2} options
4299 enables the @samp{-mpower} option and disables the @samp{-mpowerpc}
4300 option; @samp{-mcpu=601} enables both the @samp{-mpower} and
4301 @samp{-mpowerpc} options; all of @samp{-mcpu=602}, @samp{-mcpu=603},
4302 @samp{-mcpu=603e}, @samp{-mcpu=604}, @samp{-mcpu=604e},
4303 @samp{-mcpu=620}, @samp{-mcpu=403}, @samp{-mcpu=505}, @samp{-mcpu=801},
4304 @samp{-mcpu=821}, @samp{-mcpu=823}, @samp{-mcpu=860} and
4305 @samp{-mcpu=powerpc} enable the @samp{-mpowerpc} option and disable the
4306 @samp{-mpower} option; @samp{-mcpu=common} disables both the
4307 @samp{-mpower} and @samp{-mpowerpc} options.@refill
4309 @c changed paragraph
4310 Specifying any of the following options:
4311 @samp{-mcpu=rios1}, @samp{-mcpu=rios2}, @samp{-mcpu=rsc},
4312 @samp{-mcpu=power}, or @samp{-mcpu=power2}
4313 enables the @samp{-mpower} option and disables the @samp{-mpowerpc} option;
4314 @samp{-mcpu=601} enables both the @samp{-mpower} and @samp{-mpowerpc} options.
4315 All of @samp{-mcpu=602}, @samp{-mcpu=603}, @samp{-mcpu=603e},
4316 @samp{-mcpu=604}, @samp{-mcpu=620},
4317 enable the @samp{-mpowerpc} option and disable the @samp{-mpower} option.
4318 Exactly similarly, all of @samp{-mcpu=403},
4319 @samp{-mcpu=505}, @samp{-mcpu=821}, @samp{-mcpu=860} and @samp{-mcpu=powerpc}
4320 enable the @samp{-mpowerpc} option and disable the @samp{-mpower} option.
4321 @samp{-mcpu=common} disables both the
4322 @samp{-mpower} and @samp{-mpowerpc} options.@refill
4323 @c end changes to prevent overfull hboxes
4325 AIX versions 4 or greater selects @samp{-mcpu=common} by default, so
4326 that code will operate on all members of the RS/6000 and PowerPC
4327 families. In that case, GNU CC will use only the instructions in the
4328 common subset of both architectures plus some special AIX common-mode
4329 calls, and will not use the MQ register. GNU CC assumes a generic
4330 processor model for scheduling purposes.
4332 Specifying any of the options @samp{-mcpu=rios1}, @samp{-mcpu=rios2},
4333 @samp{-mcpu=rsc}, @samp{-mcpu=power}, or @samp{-mcpu=power2} also
4334 disables the @samp{new-mnemonics} option. Specifying @samp{-mcpu=601},
4335 @samp{-mcpu=602}, @samp{-mcpu=603}, @samp{-mcpu=603e}, @samp{-mcpu=604},
4336 @samp{620}, @samp{403}, or @samp{-mcpu=powerpc} also enables the
4337 @samp{new-mnemonics} option.@refill
4339 Specifying @samp{-mcpu=403}, @samp{-mcpu=821}, or @samp{-mcpu=860} also
4340 enables the @samp{-msoft-float} option.
4342 @item -mtune=@var{cpu_type}
4343 Set the instruction scheduling parameters for machine type
4344 @var{cpu_type}, but do not set the architecture type, register usage,
4345 choice of mnemonics like @samp{-mcpu=}@var{cpu_type} would. The same
4346 values for @var{cpu_type} are used for @samp{-mtune=}@var{cpu_type} as
4347 for @samp{-mcpu=}@var{cpu_type}. The @samp{-mtune=}@var{cpu_type}
4348 option overrides the @samp{-mcpu=}@var{cpu_type} option in terms of
4349 instruction scheduling parameters.
4352 @itemx -mno-fp-in-toc
4353 @itemx -mno-sum-in-toc
4354 @itemx -mminimal-toc
4355 @kindex -mminimal-toc
4356 Modify generation of the TOC (Table Of Contents), which is created for
4357 every executable file. The @samp{-mfull-toc} option is selected by
4358 default. In that case, GNU CC will allocate at least one TOC entry for
4359 each unique non-automatic variable reference in your program. GNU CC
4360 will also place floating-point constants in the TOC. However, only
4361 16,384 entries are available in the TOC.
4363 If you receive a linker error message that saying you have overflowed
4364 the available TOC space, you can reduce the amount of TOC space used
4365 with the @samp{-mno-fp-in-toc} and @samp{-mno-sum-in-toc} options.
4366 @samp{-mno-fp-in-toc} prevents GNU CC from putting floating-point
4367 constants in the TOC and @samp{-mno-sum-in-toc} forces GNU CC to
4368 generate code to calculate the sum of an address and a constant at
4369 run-time instead of putting that sum into the TOC. You may specify one
4370 or both of these options. Each causes GNU CC to produce very slightly
4371 slower and larger code at the expense of conserving TOC space.
4373 If you still run out of space in the TOC even when you specify both of
4374 these options, specify @samp{-mminimal-toc} instead. This option causes
4375 GNU CC to make only one TOC entry for every file. When you specify this
4376 option, GNU CC will produce code that is slower and larger but which
4377 uses extremely little TOC space. You may wish to use this option
4378 only on files that contain less frequently executed code. @refill
4384 Enable AIX 64-bit ABI and calling convention: 64-bit pointers, 64-bit
4385 @code{long} type, and the infrastructure needed to support them.
4386 Specifying @samp{-maix64} implies @samp{-mpowerpc64} and
4387 @samp{-mpowerpc}, while @samp{-maix32} disables the 64-bit ABI and
4388 implies @samp{-mno-powerpc64}. GNU CC defaults to @samp{-maix32}.
4393 On AIX, pass floating-point arguments to prototyped functions beyond the
4394 register save area (RSA) on the stack in addition to argument FPRs. The
4395 AIX calling convention was extended but not initially documented to
4396 handle an obscure K&R C case of calling a function that takes the
4397 address of its arguments with fewer arguments than declared. AIX XL
4398 compilers access floating point arguments which do not fit in the
4399 RSA from the stack when a subroutine is compiled without
4400 optimization. Because always storing floating-point arguments on the
4401 stack is inefficient and rarely needed, this option is not enabled by
4402 default and only is necessary when calling subroutines compiled by AIX
4403 XL compilers without optimization.
4407 Support @dfn{AIX Threads}. Link an application written to use
4408 @dfn{pthreads} with special libraries and startup code to enable the
4413 Support @dfn{IBM RS/6000 SP} @dfn{Parallel Environment} (PE). Link an
4414 application written to use message passing with special startup code to
4415 enable the application to run. The system must have PE installed in the
4416 standard location (@file{/usr/lpp/ppe.poe/}), or the @file{specs} file
4417 must be overridden with the @samp{-specs=} option to specify the
4418 appropriate directory location. The Parallel Environment does not
4419 support threads, so the @samp{-mpe} option and the @samp{-mthreads}
4420 option are incompatible.
4424 @kindex -msoft-float
4425 Generate code that does not use (uses) the floating-point register set.
4426 Software floating point emulation is provided if you use the
4427 @samp{-msoft-float} option, and pass the option to GNU CC when linking.
4430 @itemx -mno-multiple
4431 Generate code that uses (does not use) the load multiple word
4432 instructions and the store multiple word instructions. These
4433 instructions are generated by default on POWER systems, and not
4434 generated on PowerPC systems. Do not use @samp{-mmultiple} on little
4435 endian PowerPC systems, since those instructions do not work when the
4436 processor is in little endian mode.
4441 Generate code that uses (does not use) the load string instructions and the
4442 store string word instructions to save multiple registers and do small block
4443 moves. These instructions are generated by default on POWER systems, and not
4444 generated on PowerPC systems. Do not use @samp{-mstring} on little endian
4445 PowerPC systems, since those instructions do not work when the processor is in
4451 Generate code that uses (does not use) the load or store instructions
4452 that update the base register to the address of the calculated memory
4453 location. These instructions are generated by default. If you use
4454 @samp{-mno-update}, there is a small window between the time that the
4455 stack pointer is updated and the address of the previous frame is
4456 stored, which means code that walks the stack frame across interrupts or
4457 signals may get corrupted data.
4460 @itemx -mno-fused-madd
4461 @kindex -mfused-madd
4462 Generate code that uses (does not use) the floating point multiply and
4463 accumulate instructions. These instructions are generated by default if
4464 hardware floating is used.
4466 @item -mno-bit-align
4469 On System V.4 and embedded PowerPC systems do not (do) force structures
4470 and unions that contain bit fields to be aligned to the base type of the
4473 For example, by default a structure containing nothing but 8
4474 @code{unsigned} bitfields of length 1 would be aligned to a 4 byte
4475 boundary and have a size of 4 bytes. By using @samp{-mno-bit-align},
4476 the structure would be aligned to a 1 byte boundary and be one byte in
4479 @item -mno-strict-align
4480 @itemx -mstrict-align
4481 @kindex -mstrict-align
4482 On System V.4 and embedded PowerPC systems do not (do) assume that
4483 unaligned memory references will be handled by the system.
4486 @itemx -mno-relocatable
4487 @kindex -mrelocatable
4488 On embedded PowerPC systems generate code that allows (does not allow)
4489 the program to be relocated to a different address at runtime. If you
4490 use @samp{-mrelocatable} on any module, all objects linked together must
4491 be compiled with @samp{-mrelocatable} or @samp{-mrelocatable-lib}.
4493 @item -mrelocatable-lib
4494 @itemx -mno-relocatable-lib
4495 On embedded PowerPC systems generate code that allows (does not allow)
4496 the program to be relocated to a different address at runtime. Modules
4497 compiled with @samp{-mrelocatable-lib} can be linked with either modules
4498 compiled without @samp{-mrelocatable} and @samp{-mrelocatable-lib} or
4499 with modules compiled with the @samp{-mrelocatable} options.
4503 On System V.4 and embedded PowerPC systems do not (do) assume that
4504 register 2 contains a pointer to a global area pointing to the addresses
4505 used in the program.
4508 @itemx -mlittle-endian
4509 On System V.4 and embedded PowerPC systems compile code for the
4510 processor in little endian mode. The @samp{-mlittle-endian} option is
4511 the same as @samp{-mlittle}.
4515 On System V.4 and embedded PowerPC systems compile code for the
4516 processor in big endian mode. The @samp{-mbig-endian} option is
4517 the same as @samp{-mbig}.
4520 On System V.4 and embedded PowerPC systems compile code using calling
4521 conventions that adheres to the March 1995 draft of the System V
4522 Application Binary Interface, PowerPC processor supplement. This is the
4523 default unless you configured GCC using @samp{powerpc-*-eabiaix}.
4525 @item -mcall-sysv-eabi
4526 Specify both @samp{-mcall-sysv} and @samp{-meabi} options.
4528 @item -mcall-sysv-noeabi
4529 Specify both @samp{-mcall-sysv} and @samp{-mno-eabi} options.
4532 On System V.4 and embedded PowerPC systems compile code using calling
4533 conventions that are similar to those used on AIX. This is the
4534 default if you configured GCC using @samp{powerpc-*-eabiaix}.
4536 @item -mcall-solaris
4537 On System V.4 and embedded PowerPC systems compile code for the Solaris
4541 On System V.4 and embedded PowerPC systems compile code for the
4542 Linux-based GNU system.
4545 @itemx -mno-prototype
4546 On System V.4 and embedded PowerPC systems assume that all calls to
4547 variable argument functions are properly prototyped. Otherwise, the
4548 compiler must insert an instruction before every non prototyped call to
4549 set or clear bit 6 of the condition code register (@var{CR}) to
4550 indicate whether floating point values were passed in the floating point
4551 registers in case the function takes a variable arguments. With
4552 @samp{-mprototype}, only calls to prototyped variable argument functions
4553 will set or clear the bit.
4556 On embedded PowerPC systems, assume that the startup module is called
4557 @file{sim-crt0.o} and that the standard C libraries are @file{libsim.a} and
4558 @file{libc.a}. This is the default for @samp{powerpc-*-eabisim}.
4562 On embedded PowerPC systems, assume that the startup module is called
4563 @file{crt0.o} and the standard C libraries are @file{libmvme.a} and
4567 On embedded PowerPC systems, assume that the startup module is called
4568 @file{crt0.o} and the standard C libraries are @file{libads.a} and
4572 On embedded PowerPC systems, assume that the startup module is called
4573 @file{crt0.o} and the standard C libraries are @file{libyk.a} and
4577 On embedded PowerPC systems, set the @var{PPC_EMB} bit in the ELF flags
4578 header to indicate that @samp{eabi} extended relocations are used.
4582 On System V.4 and embedded PowerPC systems do (do not) adhere to the
4583 Embedded Applications Binary Interface (eabi) which is a set of
4584 modifications to the System V.4 specifications. Selecting @code{-meabi}
4585 means that the stack is aligned to an 8 byte boundary, a function
4586 @code{__eabi} is called to from @code{main} to set up the eabi
4587 environment, and the @samp{-msdata} option can use both @code{r2} and
4588 @code{r13} to point to two separate small data areas. Selecting
4589 @code{-mno-eabi} means that the stack is aligned to a 16 byte boundary,
4590 do not call an initialization function from @code{main}, and the
4591 @samp{-msdata} option will only use @code{r13} to point to a single
4592 small data area. The @samp{-meabi} option is on by default if you
4593 configured GCC using one of the @samp{powerpc*-*-eabi*} options.
4596 On System V.4 and embedded PowerPC systems, put small initialized
4597 @code{const} global and static data in the @samp{.sdata2} section, which
4598 is pointed to by register @code{r2}. Put small initialized
4599 non-@code{const} global and static data in the @samp{.sdata} section,
4600 which is pointed to by register @code{r13}. Put small uninitialized
4601 global and static data in the @samp{.sbss} section, which is adjacent to
4602 the @samp{.sdata} section. The @samp{-msdata=eabi} option is
4603 incompatible with the @samp{-mrelocatable} option. The
4604 @samp{-msdata=eabi} option also sets the @samp{-memb} option.
4607 On System V.4 and embedded PowerPC systems, put small global and static
4608 data in the @samp{.sdata} section, which is pointed to by register
4609 @code{r13}. Put small uninitialized global and static data in the
4610 @samp{.sbss} section, which is adjacent to the @samp{.sdata} section.
4611 The @samp{-msdata=sysv} option is incompatible with the
4612 @samp{-mrelocatable} option.
4614 @item -msdata=default
4616 On System V.4 and embedded PowerPC systems, if @samp{-meabi} is used,
4617 compile code the same as @samp{-msdata=eabi}, otherwise compile code the
4618 same as @samp{-msdata=sysv}.
4621 On System V.4 and embedded PowerPC systems, put small global and static
4622 data in the @samp{.sdata} section. Put small uninitialized global and
4623 static data in the @samp{.sbss} section. Do not use register @code{r13}
4624 to address small data however. This is the default behavior unless
4625 other @samp{-msdata} options are used.
4629 On embedded PowerPC systems, put all initialized global and static data
4630 in the @samp{.data} section, and all uninitialized data in the
4631 @samp{.bss} section.
4634 @cindex smaller data references (PowerPC)
4635 @cindex .sdata/.sdata2 references (PowerPC)
4636 On embedded PowerPC systems, put global and static items less than or
4637 equal to @var{num} bytes into the small data or bss sections instead of
4638 the normal data or bss section. By default, @var{num} is 8. The
4639 @samp{-G @var{num}} switch is also passed to the linker.
4640 All modules should be compiled with the same @samp{-G @var{num}} value.
4643 @itemx -mno-regnames
4644 On System V.4 and embedded PowerPC systems do (do not) emit register
4645 names in the assembly language output using symbolic forms.
4648 @subsection IBM RT Options
4650 @cindex IBM RT options
4652 These @samp{-m} options are defined for the IBM RT PC:
4656 Use an in-line code sequence for integer multiplies. This is the
4659 @item -mcall-lib-mul
4660 Call @code{lmul$$} for integer multiples.
4662 @item -mfull-fp-blocks
4663 Generate full-size floating point data blocks, including the minimum
4664 amount of scratch space recommended by IBM. This is the default.
4666 @item -mminimum-fp-blocks
4667 Do not include extra scratch space in floating point data blocks. This
4668 results in smaller code, but slower execution, since scratch space must
4669 be allocated dynamically.
4671 @cindex @file{varargs.h} and RT PC
4672 @cindex @file{stdarg.h} and RT PC
4673 @item -mfp-arg-in-fpregs
4674 Use a calling sequence incompatible with the IBM calling convention in
4675 which floating point arguments are passed in floating point registers.
4676 Note that @code{varargs.h} and @code{stdargs.h} will not work with
4677 floating point operands if this option is specified.
4679 @item -mfp-arg-in-gregs
4680 Use the normal calling convention for floating point arguments. This is
4683 @item -mhc-struct-return
4684 Return structures of more than one word in memory, rather than in a
4685 register. This provides compatibility with the MetaWare HighC (hc)
4686 compiler. Use the option @samp{-fpcc-struct-return} for compatibility
4687 with the Portable C Compiler (pcc).
4689 @item -mnohc-struct-return
4690 Return some structures of more than one word in registers, when
4691 convenient. This is the default. For compatibility with the
4692 IBM-supplied compilers, use the option @samp{-fpcc-struct-return} or the
4693 option @samp{-mhc-struct-return}.
4697 @subsection MIPS Options
4698 @cindex MIPS options
4700 These @samp{-m} options are defined for the MIPS family of computers:
4703 @item -mcpu=@var{cpu type}
4704 Assume the defaults for the machine type @var{cpu type} when scheduling
4705 instructions. The choices for @var{cpu type} are @samp{r2000}, @samp{r3000},
4706 @samp{r4000}, @samp{r4400}, @samp{r4600}, and @samp{r6000}. While picking a
4707 specific @var{cpu type} will schedule things appropriately for that
4708 particular chip, the compiler will not generate any code that does not
4709 meet level 1 of the MIPS ISA (instruction set architecture) without
4710 the @samp{-mips2} or @samp{-mips3} switches being used.
4713 Issue instructions from level 1 of the MIPS ISA. This is the default.
4714 @samp{r3000} is the default @var{cpu type} at this ISA level.
4717 Issue instructions from level 2 of the MIPS ISA (branch likely, square
4718 root instructions). @samp{r6000} is the default @var{cpu type} at this
4722 Issue instructions from level 3 of the MIPS ISA (64 bit instructions).
4723 @samp{r4000} is the default @var{cpu type} at this ISA level.
4724 This option does not change the sizes of any of the C data types.
4727 Issue instructions from level 4 of the MIPS ISA. @samp{r8000} is the
4728 default @var{cpu type} at this ISA level.
4731 Assume that 32 32-bit floating point registers are available. This is
4735 Assume that 32 64-bit floating point registers are available. This is
4736 the default when the @samp{-mips3} option is used.
4739 Assume that 32 32-bit general purpose registers are available. This is
4743 Assume that 32 64-bit general purpose registers are available. This is
4744 the default when the @samp{-mips3} option is used.
4747 Types long, int, and pointer are 64 bits. This works only if @samp{-mips3}
4751 Types long and pointer are 64 bits, and type int is 32 bits.
4752 This works only if @samp{-mips3} is also specified.
4758 Generate code for the indicated ABI.
4761 Generate code for the MIPS assembler, and invoke @file{mips-tfile} to
4762 add normal debug information. This is the default for all
4763 platforms except for the OSF/1 reference platform, using the OSF/rose
4764 object format. If the either of the @samp{-gstabs} or @samp{-gstabs+}
4765 switches are used, the @file{mips-tfile} program will encapsulate the
4766 stabs within MIPS ECOFF.
4769 Generate code for the GNU assembler. This is the default on the OSF/1
4770 reference platform, using the OSF/rose object format. Also, this is
4771 the default if the configure option @samp{--with-gnu-as} is used.
4773 @item -msplit-addresses
4774 @itemx -mno-split-addresses
4775 Generate code to load the high and low parts of address constants separately.
4776 This allows @code{gcc} to optimize away redundant loads of the high order
4777 bits of addresses. This optimization requires GNU as and GNU ld.
4778 This optimization is enabled by default for some embedded targets where
4779 GNU as and GNU ld are standard.
4783 The @samp{-mrnames} switch says to output code using the MIPS software
4784 names for the registers, instead of the hardware names (ie, @var{a0}
4785 instead of @var{$4}). The only known assembler that supports this option
4786 is the Algorithmics assembler.
4790 The @samp{-mgpopt} switch says to write all of the data declarations
4791 before the instructions in the text section, this allows the MIPS
4792 assembler to generate one word memory references instead of using two
4793 words for short global or static data items. This is on by default if
4794 optimization is selected.
4798 For each non-inline function processed, the @samp{-mstats} switch
4799 causes the compiler to emit one line to the standard error file to
4800 print statistics about the program (number of registers saved, stack
4805 The @samp{-mmemcpy} switch makes all block moves call the appropriate
4806 string function (@samp{memcpy} or @samp{bcopy}) instead of possibly
4807 generating inline code.
4810 @itemx -mno-mips-tfile
4811 The @samp{-mno-mips-tfile} switch causes the compiler not
4812 postprocess the object file with the @file{mips-tfile} program,
4813 after the MIPS assembler has generated it to add debug support. If
4814 @file{mips-tfile} is not run, then no local variables will be
4815 available to the debugger. In addition, @file{stage2} and
4816 @file{stage3} objects will have the temporary file names passed to the
4817 assembler embedded in the object file, which means the objects will
4818 not compare the same. The @samp{-mno-mips-tfile} switch should only
4819 be used when there are bugs in the @file{mips-tfile} program that
4820 prevents compilation.
4823 Generate output containing library calls for floating point.
4824 @strong{Warning:} the requisite libraries are not part of GNU CC.
4825 Normally the facilities of the machine's usual C compiler are used, but
4826 this can't be done directly in cross-compilation. You must make your
4827 own arrangements to provide suitable library functions for
4831 Generate output containing floating point instructions. This is the
4832 default if you use the unmodified sources.
4835 @itemx -mno-abicalls
4836 Emit (or do not emit) the pseudo operations @samp{.abicalls},
4837 @samp{.cpload}, and @samp{.cprestore} that some System V.4 ports use for
4838 position independent code.
4841 @itemx -mno-long-calls
4842 Do all calls with the @samp{JALR} instruction, which requires
4843 loading up a function's address into a register before the call.
4844 You need to use this switch, if you call outside of the current
4845 512 megabyte segment to functions that are not through pointers.
4848 @itemx -mno-half-pic
4849 Put pointers to extern references into the data section and load them
4850 up, rather than put the references in the text section.
4852 @item -membedded-pic
4853 @itemx -mno-embedded-pic
4854 Generate PIC code suitable for some embedded systems. All calls are
4855 made using PC relative address, and all data is addressed using the $gp
4856 register. No more than 65536 bytes of global data may be used. This
4857 requires GNU as and GNU ld which do most of the work. This currently
4858 only works on targets which use ECOFF; it does not work with ELF.
4860 @item -membedded-data
4861 @itemx -mno-embedded-data
4862 Allocate variables to the read-only data section first if possible, then
4863 next in the small data section if possible, otherwise in data. This gives
4864 slightly slower code than the default, but reduces the amount of RAM required
4865 when executing, and thus may be preferred for some embedded systems.
4867 @item -msingle-float
4868 @itemx -mdouble-float
4869 The @samp{-msingle-float} switch tells gcc to assume that the floating
4870 point coprocessor only supports single precision operations, as on the
4871 @samp{r4650} chip. The @samp{-mdouble-float} switch permits gcc to use
4872 double precision operations. This is the default.
4876 Permit use of the @samp{mad}, @samp{madu} and @samp{mul} instructions,
4877 as on the @samp{r4650} chip.
4880 Turns on @samp{-msingle-float}, @samp{-mmad}, and, at least for now,
4884 Compile code for the processor in little endian mode.
4885 The requisite libraries are assumed to exist.
4888 Compile code for the processor in big endian mode.
4889 The requisite libraries are assumed to exist.
4892 @cindex smaller data references (MIPS)
4893 @cindex gp-relative references (MIPS)
4894 Put global and static items less than or equal to @var{num} bytes into
4895 the small data or bss sections instead of the normal data or bss
4896 section. This allows the assembler to emit one word memory reference
4897 instructions based on the global pointer (@var{gp} or @var{$28}),
4898 instead of the normal two words used. By default, @var{num} is 8 when
4899 the MIPS assembler is used, and 0 when the GNU assembler is used. The
4900 @samp{-G @var{num}} switch is also passed to the assembler and linker.
4901 All modules should be compiled with the same @samp{-G @var{num}}
4905 Tell the MIPS assembler to not run its preprocessor over user
4906 assembler files (with a @samp{.s} suffix) when assembling them.
4910 These options are defined by the macro
4911 @code{TARGET_SWITCHES} in the machine description. The default for the
4912 options is also defined by that macro, which enables you to change the
4917 @subsection Intel 386 Options
4918 @cindex i386 Options
4919 @cindex Intel 386 Options
4921 These @samp{-m} options are defined for the i386 family of computers:
4924 @item -mcpu=@var{cpu type}
4925 Assume the defaults for the machine type @var{cpu type} when scheduling
4926 instructions. The choices for @var{cpu type} are: @samp{i386},
4927 @samp{i486}, @samp{i586} (@samp{pentium}), @samp{pentium}, @samp{i686}
4928 (@samp{pentiumpro}) and @samp{pentiumpro}. While picking a specific
4929 @var{cpu type} will schedule things appropriately for that particular
4930 chip, the compiler will not generate any code that does not run on the
4931 i386 without the @samp{-march=@var{cpu type}} option being used.
4933 @item -march=@var{cpu type}
4934 Generate instructions for the machine type @var{cpu type}. The choices
4935 for @var{cpu type} are: @samp{i386}, @samp{i486}, @samp{pentium}, and
4936 @samp{pentiumpro}. Specifying @samp{-march=@var{cpu type}} implies
4937 @samp{-mcpu=@var{cpu type}}.
4943 Synonyms for -mcpu=i386, -mcpu=i486, -mcpu=pentium, and -mcpu=pentiumpro
4948 Control whether or not the compiler uses IEEE floating point
4949 comparisons. These handle correctly the case where the result of a
4950 comparison is unordered.
4953 Generate output containing library calls for floating point.
4954 @strong{Warning:} the requisite libraries are not part of GNU CC.
4955 Normally the facilities of the machine's usual C compiler are used, but
4956 this can't be done directly in cross-compilation. You must make your
4957 own arrangements to provide suitable library functions for
4960 On machines where a function returns floating point results in the 80387
4961 register stack, some floating point opcodes may be emitted even if
4962 @samp{-msoft-float} is used.
4964 @item -mno-fp-ret-in-387
4965 Do not use the FPU registers for return values of functions.
4967 The usual calling convention has functions return values of types
4968 @code{float} and @code{double} in an FPU register, even if there
4969 is no FPU. The idea is that the operating system should emulate
4972 The option @samp{-mno-fp-ret-in-387} causes such values to be returned
4973 in ordinary CPU registers instead.
4975 @item -mno-fancy-math-387
4976 Some 387 emulators do not support the @code{sin}, @code{cos} and
4977 @code{sqrt} instructions for the 387. Specify this option to avoid
4978 generating those instructions. This option is the default on FreeBSD.
4979 As of revision 2.6.1, these instructions are not generated unless you
4980 also use the @samp{-ffast-math} switch.
4982 @item -malign-double
4983 @itemx -mno-align-double
4984 Control whether GNU CC aligns @code{double}, @code{long double}, and
4985 @code{long long} variables on a two word boundary or a one word
4986 boundary. Aligning @code{double} variables on a two word boundary will
4987 produce code that runs somewhat faster on a @samp{Pentium} at the
4988 expense of more memory.
4990 @strong{Warning:} if you use the @samp{-malign-double} switch,
4991 structures containing the above types will be aligned differently than
4992 the published application binary interface specifications for the 386.
4995 @itemx -mno-svr3-shlib
4996 Control whether GNU CC places uninitialized locals into @code{bss} or
4997 @code{data}. @samp{-msvr3-shlib} places these locals into @code{bss}.
4998 These options are meaningful only on System V Release 3.
5000 @item -mno-wide-multiply
5001 @itemx -mwide-multiply
5002 Control whether GNU CC uses the @code{mul} and @code{imul} that produce
5003 64 bit results in @code{eax:edx} from 32 bit operands to do @code{long
5004 long} multiplies and 32-bit division by constants.
5007 Use a different function-calling convention, in which functions that
5008 take a fixed number of arguments return with the @code{ret} @var{num}
5009 instruction, which pops their arguments while returning. This saves one
5010 instruction in the caller since there is no need to pop the arguments
5013 You can specify that an individual function is called with this calling
5014 sequence with the function attribute @samp{stdcall}. You can also
5015 override the @samp{-mrtd} option by using the function attribute
5016 @samp{cdecl}. @xref{Function Attributes}
5018 @strong{Warning:} this calling convention is incompatible with the one
5019 normally used on Unix, so you cannot use it if you need to call
5020 libraries compiled with the Unix compiler.
5022 Also, you must provide function prototypes for all functions that
5023 take variable numbers of arguments (including @code{printf});
5024 otherwise incorrect code will be generated for calls to those
5027 In addition, seriously incorrect code will result if you call a
5028 function with too many arguments. (Normally, extra arguments are
5029 harmlessly ignored.)
5031 @item -mreg-alloc=@var{regs}
5032 Control the default allocation order of integer registers. The
5033 string @var{regs} is a series of letters specifying a register. The
5034 supported letters are: @code{a} allocate EAX; @code{b} allocate EBX;
5035 @code{c} allocate ECX; @code{d} allocate EDX; @code{S} allocate ESI;
5036 @code{D} allocate EDI; @code{B} allocate EBP.
5038 @item -mregparm=@var{num}
5039 Control how many registers are used to pass integer arguments. By
5040 default, no registers are used to pass arguments, and at most 3
5041 registers can be used. You can control this behavior for a specific
5042 function by using the function attribute @samp{regparm}. @xref{Function Attributes}
5044 @strong{Warning:} if you use this switch, and
5045 @var{num} is nonzero, then you must build all modules with the same
5046 value, including any libraries. This includes the system libraries and
5049 @item -malign-loops=@var{num}
5050 Align loops to a 2 raised to a @var{num} byte boundary. If
5051 @samp{-malign-loops} is not specified, the default is 2 unless
5052 gas 2.8 (or later) is being used in which case the default is
5053 to align the loop on a 16 byte boundary if it is less than 8
5056 @item -malign-jumps=@var{num}
5057 Align instructions that are only jumped to to a 2 raised to a @var{num}
5058 byte boundary. If @samp{-malign-jumps} is not specified, the default is
5059 2 if optimizing for a 386, and 4 if optimizing for a 486 unless
5060 gas 2.8 (or later) is being used in which case the default is
5061 to align the instruction on a 16 byte boundary if it is less
5064 @item -malign-functions=@var{num}
5065 Align the start of functions to a 2 raised to @var{num} byte boundary.
5066 If @samp{-malign-functions} is not specified, the default is 2 if optimizing
5067 for a 386, and 4 if optimizing for a 486.
5071 @subsection HPPA Options
5072 @cindex HPPA Options
5074 These @samp{-m} options are defined for the HPPA family of computers:
5078 Generate code for a PA 1.0 processor.
5081 Generate code for a PA 1.1 processor.
5084 Generate code suitable for big switch tables. Use this option only if
5085 the assembler/linker complain about out of range branches within a switch
5088 @item -mjump-in-delay
5089 Fill delay slots of function calls with unconditional jump instructions
5090 by modifying the return pointer for the function call to be the target
5091 of the conditional jump.
5093 @item -mdisable-fpregs
5094 Prevent floating point registers from being used in any manner. This is
5095 necessary for compiling kernels which perform lazy context switching of
5096 floating point registers. If you use this option and attempt to perform
5097 floating point operations, the compiler will abort.
5099 @item -mdisable-indexing
5100 Prevent the compiler from using indexing address modes. This avoids some
5101 rather obscure problems when compiling MIG generated code under MACH.
5103 @item -mno-space-regs
5104 Generate code that assumes the target has no space registers. This allows
5105 GCC to generate faster indirect calls and use unscaled index address modes.
5107 Such code is suitable for level 0 PA systems and kernels.
5109 @item -mfast-indirect-calls
5110 Generate code that assumes calls never cross space boundaries. This
5111 allows GCC to emit code which performs faster indirect calls.
5113 This option will not work in the presense of shared libraries or nested
5117 Optimize for space rather than execution time. Currently this only
5118 enables out of line function prologues and epilogues. This option is
5119 incompatible with PIC code generation and profiling.
5121 @item -mlong-load-store
5122 Generate 3-instruction load and store sequences as sometimes required by
5123 the HP-UX 10 linker. This is equivalent to the @samp{+k} option to
5126 @item -mportable-runtime
5127 Use the portable calling conventions proposed by HP for ELF systems.
5130 Enable the use of assembler directives only GAS understands.
5132 @item -mschedule=@var{cpu type}
5133 Schedule code according to the constraints for the machine type
5134 @var{cpu type}. The choices for @var{cpu type} are @samp{700} for
5135 7@var{n}0 machines, @samp{7100} for 7@var{n}5 machines, and @samp{7100LC}
5136 for 7@var{n}2 machines. @samp{7100} is the default for @var{cpu type}.
5138 Note the @samp{7100LC} scheduling information is incomplete and using
5139 @samp{7100LC} often leads to bad schedules. For now it's probably best
5140 to use @samp{7100} instead of @samp{7100LC} for the 7@var{n}2 machines.
5143 Enable the optimization pass in the HPUX linker. Note this makes symbolic
5144 debugging impossible. It also triggers a bug in the HPUX 8 and HPUX 9 linkers
5145 in which they give bogus error messages when linking some programs.
5148 Generate output containing library calls for floating point.
5149 @strong{Warning:} the requisite libraries are not available for all HPPA
5150 targets. Normally the facilities of the machine's usual C compiler are
5151 used, but this cannot be done directly in cross-compilation. You must make
5152 your own arrangements to provide suitable library functions for
5153 cross-compilation. The embedded target @samp{hppa1.1-*-pro}
5154 does provide software floating point support.
5156 @samp{-msoft-float} changes the calling convention in the output file;
5157 therefore, it is only useful if you compile @emph{all} of a program with
5158 this option. In particular, you need to compile @file{libgcc.a}, the
5159 library that comes with GNU CC, with @samp{-msoft-float} in order for
5163 @node Intel 960 Options
5164 @subsection Intel 960 Options
5166 These @samp{-m} options are defined for the Intel 960 implementations:
5169 @item -m@var{cpu type}
5170 Assume the defaults for the machine type @var{cpu type} for some of
5171 the other options, including instruction scheduling, floating point
5172 support, and addressing modes. The choices for @var{cpu type} are
5173 @samp{ka}, @samp{kb}, @samp{mc}, @samp{ca}, @samp{cf},
5174 @samp{sa}, and @samp{sb}.
5180 The @samp{-mnumerics} option indicates that the processor does support
5181 floating-point instructions. The @samp{-msoft-float} option indicates
5182 that floating-point support should not be assumed.
5184 @item -mleaf-procedures
5185 @itemx -mno-leaf-procedures
5186 Do (or do not) attempt to alter leaf procedures to be callable with the
5187 @code{bal} instruction as well as @code{call}. This will result in more
5188 efficient code for explicit calls when the @code{bal} instruction can be
5189 substituted by the assembler or linker, but less efficient code in other
5190 cases, such as calls via function pointers, or using a linker that doesn't
5191 support this optimization.
5194 @itemx -mno-tail-call
5195 Do (or do not) make additional attempts (beyond those of the
5196 machine-independent portions of the compiler) to optimize tail-recursive
5197 calls into branches. You may not want to do this because the detection of
5198 cases where this is not valid is not totally complete. The default is
5199 @samp{-mno-tail-call}.
5201 @item -mcomplex-addr
5202 @itemx -mno-complex-addr
5203 Assume (or do not assume) that the use of a complex addressing mode is a
5204 win on this implementation of the i960. Complex addressing modes may not
5205 be worthwhile on the K-series, but they definitely are on the C-series.
5206 The default is currently @samp{-mcomplex-addr} for all processors except
5210 @itemx -mno-code-align
5211 Align code to 8-byte boundaries for faster fetching (or don't bother).
5212 Currently turned on by default for C-series implementations only.
5215 @item -mclean-linkage
5216 @itemx -mno-clean-linkage
5217 These options are not fully implemented.
5221 @itemx -mic2.0-compat
5222 @itemx -mic3.0-compat
5223 Enable compatibility with iC960 v2.0 or v3.0.
5227 Enable compatibility with the iC960 assembler.
5229 @item -mstrict-align
5230 @itemx -mno-strict-align
5231 Do not permit (do permit) unaligned accesses.
5234 Enable structure-alignment compatibility with Intel's gcc release version
5235 1.3 (based on gcc 1.37). This option implies @samp{-mstrict-align}.
5238 @node DEC Alpha Options
5239 @subsection DEC Alpha Options
5241 These @samp{-m} options are defined for the DEC Alpha implementations:
5244 @item -mno-soft-float
5246 Use (do not use) the hardware floating-point instructions for
5247 floating-point operations. When @code{-msoft-float} is specified,
5248 functions in @file{libgcc1.c} will be used to perform floating-point
5249 operations. Unless they are replaced by routines that emulate the
5250 floating-point operations, or compiled in such a way as to call such
5251 emulations routines, these routines will issue floating-point
5252 operations. If you are compiling for an Alpha without floating-point
5253 operations, you must ensure that the library is built so as not to call
5256 Note that Alpha implementations without floating-point operations are
5257 required to have floating-point registers.
5261 Generate code that uses (does not use) the floating-point register set.
5262 @code{-mno-fp-regs} implies @code{-msoft-float}. If the floating-point
5263 register set is not used, floating point operands are passed in integer
5264 registers as if they were integers and floating-point results are passed
5265 in $0 instead of $f0. This is a non-standard calling sequence, so any
5266 function with a floating-point argument or return value called by code
5267 compiled with @code{-mno-fp-regs} must also be compiled with that
5270 A typical use of this option is building a kernel that does not use,
5271 and hence need not save and restore, any floating-point registers.
5274 The Alpha architecture implements floating-point hardware optimized for
5275 maximum performance. It is mostly compliant with the IEEE floating
5276 point standard. However, for full compliance, software assistance is
5277 required. This option generates code fully IEEE compliant code
5278 @emph{except} that the @var{inexact flag} is not maintained (see below).
5279 If this option is turned on, the CPP macro @code{_IEEE_FP} is defined
5280 during compilation. The option is a shorthand for: @samp{-D_IEEE_FP
5281 -mfp-trap-mode=su -mtrap-precision=i -mieee-conformant}. The resulting
5282 code is less efficient but is able to correctly support denormalized
5283 numbers and exceptional IEEE values such as not-a-number and plus/minus
5284 infinity. Other Alpha compilers call this option
5285 @code{-ieee_with_no_inexact}.
5287 @item -mieee-with-inexact
5288 @c overfull hbox here --bob 22 jul96
5289 @c original text between ignore ... end ignore
5291 This is like @samp{-mieee} except the generated code also maintains the
5292 IEEE @var{inexact flag}. Turning on this option causes the generated
5293 code to implement fully-compliant IEEE math. The option is a shorthand
5294 for @samp{-D_IEEE_FP -D_IEEE_FP_INEXACT} plus @samp{-mieee-conformant},
5295 @samp{-mfp-trap-mode=sui}, and @samp{-mtrap-precision=i}. On some Alpha
5296 implementations the resulting code may execute significantly slower than
5297 the code generated by default. Since there is very little code that
5298 depends on the @var{inexact flag}, you should normally not specify this
5299 option. Other Alpha compilers call this option
5300 @samp{-ieee_with_inexact}.
5302 @c changed paragraph
5303 This is like @samp{-mieee} except the generated code also maintains the
5304 IEEE @var{inexact flag}. Turning on this option causes the generated
5305 code to implement fully-compliant IEEE math. The option is a shorthand
5306 for @samp{-D_IEEE_FP -D_IEEE_FP_INEXACT} plus the three following:
5307 @samp{-mieee-conformant},
5308 @samp{-mfp-trap-mode=sui},
5309 and @samp{-mtrap-precision=i}.
5310 On some Alpha implementations the resulting code may execute
5311 significantly slower than the code generated by default. Since there
5312 is very little code that depends on the @var{inexact flag}, you should
5313 normally not specify this option. Other Alpha compilers call this
5314 option @samp{-ieee_with_inexact}.
5315 @c end changes to prevent overfull hboxes
5317 @item -mfp-trap-mode=@var{trap mode}
5318 This option controls what floating-point related traps are enabled.
5319 Other Alpha compilers call this option @samp{-fptm }@var{trap mode}.
5320 The trap mode can be set to one of four values:
5324 This is the default (normal) setting. The only traps that are enabled
5325 are the ones that cannot be disabled in software (e.g., division by zero
5329 In addition to the traps enabled by @samp{n}, underflow traps are enabled
5333 Like @samp{su}, but the instructions are marked to be safe for software
5334 completion (see Alpha architecture manual for details).
5337 Like @samp{su}, but inexact traps are enabled as well.
5340 @item -mfp-rounding-mode=@var{rounding mode}
5341 Selects the IEEE rounding mode. Other Alpha compilers call this option
5342 @samp{-fprm }@var{rounding mode}. The @var{rounding mode} can be one
5347 Normal IEEE rounding mode. Floating point numbers are rounded towards
5348 the nearest machine number or towards the even machine number in case
5352 Round towards minus infinity.
5355 Chopped rounding mode. Floating point numbers are rounded towards zero.
5358 Dynamic rounding mode. A field in the floating point control register
5359 (@var{fpcr}, see Alpha architecture reference manual) controls the
5360 rounding mode in effect. The C library initializes this register for
5361 rounding towards plus infinity. Thus, unless your program modifies the
5362 @var{fpcr}, @samp{d} corresponds to round towards plus infinity.@end table
5364 @item -mtrap-precision=@var{trap precision}
5365 In the Alpha architecture, floating point traps are imprecise. This
5366 means without software assistance it is impossible to recover from a
5367 floating trap and program execution normally needs to be terminated.
5368 GNU CC can generate code that can assist operating system trap handlers
5369 in determining the exact location that caused a floating point trap.
5370 Depending on the requirements of an application, different levels of
5371 precisions can be selected:
5375 Program precision. This option is the default and means a trap handler
5376 can only identify which program caused a floating point exception.
5379 Function precision. The trap handler can determine the function that
5380 caused a floating point exception.
5383 Instruction precision. The trap handler can determine the exact
5384 instruction that caused a floating point exception.
5387 Other Alpha compilers provide the equivalent options called
5388 @samp{-scope_safe} and @samp{-resumption_safe}.
5390 @item -mieee-conformant
5391 This option marks the generated code as IEEE conformant. You must not
5392 use this option unless you also specify @samp{-mtrap-precision=i} and either
5393 @samp{-mfp-trap-mode=su} or @samp{-mfp-trap-mode=sui}. Its only effect
5394 is to emit the line @samp{.eflag 48} in the function prologue of the
5395 generated assembly file. Under DEC Unix, this has the effect that
5396 IEEE-conformant math library routines will be linked in.
5398 @item -mbuild-constants
5399 Normally GNU CC examines a 32- or 64-bit integer constant to
5400 see if it can construct it from smaller constants in two or three
5401 instructions. If it cannot, it will output the constant as a literal and
5402 generate code to load it from the data segment at runtime.
5404 Use this option to require GNU CC to construct @emph{all} integer constants
5405 using code, even if it takes more instructions (the maximum is six).
5407 You would typically use this option to build a shared library dynamic
5408 loader. Itself a shared library, it must relocate itself in memory
5409 before it can find the variables and constants in its own data segment.
5413 Select whether to generate code to be assembled by the vendor-supplied
5414 assembler (@samp{-malpha-as}) or by the GNU assembler @samp{-mgas}.
5422 Indicate whether GNU CC should generate code to use the optional BWX,
5423 CIX, and MAX instruction sets. The default is to use the instruction sets
5424 supported by the CPU type specified via @samp{-mcpu=} option or that
5425 of the CPU on which GNU CC was built if none was specified.
5427 @item -mcpu=@var{cpu_type}
5428 Set the instruction set, register set, and instruction scheduling
5429 parameters for machine type @var{cpu_type}. You can specify either the
5430 @samp{EV} style name or the corresponding chip number. GNU CC
5431 supports scheduling parameters for the EV4 and EV5 family of processors
5432 and will choose the default values for the instruction set from
5433 the processor you specify. If you do not specify a processor type,
5434 GNU CC will default to the processor on which the compiler was built.
5436 Supported values for @var{cpu_type} are
5441 Schedules as an EV4 and has no instruction set extensions.
5445 Schedules as an EV5 and has no instruction set extensions.
5449 Schedules as an EV5 and supports the BWX extension.
5454 Schedules as an EV5 and supports the BWX and MAX extensions.
5458 Schedules as an EV5 (until Digital releases the scheduling parameters
5459 for the EV6) and supports the BWX, CIX, and MAX extensions.
5462 @item -mmemory-latency=@var{time}
5463 Sets the latency the scheduler should assume for typical memory
5464 references as seen by the application. This number is highly
5465 dependant on the memory access patterns used by the application
5466 and the size of the external cache on the machine.
5468 Valid options for @var{time} are
5472 A decimal number representing clock cycles.
5478 The compiler contains estimates of the number of clock cycles for
5479 ``typical'' EV4 & EV5 hardware for the Level 1, 2 & 3 caches
5480 (also called Dcache, Scache, and Bcache), as well as to main memory.
5481 Note that L3 is only valid for EV5.
5486 @node Clipper Options
5487 @subsection Clipper Options
5489 These @samp{-m} options are defined for the Clipper implementations:
5493 Produce code for a C300 Clipper processor. This is the default.
5496 Produce code for a C400 Clipper processor i.e. use floating point
5500 @node H8/300 Options
5501 @subsection H8/300 Options
5503 These @samp{-m} options are defined for the H8/300 implementations:
5507 Shorten some address references at link time, when possible; uses the
5508 linker option @samp{-relax}. @xref{H8/300,, @code{ld} and the H8/300,
5509 ld.info, Using ld}, for a fuller description.
5512 Generate code for the H8/300H.
5515 Generate code for the H8/S.
5518 Make @code{int} data 32 bits by default.
5521 On the h8/300h, use the same alignment rules as for the h8/300.
5522 The default for the h8/300h is to align longs and floats on 4 byte boundaries.
5523 @samp{-malign-300} causes them to be aligned on 2 byte boundaries.
5524 This option has no effect on the h8/300.
5528 @subsection SH Options
5530 These @samp{-m} options are defined for the SH implementations:
5534 Generate code for the SH1.
5537 Generate code for the SH2.
5540 Generate code for the SH3.
5543 Generate code for the SH3e.
5546 Compile code for the processor in big endian mode.
5549 Compile code for the processor in little endian mode.
5552 Align doubles at 64 bit boundaries. Note that this changes the calling
5553 conventions, and thus some functions from the standard C library will
5554 not work unless you recompile it first with -mdalign.
5557 Shorten some address references at link time, when possible; uses the
5558 linker option @samp{-relax}.
5561 @node System V Options
5562 @subsection Options for System V
5564 These additional options are available on System V Release 4 for
5565 compatibility with other compilers on those systems:
5569 Create a shared object.
5570 It is recommended that @samp{-symbolic} or @samp{-shared} be used instead.
5573 Identify the versions of each tool used by the compiler, in a
5574 @code{.ident} assembler directive in the output.
5577 Refrain from adding @code{.ident} directives to the output file (this is
5580 @item -YP,@var{dirs}
5581 Search the directories @var{dirs}, and no others, for libraries
5582 specified with @samp{-l}.
5585 Look in the directory @var{dir} to find the M4 preprocessor.
5586 The assembler uses this option.
5587 @c This is supposed to go with a -Yd for predefined M4 macro files, but
5588 @c the generic assembler that comes with Solaris takes just -Ym.
5592 @subsection V850 Options
5593 @cindex V850 Options
5595 These @samp{-m} options are defined for V850 implementations:
5599 @itemx -mno-long-calls
5600 Treat all calls as being far away (near). If calls are assumed to be
5601 far away, the compiler will always load the functions address up into a
5602 register, and call indirect through the pointer.
5606 Do not optimize (do optimize) basic blocks that use the same index
5607 pointer 4 or more times to copy pointer into the @code{ep} register, and
5608 use the shorter @code{sld} and @code{sst} instructions. The @samp{-mep}
5609 option is on by default if you optimize.
5611 @item -mno-prolog-function
5612 @itemx -mprolog-function
5613 Do not use (do use) external functions to save and restore registers at
5614 the prolog and epilog of a function. The external functions are slower,
5615 but use less code space if more than one function saves the same number
5616 of registers. The @samp{-mprolog-function} option is on by default if
5620 Try to make the code as small as possible. At present, this just turns
5621 on the @samp{-mep} and @samp{-mprolog-function} options.
5624 Put static or global variables whose size is @var{n} bytes or less into
5625 the tiny data area that register @code{ep} points to. The tiny data
5626 area can hold up to 256 bytes in total (128 bytes for byte references).
5629 Put static or global variables whose size is @var{n} bytes or less into
5630 the small data area that register @code{gp} points to. The small data
5631 area can hold up to 64 kilobytes.
5634 Put static or global variables whose size is @var{n} bytes or less into
5635 the first 32 kilobytes of memory.
5638 Specify that the target processor is the V850.
5641 Generate code suitable for big switch tables. Use this option only if
5642 the assembler/linker complain about out of range branches within a switch
5647 @subsection ARC Options
5650 These options are defined for ARC implementations:
5654 Compile code for little endian mode. This is the default.
5657 Compile code for big endian mode.
5660 Prepend the name of the cpu to all public symbol names.
5661 In multiple-processor systems, there are many ARC variants with different
5662 instruction and register set characteristics. This flag prevents code
5663 compiled for one cpu to be linked with code compiled for another.
5664 No facility exists for handling variants that are "almost identical".
5665 This is an all or nothing option.
5667 @item -mcpu=@var{cpu}
5668 Compile code for ARC variant @var{cpu}.
5669 Which variants are supported depend on the configuration.
5670 All variants support @samp{-mcpu=base}, this is the default.
5672 @item -mtext=@var{text section}
5673 @item -mdata=@var{data section}
5674 @item -mrodata=@var{readonly data section}
5675 Put functions, data, and readonly data in @var{text section},
5676 @var{data section}, and @var{readonly data section} respectively
5677 by default. This can be overridden with the @code{section} attribute.
5678 @xref{Variable Attributes}
5683 @node Code Gen Options
5684 @section Options for Code Generation Conventions
5685 @cindex code generation conventions
5686 @cindex options, code generation
5687 @cindex run-time options
5689 These machine-independent options control the interface conventions
5690 used in code generation.
5692 Most of them have both positive and negative forms; the negative form
5693 of @samp{-ffoo} would be @samp{-fno-foo}. In the table below, only
5694 one of the forms is listed---the one which is not the default. You
5695 can figure out the other form by either removing @samp{no-} or adding
5700 Enable exception handling, and generate extra code needed to propagate
5701 exceptions. If you do not specify this option, GNU CC enables it by
5702 default for languages like C++ that normally require exception handling,
5703 and disabled for languages like C that do not normally require it.
5704 However, when compiling C code that needs to interoperate properly with
5705 exception handlers written in C++, you may need to enable this option.
5706 You may also wish to disable this option is you are compiling older C++
5707 programs that don't use exception handling.
5709 @item -fpcc-struct-return
5710 Return ``short'' @code{struct} and @code{union} values in memory like
5711 longer ones, rather than in registers. This convention is less
5712 efficient, but it has the advantage of allowing intercallability between
5713 GNU CC-compiled files and files compiled with other compilers.
5715 The precise convention for returning structures in memory depends
5716 on the target configuration macros.
5718 Short structures and unions are those whose size and alignment match
5719 that of some integer type.
5721 @item -freg-struct-return
5722 Use the convention that @code{struct} and @code{union} values are
5723 returned in registers when possible. This is more efficient for small
5724 structures than @samp{-fpcc-struct-return}.
5726 If you specify neither @samp{-fpcc-struct-return} nor its contrary
5727 @samp{-freg-struct-return}, GNU CC defaults to whichever convention is
5728 standard for the target. If there is no standard convention, GNU CC
5729 defaults to @samp{-fpcc-struct-return}, except on targets where GNU CC
5730 is the principal compiler. In those cases, we can choose the standard,
5731 and we chose the more efficient register return alternative.
5734 Allocate to an @code{enum} type only as many bytes as it needs for the
5735 declared range of possible values. Specifically, the @code{enum} type
5736 will be equivalent to the smallest integer type which has enough room.
5738 @item -fshort-double
5739 Use the same size for @code{double} as for @code{float}.
5742 Requests that the data and non-@code{const} variables of this
5743 compilation be shared data rather than private data. The distinction
5744 makes sense only on certain operating systems, where shared data is
5745 shared between processes running the same program, while private data
5746 exists in one copy per process.
5749 Allocate even uninitialized global variables in the bss section of the
5750 object file, rather than generating them as common blocks. This has the
5751 effect that if the same variable is declared (without @code{extern}) in
5752 two different compilations, you will get an error when you link them.
5753 The only reason this might be useful is if you wish to verify that the
5754 program will work on other systems which always work this way.
5757 Ignore the @samp{#ident} directive.
5759 @item -fno-gnu-linker
5760 Do not output global initializations (such as C++ constructors and
5761 destructors) in the form used by the GNU linker (on systems where the GNU
5762 linker is the standard method of handling them). Use this option when
5763 you want to use a non-GNU linker, which also requires using the
5764 @code{collect2} program to make sure the system linker includes
5765 constructors and destructors. (@code{collect2} is included in the GNU CC
5766 distribution.) For systems which @emph{must} use @code{collect2}, the
5767 compiler driver @code{gcc} is configured to do this automatically.
5769 @item -finhibit-size-directive
5770 Don't output a @code{.size} assembler directive, or anything else that
5771 would cause trouble if the function is split in the middle, and the
5772 two halves are placed at locations far apart in memory. This option is
5773 used when compiling @file{crtstuff.c}; you should not need to use it
5777 Put extra commentary information in the generated assembly code to
5778 make it more readable. This option is generally only of use to those
5779 who actually need to read the generated assembly code (perhaps while
5780 debugging the compiler itself).
5782 @samp{-fno-verbose-asm}, the default, causes the
5783 extra information to be omitted and is useful when comparing two assembler
5787 Consider all memory references through pointers to be volatile.
5789 @item -fvolatile-global
5790 Consider all memory references to extern and global data items to
5794 @cindex global offset table
5796 Generate position-independent code (PIC) suitable for use in a shared
5797 library, if supported for the target machine. Such code accesses all
5798 constant addresses through a global offset table (GOT). The dynamic
5799 loader resolves the GOT entries when the program starts (the dynamic
5800 loader is not part of GNU CC; it is part of the operating system). If
5801 the GOT size for the linked executable exceeds a machine-specific
5802 maximum size, you get an error message from the linker indicating that
5803 @samp{-fpic} does not work; in that case, recompile with @samp{-fPIC}
5804 instead. (These maximums are 16k on the m88k, 8k on the Sparc, and 32k
5805 on the m68k and RS/6000. The 386 has no such limit.)
5807 Position-independent code requires special support, and therefore works
5808 only on certain machines. For the 386, GNU CC supports PIC for System V
5809 but not for the Sun 386i. Code generated for the IBM RS/6000 is always
5810 position-independent.
5813 If supported for the target machine, emit position-independent code,
5814 suitable for dynamic linking and avoiding any limit on the size of the
5815 global offset table. This option makes a difference on the m68k, m88k,
5818 Position-independent code requires special support, and therefore works
5819 only on certain machines.
5821 @item -ffixed-@var{reg}
5822 Treat the register named @var{reg} as a fixed register; generated code
5823 should never refer to it (except perhaps as a stack pointer, frame
5824 pointer or in some other fixed role).
5826 @var{reg} must be the name of a register. The register names accepted
5827 are machine-specific and are defined in the @code{REGISTER_NAMES}
5828 macro in the machine description macro file.
5830 This flag does not have a negative form, because it specifies a
5833 @item -fcall-used-@var{reg}
5834 Treat the register named @var{reg} as an allocable register that is
5835 clobbered by function calls. It may be allocated for temporaries or
5836 variables that do not live across a call. Functions compiled this way
5837 will not save and restore the register @var{reg}.
5839 Use of this flag for a register that has a fixed pervasive role in the
5840 machine's execution model, such as the stack pointer or frame pointer,
5841 will produce disastrous results.
5843 This flag does not have a negative form, because it specifies a
5846 @item -fcall-saved-@var{reg}
5847 Treat the register named @var{reg} as an allocable register saved by
5848 functions. It may be allocated even for temporaries or variables that
5849 live across a call. Functions compiled this way will save and restore
5850 the register @var{reg} if they use it.
5852 Use of this flag for a register that has a fixed pervasive role in the
5853 machine's execution model, such as the stack pointer or frame pointer,
5854 will produce disastrous results.
5856 A different sort of disaster will result from the use of this flag for
5857 a register in which function values may be returned.
5859 This flag does not have a negative form, because it specifies a
5863 Pack all structure members together without holes. Usually you would
5864 not want to use this option, since it makes the code suboptimal, and
5865 the offsets of structure members won't agree with system libraries.
5867 @item -fcheck-memory-usage
5868 Generate extra code to check each memory access. GNU CC will generate
5869 code that is suitable for a detector of bad memory accesses such as
5870 @file{Checker}. If you specify this option, you can not use the
5871 @code{asm} or @code{__asm__} keywords.
5873 You must also specify this option when you compile functions you call that
5874 have side effects. If you do not, you may get erroneous messages from
5875 the detector. Normally, you should compile all your code with this option.
5876 If you use functions from a library that have side-effects (such as
5877 @code{read}), you may not be able to recompile the library and
5878 specify this option. In that case, you can enable the
5879 @samp{-fprefix-function-name} option, which requests GNU CC to encapsulate
5880 your code and make other functions look as if they were compiled with
5881 @samp{-fcheck-memory-usage}. This is done by calling ``stubs'',
5882 which are provided by the detector. If you cannot find or build
5883 stubs for every function you call, you may have to specify
5884 @samp{-fcheck-memory-usage} without @samp{-fprefix-function-name}.
5886 @item -fprefix-function-name
5887 Request GNU CC to add a prefix to the symbols generated for function names.
5888 GNU CC adds a prefix to the names of functions defined as well as
5889 functions called. Code compiled with this option and code compiled
5890 without the option can't be linked together, unless or stubs are used.
5892 If you compile the following code with @samp{-fprefix-function-name}
5894 extern void bar (int);
5904 GNU CC will compile the code as if it was written:
5906 extern void prefix_bar (int);
5910 return prefix_bar (a + 5);
5913 This option is designed to be used with @samp{-fcheck-memory-usage}.
5915 @item -finstrument-functions
5916 Generate instrumentation calls for entry and exit to functions. Just
5917 after function entry and just before function exit, the following
5918 profiling functions will be called with the address of the current
5919 function and its call site. (On some platforms,
5920 @code{__builtin_return_address} does not work beyond the current
5921 function, so the call site information may not be available to the
5922 profiling functions otherwise.)
5925 void __cyg_profile_func_enter (void *this_fn, void *call_site);
5926 void __cyg_profile_func_exit (void *this_fn, void *call_site);
5929 The first argument is the address of the start of the current function,
5930 which may be looked up exactly in the symbol table.
5932 This instrumentation is also done for functions expanded inline in other
5933 functions. The profiling calls will indicate where, conceptually, the
5934 inline function is entered and exited. This means that addressable
5935 versions of such functions must be available. If all your uses of a
5936 function are expanded inline, this may mean an additional expansion of
5937 code size. If you use @samp{extern inline} in your C code, an
5938 addressable version of such functions must be provided. (This is
5939 normally the case anyways, but if you get lucky and the optimizer always
5940 expands the functions inline, you might have gotten away without
5941 providing static copies.)
5943 A function may be given the attribute @code{no_instrument_function}, in
5944 which case this instrumentation will not be done. This can be used, for
5945 example, for the profiling functions listed above, high-priority
5946 interrupt routines, and any functions from which the profiling functions
5947 cannot safely be called (perhaps signal handlers, if the profiling
5948 routines generate output or allocate memory).
5951 Generate code to verify that you do not go beyond the boundary of the
5952 stack. You should specify this flag if you are running in an
5953 environment with multiple threads, but only rarely need to specify it in
5954 a single-threaded environment since stack overflow is automatically
5955 detected on nearly all systems if there is only one stack.
5958 Enable exception handling. For some targets, this implies
5959 generation of frame unwind information for all functions, which can produce
5960 significant data size overhead, though it does not affect execution.
5962 This option is on by default for languages that support exception
5963 handling (such as C++), and off for those that don't (such as C).
5967 Control whether virtual function definitions in classes are used to
5968 generate code, or only to define interfaces for their callers. (C++
5971 These options are provided for compatibility with @code{cfront} 1.x
5972 usage; the recommended alternative GNU C++ usage is in flux. @xref{C++
5973 Interface,,Declarations and Definitions in One Header}.
5975 With @samp{+e0}, virtual function definitions in classes are declared
5976 @code{extern}; the declaration is used only as an interface
5977 specification, not to generate code for the virtual functions (in this
5980 With @samp{+e1}, G++ actually generates the code implementing virtual
5981 functions defined in the code, and makes them publicly visible.
5983 @cindex aliasing of parameters
5984 @cindex parameters, aliased
5985 @item -fargument-alias
5986 @itemx -fargument-noalias
5987 @itemx -fargument-noalias-global
5988 Specify the possible relationships among parameters and between
5989 parameters and global data.
5991 @samp{-fargument-alias} specifies that arguments (parameters) may
5992 alias each other and may alias global storage.
5993 @samp{-fargument-noalias} specifies that arguments do not alias
5994 each other, but may alias global storage.
5995 @samp{-fargument-noalias-global} specifies that arguments do not
5996 alias each other and do not alias global storage.
5998 Each language will automatically use whatever option is required by
5999 the language standard. You should not need to use these options yourself.
6002 @node Environment Variables
6003 @section Environment Variables Affecting GNU CC
6004 @cindex environment variables
6006 This section describes several environment variables that affect how GNU
6007 CC operates. Some of them work by specifying directories or prefixes to use
6008 when searching for various kinds of files. Some are used to specify other
6009 aspects of the compilation environment.
6012 Note that you can also specify places to search using options such as
6013 @samp{-B}, @samp{-I} and @samp{-L} (@pxref{Directory Options}). These
6014 take precedence over places specified using environment variables, which
6015 in turn take precedence over those specified by the configuration of GNU
6019 Note that you can also specify places to search using options such as
6020 @samp{-B}, @samp{-I} and @samp{-L} (@pxref{Directory Options}). These
6021 take precedence over places specified using environment variables, which
6022 in turn take precedence over those specified by the configuration of GNU
6029 If @code{TMPDIR} is set, it specifies the directory to use for temporary
6030 files. GNU CC uses temporary files to hold the output of one stage of
6031 compilation which is to be used as input to the next stage: for example,
6032 the output of the preprocessor, which is the input to the compiler
6035 @item GCC_EXEC_PREFIX
6036 @findex GCC_EXEC_PREFIX
6037 If @code{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the
6038 names of the subprograms executed by the compiler. No slash is added
6039 when this prefix is combined with the name of a subprogram, but you can
6040 specify a prefix that ends with a slash if you wish.
6042 If GNU CC cannot find the subprogram using the specified prefix, it
6043 tries looking in the usual places for the subprogram.
6045 The default value of @code{GCC_EXEC_PREFIX} is
6046 @file{@var{prefix}/lib/gcc-lib/} where @var{prefix} is the value
6047 of @code{prefix} when you ran the @file{configure} script.
6049 Other prefixes specified with @samp{-B} take precedence over this prefix.
6051 This prefix is also used for finding files such as @file{crt0.o} that are
6054 In addition, the prefix is used in an unusual way in finding the
6055 directories to search for header files. For each of the standard
6056 directories whose name normally begins with @samp{/usr/local/lib/gcc-lib}
6057 (more precisely, with the value of @code{GCC_INCLUDE_DIR}), GNU CC tries
6058 replacing that beginning with the specified prefix to produce an
6059 alternate directory name. Thus, with @samp{-Bfoo/}, GNU CC will search
6060 @file{foo/bar} where it would normally search @file{/usr/local/lib/bar}.
6061 These alternate directories are searched first; the standard directories
6065 @findex COMPILER_PATH
6066 The value of @code{COMPILER_PATH} is a colon-separated list of
6067 directories, much like @code{PATH}. GNU CC tries the directories thus
6068 specified when searching for subprograms, if it can't find the
6069 subprograms using @code{GCC_EXEC_PREFIX}.
6072 @findex LIBRARY_PATH
6073 The value of @code{LIBRARY_PATH} is a colon-separated list of
6074 directories, much like @code{PATH}. When configured as a native compiler,
6075 GNU CC tries the directories thus specified when searching for special
6076 linker files, if it can't find them using @code{GCC_EXEC_PREFIX}. Linking
6077 using GNU CC also uses these directories when searching for ordinary
6078 libraries for the @samp{-l} option (but directories specified with
6079 @samp{-L} come first).
6081 @item C_INCLUDE_PATH
6082 @itemx CPLUS_INCLUDE_PATH
6083 @itemx OBJC_INCLUDE_PATH
6084 @findex C_INCLUDE_PATH
6085 @findex CPLUS_INCLUDE_PATH
6086 @findex OBJC_INCLUDE_PATH
6087 @c @itemx OBJCPLUS_INCLUDE_PATH
6088 These environment variables pertain to particular languages. Each
6089 variable's value is a colon-separated list of directories, much like
6090 @code{PATH}. When GNU CC searches for header files, it tries the
6091 directories listed in the variable for the language you are using, after
6092 the directories specified with @samp{-I} but before the standard header
6095 @item DEPENDENCIES_OUTPUT
6096 @findex DEPENDENCIES_OUTPUT
6097 @cindex dependencies for make as output
6098 If this variable is set, its value specifies how to output dependencies
6099 for Make based on the header files processed by the compiler. This
6100 output looks much like the output from the @samp{-M} option
6101 (@pxref{Preprocessor Options}), but it goes to a separate file, and is
6102 in addition to the usual results of compilation.
6104 The value of @code{DEPENDENCIES_OUTPUT} can be just a file name, in
6105 which case the Make rules are written to that file, guessing the target
6106 name from the source file name. Or the value can have the form
6107 @samp{@var{file} @var{target}}, in which case the rules are written to
6108 file @var{file} using @var{target} as the target name.
6112 @cindex locale definition
6113 This variable is used to pass locale information to the compiler. One way in
6114 which this information is used is to determine the character set to be used
6115 when character literals, string literals and comments are parsed in C and C++.
6116 When the compiler is configured to allow multibyte characters,
6117 the following values for @code{LANG} are recognized:
6121 Recognize JIS characters.
6123 Recognize SJIS characters.
6125 Recognize EUCJP characters.
6128 If @code{LANG} is not defined, or if it has some other value, then the
6129 compiler will use mblen and mbtowc as defined by the default locale to
6130 recognize and translate multibyte characters.
6133 @node Running Protoize
6134 @section Running Protoize
6136 The program @code{protoize} is an optional part of GNU C. You can use
6137 it to add prototypes to a program, thus converting the program to ANSI
6138 C in one respect. The companion program @code{unprotoize} does the
6139 reverse: it removes argument types from any prototypes that are found.
6141 When you run these programs, you must specify a set of source files as
6142 command line arguments. The conversion programs start out by compiling
6143 these files to see what functions they define. The information gathered
6144 about a file @var{foo} is saved in a file named @file{@var{foo}.X}.
6146 After scanning comes actual conversion. The specified files are all
6147 eligible to be converted; any files they include (whether sources or
6148 just headers) are eligible as well.
6150 But not all the eligible files are converted. By default,
6151 @code{protoize} and @code{unprotoize} convert only source and header
6152 files in the current directory. You can specify additional directories
6153 whose files should be converted with the @samp{-d @var{directory}}
6154 option. You can also specify particular files to exclude with the
6155 @samp{-x @var{file}} option. A file is converted if it is eligible, its
6156 directory name matches one of the specified directory names, and its
6157 name within the directory has not been excluded.
6159 Basic conversion with @code{protoize} consists of rewriting most
6160 function definitions and function declarations to specify the types of
6161 the arguments. The only ones not rewritten are those for varargs
6164 @code{protoize} optionally inserts prototype declarations at the
6165 beginning of the source file, to make them available for any calls that
6166 precede the function's definition. Or it can insert prototype
6167 declarations with block scope in the blocks where undeclared functions
6170 Basic conversion with @code{unprotoize} consists of rewriting most
6171 function declarations to remove any argument types, and rewriting
6172 function definitions to the old-style pre-ANSI form.
6174 Both conversion programs print a warning for any function declaration or
6175 definition that they can't convert. You can suppress these warnings
6178 The output from @code{protoize} or @code{unprotoize} replaces the
6179 original source file. The original file is renamed to a name ending
6180 with @samp{.save}. If the @samp{.save} file already exists, then
6181 the source file is simply discarded.
6183 @code{protoize} and @code{unprotoize} both depend on GNU CC itself to
6184 scan the program and collect information about the functions it uses.
6185 So neither of these programs will work until GNU CC is installed.
6187 Here is a table of the options you can use with @code{protoize} and
6188 @code{unprotoize}. Each option works with both programs unless
6192 @item -B @var{directory}
6193 Look for the file @file{SYSCALLS.c.X} in @var{directory}, instead of the
6194 usual directory (normally @file{/usr/local/lib}). This file contains
6195 prototype information about standard system functions. This option
6196 applies only to @code{protoize}.
6198 @item -c @var{compilation-options}
6199 Use @var{compilation-options} as the options when running @code{gcc} to
6200 produce the @samp{.X} files. The special option @samp{-aux-info} is
6201 always passed in addition, to tell @code{gcc} to write a @samp{.X} file.
6203 Note that the compilation options must be given as a single argument to
6204 @code{protoize} or @code{unprotoize}. If you want to specify several
6205 @code{gcc} options, you must quote the entire set of compilation options
6206 to make them a single word in the shell.
6208 There are certain @code{gcc} arguments that you cannot use, because they
6209 would produce the wrong kind of output. These include @samp{-g},
6210 @samp{-O}, @samp{-c}, @samp{-S}, and @samp{-o} If you include these in
6211 the @var{compilation-options}, they are ignored.
6214 Rename files to end in @samp{.C} instead of @samp{.c}.
6215 This is convenient if you are converting a C program to C++.
6216 This option applies only to @code{protoize}.
6219 Add explicit global declarations. This means inserting explicit
6220 declarations at the beginning of each source file for each function
6221 that is called in the file and was not declared. These declarations
6222 precede the first function definition that contains a call to an
6223 undeclared function. This option applies only to @code{protoize}.
6225 @item -i @var{string}
6226 Indent old-style parameter declarations with the string @var{string}.
6227 This option applies only to @code{protoize}.
6229 @code{unprotoize} converts prototyped function definitions to old-style
6230 function definitions, where the arguments are declared between the
6231 argument list and the initial @samp{@{}. By default, @code{unprotoize}
6232 uses five spaces as the indentation. If you want to indent with just
6233 one space instead, use @samp{-i " "}.
6236 Keep the @samp{.X} files. Normally, they are deleted after conversion
6240 Add explicit local declarations. @code{protoize} with @samp{-l} inserts
6241 a prototype declaration for each function in each block which calls the
6242 function without any declaration. This option applies only to
6246 Make no real changes. This mode just prints information about the conversions
6247 that would have been done without @samp{-n}.
6250 Make no @samp{.save} files. The original files are simply deleted.
6251 Use this option with caution.
6253 @item -p @var{program}
6254 Use the program @var{program} as the compiler. Normally, the name
6258 Work quietly. Most warnings are suppressed.
6261 Print the version number, just like @samp{-v} for @code{gcc}.
6264 If you need special compiler options to compile one of your program's
6265 source files, then you should generate that file's @samp{.X} file
6266 specially, by running @code{gcc} on that source file with the
6267 appropriate options and the option @samp{-aux-info}. Then run
6268 @code{protoize} on the entire set of files. @code{protoize} will use
6269 the existing @samp{.X} file because it is newer than the source file.
6273 gcc -Dfoo=bar file1.c -aux-info
6278 You need to include the special files along with the rest in the
6279 @code{protoize} command, even though their @samp{.X} files already
6280 exist, because otherwise they won't get converted.
6282 @xref{Protoize Caveats}, for more information on how to use
6283 @code{protoize} successfully.