-This is doc/gcc.info, produced by makeinfo version 4.5 from
+This is doc/gcc.info, produced by makeinfo version 4.11 from
doc/gcc.texi.
INFO-DIR-SECTION Programming
funds for GNU development.
\1f
-File: gcc.info, Node: C Dialect Options, Next: C++ Dialect Options, Prev: Invoking G++, Up: Invoking GCC
+File: gcc.info, Node: i386 and x86-64 Options, Next: HPPA Options, Prev: MIPS Options, Up: Submodel Options
+
+3.17.15 Intel 386 and AMD x86-64 Options
+----------------------------------------
+
+These `-m' options are defined for the i386 and x86-64 family of
+computers:
+
+`-mcpu=CPU-TYPE'
+ Tune to CPU-TYPE everything applicable about the generated code,
+ except for the ABI and the set of available instructions. The
+ choices for CPU-TYPE are `i386', `i486', `i586', `i686',
+ `pentium', `pentium-mmx', `pentiumpro', `pentium2', `pentium3',
+ `pentium4', `k6', `k6-2', `k6-3', `athlon', `athlon-tbird',
+ `athlon-4', `athlon-xp' and `athlon-mp'.
+
+ While picking a specific CPU-TYPE will schedule things
+ appropriately for that particular chip, the compiler will not
+ generate any code that does not run on the i386 without the
+ `-march=CPU-TYPE' option being used. `i586' is equivalent to
+ `pentium' and `i686' is equivalent to `pentiumpro'. `k6' and
+ `athlon' are the AMD chips as opposed to the Intel ones.
+
+`-march=CPU-TYPE'
+ Generate instructions for the machine type CPU-TYPE. The choices
+ for CPU-TYPE are the same as for `-mcpu'. Moreover, specifying
+ `-march=CPU-TYPE' implies `-mcpu=CPU-TYPE'.
+
+`-m386'
+`-m486'
+`-mpentium'
+`-mpentiumpro'
+ These options are synonyms for `-mcpu=i386', `-mcpu=i486',
+ `-mcpu=pentium', and `-mcpu=pentiumpro' respectively. These
+ synonyms are deprecated.
+
+`-mfpmath=UNIT'
+ generate floating point arithmetics for selected unit UNIT. the
+ choices for UNIT are:
+
+ `387'
+ Use the standard 387 floating point coprocessor present
+ majority of chips and emulated otherwise. Code compiled with
+ this option will run almost everywhere. The temporary
+ results are computed in 80bit precesion instead of precision
+ specified by the type resulting in slightly different results
+ compared to most of other chips. See `-ffloat-store' for more
+ detailed description.
+
+ This is the default choice for i386 compiler.
+
+ `sse'
+ Use scalar floating point instructions present in the SSE
+ instruction set. This instruction set is supported by
+ Pentium3 and newer chips, in the AMD line by Athlon-4,
+ Athlon-xp and Athlon-mp chips. The earlier version of SSE
+ instruction set supports only single precision arithmetics,
+ thus the double and extended precision arithmetics is still
+ done using 387. Later version, present only in Pentium4 and
+ the future AMD x86-64 chips supports double precision
+ arithmetics too.
+
+ For i387 you need to use `-march=CPU-TYPE', `-msse' or
+ `-msse2' switches to enable SSE extensions and make this
+ option effective. For x86-64 compiler, these extensions are
+ enabled by default.
+
+ The resulting code should be considerably faster in majority
+ of cases and avoid the numerical instability problems of 387
+ code, but may break some existing code that expects
+ temporaries to be 80bit.
+
+ This is the default choice for x86-64 compiler.
+
+ `sse,387'
+ Attempt to utilize both instruction sets at once. This
+ effectivly double the amount of available registers and on
+ chips with separate execution units for 387 and SSE the
+ execution resources too. Use this option with care, as it is
+ still experimental, because gcc register allocator does not
+ model separate functional units well resulting in instable
+ performance.
+
+`-masm=DIALECT'
+ Output asm instructions using selected DIALECT. Supported choices
+ are `intel' or `att' (the default one).
+
+`-mieee-fp'
+`-mno-ieee-fp'
+ Control whether or not the compiler uses IEEE floating point
+ comparisons. These handle correctly the case where the result of a
+ comparison is unordered.
+
+`-msoft-float'
+ Generate output containing library calls for floating point.
+ *Warning:* the requisite libraries are not part of GCC. Normally
+ the facilities of the machine's usual C compiler are used, but
+ this can't be done directly in cross-compilation. You must make
+ your own arrangements to provide suitable library functions for
+ cross-compilation.
+
+ On machines where a function returns floating point results in the
+ 80387 register stack, some floating point opcodes may be emitted
+ even if `-msoft-float' is used.
+
+`-mno-fp-ret-in-387'
+ Do not use the FPU registers for return values of functions.
+
+ The usual calling convention has functions return values of types
+ `float' and `double' in an FPU register, even if there is no FPU.
+ The idea is that the operating system should emulate an FPU.
+
+ The option `-mno-fp-ret-in-387' causes such values to be returned
+ in ordinary CPU registers instead.
+
+`-mno-fancy-math-387'
+ Some 387 emulators do not support the `sin', `cos' and `sqrt'
+ instructions for the 387. Specify this option to avoid generating
+ those instructions. This option is the default on FreeBSD,
+ OpenBSD and NetBSD. This option is overridden when `-march'
+ indicates that the target cpu will always have an FPU and so the
+ instruction will not need emulation. As of revision 2.6.1, these
+ instructions are not generated unless you also use the
+ `-funsafe-math-optimizations' switch.
+
+`-malign-double'
+`-mno-align-double'
+ Control whether GCC aligns `double', `long double', and `long
+ long' variables on a two word boundary or a one word boundary.
+ Aligning `double' variables on a two word boundary will produce
+ code that runs somewhat faster on a `Pentium' at the expense of
+ more memory.
+
+ *Warning:* if you use the `-malign-double' switch, structures
+ containing the above types will be aligned differently than the
+ published application binary interface specifications for the 386
+ and will not be binary compatible with structures in code compiled
+ without that switch.
+
+`-m128bit-long-double'
+ Control the size of `long double' type. i386 application binary
+ interface specify the size to be 12 bytes, while modern
+ architectures (Pentium and newer) prefer `long double' aligned to
+ 8 or 16 byte boundary. This is impossible to reach with 12 byte
+ long doubles in the array accesses.
+
+ *Warning:* if you use the `-m128bit-long-double' switch, the
+ structures and arrays containing `long double' will change their
+ size as well as function calling convention for function taking
+ `long double' will be modified.
+
+`-m96bit-long-double'
+ Set the size of `long double' to 96 bits as required by the i386
+ application binary interface. This is the default.
+
+`-msvr3-shlib'
+`-mno-svr3-shlib'
+ Control whether GCC places uninitialized local variables into the
+ `bss' or `data' segments. `-msvr3-shlib' places them into `bss'.
+ These options are meaningful only on System V Release 3.
+
+`-mrtd'
+ Use a different function-calling convention, in which functions
+ that take a fixed number of arguments return with the `ret' NUM
+ instruction, which pops their arguments while returning. This
+ saves one instruction in the caller since there is no need to pop
+ the arguments there.
+
+ You can specify that an individual function is called with this
+ calling sequence with the function attribute `stdcall'. You can
+ also override the `-mrtd' option by using the function attribute
+ `cdecl'. *Note Function Attributes::.
+
+ *Warning:* this calling convention is incompatible with the one
+ normally used on Unix, so you cannot use it if you need to call
+ libraries compiled with the Unix compiler.
+
+ Also, you must provide function prototypes for all functions that
+ take variable numbers of arguments (including `printf'); otherwise
+ incorrect code will be generated for calls to those functions.
+
+ In addition, seriously incorrect code will result if you call a
+ function with too many arguments. (Normally, extra arguments are
+ harmlessly ignored.)
+
+`-mregparm=NUM'
+ Control how many registers are used to pass integer arguments. By
+ default, no registers are used to pass arguments, and at most 3
+ registers can be used. You can control this behavior for a
+ specific function by using the function attribute `regparm'.
+ *Note Function Attributes::.
+
+ *Warning:* if you use this switch, and NUM is nonzero, then you
+ must build all modules with the same value, including any
+ libraries. This includes the system libraries and startup modules.
+
+`-mpreferred-stack-boundary=NUM'
+ Attempt to keep the stack boundary aligned to a 2 raised to NUM
+ byte boundary. If `-mpreferred-stack-boundary' is not specified,
+ the default is 4 (16 bytes or 128 bits), except when optimizing
+ for code size (`-Os'), in which case the default is the minimum
+ correct alignment (4 bytes for x86, and 8 bytes for x86-64).
+
+ On Pentium and PentiumPro, `double' and `long double' values
+ should be aligned to an 8 byte boundary (see `-malign-double') or
+ suffer significant run time performance penalties. On Pentium
+ III, the Streaming SIMD Extension (SSE) data type `__m128' suffers
+ similar penalties if it is not 16 byte aligned.
+
+ To ensure proper alignment of this values on the stack, the stack
+ boundary must be as aligned as that required by any value stored
+ on the stack. Further, every function must be generated such that
+ it keeps the stack aligned. Thus calling a function compiled with
+ a higher preferred stack boundary from a function compiled with a
+ lower preferred stack boundary will most likely misalign the
+ stack. It is recommended that libraries that use callbacks always
+ use the default setting.
+
+ This extra alignment does consume extra stack space, and generally
+ increases code size. Code that is sensitive to stack space usage,
+ such as embedded systems and operating system kernels, may want to
+ reduce the preferred alignment to `-mpreferred-stack-boundary=2'.
+
+`-mmmx'
+`-mno-mmx'
+
+`-msse'
+`-mno-sse'
+
+`-msse2'
+`-mno-sse2'
+
+`-m3dnow'
+`-mno-3dnow'
+ These switches enable or disable the use of built-in functions
+ that allow direct access to the MMX, SSE and 3Dnow extensions of
+ the instruction set.
+
+ *Note X86 Built-in Functions::, for details of the functions
+ enabled and disabled by these switches.
+
+ To have SSE/SSE2 instructions generated automatically from
+ floating-point code, see `-mfpmath=sse'.
+
+`-mpush-args'
+`-mno-push-args'
+ Use PUSH operations to store outgoing parameters. This method is
+ shorter and usually equally fast as method using SUB/MOV
+ operations and is enabled by default. In some cases disabling it
+ may improve performance because of improved scheduling and reduced
+ dependencies.
+
+`-maccumulate-outgoing-args'
+ If enabled, the maximum amount of space required for outgoing
+ arguments will be computed in the function prologue. This is
+ faster on most modern CPUs because of reduced dependencies,
+ improved scheduling and reduced stack usage when preferred stack
+ boundary is not equal to 2. The drawback is a notable increase in
+ code size. This switch implies `-mno-push-args'.
+
+`-mthreads'
+ Support thread-safe exception handling on `Mingw32'. Code that
+ relies on thread-safe exception handling must compile and link all
+ code with the `-mthreads' option. When compiling, `-mthreads'
+ defines `-D_MT'; when linking, it links in a special thread helper
+ library `-lmingwthrd' which cleans up per thread exception
+ handling data.
+
+`-mno-align-stringops'
+ Do not align destination of inlined string operations. This
+ switch reduces code size and improves performance in case the
+ destination is already aligned, but gcc don't know about it.
+
+`-minline-all-stringops'
+ By default GCC inlines string operations only when destination is
+ known to be aligned at least to 4 byte boundary. This enables
+ more inlining, increase code size, but may improve performance of
+ code that depends on fast memcpy, strlen and memset for short
+ lengths.
+
+`-momit-leaf-frame-pointer'
+ Don't keep the frame pointer in a register for leaf functions.
+ This avoids the instructions to save, set up and restore frame
+ pointers and makes an extra register available in leaf functions.
+ The option `-fomit-frame-pointer' removes the frame pointer for
+ all functions which might make debugging harder.
+
+ These `-m' switches are supported in addition to the above on AMD
+x86-64 processors in 64-bit environments.
+
+`-m32'
+`-m64'
+ Generate code for a 32-bit or 64-bit environment. The 32-bit
+ environment sets int, long and pointer to 32 bits and generates
+ code that runs on any i386 system. The 64-bit environment sets
+ int to 32 bits and long and pointer to 64 bits and generates code
+ for AMD's x86-64 architecture.
+
+`-mno-red-zone'
+ Do not use a so called red zone for x86-64 code. The red zone is
+ mandated by the x86-64 ABI, it is a 128-byte area beyond the
+ location of the stack pointer that will not be modified by signal
+ or interrupt handlers and therefore can be used for temporary data
+ without adjusting the stack pointer. The flag `-mno-red-zone'
+ disables this red zone.
+
+`-mcmodel=small'
+ Generate code for the small code model: the program and its
+ symbols must be linked in the lower 2 GB of the address space.
+ Pointers are 64 bits. Programs can be statically or dynamically
+ linked. This is the default code model.
+
+`-mcmodel=kernel'
+ Generate code for the kernel code model. The kernel runs in the
+ negative 2 GB of the address space. This model has to be used for
+ Linux kernel code.
+
+`-mcmodel=medium'
+ Generate code for the medium model: The program is linked in the
+ lower 2 GB of the address space but symbols can be located
+ anywhere in the address space. Programs can be statically or
+ dynamically linked, but building of shared libraries are not
+ supported with the medium model.
+
+`-mcmodel=large'
+ Generate code for the large model: This model makes no assumptions
+ about addresses and sizes of sections. Currently GCC does not
+ implement this model.
-Options Controlling C Dialect
-=============================
+\1f
+File: gcc.info, Node: HPPA Options, Next: Intel 960 Options, Prev: i386 and x86-64 Options, Up: Submodel Options
+
+3.17.16 HPPA Options
+--------------------
+
+These `-m' options are defined for the HPPA family of computers:
+
+`-march=ARCHITECTURE-TYPE'
+ Generate code for the specified architecture. The choices for
+ ARCHITECTURE-TYPE are `1.0' for PA 1.0, `1.1' for PA 1.1, and
+ `2.0' for PA 2.0 processors. Refer to `/usr/lib/sched.models' on
+ an HP-UX system to determine the proper architecture option for
+ your machine. Code compiled for lower numbered architectures will
+ run on higher numbered architectures, but not the other way around.
+
+ PA 2.0 support currently requires gas snapshot 19990413 or later.
+ The next release of binutils (current is 2.9.1) will probably
+ contain PA 2.0 support.
+
+`-mpa-risc-1-0'
+`-mpa-risc-1-1'
+`-mpa-risc-2-0'
+ Synonyms for `-march=1.0', `-march=1.1', and `-march=2.0'
+ respectively.
+
+`-mbig-switch'
+ Generate code suitable for big switch tables. Use this option
+ only if the assembler/linker complain about out of range branches
+ within a switch table.
+
+`-mjump-in-delay'
+ Fill delay slots of function calls with unconditional jump
+ instructions by modifying the return pointer for the function call
+ to be the target of the conditional jump.
+
+`-mdisable-fpregs'
+ Prevent floating point registers from being used in any manner.
+ This is necessary for compiling kernels which perform lazy context
+ switching of floating point registers. If you use this option and
+ attempt to perform floating point operations, the compiler will
+ abort.
+
+`-mdisable-indexing'
+ Prevent the compiler from using indexing address modes. This
+ avoids some rather obscure problems when compiling MIG generated
+ code under MACH.
+
+`-mno-space-regs'
+ Generate code that assumes the target has no space registers.
+ This allows GCC to generate faster indirect calls and use unscaled
+ index address modes.
+
+ Such code is suitable for level 0 PA systems and kernels.
+
+`-mfast-indirect-calls'
+ Generate code that assumes calls never cross space boundaries.
+ This allows GCC to emit code which performs faster indirect calls.
+
+ This option will not work in the presence of shared libraries or
+ nested functions.
+
+`-mlong-load-store'
+ Generate 3-instruction load and store sequences as sometimes
+ required by the HP-UX 10 linker. This is equivalent to the `+k'
+ option to the HP compilers.
+
+`-mportable-runtime'
+ Use the portable calling conventions proposed by HP for ELF
+ systems.
+
+`-mgas'
+ Enable the use of assembler directives only GAS understands.
+
+`-mschedule=CPU-TYPE'
+ Schedule code according to the constraints for the machine type
+ CPU-TYPE. The choices for CPU-TYPE are `700' `7100', `7100LC',
+ `7200', and `8000'. Refer to `/usr/lib/sched.models' on an HP-UX
+ system to determine the proper scheduling option for your machine.
+
+`-mlinker-opt'
+ Enable the optimization pass in the HPUX linker. Note this makes
+ symbolic debugging impossible. It also triggers a bug in the HPUX
+ 8 and HPUX 9 linkers in which they give bogus error messages when
+ linking some programs.
+
+`-msoft-float'
+ Generate output containing library calls for floating point.
+ *Warning:* the requisite libraries are not available for all HPPA
+ targets. Normally the facilities of the machine's usual C
+ compiler are used, but this cannot be done directly in
+ cross-compilation. You must make your own arrangements to provide
+ suitable library functions for cross-compilation. The embedded
+ target `hppa1.1-*-pro' does provide software floating point
+ support.
+
+ `-msoft-float' changes the calling convention in the output file;
+ therefore, it is only useful if you compile _all_ of a program with
+ this option. In particular, you need to compile `libgcc.a', the
+ library that comes with GCC, with `-msoft-float' in order for this
+ to work.
+
+\1f
+File: gcc.info, Node: Intel 960 Options, Next: DEC Alpha Options, Prev: HPPA Options, Up: Submodel Options
+
+3.17.17 Intel 960 Options
+-------------------------
+
+These `-m' options are defined for the Intel 960 implementations:
+
+`-mCPU-TYPE'
+ Assume the defaults for the machine type CPU-TYPE for some of the
+ other options, including instruction scheduling, floating point
+ support, and addressing modes. The choices for CPU-TYPE are `ka',
+ `kb', `mc', `ca', `cf', `sa', and `sb'. The default is `kb'.
+
+`-mnumerics'
+`-msoft-float'
+ The `-mnumerics' option indicates that the processor does support
+ floating-point instructions. The `-msoft-float' option indicates
+ that floating-point support should not be assumed.
+
+`-mleaf-procedures'
+`-mno-leaf-procedures'
+ Do (or do not) attempt to alter leaf procedures to be callable
+ with the `bal' instruction as well as `call'. This will result in
+ more efficient code for explicit calls when the `bal' instruction
+ can be substituted by the assembler or linker, but less efficient
+ code in other cases, such as calls via function pointers, or using
+ a linker that doesn't support this optimization.
+
+`-mtail-call'
+`-mno-tail-call'
+ Do (or do not) make additional attempts (beyond those of the
+ machine-independent portions of the compiler) to optimize
+ tail-recursive calls into branches. You may not want to do this
+ because the detection of cases where this is not valid is not
+ totally complete. The default is `-mno-tail-call'.
+
+`-mcomplex-addr'
+`-mno-complex-addr'
+ Assume (or do not assume) that the use of a complex addressing
+ mode is a win on this implementation of the i960. Complex
+ addressing modes may not be worthwhile on the K-series, but they
+ definitely are on the C-series. The default is currently
+ `-mcomplex-addr' for all processors except the CB and CC.
+
+`-mcode-align'
+`-mno-code-align'
+ Align code to 8-byte boundaries for faster fetching (or don't
+ bother). Currently turned on by default for C-series
+ implementations only.
+
+`-mic-compat'
+`-mic2.0-compat'
+`-mic3.0-compat'
+ Enable compatibility with iC960 v2.0 or v3.0.
+
+`-masm-compat'
+`-mintel-asm'
+ Enable compatibility with the iC960 assembler.
+
+`-mstrict-align'
+`-mno-strict-align'
+ Do not permit (do permit) unaligned accesses.
+
+`-mold-align'
+ Enable structure-alignment compatibility with Intel's gcc release
+ version 1.3 (based on gcc 1.37). This option implies
+ `-mstrict-align'.
+
+`-mlong-double-64'
+ Implement type `long double' as 64-bit floating point numbers.
+ Without the option `long double' is implemented by 80-bit floating
+ point numbers. The only reason we have it because there is no
+ 128-bit `long double' support in `fp-bit.c' yet. So it is only
+ useful for people using soft-float targets. Otherwise, we should
+ recommend against use of it.
+
+
+\1f
+File: gcc.info, Node: DEC Alpha Options, Next: DEC Alpha/VMS Options, Prev: Intel 960 Options, Up: Submodel Options
+
+3.17.18 DEC Alpha Options
+-------------------------
+
+These `-m' options are defined for the DEC Alpha implementations:
+
+`-mno-soft-float'
+`-msoft-float'
+ Use (do not use) the hardware floating-point instructions for
+ floating-point operations. When `-msoft-float' is specified,
+ functions in `libgcc.a' will be used to perform floating-point
+ operations. Unless they are replaced by routines that emulate the
+ floating-point operations, or compiled in such a way as to call
+ such emulations routines, these routines will issue floating-point
+ operations. If you are compiling for an Alpha without
+ floating-point operations, you must ensure that the library is
+ built so as not to call them.
+
+ Note that Alpha implementations without floating-point operations
+ are required to have floating-point registers.
+
+`-mfp-reg'
+`-mno-fp-regs'
+ Generate code that uses (does not use) the floating-point register
+ set. `-mno-fp-regs' implies `-msoft-float'. If the floating-point
+ register set is not used, floating point operands are passed in
+ integer registers as if they were integers and floating-point
+ results are passed in `$0' instead of `$f0'. This is a
+ non-standard calling sequence, so any function with a
+ floating-point argument or return value called by code compiled
+ with `-mno-fp-regs' must also be compiled with that option.
+
+ A typical use of this option is building a kernel that does not
+ use, and hence need not save and restore, any floating-point
+ registers.
+
+`-mieee'
+ The Alpha architecture implements floating-point hardware
+ optimized for maximum performance. It is mostly compliant with
+ the IEEE floating point standard. However, for full compliance,
+ software assistance is required. This option generates code fully
+ IEEE compliant code _except_ that the INEXACT-FLAG is not
+ maintained (see below). If this option is turned on, the
+ preprocessor macro `_IEEE_FP' is defined during compilation. The
+ resulting code is less efficient but is able to correctly support
+ denormalized numbers and exceptional IEEE values such as
+ not-a-number and plus/minus infinity. Other Alpha compilers call
+ this option `-ieee_with_no_inexact'.
+
+`-mieee-with-inexact'
+ This is like `-mieee' except the generated code also maintains the
+ IEEE INEXACT-FLAG. Turning on this option causes the generated
+ code to implement fully-compliant IEEE math. In addition to
+ `_IEEE_FP', `_IEEE_FP_EXACT' is defined as a preprocessor macro.
+ On some Alpha implementations the resulting code may execute
+ significantly slower than the code generated by default. Since
+ there is very little code that depends on the INEXACT-FLAG, you
+ should normally not specify this option. Other Alpha compilers
+ call this option `-ieee_with_inexact'.
+
+`-mfp-trap-mode=TRAP-MODE'
+ This option controls what floating-point related traps are enabled.
+ Other Alpha compilers call this option `-fptm TRAP-MODE'. The
+ trap mode can be set to one of four values:
+
+ `n'
+ This is the default (normal) setting. The only traps that
+ are enabled are the ones that cannot be disabled in software
+ (e.g., division by zero trap).
+
+ `u'
+ In addition to the traps enabled by `n', underflow traps are
+ enabled as well.
+
+ `su'
+ Like `su', but the instructions are marked to be safe for
+ software completion (see Alpha architecture manual for
+ details).
+
+ `sui'
+ Like `su', but inexact traps are enabled as well.
+
+`-mfp-rounding-mode=ROUNDING-MODE'
+ Selects the IEEE rounding mode. Other Alpha compilers call this
+ option `-fprm ROUNDING-MODE'. The ROUNDING-MODE can be one of:
+
+ `n'
+ Normal IEEE rounding mode. Floating point numbers are
+ rounded towards the nearest machine number or towards the
+ even machine number in case of a tie.
+
+ `m'
+ Round towards minus infinity.
+
+ `c'
+ Chopped rounding mode. Floating point numbers are rounded
+ towards zero.
+
+ `d'
+ Dynamic rounding mode. A field in the floating point control
+ register (FPCR, see Alpha architecture reference manual)
+ controls the rounding mode in effect. The C library
+ initializes this register for rounding towards plus infinity.
+ Thus, unless your program modifies the FPCR, `d' corresponds
+ to round towards plus infinity.
+
+`-mtrap-precision=TRAP-PRECISION'
+ In the Alpha architecture, floating point traps are imprecise.
+ This means without software assistance it is impossible to recover
+ from a floating trap and program execution normally needs to be
+ terminated. GCC can generate code that can assist operating
+ system trap handlers in determining the exact location that caused
+ a floating point trap. Depending on the requirements of an
+ application, different levels of precisions can be selected:
+
+ `p'
+ Program precision. This option is the default and means a
+ trap handler can only identify which program caused a
+ floating point exception.
+
+ `f'
+ Function precision. The trap handler can determine the
+ function that caused a floating point exception.
+
+ `i'
+ Instruction precision. The trap handler can determine the
+ exact instruction that caused a floating point exception.
+
+ Other Alpha compilers provide the equivalent options called
+ `-scope_safe' and `-resumption_safe'.
+
+`-mieee-conformant'
+ This option marks the generated code as IEEE conformant. You must
+ not use this option unless you also specify `-mtrap-precision=i'
+ and either `-mfp-trap-mode=su' or `-mfp-trap-mode=sui'. Its only
+ effect is to emit the line `.eflag 48' in the function prologue of
+ the generated assembly file. Under DEC Unix, this has the effect
+ that IEEE-conformant math library routines will be linked in.
+
+`-mbuild-constants'
+ Normally GCC examines a 32- or 64-bit integer constant to see if
+ it can construct it from smaller constants in two or three
+ instructions. If it cannot, it will output the constant as a
+ literal and generate code to load it from the data segment at
+ runtime.
+
+ Use this option to require GCC to construct _all_ integer constants
+ using code, even if it takes more instructions (the maximum is
+ six).
+
+ You would typically use this option to build a shared library
+ dynamic loader. Itself a shared library, it must relocate itself
+ in memory before it can find the variables and constants in its
+ own data segment.
+
+`-malpha-as'
+`-mgas'
+ Select whether to generate code to be assembled by the
+ vendor-supplied assembler (`-malpha-as') or by the GNU assembler
+ `-mgas'.
+
+`-mbwx'
+`-mno-bwx'
+`-mcix'
+`-mno-cix'
+`-mfix'
+`-mno-fix'
+`-mmax'
+`-mno-max'
+ Indicate whether GCC should generate code to use the optional BWX,
+ CIX, FIX and MAX instruction sets. The default is to use the
+ instruction sets supported by the CPU type specified via `-mcpu='
+ option or that of the CPU on which GCC was built if none was
+ specified.
+
+`-mfloat-vax'
+`-mfloat-ieee'
+ Generate code that uses (does not use) VAX F and G floating point
+ arithmetic instead of IEEE single and double precision.
+
+`-mexplicit-relocs'
+`-mno-explicit-relocs'
+ Older Alpha assemblers provided no way to generate symbol
+ relocations except via assembler macros. Use of these macros does
+ not allow optimial instruction scheduling. GNU binutils as of
+ version 2.12 supports a new syntax that allows the compiler to
+ explicitly mark which relocations should apply to which
+ instructions. This option is mostly useful for debugging, as GCC
+ detects the capabilities of the assembler when it is built and
+ sets the default accordingly.
+
+`-msmall-data'
+`-mlarge-data'
+ When `-mexplicit-relocs' is in effect, static data is accessed via
+ "gp-relative" relocations. When `-msmall-data' is used, objects 8
+ bytes long or smaller are placed in a "small data area" (the
+ `.sdata' and `.sbss' sections) and are accessed via 16-bit
+ relocations off of the `$gp' register. This limits the size of
+ the small data area to 64KB, but allows the variables to be
+ directly accessed via a single instruction.
+
+ The default is `-mlarge-data'. With this option the data area is
+ limited to just below 2GB. Programs that require more than 2GB of
+ data must use `malloc' or `mmap' to allocate the data in the heap
+ instead of in the program's data segment.
+
+ When generating code for shared libraries, `-fpic' implies
+ `-msmall-data' and `-fPIC' implies `-mlarge-data'.
+
+`-mcpu=CPU_TYPE'
+ Set the instruction set and instruction scheduling parameters for
+ machine type CPU_TYPE. You can specify either the `EV' style name
+ or the corresponding chip number. GCC supports scheduling
+ parameters for the EV4, EV5 and EV6 family of processors and will
+ choose the default values for the instruction set from the
+ processor you specify. If you do not specify a processor type,
+ GCC will default to the processor on which the compiler was built.
+
+ Supported values for CPU_TYPE are
+
+ `ev4'
+
+ `ev45'
+ `21064'
+ Schedules as an EV4 and has no instruction set extensions.
+
+ `ev5'
+ `21164'
+ Schedules as an EV5 and has no instruction set extensions.
+
+ `ev56'
+ `21164a'
+ Schedules as an EV5 and supports the BWX extension.
+
+ `pca56'
+ `21164pc'
+ `21164PC'
+ Schedules as an EV5 and supports the BWX and MAX extensions.
+
+ `ev6'
+ `21264'
+ Schedules as an EV6 and supports the BWX, FIX, and MAX
+ extensions.
+
+ `ev67'
+
+ `21264a'
+ Schedules as an EV6 and supports the BWX, CIX, FIX, and MAX
+ extensions.
+
+`-mtune=CPU_TYPE'
+ Set only the instruction scheduling parameters for machine type
+ CPU_TYPE. The instruction set is not changed.
+
+`-mmemory-latency=TIME'
+ Sets the latency the scheduler should assume for typical memory
+ references as seen by the application. This number is highly
+ dependent on the memory access patterns used by the application
+ and the size of the external cache on the machine.
+
+ Valid options for TIME are
+
+ `NUMBER'
+ A decimal number representing clock cycles.
+
+ `L1'
+ `L2'
+ `L3'
+ `main'
+ The compiler contains estimates of the number of clock cycles
+ for "typical" EV4 & EV5 hardware for the Level 1, 2 & 3 caches
+ (also called Dcache, Scache, and Bcache), as well as to main
+ memory. Note that L3 is only valid for EV5.
+
+
+\1f
+File: gcc.info, Node: DEC Alpha/VMS Options, Next: Clipper Options, Prev: DEC Alpha Options, Up: Submodel Options
+
+3.17.19 DEC Alpha/VMS Options
+-----------------------------
+
+These `-m' options are defined for the DEC Alpha/VMS implementations:
+
+`-mvms-return-codes'
+ Return VMS condition codes from main. The default is to return
+ POSIX style condition (e.g. error) codes.
+
+\1f
+File: gcc.info, Node: Clipper Options, Next: H8/300 Options, Prev: DEC Alpha/VMS Options, Up: Submodel Options
+
+3.17.20 Clipper Options
+-----------------------
+
+These `-m' options are defined for the Clipper implementations:
+
+`-mc300'
+ Produce code for a C300 Clipper processor. This is the default.
+
+`-mc400'
+ Produce code for a C400 Clipper processor, i.e. use floating point
+ registers f8-f15.
+
+\1f
+File: gcc.info, Node: H8/300 Options, Next: SH Options, Prev: Clipper Options, Up: Submodel Options
+
+3.17.21 H8/300 Options
+----------------------
+
+These `-m' options are defined for the H8/300 implementations:
+
+`-mrelax'
+ Shorten some address references at link time, when possible; uses
+ the linker option `-relax'. *Note `ld' and the H8/300:
+ (ld.info)H8/300, for a fuller description.
+
+`-mh'
+ Generate code for the H8/300H.
+
+`-ms'
+ Generate code for the H8/S.
+
+`-ms2600'
+ Generate code for the H8/S2600. This switch must be used with
+ `-ms'.
+
+`-mint32'
+ Make `int' data 32 bits by default.
+
+`-malign-300'
+ On the H8/300H and H8/S, use the same alignment rules as for the
+ H8/300. The default for the H8/300H and H8/S is to align longs
+ and floats on 4 byte boundaries. `-malign-300' causes them to be
+ aligned on 2 byte boundaries. This option has no effect on the
+ H8/300.
+
+\1f
+File: gcc.info, Node: SH Options, Next: System V Options, Prev: H8/300 Options, Up: Submodel Options
+
+3.17.22 SH Options
+------------------
+
+These `-m' options are defined for the SH implementations:
+
+`-m1'
+ Generate code for the SH1.
+
+`-m2'
+ Generate code for the SH2.
+
+`-m3'
+ Generate code for the SH3.
+
+`-m3e'
+ Generate code for the SH3e.
+
+`-m4-nofpu'
+ Generate code for the SH4 without a floating-point unit.
+
+`-m4-single-only'
+ Generate code for the SH4 with a floating-point unit that only
+ supports single-precision arithmetic.
+
+`-m4-single'
+ Generate code for the SH4 assuming the floating-point unit is in
+ single-precision mode by default.
+
+`-m4'
+ Generate code for the SH4.
+
+`-mb'
+ Compile code for the processor in big endian mode.
+
+`-ml'
+ Compile code for the processor in little endian mode.
+
+`-mdalign'
+ Align doubles at 64-bit boundaries. Note that this changes the
+ calling conventions, and thus some functions from the standard C
+ library will not work unless you recompile it first with
+ `-mdalign'.
+
+`-mrelax'
+ Shorten some address references at link time, when possible; uses
+ the linker option `-relax'.
+
+`-mbigtable'
+ Use 32-bit offsets in `switch' tables. The default is to use
+ 16-bit offsets.
+
+`-mfmovd'
+ Enable the use of the instruction `fmovd'.
+
+`-mhitachi'
+ Comply with the calling conventions defined by Hitachi.
+
+`-mnomacsave'
+ Mark the `MAC' register as call-clobbered, even if `-mhitachi' is
+ given.
+
+`-mieee'
+ Increase IEEE-compliance of floating-point code.
+
+`-misize'
+ Dump instruction size and location in the assembly code.
+
+`-mpadstruct'
+ This option is deprecated. It pads structures to multiple of 4
+ bytes, which is incompatible with the SH ABI.
+
+`-mspace'
+ Optimize for space instead of speed. Implied by `-Os'.
+
+`-mprefergot'
+ When generating position-independent code, emit function calls
+ using the Global Offset Table instead of the Procedure Linkage
+ Table.
+
+`-musermode'
+ Generate a library function call to invalidate instruction cache
+ entries, after fixing up a trampoline. This library function call
+ doesn't assume it can write to the whole memory address space.
+ This is the default when the target is `sh-*-linux*'.
+
+\1f
+File: gcc.info, Node: System V Options, Next: TMS320C3x/C4x Options, Prev: SH Options, Up: Submodel Options
+
+3.17.23 Options for System V
+----------------------------
+
+These additional options are available on System V Release 4 for
+compatibility with other compilers on those systems:
+
+`-G'
+ Create a shared object. It is recommended that `-symbolic' or
+ `-shared' be used instead.
+
+`-Qy'
+ Identify the versions of each tool used by the compiler, in a
+ `.ident' assembler directive in the output.
+
+`-Qn'
+ Refrain from adding `.ident' directives to the output file (this is
+ the default).
+
+`-YP,DIRS'
+ Search the directories DIRS, and no others, for libraries
+ specified with `-l'.
+
+`-Ym,DIR'
+ Look in the directory DIR to find the M4 preprocessor. The
+ assembler uses this option.
- The following options control the dialect of C (or languages derived
-from C, such as C++ and Objective-C) that the compiler accepts:
-
-`-ansi'
- In C mode, support all ISO C89 programs. In C++ mode, remove GNU
- extensions that conflict with ISO C++.
-
- This turns off certain features of GCC that are incompatible with
- ISO C89 (when compiling C code), or of standard C++ (when
- compiling C++ code), such as the `asm' and `typeof' keywords, and
- predefined macros such as `unix' and `vax' that identify the type
- of system you are using. It also enables the undesirable and
- rarely used ISO trigraph feature. For the C compiler, it disables
- recognition of C++ style `//' comments as well as the `inline'
- keyword.
-
- The alternate keywords `__asm__', `__extension__', `__inline__'
- and `__typeof__' continue to work despite `-ansi'. You would not
- want to use them in an ISO C program, of course, but it is useful
- to put them in header files that might be included in compilations
- done with `-ansi'. Alternate predefined macros such as `__unix__'
- and `__vax__' are also available, with or without `-ansi'.
-
- The `-ansi' option does not cause non-ISO programs to be rejected
- gratuitously. For that, `-pedantic' is required in addition to
- `-ansi'. *Note Warning Options::.
-
- The macro `__STRICT_ANSI__' is predefined when the `-ansi' option
- is used. Some header files may notice this macro and refrain from
- declaring certain functions or defining certain macros that the
- ISO standard doesn't call for; this is to avoid interfering with
- any programs that might use these names for other things.
-
- Functions which would normally be built in but do not have
- semantics defined by ISO C (such as `alloca' and `ffs') are not
- built-in functions with `-ansi' is used. *Note Other built-in
- functions provided by GCC: Other Builtins, for details of the
- functions affected.
-
-`-std='
- Determine the language standard. This option is currently only
- supported when compiling C. A value for this option must be
- provided; possible values are
-
- `c89'
- `iso9899:1990'
- ISO C89 (same as `-ansi').
-
- `iso9899:199409'
- ISO C89 as modified in amendment 1.
-
- `c99'
- `c9x'
- `iso9899:1999'
- `iso9899:199x'
- ISO C99. Note that this standard is not yet fully supported;
- see `http://gcc.gnu.org/gcc-3.1/c99status.html' for more
- information. The names `c9x' and `iso9899:199x' are
- deprecated.
-
- `gnu89'
- Default, ISO C89 plus GNU extensions (including some C99
- features).
-
- `gnu99'
-
- `gnu9x'
- ISO C99 plus GNU extensions. When ISO C99 is fully
- implemented in GCC, this will become the default. The name
- `gnu9x' is deprecated.
-
-
- Even when this option is not specified, you can still use some of
- the features of newer standards in so far as they do not conflict
- with previous C standards. For example, you may use
- `__restrict__' even when `-std=c99' is not specified.
-
- The `-std' options specifying some version of ISO C have the same
- effects as `-ansi', except that features that were not in ISO C89
- but are in the specified version (for example, `//' comments and
- the `inline' keyword in ISO C99) are not disabled.
-
- *Note Language Standards Supported by GCC: Standards, for details
- of these standard versions.
-
-`-aux-info FILENAME'
- Output to the given filename prototyped declarations for all
- functions declared and/or defined in a translation unit, including
- those in header files. This option is silently ignored in any
- language other than C.
-
- Besides declarations, the file indicates, in comments, the origin
- of each declaration (source file and line), whether the
- declaration was implicit, prototyped or unprototyped (`I', `N' for
- new or `O' for old, respectively, in the first character after the
- line number and the colon), and whether it came from a declaration
- or a definition (`C' or `F', respectively, in the following
- character). In the case of function definitions, a K&R-style list
- of arguments followed by their declarations is also provided,
- inside comments, after the declaration.
-
-`-fno-asm'
- Do not recognize `asm', `inline' or `typeof' as a keyword, so that
- code can use these words as identifiers. You can use the keywords
- `__asm__', `__inline__' and `__typeof__' instead. `-ansi' implies
- `-fno-asm'.
-
- In C++, this switch only affects the `typeof' keyword, since `asm'
- and `inline' are standard keywords. You may want to use the
- `-fno-gnu-keywords' flag instead, which has the same effect. In
- C99 mode (`-std=c99' or `-std=gnu99'), this switch only affects
- the `asm' and `typeof' keywords, since `inline' is a standard
- keyword in ISO C99.
-
-`-fno-builtin'
-`-fno-builtin-FUNCTION (C and Objective-C only)'
- Don't recognize built-in functions that do not begin with
- `__builtin_' as prefix. *Note Other built-in functions provided
- by GCC: Other Builtins, for details of the functions affected,
- including those which are not built-in functions when `-ansi' or
- `-std' options for strict ISO C conformance are used because they
- do not have an ISO standard meaning.
-
- GCC normally generates special code to handle certain built-in
- functions more efficiently; for instance, calls to `alloca' may
- become single instructions that adjust the stack directly, and
- calls to `memcpy' may become inline copy loops. The resulting
- code is often both smaller and faster, but since the function
- calls no longer appear as such, you cannot set a breakpoint on
- those calls, nor can you change the behavior of the functions by
- linking with a different library.
-
- In C++, `-fno-builtin' is always in effect. The `-fbuiltin'
- option has no effect. Therefore, in C++, the only way to get the
- optimization benefits of built-in functions is to call the function
- using the `__builtin_' prefix. The GNU C++ Standard Library uses
- built-in functions to implement many functions (like
- `std::strchr'), so that you automatically get efficient code.
-
- With the `-fno-builtin-FUNCTION' option, not available when
- compiling C++, only the built-in function FUNCTION is disabled.
- FUNCTION must not begin with `__builtin_'. If a function is named
- this is not built-in in this version of GCC, this option is
- ignored. There is no corresponding `-fbuiltin-FUNCTION' option;
- if you wish to enable built-in functions selectively when using
- `-fno-builtin' or `-ffreestanding', you may define macros such as:
-
- #define abs(n) __builtin_abs ((n))
- #define strcpy(d, s) __builtin_strcpy ((d), (s))
-
-`-fhosted'
- Assert that compilation takes place in a hosted environment. This
- implies `-fbuiltin'. A hosted environment is one in which the
- entire standard library is available, and in which `main' has a
- return type of `int'. Examples are nearly everything except a
- kernel. This is equivalent to `-fno-freestanding'.
-
-`-ffreestanding'
- Assert that compilation takes place in a freestanding environment.
- This implies `-fno-builtin'. A freestanding environment is one
- in which the standard library may not exist, and program startup
- may not necessarily be at `main'. The most obvious example is an
- OS kernel. This is equivalent to `-fno-hosted'.
-
- *Note Language Standards Supported by GCC: Standards, for details
- of freestanding and hosted environments.
-
-`-trigraphs'
- Support ISO C trigraphs. The `-ansi' option (and `-std' options
- for strict ISO C conformance) implies `-trigraphs'.
-
-`-no-integrated-cpp'
- Invoke the external cpp during compilation. The default is to use
- the integrated cpp (internal cpp). This option also allows a
- user-supplied cpp via the `-B' option. This flag is applicable in
- both C and C++ modes.
-
- We do not guarantee to retain this option in future, and we may
- change its semantics.
-
-`-traditional'
- Attempt to support some aspects of traditional C compilers.
- Specifically:
-
- * All `extern' declarations take effect globally even if they
- are written inside of a function definition. This includes
- implicit declarations of functions.
-
- * The newer keywords `typeof', `inline', `signed', `const' and
- `volatile' are not recognized. (You can still use the
- alternative keywords such as `__typeof__', `__inline__', and
- so on.)
-
- * Comparisons between pointers and integers are always allowed.
-
- * Integer types `unsigned short' and `unsigned char' promote to
- `unsigned int'.
-
- * Out-of-range floating point literals are not an error.
-
- * Certain constructs which ISO regards as a single invalid
- preprocessing number, such as `0xe-0xd', are treated as
- expressions instead.
-
- * String "constants" are not necessarily constant; they are
- stored in writable space, and identical looking constants are
- allocated separately. (This is the same as the effect of
- `-fwritable-strings'.)
-
- * All automatic variables not declared `register' are preserved
- by `longjmp'. Ordinarily, GNU C follows ISO C: automatic
- variables not declared `volatile' may be clobbered.
-
- * The character escape sequences `\x' and `\a' evaluate as the
- literal characters `x' and `a' respectively. Without
- `-traditional', `\x' is a prefix for the hexadecimal
- representation of a character, and `\a' produces a bell.
-
- This option is deprecated and may be removed.
-
- You may wish to use `-fno-builtin' as well as `-traditional' if
- your program uses names that are normally GNU C built-in functions
- for other purposes of its own.
-
- You cannot use `-traditional' if you include any header files that
- rely on ISO C features. Some vendors are starting to ship systems
- with ISO C header files and you cannot use `-traditional' on such
- systems to compile files that include any system headers.
-
- The `-traditional' option also enables `-traditional-cpp'.
-
-`-traditional-cpp'
- Attempt to support some aspects of traditional C preprocessors.
- See the GNU CPP manual for details.
-
-`-fcond-mismatch'
- Allow conditional expressions with mismatched types in the second
- and third arguments. The value of such an expression is void.
- This option is not supported for C++.
-
-`-funsigned-char'
- Let the type `char' be unsigned, like `unsigned char'.
+\1f
+File: gcc.info, Node: TMS320C3x/C4x Options, Next: V850 Options, Prev: System V Options, Up: Submodel Options
+
+3.17.24 TMS320C3x/C4x Options
+-----------------------------
+
+These `-m' options are defined for TMS320C3x/C4x implementations:
+
+`-mcpu=CPU_TYPE'
+ Set the instruction set, register set, and instruction scheduling
+ parameters for machine type CPU_TYPE. Supported values for
+ CPU_TYPE are `c30', `c31', `c32', `c40', and `c44'. The default
+ is `c40' to generate code for the TMS320C40.
+
+`-mbig-memory'
+
+`-mbig'
+`-msmall-memory'
+`-msmall'
+ Generates code for the big or small memory model. The small memory
+ model assumed that all data fits into one 64K word page. At
+ run-time the data page (DP) register must be set to point to the
+ 64K page containing the .bss and .data program sections. The big
+ memory model is the default and requires reloading of the DP
+ register for every direct memory access.
+
+`-mbk'
+`-mno-bk'
+ Allow (disallow) allocation of general integer operands into the
+ block count register BK.
+
+`-mdb'
+`-mno-db'
+ Enable (disable) generation of code using decrement and branch,
+ DBcond(D), instructions. This is enabled by default for the C4x.
+ To be on the safe side, this is disabled for the C3x, since the
+ maximum iteration count on the C3x is 2^23 + 1 (but who iterates
+ loops more than 2^23 times on the C3x?). Note that GCC will try
+ to reverse a loop so that it can utilise the decrement and branch
+ instruction, but will give up if there is more than one memory
+ reference in the loop. Thus a loop where the loop counter is
+ decremented can generate slightly more efficient code, in cases
+ where the RPTB instruction cannot be utilised.
+
+`-mdp-isr-reload'
+`-mparanoid'
+ Force the DP register to be saved on entry to an interrupt service
+ routine (ISR), reloaded to point to the data section, and restored
+ on exit from the ISR. This should not be required unless someone
+ has violated the small memory model by modifying the DP register,
+ say within an object library.
+
+`-mmpyi'
+`-mno-mpyi'
+ For the C3x use the 24-bit MPYI instruction for integer multiplies
+ instead of a library call to guarantee 32-bit results. Note that
+ if one of the operands is a constant, then the multiplication will
+ be performed using shifts and adds. If the `-mmpyi' option is not
+ specified for the C3x, then squaring operations are performed
+ inline instead of a library call.
+
+`-mfast-fix'
+`-mno-fast-fix'
+ The C3x/C4x FIX instruction to convert a floating point value to an
+ integer value chooses the nearest integer less than or equal to the
+ floating point value rather than to the nearest integer. Thus if
+ the floating point number is negative, the result will be
+ incorrectly truncated an additional code is necessary to detect
+ and correct this case. This option can be used to disable
+ generation of the additional code required to correct the result.
+
+`-mrptb'
+`-mno-rptb'
+ Enable (disable) generation of repeat block sequences using the
+ RPTB instruction for zero overhead looping. The RPTB construct is
+ only used for innermost loops that do not call functions or jump
+ across the loop boundaries. There is no advantage having nested
+ RPTB loops due to the overhead required to save and restore the
+ RC, RS, and RE registers. This is enabled by default with `-O2'.
+
+`-mrpts=COUNT'
+`-mno-rpts'
+ Enable (disable) the use of the single instruction repeat
+ instruction RPTS. If a repeat block contains a single
+ instruction, and the loop count can be guaranteed to be less than
+ the value COUNT, GCC will emit a RPTS instruction instead of a
+ RPTB. If no value is specified, then a RPTS will be emitted even
+ if the loop count cannot be determined at compile time. Note that
+ the repeated instruction following RPTS does not have to be
+ reloaded from memory each iteration, thus freeing up the CPU buses
+ for operands. However, since interrupts are blocked by this
+ instruction, it is disabled by default.
+
+`-mloop-unsigned'
+`-mno-loop-unsigned'
+ The maximum iteration count when using RPTS and RPTB (and DB on
+ the C40) is 2^31 + 1 since these instructions test if the
+ iteration count is negative to terminate the loop. If the
+ iteration count is unsigned there is a possibility than the 2^31 +
+ 1 maximum iteration count may be exceeded. This switch allows an
+ unsigned iteration count.
+
+`-mti'
+ Try to emit an assembler syntax that the TI assembler (asm30) is
+ happy with. This also enforces compatibility with the API
+ employed by the TI C3x C compiler. For example, long doubles are
+ passed as structures rather than in floating point registers.
+
+`-mregparm'
+`-mmemparm'
+ Generate code that uses registers (stack) for passing arguments to
+ functions. By default, arguments are passed in registers where
+ possible rather than by pushing arguments on to the stack.
+
+`-mparallel-insns'
+`-mno-parallel-insns'
+ Allow the generation of parallel instructions. This is enabled by
+ default with `-O2'.
+
+`-mparallel-mpy'
+`-mno-parallel-mpy'
+ Allow the generation of MPY||ADD and MPY||SUB parallel
+ instructions, provided `-mparallel-insns' is also specified.
+ These instructions have tight register constraints which can
+ pessimize the code generation of large functions.
+
+
+\1f
+File: gcc.info, Node: V850 Options, Next: ARC Options, Prev: TMS320C3x/C4x Options, Up: Submodel Options
+
+3.17.25 V850 Options
+--------------------
+
+These `-m' options are defined for V850 implementations:
+
+`-mlong-calls'
+`-mno-long-calls'
+ Treat all calls as being far away (near). If calls are assumed to
+ be far away, the compiler will always load the functions address
+ up into a register, and call indirect through the pointer.
+
+`-mno-ep'
+`-mep'
+ Do not optimize (do optimize) basic blocks that use the same index
+ pointer 4 or more times to copy pointer into the `ep' register, and
+ use the shorter `sld' and `sst' instructions. The `-mep' option
+ is on by default if you optimize.
+
+`-mno-prolog-function'
+`-mprolog-function'
+ Do not use (do use) external functions to save and restore
+ registers at the prolog and epilog of a function. The external
+ functions are slower, but use less code space if more than one
+ function saves the same number of registers. The
+ `-mprolog-function' option is on by default if you optimize.
+
+`-mspace'
+ Try to make the code as small as possible. At present, this just
+ turns on the `-mep' and `-mprolog-function' options.
+
+`-mtda=N'
+ Put static or global variables whose size is N bytes or less into
+ the tiny data area that register `ep' points to. The tiny data
+ area can hold up to 256 bytes in total (128 bytes for byte
+ references).
+
+`-msda=N'
+ Put static or global variables whose size is N bytes or less into
+ the small data area that register `gp' points to. The small data
+ area can hold up to 64 kilobytes.
+
+`-mzda=N'
+ Put static or global variables whose size is N bytes or less into
+ the first 32 kilobytes of memory.
+
+`-mv850'
+ Specify that the target processor is the V850.
+
+`-mbig-switch'
+ Generate code suitable for big switch tables. Use this option
+ only if the assembler/linker complain about out of range branches
+ within a switch table.
+
+\1f
+File: gcc.info, Node: ARC Options, Next: NS32K Options, Prev: V850 Options, Up: Submodel Options
+
+3.17.26 ARC Options
+-------------------
+
+These options are defined for ARC implementations:
+
+`-EL'
+ Compile code for little endian mode. This is the default.
+
+`-EB'
+ Compile code for big endian mode.
+
+`-mmangle-cpu'
+ Prepend the name of the cpu to all public symbol names. In
+ multiple-processor systems, there are many ARC variants with
+ different instruction and register set characteristics. This flag
+ prevents code compiled for one cpu to be linked with code compiled
+ for another. No facility exists for handling variants that are
+ "almost identical". This is an all or nothing option.
+
+`-mcpu=CPU'
+ Compile code for ARC variant CPU. Which variants are supported
+ depend on the configuration. All variants support `-mcpu=base',
+ this is the default.
+
+`-mtext=TEXT-SECTION'
+`-mdata=DATA-SECTION'
+`-mrodata=READONLY-DATA-SECTION'
+ Put functions, data, and readonly data in TEXT-SECTION,
+ DATA-SECTION, and READONLY-DATA-SECTION respectively by default.
+ This can be overridden with the `section' attribute. *Note
+ Variable Attributes::.
+
+
+\1f
+File: gcc.info, Node: NS32K Options, Next: AVR Options, Prev: ARC Options, Up: Submodel Options
+
+3.17.27 NS32K Options
+---------------------
+
+These are the `-m' options defined for the 32000 series. The default
+values for these options depends on which style of 32000 was selected
+when the compiler was configured; the defaults for the most common
+choices are given below.
+
+`-m32032'
+`-m32032'
+ Generate output for a 32032. This is the default when the
+ compiler is configured for 32032 and 32016 based systems.
+
+`-m32332'
+`-m32332'
+ Generate output for a 32332. This is the default when the
+ compiler is configured for 32332-based systems.
+
+`-m32532'
+`-m32532'
+ Generate output for a 32532. This is the default when the
+ compiler is configured for 32532-based systems.
+
+`-m32081'
+ Generate output containing 32081 instructions for floating point.
+ This is the default for all systems.
+
+`-m32381'
+ Generate output containing 32381 instructions for floating point.
+ This also implies `-m32081'. The 32381 is only compatible with
+ the 32332 and 32532 cpus. This is the default for the
+ pc532-netbsd configuration.
+
+`-mmulti-add'
+ Try and generate multiply-add floating point instructions `polyF'
+ and `dotF'. This option is only available if the `-m32381' option
+ is in effect. Using these instructions requires changes to
+ register allocation which generally has a negative impact on
+ performance. This option should only be enabled when compiling
+ code particularly likely to make heavy use of multiply-add
+ instructions.
+
+`-mnomulti-add'
+ Do not try and generate multiply-add floating point instructions
+ `polyF' and `dotF'. This is the default on all platforms.
+
+`-msoft-float'
+ Generate output containing library calls for floating point.
+ *Warning:* the requisite libraries may not be available.
+
+`-mnobitfield'
+ Do not use the bit-field instructions. On some machines it is
+ faster to use shifting and masking operations. This is the
+ default for the pc532.
+
+`-mbitfield'
+ Do use the bit-field instructions. This is the default for all
+ platforms except the pc532.
+
+`-mrtd'
+ Use a different function-calling convention, in which functions
+ that take a fixed number of arguments return pop their arguments
+ on return with the `ret' instruction.
+
+ This calling convention is incompatible with the one normally used
+ on Unix, so you cannot use it if you need to call libraries
+ compiled with the Unix compiler.
+
+ Also, you must provide function prototypes for all functions that
+ take variable numbers of arguments (including `printf'); otherwise
+ incorrect code will be generated for calls to those functions.
+
+ In addition, seriously incorrect code will result if you call a
+ function with too many arguments. (Normally, extra arguments are
+ harmlessly ignored.)
+
+ This option takes its name from the 680x0 `rtd' instruction.
+
+`-mregparam'
+ Use a different function-calling convention where the first two
+ arguments are passed in registers.
+
+ This calling convention is incompatible with the one normally used
+ on Unix, so you cannot use it if you need to call libraries
+ compiled with the Unix compiler.
+
+`-mnoregparam'
+ Do not pass any arguments in registers. This is the default for
+ all targets.
+
+`-msb'
+ It is OK to use the sb as an index register which is always loaded
+ with zero. This is the default for the pc532-netbsd target.
+
+`-mnosb'
+ The sb register is not available for use or has not been
+ initialized to zero by the run time system. This is the default
+ for all targets except the pc532-netbsd. It is also implied
+ whenever `-mhimem' or `-fpic' is set.
+
+`-mhimem'
+ Many ns32000 series addressing modes use displacements of up to
+ 512MB. If an address is above 512MB then displacements from zero
+ can not be used. This option causes code to be generated which
+ can be loaded above 512MB. This may be useful for operating
+ systems or ROM code.
+
+`-mnohimem'
+ Assume code will be loaded in the first 512MB of virtual address
+ space. This is the default for all platforms.
+
+
+\1f
+File: gcc.info, Node: AVR Options, Next: MCore Options, Prev: NS32K Options, Up: Submodel Options
+
+3.17.28 AVR Options
+-------------------
+
+These options are defined for AVR implementations:
+
+`-mmcu=MCU'
+ Specify ATMEL AVR instruction set or MCU type.
+
+ Instruction set avr1 is for the minimal AVR core, not supported by
+ the C compiler, only for assembler programs (MCU types: at90s1200,
+ attiny10, attiny11, attiny12, attiny15, attiny28).
+
+ Instruction set avr2 (default) is for the classic AVR core with up
+ to 8K program memory space (MCU types: at90s2313, at90s2323,
+ attiny22, at90s2333, at90s2343, at90s4414, at90s4433, at90s4434,
+ at90s8515, at90c8534, at90s8535).
+
+ Instruction set avr3 is for the classic AVR core with up to 128K
+ program memory space (MCU types: atmega103, atmega603, at43usb320,
+ at76c711).
+
+ Instruction set avr4 is for the enhanced AVR core with up to 8K
+ program memory space (MCU types: atmega8, atmega83, atmega85).
+
+ Instruction set avr5 is for the enhanced AVR core with up to 128K
+ program memory space (MCU types: atmega16, atmega161, atmega163,
+ atmega32, atmega323, atmega64, atmega128, at43usb355, at94k).
+
+`-msize'
+ Output instruction sizes to the asm file.
+
+`-minit-stack=N'
+ Specify the initial stack address, which may be a symbol or
+ numeric value, `__stack' is the default.
+
+`-mno-interrupts'
+ Generated code is not compatible with hardware interrupts. Code
+ size will be smaller.
+
+`-mcall-prologues'
+ Functions prologues/epilogues expanded as call to appropriate
+ subroutines. Code size will be smaller.
+
+`-mno-tablejump'
+ Do not generate tablejump insns which sometimes increase code size.
- Each kind of machine has a default for what `char' should be. It
- is either like `unsigned char' by default or like `signed char' by
+`-mtiny-stack'
+ Change only the low 8 bits of the stack pointer.
+
+\1f
+File: gcc.info, Node: MCore Options, Next: IA-64 Options, Prev: AVR Options, Up: Submodel Options
+
+3.17.29 MCore Options
+---------------------
+
+These are the `-m' options defined for the Motorola M*Core processors.
+
+`-mhardlit'
+`-mhardlit'
+`-mno-hardlit'
+ Inline constants into the code stream if it can be done in two
+ instructions or less.
+
+`-mdiv'
+`-mdiv'
+`-mno-div'
+ Use the divide instruction. (Enabled by default).
+
+`-mrelax-immediate'
+`-mrelax-immediate'
+`-mno-relax-immediate'
+ Allow arbitrary sized immediates in bit operations.
+
+`-mwide-bitfields'
+`-mwide-bitfields'
+`-mno-wide-bitfields'
+ Always treat bit-fields as int-sized.
+
+`-m4byte-functions'
+`-m4byte-functions'
+`-mno-4byte-functions'
+ Force all functions to be aligned to a four byte boundary.
+
+`-mcallgraph-data'
+`-mcallgraph-data'
+`-mno-callgraph-data'
+ Emit callgraph information.
+
+`-mslow-bytes'
+`-mslow-bytes'
+`-mno-slow-bytes'
+ Prefer word access when reading byte quantities.
+
+`-mlittle-endian'
+`-mlittle-endian'
+`-mbig-endian'
+ Generate code for a little endian target.
+
+`-m210'
+`-m210'
+`-m340'
+ Generate code for the 210 processor.
+
+\1f
+File: gcc.info, Node: IA-64 Options, Next: D30V Options, Prev: MCore Options, Up: Submodel Options
+
+3.17.30 IA-64 Options
+---------------------
+
+These are the `-m' options defined for the Intel IA-64 architecture.
+
+`-mbig-endian'
+ Generate code for a big endian target. This is the default for
+ HPUX.
+
+`-mlittle-endian'
+ Generate code for a little endian target. This is the default for
+ AIX5 and Linux.
+
+`-mgnu-as'
+`-mno-gnu-as'
+ Generate (or don't) code for the GNU assembler. This is the
default.
- Ideally, a portable program should always use `signed char' or
- `unsigned char' when it depends on the signedness of an object.
- But many programs have been written to use plain `char' and expect
- it to be signed, or expect it to be unsigned, depending on the
- machines they were written for. This option, and its inverse, let
- you make such a program work with the opposite default.
-
- The type `char' is always a distinct type from each of `signed
- char' or `unsigned char', even though its behavior is always just
- like one of those two.
-
-`-fsigned-char'
- Let the type `char' be signed, like `signed char'.
-
- Note that this is equivalent to `-fno-unsigned-char', which is the
- negative form of `-funsigned-char'. Likewise, the option
- `-fno-signed-char' is equivalent to `-funsigned-char'.
-
-`-fsigned-bitfields'
-`-funsigned-bitfields'
-`-fno-signed-bitfields'
-`-fno-unsigned-bitfields'
- These options control whether a bit-field is signed or unsigned,
- when the declaration does not use either `signed' or `unsigned'.
- By default, such a bit-field is signed, because this is
- consistent: the basic integer types such as `int' are signed types.
-
- However, when `-traditional' is used, bit-fields are all unsigned
- no matter what.
-
-`-fwritable-strings'
- Store string constants in the writable data segment and don't
- uniquize them. This is for compatibility with old programs which
- assume they can write into string constants. The option
- `-traditional' also has this effect.
-
- Writing into string constants is a very bad idea; "constants"
- should be constant.
-
-`-fallow-single-precision'
- Do not promote single precision math operations to double
- precision, even when compiling with `-traditional'.
-
- Traditional K&R C promotes all floating point operations to double
- precision, regardless of the sizes of the operands. On the
- architecture for which you are compiling, single precision may be
- faster than double precision. If you must use `-traditional',
- but want to use single precision operations when the operands are
- single precision, use this option. This option has no effect
- when compiling with ISO or GNU C conventions (the default).
-
-\1f
-File: gcc.info, Node: C++ Dialect Options, Next: Objective-C Dialect Options, Prev: C Dialect Options, Up: Invoking GCC
-
-Options Controlling C++ Dialect
-===============================
+`-mgnu-ld'
+`-mno-gnu-ld'
+ Generate (or don't) code for the GNU linker. This is the default.
+
+`-mno-pic'
+ Generate code that does not use a global pointer register. The
+ result is not position independent code, and violates the IA-64
+ ABI.
+
+`-mvolatile-asm-stop'
+`-mno-volatile-asm-stop'
+ Generate (or don't) a stop bit immediately before and after
+ volatile asm statements.
+
+`-mb-step'
+ Generate code that works around Itanium B step errata.
+
+`-mregister-names'
+`-mno-register-names'
+ Generate (or don't) `in', `loc', and `out' register names for the
+ stacked registers. This may make assembler output more readable.
+
+`-mno-sdata'
+`-msdata'
+ Disable (or enable) optimizations that use the small data section.
+ This may be useful for working around optimizer bugs.
+
+`-mconstant-gp'
+ Generate code that uses a single constant global pointer value.
+ This is useful when compiling kernel code.
+
+`-mauto-pic'
+ Generate code that is self-relocatable. This implies
+ `-mconstant-gp'. This is useful when compiling firmware code.
+
+`-minline-divide-min-latency'
+ Generate code for inline divides using the minimum latency
+ algorithm.
+
+`-minline-divide-max-throughput'
+ Generate code for inline divides using the maximum throughput
+ algorithm.
+
+`-mno-dwarf2-asm'
+`-mdwarf2-asm'
+ Don't (or do) generate assembler code for the DWARF2 line number
+ debugging info. This may be useful when not using the GNU
+ assembler.
+
+`-mfixed-range=REGISTER-RANGE'
+ Generate code treating the given register range as fixed registers.
+ A fixed register is one that the register allocator can not use.
+ This is useful when compiling kernel code. A register range is
+ specified as two registers separated by a dash. Multiple register
+ ranges can be specified separated by a comma.
- This section describes the command-line options that are only
-meaningful for C++ programs; but you can also use most of the GNU
-compiler options regardless of what language your program is in. For
-example, you might compile a file `firstClass.C' like this:
+\1f
+File: gcc.info, Node: D30V Options, Next: S/390 and zSeries Options, Prev: IA-64 Options, Up: Submodel Options
- g++ -g -frepo -O -c firstClass.C
+3.17.31 D30V Options
+--------------------
-In this example, only `-frepo' is an option meant only for C++
-programs; you can use the other options with any language supported by
-GCC.
+These `-m' options are defined for D30V implementations:
- Here is a list of options that are _only_ for compiling C++ programs:
-
-`-fno-access-control'
- Turn off all access checking. This switch is mainly useful for
- working around bugs in the access control code.
-
-`-fcheck-new'
- Check that the pointer returned by `operator new' is non-null
- before attempting to modify the storage allocated. The current
- Working Paper requires that `operator new' never return a null
- pointer, so this check is normally unnecessary.
-
- An alternative to using this option is to specify that your
- `operator new' does not throw any exceptions; if you declare it
- `throw()', G++ will check the return value. See also `new
- (nothrow)'.
-
-`-fconserve-space'
- Put uninitialized or runtime-initialized global variables into the
- common segment, as C does. This saves space in the executable at
- the cost of not diagnosing duplicate definitions. If you compile
- with this flag and your program mysteriously crashes after
- `main()' has completed, you may have an object that is being
- destroyed twice because two definitions were merged.
-
- This option is no longer useful on most targets, now that support
- has been added for putting variables into BSS without making them
- common.
-
-`-fno-const-strings'
- Give string constants type `char *' instead of type `const char
- *'. By default, G++ uses type `const char *' as required by the
- standard. Even if you use `-fno-const-strings', you cannot
- actually modify the value of a string constant, unless you also use
- `-fwritable-strings'.
-
- This option might be removed in a future release of G++. For
- maximum portability, you should structure your code so that it
- works with string constants that have type `const char *'.
-
-`-fdollars-in-identifiers'
- Accept `$' in identifiers. You can also explicitly prohibit use of
- `$' with the option `-fno-dollars-in-identifiers'. (GNU C allows
- `$' by default on most target systems, but there are a few
- exceptions.) Traditional C allowed the character `$' to form part
- of identifiers. However, ISO C and C++ forbid `$' in identifiers.
-
-`-fno-elide-constructors'
- The C++ standard allows an implementation to omit creating a
- temporary which is only used to initialize another object of the
- same type. Specifying this option disables that optimization, and
- forces G++ to call the copy constructor in all cases.
-
-`-fno-enforce-eh-specs'
- Don't check for violation of exception specifications at runtime.
- This option violates the C++ standard, but may be useful for
- reducing code size in production builds, much like defining
- `NDEBUG'. The compiler will still optimize based on the exception
- specifications.
-
-`-fexternal-templates'
- Cause `#pragma interface' and `implementation' to apply to
- template instantiation; template instances are emitted or not
- according to the location of the template definition. *Note
- Template Instantiation::, for more information.
-
- This option is deprecated.
-
-`-falt-external-templates'
- Similar to `-fexternal-templates', but template instances are
- emitted or not according to the place where they are first
- instantiated. *Note Template Instantiation::, for more
- information.
+`-mextmem'
+ Link the `.text', `.data', `.bss', `.strings', `.rodata',
+ `.rodata1', `.data1' sections into external memory, which starts
+ at location `0x80000000'.
- This option is deprecated.
-
-`-ffor-scope'
-`-fno-for-scope'
- If `-ffor-scope' is specified, the scope of variables declared in
- a for-init-statement is limited to the `for' loop itself, as
- specified by the C++ standard. If `-fno-for-scope' is specified,
- the scope of variables declared in a for-init-statement extends to
- the end of the enclosing scope, as was the case in old versions of
- G++, and other (traditional) implementations of C++.
-
- The default if neither flag is given to follow the standard, but
- to allow and give a warning for old-style code that would
- otherwise be invalid, or have different behavior.
-
-`-fno-gnu-keywords'
- Do not recognize `typeof' as a keyword, so that code can use this
- word as an identifier. You can use the keyword `__typeof__'
- instead. `-ansi' implies `-fno-gnu-keywords'.
-
-`-fno-implicit-templates'
- Never emit code for non-inline templates which are instantiated
- implicitly (i.e. by use); only emit code for explicit
- instantiations. *Note Template Instantiation::, for more
- information.
+`-mextmemory'
+ Same as the `-mextmem' switch.
-`-fno-implicit-inline-templates'
- Don't emit code for implicit instantiations of inline templates,
- either. The default is to handle inlines differently so that
- compiles with and without optimization will need the same set of
- explicit instantiations.
-
-`-fno-implement-inlines'
- To save space, do not emit out-of-line copies of inline functions
- controlled by `#pragma implementation'. This will cause linker
- errors if these functions are not inlined everywhere they are
- called.
-
-`-fms-extensions'
- Disable pedantic warnings about constructs used in MFC, such as
- implicit int and getting a pointer to member function via
- non-standard syntax.
-
-`-fno-nonansi-builtins'
- Disable built-in declarations of functions that are not mandated by
- ANSI/ISO C. These include `ffs', `alloca', `_exit', `index',
- `bzero', `conjf', and other related functions.
-
-`-fno-operator-names'
- Do not treat the operator name keywords `and', `bitand', `bitor',
- `compl', `not', `or' and `xor' as synonyms as keywords.
-
-`-fno-optional-diags'
- Disable diagnostics that the standard says a compiler does not
- need to issue. Currently, the only such diagnostic issued by G++
- is the one for a name having multiple meanings within a class.
-
-`-fpermissive'
- Downgrade messages about nonconformant code from errors to
- warnings. By default, G++ effectively sets `-pedantic-errors'
- without `-pedantic'; this option reverses that. This behavior and
- this option are superseded by `-pedantic', which works as it does
- for GNU C.
-
-`-frepo'
- Enable automatic template instantiation at link time. This option
- also implies `-fno-implicit-templates'. *Note Template
- Instantiation::, for more information.
-
-`-fno-rtti'
- Disable generation of information about every class with virtual
- functions for use by the C++ runtime type identification features
- (`dynamic_cast' and `typeid'). If you don't use those parts of
- the language, you can save some space by using this flag. Note
- that exception handling uses the same information, but it will
- generate it as needed.
-
-`-fstats'
- Emit statistics about front-end processing at the end of the
- compilation. This information is generally only useful to the G++
- development team.
-
-`-ftemplate-depth-N'
- Set the maximum instantiation depth for template classes to N. A
- limit on the template instantiation depth is needed to detect
- endless recursions during template class instantiation. ANSI/ISO
- C++ conforming programs must not rely on a maximum depth greater
- than 17.
-
-`-fuse-cxa-atexit'
- Register destructors for objects with static storage duration with
- the `__cxa_atexit' function rather than the `atexit' function.
- This option is required for fully standards-compliant handling of
- static destructors, but will only work if your C library supports
- `__cxa_atexit'.
-
-`-fvtable-gc'
- Emit special relocations for vtables and virtual function
- references so that the linker can identify unused virtual
- functions and zero out vtable slots that refer to them. This is
- most useful with `-ffunction-sections' and `-Wl,--gc-sections', in
- order to also discard the functions themselves.
-
- This optimization requires GNU as and GNU ld. Not all systems
- support this option. `-Wl,--gc-sections' is ignored without
- `-static'.
-
-`-fno-weak'
- Do not use weak symbol support, even if it is provided by the
- linker. By default, G++ will use weak symbols if they are
- available. This option exists only for testing, and should not be
- used by end-users; it will result in inferior code and has no
- benefits. This option may be removed in a future release of G++.
-
-`-nostdinc++'
- Do not search for header files in the standard directories
- specific to C++, but do still search the other standard
- directories. (This option is used when building the C++ library.)
-
- In addition, these optimization, warning, and code generation options
-have meanings only for C++ programs:
-
-`-fno-default-inline'
- Do not assume `inline' for functions defined inside a class scope.
- *Note Options That Control Optimization: Optimize Options. Note
- that these functions will have linkage like inline functions; they
- just won't be inlined by default.
-
-`-Wabi (C++ only)'
- Warn when G++ generates code that is probably not compatible with
- the vendor-neutral C++ ABI. Although an effort has been made to
- warn about all such cases, there are probably some cases that are
- not warned about, even though G++ is generating incompatible code.
- There may also be cases where warnings are emitted even though
- the code that is generated will be compatible.
-
- You should rewrite your code to avoid these warnings if you are
- concerned about the fact that code generated by G++ may not be
- binary compatible with code generated by other compilers.
-
- The known incompatibilites at this point include:
-
- * Incorrect handling of tail-padding for bit-fields. G++ may
- attempt to pack data into the same byte as a base class. For
- example:
-
- struct A { virtual void f(); int f1 : 1; };
- struct B : public A { int f2 : 1; };
-
- In this case, G++ will place `B::f2' into the same byte
- as`A::f1'; other compilers will not. You can avoid this
- problem by explicitly padding `A' so that its size is a
- multiple of the byte size on your platform; that will cause
- G++ and other compilers to layout `B' identically.
-
- * Incorrect handling of tail-padding for virtual bases. G++
- does not use tail padding when laying out virtual bases. For
- example:
-
- struct A { virtual void f(); char c1; };
- struct B { B(); char c2; };
- struct C : public A, public virtual B {};
-
- In this case, G++ will not place `B' into the tail-padding for
- `A'; other compilers will. You can avoid this problem by
- explicitly padding `A' so that its size is a multiple of its
- alignment (ignoring virtual base classes); that will cause
- G++ and other compilers to layout `C' identically.
-
-
-`-Wctor-dtor-privacy (C++ only)'
- Warn when a class seems unusable, because all the constructors or
- destructors in a class are private and the class has no friends or
- public static member functions.
-
-`-Wnon-virtual-dtor (C++ only)'
- Warn when a class declares a non-virtual destructor that should
- probably be virtual, because it looks like the class will be used
- polymorphically.
-
-`-Wreorder (C++ only)'
- Warn when the order of member initializers given in the code does
- not match the order in which they must be executed. For instance:
-
- struct A {
- int i;
- int j;
- A(): j (0), i (1) { }
- };
+`-monchip'
+ Link the `.text' section into onchip text memory, which starts at
+ location `0x0'. Also link `.data', `.bss', `.strings', `.rodata',
+ `.rodata1', `.data1' sections into onchip data memory, which
+ starts at location `0x20000000'.
+
+`-mno-asm-optimize'
+`-masm-optimize'
+ Disable (enable) passing `-O' to the assembler when optimizing.
+ The assembler uses the `-O' option to automatically parallelize
+ adjacent short instructions where possible.
- Here the compiler will warn that the member initializers for `i'
- and `j' will be rearranged to match the declaration order of the
- members.
+`-mbranch-cost=N'
+ Increase the internal costs of branches to N. Higher costs means
+ that the compiler will issue more instructions to avoid doing a
+ branch. The default is 2.
- The following `-W...' options are not affected by `-Wall'.
+`-mcond-exec=N'
+ Specify the maximum number of conditionally executed instructions
+ that replace a branch. The default is 4.
-`-Weffc++ (C++ only)'
- Warn about violations of the following style guidelines from Scott
- Meyers' `Effective C++' book:
+\1f
+File: gcc.info, Node: S/390 and zSeries Options, Next: CRIS Options, Prev: D30V Options, Up: Submodel Options
+
+3.17.32 S/390 and zSeries Options
+---------------------------------
- * Item 11: Define a copy constructor and an assignment
- operator for classes with dynamically allocated memory.
+These are the `-m' options defined for the S/390 and zSeries
+architecture.
- * Item 12: Prefer initialization to assignment in constructors.
+`-mhard-float'
+`-msoft-float'
+ Use (do not use) the hardware floating-point instructions and
+ registers for floating-point operations. When `-msoft-float' is
+ specified, functions in `libgcc.a' will be used to perform
+ floating-point operations. When `-mhard-float' is specified, the
+ compiler generates IEEE floating-point instructions. This is the
+ default.
- * Item 14: Make destructors virtual in base classes.
+`-mbackchain'
+`-mno-backchain'
+ Generate (or do not generate) code which maintains an explicit
+ backchain within the stack frame that points to the caller's frame.
+ This is currently needed to allow debugging. The default is to
+ generate the backchain.
+
+`-msmall-exec'
+`-mno-small-exec'
+ Generate (or do not generate) code using the `bras' instruction to
+ do subroutine calls. This only works reliably if the total
+ executable size does not exceed 64k. The default is to use the
+ `basr' instruction instead, which does not have this limitation.
+
+`-m64'
+`-m31'
+ When `-m31' is specified, generate code compliant to the Linux for
+ S/390 ABI. When `-m64' is specified, generate code compliant to
+ the Linux for zSeries ABI. This allows GCC in particular to
+ generate 64-bit instructions. For the `s390' targets, the default
+ is `-m31', while the `s390x' targets default to `-m64'.
+
+`-mmvcle'
+`-mno-mvcle'
+ Generate (or do not generate) code using the `mvcle' instruction
+ to perform block moves. When `-mno-mvcle' is specifed, use a
+ `mvc' loop instead. This is the default.
+
+`-mdebug'
+`-mno-debug'
+ Print (or do not print) additional debug information when
+ compiling. The default is to not print debug information.
- * Item 15: Have `operator=' return a reference to `*this'.
- * Item 23: Don't try to return a reference when you must
- return an object.
+\1f
+File: gcc.info, Node: CRIS Options, Next: MMIX Options, Prev: S/390 and zSeries Options, Up: Submodel Options
+
+3.17.33 CRIS Options
+--------------------
+
+These options are defined specifically for the CRIS ports.
+
+`-march=ARCHITECTURE-TYPE'
+`-mcpu=ARCHITECTURE-TYPE'
+ Generate code for the specified architecture. The choices for
+ ARCHITECTURE-TYPE are `v3', `v8' and `v10' for respectively
+ ETRAX 4, ETRAX 100, and ETRAX 100 LX. Default is `v0' except for
+ cris-axis-linux-gnu, where the default is `v10'.
+
+`-mtune=ARCHITECTURE-TYPE'
+ Tune to ARCHITECTURE-TYPE everything applicable about the generated
+ code, except for the ABI and the set of available instructions.
+ The choices for ARCHITECTURE-TYPE are the same as for
+ `-march=ARCHITECTURE-TYPE'.
+
+`-mmax-stack-frame=N'
+ Warn when the stack frame of a function exceeds N bytes.
+
+`-melinux-stacksize=N'
+ Only available with the `cris-axis-aout' target. Arranges for
+ indications in the program to the kernel loader that the stack of
+ the program should be set to N bytes.
+
+`-metrax4'
+`-metrax100'
+ The options `-metrax4' and `-metrax100' are synonyms for
+ `-march=v3' and `-march=v8' respectively.
+
+`-mpdebug'
+ Enable CRIS-specific verbose debug-related information in the
+ assembly code. This option also has the effect to turn off the
+ `#NO_APP' formatted-code indicator to the assembler at the
+ beginning of the assembly file.
+
+`-mcc-init'
+ Do not use condition-code results from previous instruction;
+ always emit compare and test instructions before use of condition
+ codes.
+
+`-mno-side-effects'
+ Do not emit instructions with side-effects in addressing modes
+ other than post-increment.
+
+`-mstack-align'
+`-mno-stack-align'
+`-mdata-align'
+`-mno-data-align'
+`-mconst-align'
+`-mno-const-align'
+ These options (no-options) arranges (eliminate arrangements) for
+ the stack-frame, individual data and constants to be aligned for
+ the maximum single data access size for the chosen CPU model. The
+ default is to arrange for 32-bit alignment. ABI details such as
+ structure layout are not affected by these options.
+
+`-m32-bit'
+`-m16-bit'
+`-m8-bit'
+ Similar to the stack- data- and const-align options above, these
+ options arrange for stack-frame, writable data and constants to
+ all be 32-bit, 16-bit or 8-bit aligned. The default is 32-bit
+ alignment.
+
+`-mno-prologue-epilogue'
+`-mprologue-epilogue'
+ With `-mno-prologue-epilogue', the normal function prologue and
+ epilogue that sets up the stack-frame are omitted and no return
+ instructions or return sequences are generated in the code. Use
+ this option only together with visual inspection of the compiled
+ code: no warnings or errors are generated when call-saved
+ registers must be saved, or storage for local variable needs to be
+ allocated.
+
+`-mno-gotplt'
+`-mgotplt'
+ With `-fpic' and `-fPIC', don't generate (do generate) instruction
+ sequences that load addresses for functions from the PLT part of
+ the GOT rather than (traditional on other architectures) calls to
+ the PLT. The default is `-mgotplt'.
+
+`-maout'
+ Legacy no-op option only recognized with the cris-axis-aout target.
+
+`-melf'
+ Legacy no-op option only recognized with the cris-axis-elf and
+ cris-axis-linux-gnu targets.
+
+`-melinux'
+ Only recognized with the cris-axis-aout target, where it selects a
+ GNU/linux-like multilib, include files and instruction set for
+ `-march=v8'.
+
+`-mlinux'
+ Legacy no-op option only recognized with the cris-axis-linux-gnu
+ target.
+
+`-sim'
+ This option, recognized for the cris-axis-aout and cris-axis-elf
+ arranges to link with input-output functions from a simulator
+ library. Code, initialized data and zero-initialized data are
+ allocated consecutively.
+
+`-sim2'
+ Like `-sim', but pass linker options to locate initialized data at
+ 0x40000000 and zero-initialized data at 0x80000000.
+\1f
+File: gcc.info, Node: MMIX Options, Next: PDP-11 Options, Prev: CRIS Options, Up: Submodel Options
+
+3.17.34 MMIX Options
+--------------------
+
+These options are defined for the MMIX:
+
+`-mlibfuncs'
+`-mno-libfuncs'
+ Specify that intrinsic library functions are being compiled,
+ passing all values in registers, no matter the size.
+
+`-mepsilon'
+`-mno-epsilon'
+ Generate floating-point comparison instructions that compare with
+ respect to the `rE' epsilon register.
+
+`-mabi=mmixware'
+`-mabi=gnu'
+ Generate code that passes function parameters and return values
+ that (in the called function) are seen as registers `$0' and up,
+ as opposed to the GNU ABI which uses global registers `$231' and
+ up.
+
+`-mzero-extend'
+`-mno-zero-extend'
+ When reading data from memory in sizes shorter than 64 bits, use
+ (do not use) zero-extending load instructions by default, rather
+ than sign-extending ones.
+
+`-mknuthdiv'
+`-mno-knuthdiv'
+ Make the result of a division yielding a remainder have the same
+ sign as the divisor. With the default, `-mno-knuthdiv', the sign
+ of the remainder follows the sign of the dividend. Both methods
+ are arithmetically valid, the latter being almost exclusively used.
+
+`-mtoplevel-symbols'
+`-mno-toplevel-symbols'
+ Prepend (do not prepend) a `:' to all global symbols, so the
+ assembly code can be used with the `PREFIX' assembly directive.
+
+`-melf'
+ Generate an executable in the ELF format, rather than the default
+ `mmo' format used by the `mmix' simulator.
+
+`-mbranch-predict'
+`-mno-branch-predict'
+ Use (do not use) the probable-branch instructions, when static
+ branch prediction indicates a probable branch.
+
+`-mbase-addresses'
+`-mno-base-addresses'
+ Generate (do not generate) code that uses _base addresses_. Using
+ a base address automatically generates a request (handled by the
+ assembler and the linker) for a constant to be set up in a global
+ register. The register is used for one or more base address
+ requests within the range 0 to 255 from the value held in the
+ register. The generally leads to short and fast code, but the
+ number of different data items that can be addressed is limited.
+ This means that a program that uses lots of static data may
+ require `-mno-base-addresses'.
- and about violations of the following style guidelines from Scott
- Meyers' `More Effective C++' book:
+\1f
+File: gcc.info, Node: PDP-11 Options, Next: Xstormy16 Options, Prev: MMIX Options, Up: Submodel Options
- * Item 6: Distinguish between prefix and postfix forms of
- increment and decrement operators.
+3.17.35 PDP-11 Options
+----------------------
- * Item 7: Never overload `&&', `||', or `,'.
+These options are defined for the PDP-11:
+`-mfpu'
+ Use hardware FPP floating point. This is the default. (FIS
+ floating point on the PDP-11/40 is not supported.)
- If you use this option, you should be aware that the standard
- library headers do not obey all of these guidelines; you can use
- `grep -v' to filter out those warnings.
+`-msoft-float'
+ Do not use hardware floating point.
-`-Wno-deprecated (C++ only)'
- Do not warn about usage of deprecated features. *Note Deprecated
- Features::.
+`-mac0'
+ Return floating-point results in ac0 (fr0 in Unix assembler
+ syntax).
-`-Wno-non-template-friend (C++ only)'
- Disable warnings when non-templatized friend functions are declared
- within a template. With the advent of explicit template
- specification support in G++, if the name of the friend is an
- unqualified-id (i.e., `friend foo(int)'), the C++ language
- specification demands that the friend declare or define an
- ordinary, nontemplate function. (Section 14.5.3). Before G++
- implemented explicit specification, unqualified-ids could be
- interpreted as a particular specialization of a templatized
- function. Because this non-conforming behavior is no longer the
- default behavior for G++, `-Wnon-template-friend' allows the
- compiler to check existing code for potential trouble spots, and
- is on by default. This new compiler behavior can be turned off
- with `-Wno-non-template-friend' which keeps the conformant
- compiler code but disables the helpful warning.
+`-mno-ac0'
+ Return floating-point results in memory. This is the default.
-`-Wold-style-cast (C++ only)'
- Warn if an old-style (C-style) cast to a non-void type is used
- within a C++ program. The new-style casts (`static_cast',
- `reinterpret_cast', and `const_cast') are less vulnerable to
- unintended effects, and much easier to grep for.
+`-m40'
+ Generate code for a PDP-11/40.
-`-Woverloaded-virtual (C++ only)'
- Warn when a function declaration hides virtual functions from a
- base class. For example, in:
+`-m45'
+ Generate code for a PDP-11/45. This is the default.
- struct A {
- virtual void f();
- };
-
- struct B: public A {
- void f(int);
- };
+`-m10'
+ Generate code for a PDP-11/10.
- the `A' class version of `f' is hidden in `B', and code like this:
+`-mbcopy-builtin'
+ Use inline `movstrhi' patterns for copying memory. This is the
+ default.
- B* b;
- b->f();
+`-mbcopy'
+ Do not use inline `movstrhi' patterns for copying memory.
- will fail to compile.
+`-mint16'
+`-mno-int32'
+ Use 16-bit `int'. This is the default.
-`-Wno-pmf-conversions (C++ only)'
- Disable the diagnostic for converting a bound pointer to member
- function to a plain pointer.
+`-mint32'
+`-mno-int16'
+ Use 32-bit `int'.
-`-Wsign-promo (C++ only)'
- Warn when overload resolution chooses a promotion from unsigned or
- enumeral type to a signed type over a conversion to an unsigned
- type of the same size. Previous versions of G++ would try to
- preserve unsignedness, but the standard mandates the current
- behavior.
+`-mfloat64'
+`-mno-float32'
+ Use 64-bit `float'. This is the default.
-`-Wsynth (C++ only)'
- Warn when G++'s synthesis behavior does not match that of cfront.
- For instance:
+`-mfloat32'
- struct A {
- operator int ();
- A& operator = (int);
- };
-
- main ()
- {
- A a,b;
- a = b;
- }
+`-mno-float64'
+ Use 32-bit `float'.
+
+`-mabshi'
+ Use `abshi2' pattern. This is the default.
+
+`-mno-abshi'
+ Do not use `abshi2' pattern.
+
+`-mbranch-expensive'
+ Pretend that branches are expensive. This is for experimenting
+ with code generation only.
+
+`-mbranch-cheap'
+ Do not pretend that branches are expensive. This is the default.
- In this example, G++ will synthesize a default `A& operator =
- (const A&);', while cfront will use the user-defined `operator ='.
+`-msplit'
+ Generate code for a system with split I&D.
+
+`-mno-split'
+ Generate code for a system without split I&D. This is the default.
+
+`-munix-asm'
+ Use Unix assembler syntax. This is the default when configured for
+ `pdp11-*-bsd'.
+
+`-mdec-asm'
+ Use DEC assembler syntax. This is the default when configured for
+ any PDP-11 target other than `pdp11-*-bsd'.
\1f
-File: gcc.info, Node: Objective-C Dialect Options, Next: Language Independent Options, Prev: C++ Dialect Options, Up: Invoking GCC
+File: gcc.info, Node: Xstormy16 Options, Next: Xtensa Options, Prev: PDP-11 Options, Up: Submodel Options
-Options Controlling Objective-C Dialect
-=======================================
+3.17.36 Xstormy16 Options
+-------------------------
+
+These options are defined for Xstormy16:
+
+`-msim'
+ Choose startup files and linker script suitable for the simulator.
+
+\1f
+File: gcc.info, Node: Xtensa Options, Prev: Xstormy16 Options, Up: Submodel Options
+
+3.17.37 Xtensa Options
+----------------------
+
+The Xtensa architecture is designed to support many different
+configurations. The compiler's default options can be set to match a
+particular Xtensa configuration by copying a configuration file into the
+GCC sources when building GCC. The options below may be used to
+override the default options.
+
+`-mbig-endian'
+`-mlittle-endian'
+ Specify big-endian or little-endian byte ordering for the target
+ Xtensa processor.
+
+`-mdensity'
+`-mno-density'
+ Enable or disable use of the optional Xtensa code density
+ instructions.
+
+`-mmac16'
+`-mno-mac16'
+ Enable or disable use of the Xtensa MAC16 option. When enabled,
+ GCC will generate MAC16 instructions from standard C code, with the
+ limitation that it will use neither the MR register file nor any
+ instruction that operates on the MR registers. When this option is
+ disabled, GCC will translate 16-bit multiply/accumulate operations
+ to a combination of core instructions and library calls, depending
+ on whether any other multiplier options are enabled.
+
+`-mmul16'
+`-mno-mul16'
+ Enable or disable use of the 16-bit integer multiplier option.
+ When enabled, the compiler will generate 16-bit multiply
+ instructions for multiplications of 16 bits or smaller in standard
+ C code. When this option is disabled, the compiler will either
+ use 32-bit multiply or MAC16 instructions if they are available or
+ generate library calls to perform the multiply operations using
+ shifts and adds.
+
+`-mmul32'
+`-mno-mul32'
+ Enable or disable use of the 32-bit integer multiplier option.
+ When enabled, the compiler will generate 32-bit multiply
+ instructions for multiplications of 32 bits or smaller in standard
+ C code. When this option is disabled, the compiler will generate
+ library calls to perform the multiply operations using either
+ shifts and adds or 16-bit multiply instructions if they are
+ available.
+
+`-mnsa'
+`-mno-nsa'
+ Enable or disable use of the optional normalization shift amount
+ (`NSA') instructions to implement the built-in `ffs' function.
+
+`-mminmax'
+`-mno-minmax'
+ Enable or disable use of the optional minimum and maximum value
+ instructions.
+
+`-msext'
+`-mno-sext'
+ Enable or disable use of the optional sign extend (`SEXT')
+ instruction.
+
+`-mbooleans'
+`-mno-booleans'
+ Enable or disable support for the boolean register file used by
+ Xtensa coprocessors. This is not typically useful by itself but
+ may be required for other options that make use of the boolean
+ registers (e.g., the floating-point option).
+
+`-mhard-float'
+`-msoft-float'
+ Enable or disable use of the floating-point option. When enabled,
+ GCC generates floating-point instructions for 32-bit `float'
+ operations. When this option is disabled, GCC generates library
+ calls to emulate 32-bit floating-point operations using integer
+ instructions. Regardless of this option, 64-bit `double'
+ operations are always emulated with calls to library functions.
+
+`-mfused-madd'
+`-mno-fused-madd'
+ Enable or disable use of fused multiply/add and multiply/subtract
+ instructions in the floating-point option. This has no effect if
+ the floating-point option is not also enabled. Disabling fused
+ multiply/add and multiply/subtract instructions forces the
+ compiler to use separate instructions for the multiply and
+ add/subtract operations. This may be desirable in some cases
+ where strict IEEE 754-compliant results are required: the fused
+ multiply add/subtract instructions do not round the intermediate
+ result, thereby producing results with _more_ bits of precision
+ than specified by the IEEE standard. Disabling fused multiply
+ add/subtract instructions also ensures that the program output is
+ not sensitive to the compiler's ability to combine multiply and
+ add/subtract operations.
+
+`-mserialize-volatile'
+`-mno-serialize-volatile'
+ When this option is enabled, GCC inserts `MEMW' instructions before
+ `volatile' memory references to guarantee sequential consistency.
+ The default is `-mserialize-volatile'. Use
+ `-mno-serialize-volatile' to omit the `MEMW' instructions.
+
+`-mtext-section-literals'
+`-mno-text-section-literals'
+ Control the treatment of literal pools. The default is
+ `-mno-text-section-literals', which places literals in a separate
+ section in the output file. This allows the literal pool to be
+ placed in a data RAM/ROM, and it also allows the linker to combine
+ literal pools from separate object files to remove redundant
+ literals and improve code size. With `-mtext-section-literals',
+ the literals are interspersed in the text section in order to keep
+ them as close as possible to their references. This may be
+ necessary for large assembly files.
+
+`-mtarget-align'
+`-mno-target-align'
+ When this option is enabled, GCC instructs the assembler to
+ automatically align instructions to reduce branch penalties at the
+ expense of some code density. The assembler attempts to widen
+ density instructions to align branch targets and the instructions
+ following call instructions. If there are not enough preceding
+ safe density instructions to align a target, no widening will be
+ performed. The default is `-mtarget-align'. These options do not
+ affect the treatment of auto-aligned instructions like `LOOP',
+ which the assembler will always align, either by widening density
+ instructions or by inserting no-op instructions.
+
+`-mlongcalls'
+`-mno-longcalls'
+ When this option is enabled, GCC instructs the assembler to
+ translate direct calls to indirect calls unless it can determine
+ that the target of a direct call is in the range allowed by the
+ call instruction. This translation typically occurs for calls to
+ functions in other source files. Specifically, the assembler
+ translates a direct `CALL' instruction into an `L32R' followed by
+ a `CALLX' instruction. The default is `-mno-longcalls'. This
+ option should be used in programs where the call target can
+ potentially be out of range. This option is implemented in the
+ assembler, not the compiler, so the assembly code generated by GCC
+ will still show direct call instructions--look at the disassembled
+ object code to see the actual instructions. Note that the
+ assembler will use an indirect call for every cross-file call, not
+ just those that really will be out of range.
- This section describes the command-line options that are only
-meaningful for Objective-C programs; but you can also use most of the
-GNU compiler options regardless of what language your program is in.
-For example, you might compile a file `some_class.m' like this:
+\1f
+File: gcc.info, Node: Code Gen Options, Next: Environment Variables, Prev: Submodel Options, Up: Invoking GCC
+
+3.18 Options for Code Generation Conventions
+============================================
+
+These machine-independent options control the interface conventions
+used in code generation.
+
+ Most of them have both positive and negative forms; the negative form
+of `-ffoo' would be `-fno-foo'. In the table below, only one of the
+forms is listed--the one which is not the default. You can figure out
+the other form by either removing `no-' or adding it.
+
+`-fexceptions'
+ Enable exception handling. Generates extra code needed to
+ propagate exceptions. For some targets, this implies GCC will
+ generate frame unwind information for all functions, which can
+ produce significant data size overhead, although it does not
+ affect execution. If you do not specify this option, GCC will
+ enable it by default for languages like C++ which normally require
+ exception handling, and disable it for languages like C that do
+ not normally require it. However, you may need to enable this
+ option when compiling C code that needs to interoperate properly
+ with exception handlers written in C++. You may also wish to
+ disable this option if you are compiling older C++ programs that
+ don't use exception handling.
+
+`-fnon-call-exceptions'
+ Generate code that allows trapping instructions to throw
+ exceptions. Note that this requires platform-specific runtime
+ support that does not exist everywhere. Moreover, it only allows
+ _trapping_ instructions to throw exceptions, i.e. memory
+ references or floating point instructions. It does not allow
+ exceptions to be thrown from arbitrary signal handlers such as
+ `SIGALRM'.
+
+`-funwind-tables'
+ Similar to `-fexceptions', except that it will just generate any
+ needed static data, but will not affect the generated code in any
+ other way. You will normally not enable this option; instead, a
+ language processor that needs this handling would enable it on
+ your behalf.
+
+`-fasynchronous-unwind-tables'
+ Generate unwind table in dwarf2 format, if supported by target
+ machine. The table is exact at each instruction boundary, so it
+ can be used for stack unwinding from asynchronous events (such as
+ debugger or garbage collector).
+
+`-fpcc-struct-return'
+ Return "short" `struct' and `union' values in memory like longer
+ ones, rather than in registers. This convention is less
+ efficient, but it has the advantage of allowing intercallability
+ between GCC-compiled files and files compiled with other
+ compilers, particularly the Portable C Compiler (pcc).
+
+ The precise convention for returning structures in memory depends
+ on the target configuration macros.
+
+ Short structures and unions are those whose size and alignment
+ match that of some integer type.
+
+ *Warning:* code compiled with the `-fpcc-struct-return' switch is
+ not binary compatible with code compiled with the
+ `-freg-struct-return' switch. Use it to conform to a non-default
+ application binary interface.
+
+`-freg-struct-return'
+ Return `struct' and `union' values in registers when possible.
+ This is more efficient for small structures than
+ `-fpcc-struct-return'.
+
+ If you specify neither `-fpcc-struct-return' nor
+ `-freg-struct-return', GCC defaults to whichever convention is
+ standard for the target. If there is no standard convention, GCC
+ defaults to `-fpcc-struct-return', except on targets where GCC is
+ the principal compiler. In those cases, we can choose the
+ standard, and we chose the more efficient register return
+ alternative.
+
+ *Warning:* code compiled with the `-freg-struct-return' switch is
+ not binary compatible with code compiled with the
+ `-fpcc-struct-return' switch. Use it to conform to a non-default
+ application binary interface.
+
+`-fshort-enums'
+ Allocate to an `enum' type only as many bytes as it needs for the
+ declared range of possible values. Specifically, the `enum' type
+ will be equivalent to the smallest integer type which has enough
+ room.
+
+ *Warning:* the `-fshort-enums' switch causes GCC to generate code
+ that is not binary compatible with code generated without that
+ switch. Use it to conform to a non-default application binary
+ interface.
+
+`-fshort-double'
+ Use the same size for `double' as for `float'.
+
+ *Warning:* the `-fshort-double' switch causes GCC to generate code
+ that is not binary compatible with code generated without that
+ switch. Use it to conform to a non-default application binary
+ interface.
+
+`-fshort-wchar'
+ Override the underlying type for `wchar_t' to be `short unsigned
+ int' instead of the default for the target. This option is useful
+ for building programs to run under WINE.
+
+ *Warning:* the `-fshort-wchar' switch causes GCC to generate code
+ that is not binary compatible with code generated without that
+ switch. Use it to conform to a non-default application binary
+ interface.
+
+`-fshared-data'
+ Requests that the data and non-`const' variables of this
+ compilation be shared data rather than private data. The
+ distinction makes sense only on certain operating systems, where
+ shared data is shared between processes running the same program,
+ while private data exists in one copy per process.
+
+`-fno-common'
+ In C, allocate even uninitialized global variables in the data
+ section of the object file, rather than generating them as common
+ blocks. This has the effect that if the same variable is declared
+ (without `extern') in two different compilations, you will get an
+ error when you link them. The only reason this might be useful is
+ if you wish to verify that the program will work on other systems
+ which always work this way.
+
+`-fno-ident'
+ Ignore the `#ident' directive.
+
+`-fno-gnu-linker'
+ Do not output global initializations (such as C++ constructors and
+ destructors) in the form used by the GNU linker (on systems where
+ the GNU linker is the standard method of handling them). Use this
+ option when you want to use a non-GNU linker, which also requires
+ using the `collect2' program to make sure the system linker
+ includes constructors and destructors. (`collect2' is included in
+ the GCC distribution.) For systems which _must_ use `collect2',
+ the compiler driver `gcc' is configured to do this automatically.
+
+`-finhibit-size-directive'
+ Don't output a `.size' assembler directive, or anything else that
+ would cause trouble if the function is split in the middle, and the
+ two halves are placed at locations far apart in memory. This
+ option is used when compiling `crtstuff.c'; you should not need to
+ use it for anything else.
+
+`-fverbose-asm'
+ Put extra commentary information in the generated assembly code to
+ make it more readable. This option is generally only of use to
+ those who actually need to read the generated assembly code
+ (perhaps while debugging the compiler itself).
+
+ `-fno-verbose-asm', the default, causes the extra information to
+ be omitted and is useful when comparing two assembler files.
+
+`-fvolatile'
+ Consider all memory references through pointers to be volatile.
+
+`-fvolatile-global'
+ Consider all memory references to extern and global data items to
+ be volatile. GCC does not consider static data items to be
+ volatile because of this switch.
+
+`-fvolatile-static'
+ Consider all memory references to static data to be volatile.
+
+`-fpic'
+ Generate position-independent code (PIC) suitable for use in a
+ shared library, if supported for the target machine. Such code
+ accesses all constant addresses through a global offset table
+ (GOT). The dynamic loader resolves the GOT entries when the
+ program starts (the dynamic loader is not part of GCC; it is part
+ of the operating system). If the GOT size for the linked
+ executable exceeds a machine-specific maximum size, you get an
+ error message from the linker indicating that `-fpic' does not
+ work; in that case, recompile with `-fPIC' instead. (These
+ maximums are 16k on the m88k, 8k on the Sparc, and 32k on the m68k
+ and RS/6000. The 386 has no such limit.)
+
+ Position-independent code requires special support, and therefore
+ works only on certain machines. For the 386, GCC supports PIC for
+ System V but not for the Sun 386i. Code generated for the IBM
+ RS/6000 is always position-independent.
+
+`-fPIC'
+ If supported for the target machine, emit position-independent
+ code, suitable for dynamic linking and avoiding any limit on the
+ size of the global offset table. This option makes a difference
+ on the m68k, m88k, and the Sparc.
+
+ Position-independent code requires special support, and therefore
+ works only on certain machines.
+
+`-ffixed-REG'
+ Treat the register named REG as a fixed register; generated code
+ should never refer to it (except perhaps as a stack pointer, frame
+ pointer or in some other fixed role).
+
+ REG must be the name of a register. The register names accepted
+ are machine-specific and are defined in the `REGISTER_NAMES' macro
+ in the machine description macro file.
+
+ This flag does not have a negative form, because it specifies a
+ three-way choice.
+
+`-fcall-used-REG'
+ Treat the register named REG as an allocable register that is
+ clobbered by function calls. It may be allocated for temporaries
+ or variables that do not live across a call. Functions compiled
+ this way will not save and restore the register REG.
+
+ It is an error to used this flag with the frame pointer or stack
+ pointer. Use of this flag for other registers that have fixed
+ pervasive roles in the machine's execution model will produce
+ disastrous results.
+
+ This flag does not have a negative form, because it specifies a
+ three-way choice.
+
+`-fcall-saved-REG'
+ Treat the register named REG as an allocable register saved by
+ functions. It may be allocated even for temporaries or variables
+ that live across a call. Functions compiled this way will save
+ and restore the register REG if they use it.
+
+ It is an error to used this flag with the frame pointer or stack
+ pointer. Use of this flag for other registers that have fixed
+ pervasive roles in the machine's execution model will produce
+ disastrous results.
+
+ A different sort of disaster will result from the use of this flag
+ for a register in which function values may be returned.
+
+ This flag does not have a negative form, because it specifies a
+ three-way choice.
+
+`-fpack-struct'
+ Pack all structure members together without holes.
+
+ *Warning:* the `-fpack-struct' switch causes GCC to generate code
+ that is not binary compatible with code generated without that
+ switch. Additionally, it makes the code suboptimial. Use it to
+ conform to a non-default application binary interface.
+
+`-finstrument-functions'
+ Generate instrumentation calls for entry and exit to functions.
+ Just after function entry and just before function exit, the
+ following profiling functions will be called with the address of
+ the current function and its call site. (On some platforms,
+ `__builtin_return_address' does not work beyond the current
+ function, so the call site information may not be available to the
+ profiling functions otherwise.)
+
+ void __cyg_profile_func_enter (void *this_fn,
+ void *call_site);
+ void __cyg_profile_func_exit (void *this_fn,
+ void *call_site);
+
+ The first argument is the address of the start of the current
+ function, which may be looked up exactly in the symbol table.
+
+ This instrumentation is also done for functions expanded inline in
+ other functions. The profiling calls will indicate where,
+ conceptually, the inline function is entered and exited. This
+ means that addressable versions of such functions must be
+ available. If all your uses of a function are expanded inline,
+ this may mean an additional expansion of code size. If you use
+ `extern inline' in your C code, an addressable version of such
+ functions must be provided. (This is normally the case anyways,
+ but if you get lucky and the optimizer always expands the
+ functions inline, you might have gotten away without providing
+ static copies.)
+
+ A function may be given the attribute `no_instrument_function', in
+ which case this instrumentation will not be done. This can be
+ used, for example, for the profiling functions listed above,
+ high-priority interrupt routines, and any functions from which the
+ profiling functions cannot safely be called (perhaps signal
+ handlers, if the profiling routines generate output or allocate
+ memory).
+
+`-fstack-check'
+ Generate code to verify that you do not go beyond the boundary of
+ the stack. You should specify this flag if you are running in an
+ environment with multiple threads, but only rarely need to specify
+ it in a single-threaded environment since stack overflow is
+ automatically detected on nearly all systems if there is only one
+ stack.
+
+ Note that this switch does not actually cause checking to be done;
+ the operating system must do that. The switch causes generation
+ of code to ensure that the operating system sees the stack being
+ extended.
+
+`-fstack-limit-register=REG'
+`-fstack-limit-symbol=SYM'
+`-fno-stack-limit'
+ Generate code to ensure that the stack does not grow beyond a
+ certain value, either the value of a register or the address of a
+ symbol. If the stack would grow beyond the value, a signal is
+ raised. For most targets, the signal is raised before the stack
+ overruns the boundary, so it is possible to catch the signal
+ without taking special precautions.
+
+ For instance, if the stack starts at absolute address `0x80000000'
+ and grows downwards, you can use the flags
+ `-fstack-limit-symbol=__stack_limit' and
+ `-Wl,--defsym,__stack_limit=0x7ffe0000' to enforce a stack limit
+ of 128KB. Note that this may only work with the GNU linker.
+
+`-fargument-alias'
+`-fargument-noalias'
+`-fargument-noalias-global'
+ Specify the possible relationships among parameters and between
+ parameters and global data.
+
+ `-fargument-alias' specifies that arguments (parameters) may alias
+ each other and may alias global storage.
+ `-fargument-noalias' specifies that arguments do not alias each
+ other, but may alias global storage.
+ `-fargument-noalias-global' specifies that arguments do not alias
+ each other and do not alias global storage.
+
+ Each language will automatically use whatever option is required by
+ the language standard. You should not need to use these options
+ yourself.
+
+`-fleading-underscore'
+ This option and its counterpart, `-fno-leading-underscore',
+ forcibly change the way C symbols are represented in the object
+ file. One use is to help link with legacy assembly code.
+
+ *Warning:* the `-fleading-underscore' switch causes GCC to
+ generate code that is not binary compatible with code generated
+ without that switch. Use it to conform to a non-default
+ application binary interface. Not all targets provide complete
+ support for this switch.
- gcc -g -fgnu-runtime -O -c some_class.m
+\1f
+File: gcc.info, Node: Environment Variables, Next: Running Protoize, Prev: Code Gen Options, Up: Invoking GCC
+
+3.19 Environment Variables Affecting GCC
+========================================
+
+This section describes several environment variables that affect how GCC
+operates. Some of them work by specifying directories or prefixes to
+use when searching for various kinds of files. Some are used to
+specify other aspects of the compilation environment.
+
+ Note that you can also specify places to search using options such as
+`-B', `-I' and `-L' (*note Directory Options::). These take precedence
+over places specified using environment variables, which in turn take
+precedence over those specified by the configuration of GCC. *Note
+Controlling the Compilation Driver `gcc': (gccint)Driver.
+
+`LANG'
+`LC_CTYPE'
+`LC_MESSAGES'
+`LC_ALL'
+ These environment variables control the way that GCC uses
+ localization information that allow GCC to work with different
+ national conventions. GCC inspects the locale categories
+ `LC_CTYPE' and `LC_MESSAGES' if it has been configured to do so.
+ These locale categories can be set to any value supported by your
+ installation. A typical value is `en_UK' for English in the United
+ Kingdom.
+
+ The `LC_CTYPE' environment variable specifies character
+ classification. GCC uses it to determine the character boundaries
+ in a string; this is needed for some multibyte encodings that
+ contain quote and escape characters that would otherwise be
+ interpreted as a string end or escape.
+
+ The `LC_MESSAGES' environment variable specifies the language to
+ use in diagnostic messages.
+
+ If the `LC_ALL' environment variable is set, it overrides the value
+ of `LC_CTYPE' and `LC_MESSAGES'; otherwise, `LC_CTYPE' and
+ `LC_MESSAGES' default to the value of the `LANG' environment
+ variable. If none of these variables are set, GCC defaults to
+ traditional C English behavior.
+
+`TMPDIR'
+ If `TMPDIR' is set, it specifies the directory to use for temporary
+ files. GCC uses temporary files to hold the output of one stage of
+ compilation which is to be used as input to the next stage: for
+ example, the output of the preprocessor, which is the input to the
+ compiler proper.
+
+`GCC_EXEC_PREFIX'
+ If `GCC_EXEC_PREFIX' is set, it specifies a prefix to use in the
+ names of the subprograms executed by the compiler. No slash is
+ added when this prefix is combined with the name of a subprogram,
+ but you can specify a prefix that ends with a slash if you wish.
+
+ If `GCC_EXEC_PREFIX' is not set, GCC will attempt to figure out an
+ appropriate prefix to use based on the pathname it was invoked
+ with.
+
+ If GCC cannot find the subprogram using the specified prefix, it
+ tries looking in the usual places for the subprogram.
+
+ The default value of `GCC_EXEC_PREFIX' is `PREFIX/lib/gcc-lib/'
+ where PREFIX is the value of `prefix' when you ran the `configure'
+ script.
+
+ Other prefixes specified with `-B' take precedence over this
+ prefix.
+
+ This prefix is also used for finding files such as `crt0.o' that
+ are used for linking.
+
+ In addition, the prefix is used in an unusual way in finding the
+ directories to search for header files. For each of the standard
+ directories whose name normally begins with
+ `/usr/local/lib/gcc-lib' (more precisely, with the value of
+ `GCC_INCLUDE_DIR'), GCC tries replacing that beginning with the
+ specified prefix to produce an alternate directory name. Thus,
+ with `-Bfoo/', GCC will search `foo/bar' where it would normally
+ search `/usr/local/lib/bar'. These alternate directories are
+ searched first; the standard directories come next.
+
+`COMPILER_PATH'
+ The value of `COMPILER_PATH' is a colon-separated list of
+ directories, much like `PATH'. GCC tries the directories thus
+ specified when searching for subprograms, if it can't find the
+ subprograms using `GCC_EXEC_PREFIX'.
+
+`LIBRARY_PATH'
+ The value of `LIBRARY_PATH' is a colon-separated list of
+ directories, much like `PATH'. When configured as a native
+ compiler, GCC tries the directories thus specified when searching
+ for special linker files, if it can't find them using
+ `GCC_EXEC_PREFIX'. Linking using GCC also uses these directories
+ when searching for ordinary libraries for the `-l' option (but
+ directories specified with `-L' come first).
+
+`LANG'
+ This variable is used to pass locale information to the compiler.
+ One way in which this information is used is to determine the
+ character set to be used when character literals, string literals
+ and comments are parsed in C and C++. When the compiler is
+ configured to allow multibyte characters, the following values for
+ `LANG' are recognized:
+
+ `C-JIS'
+ Recognize JIS characters.
+
+ `C-SJIS'
+ Recognize SJIS characters.
+
+ `C-EUCJP'
+ Recognize EUCJP characters.
+
+ If `LANG' is not defined, or if it has some other value, then the
+ compiler will use mblen and mbtowc as defined by the default
+ locale to recognize and translate multibyte characters.
+
+Some additional environments variables affect the behavior of the
+preprocessor.
+
+`CPATH'
+`C_INCLUDE_PATH'
+`CPLUS_INCLUDE_PATH'
+`OBJC_INCLUDE_PATH'
+ Each variable's value is a list of directories separated by a
+ special character, much like `PATH', in which to look for header
+ files. The special character, `PATH_SEPARATOR', is
+ target-dependent and determined at GCC build time. For
+ Windows-based targets it is a semicolon, and for almost all other
+ targets it is a colon.
+
+ `CPATH' specifies a list of directories to be searched as if
+ specified with `-I', but after any paths given with `-I' options
+ on the command line. The environment variable is used regardless
+ of which language is being preprocessed.
+
+ The remaining environment variables apply only when preprocessing
+ the particular language indicated. Each specifies a list of
+ directories to be searched as if specified with `-isystem', but
+ after any paths given with `-isystem' options on the command line.
+
+`DEPENDENCIES_OUTPUT'
+ If this variable is set, its value specifies how to output
+ dependencies for Make based on the non-system header files
+ processed by the compiler. System header files are ignored in the
+ dependency output.
+
+ The value of `DEPENDENCIES_OUTPUT' can be just a file name, in
+ which case the Make rules are written to that file, guessing the
+ target name from the source file name. Or the value can have the
+ form `FILE TARGET', in which case the rules are written to file
+ FILE using TARGET as the target name.
+
+ In other words, this environment variable is equivalent to
+ combining the options `-MM' and `-MF' (*note Preprocessor
+ Options::), with an optional `-MT' switch too.
+
+`SUNPRO_DEPENDENCIES'
+ This variable is the same as the environment variable
+ `DEPENDENCIES_OUTPUT' (*note DEPENDENCIES_OUTPUT::), except that
+ system header files are not ignored, so it implies `-M' rather
+ than `-MM'. However, the dependence on the main input file is
+ omitted. *Note Preprocessor Options::.
-In this example, only `-fgnu-runtime' is an option meant only for
-Objective-C programs; you can use the other options with any language
-supported by GCC.
+\1f
+File: gcc.info, Node: Running Protoize, Prev: Environment Variables, Up: Invoking GCC
+
+3.20 Running Protoize
+=====================
+
+The program `protoize' is an optional part of GCC. You can use it to
+add prototypes to a program, thus converting the program to ISO C in
+one respect. The companion program `unprotoize' does the reverse: it
+removes argument types from any prototypes that are found.
+
+ When you run these programs, you must specify a set of source files
+as command line arguments. The conversion programs start out by
+compiling these files to see what functions they define. The
+information gathered about a file FOO is saved in a file named `FOO.X'.
+
+ After scanning comes actual conversion. The specified files are all
+eligible to be converted; any files they include (whether sources or
+just headers) are eligible as well.
+
+ But not all the eligible files are converted. By default,
+`protoize' and `unprotoize' convert only source and header files in the
+current directory. You can specify additional directories whose files
+should be converted with the `-d DIRECTORY' option. You can also
+specify particular files to exclude with the `-x FILE' option. A file
+is converted if it is eligible, its directory name matches one of the
+specified directory names, and its name within the directory has not
+been excluded.
+
+ Basic conversion with `protoize' consists of rewriting most function
+definitions and function declarations to specify the types of the
+arguments. The only ones not rewritten are those for varargs functions.
+
+ `protoize' optionally inserts prototype declarations at the
+beginning of the source file, to make them available for any calls that
+precede the function's definition. Or it can insert prototype
+declarations with block scope in the blocks where undeclared functions
+are called.
+
+ Basic conversion with `unprotoize' consists of rewriting most
+function declarations to remove any argument types, and rewriting
+function definitions to the old-style pre-ISO form.
+
+ Both conversion programs print a warning for any function
+declaration or definition that they can't convert. You can suppress
+these warnings with `-q'.
+
+ The output from `protoize' or `unprotoize' replaces the original
+source file. The original file is renamed to a name ending with
+`.save' (for DOS, the saved filename ends in `.sav' without the
+original `.c' suffix). If the `.save' (`.sav' for DOS) file already
+exists, then the source file is simply discarded.
+
+ `protoize' and `unprotoize' both depend on GCC itself to scan the
+program and collect information about the functions it uses. So
+neither of these programs will work until GCC is installed.
+
+ Here is a table of the options you can use with `protoize' and
+`unprotoize'. Each option works with both programs unless otherwise
+stated.
+
+`-B DIRECTORY'
+ Look for the file `SYSCALLS.c.X' in DIRECTORY, instead of the
+ usual directory (normally `/usr/local/lib'). This file contains
+ prototype information about standard system functions. This option
+ applies only to `protoize'.
+
+`-c COMPILATION-OPTIONS'
+ Use COMPILATION-OPTIONS as the options when running `gcc' to
+ produce the `.X' files. The special option `-aux-info' is always
+ passed in addition, to tell `gcc' to write a `.X' file.
+
+ Note that the compilation options must be given as a single
+ argument to `protoize' or `unprotoize'. If you want to specify
+ several `gcc' options, you must quote the entire set of
+ compilation options to make them a single word in the shell.
+
+ There are certain `gcc' arguments that you cannot use, because they
+ would produce the wrong kind of output. These include `-g', `-O',
+ `-c', `-S', and `-o' If you include these in the
+ COMPILATION-OPTIONS, they are ignored.
+
+`-C'
+ Rename files to end in `.C' (`.cc' for DOS-based file systems)
+ instead of `.c'. This is convenient if you are converting a C
+ program to C++. This option applies only to `protoize'.
+
+`-g'
+ Add explicit global declarations. This means inserting explicit
+ declarations at the beginning of each source file for each function
+ that is called in the file and was not declared. These
+ declarations precede the first function definition that contains a
+ call to an undeclared function. This option applies only to
+ `protoize'.
+
+`-i STRING'
+ Indent old-style parameter declarations with the string STRING.
+ This option applies only to `protoize'.
+
+ `unprotoize' converts prototyped function definitions to old-style
+ function definitions, where the arguments are declared between the
+ argument list and the initial `{'. By default, `unprotoize' uses
+ five spaces as the indentation. If you want to indent with just
+ one space instead, use `-i " "'.
+
+`-k'
+ Keep the `.X' files. Normally, they are deleted after conversion
+ is finished.
+
+`-l'
+ Add explicit local declarations. `protoize' with `-l' inserts a
+ prototype declaration for each function in each block which calls
+ the function without any declaration. This option applies only to
+ `protoize'.
+
+`-n'
+ Make no real changes. This mode just prints information about the
+ conversions that would have been done without `-n'.
+
+`-N'
+ Make no `.save' files. The original files are simply deleted.
+ Use this option with caution.
+
+`-p PROGRAM'
+ Use the program PROGRAM as the compiler. Normally, the name `gcc'
+ is used.
+
+`-q'
+ Work quietly. Most warnings are suppressed.
+
+`-v'
+ Print the version number, just like `-v' for `gcc'.
+
+ If you need special compiler options to compile one of your program's
+source files, then you should generate that file's `.X' file specially,
+by running `gcc' on that source file with the appropriate options and
+the option `-aux-info'. Then run `protoize' on the entire set of
+files. `protoize' will use the existing `.X' file because it is newer
+than the source file. For example:
+
+ gcc -Dfoo=bar file1.c -aux-info file1.X
+ protoize *.c
+
+You need to include the special files along with the rest in the
+`protoize' command, even though their `.X' files already exist, because
+otherwise they won't get converted.
+
+ *Note Protoize Caveats::, for more information on how to use
+`protoize' successfully.
- Here is a list of options that are _only_ for compiling Objective-C
-programs:
+\1f
+File: gcc.info, Node: C Implementation, Next: C Extensions, Prev: Invoking GCC, Up: Top
+
+4 C Implementation-defined behavior
+***********************************
+
+A conforming implementation of ISO C is required to document its choice
+of behavior in each of the areas that are designated "implementation
+defined." The following lists all such areas, along with the section
+number from the ISO/IEC 9899:1999 standard.
+
+* Menu:
+
+* Translation implementation::
+* Environment implementation::
+* Identifiers implementation::
+* Characters implementation::
+* Integers implementation::
+* Floating point implementation::
+* Arrays and pointers implementation::
+* Hints implementation::
+* Structures unions enumerations and bit-fields implementation::
+* Qualifiers implementation::
+* Preprocessing directives implementation::
+* Library functions implementation::
+* Architecture implementation::
+* Locale-specific behavior implementation::
-`-fconstant-string-class=CLASS-NAME'
- Use CLASS-NAME as the name of the class to instantiate for each
- literal string specified with the syntax `@"..."'. The default
- class name is `NXConstantString'.
+\1f
+File: gcc.info, Node: Translation implementation, Next: Environment implementation, Up: C Implementation
-`-fgnu-runtime'
- Generate object code compatible with the standard GNU Objective-C
- runtime. This is the default for most types of systems.
+4.1 Translation
+===============
-`-fnext-runtime'
- Generate output compatible with the NeXT runtime. This is the
- default for NeXT-based systems, including Darwin and Mac OS X.
+ * `How a diagnostic is identified (3.10, 5.1.1.3).'
-`-gen-decls'
- Dump interface declarations for all classes seen in the source
- file to a file named `SOURCENAME.decl'.
+ * `Whether each nonempty sequence of white-space characters other
+ than new-line is retained or replaced by one space character in
+ translation phase 3 (5.1.1.2).'
-`-Wno-protocol'
- Do not warn if methods required by a protocol are not implemented
- in the class adopting it.
+\1f
+File: gcc.info, Node: Environment implementation, Next: Identifiers implementation, Prev: Translation implementation, Up: C Implementation
-`-Wselector'
- Warn if a selector has multiple methods of different types defined.
+4.2 Environment
+===============
+The behavior of these points are dependent on the implementation of the
+C library, and are not defined by GCC itself.
\1f
-File: gcc.info, Node: Language Independent Options, Next: Warning Options, Prev: Objective-C Dialect Options, Up: Invoking GCC
+File: gcc.info, Node: Identifiers implementation, Next: Characters implementation, Prev: Environment implementation, Up: C Implementation
-Options to Control Diagnostic Messages Formatting
-=================================================
+4.3 Identifiers
+===============
+
+ * `Which additional multibyte characters may appear in identifiers
+ and their correspondence to universal character names (6.4.2).'
+
+ * `The number of significant initial characters in an identifier
+ (5.2.4.1, 6.4.2).'
+
+\1f
+File: gcc.info, Node: Characters implementation, Next: Integers implementation, Prev: Identifiers implementation, Up: C Implementation
+
+4.4 Characters
+==============
+
+ * `The number of bits in a byte (3.6).'
+
+ * `The values of the members of the execution character set (5.2.1).'
+
+ * `The unique value of the member of the execution character set
+ produced for each of the standard alphabetic escape sequences
+ (5.2.2).'
+
+ * `The value of a `char' object into which has been stored any
+ character other than a member of the basic execution character set
+ (6.2.5).'
+
+ * `Which of `signed char' or `unsigned char' has the same range,
+ representation, and behavior as "plain" `char' (6.2.5, 6.3.1.1).'
+
+ * `The mapping of members of the source character set (in character
+ constants and string literals) to members of the execution
+ character set (6.4.4.4, 5.1.1.2).'
+
+ * `The value of an integer character constant containing more than
+ one character or containing a character or escape sequence that
+ does not map to a single-byte execution character (6.4.4.4).'
+
+ * `The value of a wide character constant containing more than one
+ multibyte character, or containing a multibyte character or escape
+ sequence not represented in the extended execution character set
+ (6.4.4.4).'
+
+ * `The current locale used to convert a wide character constant
+ consisting of a single multibyte character that maps to a member
+ of the extended execution character set into a corresponding wide
+ character code (6.4.4.4).'
+
+ * `The current locale used to convert a wide string literal into
+ corresponding wide character codes (6.4.5).'
+
+ * `The value of a string literal containing a multibyte character or
+ escape sequence not represented in the execution character set
+ (6.4.5).'
+
+\1f
+File: gcc.info, Node: Integers implementation, Next: Floating point implementation, Prev: Characters implementation, Up: C Implementation
+
+4.5 Integers
+============
+
+ * `Any extended integer types that exist in the implementation
+ (6.2.5).'
+
+ * `Whether signed integer types are represented using sign and
+ magnitude, two's complement, or one's complement, and whether the
+ extraordinary value is a trap representation or an ordinary value
+ (6.2.6.2).'
+
+ * `The rank of any extended integer type relative to another extended
+ integer type with the same precision (6.3.1.1).'
+
+ * `The result of, or the signal raised by, converting an integer to a
+ signed integer type when the value cannot be represented in an
+ object of that type (6.3.1.3).'
+
+ * `The results of some bitwise operations on signed integers (6.5).'
+
+\1f
+File: gcc.info, Node: Floating point implementation, Next: Arrays and pointers implementation, Prev: Integers implementation, Up: C Implementation
+
+4.6 Floating point
+==================
+
+ * `The accuracy of the floating-point operations and of the library
+ functions in `<math.h>' and `<complex.h>' that return
+ floating-point results (5.2.4.2.2).'
+
+ * `The rounding behaviors characterized by non-standard values of
+ `FLT_ROUNDS' (5.2.4.2.2).'
+
+ * `The evaluation methods characterized by non-standard negative
+ values of `FLT_EVAL_METHOD' (5.2.4.2.2).'
+
+ * `The direction of rounding when an integer is converted to a
+ floating-point number that cannot exactly represent the original
+ value (6.3.1.4).'
+
+ * `The direction of rounding when a floating-point number is
+ converted to a narrower floating-point number (6.3.1.5).'
+
+ * `How the nearest representable value or the larger or smaller
+ representable value immediately adjacent to the nearest
+ representable value is chosen for certain floating constants
+ (6.4.4.2).'
+
+ * `Whether and how floating expressions are contracted when not
+ disallowed by the `FP_CONTRACT' pragma (6.5).'
+
+ * `The default state for the `FENV_ACCESS' pragma (7.6.1).'
+
+ * `Additional floating-point exceptions, rounding modes,
+ environments, and classifications, and their macro names (7.6,
+ 7.12).'
+
+ * `The default state for the `FP_CONTRACT' pragma (7.12.2).'
+
+ * `Whether the "inexact" floating-point exception can be raised when
+ the rounded result actually does equal the mathematical result in
+ an IEC 60559 conformant implementation (F.9).'
+
+ * `Whether the "underflow" (and "inexact") floating-point exception
+ can be raised when a result is tiny but not inexact in an IEC
+ 60559 conformant implementation (F.9).'
+
+
+\1f
+File: gcc.info, Node: Arrays and pointers implementation, Next: Hints implementation, Prev: Floating point implementation, Up: C Implementation
+
+4.7 Arrays and pointers
+=======================
+
+ * `The result of converting a pointer to an integer or vice versa
+ (6.3.2.3).'
+
+ A cast from pointer to integer discards most-significant bits if
+ the pointer representation is larger than the integer type,
+ sign-extends(1) if the pointer representation is smaller than the
+ integer type, otherwise the bits are unchanged.
+
+ A cast from integer to pointer discards most-significant bits if
+ the pointer representation is smaller than the integer type,
+ extends according to the signedness of the integer type if the
+ pointer representation is larger than the integer type, otherwise
+ the bits are unchanged.
+
+ When casting from pointer to integer and back again, the resulting
+ pointer must reference the same object as the original pointer,
+ otherwise the behavior is undefined. That is, one may not use
+ integer arithmetic to avoid the undefined behavior of pointer
+ arithmetic as proscribed in 6.5.6/8.
+
+ * `The size of the result of subtracting two pointers to elements of
+ the same array (6.5.6).'
+
+
+ ---------- Footnotes ----------
+
+ (1) Future versions of GCC may zero-extend, or use a target-defined
+`ptr_extend' pattern. Do not rely on sign extension.
+
+\1f
+File: gcc.info, Node: Hints implementation, Next: Structures unions enumerations and bit-fields implementation, Prev: Arrays and pointers implementation, Up: C Implementation
+
+4.8 Hints
+=========
+
+ * `The extent to which suggestions made by using the `register'
+ storage-class specifier are effective (6.7.1).'
+
+ * `The extent to which suggestions made by using the inline function
+ specifier are effective (6.7.4).'
+
+
+\1f
+File: gcc.info, Node: Structures unions enumerations and bit-fields implementation, Next: Qualifiers implementation, Prev: Hints implementation, Up: C Implementation
+
+4.9 Structures, unions, enumerations, and bit-fields
+====================================================
+
+ * `Whether a "plain" int bit-field is treated as a `signed int'
+ bit-field or as an `unsigned int' bit-field (6.7.2, 6.7.2.1).'
+
+ * `Allowable bit-field types other than `_Bool', `signed int', and
+ `unsigned int' (6.7.2.1).'
+
+ * `Whether a bit-field can straddle a storage-unit boundary
+ (6.7.2.1).'
+
+ * `The order of allocation of bit-fields within a unit (6.7.2.1).'
+
+ * `The alignment of non-bit-field members of structures (6.7.2.1).'
+
+ * `The integer type compatible with each enumerated type (6.7.2.2).'
+
+
+\1f
+File: gcc.info, Node: Qualifiers implementation, Next: Preprocessing directives implementation, Prev: Structures unions enumerations and bit-fields implementation, Up: C Implementation
+
+4.10 Qualifiers
+===============
+
+ * `What constitutes an access to an object that has
+ volatile-qualified type (6.7.3).'
+
+
+\1f
+File: gcc.info, Node: Preprocessing directives implementation, Next: Library functions implementation, Prev: Qualifiers implementation, Up: C Implementation
+
+4.11 Preprocessing directives
+=============================
+
+ * `How sequences in both forms of header names are mapped to headers
+ or external source file names (6.4.7).'
+
+ * `Whether the value of a character constant in a constant expression
+ that controls conditional inclusion matches the value of the same
+ character constant in the execution character set (6.10.1).'
+
+ * `Whether the value of a single-character character constant in a
+ constant expression that controls conditional inclusion may have a
+ negative value (6.10.1).'
+
+ * `The places that are searched for an included `<>' delimited
+ header, and how the places are specified or the header is
+ identified (6.10.2).'
+
+ * `How the named source file is searched for in an included `""'
+ delimited header (6.10.2).'
+
+ * `The method by which preprocessing tokens (possibly resulting from
+ macro expansion) in a `#include' directive are combined into a
+ header name (6.10.2).'
+
+ * `The nesting limit for `#include' processing (6.10.2).'
+
+ * `Whether the `#' operator inserts a `\' character before the `\'
+ character that begins a universal character name in a character
+ constant or string literal (6.10.3.2).'
+
+ * `The behavior on each recognized non-`STDC #pragma' directive
+ (6.10.6).'
+
+ * `The definitions for `__DATE__' and `__TIME__' when respectively,
+ the date and time of translation are not available (6.10.8).'
+
+
+\1f
+File: gcc.info, Node: Library functions implementation, Next: Architecture implementation, Prev: Preprocessing directives implementation, Up: C Implementation
+
+4.12 Library functions
+======================
+
+The behavior of these points are dependent on the implementation of the
+C library, and are not defined by GCC itself.
+
+\1f
+File: gcc.info, Node: Architecture implementation, Next: Locale-specific behavior implementation, Prev: Library functions implementation, Up: C Implementation
+
+4.13 Architecture
+=================
+
+ * `The values or expressions assigned to the macros specified in the
+ headers `<float.h>', `<limits.h>', and `<stdint.h>' (5.2.4.2,
+ 7.18.2, 7.18.3).'
+
+ * `The number, order, and encoding of bytes in any object (when not
+ explicitly specified in this International Standard) (6.2.6.1).'
+
+ * `The value of the result of the sizeof operator (6.5.3.4).'
+
+
+\1f
+File: gcc.info, Node: Locale-specific behavior implementation, Prev: Architecture implementation, Up: C Implementation
+
+4.14 Locale-specific behavior
+=============================
+
+The behavior of these points are dependent on the implementation of the
+C library, and are not defined by GCC itself.
+
+\1f
+File: gcc.info, Node: C Extensions, Next: C++ Extensions, Prev: C Implementation, Up: Top
+
+5 Extensions to the C Language Family
+*************************************
+
+GNU C provides several language features not found in ISO standard C.
+(The `-pedantic' option directs GCC to print a warning message if any
+of these features is used.) To test for the availability of these
+features in conditional compilation, check for a predefined macro
+`__GNUC__', which is always defined under GCC.
+
+ These extensions are available in C and Objective-C. Most of them
+are also available in C++. *Note Extensions to the C++ Language: C++
+Extensions, for extensions that apply _only_ to C++.
+
+ Some features that are in ISO C99 but not C89 or C++ are also, as
+extensions, accepted by GCC in C89 mode and in C++.
+
+* Menu:
+
+* Statement Exprs:: Putting statements and declarations inside expressions.
+* Local Labels:: Labels local to a statement-expression.
+* Labels as Values:: Getting pointers to labels, and computed gotos.
+* Nested Functions:: As in Algol and Pascal, lexical scoping of functions.
+* Constructing Calls:: Dispatching a call to another function.
+* Typeof:: `typeof': referring to the type of an expression.
+* Lvalues:: Using `?:', `,' and casts in lvalues.
+* Conditionals:: Omitting the middle operand of a `?:' expression.
+* Long Long:: Double-word integers---`long long int'.
+* Complex:: Data types for complex numbers.
+* Hex Floats:: Hexadecimal floating-point constants.
+* Zero Length:: Zero-length arrays.
+* Variable Length:: Arrays whose length is computed at run time.
+* Variadic Macros:: Macros with a variable number of arguments.
+* Escaped Newlines:: Slightly looser rules for escaped newlines.
+* Multi-line Strings:: String literals with embedded newlines.
+* Subscripting:: Any array can be subscripted, even if not an lvalue.
+* Pointer Arith:: Arithmetic on `void'-pointers and function pointers.
+* Initializers:: Non-constant initializers.
+* Compound Literals:: Compound literals give structures, unions
+ or arrays as values.
+* Designated Inits:: Labeling elements of initializers.
+* Cast to Union:: Casting to union type from any member of the union.
+* Case Ranges:: `case 1 ... 9' and such.
+* Mixed Declarations:: Mixing declarations and code.
+* Function Attributes:: Declaring that functions have no side effects,
+ or that they can never return.
+* Attribute Syntax:: Formal syntax for attributes.
+* Function Prototypes:: Prototype declarations and old-style definitions.
+* C++ Comments:: C++ comments are recognized.
+* Dollar Signs:: Dollar sign is allowed in identifiers.
+* Character Escapes:: `\e' stands for the character <ESC>.
+* Variable Attributes:: Specifying attributes of variables.
+* Type Attributes:: Specifying attributes of types.
+* Alignment:: Inquiring about the alignment of a type or variable.
+* Inline:: Defining inline functions (as fast as macros).
+* Extended Asm:: Assembler instructions with C expressions as operands.
+ (With them you can define ``built-in'' functions.)
+* Constraints:: Constraints for asm operands
+* Asm Labels:: Specifying the assembler name to use for a C symbol.
+* Explicit Reg Vars:: Defining variables residing in specified registers.
+* Alternate Keywords:: `__const__', `__asm__', etc., for header files.
+* Incomplete Enums:: `enum foo;', with details to follow.
+* Function Names:: Printable strings which are the name of the current
+ function.
+* Return Address:: Getting the return or frame address of a function.
+* Vector Extensions:: Using vector instructions through built-in functions.
+* Other Builtins:: Other built-in functions.
+* Target Builtins:: Built-in functions specific to particular targets.
+* Pragmas:: Pragmas accepted by GCC.
+* Unnamed Fields:: Unnamed struct/union fields within structs/unions.
+
+\1f
+File: gcc.info, Node: Statement Exprs, Next: Local Labels, Up: C Extensions
+
+5.1 Statements and Declarations in Expressions
+==============================================
+
+A compound statement enclosed in parentheses may appear as an expression
+in GNU C. This allows you to use loops, switches, and local variables
+within an expression.
+
+ Recall that a compound statement is a sequence of statements
+surrounded by braces; in this construct, parentheses go around the
+braces. For example:
+
+ ({ int y = foo (); int z;
+ if (y > 0) z = y;
+ else z = - y;
+ z; })
+
+is a valid (though slightly more complex than necessary) expression for
+the absolute value of `foo ()'.
+
+ The last thing in the compound statement should be an expression
+followed by a semicolon; the value of this subexpression serves as the
+value of the entire construct. (If you use some other kind of statement
+last within the braces, the construct has type `void', and thus
+effectively no value.)
- Traditionally, diagnostic messages have been formatted irrespective
-of the output device's aspect (e.g. its width, ...). The options
-described below can be used to control the diagnostic messages
-formatting algorithm, e.g. how many characters per line, how often
-source location information should be reported. Right now, only the
-C++ front end can honor these options. However it is expected, in the
-near future, that the remaining front ends would be able to digest them
-correctly.
-
-`-fmessage-length=N'
- Try to format error messages so that they fit on lines of about N
- characters. The default is 72 characters for `g++' and 0 for the
- rest of the front ends supported by GCC. If N is zero, then no
- line-wrapping will be done; each error message will appear on a
- single line.
-
-`-fdiagnostics-show-location=once'
- Only meaningful in line-wrapping mode. Instructs the diagnostic
- messages reporter to emit _once_ source location information; that
- is, in case the message is too long to fit on a single physical
- line and has to be wrapped, the source location won't be emitted
- (as prefix) again, over and over, in subsequent continuation
- lines. This is the default behavior.
-
-`-fdiagnostics-show-location=every-line'
- Only meaningful in line-wrapping mode. Instructs the diagnostic
- messages reporter to emit the same source location information (as
- prefix) for physical lines that result from the process of breaking
- a message which is too long to fit on a single line.
+ This feature is especially useful in making macro definitions "safe"
+(so that they evaluate each operand exactly once). For example, the
+"maximum" function is commonly defined as a macro in standard C as
+follows:
+ #define max(a,b) ((a) > (b) ? (a) : (b))
+
+But this definition computes either A or B twice, with bad results if
+the operand has side effects. In GNU C, if you know the type of the
+operands (here let's assume `int'), you can define the macro safely as
+follows:
+
+ #define maxint(a,b) \
+ ({int _a = (a), _b = (b); _a > _b ? _a : _b; })
+
+ Embedded statements are not allowed in constant expressions, such as
+the value of an enumeration constant, the width of a bit-field, or the
+initial value of a static variable.
+
+ If you don't know the type of the operand, you can still do this,
+but you must use `typeof' (*note Typeof::).
+
+ Statement expressions are not supported fully in G++, and their fate
+there is unclear. (It is possible that they will become fully supported
+at some point, or that they will be deprecated, or that the bugs that
+are present will continue to exist indefinitely.) Presently, statement
+expressions do not work well as default arguments.
+
+ In addition, there are semantic issues with statement-expressions in
+C++. If you try to use statement-expressions instead of inline
+functions in C++, you may be surprised at the way object destruction is
+handled. For example:
+
+ #define foo(a) ({int b = (a); b + 3; })
+
+does not work the same way as:
+
+ inline int foo(int a) { int b = a; return b + 3; }
+
+In particular, if the expression passed into `foo' involves the
+creation of temporaries, the destructors for those temporaries will be
+run earlier in the case of the macro than in the case of the function.
+
+ These considerations mean that it is probably a bad idea to use
+statement-expressions of this form in header files that are designed to
+work with C++. (Note that some versions of the GNU C Library contained
+header files using statement-expression that lead to precisely this
+bug.)
+
+\1f
+File: gcc.info, Node: Local Labels, Next: Labels as Values, Prev: Statement Exprs, Up: C Extensions
+
+5.2 Locally Declared Labels
+===========================
+
+Each statement expression is a scope in which "local labels" can be
+declared. A local label is simply an identifier; you can jump to it
+with an ordinary `goto' statement, but only from within the statement
+expression it belongs to.
+
+ A local label declaration looks like this:
+
+ __label__ LABEL;
+
+or
+
+ __label__ LABEL1, LABEL2, ...;
+
+ Local label declarations must come at the beginning of the statement
+expression, right after the `({', before any ordinary declarations.
+
+ The label declaration defines the label _name_, but does not define
+the label itself. You must do this in the usual way, with `LABEL:',
+within the statements of the statement expression.
+
+ The local label feature is useful because statement expressions are
+often used in macros. If the macro contains nested loops, a `goto' can
+be useful for breaking out of them. However, an ordinary label whose
+scope is the whole function cannot be used: if the macro can be
+expanded several times in one function, the label will be multiply
+defined in that function. A local label avoids this problem. For
+example:
+
+ #define SEARCH(array, target) \
+ ({ \
+ __label__ found; \
+ typeof (target) _SEARCH_target = (target); \
+ typeof (*(array)) *_SEARCH_array = (array); \
+ int i, j; \
+ int value; \
+ for (i = 0; i < max; i++) \
+ for (j = 0; j < max; j++) \
+ if (_SEARCH_array[i][j] == _SEARCH_target) \
+ { value = i; goto found; } \
+ value = -1; \
+ found: \
+ value; \
+ })
+
+\1f
+File: gcc.info, Node: Labels as Values, Next: Nested Functions, Prev: Local Labels, Up: C Extensions
+
+5.3 Labels as Values
+====================
+
+You can get the address of a label defined in the current function (or
+a containing function) with the unary operator `&&'. The value has
+type `void *'. This value is a constant and can be used wherever a
+constant of that type is valid. For example:
+
+ void *ptr;
+ ...
+ ptr = &&foo;
+
+ To use these values, you need to be able to jump to one. This is
+done with the computed goto statement(1), `goto *EXP;'. For example,
+
+ goto *ptr;
+
+Any expression of type `void *' is allowed.
+
+ One way of using these constants is in initializing a static array
+that will serve as a jump table:
+
+ static void *array[] = { &&foo, &&bar, &&hack };
+
+ Then you can select a label with indexing, like this:
+
+ goto *array[i];
+
+Note that this does not check whether the subscript is in bounds--array
+indexing in C never does that.
+
+ Such an array of label values serves a purpose much like that of the
+`switch' statement. The `switch' statement is cleaner, so use that
+rather than an array unless the problem does not fit a `switch'
+statement very well.
+
+ Another use of label values is in an interpreter for threaded code.
+The labels within the interpreter function can be stored in the
+threaded code for super-fast dispatching.
+
+ You may not use this mechanism to jump to code in a different
+function. If you do that, totally unpredictable things will happen.
+The best way to avoid this is to store the label address only in
+automatic variables and never pass it as an argument.
+
+ An alternate way to write the above example is
+
+ static const int array[] = { &&foo - &&foo, &&bar - &&foo,
+ &&hack - &&foo };
+ goto *(&&foo + array[i]);
+
+This is more friendly to code living in shared libraries, as it reduces
+the number of dynamic relocations that are needed, and by consequence,
+allows the data to be read-only.
+
+ ---------- Footnotes ----------
+
+ (1) The analogous feature in Fortran is called an assigned goto, but
+that name seems inappropriate in C, where one can do more than simply
+store label addresses in label variables.
+
+\1f
+File: gcc.info, Node: Nested Functions, Next: Constructing Calls, Prev: Labels as Values, Up: C Extensions
+
+5.4 Nested Functions
+====================
+
+A "nested function" is a function defined inside another function.
+(Nested functions are not supported for GNU C++.) The nested function's
+name is local to the block where it is defined. For example, here we
+define a nested function named `square', and call it twice:
+
+ foo (double a, double b)
+ {
+ double square (double z) { return z * z; }
+
+ return square (a) + square (b);
+ }
+
+ The nested function can access all the variables of the containing
+function that are visible at the point of its definition. This is
+called "lexical scoping". For example, here we show a nested function
+which uses an inherited variable named `offset':
+
+ bar (int *array, int offset, int size)
+ {
+ int access (int *array, int index)
+ { return array[index + offset]; }
+ int i;
+ ...
+ for (i = 0; i < size; i++)
+ ... access (array, i) ...
+ }
+
+ Nested function definitions are permitted within functions in the
+places where variable definitions are allowed; that is, in any block,
+before the first statement in the block.
+
+ It is possible to call the nested function from outside the scope of
+its name by storing its address or passing the address to another
+function:
+
+ hack (int *array, int size)
+ {
+ void store (int index, int value)
+ { array[index] = value; }
+
+ intermediate (store, size);
+ }
+
+ Here, the function `intermediate' receives the address of `store' as
+an argument. If `intermediate' calls `store', the arguments given to
+`store' are used to store into `array'. But this technique works only
+so long as the containing function (`hack', in this example) does not
+exit.
+
+ If you try to call the nested function through its address after the
+containing function has exited, all hell will break loose. If you try
+to call it after a containing scope level has exited, and if it refers
+to some of the variables that are no longer in scope, you may be lucky,
+but it's not wise to take the risk. If, however, the nested function
+does not refer to anything that has gone out of scope, you should be
+safe.
+
+ GCC implements taking the address of a nested function using a
+technique called "trampolines". A paper describing them is available as
+
+`http://people.debian.org/~aaronl/Usenix88-lexic.pdf'.
+
+ A nested function can jump to a label inherited from a containing
+function, provided the label was explicitly declared in the containing
+function (*note Local Labels::). Such a jump returns instantly to the
+containing function, exiting the nested function which did the `goto'
+and any intermediate functions as well. Here is an example:
+
+ bar (int *array, int offset, int size)
+ {
+ __label__ failure;
+ int access (int *array, int index)
+ {
+ if (index > size)
+ goto failure;
+ return array[index + offset];
+ }
+ int i;
+ ...
+ for (i = 0; i < size; i++)
+ ... access (array, i) ...
+ ...
+ return 0;
+
+ /* Control comes here from `access'
+ if it detects an error. */
+ failure:
+ return -1;
+ }
+
+ A nested function always has internal linkage. Declaring one with
+`extern' is erroneous. If you need to declare the nested function
+before its definition, use `auto' (which is otherwise meaningless for
+function declarations).
+
+ bar (int *array, int offset, int size)
+ {
+ __label__ failure;
+ auto int access (int *, int);
+ ...
+ int access (int *array, int index)
+ {
+ if (index > size)
+ goto failure;
+ return array[index + offset];
+ }
+ ...
+ }
+
+\1f
+File: gcc.info, Node: Constructing Calls, Next: Typeof, Prev: Nested Functions, Up: C Extensions
+
+5.5 Constructing Function Calls
+===============================
+
+Using the built-in functions described below, you can record the
+arguments a function received, and call another function with the same
+arguments, without knowing the number or types of the arguments.
+
+ You can also record the return value of that function call, and
+later return that value, without knowing what data type the function
+tried to return (as long as your caller expects that data type).
+
+ -- Built-in Function: void * __builtin_apply_args ()
+ This built-in function returns a pointer to data describing how to
+ perform a call with the same arguments as were passed to the
+ current function.
+
+ The function saves the arg pointer register, structure value
+ address, and all registers that might be used to pass arguments to
+ a function into a block of memory allocated on the stack. Then it
+ returns the address of that block.
+
+ -- Built-in Function: void * __builtin_apply (void (*FUNCTION)(), void
+ *ARGUMENTS, size_t SIZE)
+ This built-in function invokes FUNCTION with a copy of the
+ parameters described by ARGUMENTS and SIZE.
+
+ The value of ARGUMENTS should be the value returned by
+ `__builtin_apply_args'. The argument SIZE specifies the size of
+ the stack argument data, in bytes.
+
+ This function returns a pointer to data describing how to return
+ whatever value was returned by FUNCTION. The data is saved in a
+ block of memory allocated on the stack.
+
+ It is not always simple to compute the proper value for SIZE. The
+ value is used by `__builtin_apply' to compute the amount of data
+ that should be pushed on the stack and copied from the incoming
+ argument area.
+
+ -- Built-in Function: void __builtin_return (void *RESULT)
+ This built-in function returns the value described by RESULT from
+ the containing function. You should specify, for RESULT, a value
+ returned by `__builtin_apply'.
+
+\1f
+File: gcc.info, Node: Typeof, Next: Lvalues, Prev: Constructing Calls, Up: C Extensions
+
+5.6 Referring to a Type with `typeof'
+=====================================
+
+Another way to refer to the type of an expression is with `typeof'.
+The syntax of using of this keyword looks like `sizeof', but the
+construct acts semantically like a type name defined with `typedef'.
+
+ There are two ways of writing the argument to `typeof': with an
+expression or with a type. Here is an example with an expression:
+
+ typeof (x[0](1))
+
+This assumes that `x' is an array of pointers to functions; the type
+described is that of the values of the functions.
+
+ Here is an example with a typename as the argument:
+
+ typeof (int *)
+
+Here the type described is that of pointers to `int'.
+
+ If you are writing a header file that must work when included in ISO
+C programs, write `__typeof__' instead of `typeof'. *Note Alternate
+Keywords::.
+
+ A `typeof'-construct can be used anywhere a typedef name could be
+used. For example, you can use it in a declaration, in a cast, or
+inside of `sizeof' or `typeof'.
+
+ `typeof' is often useful in conjunction with the
+statements-within-expressions feature. Here is how the two together can
+be used to define a safe "maximum" macro that operates on any
+arithmetic type and evaluates each of its arguments exactly once:
+
+ #define max(a,b) \
+ ({ typeof (a) _a = (a); \
+ typeof (b) _b = (b); \
+ _a > _b ? _a : _b; })
+
+ The reason for using names that start with underscores for the local
+variables is to avoid conflicts with variable names that occur within
+the expressions that are substituted for `a' and `b'. Eventually we
+hope to design a new form of declaration syntax that allows you to
+declare variables whose scopes start only after their initializers;
+this will be a more reliable way to prevent such conflicts.
+
+Some more examples of the use of `typeof':
+
+ * This declares `y' with the type of what `x' points to.
+
+ typeof (*x) y;
+
+ * This declares `y' as an array of such values.
+
+ typeof (*x) y[4];
+
+ * This declares `y' as an array of pointers to characters:
+
+ typeof (typeof (char *)[4]) y;
+
+ It is equivalent to the following traditional C declaration:
+
+ char *y[4];
+
+ To see the meaning of the declaration using `typeof', and why it
+ might be a useful way to write, let's rewrite it with these macros:
+
+ #define pointer(T) typeof(T *)
+ #define array(T, N) typeof(T [N])
+
+ Now the declaration can be rewritten this way:
+
+ array (pointer (char), 4) y;
+
+ Thus, `array (pointer (char), 4)' is the type of arrays of 4
+ pointers to `char'.
+
+ _Compatibility Note:_ In addition to `typeof', GCC 2 supported a
+more limited extension which permitted one to write
+
+ typedef T = EXPR;
+
+with the effect of declaring T to have the type of the expression EXPR.
+This extension does not work with GCC 3 (versions between 3.0 and 3.2
+will crash; 3.2.1 and later give an error). Code which relies on it
+should be rewritten to use `typeof':
+
+ typedef typeof(EXPR) T;
+
+This will work with all versions of GCC.
+
+\1f
+File: gcc.info, Node: Lvalues, Next: Conditionals, Prev: Typeof, Up: C Extensions
+
+5.7 Generalized Lvalues
+=======================
+
+Compound expressions, conditional expressions and casts are allowed as
+lvalues provided their operands are lvalues. This means that you can
+take their addresses or store values into them.
+
+ Standard C++ allows compound expressions and conditional expressions
+as lvalues, and permits casts to reference type, so use of this
+extension is deprecated for C++ code.
+
+ For example, a compound expression can be assigned, provided the last
+expression in the sequence is an lvalue. These two expressions are
+equivalent:
+
+ (a, b) += 5
+ a, (b += 5)
+
+ Similarly, the address of the compound expression can be taken.
+These two expressions are equivalent:
+
+ &(a, b)
+ a, &b
+
+ A conditional expression is a valid lvalue if its type is not void
+and the true and false branches are both valid lvalues. For example,
+these two expressions are equivalent:
+
+ (a ? b : c) = 5
+ (a ? b = 5 : (c = 5))
+
+ A cast is a valid lvalue if its operand is an lvalue. A simple
+assignment whose left-hand side is a cast works by converting the
+right-hand side first to the specified type, then to the type of the
+inner left-hand side expression. After this is stored, the value is
+converted back to the specified type to become the value of the
+assignment. Thus, if `a' has type `char *', the following two
+expressions are equivalent:
+
+ (int)a = 5
+ (int)(a = (char *)(int)5)
+
+ An assignment-with-arithmetic operation such as `+=' applied to a
+cast performs the arithmetic using the type resulting from the cast,
+and then continues as in the previous case. Therefore, these two
+expressions are equivalent:
+
+ (int)a += 5
+ (int)(a = (char *)(int) ((int)a + 5))
+
+ You cannot take the address of an lvalue cast, because the use of its
+address would not work out coherently. Suppose that `&(int)f' were
+permitted, where `f' has type `float'. Then the following statement
+would try to store an integer bit-pattern where a floating point number
+belongs:
+
+ *&(int)f = 1;
+
+ This is quite different from what `(int)f = 1' would do--that would
+convert 1 to floating point and store it. Rather than cause this
+inconsistency, we think it is better to prohibit use of `&' on a cast.
+
+ If you really do want an `int *' pointer with the address of `f',
+you can simply write `(int *)&f'.
+
+\1f
+File: gcc.info, Node: Conditionals, Next: Long Long, Prev: Lvalues, Up: C Extensions
+
+5.8 Conditionals with Omitted Operands
+======================================
+
+The middle operand in a conditional expression may be omitted. Then if
+the first operand is nonzero, its value is the value of the conditional
+expression.
+
+ Therefore, the expression
+
+ x ? : y
+
+has the value of `x' if that is nonzero; otherwise, the value of `y'.
+
+ This example is perfectly equivalent to
+
+ x ? x : y
+
+In this simple case, the ability to omit the middle operand is not
+especially useful. When it becomes useful is when the first operand
+does, or may (if it is a macro argument), contain a side effect. Then
+repeating the operand in the middle would perform the side effect
+twice. Omitting the middle operand uses the value already computed
+without the undesirable effects of recomputing it.
+
+\1f
+File: gcc.info, Node: Long Long, Next: Complex, Prev: Conditionals, Up: C Extensions
+
+5.9 Double-Word Integers
+========================
+
+ISO C99 supports data types for integers that are at least 64 bits wide,
+and as an extension GCC supports them in C89 mode and in C++. Simply
+write `long long int' for a signed integer, or `unsigned long long int'
+for an unsigned integer. To make an integer constant of type `long
+long int', add the suffix `LL' to the integer. To make an integer
+constant of type `unsigned long long int', add the suffix `ULL' to the
+integer.
+
+ You can use these types in arithmetic like any other integer types.
+Addition, subtraction, and bitwise boolean operations on these types
+are open-coded on all types of machines. Multiplication is open-coded
+if the machine supports fullword-to-doubleword a widening multiply
+instruction. Division and shifts are open-coded only on machines that
+provide special support. The operations that are not open-coded use
+special library routines that come with GCC.
+
+ There may be pitfalls when you use `long long' types for function
+arguments, unless you declare function prototypes. If a function
+expects type `int' for its argument, and you pass a value of type `long
+long int', confusion will result because the caller and the subroutine
+will disagree about the number of bytes for the argument. Likewise, if
+the function expects `long long int' and you pass `int'. The best way
+to avoid such problems is to use prototypes.
+
+\1f
+File: gcc.info, Node: Complex, Next: Hex Floats, Prev: Long Long, Up: C Extensions
+
+5.10 Complex Numbers
+====================
+
+ISO C99 supports complex floating data types, and as an extension GCC
+supports them in C89 mode and in C++, and supports complex integer data
+types which are not part of ISO C99. You can declare complex types
+using the keyword `_Complex'. As an extension, the older GNU keyword
+`__complex__' is also supported.
+
+ For example, `_Complex double x;' declares `x' as a variable whose
+real part and imaginary part are both of type `double'. `_Complex
+short int y;' declares `y' to have real and imaginary parts of type
+`short int'; this is not likely to be useful, but it shows that the set
+of complex types is complete.
+
+ To write a constant with a complex data type, use the suffix `i' or
+`j' (either one; they are equivalent). For example, `2.5fi' has type
+`_Complex float' and `3i' has type `_Complex int'. Such a constant
+always has a pure imaginary value, but you can form any complex value
+you like by adding one to a real constant. This is a GNU extension; if
+you have an ISO C99 conforming C library (such as GNU libc), and want
+to construct complex constants of floating type, you should include
+`<complex.h>' and use the macros `I' or `_Complex_I' instead.
+
+ To extract the real part of a complex-valued expression EXP, write
+`__real__ EXP'. Likewise, use `__imag__' to extract the imaginary
+part. This is a GNU extension; for values of floating type, you should
+use the ISO C99 functions `crealf', `creal', `creall', `cimagf',
+`cimag' and `cimagl', declared in `<complex.h>' and also provided as
+built-in functions by GCC.
+
+ The operator `~' performs complex conjugation when used on a value
+with a complex type. This is a GNU extension; for values of floating
+type, you should use the ISO C99 functions `conjf', `conj' and `conjl',
+declared in `<complex.h>' and also provided as built-in functions by
+GCC.
+
+ GCC can allocate complex automatic variables in a noncontiguous
+fashion; it's even possible for the real part to be in a register while
+the imaginary part is on the stack (or vice-versa). None of the
+supported debugging info formats has a way to represent noncontiguous
+allocation like this, so GCC describes a noncontiguous complex variable
+as if it were two separate variables of noncomplex type. If the
+variable's actual name is `foo', the two fictitious variables are named
+`foo$real' and `foo$imag'. You can examine and set these two
+fictitious variables with your debugger.
+
+ A future version of GDB will know how to recognize such pairs and
+treat them as a single variable with a complex type.
+
+\1f
+File: gcc.info, Node: Hex Floats, Next: Zero Length, Prev: Complex, Up: C Extensions
+
+5.11 Hex Floats
+===============
+
+ISO C99 supports floating-point numbers written not only in the usual
+decimal notation, such as `1.55e1', but also numbers such as `0x1.fp3'
+written in hexadecimal format. As a GNU extension, GCC supports this
+in C89 mode (except in some cases when strictly conforming) and in C++.
+In that format the `0x' hex introducer and the `p' or `P' exponent
+field are mandatory. The exponent is a decimal number that indicates
+the power of 2 by which the significant part will be multiplied. Thus
+`0x1.f' is 1 15/16, `p3' multiplies it by 8, and the value of `0x1.fp3'
+is the same as `1.55e1'.
+
+ Unlike for floating-point numbers in the decimal notation the
+exponent is always required in the hexadecimal notation. Otherwise the
+compiler would not be able to resolve the ambiguity of, e.g., `0x1.f'.
+This could mean `1.0f' or `1.9375' since `f' is also the extension for
+floating-point constants of type `float'.
+
+\1f
+File: gcc.info, Node: Zero Length, Next: Variable Length, Prev: Hex Floats, Up: C Extensions
+
+5.12 Arrays of Length Zero
+==========================
+
+Zero-length arrays are allowed in GNU C. They are very useful as the
+last element of a structure which is really a header for a
+variable-length object:
+
+ struct line {
+ int length;
+ char contents[0];
+ };
+
+ struct line *thisline = (struct line *)
+ malloc (sizeof (struct line) + this_length);
+ thisline->length = this_length;
+
+ In ISO C89, you would have to give `contents' a length of 1, which
+means either you waste space or complicate the argument to `malloc'.
+
+ In ISO C99, you would use a "flexible array member", which is
+slightly different in syntax and semantics:
+
+ * Flexible array members are written as `contents[]' without the `0'.
+
+ * Flexible array members have incomplete type, and so the `sizeof'
+ operator may not be applied. As a quirk of the original
+ implementation of zero-length arrays, `sizeof' evaluates to zero.
+
+ * Flexible array members may only appear as the last member of a
+ `struct' that is otherwise non-empty.
+
+ GCC versions before 3.0 allowed zero-length arrays to be statically
+initialized, as if they were flexible arrays. In addition to those
+cases that were useful, it also allowed initializations in situations
+that would corrupt later data. Non-empty initialization of zero-length
+arrays is now treated like any case where there are more initializer
+elements than the array holds, in that a suitable warning about "excess
+elements in array" is given, and the excess elements (all of them, in
+this case) are ignored.
+
+ Instead GCC allows static initialization of flexible array members.
+This is equivalent to defining a new structure containing the original
+structure followed by an array of sufficient size to contain the data.
+I.e. in the following, `f1' is constructed as if it were declared like
+`f2'.
+
+ struct f1 {
+ int x; int y[];
+ } f1 = { 1, { 2, 3, 4 } };
+
+ struct f2 {
+ struct f1 f1; int data[3];
+ } f2 = { { 1 }, { 2, 3, 4 } };
+
+The convenience of this extension is that `f1' has the desired type,
+eliminating the need to consistently refer to `f2.f1'.
+
+ This has symmetry with normal static arrays, in that an array of
+unknown size is also written with `[]'.
+
+ Of course, this extension only makes sense if the extra data comes at
+the end of a top-level object, as otherwise we would be overwriting
+data at subsequent offsets. To avoid undue complication and confusion
+with initialization of deeply nested arrays, we simply disallow any
+non-empty initialization except when the structure is the top-level
+object. For example:
+
+ struct foo { int x; int y[]; };
+ struct bar { struct foo z; };
+
+ struct foo a = { 1, { 2, 3, 4 } }; // Valid.
+ struct bar b = { { 1, { 2, 3, 4 } } }; // Invalid.
+ struct bar c = { { 1, { } } }; // Valid.
+ struct foo d[1] = { { 1 { 2, 3, 4 } } }; // Invalid.
+
+\1f
+File: gcc.info, Node: Variable Length, Next: Variadic Macros, Prev: Zero Length, Up: C Extensions
+
+5.13 Arrays of Variable Length
+==============================
+
+Variable-length automatic arrays are allowed in ISO C99, and as an
+extension GCC accepts them in C89 mode and in C++. (However, GCC's
+implementation of variable-length arrays does not yet conform in detail
+to the ISO C99 standard.) These arrays are declared like any other
+automatic arrays, but with a length that is not a constant expression.
+The storage is allocated at the point of declaration and deallocated
+when the brace-level is exited. For example:
+
+ FILE *
+ concat_fopen (char *s1, char *s2, char *mode)
+ {
+ char str[strlen (s1) + strlen (s2) + 1];
+ strcpy (str, s1);
+ strcat (str, s2);
+ return fopen (str, mode);
+ }
+
+ Jumping or breaking out of the scope of the array name deallocates
+the storage. Jumping into the scope is not allowed; you get an error
+message for it.
+
+ You can use the function `alloca' to get an effect much like
+variable-length arrays. The function `alloca' is available in many
+other C implementations (but not in all). On the other hand,
+variable-length arrays are more elegant.
+
+ There are other differences between these two methods. Space
+allocated with `alloca' exists until the containing _function_ returns.
+The space for a variable-length array is deallocated as soon as the
+array name's scope ends. (If you use both variable-length arrays and
+`alloca' in the same function, deallocation of a variable-length array
+will also deallocate anything more recently allocated with `alloca'.)
+
+ You can also use variable-length arrays as arguments to functions:
+
+ struct entry
+ tester (int len, char data[len][len])
+ {
+ ...
+ }
+
+ The length of an array is computed once when the storage is allocated
+and is remembered for the scope of the array in case you access it with
+`sizeof'.
+
+ If you want to pass the array first and the length afterward, you can
+use a forward declaration in the parameter list--another GNU extension.
+
+ struct entry
+ tester (int len; char data[len][len], int len)
+ {
+ ...
+ }
+
+ The `int len' before the semicolon is a "parameter forward
+declaration", and it serves the purpose of making the name `len' known
+when the declaration of `data' is parsed.
+
+ You can write any number of such parameter forward declarations in
+the parameter list. They can be separated by commas or semicolons, but
+the last one must end with a semicolon, which is followed by the "real"
+parameter declarations. Each forward declaration must match a "real"
+declaration in parameter name and data type. ISO C99 does not support
+parameter forward declarations.
+
+\1f
+File: gcc.info, Node: Variadic Macros, Next: Escaped Newlines, Prev: Variable Length, Up: C Extensions
+
+5.14 Macros with a Variable Number of Arguments.
+================================================
+
+In the ISO C standard of 1999, a macro can be declared to accept a
+variable number of arguments much as a function can. The syntax for
+defining the macro is similar to that of a function. Here is an
+example:
+
+ #define debug(format, ...) fprintf (stderr, format, __VA_ARGS__)
+
+ Here `...' is a "variable argument". In the invocation of such a
+macro, it represents the zero or more tokens until the closing
+parenthesis that ends the invocation, including any commas. This set of
+tokens replaces the identifier `__VA_ARGS__' in the macro body wherever
+it appears. See the CPP manual for more information.
+
+ GCC has long supported variadic macros, and used a different syntax
+that allowed you to give a name to the variable arguments just like any
+other argument. Here is an example:
+
+ #define debug(format, args...) fprintf (stderr, format, args)
+
+ This is in all ways equivalent to the ISO C example above, but
+arguably more readable and descriptive.
+
+ GNU CPP has two further variadic macro extensions, and permits them
+to be used with either of the above forms of macro definition.
+
+ In standard C, you are not allowed to leave the variable argument out
+entirely; but you are allowed to pass an empty argument. For example,
+this invocation is invalid in ISO C, because there is no comma after
+the string:
+
+ debug ("A message")
+
+ GNU CPP permits you to completely omit the variable arguments in this
+way. In the above examples, the compiler would complain, though since
+the expansion of the macro still has the extra comma after the format
+string.
+
+ To help solve this problem, CPP behaves specially for variable
+arguments used with the token paste operator, `##'. If instead you
+write
+
+ #define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__)
+
+ and if the variable arguments are omitted or empty, the `##'
+operator causes the preprocessor to remove the comma before it. If you
+do provide some variable arguments in your macro invocation, GNU CPP
+does not complain about the paste operation and instead places the
+variable arguments after the comma. Just like any other pasted macro
+argument, these arguments are not macro expanded.
+
+\1f
+File: gcc.info, Node: Escaped Newlines, Next: Multi-line Strings, Prev: Variadic Macros, Up: C Extensions
+
+5.15 Slightly Looser Rules for Escaped Newlines
+===============================================
+
+Recently, the non-traditional preprocessor has relaxed its treatment of
+escaped newlines. Previously, the newline had to immediately follow a
+backslash. The current implementation allows whitespace in the form of
+spaces, horizontal and vertical tabs, and form feeds between the
+backslash and the subsequent newline. The preprocessor issues a
+warning, but treats it as a valid escaped newline and combines the two
+lines to form a single logical line. This works within comments and
+tokens, including multi-line strings, as well as between tokens.
+Comments are _not_ treated as whitespace for the purposes of this
+relaxation, since they have not yet been replaced with spaces.
+
+\1f
+File: gcc.info, Node: Multi-line Strings, Next: Subscripting, Prev: Escaped Newlines, Up: C Extensions
+
+5.16 String Literals with Embedded Newlines
+===========================================
+
+As an extension, GNU CPP permits string literals to cross multiple lines
+without escaping the embedded newlines. Each embedded newline is
+replaced with a single `\n' character in the resulting string literal,
+regardless of what form the newline took originally.
+
+ CPP currently allows such strings in directives as well (other than
+the `#include' family). This is deprecated and will eventually be
+removed.
+
+\1f
+File: gcc.info, Node: Subscripting, Next: Pointer Arith, Prev: Multi-line Strings, Up: C Extensions
+
+5.17 Non-Lvalue Arrays May Have Subscripts
+==========================================
+
+In ISO C99, arrays that are not lvalues still decay to pointers, and
+may be subscripted, although they may not be modified or used after the
+next sequence point and the unary `&' operator may not be applied to
+them. As an extension, GCC allows such arrays to be subscripted in C89
+mode, though otherwise they do not decay to pointers outside C99 mode.
+For example, this is valid in GNU C though not valid in C89:
+
+ struct foo {int a[4];};
+
+ struct foo f();
+
+ bar (int index)
+ {
+ return f().a[index];
+ }
+
+\1f
+File: gcc.info, Node: Pointer Arith, Next: Initializers, Prev: Subscripting, Up: C Extensions
+
+5.18 Arithmetic on `void'- and Function-Pointers
+================================================
+
+In GNU C, addition and subtraction operations are supported on pointers
+to `void' and on pointers to functions. This is done by treating the
+size of a `void' or of a function as 1.
+
+ A consequence of this is that `sizeof' is also allowed on `void' and
+on function types, and returns 1.
+
+ The option `-Wpointer-arith' requests a warning if these extensions
+are used.
+
+\1f
+File: gcc.info, Node: Initializers, Next: Compound Literals, Prev: Pointer Arith, Up: C Extensions
+
+5.19 Non-Constant Initializers
+==============================
+
+As in standard C++ and ISO C99, the elements of an aggregate
+initializer for an automatic variable are not required to be constant
+expressions in GNU C. Here is an example of an initializer with
+run-time varying elements:
+
+ foo (float f, float g)
+ {
+ float beat_freqs[2] = { f-g, f+g };
+ ...
+ }
+
+\1f
+File: gcc.info, Node: Compound Literals, Next: Designated Inits, Prev: Initializers, Up: C Extensions
+
+5.20 Compound Literals
+======================
+
+ISO C99 supports compound literals. A compound literal looks like a
+cast containing an initializer. Its value is an object of the type
+specified in the cast, containing the elements specified in the
+initializer; it is an lvalue. As an extension, GCC supports compound
+literals in C89 mode and in C++.
+
+ Usually, the specified type is a structure. Assume that `struct
+foo' and `structure' are declared as shown:
+
+ struct foo {int a; char b[2];} structure;
+
+Here is an example of constructing a `struct foo' with a compound
+literal:
+
+ structure = ((struct foo) {x + y, 'a', 0});
+
+This is equivalent to writing the following:
+
+ {
+ struct foo temp = {x + y, 'a', 0};
+ structure = temp;
+ }
+
+ You can also construct an array. If all the elements of the
+compound literal are (made up of) simple constant expressions, suitable
+for use in initializers of objects of static storage duration, then the
+compound literal can be coerced to a pointer to its first element and
+used in such an initializer, as shown here:
+
+ char **foo = (char *[]) { "x", "y", "z" };
+
+ Compound literals for scalar types and union types are is also
+allowed, but then the compound literal is equivalent to a cast.
+
+ As a GNU extension, GCC allows initialization of objects with static
+storage duration by compound literals (which is not possible in ISO
+C99, because the initializer is not a constant). It is handled as if
+the object was initialized only with the bracket enclosed list if
+compound literal's and object types match. The initializer list of the
+compound literal must be constant. If the object being initialized has
+array type of unknown size, the size is determined by compound literal
+size.
+
+ static struct foo x = (struct foo) {1, 'a', 'b'};
+ static int y[] = (int []) {1, 2, 3};
+ static int z[] = (int [3]) {1};
+
+The above lines are equivalent to the following:
+ static struct foo x = {1, 'a', 'b'};
+ static int y[] = {1, 2, 3};
+ static int z[] = {1, 0, 0};
+
+\1f
+File: gcc.info, Node: Designated Inits, Next: Cast to Union, Prev: Compound Literals, Up: C Extensions
+
+5.21 Designated Initializers
+============================
+
+Standard C89 requires the elements of an initializer to appear in a
+fixed order, the same as the order of the elements in the array or
+structure being initialized.
+
+ In ISO C99 you can give the elements in any order, specifying the
+array indices or structure field names they apply to, and GNU C allows
+this as an extension in C89 mode as well. This extension is not
+implemented in GNU C++.
+
+ To specify an array index, write `[INDEX] =' before the element
+value. For example,
+
+ int a[6] = { [4] = 29, [2] = 15 };
+
+is equivalent to
+
+ int a[6] = { 0, 0, 15, 0, 29, 0 };
+
+The index values must be constant expressions, even if the array being
+initialized is automatic.
+
+ An alternative syntax for this which has been obsolete since GCC 2.5
+but GCC still accepts is to write `[INDEX]' before the element value,
+with no `='.
+
+ To initialize a range of elements to the same value, write `[FIRST
+... LAST] = VALUE'. This is a GNU extension. For example,
+
+ int widths[] = { [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 };
+
+If the value in it has side-effects, the side-effects will happen only
+once, not for each initialized field by the range initializer.
+
+Note that the length of the array is the highest value specified plus
+one.
+
+ In a structure initializer, specify the name of a field to initialize
+with `.FIELDNAME =' before the element value. For example, given the
+following structure,
+
+ struct point { int x, y; };
+
+the following initialization
+
+ struct point p = { .y = yvalue, .x = xvalue };
+
+is equivalent to
+
+ struct point p = { xvalue, yvalue };
+
+ Another syntax which has the same meaning, obsolete since GCC 2.5, is
+`FIELDNAME:', as shown here:
+
+ struct point p = { y: yvalue, x: xvalue };
+
+ The `[INDEX]' or `.FIELDNAME' is known as a "designator". You can
+also use a designator (or the obsolete colon syntax) when initializing
+a union, to specify which element of the union should be used. For
+example,
+
+ union foo { int i; double d; };
+
+ union foo f = { .d = 4 };
+
+will convert 4 to a `double' to store it in the union using the second
+element. By contrast, casting 4 to type `union foo' would store it
+into the union as the integer `i', since it is an integer. (*Note Cast
+to Union::.)
+
+ You can combine this technique of naming elements with ordinary C
+initialization of successive elements. Each initializer element that
+does not have a designator applies to the next consecutive element of
+the array or structure. For example,
+
+ int a[6] = { [1] = v1, v2, [4] = v4 };
+
+is equivalent to
+
+ int a[6] = { 0, v1, v2, 0, v4, 0 };
+
+ Labeling the elements of an array initializer is especially useful
+when the indices are characters or belong to an `enum' type. For
+example:
+
+ int whitespace[256]
+ = { [' '] = 1, ['\t'] = 1, ['\h'] = 1,
+ ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 };
+
+ You can also write a series of `.FIELDNAME' and `[INDEX]'
+designators before an `=' to specify a nested subobject to initialize;
+the list is taken relative to the subobject corresponding to the
+closest surrounding brace pair. For example, with the `struct point'
+declaration above:
+
+ struct point ptarray[10] = { [2].y = yv2, [2].x = xv2, [0].x = xv0 };
+
+If the same field is initialized multiple times, it will have value from
+the last initialization. If any such overridden initialization has
+side-effect, it is unspecified whether the side-effect happens or not.
+Currently, gcc will discard them and issue a warning.
+
+\1f
+File: gcc.info, Node: Case Ranges, Next: Mixed Declarations, Prev: Cast to Union, Up: C Extensions
+
+5.22 Case Ranges
+================
+
+You can specify a range of consecutive values in a single `case' label,
+like this:
+
+ case LOW ... HIGH:
+
+This has the same effect as the proper number of individual `case'
+labels, one for each integer value from LOW to HIGH, inclusive.
+
+ This feature is especially useful for ranges of ASCII character
+codes:
+
+ case 'A' ... 'Z':
+
+ *Be careful:* Write spaces around the `...', for otherwise it may be
+parsed wrong when you use it with integer values. For example, write
+this:
+
+ case 1 ... 5:
+
+rather than this:
+
+ case 1...5:
+
+\1f
+File: gcc.info, Node: Cast to Union, Next: Case Ranges, Prev: Designated Inits, Up: C Extensions
+
+5.23 Cast to a Union Type
+=========================
+
+A cast to union type is similar to other casts, except that the type
+specified is a union type. You can specify the type either with `union
+TAG' or with a typedef name. A cast to union is actually a constructor
+though, not a cast, and hence does not yield an lvalue like normal
+casts. (*Note Compound Literals::.)
+
+ The types that may be cast to the union type are those of the members
+of the union. Thus, given the following union and variables:
+
+ union foo { int i; double d; };
+ int x;
+ double y;
+
+both `x' and `y' can be cast to type `union foo'.
+
+ Using the cast as the right-hand side of an assignment to a variable
+of union type is equivalent to storing in a member of the union:
+
+ union foo u;
+ ...
+ u = (union foo) x == u.i = x
+ u = (union foo) y == u.d = y
+
+ You can also use the union cast as a function argument:
+
+ void hack (union foo);
+ ...
+ hack ((union foo) x);
+
+\1f
+File: gcc.info, Node: Mixed Declarations, Next: Function Attributes, Prev: Case Ranges, Up: C Extensions
+
+5.24 Mixed Declarations and Code
+================================
+
+ISO C99 and ISO C++ allow declarations and code to be freely mixed
+within compound statements. As an extension, GCC also allows this in
+C89 mode. For example, you could do:
+
+ int i;
+ ...
+ i++;
+ int j = i + 2;
+
+ Each identifier is visible from where it is declared until the end of
+the enclosing block.
+
+\1f
+File: gcc.info, Node: Function Attributes, Next: Attribute Syntax, Prev: Mixed Declarations, Up: C Extensions
+
+5.25 Declaring Attributes of Functions
+======================================
+
+In GNU C, you declare certain things about functions called in your
+program which help the compiler optimize function calls and check your
+code more carefully.
+
+ The keyword `__attribute__' allows you to specify special attributes
+when making a declaration. This keyword is followed by an attribute
+specification inside double parentheses. The following attributes are
+currently defined for functions on all targets: `noreturn', `noinline',
+`always_inline', `pure', `const', `format', `format_arg',
+`no_instrument_function', `section', `constructor', `destructor',
+`used', `unused', `deprecated', `weak', `malloc', and `alias'. Several
+other attributes are defined for functions on particular target
+systems. Other attributes, including `section' are supported for
+variables declarations (*note Variable Attributes::) and for types
+(*note Type Attributes::).
+
+ You may also specify attributes with `__' preceding and following
+each keyword. This allows you to use them in header files without
+being concerned about a possible macro of the same name. For example,
+you may use `__noreturn__' instead of `noreturn'.
+
+ *Note Attribute Syntax::, for details of the exact syntax for using
+attributes.
+
+`noreturn'
+ A few standard library functions, such as `abort' and `exit',
+ cannot return. GCC knows this automatically. Some programs define
+ their own functions that never return. You can declare them
+ `noreturn' to tell the compiler this fact. For example,
+
+ void fatal () __attribute__ ((noreturn));
+
+ void
+ fatal (...)
+ {
+ ... /* Print error message. */ ...
+ exit (1);
+ }
+
+ The `noreturn' keyword tells the compiler to assume that `fatal'
+ cannot return. It can then optimize without regard to what would
+ happen if `fatal' ever did return. This makes slightly better
+ code. More importantly, it helps avoid spurious warnings of
+ uninitialized variables.
+
+ Do not assume that registers saved by the calling function are
+ restored before calling the `noreturn' function.
+
+ It does not make sense for a `noreturn' function to have a return
+ type other than `void'.
+
+ The attribute `noreturn' is not implemented in GCC versions
+ earlier than 2.5. An alternative way to declare that a function
+ does not return, which works in the current version and in some
+ older versions, is as follows:
+
+ typedef void voidfn ();
+
+ volatile voidfn fatal;
+
+`noinline'
+ This function attribute prevents a function from being considered
+ for inlining.
+
+`always_inline'
+ Generally, functions are not inlined unless optimization is
+ specified. For functions declared inline, this attribute inlines
+ the function even if no optimization level was specified.
+
+`pure'
+ Many functions have no effects except the return value and their
+ return value depends only on the parameters and/or global
+ variables. Such a function can be subject to common subexpression
+ elimination and loop optimization just as an arithmetic operator
+ would be. These functions should be declared with the attribute
+ `pure'. For example,
+
+ int square (int) __attribute__ ((pure));
+
+ says that the hypothetical function `square' is safe to call fewer
+ times than the program says.
+
+ Some of common examples of pure functions are `strlen' or `memcmp'.
+ Interesting non-pure functions are functions with infinite loops
+ or those depending on volatile memory or other system resource,
+ that may change between two consecutive calls (such as `feof' in a
+ multithreading environment).
+
+ The attribute `pure' is not implemented in GCC versions earlier
+ than 2.96.
+
+`const'
+ Many functions do not examine any values except their arguments,
+ and have no effects except the return value. Basically this is
+ just slightly more strict class than the `pure' attribute above,
+ since function is not allowed to read global memory.
+
+ Note that a function that has pointer arguments and examines the
+ data pointed to must _not_ be declared `const'. Likewise, a
+ function that calls a non-`const' function usually must not be
+ `const'. It does not make sense for a `const' function to return
+ `void'.
+
+ The attribute `const' is not implemented in GCC versions earlier
+ than 2.5. An alternative way to declare that a function has no
+ side effects, which works in the current version and in some older
+ versions, is as follows:
+
+ typedef int intfn ();
+
+ extern const intfn square;
+
+ This approach does not work in GNU C++ from 2.6.0 on, since the
+ language specifies that the `const' must be attached to the return
+ value.
+
+`format (ARCHETYPE, STRING-INDEX, FIRST-TO-CHECK)'
+ The `format' attribute specifies that a function takes `printf',
+ `scanf', `strftime' or `strfmon' style arguments which should be
+ type-checked against a format string. For example, the
+ declaration:
+
+ extern int
+ my_printf (void *my_object, const char *my_format, ...)
+ __attribute__ ((format (printf, 2, 3)));
+
+ causes the compiler to check the arguments in calls to `my_printf'
+ for consistency with the `printf' style format string argument
+ `my_format'.
+
+ The parameter ARCHETYPE determines how the format string is
+ interpreted, and should be `printf', `scanf', `strftime' or
+ `strfmon'. (You can also use `__printf__', `__scanf__',
+ `__strftime__' or `__strfmon__'.) The parameter STRING-INDEX
+ specifies which argument is the format string argument (starting
+ from 1), while FIRST-TO-CHECK is the number of the first argument
+ to check against the format string. For functions where the
+ arguments are not available to be checked (such as `vprintf'),
+ specify the third parameter as zero. In this case the compiler
+ only checks the format string for consistency. For `strftime'
+ formats, the third parameter is required to be zero.
+
+ In the example above, the format string (`my_format') is the second
+ argument of the function `my_print', and the arguments to check
+ start with the third argument, so the correct parameters for the
+ format attribute are 2 and 3.
+
+ The `format' attribute allows you to identify your own functions
+ which take format strings as arguments, so that GCC can check the
+ calls to these functions for errors. The compiler always (unless
+ `-ffreestanding' is used) checks formats for the standard library
+ functions `printf', `fprintf', `sprintf', `scanf', `fscanf',
+ `sscanf', `strftime', `vprintf', `vfprintf' and `vsprintf'
+ whenever such warnings are requested (using `-Wformat'), so there
+ is no need to modify the header file `stdio.h'. In C99 mode, the
+ functions `snprintf', `vsnprintf', `vscanf', `vfscanf' and
+ `vsscanf' are also checked. Except in strictly conforming C
+ standard modes, the X/Open function `strfmon' is also checked as
+ are `printf_unlocked' and `fprintf_unlocked'. *Note Options
+ Controlling C Dialect: C Dialect Options.
+
+`format_arg (STRING-INDEX)'
+ The `format_arg' attribute specifies that a function takes a format
+ string for a `printf', `scanf', `strftime' or `strfmon' style
+ function and modifies it (for example, to translate it into
+ another language), so the result can be passed to a `printf',
+ `scanf', `strftime' or `strfmon' style function (with the
+ remaining arguments to the format function the same as they would
+ have been for the unmodified string). For example, the
+ declaration:
+
+ extern char *
+ my_dgettext (char *my_domain, const char *my_format)
+ __attribute__ ((format_arg (2)));
+
+ causes the compiler to check the arguments in calls to a `printf',
+ `scanf', `strftime' or `strfmon' type function, whose format
+ string argument is a call to the `my_dgettext' function, for
+ consistency with the format string argument `my_format'. If the
+ `format_arg' attribute had not been specified, all the compiler
+ could tell in such calls to format functions would be that the
+ format string argument is not constant; this would generate a
+ warning when `-Wformat-nonliteral' is used, but the calls could
+ not be checked without the attribute.
+
+ The parameter STRING-INDEX specifies which argument is the format
+ string argument (starting from 1).
+
+ The `format-arg' attribute allows you to identify your own
+ functions which modify format strings, so that GCC can check the
+ calls to `printf', `scanf', `strftime' or `strfmon' type function
+ whose operands are a call to one of your own function. The
+ compiler always treats `gettext', `dgettext', and `dcgettext' in
+ this manner except when strict ISO C support is requested by
+ `-ansi' or an appropriate `-std' option, or `-ffreestanding' is
+ used. *Note Options Controlling C Dialect: C Dialect Options.
+
+`no_instrument_function'
+ If `-finstrument-functions' is given, profiling function calls will
+ be generated at entry and exit of most user-compiled functions.
+ Functions with this attribute will not be so instrumented.
+
+`section ("SECTION-NAME")'
+ Normally, the compiler places the code it generates in the `text'
+ section. Sometimes, however, you need additional sections, or you
+ need certain particular functions to appear in special sections.
+ The `section' attribute specifies that a function lives in a
+ particular section. For example, the declaration:
+
+ extern void foobar (void) __attribute__ ((section ("bar")));
+
+ puts the function `foobar' in the `bar' section.
+
+ Some file formats do not support arbitrary sections so the
+ `section' attribute is not available on all platforms. If you
+ need to map the entire contents of a module to a particular
+ section, consider using the facilities of the linker instead.
+
+`constructor'
+`destructor'
+ The `constructor' attribute causes the function to be called
+ automatically before execution enters `main ()'. Similarly, the
+ `destructor' attribute causes the function to be called
+ automatically after `main ()' has completed or `exit ()' has been
+ called. Functions with these attributes are useful for
+ initializing data that will be used implicitly during the
+ execution of the program.
+
+ These attributes are not currently implemented for Objective-C.
+
+`unused'
+ This attribute, attached to a function, means that the function is
+ meant to be possibly unused. GCC will not produce a warning for
+ this function. GNU C++ does not currently support this attribute
+ as definitions without parameters are valid in C++.
+
+`used'
+ This attribute, attached to a function, means that code must be
+ emitted for the function even if it appears that the function is
+ not referenced. This is useful, for example, when the function is
+ referenced only in inline assembly.
+
+`deprecated'
+ The `deprecated' attribute results in a warning if the function is
+ used anywhere in the source file. This is useful when identifying
+ functions that are expected to be removed in a future version of a
+ program. The warning also includes the location of the declaration
+ of the deprecated function, to enable users to easily find further
+ information about why the function is deprecated, or what they
+ should do instead. Note that the warnings only occurs for uses:
+
+ int old_fn () __attribute__ ((deprecated));
+ int old_fn ();
+ int (*fn_ptr)() = old_fn;
+
+ results in a warning on line 3 but not line 2.
+
+ The `deprecated' attribute can also be used for variables and
+ types (*note Variable Attributes::, *note Type Attributes::.)
+
+`weak'
+ The `weak' attribute causes the declaration to be emitted as a weak
+ symbol rather than a global. This is primarily useful in defining
+ library functions which can be overridden in user code, though it
+ can also be used with non-function declarations. Weak symbols are
+ supported for ELF targets, and also for a.out targets when using
+ the GNU assembler and linker.
+
+`malloc'
+ The `malloc' attribute is used to tell the compiler that a function
+ may be treated as if it were the malloc function. The compiler
+ assumes that calls to malloc result in a pointers that cannot
+ alias anything. This will often improve optimization.
+
+`alias ("TARGET")'
+ The `alias' attribute causes the declaration to be emitted as an
+ alias for another symbol, which must be specified. For instance,
+
+ void __f () { /* do something */; }
+ void f () __attribute__ ((weak, alias ("__f")));
+
+ declares `f' to be a weak alias for `__f'. In C++, the mangled
+ name for the target must be used.
+
+ Not all target machines support this attribute.
+
+`regparm (NUMBER)'
+ On the Intel 386, the `regparm' attribute causes the compiler to
+ pass up to NUMBER integer arguments in registers EAX, EDX, and ECX
+ instead of on the stack. Functions that take a variable number of
+ arguments will continue to be passed all of their arguments on the
+ stack.
+
+`stdcall'
+ On the Intel 386, the `stdcall' attribute causes the compiler to
+ assume that the called function will pop off the stack space used
+ to pass arguments, unless it takes a variable number of arguments.
+
+ The PowerPC compiler for Windows NT currently ignores the `stdcall'
+ attribute.
+
+`cdecl'
+ On the Intel 386, the `cdecl' attribute causes the compiler to
+ assume that the calling function will pop off the stack space used
+ to pass arguments. This is useful to override the effects of the
+ `-mrtd' switch.
+
+ The PowerPC compiler for Windows NT currently ignores the `cdecl'
+ attribute.
+
+`longcall'
+ On the RS/6000 and PowerPC, the `longcall' attribute causes the
+ compiler to always call the function via a pointer, so that
+ functions which reside further than 64 megabytes (67,108,864
+ bytes) from the current location can be called.
+
+`long_call/short_call'
+ This attribute allows to specify how to call a particular function
+ on ARM. Both attributes override the `-mlong-calls' (*note ARM
+ Options::) command line switch and `#pragma long_calls' settings.
+ The `long_call' attribute causes the compiler to always call the
+ function by first loading its address into a register and then
+ using the contents of that register. The `short_call' attribute
+ always places the offset to the function from the call site into
+ the `BL' instruction directly.
+
+`dllimport'
+ On the PowerPC running Windows NT, the `dllimport' attribute causes
+ the compiler to call the function via a global pointer to the
+ function pointer that is set up by the Windows NT dll library.
+ The pointer name is formed by combining `__imp_' and the function
+ name.
+
+`dllexport'
+ On the PowerPC running Windows NT, the `dllexport' attribute causes
+ the compiler to provide a global pointer to the function pointer,
+ so that it can be called with the `dllimport' attribute. The
+ pointer name is formed by combining `__imp_' and the function name.
+
+`exception (EXCEPT-FUNC [, EXCEPT-ARG])'
+ On the PowerPC running Windows NT, the `exception' attribute causes
+ the compiler to modify the structured exception table entry it
+ emits for the declared function. The string or identifier
+ EXCEPT-FUNC is placed in the third entry of the structured
+ exception table. It represents a function, which is called by the
+ exception handling mechanism if an exception occurs. If it was
+ specified, the string or identifier EXCEPT-ARG is placed in the
+ fourth entry of the structured exception table.
+
+`function_vector'
+ Use this attribute on the H8/300 and H8/300H to indicate that the
+ specified function should be called through the function vector.
+ Calling a function through the function vector will reduce code
+ size, however; the function vector has a limited size (maximum 128
+ entries on the H8/300 and 64 entries on the H8/300H) and shares
+ space with the interrupt vector.
+
+ You must use GAS and GLD from GNU binutils version 2.7 or later for
+ this attribute to work correctly.
+
+`interrupt'
+ Use this attribute on the ARM, AVR, M32R/D and Xstormy16 ports to
+ indicate that the specified function is an interrupt handler. The
+ compiler will generate function entry and exit sequences suitable
+ for use in an interrupt handler when this attribute is present.
+
+ Note, interrupt handlers for the H8/300, H8/300H and SH processors
+ can be specified via the `interrupt_handler' attribute.
+
+ Note, on the AVR interrupts will be enabled inside the function.
+
+ Note, for the ARM you can specify the kind of interrupt to be
+ handled by adding an optional parameter to the interrupt attribute
+ like this:
+
+ void f () __attribute__ ((interrupt ("IRQ")));
+
+ Permissible values for this parameter are: IRQ, FIQ, SWI, ABORT
+ and UNDEF.
+
+`interrupt_handler'
+ Use this attribute on the H8/300, H8/300H and SH to indicate that
+ the specified function is an interrupt handler. The compiler will
+ generate function entry and exit sequences suitable for use in an
+ interrupt handler when this attribute is present.
+
+`sp_switch'
+ Use this attribute on the SH to indicate an `interrupt_handler'
+ function should switch to an alternate stack. It expects a string
+ argument that names a global variable holding the address of the
+ alternate stack.
+
+ void *alt_stack;
+ void f () __attribute__ ((interrupt_handler,
+ sp_switch ("alt_stack")));
+
+`trap_exit'
+ Use this attribute on the SH for an `interrupt_handle' to return
+ using `trapa' instead of `rte'. This attribute expects an integer
+ argument specifying the trap number to be used.
+
+`eightbit_data'
+ Use this attribute on the H8/300 and H8/300H to indicate that the
+ specified variable should be placed into the eight bit data
+ section. The compiler will generate more efficient code for
+ certain operations on data in the eight bit data area. Note the
+ eight bit data area is limited to 256 bytes of data.
+
+ You must use GAS and GLD from GNU binutils version 2.7 or later for
+ this attribute to work correctly.
+
+`tiny_data'
+ Use this attribute on the H8/300H to indicate that the specified
+ variable should be placed into the tiny data section. The
+ compiler will generate more efficient code for loads and stores on
+ data in the tiny data section. Note the tiny data area is limited
+ to slightly under 32kbytes of data.
+
+`signal'
+ Use this attribute on the AVR to indicate that the specified
+ function is an signal handler. The compiler will generate function
+ entry and exit sequences suitable for use in an signal handler
+ when this attribute is present. Interrupts will be disabled
+ inside function.
+
+`naked'
+ Use this attribute on the ARM or AVR ports to indicate that the
+ specified function do not need prologue/epilogue sequences
+ generated by the compiler. It is up to the programmer to provide
+ these sequences.
+
+`model (MODEL-NAME)'
+ Use this attribute on the M32R/D to set the addressability of an
+ object, and the code generated for a function. The identifier
+ MODEL-NAME is one of `small', `medium', or `large', representing
+ each of the code models.
+
+ Small model objects live in the lower 16MB of memory (so that their
+ addresses can be loaded with the `ld24' instruction), and are
+ callable with the `bl' instruction.
+
+ Medium model objects may live anywhere in the 32-bit address space
+ (the compiler will generate `seth/add3' instructions to load their
+ addresses), and are callable with the `bl' instruction.
+
+ Large model objects may live anywhere in the 32-bit address space
+ (the compiler will generate `seth/add3' instructions to load their
+ addresses), and may not be reachable with the `bl' instruction
+ (the compiler will generate the much slower `seth/add3/jl'
+ instruction sequence).
+
+
+ You can specify multiple attributes in a declaration by separating
+them by commas within the double parentheses or by immediately
+following an attribute declaration with another attribute declaration.
+
+ Some people object to the `__attribute__' feature, suggesting that
+ISO C's `#pragma' should be used instead. At the time `__attribute__'
+was designed, there were two reasons for not doing this.
+
+ 1. It is impossible to generate `#pragma' commands from a macro.
+
+ 2. There is no telling what the same `#pragma' might mean in another
+ compiler.
+
+ These two reasons applied to almost any application that might have
+been proposed for `#pragma'. It was basically a mistake to use
+`#pragma' for _anything_.
+
+ The ISO C99 standard includes `_Pragma', which now allows pragmas to
+be generated from macros. In addition, a `#pragma GCC' namespace is
+now in use for GCC-specific pragmas. However, it has been found
+convenient to use `__attribute__' to achieve a natural attachment of
+attributes to their corresponding declarations, whereas `#pragma GCC'
+is of use for constructs that do not naturally form part of the
+grammar. *Note Miscellaneous Preprocessing Directives: (cpp)Other
+Directives.
+
+\1f
+File: gcc.info, Node: Attribute Syntax, Next: Function Prototypes, Prev: Function Attributes, Up: C Extensions
+
+5.26 Attribute Syntax
+=====================
+
+This section describes the syntax with which `__attribute__' may be
+used, and the constructs to which attribute specifiers bind, for the C
+language. Some details may vary for C++ and Objective-C. Because of
+infelicities in the grammar for attributes, some forms described here
+may not be successfully parsed in all cases.
+
+ There are some problems with the semantics of attributes in C++. For
+example, there are no manglings for attributes, although they may affect
+code generation, so problems may arise when attributed types are used in
+conjunction with templates or overloading. Similarly, `typeid' does
+not distinguish between types with different attributes. Support for
+attributes in C++ may be restricted in future to attributes on
+declarations only, but not on nested declarators.
+
+ *Note Function Attributes::, for details of the semantics of
+attributes applying to functions. *Note Variable Attributes::, for
+details of the semantics of attributes applying to variables. *Note
+Type Attributes::, for details of the semantics of attributes applying
+to structure, union and enumerated types.
+
+ An "attribute specifier" is of the form `__attribute__
+((ATTRIBUTE-LIST))'. An "attribute list" is a possibly empty
+comma-separated sequence of "attributes", where each attribute is one
+of the following:
+
+ * Empty. Empty attributes are ignored.
+
+ * A word (which may be an identifier such as `unused', or a reserved
+ word such as `const').
+
+ * A word, followed by, in parentheses, parameters for the attribute.
+ These parameters take one of the following forms:
+
+ * An identifier. For example, `mode' attributes use this form.
+
+ * An identifier followed by a comma and a non-empty
+ comma-separated list of expressions. For example, `format'
+ attributes use this form.
+
+ * A possibly empty comma-separated list of expressions. For
+ example, `format_arg' attributes use this form with the list
+ being a single integer constant expression, and `alias'
+ attributes use this form with the list being a single string
+ constant.
+
+ An "attribute specifier list" is a sequence of one or more attribute
+specifiers, not separated by any other tokens.
+
+ An attribute specifier list may appear after the colon following a
+label, other than a `case' or `default' label. The only attribute it
+makes sense to use after a label is `unused'. This feature is intended
+for code generated by programs which contains labels that may be unused
+but which is compiled with `-Wall'. It would not normally be
+appropriate to use in it human-written code, though it could be useful
+in cases where the code that jumps to the label is contained within an
+`#ifdef' conditional.
+
+ An attribute specifier list may appear as part of a `struct',
+`union' or `enum' specifier. It may go either immediately after the
+`struct', `union' or `enum' keyword, or after the closing brace. It is
+ignored if the content of the structure, union or enumerated type is
+not defined in the specifier in which the attribute specifier list is
+used--that is, in usages such as `struct __attribute__((foo)) bar' with
+no following opening brace. Where attribute specifiers follow the
+closing brace, they are considered to relate to the structure, union or
+enumerated type defined, not to any enclosing declaration the type
+specifier appears in, and the type defined is not complete until after
+the attribute specifiers.
+
+ Otherwise, an attribute specifier appears as part of a declaration,
+counting declarations of unnamed parameters and type names, and relates
+to that declaration (which may be nested in another declaration, for
+example in the case of a parameter declaration), or to a particular
+declarator within a declaration. Where an attribute specifier is
+applied to a parameter declared as a function or an array, it should
+apply to the function or array rather than the pointer to which the
+parameter is implicitly converted, but this is not yet correctly
+implemented.
+
+ Any list of specifiers and qualifiers at the start of a declaration
+may contain attribute specifiers, whether or not such a list may in that
+context contain storage class specifiers. (Some attributes, however,
+are essentially in the nature of storage class specifiers, and only make
+sense where storage class specifiers may be used; for example,
+`section'.) There is one necessary limitation to this syntax: the
+first old-style parameter declaration in a function definition cannot
+begin with an attribute specifier, because such an attribute applies to
+the function instead by syntax described below (which, however, is not
+yet implemented in this case). In some other cases, attribute
+specifiers are permitted by this grammar but not yet supported by the
+compiler. All attribute specifiers in this place relate to the
+declaration as a whole. In the obsolescent usage where a type of `int'
+is implied by the absence of type specifiers, such a list of specifiers
+and qualifiers may be an attribute specifier list with no other
+specifiers or qualifiers.
+
+ An attribute specifier list may appear immediately before a
+declarator (other than the first) in a comma-separated list of
+declarators in a declaration of more than one identifier using a single
+list of specifiers and qualifiers. Such attribute specifiers apply
+only to the identifier before whose declarator they appear. For
+example, in
+
+ __attribute__((noreturn)) void d0 (void),
+ __attribute__((format(printf, 1, 2))) d1 (const char *, ...),
+ d2 (void)
+
+the `noreturn' attribute applies to all the functions declared; the
+`format' attribute only applies to `d1'.
+
+ An attribute specifier list may appear immediately before the comma,
+`=' or semicolon terminating the declaration of an identifier other
+than a function definition. At present, such attribute specifiers apply
+to the declared object or function, but in future they may attach to the
+outermost adjacent declarator. In simple cases there is no difference,
+but, for example, in
+
+ void (****f)(void) __attribute__((noreturn));
+
+at present the `noreturn' attribute applies to `f', which causes a
+warning since `f' is not a function, but in future it may apply to the
+function `****f'. The precise semantics of what attributes in such
+cases will apply to are not yet specified. Where an assembler name for
+an object or function is specified (*note Asm Labels::), at present the
+attribute must follow the `asm' specification; in future, attributes
+before the `asm' specification may apply to the adjacent declarator,
+and those after it to the declared object or function.
+
+ An attribute specifier list may, in future, be permitted to appear
+after the declarator in a function definition (before any old-style
+parameter declarations or the function body).
+
+ Attribute specifiers may be mixed with type qualifiers appearing
+inside the `[]' of a parameter array declarator, in the C99 construct by
+which such qualifiers are applied to the pointer to which the array is
+implicitly converted. Such attribute specifiers apply to the pointer,
+not to the array, but at present this is not implemented and they are
+ignored.
+
+ An attribute specifier list may appear at the start of a nested
+declarator. At present, there are some limitations in this usage: the
+attributes correctly apply to the declarator, but for most individual
+attributes the semantics this implies are not implemented. When
+attribute specifiers follow the `*' of a pointer declarator, they may
+be mixed with any type qualifiers present. The following describes the
+formal semantics of this syntax. It will make the most sense if you
+are familiar with the formal specification of declarators in the ISO C
+standard.
+
+ Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration `T
+D1', where `T' contains declaration specifiers that specify a type TYPE
+(such as `int') and `D1' is a declarator that contains an identifier
+IDENT. The type specified for IDENT for derived declarators whose type
+does not include an attribute specifier is as in the ISO C standard.
+
+ If `D1' has the form `( ATTRIBUTE-SPECIFIER-LIST D )', and the
+declaration `T D' specifies the type "DERIVED-DECLARATOR-TYPE-LIST
+TYPE" for IDENT, then `T D1' specifies the type
+"DERIVED-DECLARATOR-TYPE-LIST ATTRIBUTE-SPECIFIER-LIST TYPE" for IDENT.
+
+ If `D1' has the form `* TYPE-QUALIFIER-AND-ATTRIBUTE-SPECIFIER-LIST
+D', and the declaration `T D' specifies the type
+"DERIVED-DECLARATOR-TYPE-LIST TYPE" for IDENT, then `T D1' specifies
+the type "DERIVED-DECLARATOR-TYPE-LIST
+TYPE-QUALIFIER-AND-ATTRIBUTE-SPECIFIER-LIST TYPE" for IDENT.
+
+ For example,
+
+ void (__attribute__((noreturn)) ****f) (void);
+
+specifies the type "pointer to pointer to pointer to pointer to
+non-returning function returning `void'". As another example,
+
+ char *__attribute__((aligned(8))) *f;
+
+specifies the type "pointer to 8-byte-aligned pointer to `char'". Note
+again that this does not work with most attributes; for example, the
+usage of `aligned' and `noreturn' attributes given above is not yet
+supported.
+
+ For compatibility with existing code written for compiler versions
+that did not implement attributes on nested declarators, some laxity is
+allowed in the placing of attributes. If an attribute that only applies
+to types is applied to a declaration, it will be treated as applying to
+the type of that declaration. If an attribute that only applies to
+declarations is applied to the type of a declaration, it will be treated
+as applying to that declaration; and, for compatibility with code
+placing the attributes immediately before the identifier declared, such
+an attribute applied to a function return type will be treated as
+applying to the function type, and such an attribute applied to an array
+element type will be treated as applying to the array type. If an
+attribute that only applies to function types is applied to a
+pointer-to-function type, it will be treated as applying to the pointer
+target type; if such an attribute is applied to a function return type
+that is not a pointer-to-function type, it will be treated as applying
+to the function type.
+
+\1f
+File: gcc.info, Node: Function Prototypes, Next: C++ Comments, Prev: Attribute Syntax, Up: C Extensions
+
+5.27 Prototypes and Old-Style Function Definitions
+==================================================
+
+GNU C extends ISO C to allow a function prototype to override a later
+old-style non-prototype definition. Consider the following example:
+
+ /* Use prototypes unless the compiler is old-fashioned. */
+ #ifdef __STDC__
+ #define P(x) x
+ #else
+ #define P(x) ()
+ #endif
+
+ /* Prototype function declaration. */
+ int isroot P((uid_t));
+
+ /* Old-style function definition. */
+ int
+ isroot (x) /* ??? lossage here ??? */
+ uid_t x;
+ {
+ return x == 0;
+ }
+
+ Suppose the type `uid_t' happens to be `short'. ISO C does not
+allow this example, because subword arguments in old-style
+non-prototype definitions are promoted. Therefore in this example the
+function definition's argument is really an `int', which does not match
+the prototype argument type of `short'.
+
+ This restriction of ISO C makes it hard to write code that is
+portable to traditional C compilers, because the programmer does not
+know whether the `uid_t' type is `short', `int', or `long'. Therefore,
+in cases like these GNU C allows a prototype to override a later
+old-style definition. More precisely, in GNU C, a function prototype
+argument type overrides the argument type specified by a later
+old-style definition if the former type is the same as the latter type
+before promotion. Thus in GNU C the above example is equivalent to the
+following:
+
+ int isroot (uid_t);
+
+ int
+ isroot (uid_t x)
+ {
+ return x == 0;
+ }
+
+GNU C++ does not support old-style function definitions, so this
+extension is irrelevant.
+
+\1f
+File: gcc.info, Node: C++ Comments, Next: Dollar Signs, Prev: Function Prototypes, Up: C Extensions
+
+5.28 C++ Style Comments
+=======================
+
+In GNU C, you may use C++ style comments, which start with `//' and
+continue until the end of the line. Many other C implementations allow
+such comments, and they are likely to be in a future C standard.
+However, C++ style comments are not recognized if you specify `-ansi',
+a `-std' option specifying a version of ISO C before C99, or
+`-traditional', since they are incompatible with traditional constructs
+like `dividend//*comment*/divisor'.
+
+\1f
+File: gcc.info, Node: Dollar Signs, Next: Character Escapes, Prev: C++ Comments, Up: C Extensions
+
+5.29 Dollar Signs in Identifier Names
+=====================================
+
+In GNU C, you may normally use dollar signs in identifier names. This
+is because many traditional C implementations allow such identifiers.
+However, dollar signs in identifiers are not supported on a few target
+machines, typically because the target assembler does not allow them.
+
+\1f
+File: gcc.info, Node: Character Escapes, Next: Variable Attributes, Prev: Dollar Signs, Up: C Extensions
+
+5.30 The Character <ESC> in Constants
+=====================================
+
+You can use the sequence `\e' in a string or character constant to
+stand for the ASCII character <ESC>.
+
+\1f
+File: gcc.info, Node: Alignment, Next: Inline, Prev: Type Attributes, Up: C Extensions
+
+5.31 Inquiring on Alignment of Types or Variables
+=================================================
+
+The keyword `__alignof__' allows you to inquire about how an object is
+aligned, or the minimum alignment usually required by a type. Its
+syntax is just like `sizeof'.
+
+ For example, if the target machine requires a `double' value to be
+aligned on an 8-byte boundary, then `__alignof__ (double)' is 8. This
+is true on many RISC machines. On more traditional machine designs,
+`__alignof__ (double)' is 4 or even 2.
+
+ Some machines never actually require alignment; they allow reference
+to any data type even at an odd addresses. For these machines,
+`__alignof__' reports the _recommended_ alignment of a type.
+
+ If the operand of `__alignof__' is an lvalue rather than a type, its
+value is the required alignment for its type, taking into account any
+minimum alignment specified with GCC's `__attribute__' extension (*note
+Variable Attributes::). For example, after this declaration:
+
+ struct foo { int x; char y; } foo1;
+
+the value of `__alignof__ (foo1.y)' is 1, even though its actual
+alignment is probably 2 or 4, the same as `__alignof__ (int)'.
+
+ It is an error to ask for the alignment of an incomplete type.
+
+\1f
+File: gcc.info, Node: Variable Attributes, Next: Type Attributes, Prev: Character Escapes, Up: C Extensions
+
+5.32 Specifying Attributes of Variables
+=======================================
+
+The keyword `__attribute__' allows you to specify special attributes of
+variables or structure fields. This keyword is followed by an
+attribute specification inside double parentheses. Ten attributes are
+currently defined for variables: `aligned', `mode', `nocommon',
+`packed', `section', `transparent_union', `unused', `deprecated',
+`vector_size', and `weak'. Some other attributes are defined for
+variables on particular target systems. Other attributes are available
+for functions (*note Function Attributes::) and for types (*note Type
+Attributes::). Other front ends might define more attributes (*note
+Extensions to the C++ Language: C++ Extensions.).
+
+ You may also specify attributes with `__' preceding and following
+each keyword. This allows you to use them in header files without
+being concerned about a possible macro of the same name. For example,
+you may use `__aligned__' instead of `aligned'.
+
+ *Note Attribute Syntax::, for details of the exact syntax for using
+attributes.
+
+`aligned (ALIGNMENT)'
+ This attribute specifies a minimum alignment for the variable or
+ structure field, measured in bytes. For example, the declaration:
+
+ int x __attribute__ ((aligned (16))) = 0;
+
+ causes the compiler to allocate the global variable `x' on a
+ 16-byte boundary. On a 68040, this could be used in conjunction
+ with an `asm' expression to access the `move16' instruction which
+ requires 16-byte aligned operands.
+
+ You can also specify the alignment of structure fields. For
+ example, to create a double-word aligned `int' pair, you could
+ write:
+
+ struct foo { int x[2] __attribute__ ((aligned (8))); };
+
+ This is an alternative to creating a union with a `double' member
+ that forces the union to be double-word aligned.
+
+ As in the preceding examples, you can explicitly specify the
+ alignment (in bytes) that you wish the compiler to use for a given
+ variable or structure field. Alternatively, you can leave out the
+ alignment factor and just ask the compiler to align a variable or
+ field to the maximum useful alignment for the target machine you
+ are compiling for. For example, you could write:
+
+ short array[3] __attribute__ ((aligned));
+
+ Whenever you leave out the alignment factor in an `aligned'
+ attribute specification, the compiler automatically sets the
+ alignment for the declared variable or field to the largest
+ alignment which is ever used for any data type on the target
+ machine you are compiling for. Doing this can often make copy
+ operations more efficient, because the compiler can use whatever
+ instructions copy the biggest chunks of memory when performing
+ copies to or from the variables or fields that you have aligned
+ this way.
+
+ The `aligned' attribute can only increase the alignment; but you
+ can decrease it by specifying `packed' as well. See below.
+
+ Note that the effectiveness of `aligned' attributes may be limited
+ by inherent limitations in your linker. On many systems, the
+ linker is only able to arrange for variables to be aligned up to a
+ certain maximum alignment. (For some linkers, the maximum
+ supported alignment may be very very small.) If your linker is
+ only able to align variables up to a maximum of 8 byte alignment,
+ then specifying `aligned(16)' in an `__attribute__' will still
+ only provide you with 8 byte alignment. See your linker
+ documentation for further information.
+
+`mode (MODE)'
+ This attribute specifies the data type for the
+ declaration--whichever type corresponds to the mode MODE. This in
+ effect lets you request an integer or floating point type
+ according to its width.
+
+ You may also specify a mode of `byte' or `__byte__' to indicate
+ the mode corresponding to a one-byte integer, `word' or `__word__'
+ for the mode of a one-word integer, and `pointer' or `__pointer__'
+ for the mode used to represent pointers.
+
+`nocommon'
+ This attribute specifies requests GCC not to place a variable
+ "common" but instead to allocate space for it directly. If you
+ specify the `-fno-common' flag, GCC will do this for all variables.
+
+ Specifying the `nocommon' attribute for a variable provides an
+ initialization of zeros. A variable may only be initialized in one
+ source file.
+
+`packed'
+ The `packed' attribute specifies that a variable or structure field
+ should have the smallest possible alignment--one byte for a
+ variable, and one bit for a field, unless you specify a larger
+ value with the `aligned' attribute.
+
+ Here is a structure in which the field `x' is packed, so that it
+ immediately follows `a':
+
+ struct foo
+ {
+ char a;
+ int x[2] __attribute__ ((packed));
+ };
+
+`section ("SECTION-NAME")'
+ Normally, the compiler places the objects it generates in sections
+ like `data' and `bss'. Sometimes, however, you need additional
+ sections, or you need certain particular variables to appear in
+ special sections, for example to map to special hardware. The
+ `section' attribute specifies that a variable (or function) lives
+ in a particular section. For example, this small program uses
+ several specific section names:
+
+ struct duart a __attribute__ ((section ("DUART_A"))) = { 0 };
+ struct duart b __attribute__ ((section ("DUART_B"))) = { 0 };
+ char stack[10000] __attribute__ ((section ("STACK"))) = { 0 };
+ int init_data __attribute__ ((section ("INITDATA"))) = 0;
+
+ main()
+ {
+ /* Initialize stack pointer */
+ init_sp (stack + sizeof (stack));
+
+ /* Initialize initialized data */
+ memcpy (&init_data, &data, &edata - &data);
+
+ /* Turn on the serial ports */
+ init_duart (&a);
+ init_duart (&b);
+ }
+
+ Use the `section' attribute with an _initialized_ definition of a
+ _global_ variable, as shown in the example. GCC issues a warning
+ and otherwise ignores the `section' attribute in uninitialized
+ variable declarations.
+
+ You may only use the `section' attribute with a fully initialized
+ global definition because of the way linkers work. The linker
+ requires each object be defined once, with the exception that
+ uninitialized variables tentatively go in the `common' (or `bss')
+ section and can be multiply "defined". You can force a variable
+ to be initialized with the `-fno-common' flag or the `nocommon'
+ attribute.
+
+ Some file formats do not support arbitrary sections so the
+ `section' attribute is not available on all platforms. If you
+ need to map the entire contents of a module to a particular
+ section, consider using the facilities of the linker instead.
+
+`shared'
+ On Windows NT, in addition to putting variable definitions in a
+ named section, the section can also be shared among all running
+ copies of an executable or DLL. For example, this small program
+ defines shared data by putting it in a named section `shared' and
+ marking the section shareable:
+
+ int foo __attribute__((section ("shared"), shared)) = 0;
+
+ int
+ main()
+ {
+ /* Read and write foo. All running
+ copies see the same value. */
+ return 0;
+ }
+
+ You may only use the `shared' attribute along with `section'
+ attribute with a fully initialized global definition because of
+ the way linkers work. See `section' attribute for more
+ information.
+
+ The `shared' attribute is only available on Windows NT.
+
+`transparent_union'
+ This attribute, attached to a function parameter which is a union,
+ means that the corresponding argument may have the type of any
+ union member, but the argument is passed as if its type were that
+ of the first union member. For more details see *Note Type
+ Attributes::. You can also use this attribute on a `typedef' for
+ a union data type; then it applies to all function parameters with
+ that type.
+
+`unused'
+ This attribute, attached to a variable, means that the variable is
+ meant to be possibly unused. GCC will not produce a warning for
+ this variable.
+
+`deprecated'
+ The `deprecated' attribute results in a warning if the variable is
+ used anywhere in the source file. This is useful when identifying
+ variables that are expected to be removed in a future version of a
+ program. The warning also includes the location of the declaration
+ of the deprecated variable, to enable users to easily find further
+ information about why the variable is deprecated, or what they
+ should do instead. Note that the warnings only occurs for uses:
+
+ extern int old_var __attribute__ ((deprecated));
+ extern int old_var;
+ int new_fn () { return old_var; }
+
+ results in a warning on line 3 but not line 2.
+
+ The `deprecated' attribute can also be used for functions and
+ types (*note Function Attributes::, *note Type Attributes::.)
+
+`vector_size (BYTES)'
+ This attribute specifies the vector size for the variable,
+ measured in bytes. For example, the declaration:
+
+ int foo __attribute__ ((vector_size (16)));
+
+ causes the compiler to set the mode for `foo', to be 16 bytes,
+ divided into `int' sized units. Assuming a 32-bit int (a vector of
+ 4 units of 4 bytes), the corresponding mode of `foo' will be V4SI.
+
+ This attribute is only applicable to integral and float scalars,
+ although arrays, pointers, and function return values are allowed
+ in conjunction with this construct.
+
+ Aggregates with this attribute are invalid, even if they are of
+ the same size as a corresponding scalar. For example, the
+ declaration:
+
+ struct S { int a; };
+ struct S __attribute__ ((vector_size (16))) foo;
+
+ is invalid even if the size of the structure is the same as the
+ size of the `int'.
+
+`weak'
+ The `weak' attribute is described in *Note Function Attributes::.
+
+`model (MODEL-NAME)'
+ Use this attribute on the M32R/D to set the addressability of an
+ object. The identifier MODEL-NAME is one of `small', `medium', or
+ `large', representing each of the code models.
+
+ Small model objects live in the lower 16MB of memory (so that their
+ addresses can be loaded with the `ld24' instruction).
+
+ Medium and large model objects may live anywhere in the 32-bit
+ address space (the compiler will generate `seth/add3' instructions
+ to load their addresses).
+
+
+ To specify multiple attributes, separate them by commas within the
+double parentheses: for example, `__attribute__ ((aligned (16),
+packed))'.
+
+\1f
+File: gcc.info, Node: Type Attributes, Next: Alignment, Prev: Variable Attributes, Up: C Extensions
+
+5.33 Specifying Attributes of Types
+===================================
+
+The keyword `__attribute__' allows you to specify special attributes of
+`struct' and `union' types when you define such types. This keyword is
+followed by an attribute specification inside double parentheses. Five
+attributes are currently defined for types: `aligned', `packed',
+`transparent_union', `unused', and `deprecated'. Other attributes are
+defined for functions (*note Function Attributes::) and for variables
+(*note Variable Attributes::).
+
+ You may also specify any one of these attributes with `__' preceding
+and following its keyword. This allows you to use these attributes in
+header files without being concerned about a possible macro of the same
+name. For example, you may use `__aligned__' instead of `aligned'.
+
+ You may specify the `aligned' and `transparent_union' attributes
+either in a `typedef' declaration or just past the closing curly brace
+of a complete enum, struct or union type _definition_ and the `packed'
+attribute only past the closing brace of a definition.
+
+ You may also specify attributes between the enum, struct or union
+tag and the name of the type rather than after the closing brace.
+
+ *Note Attribute Syntax::, for details of the exact syntax for using
+attributes.
+
+`aligned (ALIGNMENT)'
+ This attribute specifies a minimum alignment (in bytes) for
+ variables of the specified type. For example, the declarations:
+
+ struct S { short f[3]; } __attribute__ ((aligned (8)));
+ typedef int more_aligned_int __attribute__ ((aligned (8)));
+
+ force the compiler to insure (as far as it can) that each variable
+ whose type is `struct S' or `more_aligned_int' will be allocated
+ and aligned _at least_ on a 8-byte boundary. On a Sparc, having
+ all variables of type `struct S' aligned to 8-byte boundaries
+ allows the compiler to use the `ldd' and `std' (doubleword load and
+ store) instructions when copying one variable of type `struct S' to
+ another, thus improving run-time efficiency.
+
+ Note that the alignment of any given `struct' or `union' type is
+ required by the ISO C standard to be at least a perfect multiple of
+ the lowest common multiple of the alignments of all of the members
+ of the `struct' or `union' in question. This means that you _can_
+ effectively adjust the alignment of a `struct' or `union' type by
+ attaching an `aligned' attribute to any one of the members of such
+ a type, but the notation illustrated in the example above is a
+ more obvious, intuitive, and readable way to request the compiler
+ to adjust the alignment of an entire `struct' or `union' type.
+
+ As in the preceding example, you can explicitly specify the
+ alignment (in bytes) that you wish the compiler to use for a given
+ `struct' or `union' type. Alternatively, you can leave out the
+ alignment factor and just ask the compiler to align a type to the
+ maximum useful alignment for the target machine you are compiling
+ for. For example, you could write:
+
+ struct S { short f[3]; } __attribute__ ((aligned));
+
+ Whenever you leave out the alignment factor in an `aligned'
+ attribute specification, the compiler automatically sets the
+ alignment for the type to the largest alignment which is ever used
+ for any data type on the target machine you are compiling for.
+ Doing this can often make copy operations more efficient, because
+ the compiler can use whatever instructions copy the biggest chunks
+ of memory when performing copies to or from the variables which
+ have types that you have aligned this way.
+
+ In the example above, if the size of each `short' is 2 bytes, then
+ the size of the entire `struct S' type is 6 bytes. The smallest
+ power of two which is greater than or equal to that is 8, so the
+ compiler sets the alignment for the entire `struct S' type to 8
+ bytes.
+
+ Note that although you can ask the compiler to select a
+ time-efficient alignment for a given type and then declare only
+ individual stand-alone objects of that type, the compiler's
+ ability to select a time-efficient alignment is primarily useful
+ only when you plan to create arrays of variables having the
+ relevant (efficiently aligned) type. If you declare or use arrays
+ of variables of an efficiently-aligned type, then it is likely
+ that your program will also be doing pointer arithmetic (or
+ subscripting, which amounts to the same thing) on pointers to the
+ relevant type, and the code that the compiler generates for these
+ pointer arithmetic operations will often be more efficient for
+ efficiently-aligned types than for other types.
+
+ The `aligned' attribute can only increase the alignment; but you
+ can decrease it by specifying `packed' as well. See below.
+
+ Note that the effectiveness of `aligned' attributes may be limited
+ by inherent limitations in your linker. On many systems, the
+ linker is only able to arrange for variables to be aligned up to a
+ certain maximum alignment. (For some linkers, the maximum
+ supported alignment may be very very small.) If your linker is
+ only able to align variables up to a maximum of 8 byte alignment,
+ then specifying `aligned(16)' in an `__attribute__' will still
+ only provide you with 8 byte alignment. See your linker
+ documentation for further information.
+
+`packed'
+ This attribute, attached to an `enum', `struct', or `union' type
+ definition, specified that the minimum required memory be used to
+ represent the type.
+
+ Specifying this attribute for `struct' and `union' types is
+ equivalent to specifying the `packed' attribute on each of the
+ structure or union members. Specifying the `-fshort-enums' flag
+ on the line is equivalent to specifying the `packed' attribute on
+ all `enum' definitions.
+
+ You may only specify this attribute after a closing curly brace on
+ an `enum' definition, not in a `typedef' declaration, unless that
+ declaration also contains the definition of the `enum'.
+
+`transparent_union'
+ This attribute, attached to a `union' type definition, indicates
+ that any function parameter having that union type causes calls to
+ that function to be treated in a special way.
+
+ First, the argument corresponding to a transparent union type can
+ be of any type in the union; no cast is required. Also, if the
+ union contains a pointer type, the corresponding argument can be a
+ null pointer constant or a void pointer expression; and if the
+ union contains a void pointer type, the corresponding argument can
+ be any pointer expression. If the union member type is a pointer,
+ qualifiers like `const' on the referenced type must be respected,
+ just as with normal pointer conversions.
+
+ Second, the argument is passed to the function using the calling
+ conventions of first member of the transparent union, not the
+ calling conventions of the union itself. All members of the union
+ must have the same machine representation; this is necessary for
+ this argument passing to work properly.
+
+ Transparent unions are designed for library functions that have
+ multiple interfaces for compatibility reasons. For example,
+ suppose the `wait' function must accept either a value of type
+ `int *' to comply with Posix, or a value of type `union wait *' to
+ comply with the 4.1BSD interface. If `wait''s parameter were
+ `void *', `wait' would accept both kinds of arguments, but it
+ would also accept any other pointer type and this would make
+ argument type checking less useful. Instead, `<sys/wait.h>' might
+ define the interface as follows:
+
+ typedef union
+ {
+ int *__ip;
+ union wait *__up;
+ } wait_status_ptr_t __attribute__ ((__transparent_union__));
+
+ pid_t wait (wait_status_ptr_t);
+
+ This interface allows either `int *' or `union wait *' arguments
+ to be passed, using the `int *' calling convention. The program
+ can call `wait' with arguments of either type:
+
+ int w1 () { int w; return wait (&w); }
+ int w2 () { union wait w; return wait (&w); }
+
+ With this interface, `wait''s implementation might look like this:
+
+ pid_t wait (wait_status_ptr_t p)
+ {
+ return waitpid (-1, p.__ip, 0);
+ }
+
+`unused'
+ When attached to a type (including a `union' or a `struct'), this
+ attribute means that variables of that type are meant to appear
+ possibly unused. GCC will not produce a warning for any variables
+ of that type, even if the variable appears to do nothing. This is
+ often the case with lock or thread classes, which are usually
+ defined and then not referenced, but contain constructors and
+ destructors that have nontrivial bookkeeping functions.
+
+`deprecated'
+ The `deprecated' attribute results in a warning if the type is
+ used anywhere in the source file. This is useful when identifying
+ types that are expected to be removed in a future version of a
+ program. If possible, the warning also includes the location of
+ the declaration of the deprecated type, to enable users to easily
+ find further information about why the type is deprecated, or what
+ they should do instead. Note that the warnings only occur for
+ uses and then only if the type is being applied to an identifier
+ that itself is not being declared as deprecated.
+
+ typedef int T1 __attribute__ ((deprecated));
+ T1 x;
+ typedef T1 T2;
+ T2 y;
+ typedef T1 T3 __attribute__ ((deprecated));
+ T3 z __attribute__ ((deprecated));
+
+ results in a warning on line 2 and 3 but not lines 4, 5, or 6. No
+ warning is issued for line 4 because T2 is not explicitly
+ deprecated. Line 5 has no warning because T3 is explicitly
+ deprecated. Similarly for line 6.
+
+ The `deprecated' attribute can also be used for functions and
+ variables (*note Function Attributes::, *note Variable
+ Attributes::.)
+
+
+ To specify multiple attributes, separate them by commas within the
+double parentheses: for example, `__attribute__ ((aligned (16),
+packed))'.
+
+\1f
+File: gcc.info, Node: Inline, Next: Extended Asm, Prev: Alignment, Up: C Extensions
+
+5.34 An Inline Function is As Fast As a Macro
+=============================================
+
+By declaring a function `inline', you can direct GCC to integrate that
+function's code into the code for its callers. This makes execution
+faster by eliminating the function-call overhead; in addition, if any
+of the actual argument values are constant, their known values may
+permit simplifications at compile time so that not all of the inline
+function's code needs to be included. The effect on code size is less
+predictable; object code may be larger or smaller with function
+inlining, depending on the particular case. Inlining of functions is an
+optimization and it really "works" only in optimizing compilation. If
+you don't use `-O', no function is really inline.
+
+ Inline functions are included in the ISO C99 standard, but there are
+currently substantial differences between what GCC implements and what
+the ISO C99 standard requires.
+
+ To declare a function inline, use the `inline' keyword in its
+declaration, like this:
+
+ inline int
+ inc (int *a)
+ {
+ (*a)++;
+ }
+
+ (If you are writing a header file to be included in ISO C programs,
+write `__inline__' instead of `inline'. *Note Alternate Keywords::.)
+You can also make all "simple enough" functions inline with the option
+`-finline-functions'.
+
+ Note that certain usages in a function definition can make it
+unsuitable for inline substitution. Among these usages are: use of
+varargs, use of alloca, use of variable sized data types (*note
+Variable Length::), use of computed goto (*note Labels as Values::),
+use of nonlocal goto, and nested functions (*note Nested Functions::).
+Using `-Winline' will warn when a function marked `inline' could not be
+substituted, and will give the reason for the failure.
+
+ Note that in C and Objective-C, unlike C++, the `inline' keyword
+does not affect the linkage of the function.
+
+ GCC automatically inlines member functions defined within the class
+body of C++ programs even if they are not explicitly declared `inline'.
+(You can override this with `-fno-default-inline'; *note Options
+Controlling C++ Dialect: C++ Dialect Options.)
+
+ When a function is both inline and `static', if all calls to the
+function are integrated into the caller, and the function's address is
+never used, then the function's own assembler code is never referenced.
+In this case, GCC does not actually output assembler code for the
+function, unless you specify the option `-fkeep-inline-functions'.
+Some calls cannot be integrated for various reasons (in particular,
+calls that precede the function's definition cannot be integrated, and
+neither can recursive calls within the definition). If there is a
+nonintegrated call, then the function is compiled to assembler code as
+usual. The function must also be compiled as usual if the program
+refers to its address, because that can't be inlined.
+
+ When an inline function is not `static', then the compiler must
+assume that there may be calls from other source files; since a global
+symbol can be defined only once in any program, the function must not
+be defined in the other source files, so the calls therein cannot be
+integrated. Therefore, a non-`static' inline function is always
+compiled on its own in the usual fashion.
+
+ If you specify both `inline' and `extern' in the function
+definition, then the definition is used only for inlining. In no case
+is the function compiled on its own, not even if you refer to its
+address explicitly. Such an address becomes an external reference, as
+if you had only declared the function, and had not defined it.
+
+ This combination of `inline' and `extern' has almost the effect of a
+macro. The way to use it is to put a function definition in a header
+file with these keywords, and put another copy of the definition
+(lacking `inline' and `extern') in a library file. The definition in
+the header file will cause most calls to the function to be inlined.
+If any uses of the function remain, they will refer to the single copy
+in the library.
+
+ For future compatibility with when GCC implements ISO C99 semantics
+for inline functions, it is best to use `static inline' only. (The
+existing semantics will remain available when `-std=gnu89' is
+specified, but eventually the default will be `-std=gnu99' and that
+will implement the C99 semantics, though it does not do so yet.)
+
+ GCC does not inline any functions when not optimizing unless you
+specify the `always_inline' attribute for the function, like this:
+
+ /* Prototype. */
+ inline void foo (const char) __attribute__((always_inline));
+
+\1f
+File: gcc.info, Node: Extended Asm, Next: Constraints, Prev: Inline, Up: C Extensions
+
+5.35 Assembler Instructions with C Expression Operands
+======================================================
+
+In an assembler instruction using `asm', you can specify the operands
+of the instruction using C expressions. This means you need not guess
+which registers or memory locations will contain the data you want to
+use.
+
+ You must specify an assembler instruction template much like what
+appears in a machine description, plus an operand constraint string for
+each operand.
+
+ For example, here is how to use the 68881's `fsinx' instruction:
+
+ asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
+
+Here `angle' is the C expression for the input operand while `result'
+is that of the output operand. Each has `"f"' as its operand
+constraint, saying that a floating point register is required. The `='
+in `=f' indicates that the operand is an output; all output operands'
+constraints must use `='. The constraints use the same language used
+in the machine description (*note Constraints::).
+
+ Each operand is described by an operand-constraint string followed by
+the C expression in parentheses. A colon separates the assembler
+template from the first output operand and another separates the last
+output operand from the first input, if any. Commas separate the
+operands within each group. The total number of operands is currently
+limited to 30; this limitation may be lifted in some future version of
+GCC.
+
+ If there are no output operands but there are input operands, you
+must place two consecutive colons surrounding the place where the output
+operands would go.
+
+ As of GCC version 3.1, it is also possible to specify input and
+output operands using symbolic names which can be referenced within the
+assembler code. These names are specified inside square brackets
+preceding the constraint string, and can be referenced inside the
+assembler code using `%[NAME]' instead of a percentage sign followed by
+the operand number. Using named operands the above example could look
+like:
+
+ asm ("fsinx %[angle],%[output]"
+ : [output] "=f" (result)
+ : [angle] "f" (angle));
+
+Note that the symbolic operand names have no relation whatsoever to
+other C identifiers. You may use any name you like, even those of
+existing C symbols, but must ensure that no two operands within the same
+assembler construct use the same symbolic name.
+
+ Output operand expressions must be lvalues; the compiler can check
+this. The input operands need not be lvalues. The compiler cannot
+check whether the operands have data types that are reasonable for the
+instruction being executed. It does not parse the assembler instruction
+template and does not know what it means or even whether it is valid
+assembler input. The extended `asm' feature is most often used for
+machine instructions the compiler itself does not know exist. If the
+output expression cannot be directly addressed (for example, it is a
+bit-field), your constraint must allow a register. In that case, GCC
+will use the register as the output of the `asm', and then store that
+register into the output.
+
+ The ordinary output operands must be write-only; GCC will assume that
+the values in these operands before the instruction are dead and need
+not be generated. Extended asm supports input-output or read-write
+operands. Use the constraint character `+' to indicate such an operand
+and list it with the output operands.
+
+ When the constraints for the read-write operand (or the operand in
+which only some of the bits are to be changed) allows a register, you
+may, as an alternative, logically split its function into two separate
+operands, one input operand and one write-only output operand. The
+connection between them is expressed by constraints which say they need
+to be in the same location when the instruction executes. You can use
+the same C expression for both operands, or different expressions. For
+example, here we write the (fictitious) `combine' instruction with
+`bar' as its read-only source operand and `foo' as its read-write
+destination:
+
+ asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));
+
+The constraint `"0"' for operand 1 says that it must occupy the same
+location as operand 0. A number in constraint is allowed only in an
+input operand and it must refer to an output operand.
+
+ Only a number in the constraint can guarantee that one operand will
+be in the same place as another. The mere fact that `foo' is the value
+of both operands is not enough to guarantee that they will be in the
+same place in the generated assembler code. The following would not
+work reliably:
+
+ asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar));
+
+ Various optimizations or reloading could cause operands 0 and 1 to
+be in different registers; GCC knows no reason not to do so. For
+example, the compiler might find a copy of the value of `foo' in one
+register and use it for operand 1, but generate the output operand 0 in
+a different register (copying it afterward to `foo''s own address). Of
+course, since the register for operand 1 is not even mentioned in the
+assembler code, the result will not work, but GCC can't tell that.
+
+ As of GCC version 3.1, one may write `[NAME]' instead of the operand
+number for a matching constraint. For example:
+
+ asm ("cmoveq %1,%2,%[result]"
+ : [result] "=r"(result)
+ : "r" (test), "r"(new), "[result]"(old));
+
+ Some instructions clobber specific hard registers. To describe this,
+write a third colon after the input operands, followed by the names of
+the clobbered hard registers (given as strings). Here is a realistic
+example for the VAX:
+
+ asm volatile ("movc3 %0,%1,%2"
+ : /* no outputs */
+ : "g" (from), "g" (to), "g" (count)
+ : "r0", "r1", "r2", "r3", "r4", "r5");
+
+ You may not write a clobber description in a way that overlaps with
+an input or output operand. For example, you may not have an operand
+describing a register class with one member if you mention that register
+in the clobber list. There is no way for you to specify that an input
+operand is modified without also specifying it as an output operand.
+Note that if all the output operands you specify are for this purpose
+(and hence unused), you will then also need to specify `volatile' for
+the `asm' construct, as described below, to prevent GCC from deleting
+the `asm' statement as unused.
+
+ If you refer to a particular hardware register from the assembler
+code, you will probably have to list the register after the third colon
+to tell the compiler the register's value is modified. In some
+assemblers, the register names begin with `%'; to produce one `%' in the
+assembler code, you must write `%%' in the input.
+
+ If your assembler instruction can alter the condition code register,
+add `cc' to the list of clobbered registers. GCC on some machines
+represents the condition codes as a specific hardware register; `cc'
+serves to name this register. On other machines, the condition code is
+handled differently, and specifying `cc' has no effect. But it is
+valid no matter what the machine.
+
+ If your assembler instruction modifies memory in an unpredictable
+fashion, add `memory' to the list of clobbered registers. This will
+cause GCC to not keep memory values cached in registers across the
+assembler instruction. You will also want to add the `volatile'
+keyword if the memory affected is not listed in the inputs or outputs
+of the `asm', as the `memory' clobber does not count as a side-effect
+of the `asm'.
+
+ You can put multiple assembler instructions together in a single
+`asm' template, separated by the characters normally used in assembly
+code for the system. A combination that works in most places is a
+newline to break the line, plus a tab character to move to the
+instruction field (written as `\n\t'). Sometimes semicolons can be
+used, if the assembler allows semicolons as a line-breaking character.
+Note that some assembler dialects use semicolons to start a comment.
+The input operands are guaranteed not to use any of the clobbered
+registers, and neither will the output operands' addresses, so you can
+read and write the clobbered registers as many times as you like. Here
+is an example of multiple instructions in a template; it assumes the
+subroutine `_foo' accepts arguments in registers 9 and 10:
+
+ asm ("movl %0,r9\n\tmovl %1,r10\n\tcall _foo"
+ : /* no outputs */
+ : "g" (from), "g" (to)
+ : "r9", "r10");
+
+ Unless an output operand has the `&' constraint modifier, GCC may
+allocate it in the same register as an unrelated input operand, on the
+assumption the inputs are consumed before the outputs are produced.
+This assumption may be false if the assembler code actually consists of
+more than one instruction. In such a case, use `&' for each output
+operand that may not overlap an input. *Note Modifiers::.
+
+ If you want to test the condition code produced by an assembler
+instruction, you must include a branch and a label in the `asm'
+construct, as follows:
+
+ asm ("clr %0\n\tfrob %1\n\tbeq 0f\n\tmov #1,%0\n0:"
+ : "g" (result)
+ : "g" (input));
+
+This assumes your assembler supports local labels, as the GNU assembler
+and most Unix assemblers do.
+
+ Speaking of labels, jumps from one `asm' to another are not
+supported. The compiler's optimizers do not know about these jumps, and
+therefore they cannot take account of them when deciding how to
+optimize.
+
+ Usually the most convenient way to use these `asm' instructions is to
+encapsulate them in macros that look like functions. For example,
+
+ #define sin(x) \
+ ({ double __value, __arg = (x); \
+ asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \
+ __value; })
+
+Here the variable `__arg' is used to make sure that the instruction
+operates on a proper `double' value, and to accept only those arguments
+`x' which can convert automatically to a `double'.
+
+ Another way to make sure the instruction operates on the correct data
+type is to use a cast in the `asm'. This is different from using a
+variable `__arg' in that it converts more different types. For
+example, if the desired type were `int', casting the argument to `int'
+would accept a pointer with no complaint, while assigning the argument
+to an `int' variable named `__arg' would warn about using a pointer
+unless the caller explicitly casts it.
+
+ If an `asm' has output operands, GCC assumes for optimization
+purposes the instruction has no side effects except to change the output
+operands. This does not mean instructions with a side effect cannot be
+used, but you must be careful, because the compiler may eliminate them
+if the output operands aren't used, or move them out of loops, or
+replace two with one if they constitute a common subexpression. Also,
+if your instruction does have a side effect on a variable that otherwise
+appears not to change, the old value of the variable may be reused later
+if it happens to be found in a register.
+
+ You can prevent an `asm' instruction from being deleted, moved
+significantly, or combined, by writing the keyword `volatile' after the
+`asm'. For example:
+
+ #define get_and_set_priority(new) \
+ ({ int __old; \
+ asm volatile ("get_and_set_priority %0, %1" \
+ : "=g" (__old) : "g" (new)); \
+ __old; })
+
+If you write an `asm' instruction with no outputs, GCC will know the
+instruction has side-effects and will not delete the instruction or
+move it outside of loops.
+
+ The `volatile' keyword indicates that the instruction has important
+side-effects. GCC will not delete a volatile `asm' if it is reachable.
+(The instruction can still be deleted if GCC can prove that
+control-flow will never reach the location of the instruction.) In
+addition, GCC will not reschedule instructions across a volatile `asm'
+instruction. For example:
+
+ *(volatile int *)addr = foo;
+ asm volatile ("eieio" : : );
+
+Assume `addr' contains the address of a memory mapped device register.
+The PowerPC `eieio' instruction (Enforce In-order Execution of I/O)
+tells the CPU to make sure that the store to that device register
+happens before it issues any other I/O.
+
+ Note that even a volatile `asm' instruction can be moved in ways
+that appear insignificant to the compiler, such as across jump
+instructions. You can't expect a sequence of volatile `asm'
+instructions to remain perfectly consecutive. If you want consecutive
+output, use a single `asm'. Also, GCC will perform some optimizations
+across a volatile `asm' instruction; GCC does not "forget everything"
+when it encounters a volatile `asm' instruction the way some other
+compilers do.
+
+ An `asm' instruction without any operands or clobbers (an "old
+style" `asm') will be treated identically to a volatile `asm'
+instruction.
+
+ It is a natural idea to look for a way to give access to the
+condition code left by the assembler instruction. However, when we
+attempted to implement this, we found no way to make it work reliably.
+The problem is that output operands might need reloading, which would
+result in additional following "store" instructions. On most machines,
+these instructions would alter the condition code before there was time
+to test it. This problem doesn't arise for ordinary "test" and
+"compare" instructions because they don't have any output operands.
+
+ For reasons similar to those described above, it is not possible to
+give an assembler instruction access to the condition code left by
+previous instructions.
+
+ If you are writing a header file that should be includable in ISO C
+programs, write `__asm__' instead of `asm'. *Note Alternate Keywords::.
+
+5.35.1 i386 floating point asm operands
+---------------------------------------
+
+There are several rules on the usage of stack-like regs in asm_operands
+insns. These rules apply only to the operands that are stack-like regs:
+
+ 1. Given a set of input regs that die in an asm_operands, it is
+ necessary to know which are implicitly popped by the asm, and
+ which must be explicitly popped by gcc.
+
+ An input reg that is implicitly popped by the asm must be
+ explicitly clobbered, unless it is constrained to match an output
+ operand.
+
+ 2. For any input reg that is implicitly popped by an asm, it is
+ necessary to know how to adjust the stack to compensate for the
+ pop. If any non-popped input is closer to the top of the
+ reg-stack than the implicitly popped reg, it would not be possible
+ to know what the stack looked like--it's not clear how the rest of
+ the stack "slides up".
+
+ All implicitly popped input regs must be closer to the top of the
+ reg-stack than any input that is not implicitly popped.
+
+ It is possible that if an input dies in an insn, reload might use
+ the input reg for an output reload. Consider this example:
+
+ asm ("foo" : "=t" (a) : "f" (b));
+
+ This asm says that input B is not popped by the asm, and that the
+ asm pushes a result onto the reg-stack, i.e., the stack is one
+ deeper after the asm than it was before. But, it is possible that
+ reload will think that it can use the same reg for both the input
+ and the output, if input B dies in this insn.
+
+ If any input operand uses the `f' constraint, all output reg
+ constraints must use the `&' earlyclobber.
+
+ The asm above would be written as
+
+ asm ("foo" : "=&t" (a) : "f" (b));
+
+ 3. Some operands need to be in particular places on the stack. All
+ output operands fall in this category--there is no other way to
+ know which regs the outputs appear in unless the user indicates
+ this in the constraints.
+
+ Output operands must specifically indicate which reg an output
+ appears in after an asm. `=f' is not allowed: the operand
+ constraints must select a class with a single reg.
+
+ 4. Output operands may not be "inserted" between existing stack regs.
+ Since no 387 opcode uses a read/write operand, all output operands
+ are dead before the asm_operands, and are pushed by the
+ asm_operands. It makes no sense to push anywhere but the top of
+ the reg-stack.
+
+ Output operands must start at the top of the reg-stack: output
+ operands may not "skip" a reg.
+
+ 5. Some asm statements may need extra stack space for internal
+ calculations. This can be guaranteed by clobbering stack registers
+ unrelated to the inputs and outputs.
+
+
+ Here are a couple of reasonable asms to want to write. This asm
+takes one input, which is internally popped, and produces two outputs.
+
+ asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp));
+
+ This asm takes two inputs, which are popped by the `fyl2xp1' opcode,
+and replaces them with one output. The user must code the `st(1)'
+clobber for reg-stack.c to know that `fyl2xp1' pops both inputs.
+
+ asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)");
+
+\1f
+File: gcc.info, Node: Constraints, Next: Asm Labels, Prev: Extended Asm, Up: C Extensions
+
+5.36 Constraints for `asm' Operands
+===================================
+
+Here are specific details on what constraint letters you can use with
+`asm' operands. Constraints can say whether an operand may be in a
+register, and which kinds of register; whether the operand can be a
+memory reference, and which kinds of address; whether the operand may
+be an immediate constant, and which possible values it may have.
+Constraints can also require two operands to match.
+
+* Menu:
+
+* Simple Constraints:: Basic use of constraints.
+* Multi-Alternative:: When an insn has two alternative constraint-patterns.
+* Modifiers:: More precise control over effects of constraints.
+* Machine Constraints:: Special constraints for some particular machines.
+
+\1f
+File: gcc.info, Node: Simple Constraints, Next: Multi-Alternative, Up: Constraints
+
+5.36.1 Simple Constraints
+-------------------------
+
+The simplest kind of constraint is a string full of letters, each of
+which describes one kind of operand that is permitted. Here are the
+letters that are allowed:
+
+whitespace
+ Whitespace characters are ignored and can be inserted at any
+ position except the first. This enables each alternative for
+ different operands to be visually aligned in the machine
+ description even if they have different number of constraints and
+ modifiers.
+
+`m'
+ A memory operand is allowed, with any kind of address that the
+ machine supports in general.
+
+`o'
+ A memory operand is allowed, but only if the address is
+ "offsettable". This means that adding a small integer (actually,
+ the width in bytes of the operand, as determined by its machine
+ mode) may be added to the address and the result is also a valid
+ memory address.
+
+ For example, an address which is constant is offsettable; so is an
+ address that is the sum of a register and a constant (as long as a
+ slightly larger constant is also within the range of
+ address-offsets supported by the machine); but an autoincrement or
+ autodecrement address is not offsettable. More complicated
+ indirect/indexed addresses may or may not be offsettable depending
+ on the other addressing modes that the machine supports.
+
+ Note that in an output operand which can be matched by another
+ operand, the constraint letter `o' is valid only when accompanied
+ by both `<' (if the target machine has predecrement addressing)
+ and `>' (if the target machine has preincrement addressing).
+
+`V'
+ A memory operand that is not offsettable. In other words,
+ anything that would fit the `m' constraint but not the `o'
+ constraint.
+
+`<'
+ A memory operand with autodecrement addressing (either
+ predecrement or postdecrement) is allowed.
+
+`>'
+ A memory operand with autoincrement addressing (either
+ preincrement or postincrement) is allowed.
+
+`r'
+ A register operand is allowed provided that it is in a general
+ register.
+
+`i'
+ An immediate integer operand (one with constant value) is allowed.
+ This includes symbolic constants whose values will be known only at
+ assembly time.
+
+`n'
+ An immediate integer operand with a known numeric value is allowed.
+ Many systems cannot support assembly-time constants for operands
+ less than a word wide. Constraints for these operands should use
+ `n' rather than `i'.
+
+`I', `J', `K', ... `P'
+ Other letters in the range `I' through `P' may be defined in a
+ machine-dependent fashion to permit immediate integer operands with
+ explicit integer values in specified ranges. For example, on the
+ 68000, `I' is defined to stand for the range of values 1 to 8.
+ This is the range permitted as a shift count in the shift
+ instructions.
+
+`E'
+ An immediate floating operand (expression code `const_double') is
+ allowed, but only if the target floating point format is the same
+ as that of the host machine (on which the compiler is running).
+
+`F'
+ An immediate floating operand (expression code `const_double') is
+ allowed.
+
+`G', `H'
+ `G' and `H' may be defined in a machine-dependent fashion to
+ permit immediate floating operands in particular ranges of values.
+
+`s'
+ An immediate integer operand whose value is not an explicit
+ integer is allowed.
+
+ This might appear strange; if an insn allows a constant operand
+ with a value not known at compile time, it certainly must allow
+ any known value. So why use `s' instead of `i'? Sometimes it
+ allows better code to be generated.
+
+ For example, on the 68000 in a fullword instruction it is possible
+ to use an immediate operand; but if the immediate value is between
+ -128 and 127, better code results from loading the value into a
+ register and using the register. This is because the load into
+ the register can be done with a `moveq' instruction. We arrange
+ for this to happen by defining the letter `K' to mean "any integer
+ outside the range -128 to 127", and then specifying `Ks' in the
+ operand constraints.
+
+`g'
+ Any register, memory or immediate integer operand is allowed,
+ except for registers that are not general registers.
+
+`X'
+ Any operand whatsoever is allowed.
+
+`0', `1', `2', ... `9'
+ An operand that matches the specified operand number is allowed.
+ If a digit is used together with letters within the same
+ alternative, the digit should come last.
+
+ This number is allowed to be more than a single digit. If multiple
+ digits are encountered consecutavely, they are interpreted as a
+ single decimal integer. There is scant chance for ambiguity,
+ since to-date it has never been desirable that `10' be interpreted
+ as matching either operand 1 _or_ operand 0. Should this be
+ desired, one can use multiple alternatives instead.
+
+ This is called a "matching constraint" and what it really means is
+ that the assembler has only a single operand that fills two roles
+ which `asm' distinguishes. For example, an add instruction uses
+ two input operands and an output operand, but on most CISC
+ machines an add instruction really has only two operands, one of
+ them an input-output operand:
+
+ addl #35,r12
+
+ Matching constraints are used in these circumstances. More
+ precisely, the two operands that match must include one input-only
+ operand and one output-only operand. Moreover, the digit must be a
+ smaller number than the number of the operand that uses it in the
+ constraint.
+
+`p'
+ An operand that is a valid memory address is allowed. This is for
+ "load address" and "push address" instructions.
+
+ `p' in the constraint must be accompanied by `address_operand' as
+ the predicate in the `match_operand'. This predicate interprets
+ the mode specified in the `match_operand' as the mode of the memory
+ reference for which the address would be valid.
+
+OTHER-LETTERS
+ Other letters can be defined in machine-dependent fashion to stand
+ for particular classes of registers or other arbitrary operand
+ types. `d', `a' and `f' are defined on the 68000/68020 to stand
+ for data, address and floating point registers.
+
+
+\1f
+File: gcc.info, Node: Multi-Alternative, Next: Modifiers, Prev: Simple Constraints, Up: Constraints
+
+5.36.2 Multiple Alternative Constraints
+---------------------------------------
+
+Sometimes a single instruction has multiple alternative sets of possible
+operands. For example, on the 68000, a logical-or instruction can
+combine register or an immediate value into memory, or it can combine
+any kind of operand into a register; but it cannot combine one memory
+location into another.
+
+ These constraints are represented as multiple alternatives. An
+alternative can be described by a series of letters for each operand.
+The overall constraint for an operand is made from the letters for this
+operand from the first alternative, a comma, the letters for this
+operand from the second alternative, a comma, and so on until the last
+alternative.
+
+ If all the operands fit any one alternative, the instruction is
+valid. Otherwise, for each alternative, the compiler counts how many
+instructions must be added to copy the operands so that that
+alternative applies. The alternative requiring the least copying is
+chosen. If two alternatives need the same amount of copying, the one
+that comes first is chosen. These choices can be altered with the `?'
+and `!' characters:
+
+`?'
+ Disparage slightly the alternative that the `?' appears in, as a
+ choice when no alternative applies exactly. The compiler regards
+ this alternative as one unit more costly for each `?' that appears
+ in it.
+
+`!'
+ Disparage severely the alternative that the `!' appears in. This
+ alternative can still be used if it fits without reloading, but if
+ reloading is needed, some other alternative will be used.
+
+\1f
+File: gcc.info, Node: Modifiers, Next: Machine Constraints, Prev: Multi-Alternative, Up: Constraints
+
+5.36.3 Constraint Modifier Characters
+-------------------------------------
+
+Here are constraint modifier characters.
+
+`='
+ Means that this operand is write-only for this instruction: the
+ previous value is discarded and replaced by output data.
+
+`+'
+ Means that this operand is both read and written by the
+ instruction.
+
+ When the compiler fixes up the operands to satisfy the constraints,
+ it needs to know which operands are inputs to the instruction and
+ which are outputs from it. `=' identifies an output; `+'
+ identifies an operand that is both input and output; all other
+ operands are assumed to be input only.
+
+ If you specify `=' or `+' in a constraint, you put it in the first
+ character of the constraint string.
+
+`&'
+ Means (in a particular alternative) that this operand is an
+ "earlyclobber" operand, which is modified before the instruction is
+ finished using the input operands. Therefore, this operand may
+ not lie in a register that is used as an input operand or as part
+ of any memory address.
+
+ `&' applies only to the alternative in which it is written. In
+ constraints with multiple alternatives, sometimes one alternative
+ requires `&' while others do not. See, for example, the `movdf'
+ insn of the 68000.
+
+ An input operand can be tied to an earlyclobber operand if its only
+ use as an input occurs before the early result is written. Adding
+ alternatives of this form often allows GCC to produce better code
+ when only some of the inputs can be affected by the earlyclobber.
+ See, for example, the `mulsi3' insn of the ARM.
+
+ `&' does not obviate the need to write `='.
+
+`%'
+ Declares the instruction to be commutative for this operand and the
+ following operand. This means that the compiler may interchange
+ the two operands if that is the cheapest way to make all operands
+ fit the constraints.
+
+`#'
+ Says that all following characters, up to the next comma, are to be
+ ignored as a constraint. They are significant only for choosing
+ register preferences.
+
+`*'
+ Says that the following character should be ignored when choosing
+ register preferences. `*' has no effect on the meaning of the
+ constraint as a constraint, and no effect on reloading.
+
+
+\1f
+File: gcc.info, Node: Machine Constraints, Prev: Modifiers, Up: Constraints
+
+5.36.4 Constraints for Particular Machines
+------------------------------------------
+
+Whenever possible, you should use the general-purpose constraint letters
+in `asm' arguments, since they will convey meaning more readily to
+people reading your code. Failing that, use the constraint letters
+that usually have very similar meanings across architectures. The most
+commonly used constraints are `m' and `r' (for memory and
+general-purpose registers respectively; *note Simple Constraints::), and
+`I', usually the letter indicating the most common immediate-constant
+format.
+
+ For each machine architecture, the `config/MACHINE/MACHINE.h' file
+defines additional constraints. These constraints are used by the
+compiler itself for instruction generation, as well as for `asm'
+statements; therefore, some of the constraints are not particularly
+interesting for `asm'. The constraints are defined through these
+macros:
+
+`REG_CLASS_FROM_LETTER'
+ Register class constraints (usually lower case).
+
+`CONST_OK_FOR_LETTER_P'
+ Immediate constant constraints, for non-floating point constants of
+ word size or smaller precision (usually upper case).
+
+`CONST_DOUBLE_OK_FOR_LETTER_P'
+ Immediate constant constraints, for all floating point constants
+ and for constants of greater than word size precision (usually
+ upper case).
+
+`EXTRA_CONSTRAINT'
+ Special cases of registers or memory. This macro is not required,
+ and is only defined for some machines.
+
+ Inspecting these macro definitions in the compiler source for your
+machine is the best way to be certain you have the right constraints.
+However, here is a summary of the machine-dependent constraints
+available on some particular machines.
+
+_ARM family--`arm.h'_
+
+ `f'
+ Floating-point register
+
+ `F'
+ One of the floating-point constants 0.0, 0.5, 1.0, 2.0, 3.0,
+ 4.0, 5.0 or 10.0
+
+ `G'
+ Floating-point constant that would satisfy the constraint `F'
+ if it were negated
+
+ `I'
+ Integer that is valid as an immediate operand in a data
+ processing instruction. That is, an integer in the range 0
+ to 255 rotated by a multiple of 2
+
+ `J'
+ Integer in the range -4095 to 4095
+
+ `K'
+ Integer that satisfies constraint `I' when inverted (ones
+ complement)
+
+ `L'
+ Integer that satisfies constraint `I' when negated (twos
+ complement)
+
+ `M'
+ Integer in the range 0 to 32
+
+ `Q'
+ A memory reference where the exact address is in a single
+ register (``m'' is preferable for `asm' statements)
+
+ `R'
+ An item in the constant pool
+
+ `S'
+ A symbol in the text segment of the current file
+
+_AMD 29000 family--`a29k.h'_
+
+ `l'
+ Local register 0
+
+ `b'
+ Byte Pointer (`BP') register
+
+ `q'
+ `Q' register
+
+ `h'
+ Special purpose register
+
+ `A'
+ First accumulator register
+
+ `a'
+ Other accumulator register
+
+ `f'
+ Floating point register
+
+ `I'
+ Constant greater than 0, less than 0x100
+
+ `J'
+ Constant greater than 0, less than 0x10000
+
+ `K'
+ Constant whose high 24 bits are on (1)
+
+ `L'
+ 16-bit constant whose high 8 bits are on (1)
+
+ `M'
+ 32-bit constant whose high 16 bits are on (1)
+
+ `N'
+ 32-bit negative constant that fits in 8 bits
+
+ `O'
+ The constant 0x80000000 or, on the 29050, any 32-bit constant
+ whose low 16 bits are 0.
+
+ `P'
+ 16-bit negative constant that fits in 8 bits
+
+ `G'
+ `H'
+ A floating point constant (in `asm' statements, use the
+ machine independent `E' or `F' instead)
+
+_AVR family--`avr.h'_
+
+ `l'
+ Registers from r0 to r15
+
+ `a'
+ Registers from r16 to r23
+
+ `d'
+ Registers from r16 to r31
+
+ `w'
+ Registers from r24 to r31. These registers can be used in
+ `adiw' command
+
+ `e'
+ Pointer register (r26-r31)
+
+ `b'
+ Base pointer register (r28-r31)
+
+ `q'
+ Stack pointer register (SPH:SPL)
+
+ `t'
+ Temporary register r0
+
+ `x'
+ Register pair X (r27:r26)
+
+ `y'
+ Register pair Y (r29:r28)
+
+ `z'
+ Register pair Z (r31:r30)
+
+ `I'
+ Constant greater than -1, less than 64
+
+ `J'
+ Constant greater than -64, less than 1
+
+ `K'
+ Constant integer 2
+
+ `L'
+ Constant integer 0
+
+ `M'
+ Constant that fits in 8 bits
+
+ `N'
+ Constant integer -1
+
+ `O'
+ Constant integer 8, 16, or 24
+
+ `P'
+ Constant integer 1
+
+ `G'
+ A floating point constant 0.0
+
+_IBM RS6000--`rs6000.h'_
+
+ `b'
+ Address base register
+
+ `f'
+ Floating point register
+
+ `h'
+ `MQ', `CTR', or `LINK' register
+
+ `q'
+ `MQ' register
+
+ `c'
+ `CTR' register
+
+ `l'
+ `LINK' register
+
+ `x'
+ `CR' register (condition register) number 0
+
+ `y'
+ `CR' register (condition register)
+
+ `z'
+ `FPMEM' stack memory for FPR-GPR transfers
+
+ `I'
+ Signed 16-bit constant
+
+ `J'
+ Unsigned 16-bit constant shifted left 16 bits (use `L'
+ instead for `SImode' constants)
+
+ `K'
+ Unsigned 16-bit constant
+
+ `L'
+ Signed 16-bit constant shifted left 16 bits
+
+ `M'
+ Constant larger than 31
+
+ `N'
+ Exact power of 2
+
+ `O'
+ Zero
+
+ `P'
+ Constant whose negation is a signed 16-bit constant
+
+ `G'
+ Floating point constant that can be loaded into a register
+ with one instruction per word
+
+ `Q'
+ Memory operand that is an offset from a register (`m' is
+ preferable for `asm' statements)
+
+ `R'
+ AIX TOC entry
+
+ `S'
+ Constant suitable as a 64-bit mask operand
+
+ `T'
+ Constant suitable as a 32-bit mask operand
+
+ `U'
+ System V Release 4 small data area reference
+
+_Intel 386--`i386.h'_
+
+ `q'
+ `a', `b', `c', or `d' register for the i386. For x86-64 it
+ is equivalent to `r' class. (for 8-bit instructions that do
+ not use upper halves)
+
+ `Q'
+ `a', `b', `c', or `d' register. (for 8-bit instructions, that
+ do use upper halves)
+
+ `R'
+ Legacy register--equivalent to `r' class in i386 mode. (for
+ non-8-bit registers used together with 8-bit upper halves in
+ a single instruction)
+
+ `A'
+ Specifies the `a' or `d' registers. This is primarily useful
+ for 64-bit integer values (when in 32-bit mode) intended to
+ be returned with the `d' register holding the most
+ significant bits and the `a' register holding the least
+ significant bits.
+
+ `f'
+ Floating point register
+
+ `t'
+ First (top of stack) floating point register
+
+ `u'
+ Second floating point register
+
+ `a'
+ `a' register
+
+ `b'
+ `b' register
+
+ `c'
+ `c' register
+
+ `d'
+ `d' register
+
+ `D'
+ `di' register
+
+ `S'
+ `si' register
+
+ `x'
+ `xmm' SSE register
+
+ `y'
+ MMX register
+
+ `I'
+ Constant in range 0 to 31 (for 32-bit shifts)
+
+ `J'
+ Constant in range 0 to 63 (for 64-bit shifts)
+
+ `K'
+ `0xff'
+
+ `L'
+ `0xffff'
+
+ `M'
+ 0, 1, 2, or 3 (shifts for `lea' instruction)
+
+ `N'
+ Constant in range 0 to 255 (for `out' instruction)
+
+ `Z'
+ Constant in range 0 to `0xffffffff' or symbolic reference
+ known to fit specified range. (for using immediates in zero
+ extending 32-bit to 64-bit x86-64 instructions)
+
+ `e'
+ Constant in range -2147483648 to 2147483647 or symbolic
+ reference known to fit specified range. (for using
+ immediates in 64-bit x86-64 instructions)
+
+ `G'
+ Standard 80387 floating point constant
+
+_Intel 960--`i960.h'_
+
+ `f'
+ Floating point register (`fp0' to `fp3')
+
+ `l'
+ Local register (`r0' to `r15')
+
+ `b'
+ Global register (`g0' to `g15')
+
+ `d'
+ Any local or global register
+
+ `I'
+ Integers from 0 to 31
+
+ `J'
+ 0
+
+ `K'
+ Integers from -31 to 0
+
+ `G'
+ Floating point 0
+
+ `H'
+ Floating point 1
+
+_MIPS--`mips.h'_
+
+ `d'
+ General-purpose integer register
+
+ `f'
+ Floating-point register (if available)
+
+ `h'
+ `Hi' register
+
+ `l'
+ `Lo' register
+
+ `x'
+ `Hi' or `Lo' register
+
+ `y'
+ General-purpose integer register
+
+ `z'
+ Floating-point status register
+
+ `I'
+ Signed 16-bit constant (for arithmetic instructions)
+
+ `J'
+ Zero
+
+ `K'
+ Zero-extended 16-bit constant (for logic instructions)
+
+ `L'
+ Constant with low 16 bits zero (can be loaded with `lui')
+
+ `M'
+ 32-bit constant which requires two instructions to load (a
+ constant which is not `I', `K', or `L')
+
+ `N'
+ Negative 16-bit constant
+
+ `O'
+ Exact power of two
+
+ `P'
+ Positive 16-bit constant
+
+ `G'
+ Floating point zero
+
+ `Q'
+ Memory reference that can be loaded with more than one
+ instruction (`m' is preferable for `asm' statements)
+
+ `R'
+ Memory reference that can be loaded with one instruction (`m'
+ is preferable for `asm' statements)
+
+ `S'
+ Memory reference in external OSF/rose PIC format (`m' is
+ preferable for `asm' statements)
+
+_Motorola 680x0--`m68k.h'_
+
+ `a'
+ Address register
+
+ `d'
+ Data register
+
+ `f'
+ 68881 floating-point register, if available
+
+ `x'
+ Sun FPA (floating-point) register, if available
+
+ `y'
+ First 16 Sun FPA registers, if available
+
+ `I'
+ Integer in the range 1 to 8
+
+ `J'
+ 16-bit signed number
+
+ `K'
+ Signed number whose magnitude is greater than 0x80
+
+ `L'
+ Integer in the range -8 to -1
+
+ `M'
+ Signed number whose magnitude is greater than 0x100
+
+ `G'
+ Floating point constant that is not a 68881 constant
+
+ `H'
+ Floating point constant that can be used by Sun FPA
+
+_Motorola 68HC11 & 68HC12 families--`m68hc11.h'_
+
+ `a'
+ Register 'a'
+
+ `b'
+ Register 'b'
+
+ `d'
+ Register 'd'
+
+ `q'
+ An 8-bit register
+
+ `t'
+ Temporary soft register _.tmp
+
+ `u'
+ A soft register _.d1 to _.d31
+
+ `w'
+ Stack pointer register
+
+ `x'
+ Register 'x'
+
+ `y'
+ Register 'y'
+
+ `z'
+ Pseudo register 'z' (replaced by 'x' or 'y' at the end)
+
+ `A'
+ An address register: x, y or z
+
+ `B'
+ An address register: x or y
+
+ `D'
+ Register pair (x:d) to form a 32-bit value
+
+ `L'
+ Constants in the range -65536 to 65535
+
+ `M'
+ Constants whose 16-bit low part is zero
+
+ `N'
+ Constant integer 1 or -1
+
+ `O'
+ Constant integer 16
+
+ `P'
+ Constants in the range -8 to 2
+
+
+_SPARC--`sparc.h'_
+
+ `f'
+ Floating-point register that can hold 32- or 64-bit values.
+
+ `e'
+ Floating-point register that can hold 64- or 128-bit values.
+
+ `I'
+ Signed 13-bit constant
+
+ `J'
+ Zero
+
+ `K'
+ 32-bit constant with the low 12 bits clear (a constant that
+ can be loaded with the `sethi' instruction)
+
+ `L'
+ A constant in the range supported by `movcc' instructions
+
+ `M'
+ A constant in the range supported by `movrcc' instructions
+
+ `N'
+ Same as `K', except that it verifies that bits that are not
+ in the lower 32-bit range are all zero. Must be used instead
+ of `K' for modes wider than `SImode'
+
+ `G'
+ Floating-point zero
+
+ `H'
+ Signed 13-bit constant, sign-extended to 32 or 64 bits
+
+ `Q'
+ Floating-point constant whose integral representation can be
+ moved into an integer register using a single sethi
+ instruction
+
+ `R'
+ Floating-point constant whose integral representation can be
+ moved into an integer register using a single mov instruction
+
+ `S'
+ Floating-point constant whose integral representation can be
+ moved into an integer register using a high/lo_sum
+ instruction sequence
+
+ `T'
+ Memory address aligned to an 8-byte boundary
+
+ `U'
+ Even register
+
+ `W'
+ Memory address for `e' constraint registers.
+
+
+_TMS320C3x/C4x--`c4x.h'_
+
+ `a'
+ Auxiliary (address) register (ar0-ar7)
+
+ `b'
+ Stack pointer register (sp)
+
+ `c'
+ Standard (32-bit) precision integer register
+
+ `f'
+ Extended (40-bit) precision register (r0-r11)
+
+ `k'
+ Block count register (bk)
+
+ `q'
+ Extended (40-bit) precision low register (r0-r7)
+
+ `t'
+ Extended (40-bit) precision register (r0-r1)
+
+ `u'
+ Extended (40-bit) precision register (r2-r3)
+
+ `v'
+ Repeat count register (rc)
+
+ `x'
+ Index register (ir0-ir1)
+
+ `y'
+ Status (condition code) register (st)
+
+ `z'
+ Data page register (dp)
+
+ `G'
+ Floating-point zero
+
+ `H'
+ Immediate 16-bit floating-point constant
+
+ `I'
+ Signed 16-bit constant
+
+ `J'
+ Signed 8-bit constant
+
+ `K'
+ Signed 5-bit constant
+
+ `L'
+ Unsigned 16-bit constant
+
+ `M'
+ Unsigned 8-bit constant
+
+ `N'
+ Ones complement of unsigned 16-bit constant
+
+ `O'
+ High 16-bit constant (32-bit constant with 16 LSBs zero)
+
+ `Q'
+ Indirect memory reference with signed 8-bit or index register
+ displacement
+
+ `R'
+ Indirect memory reference with unsigned 5-bit displacement
+
+ `S'
+ Indirect memory reference with 1 bit or index register
+ displacement
+
+ `T'
+ Direct memory reference
+
+ `U'
+ Symbolic address
+
+
+_S/390 and zSeries--`s390.h'_
+
+ `a'
+ Address register (general purpose register except r0)
+
+ `d'
+ Data register (arbitrary general purpose register)
+
+ `f'
+ Floating-point register
+
+ `I'
+ Unsigned 8-bit constant (0-255)
+
+ `J'
+ Unsigned 12-bit constant (0-4095)
+
+ `K'
+ Signed 16-bit constant (-32768-32767)
+
+ `L'
+ Unsigned 16-bit constant (0-65535)
+
+ `Q'
+ Memory reference without index register
+
+ `S'
+ Symbolic constant suitable for use with the `larl' instruction
+
+
+_Xstormy16--`stormy16.h'_
+
+ `a'
+ Register r0.
+
+ `b'
+ Register r1.
+
+ `c'
+ Register r2.
+
+ `d'
+ Register r8.
+
+ `e'
+ Registers r0 through r7.
+
+ `t'
+ Registers r0 and r1.
+
+ `y'
+ The carry register.
+
+ `z'
+ Registers r8 and r9.
+
+ `I'
+ A constant between 0 and 3 inclusive.
+
+ `J'
+ A constant that has exactly one bit set.
+
+ `K'
+ A constant that has exactly one bit clear.
+
+ `L'
+ A constant between 0 and 255 inclusive.
+
+ `M'
+ A constant between -255 and 0 inclusive.
+
+ `N'
+ A constant between -3 and 0 inclusive.
+
+ `O'
+ A constant between 1 and 4 inclusive.
+
+ `P'
+ A constant between -4 and -1 inclusive.
+
+ `Q'
+ A memory reference that is a stack push.
+
+ `R'
+ A memory reference that is a stack pop.
+
+ `S'
+ A memory reference that refers to an constant address of
+ known value.
+
+ `T'
+ The register indicated by Rx (not implemented yet).
+
+ `U'
+ A constant that is not between 2 and 15 inclusive.
+
+
+_Xtensa--`xtensa.h'_
+
+ `a'
+ General-purpose 32-bit register
+
+ `b'
+ One-bit boolean register
+
+ `A'
+ MAC16 40-bit accumulator register
+
+ `I'
+ Signed 12-bit integer constant, for use in MOVI instructions
+
+ `J'
+ Signed 8-bit integer constant, for use in ADDI instructions
+
+ `K'
+ Integer constant valid for BccI instructions
+
+ `L'
+ Unsigned constant valid for BccUI instructions
+
+
+
+\1f
+File: gcc.info, Node: Asm Labels, Next: Explicit Reg Vars, Prev: Constraints, Up: C Extensions
+
+5.37 Controlling Names Used in Assembler Code
+=============================================
+
+You can specify the name to be used in the assembler code for a C
+function or variable by writing the `asm' (or `__asm__') keyword after
+the declarator as follows:
+
+ int foo asm ("myfoo") = 2;
+
+This specifies that the name to be used for the variable `foo' in the
+assembler code should be `myfoo' rather than the usual `_foo'.
+
+ On systems where an underscore is normally prepended to the name of
+a C function or variable, this feature allows you to define names for
+the linker that do not start with an underscore.
+
+ It does not make sense to use this feature with a non-static local
+variable since such variables do not have assembler names. If you are
+trying to put the variable in a particular register, see *note Explicit
+Reg Vars::. GCC presently accepts such code with a warning, but will
+probably be changed to issue an error, rather than a warning, in the
+future.
+
+ You cannot use `asm' in this way in a function _definition_; but you
+can get the same effect by writing a declaration for the function
+before its definition and putting `asm' there, like this:
+
+ extern func () asm ("FUNC");
+
+ func (x, y)
+ int x, y;
+ ...
+
+ It is up to you to make sure that the assembler names you choose do
+not conflict with any other assembler symbols. Also, you must not use a
+register name; that would produce completely invalid assembler code.
+GCC does not as yet have the ability to store static variables in
+registers. Perhaps that will be added.
+
+\1f
+File: gcc.info, Node: Explicit Reg Vars, Next: Alternate Keywords, Prev: Asm Labels, Up: C Extensions
+
+5.38 Variables in Specified Registers
+=====================================
+
+GNU C allows you to put a few global variables into specified hardware
+registers. You can also specify the register in which an ordinary
+register variable should be allocated.
+
+ * Global register variables reserve registers throughout the program.
+ This may be useful in programs such as programming language
+ interpreters which have a couple of global variables that are
+ accessed very often.
+
+ * Local register variables in specific registers do not reserve the
+ registers. The compiler's data flow analysis is capable of
+ determining where the specified registers contain live values, and
+ where they are available for other uses. Stores into local
+ register variables may be deleted when they appear to be dead
+ according to dataflow analysis. References to local register
+ variables may be deleted or moved or simplified.
+
+ These local variables are sometimes convenient for use with the
+ extended `asm' feature (*note Extended Asm::), if you want to
+ write one output of the assembler instruction directly into a
+ particular register. (This will work provided the register you
+ specify fits the constraints specified for that operand in the
+ `asm'.)
+
+* Menu:
+
+* Global Reg Vars::
+* Local Reg Vars::
+
+\1f
+File: gcc.info, Node: Global Reg Vars, Next: Local Reg Vars, Up: Explicit Reg Vars
+
+5.38.1 Defining Global Register Variables
+-----------------------------------------
+
+You can define a global register variable in GNU C like this:
+
+ register int *foo asm ("a5");
+
+Here `a5' is the name of the register which should be used. Choose a
+register which is normally saved and restored by function calls on your
+machine, so that library routines will not clobber it.
+
+ Naturally the register name is cpu-dependent, so you would need to
+conditionalize your program according to cpu type. The register `a5'
+would be a good choice on a 68000 for a variable of pointer type. On
+machines with register windows, be sure to choose a "global" register
+that is not affected magically by the function call mechanism.
+
+ In addition, operating systems on one type of cpu may differ in how
+they name the registers; then you would need additional conditionals.
+For example, some 68000 operating systems call this register `%a5'.
+
+ Eventually there may be a way of asking the compiler to choose a
+register automatically, but first we need to figure out how it should
+choose and how to enable you to guide the choice. No solution is
+evident.
+
+ Defining a global register variable in a certain register reserves
+that register entirely for this use, at least within the current
+compilation. The register will not be allocated for any other purpose
+in the functions in the current compilation. The register will not be
+saved and restored by these functions. Stores into this register are
+never deleted even if they would appear to be dead, but references may
+be deleted or moved or simplified.
+
+ It is not safe to access the global register variables from signal
+handlers, or from more than one thread of control, because the system
+library routines may temporarily use the register for other things
+(unless you recompile them specially for the task at hand).
+
+ It is not safe for one function that uses a global register variable
+to call another such function `foo' by way of a third function `lose'
+that was compiled without knowledge of this variable (i.e. in a
+different source file in which the variable wasn't declared). This is
+because `lose' might save the register and put some other value there.
+For example, you can't expect a global register variable to be
+available in the comparison-function that you pass to `qsort', since
+`qsort' might have put something else in that register. (If you are
+prepared to recompile `qsort' with the same global register variable,
+you can solve this problem.)
+
+ If you want to recompile `qsort' or other source files which do not
+actually use your global register variable, so that they will not use
+that register for any other purpose, then it suffices to specify the
+compiler option `-ffixed-REG'. You need not actually add a global
+register declaration to their source code.
+
+ A function which can alter the value of a global register variable
+cannot safely be called from a function compiled without this variable,
+because it could clobber the value the caller expects to find there on
+return. Therefore, the function which is the entry point into the part
+of the program that uses the global register variable must explicitly
+save and restore the value which belongs to its caller.
+
+ On most machines, `longjmp' will restore to each global register
+variable the value it had at the time of the `setjmp'. On some
+machines, however, `longjmp' will not change the value of global
+register variables. To be portable, the function that called `setjmp'
+should make other arrangements to save the values of the global register
+variables, and to restore them in a `longjmp'. This way, the same
+thing will happen regardless of what `longjmp' does.
+
+ All global register variable declarations must precede all function
+definitions. If such a declaration could appear after function
+definitions, the declaration would be too late to prevent the register
+from being used for other purposes in the preceding functions.
+
+ Global register variables may not have initial values, because an
+executable file has no means to supply initial contents for a register.
+
+ On the Sparc, there are reports that g3 ... g7 are suitable
+registers, but certain library functions, such as `getwd', as well as
+the subroutines for division and remainder, modify g3 and g4. g1 and
+g2 are local temporaries.
+
+ On the 68000, a2 ... a5 should be suitable, as should d2 ... d7. Of
+course, it will not do to use more than a few of those.
+
+\1f
+File: gcc.info, Node: Local Reg Vars, Prev: Global Reg Vars, Up: Explicit Reg Vars
+
+5.38.2 Specifying Registers for Local Variables
+-----------------------------------------------
+
+You can define a local register variable with a specified register like
+this:
+
+ register int *foo asm ("a5");
+
+Here `a5' is the name of the register which should be used. Note that
+this is the same syntax used for defining global register variables,
+but for a local variable it would appear within a function.
+
+ Naturally the register name is cpu-dependent, but this is not a
+problem, since specific registers are most often useful with explicit
+assembler instructions (*note Extended Asm::). Both of these things
+generally require that you conditionalize your program according to cpu
+type.
+
+ In addition, operating systems on one type of cpu may differ in how
+they name the registers; then you would need additional conditionals.
+For example, some 68000 operating systems call this register `%a5'.
+
+ Defining such a register variable does not reserve the register; it
+remains available for other uses in places where flow control determines
+the variable's value is not live. However, these registers are made
+unavailable for use in the reload pass; excessive use of this feature
+leaves the compiler too few available registers to compile certain
+functions.
+
+ This option does not guarantee that GCC will generate code that has
+this variable in the register you specify at all times. You may not
+code an explicit reference to this register in an `asm' statement and
+assume it will always refer to this variable.
+
+ Stores into local register variables may be deleted when they appear
+to be dead according to dataflow analysis. References to local
+register variables may be deleted or moved or simplified.
+
+\1f
+File: gcc.info, Node: Alternate Keywords, Next: Incomplete Enums, Prev: Explicit Reg Vars, Up: C Extensions
+
+5.39 Alternate Keywords
+=======================
+
+The option `-traditional' disables certain keywords; `-ansi' and the
+various `-std' options disable certain others. This causes trouble
+when you want to use GNU C extensions, or ISO C features, in a
+general-purpose header file that should be usable by all programs,
+including ISO C programs and traditional ones. The keywords `asm',
+`typeof' and `inline' cannot be used since they won't work in a program
+compiled with `-ansi' (although `inline' can be used in a program
+compiled with `-std=c99'), while the keywords `const', `volatile',
+`signed', `typeof' and `inline' won't work in a program compiled with
+`-traditional'. The ISO C99 keyword `restrict' is only available when
+`-std=gnu99' (which will eventually be the default) or `-std=c99' (or
+the equivalent `-std=iso9899:1999') is used.
+
+ The way to solve these problems is to put `__' at the beginning and
+end of each problematical keyword. For example, use `__asm__' instead
+of `asm', `__const__' instead of `const', and `__inline__' instead of
+`inline'.
+
+ Other C compilers won't accept these alternative keywords; if you
+want to compile with another compiler, you can define the alternate
+keywords as macros to replace them with the customary keywords. It
+looks like this:
+
+ #ifndef __GNUC__
+ #define __asm__ asm
+ #endif
+
+ `-pedantic' and other options cause warnings for many GNU C
+extensions. You can prevent such warnings within one expression by
+writing `__extension__' before the expression. `__extension__' has no
+effect aside from this.
+
+\1f
+File: gcc.info, Node: Incomplete Enums, Next: Function Names, Prev: Alternate Keywords, Up: C Extensions
+
+5.40 Incomplete `enum' Types
+============================
+
+You can define an `enum' tag without specifying its possible values.
+This results in an incomplete type, much like what you get if you write
+`struct foo' without describing the elements. A later declaration
+which does specify the possible values completes the type.
+
+ You can't allocate variables or storage using the type while it is
+incomplete. However, you can work with pointers to that type.
+
+ This extension may not be very useful, but it makes the handling of
+`enum' more consistent with the way `struct' and `union' are handled.
+
+ This extension is not supported by GNU C++.
+
+\1f
+File: gcc.info, Node: Function Names, Next: Return Address, Prev: Incomplete Enums, Up: C Extensions
+
+5.41 Function Names as Strings
+==============================
+
+GCC predefines two magic identifiers to hold the name of the current
+function. The identifier `__FUNCTION__' holds the name of the function
+as it appears in the source. The identifier `__PRETTY_FUNCTION__'
+holds the name of the function pretty printed in a language specific
+fashion.
+
+ These names are always the same in a C function, but in a C++
+function they may be different. For example, this program:
+
+ extern "C" {
+ extern int printf (char *, ...);
+ }
+
+ class a {
+ public:
+ sub (int i)
+ {
+ printf ("__FUNCTION__ = %s\n", __FUNCTION__);
+ printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__);
+ }
+ };
+
+ int
+ main (void)
+ {
+ a ax;
+ ax.sub (0);
+ return 0;
+ }
+
+gives this output:
+
+ __FUNCTION__ = sub
+ __PRETTY_FUNCTION__ = int a::sub (int)
+
+ The compiler automagically replaces the identifiers with a string
+literal containing the appropriate name. Thus, they are neither
+preprocessor macros, like `__FILE__' and `__LINE__', nor variables.
+This means that they catenate with other string literals, and that they
+can be used to initialize char arrays. For example
+
+ char here[] = "Function " __FUNCTION__ " in " __FILE__;
+
+ On the other hand, `#ifdef __FUNCTION__' does not have any special
+meaning inside a function, since the preprocessor does not do anything
+special with the identifier `__FUNCTION__'.
+
+ Note that these semantics are deprecated, and that GCC 3.2 will
+handle `__FUNCTION__' and `__PRETTY_FUNCTION__' the same way as
+`__func__'. `__func__' is defined by the ISO standard C99:
+
+ The identifier `__func__' is implicitly declared by the translator
+ as if, immediately following the opening brace of each function
+ definition, the declaration
+ static const char __func__[] = "function-name";
+
+ appeared, where function-name is the name of the lexically-enclosing
+ function. This name is the unadorned name of the function.
+
+ By this definition, `__func__' is a variable, not a string literal.
+In particular, `__func__' does not catenate with other string literals.
+
+ In `C++', `__FUNCTION__' and `__PRETTY_FUNCTION__' are variables,
+declared in the same way as `__func__'.
+
+\1f
+File: gcc.info, Node: Return Address, Next: Vector Extensions, Prev: Function Names, Up: C Extensions
+
+5.42 Getting the Return or Frame Address of a Function
+======================================================
+
+These functions may be used to get information about the callers of a
+function.
+
+ -- Built-in Function: void * __builtin_return_address (unsigned int
+ LEVEL)
+ This function returns the return address of the current function,
+ or of one of its callers. The LEVEL argument is number of frames
+ to scan up the call stack. A value of `0' yields the return
+ address of the current function, a value of `1' yields the return
+ address of the caller of the current function, and so forth.
+
+ The LEVEL argument must be a constant integer.
+
+ On some machines it may be impossible to determine the return
+ address of any function other than the current one; in such cases,
+ or when the top of the stack has been reached, this function will
+ return `0' or a random value. In addition,
+ `__builtin_frame_address' may be used to determine if the top of
+ the stack has been reached.
+
+ This function should only be used with a nonzero argument for
+ debugging purposes.
+
+ -- Built-in Function: void * __builtin_frame_address (unsigned int
+ LEVEL)
+ This function is similar to `__builtin_return_address', but it
+ returns the address of the function frame rather than the return
+ address of the function. Calling `__builtin_frame_address' with a
+ value of `0' yields the frame address of the current function, a
+ value of `1' yields the frame address of the caller of the current
+ function, and so forth.
+
+ The frame is the area on the stack which holds local variables and
+ saved registers. The frame address is normally the address of the
+ first word pushed on to the stack by the function. However, the
+ exact definition depends upon the processor and the calling
+ convention. If the processor has a dedicated frame pointer
+ register, and the function has a frame, then
+ `__builtin_frame_address' will return the value of the frame
+ pointer register.
+
+ On some machines it may be impossible to determine the frame
+ address of any function other than the current one; in such cases,
+ or when the top of the stack has been reached, this function will
+ return `0' if the first frame pointer is properly initialized by
+ the startup code.
+
+ This function should only be used with a nonzero argument for
+ debugging purposes.
+
+\1f
+File: gcc.info, Node: Vector Extensions, Next: Other Builtins, Prev: Return Address, Up: C Extensions
+
+5.43 Using vector instructions through built-in functions
+=========================================================
+
+On some targets, the instruction set contains SIMD vector instructions
+that operate on multiple values contained in one large register at the
+same time. For example, on the i386 the MMX, 3Dnow! and SSE extensions
+can be used this way.
+
+ The first step in using these extensions is to provide the necessary
+data types. This should be done using an appropriate `typedef':
+
+ typedef int v4si __attribute__ ((mode(V4SI)));
+
+ The base type `int' is effectively ignored by the compiler, the
+actual properties of the new type `v4si' are defined by the
+`__attribute__'. It defines the machine mode to be used; for vector
+types these have the form `VNB'; N should be the number of elements in
+the vector, and B should be the base mode of the individual elements.
+The following can be used as base modes:
+
+`QI'
+ An integer that is as wide as the smallest addressable unit,
+ usually 8 bits.
+
+`HI'
+ An integer, twice as wide as a QI mode integer, usually 16 bits.
+
+`SI'
+ An integer, four times as wide as a QI mode integer, usually 32
+ bits.
+
+`DI'
+ An integer, eight times as wide as a QI mode integer, usually 64
+ bits.
+
+`SF'
+ A floating point value, as wide as a SI mode integer, usually 32
+ bits.
+
+`DF'
+ A floating point value, as wide as a DI mode integer, usually 64
+ bits.
+
+ Not all base types or combinations are always valid; which modes can
+be used is determined by the target machine. For example, if
+targetting the i386 MMX extensions, only `V8QI', `V4HI' and `V2SI' are
+allowed modes.
+
+ There are no `V1xx' vector modes - they would be identical to the
+corresponding base mode.
+
+ There is no distinction between signed and unsigned vector modes.
+This distinction is made by the operations that perform on the vectors,
+not by the data type.
+
+ The types defined in this manner are somewhat special, they cannot be
+used with most normal C operations (i.e., a vector addition can _not_
+be represented by a normal addition of two vector type variables). You
+can declare only variables and use them in function calls and returns,
+as well as in assignments and some casts. It is possible to cast from
+one vector type to another, provided they are of the same size (in
+fact, you can also cast vectors to and from other datatypes of the same
+size).
+
+ A port that supports vector operations provides a set of built-in
+functions that can be used to operate on vectors. For example, a
+function to add two vectors and multiply the result by a third could
+look like this:
+
+ v4si f (v4si a, v4si b, v4si c)
+ {
+ v4si tmp = __builtin_addv4si (a, b);
+ return __builtin_mulv4si (tmp, c);
+ }
projects / msp430-gcc.git / blobdiff