This is ../../gcc-3.4/gcc/doc/gcc.info, produced by makeinfo version
4.2 from ../../gcc-3.4/gcc/doc/gcc.texi.

Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "GNU General Public License" and "Funding Free
Software", the Front-Cover texts being (a) (see below), and with the
Back-Cover Texts being (b) (see below).  A copy of the license is
included in the section entitled "GNU Free Documentation License".

   (a) The FSF's Front-Cover Text is:

   A GNU Manual

   (b) The FSF's Back-Cover Text is:

   You have freedom to copy and modify this GNU Manual, like GNU
software.  Copies published by the Free Software Foundation raise
funds for GNU development.
INFO-DIR-SECTION Programming
START-INFO-DIR-ENTRY
* gcc: (gcc).                  The GNU Compiler Collection.
END-INFO-DIR-ENTRY
   This file documents the use of the GNU compilers.

   Published by the Free Software Foundation
59 Temple Place - Suite 330
Boston, MA 02111-1307 USA

File: gcc.info,  Node: FRV Options,  Prev: Xtensa Options,  Up: Submodel Options

FRV Options
-----------

`-mgpr-32'
     Only use the first 32 general purpose registers.

`-mgpr-64'
     Use all 64 general purpose registers.

`-mfpr-32'
     Use only the first 32 floating point registers.

`-mfpr-64'
     Use all 64 floating point registers

`-mhard-float'
     Use hardware instructions for floating point operations.

`-msoft-float'
     Use library routines for floating point operations.

`-malloc-cc'
     Dynamically allocate condition code registers.

`-mfixed-cc'
     Do not try to dynamically allocate condition code registers, only
     use `icc0' and `fcc0'.

`-mdword'
     Change ABI to use double word insns.

`-mno-dword'
     Do not use double word instructions.

`-mdouble'
     Use floating point double instructions.

`-mno-double'
     Do not use floating point double instructions.

`-mmedia'
     Use media instructions.

`-mno-media'
     Do not use media instructions.

`-mmuladd'
     Use multiply and add/subtract instructions.

`-mno-muladd'
     Do not use multiply and add/subtract instructions.

`-mlibrary-pic'
     Enable PIC support for building libraries

`-macc-4'
     Use only the first four media accumulator registers.

`-macc-8'
     Use all eight media accumulator registers.

`-mpack'
     Pack VLIW instructions.

`-mno-pack'
     Do not pack VLIW instructions.

`-mno-eflags'
     Do not mark ABI switches in e_flags.

`-mcond-move'
     Enable the use of conditional-move instructions (default).

     This switch is mainly for debugging the compiler and will likely
     be removed in a future version.

`-mno-cond-move'
     Disable the use of conditional-move instructions.

     This switch is mainly for debugging the compiler and will likely
     be removed in a future version.

`-mscc'
     Enable the use of conditional set instructions (default).

     This switch is mainly for debugging the compiler and will likely
     be removed in a future version.

`-mno-scc'
     Disable the use of conditional set instructions.

     This switch is mainly for debugging the compiler and will likely
     be removed in a future version.

`-mcond-exec'
     Enable the use of conditional execution (default).

     This switch is mainly for debugging the compiler and will likely
     be removed in a future version.

`-mno-cond-exec'
     Disable the use of conditional execution.

     This switch is mainly for debugging the compiler and will likely
     be removed in a future version.

`-mvliw-branch'
     Run a pass to pack branches into VLIW instructions (default).

     This switch is mainly for debugging the compiler and will likely
     be removed in a future version.

`-mno-vliw-branch'
     Do not run a pass to pack branches into VLIW instructions.

     This switch is mainly for debugging the compiler and will likely
     be removed in a future version.

`-mmulti-cond-exec'
     Enable optimization of `&&' and `||' in conditional execution
     (default).

     This switch is mainly for debugging the compiler and will likely
     be removed in a future version.

