1@c Copyright (C) 2004-2022 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@c --------------------------------------------------------------------- 6@c GENERIC 7@c --------------------------------------------------------------------- 8 9@node GENERIC 10@chapter GENERIC 11@cindex GENERIC 12 13The purpose of GENERIC is simply to provide a 14language-independent way of representing an entire function in 15trees. To this end, it was necessary to add a few new tree codes 16to the back end, but almost everything was already there. If you 17can express it with the codes in @code{gcc/tree.def}, it's 18GENERIC@. 19 20Early on, there was a great deal of debate about how to think 21about statements in a tree IL@. In GENERIC, a statement is 22defined as any expression whose value, if any, is ignored. A 23statement will always have @code{TREE_SIDE_EFFECTS} set (or it 24will be discarded), but a non-statement expression may also have 25side effects. A @code{CALL_EXPR}, for instance. 26 27It would be possible for some local optimizations to work on the 28GENERIC form of a function; indeed, the adapted tree inliner 29works fine on GENERIC, but the current compiler performs inlining 30after lowering to GIMPLE (a restricted form described in the next 31section). Indeed, currently the frontends perform this lowering 32before handing off to @code{tree_rest_of_compilation}, but this 33seems inelegant. 34 35@menu 36* Deficiencies:: Topics not yet covered in this document. 37* Tree overview:: All about @code{tree}s. 38* Types:: Fundamental and aggregate types. 39* Declarations:: Type declarations and variables. 40* Attributes:: Declaration and type attributes. 41* Expressions: Expression trees. Operating on data. 42* Statements:: Control flow and related trees. 43* Functions:: Function bodies, linkage, and other aspects. 44* Language-dependent trees:: Topics and trees specific to language front ends. 45* C and C++ Trees:: Trees specific to C and C++. 46@end menu 47 48@c --------------------------------------------------------------------- 49@c Deficiencies 50@c --------------------------------------------------------------------- 51 52@node Deficiencies 53@section Deficiencies 54 55@c The spelling of "incomplet" and "incorrekt" below is intentional. 56There are many places in which this document is incomplet and incorrekt. 57It is, as of yet, only @emph{preliminary} documentation. 58 59@c --------------------------------------------------------------------- 60@c Overview 61@c --------------------------------------------------------------------- 62 63@node Tree overview 64@section Overview 65@cindex tree 66@findex TREE_CODE 67 68The central data structure used by the internal representation is the 69@code{tree}. These nodes, while all of the C type @code{tree}, are of 70many varieties. A @code{tree} is a pointer type, but the object to 71which it points may be of a variety of types. From this point forward, 72we will refer to trees in ordinary type, rather than in @code{this 73font}, except when talking about the actual C type @code{tree}. 74 75You can tell what kind of node a particular tree is by using the 76@code{TREE_CODE} macro. Many, many macros take trees as input and 77return trees as output. However, most macros require a certain kind of 78tree node as input. In other words, there is a type-system for trees, 79but it is not reflected in the C type-system. 80 81For safety, it is useful to configure GCC with @option{--enable-checking}. 82Although this results in a significant performance penalty (since all 83tree types are checked at run-time), and is therefore inappropriate in a 84release version, it is extremely helpful during the development process. 85 86Many macros behave as predicates. Many, although not all, of these 87predicates end in @samp{_P}. Do not rely on the result type of these 88macros being of any particular type. You may, however, rely on the fact 89that the type can be compared to @code{0}, so that statements like 90@smallexample 91if (TEST_P (t) && !TEST_P (y)) 92 x = 1; 93@end smallexample 94@noindent 95and 96@smallexample 97int i = (TEST_P (t) != 0); 98@end smallexample 99@noindent 100are legal. Macros that return @code{int} values now may be changed to 101return @code{tree} values, or other pointers in the future. Even those 102that continue to return @code{int} may return multiple nonzero codes 103where previously they returned only zero and one. Therefore, you should 104not write code like 105@smallexample 106if (TEST_P (t) == 1) 107@end smallexample 108@noindent 109as this code is not guaranteed to work correctly in the future. 110 111You should not take the address of values returned by the macros or 112functions described here. In particular, no guarantee is given that the 113values are lvalues. 114 115In general, the names of macros are all in uppercase, while the names of 116functions are entirely in lowercase. There are rare exceptions to this 117rule. You should assume that any macro or function whose name is made 118up entirely of uppercase letters may evaluate its arguments more than 119once. You may assume that a macro or function whose name is made up 120entirely of lowercase letters will evaluate its arguments only once. 121 122The @code{error_mark_node} is a special tree. Its tree code is 123@code{ERROR_MARK}, but since there is only ever one node with that code, 124the usual practice is to compare the tree against 125@code{error_mark_node}. (This test is just a test for pointer 126equality.) If an error has occurred during front-end processing the 127flag @code{errorcount} will be set. If the front end has encountered 128code it cannot handle, it will issue a message to the user and set 129@code{sorrycount}. When these flags are set, any macro or function 130which normally returns a tree of a particular kind may instead return 131the @code{error_mark_node}. Thus, if you intend to do any processing of 132erroneous code, you must be prepared to deal with the 133@code{error_mark_node}. 134 135Occasionally, a particular tree slot (like an operand to an expression, 136or a particular field in a declaration) will be referred to as 137``reserved for the back end''. These slots are used to store RTL when 138the tree is converted to RTL for use by the GCC back end. However, if 139that process is not taking place (e.g., if the front end is being hooked 140up to an intelligent editor), then those slots may be used by the 141back end presently in use. 142 143If you encounter situations that do not match this documentation, such 144as tree nodes of types not mentioned here, or macros documented to 145return entities of a particular kind that instead return entities of 146some different kind, you have found a bug, either in the front end or in 147the documentation. Please report these bugs as you would any other 148bug. 149 150@menu 151* Macros and Functions::Macros and functions that can be used with all trees. 152* Identifiers:: The names of things. 153* Containers:: Lists and vectors. 154@end menu 155 156@c --------------------------------------------------------------------- 157@c Trees 158@c --------------------------------------------------------------------- 159 160@node Macros and Functions 161@subsection Trees 162@cindex tree 163@findex TREE_CHAIN 164@findex TREE_TYPE 165 166All GENERIC trees have two fields in common. First, @code{TREE_CHAIN} 167is a pointer that can be used as a singly-linked list to other trees. 168The other is @code{TREE_TYPE}. Many trees store the type of an 169expression or declaration in this field. 170 171These are some other functions for handling trees: 172 173@ftable @code 174 175@item tree_size 176Return the number of bytes a tree takes. 177 178@item build0 179@itemx build1 180@itemx build2 181@itemx build3 182@itemx build4 183@itemx build5 184@itemx build6 185 186These functions build a tree and supply values to put in each 187parameter. The basic signature is @samp{@w{code, type, [operands]}}. 188@code{code} is the @code{TREE_CODE}, and @code{type} is a tree 189representing the @code{TREE_TYPE}. These are followed by the 190operands, each of which is also a tree. 191 192@end ftable 193 194 195@c --------------------------------------------------------------------- 196@c Identifiers 197@c --------------------------------------------------------------------- 198 199@node Identifiers 200@subsection Identifiers 201@cindex identifier 202@cindex name 203@tindex IDENTIFIER_NODE 204 205An @code{IDENTIFIER_NODE} represents a slightly more general concept 206than the standard C or C++ concept of identifier. In particular, an 207@code{IDENTIFIER_NODE} may contain a @samp{$}, or other extraordinary 208characters. 209 210There are never two distinct @code{IDENTIFIER_NODE}s representing the 211same identifier. Therefore, you may use pointer equality to compare 212@code{IDENTIFIER_NODE}s, rather than using a routine like 213@code{strcmp}. Use @code{get_identifier} to obtain the unique 214@code{IDENTIFIER_NODE} for a supplied string. 215 216You can use the following macros to access identifiers: 217@ftable @code 218@item IDENTIFIER_POINTER 219The string represented by the identifier, represented as a 220@code{char*}. This string is always @code{NUL}-terminated, and contains 221no embedded @code{NUL} characters. 222 223@item IDENTIFIER_LENGTH 224The length of the string returned by @code{IDENTIFIER_POINTER}, not 225including the trailing @code{NUL}. This value of 226@code{IDENTIFIER_LENGTH (x)} is always the same as @code{strlen 227(IDENTIFIER_POINTER (x))}. 228 229@item IDENTIFIER_OPNAME_P 230This predicate holds if the identifier represents the name of an 231overloaded operator. In this case, you should not depend on the 232contents of either the @code{IDENTIFIER_POINTER} or the 233@code{IDENTIFIER_LENGTH}. 234 235@item IDENTIFIER_TYPENAME_P 236This predicate holds if the identifier represents the name of a 237user-defined conversion operator. In this case, the @code{TREE_TYPE} of 238the @code{IDENTIFIER_NODE} holds the type to which the conversion 239operator converts. 240 241@end ftable 242 243@c --------------------------------------------------------------------- 244@c Containers 245@c --------------------------------------------------------------------- 246 247@node Containers 248@subsection Containers 249@cindex container 250@cindex list 251@cindex vector 252@tindex TREE_LIST 253@tindex TREE_VEC 254@findex TREE_PURPOSE 255@findex TREE_VALUE 256@findex TREE_VEC_LENGTH 257@findex TREE_VEC_ELT 258 259Two common container data structures can be represented directly with 260tree nodes. A @code{TREE_LIST} is a singly linked list containing two 261trees per node. These are the @code{TREE_PURPOSE} and @code{TREE_VALUE} 262of each node. (Often, the @code{TREE_PURPOSE} contains some kind of 263tag, or additional information, while the @code{TREE_VALUE} contains the 264majority of the payload. In other cases, the @code{TREE_PURPOSE} is 265simply @code{NULL_TREE}, while in still others both the 266@code{TREE_PURPOSE} and @code{TREE_VALUE} are of equal stature.) Given 267one @code{TREE_LIST} node, the next node is found by following the 268@code{TREE_CHAIN}. If the @code{TREE_CHAIN} is @code{NULL_TREE}, then 269you have reached the end of the list. 270 271A @code{TREE_VEC} is a simple vector. The @code{TREE_VEC_LENGTH} is an 272integer (not a tree) giving the number of nodes in the vector. The 273nodes themselves are accessed using the @code{TREE_VEC_ELT} macro, which 274takes two arguments. The first is the @code{TREE_VEC} in question; the 275second is an integer indicating which element in the vector is desired. 276The elements are indexed from zero. 277 278@c --------------------------------------------------------------------- 279@c Types 280@c --------------------------------------------------------------------- 281 282@node Types 283@section Types 284@cindex type 285@cindex pointer 286@cindex reference 287@cindex fundamental type 288@cindex array 289@tindex VOID_TYPE 290@tindex INTEGER_TYPE 291@tindex TYPE_MIN_VALUE 292@tindex TYPE_MAX_VALUE 293@tindex REAL_TYPE 294@tindex FIXED_POINT_TYPE 295@tindex COMPLEX_TYPE 296@tindex ENUMERAL_TYPE 297@tindex BOOLEAN_TYPE 298@tindex POINTER_TYPE 299@tindex REFERENCE_TYPE 300@tindex FUNCTION_TYPE 301@tindex METHOD_TYPE 302@tindex ARRAY_TYPE 303@tindex RECORD_TYPE 304@tindex UNION_TYPE 305@tindex OPAQUE_TYPE 306@tindex UNKNOWN_TYPE 307@tindex OFFSET_TYPE 308@findex TYPE_UNQUALIFIED 309@findex TYPE_QUAL_CONST 310@findex TYPE_QUAL_VOLATILE 311@findex TYPE_QUAL_RESTRICT 312@findex TYPE_MAIN_VARIANT 313@cindex qualified type 314@findex TYPE_SIZE 315@findex TYPE_ALIGN 316@findex TYPE_PRECISION 317@findex TYPE_ARG_TYPES 318@findex TYPE_METHOD_BASETYPE 319@findex TYPE_OFFSET_BASETYPE 320@findex TREE_TYPE 321@findex TYPE_CONTEXT 322@findex TYPE_NAME 323@findex TYPENAME_TYPE_FULLNAME 324@findex TYPE_FIELDS 325@findex TYPE_CANONICAL 326@findex TYPE_STRUCTURAL_EQUALITY_P 327@findex SET_TYPE_STRUCTURAL_EQUALITY 328 329All types have corresponding tree nodes. However, you should not assume 330that there is exactly one tree node corresponding to each type. There 331are often multiple nodes corresponding to the same type. 332 333For the most part, different kinds of types have different tree codes. 334(For example, pointer types use a @code{POINTER_TYPE} code while arrays 335use an @code{ARRAY_TYPE} code.) However, pointers to member functions 336use the @code{RECORD_TYPE} code. Therefore, when writing a 337@code{switch} statement that depends on the code associated with a 338particular type, you should take care to handle pointers to member 339functions under the @code{RECORD_TYPE} case label. 340 341The following functions and macros deal with cv-qualification of types: 342@ftable @code 343@item TYPE_MAIN_VARIANT 344This macro returns the unqualified version of a type. It may be applied 345to an unqualified type, but it is not always the identity function in 346that case. 347@end ftable 348 349A few other macros and functions are usable with all types: 350@ftable @code 351@item TYPE_SIZE 352The number of bits required to represent the type, represented as an 353@code{INTEGER_CST}. For an incomplete type, @code{TYPE_SIZE} will be 354@code{NULL_TREE}. 355 356@item TYPE_ALIGN 357The alignment of the type, in bits, represented as an @code{int}. 358 359@item TYPE_NAME 360This macro returns a declaration (in the form of a @code{TYPE_DECL}) for 361the type. (Note this macro does @emph{not} return an 362@code{IDENTIFIER_NODE}, as you might expect, given its name!) You can 363look at the @code{DECL_NAME} of the @code{TYPE_DECL} to obtain the 364actual name of the type. The @code{TYPE_NAME} will be @code{NULL_TREE} 365for a type that is not a built-in type, the result of a typedef, or a 366named class type. 367 368@item TYPE_CANONICAL 369This macro returns the ``canonical'' type for the given type 370node. Canonical types are used to improve performance in the C++ and 371Objective-C++ front ends by allowing efficient comparison between two 372type nodes in @code{same_type_p}: if the @code{TYPE_CANONICAL} values 373of the types are equal, the types are equivalent; otherwise, the types 374are not equivalent. The notion of equivalence for canonical types is 375the same as the notion of type equivalence in the language itself. For 376instance, 377 378When @code{TYPE_CANONICAL} is @code{NULL_TREE}, there is no canonical 379type for the given type node. In this case, comparison between this 380type and any other type requires the compiler to perform a deep, 381``structural'' comparison to see if the two type nodes have the same 382form and properties. 383 384The canonical type for a node is always the most fundamental type in 385the equivalence class of types. For instance, @code{int} is its own 386canonical type. A typedef @code{I} of @code{int} will have @code{int} 387as its canonical type. Similarly, @code{I*}@ and a typedef @code{IP}@ 388(defined to @code{I*}) will has @code{int*} as their canonical 389type. When building a new type node, be sure to set 390@code{TYPE_CANONICAL} to the appropriate canonical type. If the new 391type is a compound type (built from other types), and any of those 392other types require structural equality, use 393@code{SET_TYPE_STRUCTURAL_EQUALITY} to ensure that the new type also 394requires structural equality. Finally, if for some reason you cannot 395guarantee that @code{TYPE_CANONICAL} will point to the canonical type, 396use @code{SET_TYPE_STRUCTURAL_EQUALITY} to make sure that the new 397type--and any type constructed based on it--requires structural 398equality. If you suspect that the canonical type system is 399miscomparing types, pass @code{--param verify-canonical-types=1} to 400the compiler or configure with @code{--enable-checking} to force the 401compiler to verify its canonical-type comparisons against the 402structural comparisons; the compiler will then print any warnings if 403the canonical types miscompare. 404 405@item TYPE_STRUCTURAL_EQUALITY_P 406This predicate holds when the node requires structural equality 407checks, e.g., when @code{TYPE_CANONICAL} is @code{NULL_TREE}. 408 409@item SET_TYPE_STRUCTURAL_EQUALITY 410This macro states that the type node it is given requires structural 411equality checks, e.g., it sets @code{TYPE_CANONICAL} to 412@code{NULL_TREE}. 413 414@item same_type_p 415This predicate takes two types as input, and holds if they are the same 416type. For example, if one type is a @code{typedef} for the other, or 417both are @code{typedef}s for the same type. This predicate also holds if 418the two trees given as input are simply copies of one another; i.e., 419there is no difference between them at the source level, but, for 420whatever reason, a duplicate has been made in the representation. You 421should never use @code{==} (pointer equality) to compare types; always 422use @code{same_type_p} instead. 423@end ftable 424 425Detailed below are the various kinds of types, and the macros that can 426be used to access them. Although other kinds of types are used 427elsewhere in G++, the types described here are the only ones that you 428will encounter while examining the intermediate representation. 429 430@table @code 431@item VOID_TYPE 432Used to represent the @code{void} type. 433 434@item INTEGER_TYPE 435Used to represent the various integral types, including @code{char}, 436@code{short}, @code{int}, @code{long}, and @code{long long}. This code 437is not used for enumeration types, nor for the @code{bool} type. 438The @code{TYPE_PRECISION} is the number of bits used in 439the representation, represented as an @code{unsigned int}. (Note that 440in the general case this is not the same value as @code{TYPE_SIZE}; 441suppose that there were a 24-bit integer type, but that alignment 442requirements for the ABI required 32-bit alignment. Then, 443@code{TYPE_SIZE} would be an @code{INTEGER_CST} for 32, while 444@code{TYPE_PRECISION} would be 24.) The integer type is unsigned if 445@code{TYPE_UNSIGNED} holds; otherwise, it is signed. 446 447The @code{TYPE_MIN_VALUE} is an @code{INTEGER_CST} for the smallest 448integer that may be represented by this type. Similarly, the 449@code{TYPE_MAX_VALUE} is an @code{INTEGER_CST} for the largest integer 450that may be represented by this type. 451 452@item REAL_TYPE 453Used to represent the @code{float}, @code{double}, and @code{long 454double} types. The number of bits in the floating-point representation 455is given by @code{TYPE_PRECISION}, as in the @code{INTEGER_TYPE} case. 456 457@item FIXED_POINT_TYPE 458Used to represent the @code{short _Fract}, @code{_Fract}, @code{long 459_Fract}, @code{long long _Fract}, @code{short _Accum}, @code{_Accum}, 460@code{long _Accum}, and @code{long long _Accum} types. The number of bits 461in the fixed-point representation is given by @code{TYPE_PRECISION}, 462as in the @code{INTEGER_TYPE} case. There may be padding bits, fractional 463bits and integral bits. The number of fractional bits is given by 464@code{TYPE_FBIT}, and the number of integral bits is given by @code{TYPE_IBIT}. 465The fixed-point type is unsigned if @code{TYPE_UNSIGNED} holds; otherwise, 466it is signed. 467The fixed-point type is saturating if @code{TYPE_SATURATING} holds; otherwise, 468it is not saturating. 469 470@item COMPLEX_TYPE 471Used to represent GCC built-in @code{__complex__} data types. The 472@code{TREE_TYPE} is the type of the real and imaginary parts. 473 474@item ENUMERAL_TYPE 475Used to represent an enumeration type. The @code{TYPE_PRECISION} gives 476(as an @code{int}), the number of bits used to represent the type. If 477there are no negative enumeration constants, @code{TYPE_UNSIGNED} will 478hold. The minimum and maximum enumeration constants may be obtained 479with @code{TYPE_MIN_VALUE} and @code{TYPE_MAX_VALUE}, respectively; each 480of these macros returns an @code{INTEGER_CST}. 481 482The actual enumeration constants themselves may be obtained by looking 483at the @code{TYPE_VALUES}. This macro will return a @code{TREE_LIST}, 484containing the constants. The @code{TREE_PURPOSE} of each node will be 485an @code{IDENTIFIER_NODE} giving the name of the constant; the 486@code{TREE_VALUE} will be an @code{INTEGER_CST} giving the value 487assigned to that constant. These constants will appear in the order in 488which they were declared. The @code{TREE_TYPE} of each of these 489constants will be the type of enumeration type itself. 490 491@item OPAQUE_TYPE 492Used for things that have a @code{MODE_OPAQUE} mode class in the 493backend. Opaque types have a size and precision, and can be held in 494memory or registers. They are used when we do not want the compiler to 495make assumptions about the availability of other operations as would 496happen with integer types. 497 498@item BOOLEAN_TYPE 499Used to represent the @code{bool} type. 500 501@item POINTER_TYPE 502Used to represent pointer types, and pointer to data member types. The 503@code{TREE_TYPE} gives the type to which this type points. 504 505@item REFERENCE_TYPE 506Used to represent reference types. The @code{TREE_TYPE} gives the type 507to which this type refers. 508 509@item FUNCTION_TYPE 510Used to represent the type of non-member functions and of static member 511functions. The @code{TREE_TYPE} gives the return type of the function. 512The @code{TYPE_ARG_TYPES} are a @code{TREE_LIST} of the argument types. 513The @code{TREE_VALUE} of each node in this list is the type of the 514corresponding argument; the @code{TREE_PURPOSE} is an expression for the 515default argument value, if any. If the last node in the list is 516@code{void_list_node} (a @code{TREE_LIST} node whose @code{TREE_VALUE} 517is the @code{void_type_node}), then functions of this type do not take 518variable arguments. Otherwise, they do take a variable number of 519arguments. 520 521Note that in C (but not in C++) a function declared like @code{void f()} 522is an unprototyped function taking a variable number of arguments; the 523@code{TYPE_ARG_TYPES} of such a function will be @code{NULL}. 524 525@item METHOD_TYPE 526Used to represent the type of a non-static member function. Like a 527@code{FUNCTION_TYPE}, the return type is given by the @code{TREE_TYPE}. 528The type of @code{*this}, i.e., the class of which functions of this 529type are a member, is given by the @code{TYPE_METHOD_BASETYPE}. The 530@code{TYPE_ARG_TYPES} is the parameter list, as for a 531@code{FUNCTION_TYPE}, and includes the @code{this} argument. 532 533@item ARRAY_TYPE 534Used to represent array types. The @code{TREE_TYPE} gives the type of 535the elements in the array. If the array-bound is present in the type, 536the @code{TYPE_DOMAIN} is an @code{INTEGER_TYPE} whose 537@code{TYPE_MIN_VALUE} and @code{TYPE_MAX_VALUE} will be the lower and 538upper bounds of the array, respectively. The @code{TYPE_MIN_VALUE} will 539always be an @code{INTEGER_CST} for zero, while the 540@code{TYPE_MAX_VALUE} will be one less than the number of elements in 541the array, i.e., the highest value which may be used to index an element 542in the array. 543 544@item RECORD_TYPE 545Used to represent @code{struct} and @code{class} types, as well as 546pointers to member functions and similar constructs in other languages. 547@code{TYPE_FIELDS} contains the items contained in this type, each of 548which can be a @code{FIELD_DECL}, @code{VAR_DECL}, @code{CONST_DECL}, or 549@code{TYPE_DECL}. You may not make any assumptions about the ordering 550of the fields in the type or whether one or more of them overlap. 551 552@item UNION_TYPE 553Used to represent @code{union} types. Similar to @code{RECORD_TYPE} 554except that all @code{FIELD_DECL} nodes in @code{TYPE_FIELD} start at 555bit position zero. 556 557@item QUAL_UNION_TYPE 558Used to represent part of a variant record in Ada. Similar to 559@code{UNION_TYPE} except that each @code{FIELD_DECL} has a 560@code{DECL_QUALIFIER} field, which contains a boolean expression that 561indicates whether the field is present in the object. The type will only 562have one field, so each field's @code{DECL_QUALIFIER} is only evaluated 563if none of the expressions in the previous fields in @code{TYPE_FIELDS} 564are nonzero. Normally these expressions will reference a field in the 565outer object using a @code{PLACEHOLDER_EXPR}. 566 567@item LANG_TYPE 568This node is used to represent a language-specific type. The front 569end must handle it. 570 571@item OFFSET_TYPE 572This node is used to represent a pointer-to-data member. For a data 573member @code{X::m} the @code{TYPE_OFFSET_BASETYPE} is @code{X} and the 574@code{TREE_TYPE} is the type of @code{m}. 575 576@end table 577 578There are variables whose values represent some of the basic types. 579These include: 580@table @code 581@item void_type_node 582A node for @code{void}. 583 584@item integer_type_node 585A node for @code{int}. 586 587@item unsigned_type_node. 588A node for @code{unsigned int}. 589 590@item char_type_node. 591A node for @code{char}. 592@end table 593@noindent 594It may sometimes be useful to compare one of these variables with a type 595in hand, using @code{same_type_p}. 596 597@c --------------------------------------------------------------------- 598@c Declarations 599@c --------------------------------------------------------------------- 600 601@node Declarations 602@section Declarations 603@cindex declaration 604@cindex variable 605@cindex type declaration 606@tindex LABEL_DECL 607@tindex CONST_DECL 608@tindex TYPE_DECL 609@tindex VAR_DECL 610@tindex PARM_DECL 611@tindex DEBUG_EXPR_DECL 612@tindex FIELD_DECL 613@tindex NAMESPACE_DECL 614@tindex RESULT_DECL 615@tindex TEMPLATE_DECL 616@tindex THUNK_DECL 617@findex THUNK_DELTA 618@findex DECL_INITIAL 619@findex DECL_SIZE 620@findex DECL_ALIGN 621@findex DECL_EXTERNAL 622 623This section covers the various kinds of declarations that appear in the 624internal representation, except for declarations of functions 625(represented by @code{FUNCTION_DECL} nodes), which are described in 626@ref{Functions}. 627 628@menu 629* Working with declarations:: Macros and functions that work on 630declarations. 631* Internal structure:: How declaration nodes are represented. 632@end menu 633 634@node Working with declarations 635@subsection Working with declarations 636 637Some macros can be used with any kind of declaration. These include: 638@ftable @code 639@item DECL_NAME 640This macro returns an @code{IDENTIFIER_NODE} giving the name of the 641entity. 642 643@item TREE_TYPE 644This macro returns the type of the entity declared. 645 646@item EXPR_FILENAME 647This macro returns the name of the file in which the entity was 648declared, as a @code{char*}. For an entity declared implicitly by the 649compiler (like @code{__builtin_memcpy}), this will be the string 650@code{"<internal>"}. 651 652@item EXPR_LINENO 653This macro returns the line number at which the entity was declared, as 654an @code{int}. 655 656@item DECL_ARTIFICIAL 657This predicate holds if the declaration was implicitly generated by the 658compiler. For example, this predicate will hold of an implicitly 659declared member function, or of the @code{TYPE_DECL} implicitly 660generated for a class type. Recall that in C++ code like: 661@smallexample 662struct S @{@}; 663@end smallexample 664@noindent 665is roughly equivalent to C code like: 666@smallexample 667struct S @{@}; 668typedef struct S S; 669@end smallexample 670The implicitly generated @code{typedef} declaration is represented by a 671@code{TYPE_DECL} for which @code{DECL_ARTIFICIAL} holds. 672 673@end ftable 674 675The various kinds of declarations include: 676@table @code 677@item LABEL_DECL 678These nodes are used to represent labels in function bodies. For more 679information, see @ref{Functions}. These nodes only appear in block 680scopes. 681 682@item CONST_DECL 683These nodes are used to represent enumeration constants. The value of 684the constant is given by @code{DECL_INITIAL} which will be an 685@code{INTEGER_CST} with the same type as the @code{TREE_TYPE} of the 686@code{CONST_DECL}, i.e., an @code{ENUMERAL_TYPE}. 687 688@item RESULT_DECL 689These nodes represent the value returned by a function. When a value is 690assigned to a @code{RESULT_DECL}, that indicates that the value should 691be returned, via bitwise copy, by the function. You can use 692@code{DECL_SIZE} and @code{DECL_ALIGN} on a @code{RESULT_DECL}, just as 693with a @code{VAR_DECL}. 694 695@item TYPE_DECL 696These nodes represent @code{typedef} declarations. The @code{TREE_TYPE} 697is the type declared to have the name given by @code{DECL_NAME}. In 698some cases, there is no associated name. 699 700@item VAR_DECL 701These nodes represent variables with namespace or block scope, as well 702as static data members. The @code{DECL_SIZE} and @code{DECL_ALIGN} are 703analogous to @code{TYPE_SIZE} and @code{TYPE_ALIGN}. For a declaration, 704you should always use the @code{DECL_SIZE} and @code{DECL_ALIGN} rather 705than the @code{TYPE_SIZE} and @code{TYPE_ALIGN} given by the 706@code{TREE_TYPE}, since special attributes may have been applied to the 707variable to give it a particular size and alignment. You may use the 708predicates @code{DECL_THIS_STATIC} or @code{DECL_THIS_EXTERN} to test 709whether the storage class specifiers @code{static} or @code{extern} were 710used to declare a variable. 711 712If this variable is initialized (but does not require a constructor), 713the @code{DECL_INITIAL} will be an expression for the initializer. The 714initializer should be evaluated, and a bitwise copy into the variable 715performed. If the @code{DECL_INITIAL} is the @code{error_mark_node}, 716there is an initializer, but it is given by an explicit statement later 717in the code; no bitwise copy is required. 718 719GCC provides an extension that allows either automatic variables, or 720global variables, to be placed in particular registers. This extension 721is being used for a particular @code{VAR_DECL} if @code{DECL_REGISTER} 722holds for the @code{VAR_DECL}, and if @code{DECL_ASSEMBLER_NAME} is not 723equal to @code{DECL_NAME}. In that case, @code{DECL_ASSEMBLER_NAME} is 724the name of the register into which the variable will be placed. 725 726@item PARM_DECL 727Used to represent a parameter to a function. Treat these nodes 728similarly to @code{VAR_DECL} nodes. These nodes only appear in the 729@code{DECL_ARGUMENTS} for a @code{FUNCTION_DECL}. 730 731The @code{DECL_ARG_TYPE} for a @code{PARM_DECL} is the type that will 732actually be used when a value is passed to this function. It may be a 733wider type than the @code{TREE_TYPE} of the parameter; for example, the 734ordinary type might be @code{short} while the @code{DECL_ARG_TYPE} is 735@code{int}. 736 737@item DEBUG_EXPR_DECL 738Used to represent an anonymous debug-information temporary created to 739hold an expression as it is optimized away, so that its value can be 740referenced in debug bind statements. 741 742@item FIELD_DECL 743These nodes represent non-static data members. The @code{DECL_SIZE} and 744@code{DECL_ALIGN} behave as for @code{VAR_DECL} nodes. 745The position of the field within the parent record is specified by a 746combination of three attributes. @code{DECL_FIELD_OFFSET} is the position, 747counting in bytes, of the @code{DECL_OFFSET_ALIGN}-bit sized word containing 748the bit of the field closest to the beginning of the structure. 749@code{DECL_FIELD_BIT_OFFSET} is the bit offset of the first bit of the field 750within this word; this may be nonzero even for fields that are not bit-fields, 751since @code{DECL_OFFSET_ALIGN} may be greater than the natural alignment 752of the field's type. 753 754If @code{DECL_C_BIT_FIELD} holds, this field is a bit-field. In a bit-field, 755@code{DECL_BIT_FIELD_TYPE} also contains the type that was originally 756specified for it, while DECL_TYPE may be a modified type with lesser precision, 757according to the size of the bit field. 758 759@item NAMESPACE_DECL 760Namespaces provide a name hierarchy for other declarations. They 761appear in the @code{DECL_CONTEXT} of other @code{_DECL} nodes. 762 763@end table 764 765@node Internal structure 766@subsection Internal structure 767 768@code{DECL} nodes are represented internally as a hierarchy of 769structures. 770 771@menu 772* Current structure hierarchy:: The current DECL node structure 773hierarchy. 774* Adding new DECL node types:: How to add a new DECL node to a 775frontend. 776@end menu 777 778@node Current structure hierarchy 779@subsubsection Current structure hierarchy 780 781@table @code 782 783@item struct tree_decl_minimal 784This is the minimal structure to inherit from in order for common 785@code{DECL} macros to work. The fields it contains are a unique ID, 786source location, context, and name. 787 788@item struct tree_decl_common 789This structure inherits from @code{struct tree_decl_minimal}. It 790contains fields that most @code{DECL} nodes need, such as a field to 791store alignment, machine mode, size, and attributes. 792 793@item struct tree_field_decl 794This structure inherits from @code{struct tree_decl_common}. It is 795used to represent @code{FIELD_DECL}. 796 797@item struct tree_label_decl 798This structure inherits from @code{struct tree_decl_common}. It is 799used to represent @code{LABEL_DECL}. 800 801@item struct tree_translation_unit_decl 802This structure inherits from @code{struct tree_decl_common}. It is 803used to represent @code{TRANSLATION_UNIT_DECL}. 804 805@item struct tree_decl_with_rtl 806This structure inherits from @code{struct tree_decl_common}. It 807contains a field to store the low-level RTL associated with a 808@code{DECL} node. 809 810@item struct tree_result_decl 811This structure inherits from @code{struct tree_decl_with_rtl}. It is 812used to represent @code{RESULT_DECL}. 813 814@item struct tree_const_decl 815This structure inherits from @code{struct tree_decl_with_rtl}. It is 816used to represent @code{CONST_DECL}. 817 818@item struct tree_parm_decl 819This structure inherits from @code{struct tree_decl_with_rtl}. It is 820used to represent @code{PARM_DECL}. 821 822@item struct tree_decl_with_vis 823This structure inherits from @code{struct tree_decl_with_rtl}. It 824contains fields necessary to store visibility information, as well as 825a section name and assembler name. 826 827@item struct tree_var_decl 828This structure inherits from @code{struct tree_decl_with_vis}. It is 829used to represent @code{VAR_DECL}. 830 831@item struct tree_function_decl 832This structure inherits from @code{struct tree_decl_with_vis}. It is 833used to represent @code{FUNCTION_DECL}. 834 835@end table 836@node Adding new DECL node types 837@subsubsection Adding new DECL node types 838 839Adding a new @code{DECL} tree consists of the following steps 840 841@table @asis 842 843@item Add a new tree code for the @code{DECL} node 844For language specific @code{DECL} nodes, there is a @file{.def} file 845in each frontend directory where the tree code should be added. 846For @code{DECL} nodes that are part of the middle-end, the code should 847be added to @file{tree.def}. 848 849@item Create a new structure type for the @code{DECL} node 850These structures should inherit from one of the existing structures in 851the language hierarchy by using that structure as the first member. 852 853@smallexample 854struct tree_foo_decl 855@{ 856 struct tree_decl_with_vis common; 857@} 858@end smallexample 859 860Would create a structure name @code{tree_foo_decl} that inherits from 861@code{struct tree_decl_with_vis}. 862 863For language specific @code{DECL} nodes, this new structure type 864should go in the appropriate @file{.h} file. 865For @code{DECL} nodes that are part of the middle-end, the structure 866type should go in @file{tree.h}. 867 868@item Add a member to the tree structure enumerator for the node 869For garbage collection and dynamic checking purposes, each @code{DECL} 870node structure type is required to have a unique enumerator value 871specified with it. 872For language specific @code{DECL} nodes, this new enumerator value 873should go in the appropriate @file{.def} file. 874For @code{DECL} nodes that are part of the middle-end, the enumerator 875values are specified in @file{treestruct.def}. 876 877@item Update @code{union tree_node} 878In order to make your new structure type usable, it must be added to 879@code{union tree_node}. 880For language specific @code{DECL} nodes, a new entry should be added 881to the appropriate @file{.h} file of the form 882@smallexample 883 struct tree_foo_decl GTY ((tag ("TS_VAR_DECL"))) foo_decl; 884@end smallexample 885For @code{DECL} nodes that are part of the middle-end, the additional 886member goes directly into @code{union tree_node} in @file{tree.h}. 887 888@item Update dynamic checking info 889In order to be able to check whether accessing a named portion of 890@code{union tree_node} is legal, and whether a certain @code{DECL} node 891contains one of the enumerated @code{DECL} node structures in the 892hierarchy, a simple lookup table is used. 893This lookup table needs to be kept up to date with the tree structure 894hierarchy, or else checking and containment macros will fail 895inappropriately. 896 897For language specific @code{DECL} nodes, there is an @code{init_ts} 898function in an appropriate @file{.c} file, which initializes the lookup 899table. 900Code setting up the table for new @code{DECL} nodes should be added 901there. 902For each @code{DECL} tree code and enumerator value representing a 903member of the inheritance hierarchy, the table should contain 1 if 904that tree code inherits (directly or indirectly) from that member. 905Thus, a @code{FOO_DECL} node derived from @code{struct decl_with_rtl}, 906and enumerator value @code{TS_FOO_DECL}, would be set up as follows 907@smallexample 908tree_contains_struct[FOO_DECL][TS_FOO_DECL] = 1; 909tree_contains_struct[FOO_DECL][TS_DECL_WRTL] = 1; 910tree_contains_struct[FOO_DECL][TS_DECL_COMMON] = 1; 911tree_contains_struct[FOO_DECL][TS_DECL_MINIMAL] = 1; 912@end smallexample 913 914For @code{DECL} nodes that are part of the middle-end, the setup code 915goes into @file{tree.cc}. 916 917@item Add macros to access any new fields and flags 918 919Each added field or flag should have a macro that is used to access 920it, that performs appropriate checking to ensure only the right type of 921@code{DECL} nodes access the field. 922 923These macros generally take the following form 924@smallexample 925#define FOO_DECL_FIELDNAME(NODE) FOO_DECL_CHECK(NODE)->foo_decl.fieldname 926@end smallexample 927However, if the structure is simply a base class for further 928structures, something like the following should be used 929@smallexample 930#define BASE_STRUCT_CHECK(T) CONTAINS_STRUCT_CHECK(T, TS_BASE_STRUCT) 931#define BASE_STRUCT_FIELDNAME(NODE) \ 932 (BASE_STRUCT_CHECK(NODE)->base_struct.fieldname 933@end smallexample 934 935Reading them from the generated @file{all-tree.def} file (which in 936turn includes all the @file{tree.def} files), @file{gencheck.cc} is 937used during GCC's build to generate the @code{*_CHECK} macros for all 938tree codes. 939 940@end table 941 942 943@c --------------------------------------------------------------------- 944@c Attributes 945@c --------------------------------------------------------------------- 946@node Attributes 947@section Attributes in trees 948@cindex attributes 949 950Attributes, as specified using the @code{__attribute__} keyword, are 951represented internally as a @code{TREE_LIST}. The @code{TREE_PURPOSE} 952is the name of the attribute, as an @code{IDENTIFIER_NODE}. The 953@code{TREE_VALUE} is a @code{TREE_LIST} of the arguments of the 954attribute, if any, or @code{NULL_TREE} if there are no arguments; the 955arguments are stored as the @code{TREE_VALUE} of successive entries in 956the list, and may be identifiers or expressions. The @code{TREE_CHAIN} 957of the attribute is the next attribute in a list of attributes applying 958to the same declaration or type, or @code{NULL_TREE} if there are no 959further attributes in the list. 960 961Attributes may be attached to declarations and to types; these 962attributes may be accessed with the following macros. All attributes 963are stored in this way, and many also cause other changes to the 964declaration or type or to other internal compiler data structures. 965 966@deftypefn {Tree Macro} tree DECL_ATTRIBUTES (tree @var{decl}) 967This macro returns the attributes on the declaration @var{decl}. 968@end deftypefn 969 970@deftypefn {Tree Macro} tree TYPE_ATTRIBUTES (tree @var{type}) 971This macro returns the attributes on the type @var{type}. 972@end deftypefn 973 974 975@c --------------------------------------------------------------------- 976@c Expressions 977@c --------------------------------------------------------------------- 978 979@node Expression trees 980@section Expressions 981@cindex expression 982@findex TREE_TYPE 983@findex TREE_OPERAND 984 985The internal representation for expressions is for the most part quite 986straightforward. However, there are a few facts that one must bear in 987mind. In particular, the expression ``tree'' is actually a directed 988acyclic graph. (For example there may be many references to the integer 989constant zero throughout the source program; many of these will be 990represented by the same expression node.) You should not rely on 991certain kinds of node being shared, nor should you rely on certain kinds of 992nodes being unshared. 993 994The following macros can be used with all expression nodes: 995 996@ftable @code 997@item TREE_TYPE 998Returns the type of the expression. This value may not be precisely the 999same type that would be given the expression in the original program. 1000@end ftable 1001 1002In what follows, some nodes that one might expect to always have type 1003@code{bool} are documented to have either integral or boolean type. At 1004some point in the future, the C front end may also make use of this same 1005intermediate representation, and at this point these nodes will 1006certainly have integral type. The previous sentence is not meant to 1007imply that the C++ front end does not or will not give these nodes 1008integral type. 1009 1010Below, we list the various kinds of expression nodes. Except where 1011noted otherwise, the operands to an expression are accessed using the 1012@code{TREE_OPERAND} macro. For example, to access the first operand to 1013a binary plus expression @code{expr}, use: 1014 1015@smallexample 1016TREE_OPERAND (expr, 0) 1017@end smallexample 1018@noindent 1019 1020As this example indicates, the operands are zero-indexed. 1021 1022 1023@menu 1024* Constants: Constant expressions. 1025* Storage References:: 1026* Unary and Binary Expressions:: 1027* Vectors:: 1028@end menu 1029 1030@node Constant expressions 1031@subsection Constant expressions 1032@tindex INTEGER_CST 1033@findex tree_int_cst_lt 1034@findex tree_int_cst_equal 1035@tindex tree_fits_uhwi_p 1036@tindex tree_fits_shwi_p 1037@tindex tree_to_uhwi 1038@tindex tree_to_shwi 1039@tindex TREE_INT_CST_NUNITS 1040@tindex TREE_INT_CST_ELT 1041@tindex TREE_INT_CST_LOW 1042@tindex REAL_CST 1043@tindex FIXED_CST 1044@tindex COMPLEX_CST 1045@tindex VECTOR_CST 1046@tindex STRING_CST 1047@tindex POLY_INT_CST 1048@findex TREE_STRING_LENGTH 1049@findex TREE_STRING_POINTER 1050 1051The table below begins with constants, moves on to unary expressions, 1052then proceeds to binary expressions, and concludes with various other 1053kinds of expressions: 1054 1055@table @code 1056@item INTEGER_CST 1057These nodes represent integer constants. Note that the type of these 1058constants is obtained with @code{TREE_TYPE}; they are not always of type 1059@code{int}. In particular, @code{char} constants are represented with 1060@code{INTEGER_CST} nodes. The value of the integer constant @code{e} is 1061represented in an array of HOST_WIDE_INT. There are enough elements 1062in the array to represent the value without taking extra elements for 1063redundant 0s or -1. The number of elements used to represent @code{e} 1064is available via @code{TREE_INT_CST_NUNITS}. Element @code{i} can be 1065extracted by using @code{TREE_INT_CST_ELT (e, i)}. 1066@code{TREE_INT_CST_LOW} is a shorthand for @code{TREE_INT_CST_ELT (e, 0)}. 1067 1068The functions @code{tree_fits_shwi_p} and @code{tree_fits_uhwi_p} 1069can be used to tell if the value is small enough to fit in a 1070signed HOST_WIDE_INT or an unsigned HOST_WIDE_INT respectively. 1071The value can then be extracted using @code{tree_to_shwi} and 1072@code{tree_to_uhwi}. 1073 1074@item REAL_CST 1075 1076FIXME: Talk about how to obtain representations of this constant, do 1077comparisons, and so forth. 1078 1079@item FIXED_CST 1080 1081These nodes represent fixed-point constants. The type of these constants 1082is obtained with @code{TREE_TYPE}. @code{TREE_FIXED_CST_PTR} points to 1083a @code{struct fixed_value}; @code{TREE_FIXED_CST} returns the structure 1084itself. @code{struct fixed_value} contains @code{data} with the size of two 1085@code{HOST_BITS_PER_WIDE_INT} and @code{mode} as the associated fixed-point 1086machine mode for @code{data}. 1087 1088@item COMPLEX_CST 1089These nodes are used to represent complex number constants, that is a 1090@code{__complex__} whose parts are constant nodes. The 1091@code{TREE_REALPART} and @code{TREE_IMAGPART} return the real and the 1092imaginary parts respectively. 1093 1094@item VECTOR_CST 1095These nodes are used to represent vector constants. Each vector 1096constant @var{v} is treated as a specific instance of an arbitrary-length 1097sequence that itself contains @samp{VECTOR_CST_NPATTERNS (@var{v})} 1098interleaved patterns. Each pattern has the form: 1099 1100@smallexample 1101@{ @var{base0}, @var{base1}, @var{base1} + @var{step}, @var{base1} + @var{step} * 2, @dots{} @} 1102@end smallexample 1103 1104The first three elements in each pattern are enough to determine the 1105values of the other elements. However, if all @var{step}s are zero, 1106only the first two elements are needed. If in addition each @var{base1} 1107is equal to the corresponding @var{base0}, only the first element in 1108each pattern is needed. The number of encoded elements per pattern 1109is given by @samp{VECTOR_CST_NELTS_PER_PATTERN (@var{v})}. 1110 1111For example, the constant: 1112 1113@smallexample 1114@{ 0, 1, 2, 6, 3, 8, 4, 10, 5, 12, 6, 14, 7, 16, 8, 18 @} 1115@end smallexample 1116 1117is interpreted as an interleaving of the sequences: 1118 1119@smallexample 1120@{ 0, 2, 3, 4, 5, 6, 7, 8 @} 1121@{ 1, 6, 8, 10, 12, 14, 16, 18 @} 1122@end smallexample 1123 1124where the sequences are represented by the following patterns: 1125 1126@smallexample 1127@var{base0} == 0, @var{base1} == 2, @var{step} == 1 1128@var{base0} == 1, @var{base1} == 6, @var{step} == 2 1129@end smallexample 1130 1131In this case: 1132 1133@smallexample 1134VECTOR_CST_NPATTERNS (@var{v}) == 2 1135VECTOR_CST_NELTS_PER_PATTERN (@var{v}) == 3 1136@end smallexample 1137 1138The vector is therefore encoded using the first 6 elements 1139(@samp{@{ 0, 1, 2, 6, 3, 8 @}}), with the remaining 10 elements 1140being implicit extensions of them. 1141 1142Sometimes this scheme can create two possible encodings of the same 1143vector. For example @{ 0, 1 @} could be seen as two patterns with 1144one element each or one pattern with two elements (@var{base0} and 1145@var{base1}). The canonical encoding is always the one with the 1146fewest patterns or (if both encodings have the same number of 1147petterns) the one with the fewest encoded elements. 1148 1149@samp{vector_cst_encoding_nelts (@var{v})} gives the total number of 1150encoded elements in @var{v}, which is 6 in the example above. 1151@code{VECTOR_CST_ENCODED_ELTS (@var{v})} gives a pointer to the elements 1152encoded in @var{v} and @code{VECTOR_CST_ENCODED_ELT (@var{v}, @var{i})} 1153accesses the value of encoded element @var{i}. 1154 1155@samp{VECTOR_CST_DUPLICATE_P (@var{v})} is true if @var{v} simply contains 1156repeated instances of @samp{VECTOR_CST_NPATTERNS (@var{v})} values. This is 1157a shorthand for testing @samp{VECTOR_CST_NELTS_PER_PATTERN (@var{v}) == 1}. 1158 1159@samp{VECTOR_CST_STEPPED_P (@var{v})} is true if at least one 1160pattern in @var{v} has a nonzero step. This is a shorthand for 1161testing @samp{VECTOR_CST_NELTS_PER_PATTERN (@var{v}) == 3}. 1162 1163The utility function @code{vector_cst_elt} gives the value of an 1164arbitrary index as a @code{tree}. @code{vector_cst_int_elt} gives 1165the same value as a @code{wide_int}. 1166 1167@item STRING_CST 1168These nodes represent string-constants. The @code{TREE_STRING_LENGTH} 1169returns the length of the string, as an @code{int}. The 1170@code{TREE_STRING_POINTER} is a @code{char*} containing the string 1171itself. The string may not be @code{NUL}-terminated, and it may contain 1172embedded @code{NUL} characters. Therefore, the 1173@code{TREE_STRING_LENGTH} includes the trailing @code{NUL} if it is 1174present. 1175 1176For wide string constants, the @code{TREE_STRING_LENGTH} is the number 1177of bytes in the string, and the @code{TREE_STRING_POINTER} 1178points to an array of the bytes of the string, as represented on the 1179target system (that is, as integers in the target endianness). Wide and 1180non-wide string constants are distinguished only by the @code{TREE_TYPE} 1181of the @code{STRING_CST}. 1182 1183FIXME: The formats of string constants are not well-defined when the 1184target system bytes are not the same width as host system bytes. 1185 1186@item POLY_INT_CST 1187These nodes represent invariants that depend on some target-specific 1188runtime parameters. They consist of @code{NUM_POLY_INT_COEFFS} 1189coefficients, with the first coefficient being the constant term and 1190the others being multipliers that are applied to the runtime parameters. 1191 1192@code{POLY_INT_CST_ELT (@var{x}, @var{i})} references coefficient number 1193@var{i} of @code{POLY_INT_CST} node @var{x}. Each coefficient is an 1194@code{INTEGER_CST}. 1195 1196@end table 1197 1198@node Storage References 1199@subsection References to storage 1200@tindex ADDR_EXPR 1201@tindex INDIRECT_REF 1202@tindex MEM_REF 1203@tindex ARRAY_REF 1204@tindex ARRAY_RANGE_REF 1205@tindex TARGET_MEM_REF 1206@tindex COMPONENT_REF 1207 1208@table @code 1209@item ARRAY_REF 1210These nodes represent array accesses. The first operand is the array; 1211the second is the index. To calculate the address of the memory 1212accessed, you must scale the index by the size of the type of the array 1213elements. The type of these expressions must be the type of a component of 1214the array. The third and fourth operands are used after gimplification 1215to represent the lower bound and component size but should not be used 1216directly; call @code{array_ref_low_bound} and @code{array_ref_element_size} 1217instead. 1218 1219@item ARRAY_RANGE_REF 1220These nodes represent access to a range (or ``slice'') of an array. The 1221operands are the same as that for @code{ARRAY_REF} and have the same 1222meanings. The type of these expressions must be an array whose component 1223type is the same as that of the first operand. The range of that array 1224type determines the amount of data these expressions access. 1225 1226@item COMPONENT_REF 1227These nodes represent non-static data member accesses. The first 1228operand is the object (rather than a pointer to it); the second operand 1229is the @code{FIELD_DECL} for the data member. The third operand represents 1230the byte offset of the field, but should not be used directly; call 1231@code{component_ref_field_offset} instead. 1232 1233@item ADDR_EXPR 1234These nodes are used to represent the address of an object. (These 1235expressions will always have pointer or reference type.) The operand may 1236be another expression, or it may be a declaration. 1237 1238As an extension, GCC allows users to take the address of a label. In 1239this case, the operand of the @code{ADDR_EXPR} will be a 1240@code{LABEL_DECL}. The type of such an expression is @code{void*}. 1241 1242If the object addressed is not an lvalue, a temporary is created, and 1243the address of the temporary is used. 1244 1245@item INDIRECT_REF 1246These nodes are used to represent the object pointed to by a pointer. 1247The operand is the pointer being dereferenced; it will always have 1248pointer or reference type. 1249 1250@item MEM_REF 1251These nodes are used to represent the object pointed to by a pointer 1252offset by a constant. 1253The first operand is the pointer being dereferenced; it will always have 1254pointer or reference type. The second operand is a pointer constant 1255serving as constant offset applied to the pointer being dereferenced 1256with its type specifying the type to be used for type-based alias analysis. 1257The type of the node specifies the alignment of the access. 1258 1259@item TARGET_MEM_REF 1260These nodes represent memory accesses whose address directly map to 1261an addressing mode of the target architecture. The first argument 1262is @code{TMR_BASE} and is a pointer to the object being accessed. 1263The second argument is @code{TMR_OFFSET} which is a pointer constant 1264with dual purpose serving both as constant offset and holder of 1265the type used for type-based alias analysis. The first two operands 1266have exactly the same semantics as @code{MEM_REF}. The third 1267and fourth operand are @code{TMR_INDEX} and @code{TMR_STEP} where 1268the former is an integer and the latter an integer constant. The 1269fifth and last operand is @code{TMR_INDEX2} which is an alternate 1270non-constant offset. Any of the third to last operands may be 1271@code{NULL} if the corresponding component does not appear in 1272the address, but @code{TMR_INDEX} and @code{TMR_STEP} shall be 1273always supplied in pair. The Address of the @code{TARGET_MEM_REF} 1274is determined in the following way. 1275 1276@smallexample 1277TMR_BASE + TMR_OFFSET + TMR_INDEX * TMR_STEP + TMR_INDEX2 1278@end smallexample 1279 1280The type of the node specifies the alignment of the access. 1281 1282@end table 1283 1284@node Unary and Binary Expressions 1285@subsection Unary and Binary Expressions 1286@tindex NEGATE_EXPR 1287@tindex ABS_EXPR 1288@tindex ABSU_EXPR 1289@tindex BIT_NOT_EXPR 1290@tindex TRUTH_NOT_EXPR 1291@tindex PREDECREMENT_EXPR 1292@tindex PREINCREMENT_EXPR 1293@tindex POSTDECREMENT_EXPR 1294@tindex POSTINCREMENT_EXPR 1295@tindex FIX_TRUNC_EXPR 1296@tindex FLOAT_EXPR 1297@tindex COMPLEX_EXPR 1298@tindex CONJ_EXPR 1299@tindex REALPART_EXPR 1300@tindex IMAGPART_EXPR 1301@tindex NON_LVALUE_EXPR 1302@tindex NOP_EXPR 1303@tindex CONVERT_EXPR 1304@tindex FIXED_CONVERT_EXPR 1305@tindex THROW_EXPR 1306@tindex LSHIFT_EXPR 1307@tindex RSHIFT_EXPR 1308@tindex BIT_IOR_EXPR 1309@tindex BIT_XOR_EXPR 1310@tindex BIT_AND_EXPR 1311@tindex TRUTH_ANDIF_EXPR 1312@tindex TRUTH_ORIF_EXPR 1313@tindex TRUTH_AND_EXPR 1314@tindex TRUTH_OR_EXPR 1315@tindex TRUTH_XOR_EXPR 1316@tindex POINTER_PLUS_EXPR 1317@tindex POINTER_DIFF_EXPR 1318@tindex PLUS_EXPR 1319@tindex MINUS_EXPR 1320@tindex MULT_EXPR 1321@tindex WIDEN_MULT_EXPR 1322@tindex MULT_HIGHPART_EXPR 1323@tindex RDIV_EXPR 1324@tindex TRUNC_DIV_EXPR 1325@tindex FLOOR_DIV_EXPR 1326@tindex CEIL_DIV_EXPR 1327@tindex ROUND_DIV_EXPR 1328@tindex TRUNC_MOD_EXPR 1329@tindex FLOOR_MOD_EXPR 1330@tindex CEIL_MOD_EXPR 1331@tindex ROUND_MOD_EXPR 1332@tindex EXACT_DIV_EXPR 1333@tindex LT_EXPR 1334@tindex LE_EXPR 1335@tindex GT_EXPR 1336@tindex GE_EXPR 1337@tindex EQ_EXPR 1338@tindex NE_EXPR 1339@tindex ORDERED_EXPR 1340@tindex UNORDERED_EXPR 1341@tindex UNLT_EXPR 1342@tindex UNLE_EXPR 1343@tindex UNGT_EXPR 1344@tindex UNGE_EXPR 1345@tindex UNEQ_EXPR 1346@tindex LTGT_EXPR 1347@tindex MODIFY_EXPR 1348@tindex INIT_EXPR 1349@tindex COMPOUND_EXPR 1350@tindex COND_EXPR 1351@tindex CALL_EXPR 1352@tindex STMT_EXPR 1353@tindex BIND_EXPR 1354@tindex LOOP_EXPR 1355@tindex EXIT_EXPR 1356@tindex CLEANUP_POINT_EXPR 1357@tindex CONSTRUCTOR 1358@tindex COMPOUND_LITERAL_EXPR 1359@tindex SAVE_EXPR 1360@tindex TARGET_EXPR 1361@tindex VA_ARG_EXPR 1362@tindex ANNOTATE_EXPR 1363 1364@table @code 1365@item NEGATE_EXPR 1366These nodes represent unary negation of the single operand, for both 1367integer and floating-point types. The type of negation can be 1368determined by looking at the type of the expression. 1369 1370The behavior of this operation on signed arithmetic overflow is 1371controlled by the @code{flag_wrapv} and @code{flag_trapv} variables. 1372 1373@item ABS_EXPR 1374These nodes represent the absolute value of the single operand, for 1375both integer and floating-point types. This is typically used to 1376implement the @code{abs}, @code{labs} and @code{llabs} builtins for 1377integer types, and the @code{fabs}, @code{fabsf} and @code{fabsl} 1378builtins for floating point types. The type of abs operation can 1379be determined by looking at the type of the expression. 1380 1381This node is not used for complex types. To represent the modulus 1382or complex abs of a complex value, use the @code{BUILT_IN_CABS}, 1383@code{BUILT_IN_CABSF} or @code{BUILT_IN_CABSL} builtins, as used 1384to implement the C99 @code{cabs}, @code{cabsf} and @code{cabsl} 1385built-in functions. 1386 1387@item ABSU_EXPR 1388These nodes represent the absolute value of the single operand in 1389equivalent unsigned type such that @code{ABSU_EXPR} of @code{TYPE_MIN} 1390is well defined. 1391 1392@item BIT_NOT_EXPR 1393These nodes represent bitwise complement, and will always have integral 1394type. The only operand is the value to be complemented. 1395 1396@item TRUTH_NOT_EXPR 1397These nodes represent logical negation, and will always have integral 1398(or boolean) type. The operand is the value being negated. The type 1399of the operand and that of the result are always of @code{BOOLEAN_TYPE} 1400or @code{INTEGER_TYPE}. 1401 1402@item PREDECREMENT_EXPR 1403@itemx PREINCREMENT_EXPR 1404@itemx POSTDECREMENT_EXPR 1405@itemx POSTINCREMENT_EXPR 1406These nodes represent increment and decrement expressions. The value of 1407the single operand is computed, and the operand incremented or 1408decremented. In the case of @code{PREDECREMENT_EXPR} and 1409@code{PREINCREMENT_EXPR}, the value of the expression is the value 1410resulting after the increment or decrement; in the case of 1411@code{POSTDECREMENT_EXPR} and @code{POSTINCREMENT_EXPR} is the value 1412before the increment or decrement occurs. The type of the operand, like 1413that of the result, will be either integral, boolean, or floating-point. 1414 1415@item FIX_TRUNC_EXPR 1416These nodes represent conversion of a floating-point value to an 1417integer. The single operand will have a floating-point type, while 1418the complete expression will have an integral (or boolean) type. The 1419operand is rounded towards zero. 1420 1421@item FLOAT_EXPR 1422These nodes represent conversion of an integral (or boolean) value to a 1423floating-point value. The single operand will have integral type, while 1424the complete expression will have a floating-point type. 1425 1426FIXME: How is the operand supposed to be rounded? Is this dependent on 1427@option{-mieee}? 1428 1429@item COMPLEX_EXPR 1430These nodes are used to represent complex numbers constructed from two 1431expressions of the same (integer or real) type. The first operand is the 1432real part and the second operand is the imaginary part. 1433 1434@item CONJ_EXPR 1435These nodes represent the conjugate of their operand. 1436 1437@item REALPART_EXPR 1438@itemx IMAGPART_EXPR 1439These nodes represent respectively the real and the imaginary parts 1440of complex numbers (their sole argument). 1441 1442@item NON_LVALUE_EXPR 1443These nodes indicate that their one and only operand is not an lvalue. 1444A back end can treat these identically to the single operand. 1445 1446@item NOP_EXPR 1447These nodes are used to represent conversions that do not require any 1448code-generation. For example, conversion of a @code{char*} to an 1449@code{int*} does not require any code be generated; such a conversion is 1450represented by a @code{NOP_EXPR}. The single operand is the expression 1451to be converted. The conversion from a pointer to a reference is also 1452represented with a @code{NOP_EXPR}. 1453 1454@item CONVERT_EXPR 1455These nodes are similar to @code{NOP_EXPR}s, but are used in those 1456situations where code may need to be generated. For example, if an 1457@code{int*} is converted to an @code{int} code may need to be generated 1458on some platforms. These nodes are never used for C++-specific 1459conversions, like conversions between pointers to different classes in 1460an inheritance hierarchy. Any adjustments that need to be made in such 1461cases are always indicated explicitly. Similarly, a user-defined 1462conversion is never represented by a @code{CONVERT_EXPR}; instead, the 1463function calls are made explicit. 1464 1465@item FIXED_CONVERT_EXPR 1466These nodes are used to represent conversions that involve fixed-point 1467values. For example, from a fixed-point value to another fixed-point value, 1468from an integer to a fixed-point value, from a fixed-point value to an 1469integer, from a floating-point value to a fixed-point value, or from 1470a fixed-point value to a floating-point value. 1471 1472@item LSHIFT_EXPR 1473@itemx RSHIFT_EXPR 1474These nodes represent left and right shifts, respectively. The first 1475operand is the value to shift; it will always be of integral type. The 1476second operand is an expression for the number of bits by which to 1477shift. Right shift should be treated as arithmetic, i.e., the 1478high-order bits should be zero-filled when the expression has unsigned 1479type and filled with the sign bit when the expression has signed type. 1480Note that the result is undefined if the second operand is larger 1481than or equal to the first operand's type size. Unlike most nodes, these 1482can have a vector as first operand and a scalar as second operand. 1483 1484 1485@item BIT_IOR_EXPR 1486@itemx BIT_XOR_EXPR 1487@itemx BIT_AND_EXPR 1488These nodes represent bitwise inclusive or, bitwise exclusive or, and 1489bitwise and, respectively. Both operands will always have integral 1490type. 1491 1492@item TRUTH_ANDIF_EXPR 1493@itemx TRUTH_ORIF_EXPR 1494These nodes represent logical ``and'' and logical ``or'', respectively. 1495These operators are not strict; i.e., the second operand is evaluated 1496only if the value of the expression is not determined by evaluation of 1497the first operand. The type of the operands and that of the result are 1498always of @code{BOOLEAN_TYPE} or @code{INTEGER_TYPE}. 1499 1500@item TRUTH_AND_EXPR 1501@itemx TRUTH_OR_EXPR 1502@itemx TRUTH_XOR_EXPR 1503These nodes represent logical and, logical or, and logical exclusive or. 1504They are strict; both arguments are always evaluated. There are no 1505corresponding operators in C or C++, but the front end will sometimes 1506generate these expressions anyhow, if it can tell that strictness does 1507not matter. The type of the operands and that of the result are 1508always of @code{BOOLEAN_TYPE} or @code{INTEGER_TYPE}. 1509 1510@item POINTER_PLUS_EXPR 1511This node represents pointer arithmetic. The first operand is always 1512a pointer/reference type. The second operand is always an unsigned 1513integer type compatible with sizetype. This and POINTER_DIFF_EXPR are 1514the only binary arithmetic operators that can operate on pointer types. 1515 1516@item POINTER_DIFF_EXPR 1517This node represents pointer subtraction. The two operands always 1518have pointer/reference type. It returns a signed integer of the same 1519precision as the pointers. The behavior is undefined if the difference 1520of the two pointers, seen as infinite precision non-negative integers, 1521does not fit in the result type. The result does not depend on the 1522pointer type, it is not divided by the size of the pointed-to type. 1523 1524@item PLUS_EXPR 1525@itemx MINUS_EXPR 1526@itemx MULT_EXPR 1527These nodes represent various binary arithmetic operations. 1528Respectively, these operations are addition, subtraction (of the second 1529operand from the first) and multiplication. Their operands may have 1530either integral or floating type, but there will never be case in which 1531one operand is of floating type and the other is of integral type. 1532 1533The behavior of these operations on signed arithmetic overflow is 1534controlled by the @code{flag_wrapv} and @code{flag_trapv} variables. 1535 1536@item WIDEN_MULT_EXPR 1537This node represents a widening multiplication. The operands have 1538integral types with same @var{b} bits of precision, producing an 1539integral type result with at least @math{2@var{b}} bits of precision. 1540The behaviour is equivalent to extending both operands, possibly of 1541different signedness, to the result type, then multiplying them. 1542 1543@item MULT_HIGHPART_EXPR 1544This node represents the ``high-part'' of a widening multiplication. 1545For an integral type with @var{b} bits of precision, the result is 1546the most significant @var{b} bits of the full @math{2@var{b}} product. 1547Both operands must have the same precision and same signedness. 1548 1549@item RDIV_EXPR 1550This node represents a floating point division operation. 1551 1552@item TRUNC_DIV_EXPR 1553@itemx FLOOR_DIV_EXPR 1554@itemx CEIL_DIV_EXPR 1555@itemx ROUND_DIV_EXPR 1556These nodes represent integer division operations that return an integer 1557result. @code{TRUNC_DIV_EXPR} rounds towards zero, @code{FLOOR_DIV_EXPR} 1558rounds towards negative infinity, @code{CEIL_DIV_EXPR} rounds towards 1559positive infinity and @code{ROUND_DIV_EXPR} rounds to the closest integer. 1560Integer division in C and C++ is truncating, i.e.@: @code{TRUNC_DIV_EXPR}. 1561 1562The behavior of these operations on signed arithmetic overflow, when 1563dividing the minimum signed integer by minus one, is controlled by the 1564@code{flag_wrapv} and @code{flag_trapv} variables. 1565 1566@item TRUNC_MOD_EXPR 1567@itemx FLOOR_MOD_EXPR 1568@itemx CEIL_MOD_EXPR 1569@itemx ROUND_MOD_EXPR 1570These nodes represent the integer remainder or modulus operation. 1571The integer modulus of two operands @code{a} and @code{b} is 1572defined as @code{a - (a/b)*b} where the division calculated using 1573the corresponding division operator. Hence for @code{TRUNC_MOD_EXPR} 1574this definition assumes division using truncation towards zero, i.e.@: 1575@code{TRUNC_DIV_EXPR}. Integer remainder in C and C++ uses truncating 1576division, i.e.@: @code{TRUNC_MOD_EXPR}. 1577 1578@item EXACT_DIV_EXPR 1579The @code{EXACT_DIV_EXPR} code is used to represent integer divisions where 1580the numerator is known to be an exact multiple of the denominator. This 1581allows the backend to choose between the faster of @code{TRUNC_DIV_EXPR}, 1582@code{CEIL_DIV_EXPR} and @code{FLOOR_DIV_EXPR} for the current target. 1583 1584@item LT_EXPR 1585@itemx LE_EXPR 1586@itemx GT_EXPR 1587@itemx GE_EXPR 1588@itemx LTGT_EXPR 1589@itemx EQ_EXPR 1590@itemx NE_EXPR 1591These nodes represent the less than, less than or equal to, greater than, 1592greater than or equal to, less or greater than, equal, and not equal 1593comparison operators. The first and second operands will either be both 1594of integral type, both of floating type or both of vector type, except for 1595LTGT_EXPR where they will only be both of floating type. The result type 1596of these expressions will always be of integral, boolean or signed integral 1597vector type. These operations return the result type's zero value for false, 1598the result type's one value for true, and a vector whose elements are zero 1599(false) or minus one (true) for vectors. 1600 1601For floating point comparisons, if we honor IEEE NaNs and either operand 1602is NaN, then @code{NE_EXPR} always returns true and the remaining operators 1603always return false. On some targets, comparisons against an IEEE NaN, 1604other than equality and inequality, may generate a floating-point exception. 1605 1606@item ORDERED_EXPR 1607@itemx UNORDERED_EXPR 1608These nodes represent non-trapping ordered and unordered comparison 1609operators. These operations take two floating point operands and 1610determine whether they are ordered or unordered relative to each other. 1611If either operand is an IEEE NaN, their comparison is defined to be 1612unordered, otherwise the comparison is defined to be ordered. The 1613result type of these expressions will always be of integral or boolean 1614type. These operations return the result type's zero value for false, 1615and the result type's one value for true. 1616 1617@item UNLT_EXPR 1618@itemx UNLE_EXPR 1619@itemx UNGT_EXPR 1620@itemx UNGE_EXPR 1621@itemx UNEQ_EXPR 1622These nodes represent the unordered comparison operators. 1623These operations take two floating point operands and determine whether 1624the operands are unordered or are less than, less than or equal to, 1625greater than, greater than or equal to, or equal respectively. For 1626example, @code{UNLT_EXPR} returns true if either operand is an IEEE 1627NaN or the first operand is less than the second. All these operations 1628are guaranteed not to generate a floating point exception. The result 1629type of these expressions will always be of integral or boolean type. 1630These operations return the result type's zero value for false, 1631and the result type's one value for true. 1632 1633@item MODIFY_EXPR 1634These nodes represent assignment. The left-hand side is the first 1635operand; the right-hand side is the second operand. The left-hand side 1636will be a @code{VAR_DECL}, @code{INDIRECT_REF}, @code{COMPONENT_REF}, or 1637other lvalue. 1638 1639These nodes are used to represent not only assignment with @samp{=} but 1640also compound assignments (like @samp{+=}), by reduction to @samp{=} 1641assignment. In other words, the representation for @samp{i += 3} looks 1642just like that for @samp{i = i + 3}. 1643 1644@item INIT_EXPR 1645These nodes are just like @code{MODIFY_EXPR}, but are used only when a 1646variable is initialized, rather than assigned to subsequently. This 1647means that we can assume that the target of the initialization is not 1648used in computing its own value; any reference to the lhs in computing 1649the rhs is undefined. 1650 1651@item COMPOUND_EXPR 1652These nodes represent comma-expressions. The first operand is an 1653expression whose value is computed and thrown away prior to the 1654evaluation of the second operand. The value of the entire expression is 1655the value of the second operand. 1656 1657@item COND_EXPR 1658These nodes represent @code{?:} expressions. The first operand 1659is of boolean or integral type. If it evaluates to a nonzero value, 1660the second operand should be evaluated, and returned as the value of the 1661expression. Otherwise, the third operand is evaluated, and returned as 1662the value of the expression. 1663 1664The second operand must have the same type as the entire expression, 1665unless it unconditionally throws an exception or calls a noreturn 1666function, in which case it should have void type. The same constraints 1667apply to the third operand. This allows array bounds checks to be 1668represented conveniently as @code{(i >= 0 && i < 10) ? i : abort()}. 1669 1670As a GNU extension, the C language front-ends allow the second 1671operand of the @code{?:} operator may be omitted in the source. 1672For example, @code{x ? : 3} is equivalent to @code{x ? x : 3}, 1673assuming that @code{x} is an expression without side effects. 1674In the tree representation, however, the second operand is always 1675present, possibly protected by @code{SAVE_EXPR} if the first 1676argument does cause side effects. 1677 1678@item CALL_EXPR 1679These nodes are used to represent calls to functions, including 1680non-static member functions. @code{CALL_EXPR}s are implemented as 1681expression nodes with a variable number of operands. Rather than using 1682@code{TREE_OPERAND} to extract them, it is preferable to use the 1683specialized accessor macros and functions that operate specifically on 1684@code{CALL_EXPR} nodes. 1685 1686@code{CALL_EXPR_FN} returns a pointer to the 1687function to call; it is always an expression whose type is a 1688@code{POINTER_TYPE}. 1689 1690The number of arguments to the call is returned by @code{call_expr_nargs}, 1691while the arguments themselves can be accessed with the @code{CALL_EXPR_ARG} 1692macro. The arguments are zero-indexed and numbered left-to-right. 1693You can iterate over the arguments using @code{FOR_EACH_CALL_EXPR_ARG}, as in: 1694 1695@smallexample 1696tree call, arg; 1697call_expr_arg_iterator iter; 1698FOR_EACH_CALL_EXPR_ARG (arg, iter, call) 1699 /* arg is bound to successive arguments of call. */ 1700 @dots{}; 1701@end smallexample 1702 1703For non-static 1704member functions, there will be an operand corresponding to the 1705@code{this} pointer. There will always be expressions corresponding to 1706all of the arguments, even if the function is declared with default 1707arguments and some arguments are not explicitly provided at the call 1708sites. 1709 1710@code{CALL_EXPR}s also have a @code{CALL_EXPR_STATIC_CHAIN} operand that 1711is used to implement nested functions. This operand is otherwise null. 1712 1713@item CLEANUP_POINT_EXPR 1714These nodes represent full-expressions. The single operand is an 1715expression to evaluate. Any destructor calls engendered by the creation 1716of temporaries during the evaluation of that expression should be 1717performed immediately after the expression is evaluated. 1718 1719@item CONSTRUCTOR 1720These nodes represent the brace-enclosed initializers for a structure or an 1721array. They contain a sequence of component values made out of a vector of 1722constructor_elt, which is a (@code{INDEX}, @code{VALUE}) pair. 1723 1724If the @code{TREE_TYPE} of the @code{CONSTRUCTOR} is a @code{RECORD_TYPE}, 1725@code{UNION_TYPE} or @code{QUAL_UNION_TYPE} then the @code{INDEX} of each 1726node in the sequence will be a @code{FIELD_DECL} and the @code{VALUE} will 1727be the expression used to initialize that field. 1728 1729If the @code{TREE_TYPE} of the @code{CONSTRUCTOR} is an @code{ARRAY_TYPE}, 1730then the @code{INDEX} of each node in the sequence will be an 1731@code{INTEGER_CST} or a @code{RANGE_EXPR} of two @code{INTEGER_CST}s. 1732A single @code{INTEGER_CST} indicates which element of the array is being 1733assigned to. A @code{RANGE_EXPR} indicates an inclusive range of elements 1734to initialize. In both cases the @code{VALUE} is the corresponding 1735initializer. It is re-evaluated for each element of a 1736@code{RANGE_EXPR}. If the @code{INDEX} is @code{NULL_TREE}, then 1737the initializer is for the next available array element. 1738 1739In the front end, you should not depend on the fields appearing in any 1740particular order. However, in the middle end, fields must appear in 1741declaration order. You should not assume that all fields will be 1742represented. Unrepresented fields will be cleared (zeroed), unless the 1743CONSTRUCTOR_NO_CLEARING flag is set, in which case their value becomes 1744undefined. 1745 1746@item COMPOUND_LITERAL_EXPR 1747@findex COMPOUND_LITERAL_EXPR_DECL_EXPR 1748@findex COMPOUND_LITERAL_EXPR_DECL 1749These nodes represent ISO C99 compound literals. The 1750@code{COMPOUND_LITERAL_EXPR_DECL_EXPR} is a @code{DECL_EXPR} 1751containing an anonymous @code{VAR_DECL} for 1752the unnamed object represented by the compound literal; the 1753@code{DECL_INITIAL} of that @code{VAR_DECL} is a @code{CONSTRUCTOR} 1754representing the brace-enclosed list of initializers in the compound 1755literal. That anonymous @code{VAR_DECL} can also be accessed directly 1756by the @code{COMPOUND_LITERAL_EXPR_DECL} macro. 1757 1758@item SAVE_EXPR 1759 1760A @code{SAVE_EXPR} represents an expression (possibly involving 1761side effects) that is used more than once. The side effects should 1762occur only the first time the expression is evaluated. Subsequent uses 1763should just reuse the computed value. The first operand to the 1764@code{SAVE_EXPR} is the expression to evaluate. The side effects should 1765be executed where the @code{SAVE_EXPR} is first encountered in a 1766depth-first preorder traversal of the expression tree. 1767 1768@item TARGET_EXPR 1769A @code{TARGET_EXPR} represents a temporary object. The first operand 1770is a @code{VAR_DECL} for the temporary variable. The second operand is 1771the initializer for the temporary. The initializer is evaluated and, 1772if non-void, copied (bitwise) into the temporary. If the initializer 1773is void, that means that it will perform the initialization itself. 1774 1775Often, a @code{TARGET_EXPR} occurs on the right-hand side of an 1776assignment, or as the second operand to a comma-expression which is 1777itself the right-hand side of an assignment, etc. In this case, we say 1778that the @code{TARGET_EXPR} is ``normal''; otherwise, we say it is 1779``orphaned''. For a normal @code{TARGET_EXPR} the temporary variable 1780should be treated as an alias for the left-hand side of the assignment, 1781rather than as a new temporary variable. 1782 1783The third operand to the @code{TARGET_EXPR}, if present, is a 1784cleanup-expression (i.e., destructor call) for the temporary. If this 1785expression is orphaned, then this expression must be executed when the 1786statement containing this expression is complete. These cleanups must 1787always be executed in the order opposite to that in which they were 1788encountered. Note that if a temporary is created on one branch of a 1789conditional operator (i.e., in the second or third operand to a 1790@code{COND_EXPR}), the cleanup must be run only if that branch is 1791actually executed. 1792 1793@item VA_ARG_EXPR 1794This node is used to implement support for the C/C++ variable argument-list 1795mechanism. It represents expressions like @code{va_arg (ap, type)}. 1796Its @code{TREE_TYPE} yields the tree representation for @code{type} and 1797its sole argument yields the representation for @code{ap}. 1798 1799@item ANNOTATE_EXPR 1800This node is used to attach markers to an expression. The first operand 1801is the annotated expression, the second is an @code{INTEGER_CST} with 1802a value from @code{enum annot_expr_kind}, the third is an @code{INTEGER_CST}. 1803@end table 1804 1805 1806@node Vectors 1807@subsection Vectors 1808@tindex VEC_DUPLICATE_EXPR 1809@tindex VEC_SERIES_EXPR 1810@tindex VEC_LSHIFT_EXPR 1811@tindex VEC_RSHIFT_EXPR 1812@tindex VEC_WIDEN_MULT_HI_EXPR 1813@tindex VEC_WIDEN_MULT_LO_EXPR 1814@tindex VEC_WIDEN_PLUS_HI_EXPR 1815@tindex VEC_WIDEN_PLUS_LO_EXPR 1816@tindex VEC_WIDEN_MINUS_HI_EXPR 1817@tindex VEC_WIDEN_MINUS_LO_EXPR 1818@tindex VEC_UNPACK_HI_EXPR 1819@tindex VEC_UNPACK_LO_EXPR 1820@tindex VEC_UNPACK_FLOAT_HI_EXPR 1821@tindex VEC_UNPACK_FLOAT_LO_EXPR 1822@tindex VEC_UNPACK_FIX_TRUNC_HI_EXPR 1823@tindex VEC_UNPACK_FIX_TRUNC_LO_EXPR 1824@tindex VEC_PACK_TRUNC_EXPR 1825@tindex VEC_PACK_SAT_EXPR 1826@tindex VEC_PACK_FIX_TRUNC_EXPR 1827@tindex VEC_PACK_FLOAT_EXPR 1828@tindex VEC_COND_EXPR 1829@tindex SAD_EXPR 1830 1831@table @code 1832@item VEC_DUPLICATE_EXPR 1833This node has a single operand and represents a vector in which every 1834element is equal to that operand. 1835 1836@item VEC_SERIES_EXPR 1837This node represents a vector formed from a scalar base and step, 1838given as the first and second operands respectively. Element @var{i} 1839of the result is equal to @samp{@var{base} + @var{i}*@var{step}}. 1840 1841This node is restricted to integral types, in order to avoid 1842specifying the rounding behavior for floating-point types. 1843 1844@item VEC_LSHIFT_EXPR 1845@itemx VEC_RSHIFT_EXPR 1846These nodes represent whole vector left and right shifts, respectively. 1847The first operand is the vector to shift; it will always be of vector type. 1848The second operand is an expression for the number of bits by which to 1849shift. Note that the result is undefined if the second operand is larger 1850than or equal to the first operand's type size. 1851 1852@item VEC_WIDEN_MULT_HI_EXPR 1853@itemx VEC_WIDEN_MULT_LO_EXPR 1854These nodes represent widening vector multiplication of the high and low 1855parts of the two input vectors, respectively. Their operands are vectors 1856that contain the same number of elements (@code{N}) of the same integral type. 1857The result is a vector that contains half as many elements, of an integral type 1858whose size is twice as wide. In the case of @code{VEC_WIDEN_MULT_HI_EXPR} the 1859high @code{N/2} elements of the two vector are multiplied to produce the 1860vector of @code{N/2} products. In the case of @code{VEC_WIDEN_MULT_LO_EXPR} the 1861low @code{N/2} elements of the two vector are multiplied to produce the 1862vector of @code{N/2} products. 1863 1864@item VEC_WIDEN_PLUS_HI_EXPR 1865@itemx VEC_WIDEN_PLUS_LO_EXPR 1866These nodes represent widening vector addition of the high and low parts of 1867the two input vectors, respectively. Their operands are vectors that contain 1868the same number of elements (@code{N}) of the same integral type. The result 1869is a vector that contains half as many elements, of an integral type whose size 1870is twice as wide. In the case of @code{VEC_WIDEN_PLUS_HI_EXPR} the high 1871@code{N/2} elements of the two vectors are added to produce the vector of 1872@code{N/2} products. In the case of @code{VEC_WIDEN_PLUS_LO_EXPR} the low 1873@code{N/2} elements of the two vectors are added to produce the vector of 1874@code{N/2} products. 1875 1876@item VEC_WIDEN_MINUS_HI_EXPR 1877@itemx VEC_WIDEN_MINUS_LO_EXPR 1878These nodes represent widening vector subtraction of the high and low parts of 1879the two input vectors, respectively. Their operands are vectors that contain 1880the same number of elements (@code{N}) of the same integral type. The high/low 1881elements of the second vector are subtracted from the high/low elements of the 1882first. The result is a vector that contains half as many elements, of an 1883integral type whose size is twice as wide. In the case of 1884@code{VEC_WIDEN_MINUS_HI_EXPR} the high @code{N/2} elements of the second 1885vector are subtracted from the high @code{N/2} of the first to produce the 1886vector of @code{N/2} products. In the case of 1887@code{VEC_WIDEN_MINUS_LO_EXPR} the low @code{N/2} elements of the second 1888vector are subtracted from the low @code{N/2} of the first to produce the 1889vector of @code{N/2} products. 1890 1891@item VEC_UNPACK_HI_EXPR 1892@itemx VEC_UNPACK_LO_EXPR 1893These nodes represent unpacking of the high and low parts of the input vector, 1894respectively. The single operand is a vector that contains @code{N} elements 1895of the same integral or floating point type. The result is a vector 1896that contains half as many elements, of an integral or floating point type 1897whose size is twice as wide. In the case of @code{VEC_UNPACK_HI_EXPR} the 1898high @code{N/2} elements of the vector are extracted and widened (promoted). 1899In the case of @code{VEC_UNPACK_LO_EXPR} the low @code{N/2} elements of the 1900vector are extracted and widened (promoted). 1901 1902@item VEC_UNPACK_FLOAT_HI_EXPR 1903@itemx VEC_UNPACK_FLOAT_LO_EXPR 1904These nodes represent unpacking of the high and low parts of the input vector, 1905where the values are converted from fixed point to floating point. The 1906single operand is a vector that contains @code{N} elements of the same 1907integral type. The result is a vector that contains half as many elements 1908of a floating point type whose size is twice as wide. In the case of 1909@code{VEC_UNPACK_FLOAT_HI_EXPR} the high @code{N/2} elements of the vector are 1910extracted, converted and widened. In the case of @code{VEC_UNPACK_FLOAT_LO_EXPR} 1911the low @code{N/2} elements of the vector are extracted, converted and widened. 1912 1913@item VEC_UNPACK_FIX_TRUNC_HI_EXPR 1914@itemx VEC_UNPACK_FIX_TRUNC_LO_EXPR 1915These nodes represent unpacking of the high and low parts of the input vector, 1916where the values are truncated from floating point to fixed point. The 1917single operand is a vector that contains @code{N} elements of the same 1918floating point type. The result is a vector that contains half as many 1919elements of an integral type whose size is twice as wide. In the case of 1920@code{VEC_UNPACK_FIX_TRUNC_HI_EXPR} the high @code{N/2} elements of the 1921vector are extracted and converted with truncation. In the case of 1922@code{VEC_UNPACK_FIX_TRUNC_LO_EXPR} the low @code{N/2} elements of the 1923vector are extracted and converted with truncation. 1924 1925@item VEC_PACK_TRUNC_EXPR 1926This node represents packing of truncated elements of the two input vectors 1927into the output vector. Input operands are vectors that contain the same 1928number of elements of the same integral or floating point type. The result 1929is a vector that contains twice as many elements of an integral or floating 1930point type whose size is half as wide. The elements of the two vectors are 1931demoted and merged (concatenated) to form the output vector. 1932 1933@item VEC_PACK_SAT_EXPR 1934This node represents packing of elements of the two input vectors into the 1935output vector using saturation. Input operands are vectors that contain 1936the same number of elements of the same integral type. The result is a 1937vector that contains twice as many elements of an integral type whose size 1938is half as wide. The elements of the two vectors are demoted and merged 1939(concatenated) to form the output vector. 1940 1941@item VEC_PACK_FIX_TRUNC_EXPR 1942This node represents packing of elements of the two input vectors into the 1943output vector, where the values are converted from floating point 1944to fixed point. Input operands are vectors that contain the same number 1945of elements of a floating point type. The result is a vector that contains 1946twice as many elements of an integral type whose size is half as wide. The 1947elements of the two vectors are merged (concatenated) to form the output 1948vector. 1949 1950@item VEC_PACK_FLOAT_EXPR 1951This node represents packing of elements of the two input vectors into the 1952output vector, where the values are converted from fixed point to floating 1953point. Input operands are vectors that contain the same number of elements 1954of an integral type. The result is a vector that contains twice as many 1955elements of floating point type whose size is half as wide. The elements of 1956the two vectors are merged (concatenated) to form the output vector. 1957 1958@item VEC_COND_EXPR 1959These nodes represent @code{?:} expressions. The three operands must be 1960vectors of the same size and number of elements. The second and third 1961operands must have the same type as the entire expression. The first 1962operand is of signed integral vector type. If an element of the first 1963operand evaluates to a zero value, the corresponding element of the 1964result is taken from the third operand. If it evaluates to a minus one 1965value, it is taken from the second operand. It should never evaluate to 1966any other value currently, but optimizations should not rely on that 1967property. In contrast with a @code{COND_EXPR}, all operands are always 1968evaluated. 1969 1970@item SAD_EXPR 1971This node represents the Sum of Absolute Differences operation. The three 1972operands must be vectors of integral types. The first and second operand 1973must have the same type. The size of the vector element of the third 1974operand must be at lease twice of the size of the vector element of the 1975first and second one. The SAD is calculated between the first and second 1976operands, added to the third operand, and returned. 1977 1978@end table 1979 1980 1981@c --------------------------------------------------------------------- 1982@c Statements 1983@c --------------------------------------------------------------------- 1984 1985@node Statements 1986@section Statements 1987@cindex Statements 1988 1989Most statements in GIMPLE are assignment statements, represented by 1990@code{GIMPLE_ASSIGN}. No other C expressions can appear at statement level; 1991a reference to a volatile object is converted into a 1992@code{GIMPLE_ASSIGN}. 1993 1994There are also several varieties of complex statements. 1995 1996@menu 1997* Basic Statements:: 1998* Blocks:: 1999* Statement Sequences:: 2000* Empty Statements:: 2001* Jumps:: 2002* Cleanups:: 2003* OpenMP:: 2004* OpenACC:: 2005@end menu 2006 2007@node Basic Statements 2008@subsection Basic Statements 2009@cindex Basic Statements 2010 2011@table @code 2012@item ASM_EXPR 2013 2014Used to represent an inline assembly statement. For an inline assembly 2015statement like: 2016@smallexample 2017asm ("mov x, y"); 2018@end smallexample 2019The @code{ASM_STRING} macro will return a @code{STRING_CST} node for 2020@code{"mov x, y"}. If the original statement made use of the 2021extended-assembly syntax, then @code{ASM_OUTPUTS}, 2022@code{ASM_INPUTS}, and @code{ASM_CLOBBERS} will be the outputs, inputs, 2023and clobbers for the statement, represented as @code{STRING_CST} nodes. 2024The extended-assembly syntax looks like: 2025@smallexample 2026asm ("fsinx %1,%0" : "=f" (result) : "f" (angle)); 2027@end smallexample 2028The first string is the @code{ASM_STRING}, containing the instruction 2029template. The next two strings are the output and inputs, respectively; 2030this statement has no clobbers. As this example indicates, ``plain'' 2031assembly statements are merely a special case of extended assembly 2032statements; they have no cv-qualifiers, outputs, inputs, or clobbers. 2033All of the strings will be @code{NUL}-terminated, and will contain no 2034embedded @code{NUL}-characters. 2035 2036If the assembly statement is declared @code{volatile}, or if the 2037statement was not an extended assembly statement, and is therefore 2038implicitly volatile, then the predicate @code{ASM_VOLATILE_P} will hold 2039of the @code{ASM_EXPR}. 2040 2041@item DECL_EXPR 2042 2043Used to represent a local declaration. The @code{DECL_EXPR_DECL} macro 2044can be used to obtain the entity declared. This declaration may be a 2045@code{LABEL_DECL}, indicating that the label declared is a local label. 2046(As an extension, GCC allows the declaration of labels with scope.) In 2047C, this declaration may be a @code{FUNCTION_DECL}, indicating the 2048use of the GCC nested function extension. For more information, 2049@pxref{Functions}. 2050 2051@item LABEL_EXPR 2052 2053Used to represent a label. The @code{LABEL_DECL} declared by this 2054statement can be obtained with the @code{LABEL_EXPR_LABEL} macro. The 2055@code{IDENTIFIER_NODE} giving the name of the label can be obtained from 2056the @code{LABEL_DECL} with @code{DECL_NAME}. 2057 2058@item GOTO_EXPR 2059 2060Used to represent a @code{goto} statement. The @code{GOTO_DESTINATION} will 2061usually be a @code{LABEL_DECL}. However, if the ``computed goto'' extension 2062has been used, the @code{GOTO_DESTINATION} will be an arbitrary expression 2063indicating the destination. This expression will always have pointer type. 2064 2065@item RETURN_EXPR 2066 2067Used to represent a @code{return} statement. Operand 0 represents the 2068value to return. It should either be the @code{RESULT_DECL} for the 2069containing function, or a @code{MODIFY_EXPR} or @code{INIT_EXPR} 2070setting the function's @code{RESULT_DECL}. It will be 2071@code{NULL_TREE} if the statement was just 2072@smallexample 2073return; 2074@end smallexample 2075 2076@item LOOP_EXPR 2077These nodes represent ``infinite'' loops. The @code{LOOP_EXPR_BODY} 2078represents the body of the loop. It should be executed forever, unless 2079an @code{EXIT_EXPR} is encountered. 2080 2081@item EXIT_EXPR 2082These nodes represent conditional exits from the nearest enclosing 2083@code{LOOP_EXPR}. The single operand is the condition; if it is 2084nonzero, then the loop should be exited. An @code{EXIT_EXPR} will only 2085appear within a @code{LOOP_EXPR}. 2086 2087@item SWITCH_EXPR 2088 2089Used to represent a @code{switch} statement. The @code{SWITCH_COND} 2090is the expression on which the switch is occurring. The 2091@code{SWITCH_BODY} is the body of the switch statement. 2092@code{SWITCH_ALL_CASES_P} is true if the switch includes a default 2093label or the case label ranges cover all possible values of the 2094condition expression. 2095 2096Note that @code{TREE_TYPE} for a @code{SWITCH_EXPR} represents the 2097original type of switch expression as given in the source, before any 2098compiler conversions, instead of the type of the switch expression 2099itself (which is not meaningful). 2100 2101@item CASE_LABEL_EXPR 2102 2103Use to represent a @code{case} label, range of @code{case} labels, or a 2104@code{default} label. If @code{CASE_LOW} is @code{NULL_TREE}, then this is a 2105@code{default} label. Otherwise, if @code{CASE_HIGH} is @code{NULL_TREE}, then 2106this is an ordinary @code{case} label. In this case, @code{CASE_LOW} is 2107an expression giving the value of the label. Both @code{CASE_LOW} and 2108@code{CASE_HIGH} are @code{INTEGER_CST} nodes. These values will have 2109the same type as the condition expression in the switch statement. 2110 2111Otherwise, if both @code{CASE_LOW} and @code{CASE_HIGH} are defined, the 2112statement is a range of case labels. Such statements originate with the 2113extension that allows users to write things of the form: 2114@smallexample 2115case 2 ... 5: 2116@end smallexample 2117The first value will be @code{CASE_LOW}, while the second will be 2118@code{CASE_HIGH}. 2119 2120@item DEBUG_BEGIN_STMT 2121 2122Marks the beginning of a source statement, for purposes of debug 2123information generation. 2124 2125@end table 2126 2127 2128@node Blocks 2129@subsection Blocks 2130@cindex Blocks 2131 2132Block scopes and the variables they declare in GENERIC are 2133expressed using the @code{BIND_EXPR} code, which in previous 2134versions of GCC was primarily used for the C statement-expression 2135extension. 2136 2137Variables in a block are collected into @code{BIND_EXPR_VARS} in 2138declaration order through their @code{TREE_CHAIN} field. Any runtime 2139initialization is moved out of @code{DECL_INITIAL} and into a 2140statement in the controlled block. When gimplifying from C or C++, 2141this initialization replaces the @code{DECL_STMT}. These variables 2142will never require cleanups. The scope of these variables is just the 2143body 2144 2145Variable-length arrays (VLAs) complicate this process, as their size 2146often refers to variables initialized earlier in the block and their 2147initialization involves an explicit stack allocation. To handle this, 2148we add an indirection and replace them with a pointer to stack space 2149allocated by means of @code{alloca}. In most cases, we also arrange 2150for this space to be reclaimed when the enclosing @code{BIND_EXPR} is 2151exited, the exception to this being when there is an explicit call to 2152@code{alloca} in the source code, in which case the stack is left 2153depressed on exit of the @code{BIND_EXPR}. 2154 2155A C++ program will usually contain more @code{BIND_EXPR}s than 2156there are syntactic blocks in the source code, since several C++ 2157constructs have implicit scopes associated with them. On the 2158other hand, although the C++ front end uses pseudo-scopes to 2159handle cleanups for objects with destructors, these don't 2160translate into the GIMPLE form; multiple declarations at the same 2161level use the same @code{BIND_EXPR}. 2162 2163@node Statement Sequences 2164@subsection Statement Sequences 2165@cindex Statement Sequences 2166 2167Multiple statements at the same nesting level are collected into 2168a @code{STATEMENT_LIST}. Statement lists are modified and 2169traversed using the interface in @samp{tree-iterator.h}. 2170 2171@node Empty Statements 2172@subsection Empty Statements 2173@cindex Empty Statements 2174 2175Whenever possible, statements with no effect are discarded. But 2176if they are nested within another construct which cannot be 2177discarded for some reason, they are instead replaced with an 2178empty statement, generated by @code{build_empty_stmt}. 2179Initially, all empty statements were shared, after the pattern of 2180the Java front end, but this caused a lot of trouble in practice. 2181 2182An empty statement is represented as @code{(void)0}. 2183 2184@node Jumps 2185@subsection Jumps 2186@cindex Jumps 2187 2188Other jumps are expressed by either @code{GOTO_EXPR} or 2189@code{RETURN_EXPR}. 2190 2191The operand of a @code{GOTO_EXPR} must be either a label or a 2192variable containing the address to jump to. 2193 2194The operand of a @code{RETURN_EXPR} is either @code{NULL_TREE}, 2195@code{RESULT_DECL}, or a @code{MODIFY_EXPR} which sets the return 2196value. It would be nice to move the @code{MODIFY_EXPR} into a 2197separate statement, but the special return semantics in 2198@code{expand_return} make that difficult. It may still happen in 2199the future, perhaps by moving most of that logic into 2200@code{expand_assignment}. 2201 2202@node Cleanups 2203@subsection Cleanups 2204@cindex Cleanups 2205 2206Destructors for local C++ objects and similar dynamic cleanups are 2207represented in GIMPLE by a @code{TRY_FINALLY_EXPR}. 2208@code{TRY_FINALLY_EXPR} has two operands, both of which are a sequence 2209of statements to execute. The first sequence is executed. When it 2210completes the second sequence is executed. 2211 2212The first sequence may complete in the following ways: 2213 2214@enumerate 2215 2216@item Execute the last statement in the sequence and fall off the 2217end. 2218 2219@item Execute a goto statement (@code{GOTO_EXPR}) to an ordinary 2220label outside the sequence. 2221 2222@item Execute a return statement (@code{RETURN_EXPR}). 2223 2224@item Throw an exception. This is currently not explicitly represented in 2225GIMPLE. 2226 2227@end enumerate 2228 2229The second sequence is not executed if the first sequence completes by 2230calling @code{setjmp} or @code{exit} or any other function that does 2231not return. The second sequence is also not executed if the first 2232sequence completes via a non-local goto or a computed goto (in general 2233the compiler does not know whether such a goto statement exits the 2234first sequence or not, so we assume that it doesn't). 2235 2236After the second sequence is executed, if it completes normally by 2237falling off the end, execution continues wherever the first sequence 2238would have continued, by falling off the end, or doing a goto, etc. 2239 2240If the second sequence is an @code{EH_ELSE_EXPR} selector, then the 2241sequence in its first operand is used when the first sequence completes 2242normally, and that in its second operand is used for exceptional 2243cleanups, i.e., when an exception propagates out of the first sequence. 2244 2245@code{TRY_FINALLY_EXPR} complicates the flow graph, since the cleanup 2246needs to appear on every edge out of the controlled block; this 2247reduces the freedom to move code across these edges. Therefore, the 2248EH lowering pass which runs before most of the optimization passes 2249eliminates these expressions by explicitly adding the cleanup to each 2250edge. Rethrowing the exception is represented using @code{RESX_EXPR}. 2251 2252@node OpenMP 2253@subsection OpenMP 2254@tindex OMP_PARALLEL 2255@tindex OMP_FOR 2256@tindex OMP_SECTIONS 2257@tindex OMP_SINGLE 2258@tindex OMP_SECTION 2259@tindex OMP_MASTER 2260@tindex OMP_ORDERED 2261@tindex OMP_CRITICAL 2262@tindex OMP_RETURN 2263@tindex OMP_CONTINUE 2264@tindex OMP_ATOMIC 2265@tindex OMP_CLAUSE 2266 2267All the statements starting with @code{OMP_} represent directives and 2268clauses used by the OpenMP API @w{@uref{https://www.openmp.org}}. 2269 2270@table @code 2271@item OMP_PARALLEL 2272 2273Represents @code{#pragma omp parallel [clause1 @dots{} clauseN]}. It 2274has four operands: 2275 2276Operand @code{OMP_PARALLEL_BODY} is valid while in GENERIC and 2277High GIMPLE forms. It contains the body of code to be executed 2278by all the threads. During GIMPLE lowering, this operand becomes 2279@code{NULL} and the body is emitted linearly after 2280@code{OMP_PARALLEL}. 2281 2282Operand @code{OMP_PARALLEL_CLAUSES} is the list of clauses 2283associated with the directive. 2284 2285Operand @code{OMP_PARALLEL_FN} is created by 2286@code{pass_lower_omp}, it contains the @code{FUNCTION_DECL} 2287for the function that will contain the body of the parallel 2288region. 2289 2290Operand @code{OMP_PARALLEL_DATA_ARG} is also created by 2291@code{pass_lower_omp}. If there are shared variables to be 2292communicated to the children threads, this operand will contain 2293the @code{VAR_DECL} that contains all the shared values and 2294variables. 2295 2296@item OMP_FOR 2297 2298Represents @code{#pragma omp for [clause1 @dots{} clauseN]}. It has 2299six operands: 2300 2301Operand @code{OMP_FOR_BODY} contains the loop body. 2302 2303Operand @code{OMP_FOR_CLAUSES} is the list of clauses 2304associated with the directive. 2305 2306Operand @code{OMP_FOR_INIT} is the loop initialization code of 2307the form @code{VAR = N1}. 2308 2309Operand @code{OMP_FOR_COND} is the loop conditional expression 2310of the form @code{VAR @{<,>,<=,>=@} N2}. 2311 2312Operand @code{OMP_FOR_INCR} is the loop index increment of the 2313form @code{VAR @{+=,-=@} INCR}. 2314 2315Operand @code{OMP_FOR_PRE_BODY} contains side effect code from 2316operands @code{OMP_FOR_INIT}, @code{OMP_FOR_COND} and 2317@code{OMP_FOR_INC}. These side effects are part of the 2318@code{OMP_FOR} block but must be evaluated before the start of 2319loop body. 2320 2321The loop index variable @code{VAR} must be a signed integer variable, 2322which is implicitly private to each thread. Bounds 2323@code{N1} and @code{N2} and the increment expression 2324@code{INCR} are required to be loop invariant integer 2325expressions that are evaluated without any synchronization. The 2326evaluation order, frequency of evaluation and side effects are 2327unspecified by the standard. 2328 2329@item OMP_SECTIONS 2330 2331Represents @code{#pragma omp sections [clause1 @dots{} clauseN]}. 2332 2333Operand @code{OMP_SECTIONS_BODY} contains the sections body, 2334which in turn contains a set of @code{OMP_SECTION} nodes for 2335each of the concurrent sections delimited by @code{#pragma omp 2336section}. 2337 2338Operand @code{OMP_SECTIONS_CLAUSES} is the list of clauses 2339associated with the directive. 2340 2341@item OMP_SECTION 2342 2343Section delimiter for @code{OMP_SECTIONS}. 2344 2345@item OMP_SINGLE 2346 2347Represents @code{#pragma omp single}. 2348 2349Operand @code{OMP_SINGLE_BODY} contains the body of code to be 2350executed by a single thread. 2351 2352Operand @code{OMP_SINGLE_CLAUSES} is the list of clauses 2353associated with the directive. 2354 2355@item OMP_MASTER 2356 2357Represents @code{#pragma omp master}. 2358 2359Operand @code{OMP_MASTER_BODY} contains the body of code to be 2360executed by the master thread. 2361 2362@item OMP_ORDERED 2363 2364Represents @code{#pragma omp ordered}. 2365 2366Operand @code{OMP_ORDERED_BODY} contains the body of code to be 2367executed in the sequential order dictated by the loop index 2368variable. 2369 2370@item OMP_CRITICAL 2371 2372Represents @code{#pragma omp critical [name]}. 2373 2374Operand @code{OMP_CRITICAL_BODY} is the critical section. 2375 2376Operand @code{OMP_CRITICAL_NAME} is an optional identifier to 2377label the critical section. 2378 2379@item OMP_RETURN 2380 2381This does not represent any OpenMP directive, it is an artificial 2382marker to indicate the end of the body of an OpenMP@. It is used 2383by the flow graph (@code{tree-cfg.cc}) and OpenMP region 2384building code (@code{omp-low.cc}). 2385 2386@item OMP_CONTINUE 2387 2388Similarly, this instruction does not represent an OpenMP 2389directive, it is used by @code{OMP_FOR} (and similar codes) as well as 2390@code{OMP_SECTIONS} to mark the place where the code needs to 2391loop to the next iteration, or the next section, respectively. 2392 2393In some cases, @code{OMP_CONTINUE} is placed right before 2394@code{OMP_RETURN}. But if there are cleanups that need to 2395occur right after the looping body, it will be emitted between 2396@code{OMP_CONTINUE} and @code{OMP_RETURN}. 2397 2398@item OMP_ATOMIC 2399 2400Represents @code{#pragma omp atomic}. 2401 2402Operand 0 is the address at which the atomic operation is to be 2403performed. 2404 2405Operand 1 is the expression to evaluate. The gimplifier tries 2406three alternative code generation strategies. Whenever possible, 2407an atomic update built-in is used. If that fails, a 2408compare-and-swap loop is attempted. If that also fails, a 2409regular critical section around the expression is used. 2410 2411@item OMP_CLAUSE 2412 2413Represents clauses associated with one of the @code{OMP_} directives. 2414Clauses are represented by separate subcodes defined in 2415@file{tree.h}. Clauses codes can be one of: 2416@code{OMP_CLAUSE_PRIVATE}, @code{OMP_CLAUSE_SHARED}, 2417@code{OMP_CLAUSE_FIRSTPRIVATE}, 2418@code{OMP_CLAUSE_LASTPRIVATE}, @code{OMP_CLAUSE_COPYIN}, 2419@code{OMP_CLAUSE_COPYPRIVATE}, @code{OMP_CLAUSE_IF}, 2420@code{OMP_CLAUSE_NUM_THREADS}, @code{OMP_CLAUSE_SCHEDULE}, 2421@code{OMP_CLAUSE_NOWAIT}, @code{OMP_CLAUSE_ORDERED}, 2422@code{OMP_CLAUSE_DEFAULT}, @code{OMP_CLAUSE_REDUCTION}, 2423@code{OMP_CLAUSE_COLLAPSE}, @code{OMP_CLAUSE_UNTIED}, 2424@code{OMP_CLAUSE_FINAL}, and @code{OMP_CLAUSE_MERGEABLE}. Each code 2425represents the corresponding OpenMP clause. 2426 2427Clauses associated with the same directive are chained together 2428via @code{OMP_CLAUSE_CHAIN}. Those clauses that accept a list 2429of variables are restricted to exactly one, accessed with 2430@code{OMP_CLAUSE_VAR}. Therefore, multiple variables under the 2431same clause @code{C} need to be represented as multiple @code{C} clauses 2432chained together. This facilitates adding new clauses during 2433compilation. 2434 2435@end table 2436 2437@node OpenACC 2438@subsection OpenACC 2439@tindex OACC_CACHE 2440@tindex OACC_DATA 2441@tindex OACC_DECLARE 2442@tindex OACC_ENTER_DATA 2443@tindex OACC_EXIT_DATA 2444@tindex OACC_HOST_DATA 2445@tindex OACC_KERNELS 2446@tindex OACC_LOOP 2447@tindex OACC_PARALLEL 2448@tindex OACC_SERIAL 2449@tindex OACC_UPDATE 2450 2451All the statements starting with @code{OACC_} represent directives and 2452clauses used by the OpenACC API @w{@uref{https://www.openacc.org}}. 2453 2454@table @code 2455@item OACC_CACHE 2456 2457Represents @code{#pragma acc cache (var @dots{})}. 2458 2459@item OACC_DATA 2460 2461Represents @code{#pragma acc data [clause1 @dots{} clauseN]}. 2462 2463@item OACC_DECLARE 2464 2465Represents @code{#pragma acc declare [clause1 @dots{} clauseN]}. 2466 2467@item OACC_ENTER_DATA 2468 2469Represents @code{#pragma acc enter data [clause1 @dots{} clauseN]}. 2470 2471@item OACC_EXIT_DATA 2472 2473Represents @code{#pragma acc exit data [clause1 @dots{} clauseN]}. 2474 2475@item OACC_HOST_DATA 2476 2477Represents @code{#pragma acc host_data [clause1 @dots{} clauseN]}. 2478 2479@item OACC_KERNELS 2480 2481Represents @code{#pragma acc kernels [clause1 @dots{} clauseN]}. 2482 2483@item OACC_LOOP 2484 2485Represents @code{#pragma acc loop [clause1 @dots{} clauseN]}. 2486 2487See the description of the @code{OMP_FOR} code. 2488 2489@item OACC_PARALLEL 2490 2491Represents @code{#pragma acc parallel [clause1 @dots{} clauseN]}. 2492 2493@item OACC_SERIAL 2494 2495Represents @code{#pragma acc serial [clause1 @dots{} clauseN]}. 2496 2497@item OACC_UPDATE 2498 2499Represents @code{#pragma acc update [clause1 @dots{} clauseN]}. 2500 2501@end table 2502 2503@c --------------------------------------------------------------------- 2504@c Functions 2505@c --------------------------------------------------------------------- 2506 2507@node Functions 2508@section Functions 2509@cindex function 2510@tindex FUNCTION_DECL 2511 2512A function is represented by a @code{FUNCTION_DECL} node. It stores 2513the basic pieces of the function such as body, parameters, and return 2514type as well as information on the surrounding context, visibility, 2515and linkage. 2516 2517@menu 2518* Function Basics:: Function names, body, and parameters. 2519* Function Properties:: Context, linkage, etc. 2520@end menu 2521 2522@c --------------------------------------------------------------------- 2523@c Function Basics 2524@c --------------------------------------------------------------------- 2525 2526@node Function Basics 2527@subsection Function Basics 2528@findex DECL_NAME 2529@findex DECL_ASSEMBLER_NAME 2530@findex TREE_PUBLIC 2531@findex DECL_ARTIFICIAL 2532@findex DECL_FUNCTION_SPECIFIC_TARGET 2533@findex DECL_FUNCTION_SPECIFIC_OPTIMIZATION 2534 2535A function has four core parts: the name, the parameters, the result, 2536and the body. The following macros and functions access these parts 2537of a @code{FUNCTION_DECL} as well as other basic features: 2538@ftable @code 2539@item DECL_NAME 2540This macro returns the unqualified name of the function, as an 2541@code{IDENTIFIER_NODE}. For an instantiation of a function template, 2542the @code{DECL_NAME} is the unqualified name of the template, not 2543something like @code{f<int>}. The value of @code{DECL_NAME} is 2544undefined when used on a constructor, destructor, overloaded operator, 2545or type-conversion operator, or any function that is implicitly 2546generated by the compiler. See below for macros that can be used to 2547distinguish these cases. 2548 2549@item DECL_ASSEMBLER_NAME 2550This macro returns the mangled name of the function, also an 2551@code{IDENTIFIER_NODE}. This name does not contain leading underscores 2552on systems that prefix all identifiers with underscores. The mangled 2553name is computed in the same way on all platforms; if special processing 2554is required to deal with the object file format used on a particular 2555platform, it is the responsibility of the back end to perform those 2556modifications. (Of course, the back end should not modify 2557@code{DECL_ASSEMBLER_NAME} itself.) 2558 2559Using @code{DECL_ASSEMBLER_NAME} will cause additional memory to be 2560allocated (for the mangled name of the entity) so it should be used 2561only when emitting assembly code. It should not be used within the 2562optimizers to determine whether or not two declarations are the same, 2563even though some of the existing optimizers do use it in that way. 2564These uses will be removed over time. 2565 2566@item DECL_ARGUMENTS 2567This macro returns the @code{PARM_DECL} for the first argument to the 2568function. Subsequent @code{PARM_DECL} nodes can be obtained by 2569following the @code{TREE_CHAIN} links. 2570 2571@item DECL_RESULT 2572This macro returns the @code{RESULT_DECL} for the function. 2573 2574@item DECL_SAVED_TREE 2575This macro returns the complete body of the function. 2576 2577@item TREE_TYPE 2578This macro returns the @code{FUNCTION_TYPE} or @code{METHOD_TYPE} for 2579the function. 2580 2581@item DECL_INITIAL 2582A function that has a definition in the current translation unit will 2583have a non-@code{NULL} @code{DECL_INITIAL}. However, back ends should not make 2584use of the particular value given by @code{DECL_INITIAL}. 2585 2586It should contain a tree of @code{BLOCK} nodes that mirrors the scopes 2587that variables are bound in the function. Each block contains a list 2588of decls declared in a basic block, a pointer to a chain of blocks at 2589the next lower scope level, then a pointer to the next block at the 2590same level and a backpointer to the parent @code{BLOCK} or 2591@code{FUNCTION_DECL}. So given a function as follows: 2592 2593@smallexample 2594void foo() 2595@{ 2596 int a; 2597 @{ 2598 int b; 2599 @} 2600 int c; 2601@} 2602@end smallexample 2603 2604you would get the following: 2605 2606@smallexample 2607tree foo = FUNCTION_DECL; 2608tree decl_a = VAR_DECL; 2609tree decl_b = VAR_DECL; 2610tree decl_c = VAR_DECL; 2611tree block_a = BLOCK; 2612tree block_b = BLOCK; 2613tree block_c = BLOCK; 2614BLOCK_VARS(block_a) = decl_a; 2615BLOCK_SUBBLOCKS(block_a) = block_b; 2616BLOCK_CHAIN(block_a) = block_c; 2617BLOCK_SUPERCONTEXT(block_a) = foo; 2618BLOCK_VARS(block_b) = decl_b; 2619BLOCK_SUPERCONTEXT(block_b) = block_a; 2620BLOCK_VARS(block_c) = decl_c; 2621BLOCK_SUPERCONTEXT(block_c) = foo; 2622DECL_INITIAL(foo) = block_a; 2623@end smallexample 2624 2625@end ftable 2626 2627@c --------------------------------------------------------------------- 2628@c Function Properties 2629@c --------------------------------------------------------------------- 2630 2631@node Function Properties 2632@subsection Function Properties 2633@cindex function properties 2634@cindex statements 2635 2636To determine the scope of a function, you can use the 2637@code{DECL_CONTEXT} macro. This macro will return the class 2638(either a @code{RECORD_TYPE} or a @code{UNION_TYPE}) or namespace (a 2639@code{NAMESPACE_DECL}) of which the function is a member. For a virtual 2640function, this macro returns the class in which the function was 2641actually defined, not the base class in which the virtual declaration 2642occurred. 2643 2644In C, the @code{DECL_CONTEXT} for a function maybe another function. 2645This representation indicates that the GNU nested function extension 2646is in use. For details on the semantics of nested functions, see the 2647GCC Manual. The nested function can refer to local variables in its 2648containing function. Such references are not explicitly marked in the 2649tree structure; back ends must look at the @code{DECL_CONTEXT} for the 2650referenced @code{VAR_DECL}. If the @code{DECL_CONTEXT} for the 2651referenced @code{VAR_DECL} is not the same as the function currently 2652being processed, and neither @code{DECL_EXTERNAL} nor 2653@code{TREE_STATIC} hold, then the reference is to a local variable in 2654a containing function, and the back end must take appropriate action. 2655 2656@ftable @code 2657@item DECL_EXTERNAL 2658This predicate holds if the function is undefined. 2659 2660@item TREE_PUBLIC 2661This predicate holds if the function has external linkage. 2662 2663@item TREE_STATIC 2664This predicate holds if the function has been defined. 2665 2666@item TREE_THIS_VOLATILE 2667This predicate holds if the function does not return normally. 2668 2669@item TREE_READONLY 2670This predicate holds if the function can only read its arguments. 2671 2672@item DECL_PURE_P 2673This predicate holds if the function can only read its arguments, but 2674may also read global memory. 2675 2676@item DECL_VIRTUAL_P 2677This predicate holds if the function is virtual. 2678 2679@item DECL_ARTIFICIAL 2680This macro holds if the function was implicitly generated by the 2681compiler, rather than explicitly declared. In addition to implicitly 2682generated class member functions, this macro holds for the special 2683functions created to implement static initialization and destruction, to 2684compute run-time type information, and so forth. 2685 2686@item DECL_FUNCTION_SPECIFIC_TARGET 2687This macro returns a tree node that holds the target options that are 2688to be used to compile this particular function or @code{NULL_TREE} if 2689the function is to be compiled with the target options specified on 2690the command line. 2691 2692@item DECL_FUNCTION_SPECIFIC_OPTIMIZATION 2693This macro returns a tree node that holds the optimization options 2694that are to be used to compile this particular function or 2695@code{NULL_TREE} if the function is to be compiled with the 2696optimization options specified on the command line. 2697 2698@end ftable 2699 2700@c --------------------------------------------------------------------- 2701@c Language-dependent trees 2702@c --------------------------------------------------------------------- 2703 2704@node Language-dependent trees 2705@section Language-dependent trees 2706@cindex language-dependent trees 2707 2708Front ends may wish to keep some state associated with various GENERIC 2709trees while parsing. To support this, trees provide a set of flags 2710that may be used by the front end. They are accessed using 2711@code{TREE_LANG_FLAG_n} where @samp{n} is currently 0 through 6. 2712 2713If necessary, a front end can use some language-dependent tree 2714codes in its GENERIC representation, so long as it provides a 2715hook for converting them to GIMPLE and doesn't expect them to 2716work with any (hypothetical) optimizers that run before the 2717conversion to GIMPLE@. The intermediate representation used while 2718parsing C and C++ looks very little like GENERIC, but the C and 2719C++ gimplifier hooks are perfectly happy to take it as input and 2720spit out GIMPLE@. 2721 2722 2723 2724@node C and C++ Trees 2725@section C and C++ Trees 2726 2727This section documents the internal representation used by GCC to 2728represent C and C++ source programs. When presented with a C or C++ 2729source program, GCC parses the program, performs semantic analysis 2730(including the generation of error messages), and then produces the 2731internal representation described here. This representation contains a 2732complete representation for the entire translation unit provided as 2733input to the front end. This representation is then typically processed 2734by a code-generator in order to produce machine code, but could also be 2735used in the creation of source browsers, intelligent editors, automatic 2736documentation generators, interpreters, and any other programs needing 2737the ability to process C or C++ code. 2738 2739This section explains the internal representation. In particular, it 2740documents the internal representation for C and C++ source 2741constructs, and the macros, functions, and variables that can be used to 2742access these constructs. The C++ representation is largely a superset 2743of the representation used in the C front end. There is only one 2744construct used in C that does not appear in the C++ front end and that 2745is the GNU ``nested function'' extension. Many of the macros documented 2746here do not apply in C because the corresponding language constructs do 2747not appear in C@. 2748 2749The C and C++ front ends generate a mix of GENERIC trees and ones 2750specific to C and C++. These language-specific trees are higher-level 2751constructs than the ones in GENERIC to make the parser's job easier. 2752This section describes those trees that aren't part of GENERIC as well 2753as aspects of GENERIC trees that are treated in a language-specific 2754manner. 2755 2756If you are developing a ``back end'', be it is a code-generator or some 2757other tool, that uses this representation, you may occasionally find 2758that you need to ask questions not easily answered by the functions and 2759macros available here. If that situation occurs, it is quite likely 2760that GCC already supports the functionality you desire, but that the 2761interface is simply not documented here. In that case, you should ask 2762the GCC maintainers (via mail to @email{gcc@@gcc.gnu.org}) about 2763documenting the functionality you require. Similarly, if you find 2764yourself writing functions that do not deal directly with your back end, 2765but instead might be useful to other people using the GCC front end, you 2766should submit your patches for inclusion in GCC@. 2767 2768@menu 2769* Types for C++:: Fundamental and aggregate types. 2770* Namespaces:: Namespaces. 2771* Classes:: Classes. 2772* Functions for C++:: Overloading and accessors for C++. 2773* Statements for C and C++:: Statements specific to C and C++. 2774* C++ Expressions:: From @code{typeid} to @code{throw}. 2775@end menu 2776 2777@node Types for C++ 2778@subsection Types for C++ 2779@tindex UNKNOWN_TYPE 2780@tindex TYPENAME_TYPE 2781@tindex TYPEOF_TYPE 2782@findex cp_type_quals 2783@findex TYPE_UNQUALIFIED 2784@findex TYPE_QUAL_CONST 2785@findex TYPE_QUAL_VOLATILE 2786@findex TYPE_QUAL_RESTRICT 2787@findex TYPE_MAIN_VARIANT 2788@cindex qualified type 2789@findex TYPE_SIZE 2790@findex TYPE_ALIGN 2791@findex TYPE_PRECISION 2792@findex TYPE_ARG_TYPES 2793@findex TYPE_METHOD_BASETYPE 2794@findex TYPE_PTRDATAMEM_P 2795@findex TYPE_OFFSET_BASETYPE 2796@findex TREE_TYPE 2797@findex TYPE_CONTEXT 2798@findex TYPE_NAME 2799@findex TYPENAME_TYPE_FULLNAME 2800@findex TYPE_FIELDS 2801@findex TYPE_PTROBV_P 2802 2803In C++, an array type is not qualified; rather the type of the array 2804elements is qualified. This situation is reflected in the intermediate 2805representation. The macros described here will always examine the 2806qualification of the underlying element type when applied to an array 2807type. (If the element type is itself an array, then the recursion 2808continues until a non-array type is found, and the qualification of this 2809type is examined.) So, for example, @code{CP_TYPE_CONST_P} will hold of 2810the type @code{const int ()[7]}, denoting an array of seven @code{int}s. 2811 2812The following functions and macros deal with cv-qualification of types: 2813@ftable @code 2814@item cp_type_quals 2815This function returns the set of type qualifiers applied to this type. 2816This value is @code{TYPE_UNQUALIFIED} if no qualifiers have been 2817applied. The @code{TYPE_QUAL_CONST} bit is set if the type is 2818@code{const}-qualified. The @code{TYPE_QUAL_VOLATILE} bit is set if the 2819type is @code{volatile}-qualified. The @code{TYPE_QUAL_RESTRICT} bit is 2820set if the type is @code{restrict}-qualified. 2821 2822@item CP_TYPE_CONST_P 2823This macro holds if the type is @code{const}-qualified. 2824 2825@item CP_TYPE_VOLATILE_P 2826This macro holds if the type is @code{volatile}-qualified. 2827 2828@item CP_TYPE_RESTRICT_P 2829This macro holds if the type is @code{restrict}-qualified. 2830 2831@item CP_TYPE_CONST_NON_VOLATILE_P 2832This predicate holds for a type that is @code{const}-qualified, but 2833@emph{not} @code{volatile}-qualified; other cv-qualifiers are ignored as 2834well: only the @code{const}-ness is tested. 2835 2836@end ftable 2837 2838A few other macros and functions are usable with all types: 2839@ftable @code 2840@item TYPE_SIZE 2841The number of bits required to represent the type, represented as an 2842@code{INTEGER_CST}. For an incomplete type, @code{TYPE_SIZE} will be 2843@code{NULL_TREE}. 2844 2845@item TYPE_ALIGN 2846The alignment of the type, in bits, represented as an @code{int}. 2847 2848@item TYPE_NAME 2849This macro returns a declaration (in the form of a @code{TYPE_DECL}) for 2850the type. (Note this macro does @emph{not} return an 2851@code{IDENTIFIER_NODE}, as you might expect, given its name!) You can 2852look at the @code{DECL_NAME} of the @code{TYPE_DECL} to obtain the 2853actual name of the type. The @code{TYPE_NAME} will be @code{NULL_TREE} 2854for a type that is not a built-in type, the result of a typedef, or a 2855named class type. 2856 2857@item CP_INTEGRAL_TYPE 2858This predicate holds if the type is an integral type. Notice that in 2859C++, enumerations are @emph{not} integral types. 2860 2861@item ARITHMETIC_TYPE_P 2862This predicate holds if the type is an integral type (in the C++ sense) 2863or a floating point type. 2864 2865@item CLASS_TYPE_P 2866This predicate holds for a class-type. 2867 2868@item TYPE_BUILT_IN 2869This predicate holds for a built-in type. 2870 2871@item TYPE_PTRDATAMEM_P 2872This predicate holds if the type is a pointer to data member. 2873 2874@item TYPE_PTR_P 2875This predicate holds if the type is a pointer type, and the pointee is 2876not a data member. 2877 2878@item TYPE_PTRFN_P 2879This predicate holds for a pointer to function type. 2880 2881@item TYPE_PTROB_P 2882This predicate holds for a pointer to object type. Note however that it 2883does not hold for the generic pointer to object type @code{void *}. You 2884may use @code{TYPE_PTROBV_P} to test for a pointer to object type as 2885well as @code{void *}. 2886 2887@end ftable 2888 2889The table below describes types specific to C and C++ as well as 2890language-dependent info about GENERIC types. 2891 2892@table @code 2893 2894@item POINTER_TYPE 2895Used to represent pointer types, and pointer to data member types. If 2896@code{TREE_TYPE} 2897is a pointer to data member type, then @code{TYPE_PTRDATAMEM_P} will hold. 2898For a pointer to data member type of the form @samp{T X::*}, 2899@code{TYPE_PTRMEM_CLASS_TYPE} will be the type @code{X}, while 2900@code{TYPE_PTRMEM_POINTED_TO_TYPE} will be the type @code{T}. 2901 2902@item RECORD_TYPE 2903Used to represent @code{struct} and @code{class} types in C and C++. If 2904@code{TYPE_PTRMEMFUNC_P} holds, then this type is a pointer-to-member 2905type. In that case, the @code{TYPE_PTRMEMFUNC_FN_TYPE} is a 2906@code{POINTER_TYPE} pointing to a @code{METHOD_TYPE}. The 2907@code{METHOD_TYPE} is the type of a function pointed to by the 2908pointer-to-member function. If @code{TYPE_PTRMEMFUNC_P} does not hold, 2909this type is a class type. For more information, @pxref{Classes}. 2910 2911@item UNKNOWN_TYPE 2912This node is used to represent a type the knowledge of which is 2913insufficient for a sound processing. 2914 2915@item TYPENAME_TYPE 2916Used to represent a construct of the form @code{typename T::A}. The 2917@code{TYPE_CONTEXT} is @code{T}; the @code{TYPE_NAME} is an 2918@code{IDENTIFIER_NODE} for @code{A}. If the type is specified via a 2919template-id, then @code{TYPENAME_TYPE_FULLNAME} yields a 2920@code{TEMPLATE_ID_EXPR}. The @code{TREE_TYPE} is non-@code{NULL} if the 2921node is implicitly generated in support for the implicit typename 2922extension; in which case the @code{TREE_TYPE} is a type node for the 2923base-class. 2924 2925@item TYPEOF_TYPE 2926Used to represent the @code{__typeof__} extension. The 2927@code{TYPE_FIELDS} is the expression the type of which is being 2928represented. 2929 2930@end table 2931 2932 2933@c --------------------------------------------------------------------- 2934@c Namespaces 2935@c --------------------------------------------------------------------- 2936 2937@node Namespaces 2938@subsection Namespaces 2939@cindex namespace, scope 2940@tindex NAMESPACE_DECL 2941 2942The root of the entire intermediate representation is the variable 2943@code{global_namespace}. This is the namespace specified with @code{::} 2944in C++ source code. All other namespaces, types, variables, functions, 2945and so forth can be found starting with this namespace. 2946 2947However, except for the fact that it is distinguished as the root of the 2948representation, the global namespace is no different from any other 2949namespace. Thus, in what follows, we describe namespaces generally, 2950rather than the global namespace in particular. 2951 2952A namespace is represented by a @code{NAMESPACE_DECL} node. 2953 2954The following macros and functions can be used on a @code{NAMESPACE_DECL}: 2955 2956@ftable @code 2957@item DECL_NAME 2958This macro is used to obtain the @code{IDENTIFIER_NODE} corresponding to 2959the unqualified name of the name of the namespace (@pxref{Identifiers}). 2960The name of the global namespace is @samp{::}, even though in C++ the 2961global namespace is unnamed. However, you should use comparison with 2962@code{global_namespace}, rather than @code{DECL_NAME} to determine 2963whether or not a namespace is the global one. An unnamed namespace 2964will have a @code{DECL_NAME} equal to @code{anonymous_namespace_name}. 2965Within a single translation unit, all unnamed namespaces will have the 2966same name. 2967 2968@item DECL_CONTEXT 2969This macro returns the enclosing namespace. The @code{DECL_CONTEXT} for 2970the @code{global_namespace} is @code{NULL_TREE}. 2971 2972@item DECL_NAMESPACE_ALIAS 2973If this declaration is for a namespace alias, then 2974@code{DECL_NAMESPACE_ALIAS} is the namespace for which this one is an 2975alias. 2976 2977Do not attempt to use @code{cp_namespace_decls} for a namespace which is 2978an alias. Instead, follow @code{DECL_NAMESPACE_ALIAS} links until you 2979reach an ordinary, non-alias, namespace, and call 2980@code{cp_namespace_decls} there. 2981 2982@item DECL_NAMESPACE_STD_P 2983This predicate holds if the namespace is the special @code{::std} 2984namespace. 2985 2986@item cp_namespace_decls 2987This function will return the declarations contained in the namespace, 2988including types, overloaded functions, other namespaces, and so forth. 2989If there are no declarations, this function will return 2990@code{NULL_TREE}. The declarations are connected through their 2991@code{TREE_CHAIN} fields. 2992 2993Although most entries on this list will be declarations, 2994@code{TREE_LIST} nodes may also appear. In this case, the 2995@code{TREE_VALUE} will be an @code{OVERLOAD}. The value of the 2996@code{TREE_PURPOSE} is unspecified; back ends should ignore this value. 2997As with the other kinds of declarations returned by 2998@code{cp_namespace_decls}, the @code{TREE_CHAIN} will point to the next 2999declaration in this list. 3000 3001For more information on the kinds of declarations that can occur on this 3002list, @xref{Declarations}. Some declarations will not appear on this 3003list. In particular, no @code{FIELD_DECL}, @code{LABEL_DECL}, or 3004@code{PARM_DECL} nodes will appear here. 3005 3006This function cannot be used with namespaces that have 3007@code{DECL_NAMESPACE_ALIAS} set. 3008 3009@end ftable 3010 3011@c --------------------------------------------------------------------- 3012@c Classes 3013@c --------------------------------------------------------------------- 3014 3015@node Classes 3016@subsection Classes 3017@cindex class, scope 3018@tindex RECORD_TYPE 3019@tindex UNION_TYPE 3020@findex CLASSTYPE_DECLARED_CLASS 3021@findex TYPE_BINFO 3022@findex BINFO_TYPE 3023@findex TYPE_FIELDS 3024@findex TYPE_VFIELD 3025 3026Besides namespaces, the other high-level scoping construct in C++ is the 3027class. (Throughout this manual the term @dfn{class} is used to mean the 3028types referred to in the ANSI/ISO C++ Standard as classes; these include 3029types defined with the @code{class}, @code{struct}, and @code{union} 3030keywords.) 3031 3032A class type is represented by either a @code{RECORD_TYPE} or a 3033@code{UNION_TYPE}. A class declared with the @code{union} tag is 3034represented by a @code{UNION_TYPE}, while classes declared with either 3035the @code{struct} or the @code{class} tag are represented by 3036@code{RECORD_TYPE}s. You can use the @code{CLASSTYPE_DECLARED_CLASS} 3037macro to discern whether or not a particular type is a @code{class} as 3038opposed to a @code{struct}. This macro will be true only for classes 3039declared with the @code{class} tag. 3040 3041Almost all members are available on the @code{TYPE_FIELDS} 3042list. Given one member, the next can be found by following the 3043@code{TREE_CHAIN}. You should not depend in any way on the order in 3044which fields appear on this list. All nodes on this list will be 3045@samp{DECL} nodes. A @code{FIELD_DECL} is used to represent a non-static 3046data member, a @code{VAR_DECL} is used to represent a static data 3047member, and a @code{TYPE_DECL} is used to represent a type. Note that 3048the @code{CONST_DECL} for an enumeration constant will appear on this 3049list, if the enumeration type was declared in the class. (Of course, 3050the @code{TYPE_DECL} for the enumeration type will appear here as well.) 3051There are no entries for base classes on this list. In particular, 3052there is no @code{FIELD_DECL} for the ``base-class portion'' of an 3053object. If a function member is overloaded, each of the overloaded 3054functions appears; no @code{OVERLOAD} nodes appear on the @code{TYPE_FIELDS} 3055list. Implicitly declared functions (including default constructors, 3056copy constructors, assignment operators, and destructors) will appear on 3057this list as well. 3058 3059The @code{TYPE_VFIELD} is a compiler-generated field used to point to 3060virtual function tables. It may or may not appear on the 3061@code{TYPE_FIELDS} list. However, back ends should handle the 3062@code{TYPE_VFIELD} just like all the entries on the @code{TYPE_FIELDS} 3063list. 3064 3065Every class has an associated @dfn{binfo}, which can be obtained with 3066@code{TYPE_BINFO}. Binfos are used to represent base-classes. The 3067binfo given by @code{TYPE_BINFO} is the degenerate case, whereby every 3068class is considered to be its own base-class. The base binfos for a 3069particular binfo are held in a vector, whose length is obtained with 3070@code{BINFO_N_BASE_BINFOS}. The base binfos themselves are obtained 3071with @code{BINFO_BASE_BINFO} and @code{BINFO_BASE_ITERATE}. To add a 3072new binfo, use @code{BINFO_BASE_APPEND}. The vector of base binfos can 3073be obtained with @code{BINFO_BASE_BINFOS}, but normally you do not need 3074to use that. The class type associated with a binfo is given by 3075@code{BINFO_TYPE}. It is not always the case that @code{BINFO_TYPE 3076(TYPE_BINFO (x))}, because of typedefs and qualified types. Neither is 3077it the case that @code{TYPE_BINFO (BINFO_TYPE (y))} is the same binfo as 3078@code{y}. The reason is that if @code{y} is a binfo representing a 3079base-class @code{B} of a derived class @code{D}, then @code{BINFO_TYPE 3080(y)} will be @code{B}, and @code{TYPE_BINFO (BINFO_TYPE (y))} will be 3081@code{B} as its own base-class, rather than as a base-class of @code{D}. 3082 3083The access to a base type can be found with @code{BINFO_BASE_ACCESS}. 3084This will produce @code{access_public_node}, @code{access_private_node} 3085or @code{access_protected_node}. If bases are always public, 3086@code{BINFO_BASE_ACCESSES} may be @code{NULL}. 3087 3088@code{BINFO_VIRTUAL_P} is used to specify whether the binfo is inherited 3089virtually or not. The other flags, @code{BINFO_FLAG_0} to 3090@code{BINFO_FLAG_6}, can be used for language specific use. 3091 3092The following macros can be used on a tree node representing a class-type. 3093 3094@ftable @code 3095@item LOCAL_CLASS_P 3096This predicate holds if the class is local class @emph{i.e.}@: declared 3097inside a function body. 3098 3099@item TYPE_POLYMORPHIC_P 3100This predicate holds if the class has at least one virtual function 3101(declared or inherited). 3102 3103@item TYPE_HAS_DEFAULT_CONSTRUCTOR 3104This predicate holds whenever its argument represents a class-type with 3105default constructor. 3106 3107@item CLASSTYPE_HAS_MUTABLE 3108@itemx TYPE_HAS_MUTABLE_P 3109These predicates hold for a class-type having a mutable data member. 3110 3111@item CLASSTYPE_NON_POD_P 3112This predicate holds only for class-types that are not PODs. 3113 3114@item TYPE_HAS_NEW_OPERATOR 3115This predicate holds for a class-type that defines 3116@code{operator new}. 3117 3118@item TYPE_HAS_ARRAY_NEW_OPERATOR 3119This predicate holds for a class-type for which 3120@code{operator new[]} is defined. 3121 3122@item TYPE_OVERLOADS_CALL_EXPR 3123This predicate holds for class-type for which the function call 3124@code{operator()} is overloaded. 3125 3126@item TYPE_OVERLOADS_ARRAY_REF 3127This predicate holds for a class-type that overloads 3128@code{operator[]} 3129 3130@item TYPE_OVERLOADS_ARROW 3131This predicate holds for a class-type for which @code{operator->} is 3132overloaded. 3133 3134@end ftable 3135 3136@node Functions for C++ 3137@subsection Functions for C++ 3138@cindex function 3139@tindex FUNCTION_DECL 3140@tindex OVERLOAD 3141@findex OVL_CURRENT 3142@findex OVL_NEXT 3143 3144A function is represented by a @code{FUNCTION_DECL} node. A set of 3145overloaded functions is sometimes represented by an @code{OVERLOAD} node. 3146 3147An @code{OVERLOAD} node is not a declaration, so none of the 3148@samp{DECL_} macros should be used on an @code{OVERLOAD}. An 3149@code{OVERLOAD} node is similar to a @code{TREE_LIST}. Use 3150@code{OVL_CURRENT} to get the function associated with an 3151@code{OVERLOAD} node; use @code{OVL_NEXT} to get the next 3152@code{OVERLOAD} node in the list of overloaded functions. The macros 3153@code{OVL_CURRENT} and @code{OVL_NEXT} are actually polymorphic; you can 3154use them to work with @code{FUNCTION_DECL} nodes as well as with 3155overloads. In the case of a @code{FUNCTION_DECL}, @code{OVL_CURRENT} 3156will always return the function itself, and @code{OVL_NEXT} will always 3157be @code{NULL_TREE}. 3158 3159To determine the scope of a function, you can use the 3160@code{DECL_CONTEXT} macro. This macro will return the class 3161(either a @code{RECORD_TYPE} or a @code{UNION_TYPE}) or namespace (a 3162@code{NAMESPACE_DECL}) of which the function is a member. For a virtual 3163function, this macro returns the class in which the function was 3164actually defined, not the base class in which the virtual declaration 3165occurred. 3166 3167If a friend function is defined in a class scope, the 3168@code{DECL_FRIEND_CONTEXT} macro can be used to determine the class in 3169which it was defined. For example, in 3170@smallexample 3171class C @{ friend void f() @{@} @}; 3172@end smallexample 3173@noindent 3174the @code{DECL_CONTEXT} for @code{f} will be the 3175@code{global_namespace}, but the @code{DECL_FRIEND_CONTEXT} will be the 3176@code{RECORD_TYPE} for @code{C}. 3177 3178 3179The following macros and functions can be used on a @code{FUNCTION_DECL}: 3180@ftable @code 3181@item DECL_MAIN_P 3182This predicate holds for a function that is the program entry point 3183@code{::code}. 3184 3185@item DECL_LOCAL_FUNCTION_P 3186This predicate holds if the function was declared at block scope, even 3187though it has a global scope. 3188 3189@item DECL_ANTICIPATED 3190This predicate holds if the function is a built-in function but its 3191prototype is not yet explicitly declared. 3192 3193@item DECL_EXTERN_C_FUNCTION_P 3194This predicate holds if the function is declared as an 3195`@code{extern "C"}' function. 3196 3197@item DECL_LINKONCE_P 3198This macro holds if multiple copies of this function may be emitted in 3199various translation units. It is the responsibility of the linker to 3200merge the various copies. Template instantiations are the most common 3201example of functions for which @code{DECL_LINKONCE_P} holds; G++ 3202instantiates needed templates in all translation units which require them, 3203and then relies on the linker to remove duplicate instantiations. 3204 3205FIXME: This macro is not yet implemented. 3206 3207@item DECL_FUNCTION_MEMBER_P 3208This macro holds if the function is a member of a class, rather than a 3209member of a namespace. 3210 3211@item DECL_STATIC_FUNCTION_P 3212This predicate holds if the function a static member function. 3213 3214@item DECL_NONSTATIC_MEMBER_FUNCTION_P 3215This macro holds for a non-static member function. 3216 3217@item DECL_CONST_MEMFUNC_P 3218This predicate holds for a @code{const}-member function. 3219 3220@item DECL_VOLATILE_MEMFUNC_P 3221This predicate holds for a @code{volatile}-member function. 3222 3223@item DECL_CONSTRUCTOR_P 3224This macro holds if the function is a constructor. 3225 3226@item DECL_NONCONVERTING_P 3227This predicate holds if the constructor is a non-converting constructor. 3228 3229@item DECL_COMPLETE_CONSTRUCTOR_P 3230This predicate holds for a function which is a constructor for an object 3231of a complete type. 3232 3233@item DECL_BASE_CONSTRUCTOR_P 3234This predicate holds for a function which is a constructor for a base 3235class sub-object. 3236 3237@item DECL_COPY_CONSTRUCTOR_P 3238This predicate holds for a function which is a copy-constructor. 3239 3240@item DECL_DESTRUCTOR_P 3241This macro holds if the function is a destructor. 3242 3243@item DECL_COMPLETE_DESTRUCTOR_P 3244This predicate holds if the function is the destructor for an object a 3245complete type. 3246 3247@item DECL_OVERLOADED_OPERATOR_P 3248This macro holds if the function is an overloaded operator. 3249 3250@item DECL_CONV_FN_P 3251This macro holds if the function is a type-conversion operator. 3252 3253@item DECL_GLOBAL_CTOR_P 3254This predicate holds if the function is a file-scope initialization 3255function. 3256 3257@item DECL_GLOBAL_DTOR_P 3258This predicate holds if the function is a file-scope finalization 3259function. 3260 3261@item DECL_THUNK_P 3262This predicate holds if the function is a thunk. 3263 3264These functions represent stub code that adjusts the @code{this} pointer 3265and then jumps to another function. When the jumped-to function 3266returns, control is transferred directly to the caller, without 3267returning to the thunk. The first parameter to the thunk is always the 3268@code{this} pointer; the thunk should add @code{THUNK_DELTA} to this 3269value. (The @code{THUNK_DELTA} is an @code{int}, not an 3270@code{INTEGER_CST}.) 3271 3272Then, if @code{THUNK_VCALL_OFFSET} (an @code{INTEGER_CST}) is nonzero 3273the adjusted @code{this} pointer must be adjusted again. The complete 3274calculation is given by the following pseudo-code: 3275 3276@smallexample 3277this += THUNK_DELTA 3278if (THUNK_VCALL_OFFSET) 3279 this += (*((ptrdiff_t **) this))[THUNK_VCALL_OFFSET] 3280@end smallexample 3281 3282Finally, the thunk should jump to the location given 3283by @code{DECL_INITIAL}; this will always be an expression for the 3284address of a function. 3285 3286@item DECL_NON_THUNK_FUNCTION_P 3287This predicate holds if the function is @emph{not} a thunk function. 3288 3289@item GLOBAL_INIT_PRIORITY 3290If either @code{DECL_GLOBAL_CTOR_P} or @code{DECL_GLOBAL_DTOR_P} holds, 3291then this gives the initialization priority for the function. The 3292linker will arrange that all functions for which 3293@code{DECL_GLOBAL_CTOR_P} holds are run in increasing order of priority 3294before @code{main} is called. When the program exits, all functions for 3295which @code{DECL_GLOBAL_DTOR_P} holds are run in the reverse order. 3296 3297@item TYPE_RAISES_EXCEPTIONS 3298This macro returns the list of exceptions that a (member-)function can 3299raise. The returned list, if non @code{NULL}, is comprised of nodes 3300whose @code{TREE_VALUE} represents a type. 3301 3302@item TYPE_NOTHROW_P 3303This predicate holds when the exception-specification of its arguments 3304is of the form `@code{()}'. 3305 3306@item DECL_ARRAY_DELETE_OPERATOR_P 3307This predicate holds if the function an overloaded 3308@code{operator delete[]}. 3309 3310@end ftable 3311 3312@c --------------------------------------------------------------------- 3313@c Function Bodies 3314@c --------------------------------------------------------------------- 3315 3316@node Statements for C and C++ 3317@subsection Statements for C and C++ 3318@cindex statements 3319@tindex BREAK_STMT 3320@tindex CLEANUP_STMT 3321@findex CLEANUP_DECL 3322@findex CLEANUP_EXPR 3323@tindex CONTINUE_STMT 3324@tindex DECL_STMT 3325@findex DECL_STMT_DECL 3326@tindex DO_STMT 3327@findex DO_BODY 3328@findex DO_COND 3329@tindex EMPTY_CLASS_EXPR 3330@tindex EXPR_STMT 3331@findex EXPR_STMT_EXPR 3332@tindex FOR_STMT 3333@findex FOR_INIT_STMT 3334@findex FOR_COND 3335@findex FOR_EXPR 3336@findex FOR_BODY 3337@tindex HANDLER 3338@tindex IF_STMT 3339@findex IF_COND 3340@findex THEN_CLAUSE 3341@findex ELSE_CLAUSE 3342@tindex RETURN_STMT 3343@findex RETURN_EXPR 3344@tindex SUBOBJECT 3345@findex SUBOBJECT_CLEANUP 3346@tindex SWITCH_STMT 3347@findex SWITCH_COND 3348@findex SWITCH_BODY 3349@tindex TRY_BLOCK 3350@findex TRY_STMTS 3351@findex TRY_HANDLERS 3352@findex HANDLER_PARMS 3353@findex HANDLER_BODY 3354@findex USING_STMT 3355@tindex WHILE_STMT 3356@findex WHILE_BODY 3357@findex WHILE_COND 3358 3359A function that has a definition in the current translation unit has 3360a non-@code{NULL} @code{DECL_INITIAL}. However, back ends should not make 3361use of the particular value given by @code{DECL_INITIAL}. 3362 3363The @code{DECL_SAVED_TREE} gives the complete body of the 3364function. 3365 3366There are tree nodes corresponding to all of the source-level 3367statement constructs, used within the C and C++ frontends. These are 3368enumerated here, together with a list of the various macros that can 3369be used to obtain information about them. There are a few macros that 3370can be used with all statements: 3371 3372@ftable @code 3373@item STMT_IS_FULL_EXPR_P 3374In C++, statements normally constitute ``full expressions''; temporaries 3375created during a statement are destroyed when the statement is complete. 3376However, G++ sometimes represents expressions by statements; these 3377statements will not have @code{STMT_IS_FULL_EXPR_P} set. Temporaries 3378created during such statements should be destroyed when the innermost 3379enclosing statement with @code{STMT_IS_FULL_EXPR_P} set is exited. 3380 3381@end ftable 3382 3383Here is the list of the various statement nodes, and the macros used to 3384access them. This documentation describes the use of these nodes in 3385non-template functions (including instantiations of template functions). 3386In template functions, the same nodes are used, but sometimes in 3387slightly different ways. 3388 3389Many of the statements have substatements. For example, a @code{while} 3390loop has a body, which is itself a statement. If the substatement 3391is @code{NULL_TREE}, it is considered equivalent to a statement 3392consisting of a single @code{;}, i.e., an expression statement in which 3393the expression has been omitted. A substatement may in fact be a list 3394of statements, connected via their @code{TREE_CHAIN}s. So, you should 3395always process the statement tree by looping over substatements, like 3396this: 3397@smallexample 3398void process_stmt (stmt) 3399 tree stmt; 3400@{ 3401 while (stmt) 3402 @{ 3403 switch (TREE_CODE (stmt)) 3404 @{ 3405 case IF_STMT: 3406 process_stmt (THEN_CLAUSE (stmt)); 3407 /* @r{More processing here.} */ 3408 break; 3409 3410 @dots{} 3411 @} 3412 3413 stmt = TREE_CHAIN (stmt); 3414 @} 3415@} 3416@end smallexample 3417In other words, while the @code{then} clause of an @code{if} statement 3418in C++ can be only one statement (although that one statement may be a 3419compound statement), the intermediate representation sometimes uses 3420several statements chained together. 3421 3422@table @code 3423@item BREAK_STMT 3424 3425Used to represent a @code{break} statement. There are no additional 3426fields. 3427 3428@item CLEANUP_STMT 3429 3430Used to represent an action that should take place upon exit from the 3431enclosing scope. Typically, these actions are calls to destructors for 3432local objects, but back ends cannot rely on this fact. If these nodes 3433are in fact representing such destructors, @code{CLEANUP_DECL} will be 3434the @code{VAR_DECL} destroyed. Otherwise, @code{CLEANUP_DECL} will be 3435@code{NULL_TREE}. In any case, the @code{CLEANUP_EXPR} is the 3436expression to execute. The cleanups executed on exit from a scope 3437should be run in the reverse order of the order in which the associated 3438@code{CLEANUP_STMT}s were encountered. 3439 3440@item CONTINUE_STMT 3441 3442Used to represent a @code{continue} statement. There are no additional 3443fields. 3444 3445@item CTOR_STMT 3446 3447Used to mark the beginning (if @code{CTOR_BEGIN_P} holds) or end (if 3448@code{CTOR_END_P} holds of the main body of a constructor. See also 3449@code{SUBOBJECT} for more information on how to use these nodes. 3450 3451@item DO_STMT 3452 3453Used to represent a @code{do} loop. The body of the loop is given by 3454@code{DO_BODY} while the termination condition for the loop is given by 3455@code{DO_COND}. The condition for a @code{do}-statement is always an 3456expression. 3457 3458@item EMPTY_CLASS_EXPR 3459 3460Used to represent a temporary object of a class with no data whose 3461address is never taken. (All such objects are interchangeable.) The 3462@code{TREE_TYPE} represents the type of the object. 3463 3464@item EXPR_STMT 3465 3466Used to represent an expression statement. Use @code{EXPR_STMT_EXPR} to 3467obtain the expression. 3468 3469@item FOR_STMT 3470 3471Used to represent a @code{for} statement. The @code{FOR_INIT_STMT} is 3472the initialization statement for the loop. The @code{FOR_COND} is the 3473termination condition. The @code{FOR_EXPR} is the expression executed 3474right before the @code{FOR_COND} on each loop iteration; often, this 3475expression increments a counter. The body of the loop is given by 3476@code{FOR_BODY}. @code{FOR_SCOPE} holds the scope of the @code{for} 3477statement (used in the C++ front end only). Note that 3478@code{FOR_INIT_STMT} and @code{FOR_BODY} return statements, while 3479@code{FOR_COND} and @code{FOR_EXPR} return expressions. 3480 3481@item HANDLER 3482 3483Used to represent a C++ @code{catch} block. The @code{HANDLER_TYPE} 3484is the type of exception that will be caught by this handler; it is 3485equal (by pointer equality) to @code{NULL} if this handler is for all 3486types. @code{HANDLER_PARMS} is the @code{DECL_STMT} for the catch 3487parameter, and @code{HANDLER_BODY} is the code for the block itself. 3488 3489@item IF_STMT 3490 3491Used to represent an @code{if} statement. The @code{IF_COND} is the 3492expression. 3493 3494If the condition is a @code{TREE_LIST}, then the @code{TREE_PURPOSE} is 3495a statement (usually a @code{DECL_STMT}). Each time the condition is 3496evaluated, the statement should be executed. Then, the 3497@code{TREE_VALUE} should be used as the conditional expression itself. 3498This representation is used to handle C++ code like this: 3499 3500@smallexample 3501if (int i = 7) @dots{} 3502@end smallexample 3503 3504where there is a new local variable (or variables) declared within the 3505condition. 3506 3507The @code{THEN_CLAUSE} represents the statement given by the @code{then} 3508condition, while the @code{ELSE_CLAUSE} represents the statement given 3509by the @code{else} condition. 3510 3511C++ distinguishes between this and @code{COND_EXPR} for handling templates. 3512 3513@item SUBOBJECT 3514 3515In a constructor, these nodes are used to mark the point at which a 3516subobject of @code{this} is fully constructed. If, after this point, an 3517exception is thrown before a @code{CTOR_STMT} with @code{CTOR_END_P} set 3518is encountered, the @code{SUBOBJECT_CLEANUP} must be executed. The 3519cleanups must be executed in the reverse order in which they appear. 3520 3521@item SWITCH_STMT 3522 3523Used to represent a @code{switch} statement. The @code{SWITCH_STMT_COND} 3524is the expression on which the switch is occurring. See the documentation 3525for an @code{IF_STMT} for more information on the representation used 3526for the condition. The @code{SWITCH_STMT_BODY} is the body of the switch 3527statement. The @code{SWITCH_STMT_TYPE} is the original type of switch 3528expression as given in the source, before any compiler conversions. 3529The @code{SWITCH_STMT_SCOPE} is the statement scope (used in the 3530C++ front end only). 3531 3532There are also two boolean flags used with @code{SWITCH_STMT}. 3533@code{SWITCH_STMT_ALL_CASES_P} is true if the switch includes a default label 3534or the case label ranges cover all possible values of the condition 3535expression. @code{SWITCH_STMT_NO_BREAK_P} is true if there are no 3536@code{break} statements in the switch. 3537 3538@item TRY_BLOCK 3539Used to represent a @code{try} block. The body of the try block is 3540given by @code{TRY_STMTS}. Each of the catch blocks is a @code{HANDLER} 3541node. The first handler is given by @code{TRY_HANDLERS}. Subsequent 3542handlers are obtained by following the @code{TREE_CHAIN} link from one 3543handler to the next. The body of the handler is given by 3544@code{HANDLER_BODY}. 3545 3546If @code{CLEANUP_P} holds of the @code{TRY_BLOCK}, then the 3547@code{TRY_HANDLERS} will not be a @code{HANDLER} node. Instead, it will 3548be an expression that should be executed if an exception is thrown in 3549the try block. It must rethrow the exception after executing that code. 3550And, if an exception is thrown while the expression is executing, 3551@code{terminate} must be called. 3552 3553@item USING_STMT 3554Used to represent a @code{using} directive. The namespace is given by 3555@code{USING_STMT_NAMESPACE}, which will be a NAMESPACE_DECL@. This node 3556is needed inside template functions, to implement using directives 3557during instantiation. 3558 3559@item WHILE_STMT 3560 3561Used to represent a @code{while} loop. The @code{WHILE_COND} is the 3562termination condition for the loop. See the documentation for an 3563@code{IF_STMT} for more information on the representation used for the 3564condition. 3565 3566The @code{WHILE_BODY} is the body of the loop. 3567 3568@end table 3569 3570@node C++ Expressions 3571@subsection C++ Expressions 3572 3573This section describes expressions specific to the C and C++ front 3574ends. 3575 3576@table @code 3577@item TYPEID_EXPR 3578 3579Used to represent a @code{typeid} expression. 3580 3581@item NEW_EXPR 3582@itemx VEC_NEW_EXPR 3583 3584Used to represent a call to @code{new} and @code{new[]} respectively. 3585 3586@item DELETE_EXPR 3587@itemx VEC_DELETE_EXPR 3588 3589Used to represent a call to @code{delete} and @code{delete[]} respectively. 3590 3591@item MEMBER_REF 3592 3593Represents a reference to a member of a class. 3594 3595@item THROW_EXPR 3596 3597Represents an instance of @code{throw} in the program. Operand 0, 3598which is the expression to throw, may be @code{NULL_TREE}. 3599 3600 3601@item AGGR_INIT_EXPR 3602An @code{AGGR_INIT_EXPR} represents the initialization as the return 3603value of a function call, or as the result of a constructor. An 3604@code{AGGR_INIT_EXPR} will only appear as a full-expression, or as the 3605second operand of a @code{TARGET_EXPR}. @code{AGGR_INIT_EXPR}s have 3606a representation similar to that of @code{CALL_EXPR}s. You can use 3607the @code{AGGR_INIT_EXPR_FN} and @code{AGGR_INIT_EXPR_ARG} macros to access 3608the function to call and the arguments to pass. 3609 3610If @code{AGGR_INIT_VIA_CTOR_P} holds of the @code{AGGR_INIT_EXPR}, then 3611the initialization is via a constructor call. The address of the 3612@code{AGGR_INIT_EXPR_SLOT} operand, which is always a @code{VAR_DECL}, 3613is taken, and this value replaces the first argument in the argument 3614list. 3615 3616In either case, the expression is void. 3617 3618 3619@end table 3620