This is the mail archive of the gcc-patches@gcc.gnu.org mailing list for the GCC project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Patch to docs of Cimplementation-defined behavior


This patch fills out the documentation of C implementation-defined
behavior, also adding C90 references where appropriate (though not
adding points differently worded in C90 if they are adequately covered
under the listed C99 points).  Many points are listed as determined by
the system ABI and we do need better documentation pointing to the
ABIs for specific systems and saying that this is the ABI used on
certain named systems.  Some of these points could also be addressed
with a -print-implementation-defined option that lists various
properties for the currently used combination of command-line options.

It passes "make info" and "make dvi".  Applied to mainline.

-- 
Joseph S. Myers               http://www.srcf.ucam.org/~jsm28/gcc/
    jsm@polyomino.org.uk (personal mail)
    jsm28@gcc.gnu.org (Bugzilla assignments and CCs)

2004-07-29  Joseph S. Myers  <jsm@polyomino.org.uk>

	* doc/implement-c.texi: Add C90 subclause references.  Point to
	preprocessor documentation instead of duplicating it.  Add points
	only present in C90.  Fill in documentation for all points.

--- implement-c.texi.orig	2004-07-22 20:05:43.000000000 +0000
+++ implement-c.texi	2004-07-29 17:08:00.000000000 +0000
@@ -9,7 +9,19 @@
 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.
+along with the section numbers from the ISO/IEC 9899:1990 and ISO/IEC
+9899:1999 standards.  Some areas are only implementation-defined in
+one version of the standard.
+
+Some choices depend on the externally determined ABI for the platform
+(including standard character encodings) which GCC follows; these are
+listed as ``determined by ABI'' below.  @xref{Compatibility, , Binary
+Compatibility}, and @uref{http://gcc.gnu.org/readings.html}.  Some
+choices are documented in the preprocessor manual.
+@xref{Implementation-defined behavior, , Implementation-defined
+behavior, cpp, The C Preprocessor}.  Some choices are made by the
+library and operating system (or other environment when compiling for
+a freestanding environment); refer to their documentation for details.
 
 @menu
 * Translation implementation::
@@ -22,6 +34,8 @@
 * Hints implementation::
 * Structures unions enumerations and bit-fields implementation::
 * Qualifiers implementation::
+* Declarators implementation::
+* Statements implementation::
 * Preprocessing directives implementation::
 * Library functions implementation::
 * Architecture implementation::
@@ -33,38 +47,63 @@
 
 @itemize @bullet
 @item
-@cite{How a diagnostic is identified (3.10, 5.1.1.3).}
+@cite{How a diagnostic is identified (C90 3.7, C99 3.10, C90 and C99 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).}
+phase 3 (C90 and C99 5.1.1.2).}
+
+@xref{Implementation-defined behavior, , Implementation-defined
+behavior, cpp, The C Preprocessor}.
+
 @end itemize
 
 @node Environment implementation
 @section Environment
 
-The behavior of these points are dependent on the implementation
+The behavior of most of these points are dependent on the implementation
 of the C library, and are not defined by GCC itself.
 
+@itemize @bullet
+@item
+@cite{The mapping between physical source file multibyte characters
+and the source character set in translation phase 1 (C90 and C99 5.1.1.2).}
+
+@xref{Implementation-defined behavior, , Implementation-defined
+behavior, cpp, The C Preprocessor}.
+
+@end itemize
+
 @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).}