`-mno-multi-cond-exec'
     Disable optimization of `&&' and `||' in conditional execution.

     This switch is mainly for debugging the compiler and will likely
     be removed in a future version.

`-mnested-cond-exec'
     Enable nested conditional execution optimizations (default).

     This switch is mainly for debugging the compiler and will likely
     be removed in a future version.

`-mno-nested-cond-exec'
     Disable nested conditional execution optimizations.

     This switch is mainly for debugging the compiler and will likely
     be removed in a future version.

`-mtomcat-stats'
     Cause gas to print out tomcat statistics.

`-mcpu=CPU'
     Select the processor type for which to generate code.  Possible
     values are `simple', `tomcat', `fr500', `fr400', `fr300', `frv'.


File: gcc.info,  Node: Xtensa Options,  Next: FRV Options,  Prev: Xstormy16 Options,  Up: Submodel Options

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.

`-mconst16'
`-mno-const16'
     Enable or disable use of `CONST16' instructions for loading
     constant values.  The `CONST16' instruction is currently not a
     standard option from Tensilica.  When enabled, `CONST16'
     instructions are always used in place of the standard `L32R'
     instructions.  The use of `CONST16' is enabled by default only if
     the `L32R' instruction is not available.

`-mabs'
`-mno-abs'
     Enable or disable use of the Xtensa `ABS' instruction for absolute
     value operations.

`-maddx'
`-mno-addx'
     Enable or disable use of the Xtensa `ADDX' and `SUBX' 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.

`-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.


File: gcc.info,  Node: Code Gen Options,  Next: Environment Variables,  Prev: Submodel Options,  Up: Invoking GCC

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.

`-fbounds-check'
     For front-ends that support it, generate additional code to check
     that indices used to access arrays are within the declared range.
     This is currently only supported by the Java and Fortran 77
     front-ends, where this option defaults to true and false
     respectively.

`-ftrapv'
     This option generates traps for signed overflow on addition,
     subtraction, multiplication operations.

`-fwrapv'
     This option instructs the compiler to assume that signed arithmetic
     overflow of addition, subtraction and multiplication wraps around
     using twos-complement representation.  This flag enables some
     optimizations and disables other.  This option is enabled by
     default for the Java front-end, as required by the Java language
     specification.

`-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.

`-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.

`-fpie'
`-fPIE'
     These options are similar to `-fpic' and `-fPIC', but generated
     position independent code can be only linked into executables.
     Usually these options are used when `-pie' GCC option will be used
     during linking.

`-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 suboptimal.  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.

`-ftls-model=MODEL'
     Alter the thread-local storage model to be used (*note
     Thread-Local::).  The MODEL argument should be one of
     `global-dynamic', `local-dynamic', `initial-exec' or `local-exec'.

     The default without `-fpic' is `initial-exec'; with `-fpic' the
     default is `global-dynamic'.


File: gcc.info,  Node: Environment Variables,  Next: Precompiled Headers,  Prev: Code Gen Options,  Up: Invoking GCC

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/' 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'
     (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.  This 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.

     In all these variables, an empty element instructs the compiler to
     search its current working directory.  Empty elements can appear
     at the beginning or end of a path.  For instance, if the value of
     `CPATH' is `:/special/include', that has the same effect as
     `-I. -I/special/include'.

`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 `DEPENDENCIES_OUTPUT' (see above),
     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::.


File: gcc.info,  Node: Precompiled Headers,  Next: Running Protoize,  Prev: Environment Variables,  Up: Invoking GCC

Using Precompiled Headers
=========================

   Often large projects have many header files that are included in
every source file.  The time the compiler takes to process these header
files over and over again can account for nearly all of the time
required to build the project.  To make builds faster, GCC allows users
to `precompile' a header file; then, if builds can use the precompiled
header file they will be much faster.

   To create a precompiled header file, simply compile it as you would
