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