+and their correspondence to universal character names (C99 6.4.2).}
+
+@xref{Implementation-defined behavior, , Implementation-defined
+behavior, cpp, The C Preprocessor}.
 
 @item
 @cite{The number of significant initial characters in an identifier
-(5.2.4.1, 6.4.2).}
+(C90 6.1.2, C90 and C99 5.2.4.1, C99 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.
 
+@item
+@cite{Whether case distinctions are significant in an identifier with
+external linkage (C90 6.1.2).}
+
+This is a property of the linker.  C99 requires that case distinctions
+are always significant in identifiers with external linkage and
+systems without this property are not supported by GCC@.
+
 @end itemize
 
 @node Characters implementation
@@ -72,50 +111,86 @@
 
 @itemize @bullet
 @item
-@cite{The number of bits in a byte (3.6).}
+@cite{The number of bits in a byte (C90 3.4, C99 3.6).}
+
+Determined by ABI@.
 
 @item
-@cite{The values of the members of the execution character set (5.2.1).}
+@cite{The values of the members of the execution character set (C90
+and C99 5.2.1).}
+
+Determined by ABI@.
 
 @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).}
+for each of the standard alphabetic escape sequences (C90 and C99 5.2.2).}
+
+Determined by ABI@.
 
 @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).}
+character other than a member of the basic execution character set
+(C90 6.1.2.5, C99 6.2.5).}
+
+Determined by ABI@.
 
 @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).}
+@cite{Which of @code{signed char} or @code{unsigned char} has the same
+range, representation, and behavior as ``plain'' @code{char} (C90
+6.1.2.5, C90 6.2.1.1, C99 6.2.5, C99 6.3.1.1).}
+
+@opindex fsigned-char
+@opindex funsigned-char
+Determined by ABI@.  The options @option{-funsigned-char} and
+@option{-fsigned-char} change the default.  @xref{C Dialect Options, ,
+Options Controlling C Dialect}.
 
 @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).}
+set (C90 6.1.3.4, C99 6.4.4.4, C90 and C99 5.1.1.2).}
+
+Determined by ABI@.
 
 @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).}
+to a single-byte execution character (C90 6.1.3.4, C99 6.4.4.4).}
+
+@xref{Implementation-defined behavior, , Implementation-defined
+behavior, cpp, The C Preprocessor}.
 
 @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).}
+sequence not represented in the extended execution character set (C90
+6.1.3.4, C99 6.4.4.4).}
+
+@xref{Implementation-defined behavior, , Implementation-defined
+behavior, cpp, The C Preprocessor}.
 
 @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).}
+execution character set into a corresponding wide character code (C90
+6.1.3.4, C99 6.4.4.4).}
+
+@xref{Implementation-defined behavior, , Implementation-defined
+behavior, cpp, The C Preprocessor}.
 
 @item
 @cite{The current locale used to convert a wide string literal into
-corresponding wide character codes (6.4.5).}
+corresponding wide character codes (C90 6.1.4, C99 6.4.5).}
+
+@xref{Implementation-defined behavior, , Implementation-defined
+behavior, cpp, The C Preprocessor}.
 
 @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).}
+sequence not represented in the execution character set (C90 6.1.4, C99 6.4.5).}
+
+@xref{Implementation-defined behavior, , Implementation-defined
+behavior, cpp, The C Preprocessor}.
 @end itemize
 
 @node Integers implementation
@@ -123,27 +198,58 @@
 
 @itemize @bullet
 @item
-@cite{Any extended integer types that exist in the implementation (6.2.5).}
+@cite{Any extended integer types that exist in the implementation (C99 6.2.5).}
+
+GCC does not support any extended integer types.
+@c The __mode__ attribute might create types of precisions not
+@c otherwise supported, but the syntax isn't right for use everywhere
+@c the standard type names might be used.  Predefined typedefs should
+@c be used if any extended integer types are to be defined.  The
+@c __int128_t and __uint128_t typedefs are not extended integer types
+@c as they are generally longer than the ABI-specified intmax_t.
 
 @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).}
+is a trap representation or an ordinary value (C99 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).}
+integer type with the same precision (C99 6.3.1.1).}
+
+GCC does not support any extended integer types.
+@c If it did, there would only be one of each precision and signedness.
 
 @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).}
+that type (C90 6.2.1.2, C99 6.3.1.3).}
+
+For conversion to a type of width @math{N}, the value is reduced
+modulo @math{2^N} to be within range of the type; no signal is raised.
 
 @item
