1@c Copyright (C) 2001,2002,2003,2004 Free Software Foundation, Inc. 2@c This is part of the GCC manual. 3@c For copying conditions, see the file gcc.texi. 4 5@node C Implementation 6@chapter C Implementation-defined behavior 7@cindex implementation-defined behavior, C language 8 9A conforming implementation of ISO C is required to document its 10choice of behavior in each of the areas that are designated 11``implementation defined''. The following lists all such areas, 12along with the section numbers from the ISO/IEC 9899:1990 and ISO/IEC 139899:1999 standards. Some areas are only implementation-defined in 14one version of the standard. 15 16Some choices depend on the externally determined ABI for the platform 17(including standard character encodings) which GCC follows; these are 18listed as ``determined by ABI'' below. @xref{Compatibility, , Binary 19Compatibility}, and @uref{http://gcc.gnu.org/readings.html}. Some 20choices are documented in the preprocessor manual. 21@xref{Implementation-defined behavior, , Implementation-defined 22behavior, cpp, The C Preprocessor}. Some choices are made by the 23library and operating system (or other environment when compiling for 24a freestanding environment); refer to their documentation for details. 25 26@menu 27* Translation implementation:: 28* Environment implementation:: 29* Identifiers implementation:: 30* Characters implementation:: 31* Integers implementation:: 32* Floating point implementation:: 33* Arrays and pointers implementation:: 34* Hints implementation:: 35* Structures unions enumerations and bit-fields implementation:: 36* Qualifiers implementation:: 37* Declarators implementation:: 38* Statements implementation:: 39* Preprocessing directives implementation:: 40* Library functions implementation:: 41* Architecture implementation:: 42* Locale-specific behavior implementation:: 43@end menu 44 45@node Translation implementation 46@section Translation 47 48@itemize @bullet 49@item 50@cite{How a diagnostic is identified (C90 3.7, C99 3.10, C90 and C99 5.1.1.3).} 51 52Diagnostics consist of all the output sent to stderr by GCC@. 53 54@item 55@cite{Whether each nonempty sequence of white-space characters other than 56new-line is retained or replaced by one space character in translation 57phase 3 (C90 and C99 5.1.1.2).} 58 59@xref{Implementation-defined behavior, , Implementation-defined 60behavior, cpp, The C Preprocessor}. 61 62@end itemize 63 64@node Environment implementation 65@section Environment 66 67The behavior of most of these points are dependent on the implementation 68of the C library, and are not defined by GCC itself. 69 70@itemize @bullet 71@item 72@cite{The mapping between physical source file multibyte characters 73and the source character set in translation phase 1 (C90 and C99 5.1.1.2).} 74 75@xref{Implementation-defined behavior, , Implementation-defined 76behavior, cpp, The C Preprocessor}. 77 78@end itemize 79 80@node Identifiers implementation 81@section Identifiers 82 83@itemize @bullet 84@item 85@cite{Which additional multibyte characters may appear in identifiers 86and their correspondence to universal character names (C99 6.4.2).} 87 88@xref{Implementation-defined behavior, , Implementation-defined 89behavior, cpp, The C Preprocessor}. 90 91@item 92@cite{The number of significant initial characters in an identifier 93(C90 6.1.2, C90 and C99 5.2.4.1, C99 6.4.2).} 94 95For internal names, all characters are significant. For external names, 96the number of significant characters are defined by the linker; for 97almost all targets, all characters are significant. 98 99@item 100@cite{Whether case distinctions are significant in an identifier with 101external linkage (C90 6.1.2).} 102 103This is a property of the linker. C99 requires that case distinctions 104are always significant in identifiers with external linkage and 105systems without this property are not supported by GCC@. 106 107@end itemize 108 109@node Characters implementation 110@section Characters 111 112@itemize @bullet 113@item 114@cite{The number of bits in a byte (C90 3.4, C99 3.6).} 115 116Determined by ABI@. 117 118@item 119@cite{The values of the members of the execution character set (C90 120and C99 5.2.1).} 121 122Determined by ABI@. 123 124@item 125@cite{The unique value of the member of the execution character set produced 126for each of the standard alphabetic escape sequences (C90 and C99 5.2.2).} 127 128Determined by ABI@. 129 130@item 131@cite{The value of a @code{char} object into which has been stored any 132character other than a member of the basic execution character set 133(C90 6.1.2.5, C99 6.2.5).} 134 135Determined by ABI@. 136 137@item 138@cite{Which of @code{signed char} or @code{unsigned char} has the same 139range, representation, and behavior as ``plain'' @code{char} (C90 1406.1.2.5, C90 6.2.1.1, C99 6.2.5, C99 6.3.1.1).} 141 142@opindex fsigned-char 143@opindex funsigned-char 144Determined by ABI@. The options @option{-funsigned-char} and 145@option{-fsigned-char} change the default. @xref{C Dialect Options, , 146Options Controlling C Dialect}. 147 148@item 149@cite{The mapping of members of the source character set (in character 150constants and string literals) to members of the execution character 151set (C90 6.1.3.4, C99 6.4.4.4, C90 and C99 5.1.1.2).} 152 153Determined by ABI@. 154 155@item 156@cite{The value of an integer character constant containing more than one 157character or containing a character or escape sequence that does not map 158to a single-byte execution character (C90 6.1.3.4, C99 6.4.4.4).} 159 160@xref{Implementation-defined behavior, , Implementation-defined 161behavior, cpp, The C Preprocessor}. 162 163@item 164@cite{The value of a wide character constant containing more than one 165multibyte character, or containing a multibyte character or escape 166sequence not represented in the extended execution character set (C90 1676.1.3.4, C99 6.4.4.4).} 168 169@xref{Implementation-defined behavior, , Implementation-defined 170behavior, cpp, The C Preprocessor}. 171 172@item 173@cite{The current locale used to convert a wide character constant consisting 174of a single multibyte character that maps to a member of the extended 175execution character set into a corresponding wide character code (C90 1766.1.3.4, C99 6.4.4.4).} 177 178@xref{Implementation-defined behavior, , Implementation-defined 179behavior, cpp, The C Preprocessor}. 180 181@item 182@cite{The current locale used to convert a wide string literal into 183corresponding wide character codes (C90 6.1.4, C99 6.4.5).} 184 185@xref{Implementation-defined behavior, , Implementation-defined 186behavior, cpp, The C Preprocessor}. 187 188@item 189@cite{The value of a string literal containing a multibyte character or escape 190sequence not represented in the execution character set (C90 6.1.4, C99 6.4.5).} 191 192@xref{Implementation-defined behavior, , Implementation-defined 193behavior, cpp, The C Preprocessor}. 194@end itemize 195 196@node Integers implementation 197@section Integers 198 199@itemize @bullet 200@item 201@cite{Any extended integer types that exist in the implementation (C99 6.2.5).} 202 203GCC does not support any extended integer types. 204@c The __mode__ attribute might create types of precisions not 205@c otherwise supported, but the syntax isn't right for use everywhere 206@c the standard type names might be used. Predefined typedefs should 207@c be used if any extended integer types are to be defined. The 208@c __int128_t and __uint128_t typedefs are not extended integer types 209@c as they are generally longer than the ABI-specified intmax_t. 210 211@item 212@cite{Whether signed integer types are represented using sign and magnitude, 213two's complement, or one's complement, and whether the extraordinary value 214is a trap representation or an ordinary value (C99 6.2.6.2).} 215 216GCC supports only two's complement integer types, and all bit patterns 217are ordinary values. 218 219@item 220@cite{The rank of any extended integer type relative to another extended 221integer type with the same precision (C99 6.3.1.1).} 222 223GCC does not support any extended integer types. 224@c If it did, there would only be one of each precision and signedness. 225 226@item 227@cite{The result of, or the signal raised by, converting an integer to a 228signed integer type when the value cannot be represented in an object of 229that type (C90 6.2.1.2, C99 6.3.1.3).} 230 231For conversion to a type of width @math{N}, the value is reduced 232modulo @math{2^N} to be within range of the type; no signal is raised. 233 234@item 235@cite{The results of some bitwise operations on signed integers (C90 2366.3, C99 6.5).} 237 238Bitwise operators act on the representation of the value including 239both the sign and value bits, where the sign bit is considered 240immediately above the highest-value value bit. Signed @samp{>>} acts 241on negative numbers by sign extension. 242 243GCC does not use the latitude given in C99 only to treat certain 244aspects of signed @samp{<<} as undefined, but this is subject to 245change. 246 247@item 248@cite{The sign of the remainder on integer division (C90 6.3.5).} 249 250GCC always follows the C99 requirement that the result of division is 251truncated towards zero. 252 253@end itemize 254 255@node Floating point implementation 256@section Floating point 257 258@itemize @bullet 259@item 260@cite{The accuracy of the floating-point operations and of the library 261functions in @code{<math.h>} and @code{<complex.h>} that return floating-point 262results (C90 and C99 5.2.4.2.2).} 263 264The accuracy is unknown. 265 266@item 267@cite{The rounding behaviors characterized by non-standard values 268of @code{FLT_ROUNDS} @gol 269(C90 and C99 5.2.4.2.2).} 270 271GCC does not use such values. 272 273@item 274@cite{The evaluation methods characterized by non-standard negative 275values of @code{FLT_EVAL_METHOD} (C99 5.2.4.2.2).} 276 277GCC does not use such values. 278 279@item 280@cite{The direction of rounding when an integer is converted to a 281floating-point number that cannot exactly represent the original 282value (C90 6.2.1.3, C99 6.3.1.4).} 283 284C99 Annex F is followed. 285 286@item 287@cite{The direction of rounding when a floating-point number is 288converted to a narrower floating-point number (C90 6.2.1.4, C99 2896.3.1.5).} 290 291C99 Annex F is followed. 292 293@item 294@cite{How the nearest representable value or the larger or smaller 295representable value immediately adjacent to the nearest representable 296value is chosen for certain floating constants (C90 6.1.3.1, C99 2976.4.4.2).} 298 299C99 Annex F is followed. 300 301@item 302@cite{Whether and how floating expressions are contracted when not 303disallowed by the @code{FP_CONTRACT} pragma (C99 6.5).} 304 305Expressions are currently only contracted if 306@option{-funsafe-math-optimizations} or @option{-ffast-math} are used. 307This is subject to change. 308 309@item 310@cite{The default state for the @code{FENV_ACCESS} pragma (C99 7.6.1).} 311 312This pragma is not implemented, but the default is to ``off'' unless 313@option{-frounding-math} is used in which case it is ``on''. 314 315@item 316@cite{Additional floating-point exceptions, rounding modes, environments, 317and classifications, and their macro names (C99 7.6, C99 7.12).} 318 319This is dependent on the implementation of the C library, and is not 320defined by GCC itself. 321 322@item 323@cite{The default state for the @code{FP_CONTRACT} pragma (C99 7.12.2).} 324 325This pragma is not implemented. Expressions are currently only 326contracted if @option{-funsafe-math-optimizations} or 327@option{-ffast-math} are used. This is subject to change. 328 329@item 330@cite{Whether the ``inexact'' floating-point exception can be raised 331when the rounded result actually does equal the mathematical result 332in an IEC 60559 conformant implementation (C99 F.9).} 333 334This is dependent on the implementation of the C library, and is not 335defined by GCC itself. 336 337@item 338@cite{Whether the ``underflow'' (and ``inexact'') floating-point 339exception can be raised when a result is tiny but not inexact in an 340IEC 60559 conformant implementation (C99 F.9).} 341 342This is dependent on the implementation of the C library, and is not 343defined by GCC itself. 344 345@end itemize 346 347@node Arrays and pointers implementation 348@section Arrays and pointers 349 350@itemize @bullet 351@item 352@cite{The result of converting a pointer to an integer or 353vice versa (C90 6.3.4, C99 6.3.2.3).} 354 355A cast from pointer to integer discards most-significant bits if the 356pointer representation is larger than the integer type, 357sign-extends@footnote{Future versions of GCC may zero-extend, or use 358a target-defined @code{ptr_extend} pattern. Do not rely on sign extension.} 359if the pointer representation is smaller than the integer type, otherwise 360the bits are unchanged. 361@c ??? We've always claimed that pointers were unsigned entities. 362@c Shouldn't we therefore be doing zero-extension? If so, the bug 363@c is in convert_to_integer, where we call type_for_size and request 364@c a signed integral type. On the other hand, it might be most useful 365@c for the target if we extend according to POINTERS_EXTEND_UNSIGNED. 366 367A cast from integer to pointer discards most-significant bits if the 368pointer representation is smaller than the integer type, extends according 369to the signedness of the integer type if the pointer representation 370is larger than the integer type, otherwise the bits are unchanged. 371 372When casting from pointer to integer and back again, the resulting 373pointer must reference the same object as the original pointer, otherwise 374the behavior is undefined. That is, one may not use integer arithmetic to 375avoid the undefined behavior of pointer arithmetic as proscribed in 376C99 6.5.6/8. 377 378@item 379@cite{The size of the result of subtracting two pointers to elements 380of the same array (C90 6.3.6, C99 6.5.6).} 381 382The value is as specified in the standard and the type is determined 383by the ABI@. 384 385@end itemize 386 387@node Hints implementation 388@section Hints 389 390@itemize @bullet 391@item 392@cite{The extent to which suggestions made by using the @code{register} 393storage-class specifier are effective (C90 6.5.1, C99 6.7.1).} 394 395The @code{register} specifier affects code generation only in these ways: 396 397@itemize @bullet 398@item 399When used as part of the register variable extension, see 400@ref{Explicit Reg Vars}. 401 402@item 403When @option{-O0} is in use, the compiler allocates distinct stack 404memory for all variables that do not have the @code{register} 405storage-class specifier; if @code{register} is specified, the variable 406may have a shorter lifespan than the code would indicate and may never 407be placed in memory. 408 409@item 410On some rare x86 targets, @code{setjmp} doesn't save the registers in 411all circumstances. In those cases, GCC doesn't allocate any variables 412in registers unless they are marked @code{register}. 413 414@end itemize 415 416@item 417@cite{The extent to which suggestions made by using the inline function 418specifier are effective (C99 6.7.4).} 419 420GCC will not inline any functions if the @option{-fno-inline} option is 421used or if @option{-O0} is used. Otherwise, GCC may still be unable to 422inline a function for many reasons; the @option{-Winline} option may be 423used to determine if a function has not been inlined and why not. 424 425@end itemize 426 427@node Structures unions enumerations and bit-fields implementation 428@section Structures, unions, enumerations, and bit-fields 429 430@itemize @bullet 431@item 432@cite{A member of a union object is accessed using a member of a 433different type (C90 6.3.2.3).} 434 435The relevant bytes of the representation of the object are treated as 436an object of the type used for the access. This may be a trap 437representation. 438 439@item 440@cite{Whether a ``plain'' @code{int} bit-field is treated as a 441@code{signed int} bit-field or as an @code{unsigned int} bit-field 442(C90 6.5.2, C90 6.5.2.1, C99 6.7.2, C99 6.7.2.1).} 443 444@opindex funsigned-bitfields 445By default it is treated as @code{signed int} but this may be changed 446by the @option{-funsigned-bitfields} option. 447 448@item 449@cite{Allowable bit-field types other than @code{_Bool}, @code{signed int}, 450and @code{unsigned int} (C99 6.7.2.1).} 451 452No other types are permitted in strictly conforming mode. 453@c Would it be better to restrict the pedwarn for other types to C90 454@c mode and document the other types for C99 mode? 455 456@item 457@cite{Whether a bit-field can straddle a storage-unit boundary (C90 4586.5.2.1, C99 6.7.2.1).} 459 460Determined by ABI@. 461 462@item 463@cite{The order of allocation of bit-fields within a unit (C90 4646.5.2.1, C99 6.7.2.1).} 465 466Determined by ABI@. 467 468@item 469@cite{The alignment of non-bit-field members of structures (C90 4706.5.2.1, C99 6.7.2.1).} 471 472Determined by ABI@. 473 474@item 475@cite{The integer type compatible with each enumerated type (C90 4766.5.2.2, C99 6.7.2.2).} 477 478@opindex fshort-enums 479Normally, the type is @code{unsigned int} if there are no negative 480values in the enumeration, otherwise @code{int}. If 481@option{-fshort-enums} is specified, then if there are negative values 482it is the first of @code{signed char}, @code{short} and @code{int} 483that can represent all the values, otherwise it is the first of 484@code{unsigned char}, @code{unsigned short} and @code{unsigned int} 485that can represent all the values. 486@c On a few unusual targets with 64-bit int, this doesn't agree with 487@c the code and one of the types accessed via mode attributes (which 488@c are not currently considered extended integer types) may be used. 489@c If these types are made extended integer types, it would still be 490@c the case that -fshort-enums stops the implementation from 491@c conforming to C90 on those targets. 492 493On some targets, @option{-fshort-enums} is the default; this is 494determined by the ABI@. 495 496@end itemize 497 498@node Qualifiers implementation 499@section Qualifiers 500 501@itemize @bullet 502@item 503@cite{What constitutes an access to an object that has volatile-qualified 504type (C90 6.5.3, C99 6.7.3).} 505 506Such an object is normally accessed by pointers and used for accessing 507hardware. In most expressions, it is intuitively obvious what is a read 508and what is a write. For example 509 510@smallexample 511volatile int *dst = @var{somevalue}; 512volatile int *src = @var{someothervalue}; 513*dst = *src; 514@end smallexample 515 516@noindent 517will cause a read of the volatile object pointed to by @var{src} and store the 518value into the volatile object pointed to by @var{dst}. There is no 519guarantee that these reads and writes are atomic, especially for objects 520larger than @code{int}. 521 522However, if the volatile storage is not being modified, and the value of 523the volatile storage is not used, then the situation is less obvious. 524For example 525 526@smallexample 527volatile int *src = @var{somevalue}; 528*src; 529@end smallexample 530 531According to the C standard, such an expression is an rvalue whose type 532is the unqualified version of its original type, i.e. @code{int}. Whether 533GCC interprets this as a read of the volatile object being pointed to or 534only as a request to evaluate the expression for its side-effects depends 535on this type. 536 537If it is a scalar type, or on most targets an aggregate type whose only 538member object is of a scalar type, or a union type whose member objects 539are of scalar types, the expression is interpreted by GCC as a read of 540the volatile object; in the other cases, the expression is only evaluated 541for its side-effects. 542 543@end itemize 544 545@node Declarators implementation 546@section Declarators 547 548@itemize @bullet 549@item 550@cite{The maximum number of declarators that may modify an arithmetic, 551structure or union type (C90 6.5.4).} 552 553GCC is only limited by available memory. 554 555@end itemize 556 557@node Statements implementation 558@section Statements 559 560@itemize @bullet 561@item 562@cite{The maximum number of @code{case} values in a @code{switch} 563statement (C90 6.6.4.2).} 564 565GCC is only limited by available memory. 566 567@end itemize 568 569@node Preprocessing directives implementation 570@section Preprocessing directives 571 572@xref{Implementation-defined behavior, , Implementation-defined 573behavior, cpp, The C Preprocessor}, for details of these aspects of 574implementation-defined behavior. 575 576@itemize @bullet 577@item 578@cite{How sequences in both forms of header names are mapped to headers 579or external source file names (C90 6.1.7, C99 6.4.7).} 580 581@item 582@cite{Whether the value of a character constant in a constant expression 583that controls conditional inclusion matches the value of the same character 584constant in the execution character set (C90 6.8.1, C99 6.10.1).} 585 586@item 587@cite{Whether the value of a single-character character constant in a 588constant expression that controls conditional inclusion may have a 589negative value (C90 6.8.1, C99 6.10.1).} 590 591@item 592@cite{The places that are searched for an included @samp{<>} delimited 593header, and how the places are specified or the header is 594identified (C90 6.8.2, C99 6.10.2).} 595 596@item 597@cite{How the named source file is searched for in an included @samp{""} 598delimited header (C90 6.8.2, C99 6.10.2).} 599 600@item 601@cite{The method by which preprocessing tokens (possibly resulting from 602macro expansion) in a @code{#include} directive are combined into a header 603name (C90 6.8.2, C99 6.10.2).} 604 605@item 606@cite{The nesting limit for @code{#include} processing (C90 6.8.2, C99 6076.10.2).} 608 609@item 610@cite{Whether the @samp{#} operator inserts a @samp{\} character before 611the @samp{\} character that begins a universal character name in a 612character constant or string literal (C99 6.10.3.2).} 613 614@item 615@cite{The behavior on each recognized non-@code{STDC #pragma} 616directive (C90 6.8.6, C99 6.10.6).} 617 618@xref{Pragmas, , Pragmas, cpp, The C Preprocessor}, for details of 619pragmas accepted by GCC on all targets. @xref{Pragmas, , Pragmas 620Accepted by GCC}, for details of target-specific pragmas. 621 622@item 623@cite{The definitions for @code{__DATE__} and @code{__TIME__} when 624respectively, the date and time of translation are not available (C90 6256.8.8, C99 6.10.8).} 626 627@end itemize 628 629@node Library functions implementation 630@section Library functions 631 632The behavior of most of these points are dependent on the implementation 633of the C library, and are not defined by GCC itself. 634 635@itemize @bullet 636@item 637@cite{The null pointer constant to which the macro @code{NULL} expands 638(C90 7.1.6, C99 7.17).} 639 640In @code{<stddef.h>}, @code{NULL} expands to @code{((void *)0)}. GCC 641does not provide the other headers which define @code{NULL} and some 642library implementations may use other definitions in those headers. 643 644@end itemize 645 646@node Architecture implementation 647@section Architecture 648 649@itemize @bullet 650@item 651@cite{The values or expressions assigned to the macros specified in the 652headers @code{<float.h>}, @code{<limits.h>}, and @code{<stdint.h>} 653(C90 and C99 5.2.4.2, C99 7.18.2, C99 7.18.3).} 654 655Determined by ABI@. 656 657@item 658@cite{The number, order, and encoding of bytes in any object 659(when not explicitly specified in this International Standard) (C99 6.2.6.1).} 660 661Determined by ABI@. 662 663@item 664@cite{The value of the result of the @code{sizeof} operator (C90 6656.3.3.4, C99 6.5.3.4).} 666 667Determined by ABI@. 668 669@end itemize 670 671@node Locale-specific behavior implementation 672@section Locale-specific behavior 673 674The behavior of these points are dependent on the implementation 675of the C library, and are not defined by GCC itself. 676