* doc/implement-c.texi: New file.

	* doc/extend.texi (C Implementation): Move to there.
	* doc/gcc.texi: Include implement-c.texi.
	* Makefile.in (TEXI_GCC_FILES): Add implement-c.texi.


git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@85058 138bc75d-0d04-0410-961f-82ee72b054a4

1 files changed, 403 insertions, 0 deletions

diff --git a/gcc/doc/implement-c.texi b/gcc/doc/implement-c.texi
new file mode 100644
index 00000000000..f179877df66
--- /dev/null
+++ b/gcc/doc/implement-c.texi
@@ -0,0 +1,403 @@
+@c Copyright (C) 2001,2002,2003,2004 Free Software Foundation, Inc.
+@c This is part of the GCC manual.
+@c For copying conditions, see the file gcc.texi.
+
+@node C Implementation
+@chapter C Implementation-defined behavior
+@cindex implementation-defined behavior, C language
+
+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::
+@end menu
+
+@node Translation implementation
+@section Translation
+
+@itemize @bullet
+@item
+@cite{How a diagnostic is identified (3.10, 5.1.1.3).}
+
+Diagnostics consist of all the output sent to stderr by GCC.
+
+@item
+@cite{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).}
+@end itemize
+
+@node Environment implementation
+@section Environment
+
+The behavior of these points are dependent on the implementation
+of the C library, and are not defined by GCC itself.
+
+@node Identifiers implementation
+@section Identifiers
+
+@itemize @bullet
+@item
+@cite{Which additional multibyte characters may appear in identifiers
+and their correspondence to universal character names (6.4.2).}
+
+@item
+@cite{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.
+
+@end itemize
+
+@node Characters implementation
+@section Characters
+
+@itemize @bullet
+@item
+@cite{The number of bits in a byte (3.6).}
+
+@item
+@cite{The values of the members of the execution character set (5.2.1).}
+
+@item
+@cite{The unique value of the member of the execution character set produced
+for each of the standard alphabetic escape sequences (5.2.2).}
+
+@item
+@cite{The value of a @code{char} object into which has been stored any
+character other than a member of the basic execution character set (6.2.5).}
+
+@item
+@cite{Which of @code{signed char} or @code{unsigned char} has the same range,
+representation, and behavior as ``plain'' @code{char} (6.2.5, 6.3.1.1).}
+
+@item
+@cite{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).}
+
+@item
+@cite{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).}
+
+@item
+@cite{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).}
+
+@item
+@cite{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).}
+
+@item
+@cite{The current locale used to convert a wide string literal into
+corresponding wide character codes (6.4.5).}
+
+@item
+@cite{The value of a string literal containing a multibyte character or escape
+sequence not represented in the execution character set (6.4.5).}
+@end itemize
+
+@node Integers implementation
+@section Integers
+
+@itemize @bullet
+@item
+@cite{Any extended integer types that exist in the implementation (6.2.5).}
+
+@item
+@cite{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.
+
+@item
+@cite{The rank of any extended integer type relative to another extended
+integer type with the same precision (6.3.1.1).}
+
+@item
+@cite{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).}
+
+@item
+@cite{The results of some bitwise operations on signed integers (6.5).}
+@end itemize
+
+@node Floating point implementation
+@section Floating point
+
+@itemize @bullet
+@item
+@cite{The accuracy of the floating-point operations and of the library
+functions in @code{<math.h>} and @code{<complex.h>} that return floating-point
+results (5.2.4.2.2).}
+
+@item
+@cite{The rounding behaviors characterized by non-standard values
+of @code{FLT_ROUNDS} @gol
+(5.2.4.2.2).}
+
+@item
+@cite{The evaluation methods characterized by non-standard negative
+values of @code{FLT_EVAL_METHOD} (5.2.4.2.2).}
+
+@item
+@cite{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).}
+
+@item
+@cite{The direction of rounding when a floating-point number is
+converted to a narrower floating-point number (6.3.1.5).}
+
+@item
+@cite{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).}
+
+@item
+@cite{Whether and how floating expressions are contracted when not
+disallowed by the @code{FP_CONTRACT} pragma (6.5).}
+
+@item
+@cite{The default state for the @code{FENV_ACCESS} pragma (7.6.1).}
+
+@item
+@cite{Additional floating-point exceptions, rounding modes, environments,
+and classifications, and their macro names (7.6, 7.12).}
+
+@item
+@cite{The default state for the @code{FP_CONTRACT} pragma (7.12.2).}
+
+@item
+@cite{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).}
+
+@item
+@cite{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).}
+
+@end itemize
+
+@node Arrays and pointers implementation
+@section Arrays and pointers
+
+@itemize @bullet
+@item
+@cite{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@footnote{Future versions of GCC may zero-extend, or use
+a target-defined @code{ptr_extend} pattern.  Do not rely on sign extension.}
+if the pointer representation is smaller than the integer type, otherwise
+the bits are unchanged.
+@c ??? We've always claimed that pointers were unsigned entities.
+@c Shouldn't we therefore be doing zero-extension?  If so, the bug
+@c is in convert_to_integer, where we call type_for_size and request
+@c a signed integral type.  On the other hand, it might be most useful
+@c for the target if we extend according to POINTERS_EXTEND_UNSIGNED.
+
+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.
+
+@item
+@cite{The size of the result of subtracting two pointers to elements
+of the same array (6.5.6).}
+
+@end itemize
+
+@node Hints implementation
+@section Hints
+
+@itemize @bullet
+@item
+@cite{The extent to which suggestions made by using the @code{register}
+storage-class specifier are effective (6.7.1).}
+
+The @code{register} specifier affects code generation only in these ways:
+
+@itemize @bullet
+@item
+When used as part of the register variable extension, see
+@ref{Explicit Reg Vars}.
+
+@item
+When @option{-O0} is in use, the compiler allocates distinct stack
+memory for all variables that do not have the @code{register}
+storage-class specifier; if @code{register} is specified, the variable
+may have a shorter lifespan than the code would indicate and may never
+be placed in memory.
+
+@item
+On some rare x86 targets, @code{setjmp} doesn't save the registers in
+all circumstances.  In those cases, GCC doesn't allocate any variables
+in registers unless they are marked @code{register}.
+
+@end itemize
+
+@item
+@cite{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 @option{-fno-inline} option is
+used or if @option{-O0} is used.  Otherwise, GCC may still be unable to
+inline a function for many reasons; the @option{-Winline} option may be
+used to determine if a function has not been inlined and why not.
+
+@end itemize
+
+@node Structures unions enumerations and bit-fields implementation
+@section Structures, unions, enumerations, and bit-fields
+
+@itemize @bullet
+@item
+@cite{Whether a ``plain'' int bit-field is treated as a @code{signed int}
+bit-field or as an @code{unsigned int} bit-field (6.7.2, 6.7.2.1).}
+
+@item
+@cite{Allowable bit-field types other than @code{_Bool}, @code{signed int},
+and @code{unsigned int} (6.7.2.1).}
+
+@item
+@cite{Whether a bit-field can straddle a storage-unit boundary (6.7.2.1).}
+
+@item
+@cite{The order of allocation of bit-fields within a unit (6.7.2.1).}
+
+@item
+@cite{The alignment of non-bit-field members of structures (6.7.2.1).}
+
+@item
+@cite{The integer type compatible with each enumerated type (6.7.2.2).}
+
+@end itemize
+
+@node Qualifiers implementation
+@section Qualifiers
+
+@itemize @bullet
+@item
+@cite{What constitutes an access to an object that has volatile-qualified
+type (6.7.3).}
+
+@end itemize
+
+@node Preprocessing directives implementation
+@section Preprocessing directives
+
+@itemize @bullet
+@item
+@cite{How sequences in both forms of header names are mapped to headers
+or external source file names (6.4.7).}
+
+@item
+@cite{Whether the value of a character constant in a constant expression
+that controls conditional inclusion matches the value of the same character
+constant in the execution character set (6.10.1).}
+
+@item
+@cite{Whether the value of a single-character character constant in a
+constant expression that controls conditional inclusion may have a
+negative value (6.10.1).}
+
+@item
+@cite{The places that are searched for an included @samp{<>} delimited
+header, and how the places are specified or the header is
+identified (6.10.2).}
+
+@item
+@cite{How the named source file is searched for in an included @samp{""}
+delimited header (6.10.2).}
+
+@item
+@cite{The method by which preprocessing tokens (possibly resulting from
+macro expansion) in a @code{#include} directive are combined into a header
+name (6.10.2).}
+
+@item
+@cite{The nesting limit for @code{#include} processing (6.10.2).}
+
+GCC imposes a limit of 200 nested @code{#include}s.
+
+@item
+@cite{Whether the @samp{#} operator inserts a @samp{\} character before
+the @samp{\} character that begins a universal character name in a
+character constant or string literal (6.10.3.2).}
+
+@item
+@cite{The behavior on each recognized non-@code{STDC #pragma}
+directive (6.10.6).}
+
+@item
+@cite{The definitions for @code{__DATE__} and @code{__TIME__} when
+respectively, the date and time of translation are not available (6.10.8).}
+
+If the date and time are not available, @code{__DATE__} expands to
+@code{@w{"??? ?? ????"}} and @code{__TIME__} expands to
+@code{"??:??:??"}.
+
+@end itemize
+
+@node Library functions implementation
+@section Library functions
+
+The behavior of these points are dependent on the implementation
+of the C library, and are not defined by GCC itself.
+
+@node Architecture implementation
+@section Architecture
+
+@itemize @bullet
+@item
+@cite{The values or expressions assigned to the macros specified in the
+headers @code{<float.h>}, @code{<limits.h>}, and @code{<stdint.h>}
+(5.2.4.2, 7.18.2, 7.18.3).}
+
+@item
+@cite{The number, order, and encoding of bytes in any object
+(when not explicitly specified in this International Standard) (6.2.6.1).}
+
+@item
+@cite{The value of the result of the sizeof operator (6.5.3.4).}
+
+@end itemize
+
+@node Locale-specific behavior implementation
+@section Locale-specific behavior
+
+The behavior of these points are dependent on the implementation
+of the C library, and are not defined by GCC itself.