-@cite{The results of some bitwise operations on signed integers (6.5).}
+@cite{The results of some bitwise operations on signed integers (C90
+6.3, C99 6.5).}
+
+Bitwise operators act on the representation of the value including
+both the sign and value bits, where the sign bit is considered
+immediately above the highest-value value bit.  Signed @samp{>>} acts
+on negative numbers by sign extension.
+
+GCC does not use the latitude given in C99 only to treat certain
+aspects of signed @samp{<<} as undefined, but this is subject to
+change.
+
+@item
+@cite{The sign of the remainder on integer division (C90 6.3.5).}
+
+GCC always follows the C99 requirement that the result of division is
+truncated towards zero.
+
 @end itemize
 
 @node Floating point implementation
@@ -153,54 +259,88 @@
 @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).}
+results (C90 and C99 5.2.4.2.2).}
+
+The accuracy is unknown.
 
 @item
 @cite{The rounding behaviors characterized by non-standard values
 of @code{FLT_ROUNDS} @gol
-(5.2.4.2.2).}
+(C90 and C99 5.2.4.2.2).}
+
+GCC does not use such values.
 
 @item
 @cite{The evaluation methods characterized by non-standard negative
-values of @code{FLT_EVAL_METHOD} (5.2.4.2.2).}
+values of @code{FLT_EVAL_METHOD} (C99 5.2.4.2.2).}
+
+GCC does not use such values.
 
 @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).}
+value (C90 6.2.1.3, C99 6.3.1.4).}
+
+C99 Annex F is followed.
 
 @item
 @cite{The direction of rounding when a floating-point number is
-converted to a narrower floating-point number (6.3.1.5).}
+converted to a narrower floating-point number (C90 6.2.1.4, C99
+6.3.1.5).}
+
+C99 Annex F is followed.
 
 @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).}
+value is chosen for certain floating constants (C90 6.1.3.1, C99
+6.4.4.2).}
+
+C99 Annex F is followed.
 
 @item
 @cite{Whether and how floating expressions are contracted when not
-disallowed by the @code{FP_CONTRACT} pragma (6.5).}
+disallowed by the @code{FP_CONTRACT} pragma (C99 6.5).}
+
+Expressions are currently only contracted if
+@option{-funsafe-math-optimizations} or @option{-ffast-math} are used.
+This is subject to change.
 
 @item
-@cite{The default state for the @code{FENV_ACCESS} pragma (7.6.1).}
+@cite{The default state for the @code{FENV_ACCESS} pragma (C99 7.6.1).}
+
+This pragma is not implemented, but the default is to ``off'' unless
+@option{-frounding-math} is used in which case it is ``on''.
 
 @item
 @cite{Additional floating-point exceptions, rounding modes, environments,
-and classifications, and their macro names (7.6, 7.12).}
+and classifications, and their macro names (C99 7.6, C99 7.12).}
+
+This is dependent on the implementation of the C library, and is not
+defined by GCC itself.
 
 @item
-@cite{The default state for the @code{FP_CONTRACT} pragma (7.12.2).}
+@cite{The default state for the @code{FP_CONTRACT} pragma (C99 7.12.2).}
+
+This pragma is not implemented.  Expressions are currently only
+contracted if @option{-funsafe-math-optimizations} or
+@option{-ffast-math} are used.  This is subject to change.
 
 @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).}
+in an IEC 60559 conformant implementation (C99 F.9).}
+
+This is dependent on the implementation of the C library, and is not
+defined by GCC itself.
 
 @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).}
+IEC 60559 conformant implementation (C99 F.9).}
+
+This is dependent on the implementation of the C library, and is not
+defined by GCC itself.
 
 @end itemize
 
