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