any other file, if necessary using the `-x' option to make the driver
treat it as a C or C++ header file.  You will probably want to use a
tool like `make' to keep the precompiled header up-to-date when the
headers it contains change.

   A precompiled header file will be searched for when `#include' is
seen in the compilation.  As it searches for the included file (*note
Search Path: (cpp.info)Search Path.) the compiler looks for a
precompiled header in each directory just before it looks for the
include file in that directory.  The name searched for is the name
specified in the `#include' with `.gch' appended.  If the precompiled
header file can't be used, it is ignored.

   For instance, if you have `#include "all.h"', and you have
`all.h.gch' in the same directory as `all.h', then the precompiled
header file will be used if possible, and the original header will be
used otherwise.

   Alternatively, you might decide to put the precompiled header file
in a directory and use `-I' to ensure that directory is searched before
(or instead of) the directory containing the original header.  Then, if
you want to check that the precompiled header file is always used, you
can put a file of the same name as the original header in this
directory containing an `#error' command.

   This also works with `-include'.  So yet another way to use
precompiled headers, good for projects not designed with precompiled
header files in mind, is to simply take most of the header files used by
a project, include them from another header file, precompile that header
file, and `-include' the precompiled header.  If the header files have
guards against multiple inclusion, they will be skipped because they've
already been included (in the precompiled header).

   If you need to precompile the same header file for different
languages, targets, or compiler options, you can instead make a
_directory_ named like `all.h.gch', and put each precompiled header in
the directory.  (It doesn't matter what you call the files in the
directory, every precompiled header in the directory will be
considered.)  The first precompiled header encountered in the directory
that is valid for this compilation will be used; they're searched in no
particular order.

   There are many other possibilities, limited only by your imagination,
good sense, and the constraints of your build system.

   A precompiled header file can be used only when these conditions
apply:

   * Only one precompiled header can be used in a particular
     compilation.

   * A precompiled header can't be used once the first C token is seen.
     You can have preprocessor directives before a precompiled header;
     you can even include a precompiled header from inside another
     header, so long as there are no C tokens before the `#include'.

   * The precompiled header file must be produced for the same language
     as the current compilation.  You can't use a C precompiled header
     for a C++ compilation.

   * The precompiled header file must be produced by the same compiler
     version and configuration as the current compilation is using.
     The easiest way to guarantee this is to use the same compiler
     binary for creating and using precompiled headers.

   * Any macros defined before the precompiled header (including with
     `-D') must either be defined in the same way as when the
     precompiled header was generated, or must not affect the
     precompiled header, which usually means that the they don't appear
     in the precompiled header at all.

   * Certain command-line options must be defined in the same way as
     when the precompiled header was generated.  At present, it's not
     clear which options are safe to change and which are not; the
     safest choice is to use exactly the same options when generating
     and using the precompiled header.

   For all of these but the last, the compiler will automatically ignore
the precompiled header if the conditions aren't met.  For the last item,
some option changes will cause the precompiled header to be rejected,
but not all incompatible option combinations have yet been found.  If
you find a new incompatible combination, please consider filing a bug
report, see *Note Bugs::.


File: gcc.info,  Node: Running Protoize,  Prev: Precompiled Headers,  Up: Invoking GCC

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.


File: gcc.info,  Node: C Implementation,  Next: C Extensions,  Prev: Invoking GCC,  Up: Top

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::


File: gcc.info,  Node: Translation implementation,  Next: Environment implementation,  Up: C Implementation

Translation
===========

   * `How a diagnostic is identified (3.10, 5.1.1.3).'

     Diagnostics consist of all the output sent to stderr by GCC.

   * `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).'


File: gcc.info,  Node: Environment implementation,  Next: Identifiers implementation,  Prev: Translation implementation,  Up: C Implementation

Environment
===========

   The behavior of these points are dependent on the implementation of
the C library, and are not defined by GCC itself.


File: gcc.info,  Node: Identifiers implementation,  Next: Characters implementation,  Prev: Environment implementation,  Up: C Implementation

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).'

     For internal names, all characters are significant.  For external
     names, the number of significant characters are defined by the
     linker; for almost all targets, all characters are significant.