@@ -210,7 +350,7 @@
 @itemize @bullet
 @item
 @cite{The result of converting a pointer to an integer or
-vice versa (6.3.2.3).}
+vice versa (C90 6.3.4, C99 6.3.2.3).}
 
 A cast from pointer to integer discards most-significant bits if the
 pointer representation is larger than the integer type,
@@ -232,11 +372,15 @@
 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.
+avoid the undefined behavior of pointer arithmetic as proscribed in
+C99 6.5.6/8.
 
 @item
 @cite{The size of the result of subtracting two pointers to elements
-of the same array (6.5.6).}
+of the same array (C90 6.3.6, C99 6.5.6).}
+
+The value is as specified in the standard and the type is determined
+by the ABI@.
 
 @end itemize
 
@@ -246,7 +390,7 @@
 @itemize @bullet
 @item
 @cite{The extent to which suggestions made by using the @code{register}
-storage-class specifier are effective (6.7.1).}
+storage-class specifier are effective (C90 6.5.1, C99 6.7.1).}
 
 The @code{register} specifier affects code generation only in these ways:
 
@@ -271,7 +415,7 @@
 
 @item
 @cite{The extent to which suggestions made by using the inline function
-specifier are effective (6.7.4).}
+specifier are effective (C99 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
@@ -285,24 +429,69 @@
 
 @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).}
+@cite{A member of a union object is accessed using a member of a
+different type (C90 6.3.2.3).}
+
+The relevant bytes of the representation of the object are treated as
+an object of the type used for the access.  This may be a trap
+representation.
+
+@item
+@cite{Whether a ``plain'' @code{int} bit-field is treated as a
+@code{signed int} bit-field or as an @code{unsigned int} bit-field
+(C90 6.5.2, C90 6.5.2.1, C99 6.7.2, C99 6.7.2.1).}
+
+@opindex funsigned-bitfields
+By default it is treated as @code{signed int} but this may be changed
+by the @option{-funsigned-bitfields} option.
 
 @item
 @cite{Allowable bit-field types other than @code{_Bool}, @code{signed int},
-and @code{unsigned int} (6.7.2.1).}
+and @code{unsigned int} (C99 6.7.2.1).}
+
+No other types are permitted in strictly conforming mode.
+@c Would it be better to restrict the pedwarn for other types to C90
+@c mode and document the other types for C99 mode?
 
 @item
-@cite{Whether a bit-field can straddle a storage-unit boundary (6.7.2.1).}
+@cite{Whether a bit-field can straddle a storage-unit boundary (C90
+6.5.2.1, C99 6.7.2.1).}
+
+Determined by ABI@.
 
 @item
-@cite{The order of allocation of bit-fields within a unit (6.7.2.1).}
+@cite{The order of allocation of bit-fields within a unit (C90
+6.5.2.1, C99 6.7.2.1).}
+
+Determined by ABI@.
 
 @item
-@cite{The alignment of non-bit-field members of structures (6.7.2.1).}
+@cite{The alignment of non-bit-field members of structures (C90
+6.5.2.1, C99 6.7.2.1).}
+
+Determined by ABI@.
 
 @item
-@cite{The integer type compatible with each enumerated type (6.7.2.2).}
+@cite{The integer type compatible with each enumerated type (C90
+6.5.2.2, C99 6.7.2.2).}
+
+@opindex fshort-enums
+Normally, the type is @code{unsigned int} if there are no negative
+values in the enumeration, otherwise @code{int}.  If
+@option{-fshort-enums} is specified, then if there are negative values
+it is the first of @code{signed char}, @code{short} and @code{int}
+that can represent all the values, otherwise it is the first of
+@code{unsigned char}, @code{unsigned short} and @code{unsigned int}
+that can represent all the values.
+@c On a few unusual targets with 64-bit int, this doesn't agree with
+@c the code and one of the types accessed via mode attributes (which
+@c are not currently considered extended integer types) may be used.
+@c If these types are made extended integer types, it would still be
+@c the case that -fshort-enums stops the implementation from
+@c conforming to C90 on those targets.
+
+On some targets, @option{-fshort-enums} is the default; this is
+determined by the ABI@.
 
 @end itemize
 
