This is
/es/build/frv-050408/1/frv550-uclinux/X-tools-build/gcc/doc/gcc.info,
produced by makeinfo version 4.0 from
/es/build/frv-050408/1/frv550-uclinux/sources/tools-src/gcc/doc/gcc.texi.

START-INFO-DIR-ENTRY
* usegcc: (usegcc).			Using the GNU C compiler.
END-INFO-DIR-ENTRY

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

`-funaligned-pointers'
     Assume that all pointers contain unaligned addresses.  On machines
     where unaligned memory accesses trap, this will result in much
     larger and slower code for all pointer dereferences, but the code
     will work even if addresses are unaligned.

`-funaligned-struct-hack'
     Always access structure fields using loads and stores of the
     declared size.  This option is useful for code that derefences
     pointers to unaligned structures, but only accesses fields that
     are themselves aligned.  Without this option, gcc may try to use a
     memory access larger than the field.  This might give an unaligned
     access fault on some hardware.

     This option makes some invalid code work at the expense of
     disabling some optimizations.  It is strongly recommended that
     this option not be used.

`-foptimize-comparisons'
     Optimize multiple comparisons better within `&&' and `||'
     expressions.  This is an experimental option.  In some cases it can
     result in worse code.  It depends on many factors.  Now it is known
     only that the optimization works well for PPC740 and PPC750.  This
     option switches on the following transformations:
            (a != 0 || b != 0)  =>  ((a | b) != 0)
            (a == 0 && b == 0)  =>  ((a | b) == 0)
            (a != b || c != d)  =>  (((a ^ b) | (c ^ d)) != 0)
            (a == b && c == d)  =>  (((a ^ b) | (c ^ d)) == 0)
            (a != 0 && b != 0)  =>  (((a | -a) & (b | -b)) < 0)
            (a != b && c != d)  =>  x = a ^ b; y = c ^ d; (((x | -x) & (y | -y)) < 0)
            (a < 0 || b < 0)    =>  ((a | b) < 0)
            (a < 0 && b < 0)    =>  ((a & b) < 0)
            (a >= 0 || b >= 0)  =>  ((a & b) >= 0)
            (a >= 0 && b >= 0)  =>  ((a | b) >= 0)
            (a < 0 || b >= 0)   =>  ((a | ~b) < 0)
            (a < 0 && b >= 0)   =>  ((a & ~b) < 0)
            (a >= 0 || b < 0)   =>  ((~a | b) < 0)
            (a >= 0 && b < 0)   =>  ((~a & b) < 0)
            (a != 0 && b < 0)   =>  (((a | -a) & b) < 0)
            (a != 0 && b >= 0)  =>  (((a | -a) & ~b) < 0)
            (a < 0 && b != 0)   =>  (((b | -b) & a) < 0)
            (a >= 0 && b != 0)  =>  (((b | -b) & ~a) < 0)


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.



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

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


File: gcc.info,  Node: Integers implementation,  Next: Floating point implementation,  Prev: Characters implementation,  Up: C Implementation

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

     GCC supports only two's complement integer types, and all bit
     patterns are ordinary values.

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


File: gcc.info,  Node: Floating point implementation,  Next: Arrays and pointers implementation,  Prev: Integers implementation,  Up: C Implementation

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



File: gcc.info,  Node: Arrays and pointers implementation,  Next: Hints implementation,  Prev: Floating point implementation,  Up: C Implementation

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.


File: gcc.info,  Node: Hints implementation,  Next: Structures unions enumerations and bit-fields implementation,  Prev: Arrays and pointers implementation,  Up: C Implementation

Hints
=====

   * `The extent to which suggestions made by using the `register'
     storage-class specifier are effective (6.7.1).'

     The `register' specifier affects code generation only in these
     ways:

        * When used as part of the register variable extension, see
          *Note Explicit Reg Vars::.

        * When `-O0' is in use, the compiler allocates distinct stack
          memory for all variables that do not have the `register'
          storage-class specifier; if `register' is specified, the
          variable may have a shorter lifespan than the code would
          indicate and may never be placed in memory.

        * On some rare x86 targets, `setjmp' doesn't save the registers
          in all circumstances.  In those cases, GCC doesn't allocate
          any variables in registers unless they are marked `register'.


   * `The extent to which suggestions made by using the inline function
     specifier are effective (6.7.4).'

     GCC will not inline any functions if the `-fno-inline' option is
     used or if `-O0' is used.  Otherwise, GCC may still be unable to
     inline a function for many reasons; the `-Winline' option may be
     used to determine if a function has not been inlined and why not.



File: gcc.info,  Node: Structures unions enumerations and bit-fields implementation,  Next: Qualifiers implementation,  Prev: Hints implementation,  Up: C Implementation

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



File: gcc.info,  Node: Qualifiers implementation,  Next: Preprocessing directives implementation,  Prev: Structures unions enumerations and bit-fields implementation,  Up: C Implementation

Qualifiers
==========

   * `What constitutes an access to an object that has
     volatile-qualified type (6.7.3).'