@@ -312,72 +501,113 @@
 @itemize @bullet
 @item
 @cite{What constitutes an access to an object that has volatile-qualified
-type (6.7.3).}
+type (C90 6.5.3, C99 6.7.3).}
+
+@xref{Volatiles, , When is a Volatile Object Accessed?}.
+
+@end itemize
+
+@node Declarators implementation
+@section Declarators
+
+@itemize @bullet
+@item
+@cite{The maximum number of declarators that may modify an arithmetic,
+structure or union type (C90 6.5.4).}
+
+GCC is only limited by available memory.
+
+@end itemize
+
+@node Statements implementation
+@section Statements
+
+@itemize @bullet
+@item
+@cite{The maximum number of @code{case} values in a @code{switch}
+statement (C90 6.6.4.2).}
+
+GCC is only limited by available memory.
 
 @end itemize
 
 @node Preprocessing directives implementation
 @section Preprocessing directives
 
+@xref{Implementation-defined behavior, , Implementation-defined
+behavior, cpp, The C Preprocessor}, for details of these aspects of
+implementation-defined behavior.
+
 @itemize @bullet
 @item
 @cite{How sequences in both forms of header names are mapped to headers
-or external source file names (6.4.7).}
+or external source file names (C90 6.1.7, C99 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).}
+constant in the execution character set (C90 6.8.1, C99 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).}
+negative value (C90 6.8.1, C99 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).}
+identified (C90 6.8.2, C99 6.10.2).}
 
 @item
 @cite{How the named source file is searched for in an included @samp{""}
-delimited header (6.10.2).}
+delimited header (C90 6.8.2, C99 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).}
+name (C90 6.8.2, C99 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.
+@cite{The nesting limit for @code{#include} processing (C90 6.8.2, C99
+6.10.2).}
 
 @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).}
+character constant or string literal (C99 6.10.3.2).}
 
 @item
 @cite{The behavior on each recognized non-@code{STDC #pragma}
-directive (6.10.6).}
+directive (C90 6.8.6, C99 6.10.6).}
+
+@xref{Pragmas, , Pragmas, cpp, The C Preprocessor}, for details of
+pragmas accepted by GCC on all targets.  @xref{Pragmas, , Pragmas
+Accepted by GCC}, for details of target-specific pragmas.
 
 @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{"??:??:??"}.
+respectively, the date and time of translation are not available (C90
+6.8.8, C99 6.10.8).}
 
 @end itemize
 
 @node Library functions implementation
 @section Library functions
 
-The behavior of these points are dependent on the implementation
+The behavior of most of these points are dependent on the implementation
 of the C library, and are not defined by GCC itself.
 
+@itemize @bullet
+@item
+@cite{The null pointer constant to which the macro @code{NULL} expands
+(C90 7.1.6, C99 7.17).}
+
+In @code{<stddef.h>}, @code{NULL} expands to @code{((void *)0)}.  GCC
+does not provide the other headers which define @code{NULL} and some
+library implementations may use other definitions in those headers.
+
+@end itemize
+
 @node Architecture implementation
 @section Architecture
 
@@ -385,14 +615,21 @@
 @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).}
+(C90 and C99 5.2.4.2, C99 7.18.2, C99 7.18.3).}
+
+Determined by ABI@.
 
 @item
 @cite{The number, order, and encoding of bytes in any object
-(when not explicitly specified in this International Standard) (6.2.6.1).}
+(when not explicitly specified in this International Standard) (C99 6.2.6.1).}
+
+Determined by ABI@.
 
 @item
-@cite{The value of the result of the sizeof operator (6.5.3.4).}
+@cite{The value of the result of the @code{sizeof} operator (C90
+6.3.3.4, C99 6.5.3.4).}
+
+Determined by ABI@.
 
 @end itemize
 


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]