1@c Copyright (c) 2004, 2005, 2007, 2008, 2010 Free Software Foundation, Inc. 2@c Free Software Foundation, Inc. 3@c This is part of the GCC manual. 4@c For copying conditions, see the file gcc.texi. 5 6@c --------------------------------------------------------------------- 7@c GENERIC 8@c --------------------------------------------------------------------- 9 10@node GENERIC 11@chapter GENERIC 12@cindex GENERIC 13 14The purpose of GENERIC is simply to provide a 15language-independent way of representing an entire function in 16trees. To this end, it was necessary to add a few new tree codes 17to the back end, but most everything was already there. If you 18can express it with the codes in @code{gcc/tree.def}, it's 19GENERIC@. 20 21Early on, there was a great deal of debate about how to think 22about statements in a tree IL@. In GENERIC, a statement is 23defined as any expression whose value, if any, is ignored. A 24statement will always have @code{TREE_SIDE_EFFECTS} set (or it 25will be discarded), but a non-statement expression may also have 26side effects. A @code{CALL_EXPR}, for instance. 27 28It would be possible for some local optimizations to work on the 29GENERIC form of a function; indeed, the adapted tree inliner 30works fine on GENERIC, but the current compiler performs inlining 31after lowering to GIMPLE (a restricted form described in the next 32section). Indeed, currently the frontends perform this lowering 33before handing off to @code{tree_rest_of_compilation}, but this 34seems inelegant. 35 36@menu 37* Deficiencies:: Topics net yet covered in this document. 38* Tree overview:: All about @code{tree}s. 39* Types:: Fundamental and aggregate types. 40* Declarations:: Type declarations and variables. 41* Attributes:: Declaration and type attributes. 42* Expressions: Expression trees. Operating on data. 43* Statements:: Control flow and related trees. 44* Functions:: Function bodies, linkage, and other aspects. 45* Language-dependent trees:: Topics and trees specific to language front ends. 46* C and C++ Trees:: Trees specific to C and C++. 47* Java Trees:: Trees specific to Java. 48@end menu 49 50@c --------------------------------------------------------------------- 51@c Deficiencies 52@c --------------------------------------------------------------------- 53 54@node Deficiencies 55@section Deficiencies 56 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 207that 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 928@end table 929 930 931@c --------------------------------------------------------------------- 932@c Attributes 933@c --------------------------------------------------------------------- 934@node Attributes 935@section Attributes in trees 936@cindex attributes 937 938Attributes, as specified using the @code{__attribute__} keyword, are 939represented internally as a @code{TREE_LIST}. The @code{TREE_PURPOSE} 940is the name of the attribute, as an @code{IDENTIFIER_NODE}. The 941@code{TREE_VALUE} is a @code{TREE_LIST} of the arguments of the 942attribute, if any, or @code{NULL_TREE} if there are no arguments; the 943arguments are stored as the @code{TREE_VALUE} of successive entries in 944the list, and may be identifiers or expressions. The @code{TREE_CHAIN} 945of the attribute is the next attribute in a list of attributes applying 946to the same declaration or type, or @code{NULL_TREE} if there are no 947further attributes in the list. 948 949Attributes may be attached to declarations and to types; these 950attributes may be accessed with the following macros. All attributes 951are stored in this way, and many also cause other changes to the 952declaration or type or to other internal compiler data structures. 953 954@deftypefn {Tree Macro} tree DECL_ATTRIBUTES (tree @var{decl}) 955This macro returns the attributes on the declaration @var{decl}. 956@end deftypefn 957 958@deftypefn {Tree Macro} tree TYPE_ATTRIBUTES (tree @var{type}) 959This macro returns the attributes on the type @var{type}. 960@end deftypefn 961 962 963@c --------------------------------------------------------------------- 964@c Expressions 965@c --------------------------------------------------------------------- 966 967@node Expression trees 968@section Expressions 969@cindex expression 970@findex TREE_TYPE 971@findex TREE_OPERAND 972 973The internal representation for expressions is for the most part quite 974straightforward. However, there are a few facts that one must bear in 975mind. In particular, the expression ``tree'' is actually a directed 976acyclic graph. (For example there may be many references to the integer 977constant zero throughout the source program; many of these will be 978represented by the same expression node.) You should not rely on 979certain kinds of node being shared, nor should you rely on certain kinds of 980nodes being unshared. 981 982The following macros can be used with all expression nodes: 983 984@ftable @code 985@item TREE_TYPE 986Returns the type of the expression. This value may not be precisely the 987same type that would be given the expression in the original program. 988@end ftable 989 990In what follows, some nodes that one might expect to always have type 991@code{bool} are documented to have either integral or boolean type. At 992some point in the future, the C front end may also make use of this same 993intermediate representation, and at this point these nodes will 994certainly have integral type. The previous sentence is not meant to 995imply that the C++ front end does not or will not give these nodes 996integral type. 997 998Below, we list the various kinds of expression nodes. Except where 999noted otherwise, the operands to an expression are accessed using the 1000@code{TREE_OPERAND} macro. For example, to access the first operand to 1001a binary plus expression @code{expr}, use: 1002 1003@smallexample 1004TREE_OPERAND (expr, 0) 1005@end smallexample 1006@noindent 1007 1008As this example indicates, the operands are zero-indexed. 1009 1010 1011@menu 1012* Constants: Constant expressions. 1013* Storage References:: 1014* Unary and Binary Expressions:: 1015* Vectors:: 1016@end menu 1017 1018@node Constant expressions 1019@subsection Constant expressions 1020@tindex INTEGER_CST 1021@findex TREE_INT_CST_HIGH 1022@findex TREE_INT_CST_LOW 1023@findex tree_int_cst_lt 1024@findex tree_int_cst_equal 1025@tindex REAL_CST 1026@tindex FIXED_CST 1027@tindex COMPLEX_CST 1028@tindex VECTOR_CST 1029@tindex STRING_CST 1030@findex TREE_STRING_LENGTH 1031@findex TREE_STRING_POINTER 1032 1033The table below begins with constants, moves on to unary expressions, 1034then proceeds to binary expressions, and concludes with various other 1035kinds of expressions: 1036 1037@table @code 1038@item INTEGER_CST 1039These nodes represent integer constants. Note that the type of these 1040constants is obtained with @code{TREE_TYPE}; they are not always of type 1041@code{int}. In particular, @code{char} constants are represented with 1042@code{INTEGER_CST} nodes. The value of the integer constant @code{e} is 1043given by 1044@smallexample 1045((TREE_INT_CST_HIGH (e) << HOST_BITS_PER_WIDE_INT) 1046+ TREE_INST_CST_LOW (e)) 1047@end smallexample 1048@noindent 1049HOST_BITS_PER_WIDE_INT is at least thirty-two on all platforms. Both 1050@code{TREE_INT_CST_HIGH} and @code{TREE_INT_CST_LOW} return a 1051@code{HOST_WIDE_INT}. The value of an @code{INTEGER_CST} is interpreted 1052as a signed or unsigned quantity depending on the type of the constant. 1053In general, the expression given above will overflow, so it should not 1054be used to calculate the value of the constant. 1055 1056The variable @code{integer_zero_node} is an integer constant with value 1057zero. Similarly, @code{integer_one_node} is an integer constant with 1058value one. The @code{size_zero_node} and @code{size_one_node} variables 1059are analogous, but have type @code{size_t} rather than @code{int}. 1060 1061The function @code{tree_int_cst_lt} is a predicate which holds if its 1062first argument is less than its second. Both constants are assumed to 1063have the same signedness (i.e., either both should be signed or both 1064should be unsigned.) The full width of the constant is used when doing 1065the comparison; the usual rules about promotions and conversions are 1066ignored. Similarly, @code{tree_int_cst_equal} holds if the two 1067constants are equal. The @code{tree_int_cst_sgn} function returns the 1068sign of a constant. The value is @code{1}, @code{0}, or @code{-1} 1069according on whether the constant is greater than, equal to, or less 1070than zero. Again, the signedness of the constant's type is taken into 1071account; an unsigned constant is never less than zero, no matter what 1072its bit-pattern. 1073 1074@item REAL_CST 1075 1076FIXME: Talk about how to obtain representations of this constant, do 1077comparisons, and so forth. 1078 1079@item FIXED_CST 1080 1081These nodes represent fixed-point constants. The type of these constants 1082is obtained with @code{TREE_TYPE}. @code{TREE_FIXED_CST_PTR} points to 1083a @code{struct fixed_value}; @code{TREE_FIXED_CST} returns the structure 1084itself. @code{struct fixed_value} contains @code{data} with the size of two 1085@code{HOST_BITS_PER_WIDE_INT} and @code{mode} as the associated fixed-point 1086machine mode for @code{data}. 1087 1088@item COMPLEX_CST 1089These nodes are used to represent complex number constants, that is a 1090@code{__complex__} whose parts are constant nodes. The 1091@code{TREE_REALPART} and @code{TREE_IMAGPART} return the real and the 1092imaginary parts respectively. 1093 1094@item VECTOR_CST 1095These nodes are used to represent vector constants, whose parts are 1096constant nodes. Each individual constant node is either an integer or a 1097double constant node. The first operand is a @code{TREE_LIST} of the 1098constant nodes and is accessed through @code{TREE_VECTOR_CST_ELTS}. 1099 1100@item STRING_CST 1101These nodes represent string-constants. The @code{TREE_STRING_LENGTH} 1102returns the length of the string, as an @code{int}. The 1103@code{TREE_STRING_POINTER} is a @code{char*} containing the string 1104itself. The string may not be @code{NUL}-terminated, and it may contain 1105embedded @code{NUL} characters. Therefore, the 1106@code{TREE_STRING_LENGTH} includes the trailing @code{NUL} if it is 1107present. 1108 1109For wide string constants, the @code{TREE_STRING_LENGTH} is the number 1110of bytes in the string, and the @code{TREE_STRING_POINTER} 1111points to an array of the bytes of the string, as represented on the 1112target system (that is, as integers in the target endianness). Wide and 1113non-wide string constants are distinguished only by the @code{TREE_TYPE} 1114of the @code{STRING_CST}. 1115 1116FIXME: The formats of string constants are not well-defined when the 1117target system bytes are not the same width as host system bytes. 1118 1119@end table 1120 1121@node Storage References 1122@subsection References to storage 1123@tindex ADDR_EXPR 1124@tindex INDIRECT_REF 1125@tindex ARRAY_REF 1126@tindex ARRAY_RANGE_REF 1127@tindex TARGET_MEM_REF 1128@tindex COMPONENT_REF 1129 1130@table @code 1131@item ARRAY_REF 1132These nodes represent array accesses. The first operand is the array; 1133the second is the index. To calculate the address of the memory 1134accessed, you must scale the index by the size of the type of the array 1135elements. The type of these expressions must be the type of a component of 1136the array. The third and fourth operands are used after gimplification 1137to represent the lower bound and component size but should not be used 1138directly; call @code{array_ref_low_bound} and @code{array_ref_element_size} 1139instead. 1140 1141@item ARRAY_RANGE_REF 1142These nodes represent access to a range (or ``slice'') of an array. The 1143operands are the same as that for @code{ARRAY_REF} and have the same 1144meanings. The type of these expressions must be an array whose component 1145type is the same as that of the first operand. The range of that array 1146type determines the amount of data these expressions access. 1147 1148@item TARGET_MEM_REF 1149These nodes represent memory accesses whose address directly map to 1150an addressing mode of the target architecture. The first argument 1151is @code{TMR_SYMBOL} and must be a @code{VAR_DECL} of an object with 1152a fixed address. The second argument is @code{TMR_BASE} and the 1153third one is @code{TMR_INDEX}. The fourth argument is 1154@code{TMR_STEP} and must be an @code{INTEGER_CST}. The fifth 1155argument is @code{TMR_OFFSET} and must be an @code{INTEGER_CST}. 1156Any of the arguments may be NULL if the appropriate component 1157does not appear in the address. Address of the @code{TARGET_MEM_REF} 1158is determined in the following way. 1159 1160@smallexample 1161&TMR_SYMBOL + TMR_BASE + TMR_INDEX * TMR_STEP + TMR_OFFSET 1162@end smallexample 1163 1164The sixth argument is the reference to the original memory access, which 1165is preserved for the purposes of the RTL alias analysis. The seventh 1166argument is a tag representing the results of tree level alias analysis. 1167 1168@item ADDR_EXPR 1169These nodes are used to represent the address of an object. (These 1170expressions will always have pointer or reference type.) The operand may 1171be another expression, or it may be a declaration. 1172 1173As an extension, GCC allows users to take the address of a label. In 1174this case, the operand of the @code{ADDR_EXPR} will be a 1175@code{LABEL_DECL}. The type of such an expression is @code{void*}. 1176 1177If the object addressed is not an lvalue, a temporary is created, and 1178the address of the temporary is used. 1179 1180@item INDIRECT_REF 1181These nodes are used to represent the object pointed to by a pointer. 1182The operand is the pointer being dereferenced; it will always have 1183pointer or reference type. 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 RDIV_EXPR 1231@tindex TRUNC_DIV_EXPR 1232@tindex FLOOR_DIV_EXPR 1233@tindex CEIL_DIV_EXPR 1234@tindex ROUND_DIV_EXPR 1235@tindex TRUNC_MOD_EXPR 1236@tindex FLOOR_MOD_EXPR 1237@tindex CEIL_MOD_EXPR 1238@tindex ROUND_MOD_EXPR 1239@tindex EXACT_DIV_EXPR 1240@tindex LT_EXPR 1241@tindex LE_EXPR 1242@tindex GT_EXPR 1243@tindex GE_EXPR 1244@tindex EQ_EXPR 1245@tindex NE_EXPR 1246@tindex ORDERED_EXPR 1247@tindex UNORDERED_EXPR 1248@tindex UNLT_EXPR 1249@tindex UNLE_EXPR 1250@tindex UNGT_EXPR 1251@tindex UNGE_EXPR 1252@tindex UNEQ_EXPR 1253@tindex LTGT_EXPR 1254@tindex MODIFY_EXPR 1255@tindex INIT_EXPR 1256@tindex COMPOUND_EXPR 1257@tindex COND_EXPR 1258@tindex CALL_EXPR 1259@tindex STMT_EXPR 1260@tindex BIND_EXPR 1261@tindex LOOP_EXPR 1262@tindex EXIT_EXPR 1263@tindex CLEANUP_POINT_EXPR 1264@tindex CONSTRUCTOR 1265@tindex COMPOUND_LITERAL_EXPR 1266@tindex SAVE_EXPR 1267@tindex TARGET_EXPR 1268@tindex VA_ARG_EXPR 1269 1270@table @code 1271@item NEGATE_EXPR 1272These nodes represent unary negation of the single operand, for both 1273integer and floating-point types. The type of negation can be 1274determined by looking at the type of the expression. 1275 1276The behavior of this operation on signed arithmetic overflow is 1277controlled by the @code{flag_wrapv} and @code{flag_trapv} variables. 1278 1279@item ABS_EXPR 1280These nodes represent the absolute value of the single operand, for 1281both integer and floating-point types. This is typically used to 1282implement the @code{abs}, @code{labs} and @code{llabs} builtins for 1283integer types, and the @code{fabs}, @code{fabsf} and @code{fabsl} 1284builtins for floating point types. The type of abs operation can 1285be determined by looking at the type of the expression. 1286 1287This node is not used for complex types. To represent the modulus 1288or complex abs of a complex value, use the @code{BUILT_IN_CABS}, 1289@code{BUILT_IN_CABSF} or @code{BUILT_IN_CABSL} builtins, as used 1290to implement the C99 @code{cabs}, @code{cabsf} and @code{cabsl} 1291built-in functions. 1292 1293@item BIT_NOT_EXPR 1294These nodes represent bitwise complement, and will always have integral 1295type. The only operand is the value to be complemented. 1296 1297@item TRUTH_NOT_EXPR 1298These nodes represent logical negation, and will always have integral 1299(or boolean) type. The operand is the value being negated. The type 1300of the operand and that of the result are always of @code{BOOLEAN_TYPE} 1301or @code{INTEGER_TYPE}. 1302 1303@item PREDECREMENT_EXPR 1304@itemx PREINCREMENT_EXPR 1305@itemx POSTDECREMENT_EXPR 1306@itemx POSTINCREMENT_EXPR 1307These nodes represent increment and decrement expressions. The value of 1308the single operand is computed, and the operand incremented or 1309decremented. In the case of @code{PREDECREMENT_EXPR} and 1310@code{PREINCREMENT_EXPR}, the value of the expression is the value 1311resulting after the increment or decrement; in the case of 1312@code{POSTDECREMENT_EXPR} and @code{POSTINCREMENT_EXPR} is the value 1313before the increment or decrement occurs. The type of the operand, like 1314that of the result, will be either integral, boolean, or floating-point. 1315 1316@item FIX_TRUNC_EXPR 1317These nodes represent conversion of a floating-point value to an 1318integer. The single operand will have a floating-point type, while 1319the complete expression will have an integral (or boolean) type. The 1320operand is rounded towards zero. 1321 1322@item FLOAT_EXPR 1323These nodes represent conversion of an integral (or boolean) value to a 1324floating-point value. The single operand will have integral type, while 1325the complete expression will have a floating-point type. 1326 1327FIXME: How is the operand supposed to be rounded? Is this dependent on 1328@option{-mieee}? 1329 1330@item COMPLEX_EXPR 1331These nodes are used to represent complex numbers constructed from two 1332expressions of the same (integer or real) type. The first operand is the 1333real part and the second operand is the imaginary part. 1334 1335@item CONJ_EXPR 1336These nodes represent the conjugate of their operand. 1337 1338@item REALPART_EXPR 1339@itemx IMAGPART_EXPR 1340These nodes represent respectively the real and the imaginary parts 1341of complex numbers (their sole argument). 1342 1343@item NON_LVALUE_EXPR 1344These nodes indicate that their one and only operand is not an lvalue. 1345A back end can treat these identically to the single operand. 1346 1347@item NOP_EXPR 1348These nodes are used to represent conversions that do not require any 1349code-generation. For example, conversion of a @code{char*} to an 1350@code{int*} does not require any code be generated; such a conversion is 1351represented by a @code{NOP_EXPR}. The single operand is the expression 1352to be converted. The conversion from a pointer to a reference is also 1353represented with a @code{NOP_EXPR}. 1354 1355@item CONVERT_EXPR 1356These nodes are similar to @code{NOP_EXPR}s, but are used in those 1357situations where code may need to be generated. For example, if an 1358@code{int*} is converted to an @code{int} code may need to be generated 1359on some platforms. These nodes are never used for C++-specific 1360conversions, like conversions between pointers to different classes in 1361an inheritance hierarchy. Any adjustments that need to be made in such 1362cases are always indicated explicitly. Similarly, a user-defined 1363conversion is never represented by a @code{CONVERT_EXPR}; instead, the 1364function calls are made explicit. 1365 1366@item FIXED_CONVERT_EXPR 1367These nodes are used to represent conversions that involve fixed-point 1368values. For example, from a fixed-point value to another fixed-point value, 1369from an integer to a fixed-point value, from a fixed-point value to an 1370integer, from a floating-point value to a fixed-point value, or from 1371a fixed-point value to a floating-point value. 1372 1373@item LSHIFT_EXPR 1374@itemx RSHIFT_EXPR 1375These nodes represent left and right shifts, respectively. The first 1376operand is the value to shift; it will always be of integral type. The 1377second operand is an expression for the number of bits by which to 1378shift. Right shift should be treated as arithmetic, i.e., the 1379high-order bits should be zero-filled when the expression has unsigned 1380type and filled with the sign bit when the expression has signed type. 1381Note that the result is undefined if the second operand is larger 1382than or equal to the first operand's type size. 1383 1384 1385@item BIT_IOR_EXPR 1386@itemx BIT_XOR_EXPR 1387@itemx BIT_AND_EXPR 1388These nodes represent bitwise inclusive or, bitwise exclusive or, and 1389bitwise and, respectively. Both operands will always have integral 1390type. 1391 1392@item TRUTH_ANDIF_EXPR 1393@itemx TRUTH_ORIF_EXPR 1394These nodes represent logical ``and'' and logical ``or'', respectively. 1395These operators are not strict; i.e., the second operand is evaluated 1396only if the value of the expression is not determined by evaluation of 1397the first operand. The type of the operands and that of the result are 1398always of @code{BOOLEAN_TYPE} or @code{INTEGER_TYPE}. 1399 1400@item TRUTH_AND_EXPR 1401@itemx TRUTH_OR_EXPR 1402@itemx TRUTH_XOR_EXPR 1403These nodes represent logical and, logical or, and logical exclusive or. 1404They are strict; both arguments are always evaluated. There are no 1405corresponding operators in C or C++, but the front end will sometimes 1406generate these expressions anyhow, if it can tell that strictness does 1407not matter. The type of the operands and that of the result are 1408always of @code{BOOLEAN_TYPE} or @code{INTEGER_TYPE}. 1409 1410@itemx POINTER_PLUS_EXPR 1411This node represents pointer arithmetic. The first operand is always 1412a pointer/reference type. The second operand is always an unsigned 1413integer type compatible with sizetype. This is the only binary 1414arithmetic operand that can operate on pointer types. 1415 1416@itemx PLUS_EXPR 1417@itemx MINUS_EXPR 1418@itemx MULT_EXPR 1419These nodes represent various binary arithmetic operations. 1420Respectively, these operations are addition, subtraction (of the second 1421operand from the first) and multiplication. Their operands may have 1422either integral or floating type, but there will never be case in which 1423one operand is of floating type and the other is of integral type. 1424 1425The behavior of these operations on signed arithmetic overflow is 1426controlled by the @code{flag_wrapv} and @code{flag_trapv} variables. 1427 1428@item RDIV_EXPR 1429This node represents a floating point division operation. 1430 1431@item TRUNC_DIV_EXPR 1432@itemx FLOOR_DIV_EXPR 1433@itemx CEIL_DIV_EXPR 1434@itemx ROUND_DIV_EXPR 1435These nodes represent integer division operations that return an integer 1436result. @code{TRUNC_DIV_EXPR} rounds towards zero, @code{FLOOR_DIV_EXPR} 1437rounds towards negative infinity, @code{CEIL_DIV_EXPR} rounds towards 1438positive infinity and @code{ROUND_DIV_EXPR} rounds to the closest integer. 1439Integer division in C and C++ is truncating, i.e.@: @code{TRUNC_DIV_EXPR}. 1440 1441The behavior of these operations on signed arithmetic overflow, when 1442dividing the minimum signed integer by minus one, is controlled by the 1443@code{flag_wrapv} and @code{flag_trapv} variables. 1444 1445@item TRUNC_MOD_EXPR 1446@itemx FLOOR_MOD_EXPR 1447@itemx CEIL_MOD_EXPR 1448@itemx ROUND_MOD_EXPR 1449These nodes represent the integer remainder or modulus operation. 1450The integer modulus of two operands @code{a} and @code{b} is 1451defined as @code{a - (a/b)*b} where the division calculated using 1452the corresponding division operator. Hence for @code{TRUNC_MOD_EXPR} 1453this definition assumes division using truncation towards zero, i.e.@: 1454@code{TRUNC_DIV_EXPR}. Integer remainder in C and C++ uses truncating 1455division, i.e.@: @code{TRUNC_MOD_EXPR}. 1456 1457@item EXACT_DIV_EXPR 1458The @code{EXACT_DIV_EXPR} code is used to represent integer divisions where 1459the numerator is known to be an exact multiple of the denominator. This 1460allows the backend to choose between the faster of @code{TRUNC_DIV_EXPR}, 1461@code{CEIL_DIV_EXPR} and @code{FLOOR_DIV_EXPR} for the current target. 1462 1463@item LT_EXPR 1464@itemx LE_EXPR 1465@itemx GT_EXPR 1466@itemx GE_EXPR 1467@itemx EQ_EXPR 1468@itemx NE_EXPR 1469These nodes represent the less than, less than or equal to, greater 1470than, greater than or equal to, equal, and not equal comparison 1471operators. The first and second operand with either be both of integral 1472type or both of floating type. The result type of these expressions 1473will always be of integral or boolean type. These operations return 1474the result type's zero value for false, and the result type's one value 1475for true. 1476 1477For floating point comparisons, if we honor IEEE NaNs and either operand 1478is NaN, then @code{NE_EXPR} always returns true and the remaining operators 1479always return false. On some targets, comparisons against an IEEE NaN, 1480other than equality and inequality, may generate a floating point exception. 1481 1482@item ORDERED_EXPR 1483@itemx UNORDERED_EXPR 1484These nodes represent non-trapping ordered and unordered comparison 1485operators. These operations take two floating point operands and 1486determine whether they are ordered or unordered relative to each other. 1487If either operand is an IEEE NaN, their comparison is defined to be 1488unordered, otherwise the comparison is defined to be ordered. The 1489result type of these expressions will always be of integral or boolean 1490type. These operations return the result type's zero value for false, 1491and the result type's one value for true. 1492 1493@item UNLT_EXPR 1494@itemx UNLE_EXPR 1495@itemx UNGT_EXPR 1496@itemx UNGE_EXPR 1497@itemx UNEQ_EXPR 1498@itemx LTGT_EXPR 1499These nodes represent the unordered comparison operators. 1500These operations take two floating point operands and determine whether 1501the operands are unordered or are less than, less than or equal to, 1502greater than, greater than or equal to, or equal respectively. For 1503example, @code{UNLT_EXPR} returns true if either operand is an IEEE 1504NaN or the first operand is less than the second. With the possible 1505exception of @code{LTGT_EXPR}, all of these operations are guaranteed 1506not to generate a floating point exception. The result 1507type of these expressions will always be of integral or boolean type. 1508These operations return the result type's zero value for false, 1509and the result type's one value for true. 1510 1511@item MODIFY_EXPR 1512These nodes represent assignment. The left-hand side is the first 1513operand; the right-hand side is the second operand. The left-hand side 1514will be a @code{VAR_DECL}, @code{INDIRECT_REF}, @code{COMPONENT_REF}, or 1515other lvalue. 1516 1517These nodes are used to represent not only assignment with @samp{=} but 1518also compound assignments (like @samp{+=}), by reduction to @samp{=} 1519assignment. In other words, the representation for @samp{i += 3} looks 1520just like that for @samp{i = i + 3}. 1521 1522@item INIT_EXPR 1523These nodes are just like @code{MODIFY_EXPR}, but are used only when a 1524variable is initialized, rather than assigned to subsequently. This 1525means that we can assume that the target of the initialization is not 1526used in computing its own value; any reference to the lhs in computing 1527the rhs is undefined. 1528 1529@item COMPOUND_EXPR 1530These nodes represent comma-expressions. The first operand is an 1531expression whose value is computed and thrown away prior to the 1532evaluation of the second operand. The value of the entire expression is 1533the value of the second operand. 1534 1535@item COND_EXPR 1536These nodes represent @code{?:} expressions. The first operand 1537is of boolean or integral type. If it evaluates to a nonzero value, 1538the second operand should be evaluated, and returned as the value of the 1539expression. Otherwise, the third operand is evaluated, and returned as 1540the value of the expression. 1541 1542The second operand must have the same type as the entire expression, 1543unless it unconditionally throws an exception or calls a noreturn 1544function, in which case it should have void type. The same constraints 1545apply to the third operand. This allows array bounds checks to be 1546represented conveniently as @code{(i >= 0 && i < 10) ? i : abort()}. 1547 1548As a GNU extension, the C language front-ends allow the second 1549operand of the @code{?:} operator may be omitted in the source. 1550For example, @code{x ? : 3} is equivalent to @code{x ? x : 3}, 1551assuming that @code{x} is an expression without side-effects. 1552In the tree representation, however, the second operand is always 1553present, possibly protected by @code{SAVE_EXPR} if the first 1554argument does cause side-effects. 1555 1556@item CALL_EXPR 1557These nodes are used to represent calls to functions, including 1558non-static member functions. @code{CALL_EXPR}s are implemented as 1559expression nodes with a variable number of operands. Rather than using 1560@code{TREE_OPERAND} to extract them, it is preferable to use the 1561specialized accessor macros and functions that operate specifically on 1562@code{CALL_EXPR} nodes. 1563 1564@code{CALL_EXPR_FN} returns a pointer to the 1565function to call; it is always an expression whose type is a 1566@code{POINTER_TYPE}. 1567 1568The number of arguments to the call is returned by @code{call_expr_nargs}, 1569while the arguments themselves can be accessed with the @code{CALL_EXPR_ARG} 1570macro. The arguments are zero-indexed and numbered left-to-right. 1571You can iterate over the arguments using @code{FOR_EACH_CALL_EXPR_ARG}, as in: 1572 1573@smallexample 1574tree call, arg; 1575call_expr_arg_iterator iter; 1576FOR_EACH_CALL_EXPR_ARG (arg, iter, call) 1577 /* arg is bound to successive arguments of call. */ 1578 @dots{}; 1579@end smallexample 1580 1581For non-static 1582member functions, there will be an operand corresponding to the 1583@code{this} pointer. There will always be expressions corresponding to 1584all of the arguments, even if the function is declared with default 1585arguments and some arguments are not explicitly provided at the call 1586sites. 1587 1588@code{CALL_EXPR}s also have a @code{CALL_EXPR_STATIC_CHAIN} operand that 1589is used to implement nested functions. This operand is otherwise null. 1590 1591@item CLEANUP_POINT_EXPR 1592These nodes represent full-expressions. The single operand is an 1593expression to evaluate. Any destructor calls engendered by the creation 1594of temporaries during the evaluation of that expression should be 1595performed immediately after the expression is evaluated. 1596 1597@item CONSTRUCTOR 1598These nodes represent the brace-enclosed initializers for a structure or 1599array. The first operand is reserved for use by the back end. The 1600second operand is a @code{TREE_LIST}. If the @code{TREE_TYPE} of the 1601@code{CONSTRUCTOR} is a @code{RECORD_TYPE} or @code{UNION_TYPE}, then 1602the @code{TREE_PURPOSE} of each node in the @code{TREE_LIST} will be a 1603@code{FIELD_DECL} and the @code{TREE_VALUE} of each node will be the 1604expression used to initialize that field. 1605 1606If the @code{TREE_TYPE} of the @code{CONSTRUCTOR} is an 1607@code{ARRAY_TYPE}, then the @code{TREE_PURPOSE} of each element in the 1608@code{TREE_LIST} will be an @code{INTEGER_CST} or a @code{RANGE_EXPR} of 1609two @code{INTEGER_CST}s. A single @code{INTEGER_CST} indicates which 1610element of the array (indexed from zero) is being assigned to. A 1611@code{RANGE_EXPR} indicates an inclusive range of elements to 1612initialize. In both cases the @code{TREE_VALUE} is the corresponding 1613initializer. It is re-evaluated for each element of a 1614@code{RANGE_EXPR}. If the @code{TREE_PURPOSE} is @code{NULL_TREE}, then 1615the initializer is for the next available array element. 1616 1617In the front end, you should not depend on the fields appearing in any 1618particular order. However, in the middle end, fields must appear in 1619declaration order. You should not assume that all fields will be 1620represented. Unrepresented fields will be set to zero. 1621 1622@item COMPOUND_LITERAL_EXPR 1623@findex COMPOUND_LITERAL_EXPR_DECL_EXPR 1624@findex COMPOUND_LITERAL_EXPR_DECL 1625These nodes represent ISO C99 compound literals. The 1626@code{COMPOUND_LITERAL_EXPR_DECL_EXPR} is a @code{DECL_EXPR} 1627containing an anonymous @code{VAR_DECL} for 1628the unnamed object represented by the compound literal; the 1629@code{DECL_INITIAL} of that @code{VAR_DECL} is a @code{CONSTRUCTOR} 1630representing the brace-enclosed list of initializers in the compound 1631literal. That anonymous @code{VAR_DECL} can also be accessed directly 1632by the @code{COMPOUND_LITERAL_EXPR_DECL} macro. 1633 1634@item SAVE_EXPR 1635 1636A @code{SAVE_EXPR} represents an expression (possibly involving 1637side-effects) that is used more than once. The side-effects should 1638occur only the first time the expression is evaluated. Subsequent uses 1639should just reuse the computed value. The first operand to the 1640@code{SAVE_EXPR} is the expression to evaluate. The side-effects should 1641be executed where the @code{SAVE_EXPR} is first encountered in a 1642depth-first preorder traversal of the expression tree. 1643 1644@item TARGET_EXPR 1645A @code{TARGET_EXPR} represents a temporary object. The first operand 1646is a @code{VAR_DECL} for the temporary variable. The second operand is 1647the initializer for the temporary. The initializer is evaluated and, 1648if non-void, copied (bitwise) into the temporary. If the initializer 1649is void, that means that it will perform the initialization itself. 1650 1651Often, a @code{TARGET_EXPR} occurs on the right-hand side of an 1652assignment, or as the second operand to a comma-expression which is 1653itself the right-hand side of an assignment, etc. In this case, we say 1654that the @code{TARGET_EXPR} is ``normal''; otherwise, we say it is 1655``orphaned''. For a normal @code{TARGET_EXPR} the temporary variable 1656should be treated as an alias for the left-hand side of the assignment, 1657rather than as a new temporary variable. 1658 1659The third operand to the @code{TARGET_EXPR}, if present, is a 1660cleanup-expression (i.e., destructor call) for the temporary. If this 1661expression is orphaned, then this expression must be executed when the 1662statement containing this expression is complete. These cleanups must 1663always be executed in the order opposite to that in which they were 1664encountered. Note that if a temporary is created on one branch of a 1665conditional operator (i.e., in the second or third operand to a 1666@code{COND_EXPR}), the cleanup must be run only if that branch is 1667actually executed. 1668 1669@item VA_ARG_EXPR 1670This node is used to implement support for the C/C++ variable argument-list 1671mechanism. It represents expressions like @code{va_arg (ap, type)}. 1672Its @code{TREE_TYPE} yields the tree representation for @code{type} and 1673its sole argument yields the representation for @code{ap}. 1674 1675@end table 1676 1677@node Vectors 1678@subsection Vectors 1679@tindex VEC_LSHIFT_EXPR 1680@tindex VEC_RSHIFT_EXPR 1681@tindex VEC_WIDEN_MULT_HI_EXPR 1682@tindex VEC_WIDEN_MULT_LO_EXPR 1683@tindex VEC_UNPACK_HI_EXPR 1684@tindex VEC_UNPACK_LO_EXPR 1685@tindex VEC_UNPACK_FLOAT_HI_EXPR 1686@tindex VEC_UNPACK_FLOAT_LO_EXPR 1687@tindex VEC_PACK_TRUNC_EXPR 1688@tindex VEC_PACK_SAT_EXPR 1689@tindex VEC_PACK_FIX_TRUNC_EXPR 1690@tindex VEC_EXTRACT_EVEN_EXPR 1691@tindex VEC_EXTRACT_ODD_EXPR 1692@tindex VEC_INTERLEAVE_HIGH_EXPR 1693@tindex VEC_INTERLEAVE_LOW_EXPR 1694 1695@table @code 1696@item VEC_LSHIFT_EXPR 1697@itemx VEC_RSHIFT_EXPR 1698These nodes represent whole vector left and right shifts, respectively. 1699The first operand is the vector to shift; it will always be of vector type. 1700The second operand is an expression for the number of bits by which to 1701shift. Note that the result is undefined if the second operand is larger 1702than or equal to the first operand's type size. 1703 1704@item VEC_WIDEN_MULT_HI_EXPR 1705@itemx VEC_WIDEN_MULT_LO_EXPR 1706These nodes represent widening vector multiplication of the high and low 1707parts of the two input vectors, respectively. Their operands are vectors 1708that contain the same number of elements (@code{N}) of the same integral type. 1709The result is a vector that contains half as many elements, of an integral type 1710whose size is twice as wide. In the case of @code{VEC_WIDEN_MULT_HI_EXPR} the 1711high @code{N/2} elements of the two vector are multiplied to produce the 1712vector of @code{N/2} products. In the case of @code{VEC_WIDEN_MULT_LO_EXPR} the 1713low @code{N/2} elements of the two vector are multiplied to produce the 1714vector of @code{N/2} products. 1715 1716@item VEC_UNPACK_HI_EXPR 1717@itemx VEC_UNPACK_LO_EXPR 1718These nodes represent unpacking of the high and low parts of the input vector, 1719respectively. The single operand is a vector that contains @code{N} elements 1720of the same integral or floating point type. The result is a vector 1721that contains half as many elements, of an integral or floating point type 1722whose size is twice as wide. In the case of @code{VEC_UNPACK_HI_EXPR} the 1723high @code{N/2} elements of the vector are extracted and widened (promoted). 1724In the case of @code{VEC_UNPACK_LO_EXPR} the low @code{N/2} elements of the 1725vector are extracted and widened (promoted). 1726 1727@item VEC_UNPACK_FLOAT_HI_EXPR 1728@itemx VEC_UNPACK_FLOAT_LO_EXPR 1729These nodes represent unpacking of the high and low parts of the input vector, 1730where the values are converted from fixed point to floating point. The 1731single operand is a vector that contains @code{N} elements of the same 1732integral type. The result is a vector that contains half as many elements 1733of a floating point type whose size is twice as wide. In the case of 1734@code{VEC_UNPACK_HI_EXPR} the high @code{N/2} elements of the vector are 1735extracted, converted and widened. In the case of @code{VEC_UNPACK_LO_EXPR} 1736the low @code{N/2} elements of the vector are extracted, converted and widened. 1737 1738@item VEC_PACK_TRUNC_EXPR 1739This node represents packing of truncated elements of the two input vectors 1740into the output vector. Input operands are vectors that contain the same 1741number of elements of the same integral or floating point type. The result 1742is a vector that contains twice as many elements of an integral or floating 1743point type whose size is half as wide. The elements of the two vectors are 1744demoted and merged (concatenated) to form the output vector. 1745 1746@item VEC_PACK_SAT_EXPR 1747This node represents packing of elements of the two input vectors into the 1748output vector using saturation. Input operands are vectors that contain 1749the same number of elements of the same integral type. The result is a 1750vector that contains twice as many elements of an integral type whose size 1751is half as wide. The elements of the two vectors are demoted and merged 1752(concatenated) to form the output vector. 1753 1754@item VEC_PACK_FIX_TRUNC_EXPR 1755This node represents packing of elements of the two input vectors into the 1756output vector, where the values are converted from floating point 1757to fixed point. Input operands are vectors that contain the same number 1758of elements of a floating point type. The result is a vector that contains 1759twice as many elements of an integral type whose size is half as wide. The 1760elements of the two vectors are merged (concatenated) to form the output 1761vector. 1762 1763@item VEC_EXTRACT_EVEN_EXPR 1764@itemx VEC_EXTRACT_ODD_EXPR 1765These nodes represent extracting of the even/odd elements of the two input 1766vectors, respectively. Their operands and result are vectors that contain the 1767same number of elements of the same type. 1768 1769@item VEC_INTERLEAVE_HIGH_EXPR 1770@itemx VEC_INTERLEAVE_LOW_EXPR 1771These nodes represent merging and interleaving of the high/low elements of the 1772two input vectors, respectively. The operands and the result are vectors that 1773contain the same number of elements (@code{N}) of the same type. 1774In the case of @code{VEC_INTERLEAVE_HIGH_EXPR}, the high @code{N/2} elements of 1775the first input vector are interleaved with the high @code{N/2} elements of the 1776second input vector. In the case of @code{VEC_INTERLEAVE_LOW_EXPR}, the low 1777@code{N/2} elements of the first input vector are interleaved with the low 1778@code{N/2} elements of the second input vector. 1779 1780@end table 1781 1782 1783@c --------------------------------------------------------------------- 1784@c Statements 1785@c --------------------------------------------------------------------- 1786 1787@node Statements 1788@section Statements 1789@cindex Statements 1790 1791Most statements in GIMPLE are assignment statements, represented by 1792@code{GIMPLE_ASSIGN}. No other C expressions can appear at statement level; 1793a reference to a volatile object is converted into a 1794@code{GIMPLE_ASSIGN}. 1795 1796There are also several varieties of complex statements. 1797 1798@menu 1799* Basic Statements:: 1800* Blocks:: 1801* Statement Sequences:: 1802* Empty Statements:: 1803* Jumps:: 1804* Cleanups:: 1805* OpenMP:: 1806@end menu 1807 1808@node Basic Statements 1809@subsection Basic Statements 1810@cindex Basic Statements 1811 1812@table @code 1813@item ASM_EXPR 1814 1815Used to represent an inline assembly statement. For an inline assembly 1816statement like: 1817@smallexample 1818asm ("mov x, y"); 1819@end smallexample 1820The @code{ASM_STRING} macro will return a @code{STRING_CST} node for 1821@code{"mov x, y"}. If the original statement made use of the 1822extended-assembly syntax, then @code{ASM_OUTPUTS}, 1823@code{ASM_INPUTS}, and @code{ASM_CLOBBERS} will be the outputs, inputs, 1824and clobbers for the statement, represented as @code{STRING_CST} nodes. 1825The extended-assembly syntax looks like: 1826@smallexample 1827asm ("fsinx %1,%0" : "=f" (result) : "f" (angle)); 1828@end smallexample 1829The first string is the @code{ASM_STRING}, containing the instruction 1830template. The next two strings are the output and inputs, respectively; 1831this statement has no clobbers. As this example indicates, ``plain'' 1832assembly statements are merely a special case of extended assembly 1833statements; they have no cv-qualifiers, outputs, inputs, or clobbers. 1834All of the strings will be @code{NUL}-terminated, and will contain no 1835embedded @code{NUL}-characters. 1836 1837If the assembly statement is declared @code{volatile}, or if the 1838statement was not an extended assembly statement, and is therefore 1839implicitly volatile, then the predicate @code{ASM_VOLATILE_P} will hold 1840of the @code{ASM_EXPR}. 1841 1842@item DECL_EXPR 1843 1844Used to represent a local declaration. The @code{DECL_EXPR_DECL} macro 1845can be used to obtain the entity declared. This declaration may be a 1846@code{LABEL_DECL}, indicating that the label declared is a local label. 1847(As an extension, GCC allows the declaration of labels with scope.) In 1848C, this declaration may be a @code{FUNCTION_DECL}, indicating the 1849use of the GCC nested function extension. For more information, 1850@pxref{Functions}. 1851 1852@item LABEL_EXPR 1853 1854Used to represent a label. The @code{LABEL_DECL} declared by this 1855statement can be obtained with the @code{LABEL_EXPR_LABEL} macro. The 1856@code{IDENTIFIER_NODE} giving the name of the label can be obtained from 1857the @code{LABEL_DECL} with @code{DECL_NAME}. 1858 1859@item GOTO_EXPR 1860 1861Used to represent a @code{goto} statement. The @code{GOTO_DESTINATION} will 1862usually be a @code{LABEL_DECL}. However, if the ``computed goto'' extension 1863has been used, the @code{GOTO_DESTINATION} will be an arbitrary expression 1864indicating the destination. This expression will always have pointer type. 1865 1866@item RETURN_EXPR 1867 1868Used to represent a @code{return} statement. Operand 0 represents the 1869value to return. It should either be the @code{RESULT_DECL} for the 1870containing function, or a @code{MODIFY_EXPR} or @code{INIT_EXPR} 1871setting the function's @code{RESULT_DECL}. It will be 1872@code{NULL_TREE} if the statement was just 1873@smallexample 1874return; 1875@end smallexample 1876 1877@item LOOP_EXPR 1878These nodes represent ``infinite'' loops. The @code{LOOP_EXPR_BODY} 1879represents the body of the loop. It should be executed forever, unless 1880an @code{EXIT_EXPR} is encountered. 1881 1882@item EXIT_EXPR 1883These nodes represent conditional exits from the nearest enclosing 1884@code{LOOP_EXPR}. The single operand is the condition; if it is 1885nonzero, then the loop should be exited. An @code{EXIT_EXPR} will only 1886appear within a @code{LOOP_EXPR}. 1887 1888@item SWITCH_STMT 1889 1890Used to represent a @code{switch} statement. The @code{SWITCH_STMT_COND} 1891is the expression on which the switch is occurring. See the documentation 1892for an @code{IF_STMT} for more information on the representation used 1893for the condition. The @code{SWITCH_STMT_BODY} is the body of the switch 1894statement. The @code{SWITCH_STMT_TYPE} is the original type of switch 1895expression as given in the source, before any compiler conversions. 1896 1897@item CASE_LABEL_EXPR 1898 1899Use to represent a @code{case} label, range of @code{case} labels, or a 1900@code{default} label. If @code{CASE_LOW} is @code{NULL_TREE}, then this is a 1901@code{default} label. Otherwise, if @code{CASE_HIGH} is @code{NULL_TREE}, then 1902this is an ordinary @code{case} label. In this case, @code{CASE_LOW} is 1903an expression giving the value of the label. Both @code{CASE_LOW} and 1904@code{CASE_HIGH} are @code{INTEGER_CST} nodes. These values will have 1905the same type as the condition expression in the switch statement. 1906 1907Otherwise, if both @code{CASE_LOW} and @code{CASE_HIGH} are defined, the 1908statement is a range of case labels. Such statements originate with the 1909extension that allows users to write things of the form: 1910@smallexample 1911case 2 ... 5: 1912@end smallexample 1913The first value will be @code{CASE_LOW}, while the second will be 1914@code{CASE_HIGH}. 1915 1916@end table 1917 1918 1919@node Blocks 1920@subsection Blocks 1921@cindex Blocks 1922 1923Block scopes and the variables they declare in GENERIC are 1924expressed using the @code{BIND_EXPR} code, which in previous 1925versions of GCC was primarily used for the C statement-expression 1926extension. 1927 1928Variables in a block are collected into @code{BIND_EXPR_VARS} in 1929declaration order through their @code{TREE_CHAIN} field. Any runtime 1930initialization is moved out of @code{DECL_INITIAL} and into a 1931statement in the controlled block. When gimplifying from C or C++, 1932this initialization replaces the @code{DECL_STMT}. These variables 1933will never require cleanups. The scope of these variables is just the 1934body 1935 1936Variable-length arrays (VLAs) complicate this process, as their 1937size often refers to variables initialized earlier in the block. 1938To handle this, we currently split the block at that point, and 1939move the VLA into a new, inner @code{BIND_EXPR}. This strategy 1940may change in the future. 1941 1942A C++ program will usually contain more @code{BIND_EXPR}s than 1943there are syntactic blocks in the source code, since several C++ 1944constructs have implicit scopes associated with them. On the 1945other hand, although the C++ front end uses pseudo-scopes to 1946handle cleanups for objects with destructors, these don't 1947translate into the GIMPLE form; multiple declarations at the same 1948level use the same @code{BIND_EXPR}. 1949 1950@node Statement Sequences 1951@subsection Statement Sequences 1952@cindex Statement Sequences 1953 1954Multiple statements at the same nesting level are collected into 1955a @code{STATEMENT_LIST}. Statement lists are modified and 1956traversed using the interface in @samp{tree-iterator.h}. 1957 1958@node Empty Statements 1959@subsection Empty Statements 1960@cindex Empty Statements 1961 1962Whenever possible, statements with no effect are discarded. But 1963if they are nested within another construct which cannot be 1964discarded for some reason, they are instead replaced with an 1965empty statement, generated by @code{build_empty_stmt}. 1966Initially, all empty statements were shared, after the pattern of 1967the Java front end, but this caused a lot of trouble in practice. 1968 1969An empty statement is represented as @code{(void)0}. 1970 1971@node Jumps 1972@subsection Jumps 1973@cindex Jumps 1974 1975Other jumps are expressed by either @code{GOTO_EXPR} or 1976@code{RETURN_EXPR}. 1977 1978The operand of a @code{GOTO_EXPR} must be either a label or a 1979variable containing the address to jump to. 1980 1981The operand of a @code{RETURN_EXPR} is either @code{NULL_TREE}, 1982@code{RESULT_DECL}, or a @code{MODIFY_EXPR} which sets the return 1983value. It would be nice to move the @code{MODIFY_EXPR} into a 1984separate statement, but the special return semantics in 1985@code{expand_return} make that difficult. It may still happen in 1986the future, perhaps by moving most of that logic into 1987@code{expand_assignment}. 1988 1989@node Cleanups 1990@subsection Cleanups 1991@cindex Cleanups 1992 1993Destructors for local C++ objects and similar dynamic cleanups are 1994represented in GIMPLE by a @code{TRY_FINALLY_EXPR}. 1995@code{TRY_FINALLY_EXPR} has two operands, both of which are a sequence 1996of statements to execute. The first sequence is executed. When it 1997completes the second sequence is executed. 1998 1999The first sequence may complete in the following ways: 2000 2001@enumerate 2002 2003@item Execute the last statement in the sequence and fall off the 2004end. 2005 2006@item Execute a goto statement (@code{GOTO_EXPR}) to an ordinary 2007label outside the sequence. 2008 2009@item Execute a return statement (@code{RETURN_EXPR}). 2010 2011@item Throw an exception. This is currently not explicitly represented in 2012GIMPLE. 2013 2014@end enumerate 2015 2016The second sequence is not executed if the first sequence completes by 2017calling @code{setjmp} or @code{exit} or any other function that does 2018not return. The second sequence is also not executed if the first 2019sequence completes via a non-local goto or a computed goto (in general 2020the compiler does not know whether such a goto statement exits the 2021first sequence or not, so we assume that it doesn't). 2022 2023After the second sequence is executed, if it completes normally by 2024falling off the end, execution continues wherever the first sequence 2025would have continued, by falling off the end, or doing a goto, etc. 2026 2027@code{TRY_FINALLY_EXPR} complicates the flow graph, since the cleanup 2028needs to appear on every edge out of the controlled block; this 2029reduces the freedom to move code across these edges. Therefore, the 2030EH lowering pass which runs before most of the optimization passes 2031eliminates these expressions by explicitly adding the cleanup to each 2032edge. Rethrowing the exception is represented using @code{RESX_EXPR}. 2033 2034@node OpenMP 2035@subsection OpenMP 2036@tindex OMP_PARALLEL 2037@tindex OMP_FOR 2038@tindex OMP_SECTIONS 2039@tindex OMP_SINGLE 2040@tindex OMP_SECTION 2041@tindex OMP_MASTER 2042@tindex OMP_ORDERED 2043@tindex OMP_CRITICAL 2044@tindex OMP_RETURN 2045@tindex OMP_CONTINUE 2046@tindex OMP_ATOMIC 2047@tindex OMP_CLAUSE 2048 2049All the statements starting with @code{OMP_} represent directives and 2050clauses used by the OpenMP API @w{@uref{http://www.openmp.org/}}. 2051 2052@table @code 2053@item OMP_PARALLEL 2054 2055Represents @code{#pragma omp parallel [clause1 @dots{} clauseN]}. It 2056has four operands: 2057 2058Operand @code{OMP_PARALLEL_BODY} is valid while in GENERIC and 2059High GIMPLE forms. It contains the body of code to be executed 2060by all the threads. During GIMPLE lowering, this operand becomes 2061@code{NULL} and the body is emitted linearly after 2062@code{OMP_PARALLEL}. 2063 2064Operand @code{OMP_PARALLEL_CLAUSES} is the list of clauses 2065associated with the directive. 2066 2067Operand @code{OMP_PARALLEL_FN} is created by 2068@code{pass_lower_omp}, it contains the @code{FUNCTION_DECL} 2069for the function that will contain the body of the parallel 2070region. 2071 2072Operand @code{OMP_PARALLEL_DATA_ARG} is also created by 2073@code{pass_lower_omp}. If there are shared variables to be 2074communicated to the children threads, this operand will contain 2075the @code{VAR_DECL} that contains all the shared values and 2076variables. 2077 2078@item OMP_FOR 2079 2080Represents @code{#pragma omp for [clause1 @dots{} clauseN]}. It 2081has 5 operands: 2082 2083Operand @code{OMP_FOR_BODY} contains the loop body. 2084 2085Operand @code{OMP_FOR_CLAUSES} is the list of clauses 2086associated with the directive. 2087 2088Operand @code{OMP_FOR_INIT} is the loop initialization code of 2089the form @code{VAR = N1}. 2090 2091Operand @code{OMP_FOR_COND} is the loop conditional expression 2092of the form @code{VAR @{<,>,<=,>=@} N2}. 2093 2094Operand @code{OMP_FOR_INCR} is the loop index increment of the 2095form @code{VAR @{+=,-=@} INCR}. 2096 2097Operand @code{OMP_FOR_PRE_BODY} contains side-effect code from 2098operands @code{OMP_FOR_INIT}, @code{OMP_FOR_COND} and 2099@code{OMP_FOR_INC}. These side-effects are part of the 2100@code{OMP_FOR} block but must be evaluated before the start of 2101loop body. 2102 2103The loop index variable @code{VAR} must be a signed integer variable, 2104which is implicitly private to each thread. Bounds 2105@code{N1} and @code{N2} and the increment expression 2106@code{INCR} are required to be loop invariant integer 2107expressions that are evaluated without any synchronization. The 2108evaluation order, frequency of evaluation and side-effects are 2109unspecified by the standard. 2110 2111@item OMP_SECTIONS 2112 2113Represents @code{#pragma omp sections [clause1 @dots{} clauseN]}. 2114 2115Operand @code{OMP_SECTIONS_BODY} contains the sections body, 2116which in turn contains a set of @code{OMP_SECTION} nodes for 2117each of the concurrent sections delimited by @code{#pragma omp 2118section}. 2119 2120Operand @code{OMP_SECTIONS_CLAUSES} is the list of clauses 2121associated with the directive. 2122 2123@item OMP_SECTION 2124 2125Section delimiter for @code{OMP_SECTIONS}. 2126 2127@item OMP_SINGLE 2128 2129Represents @code{#pragma omp single}. 2130 2131Operand @code{OMP_SINGLE_BODY} contains the body of code to be 2132executed by a single thread. 2133 2134Operand @code{OMP_SINGLE_CLAUSES} is the list of clauses 2135associated with the directive. 2136 2137@item OMP_MASTER 2138 2139Represents @code{#pragma omp master}. 2140 2141Operand @code{OMP_MASTER_BODY} contains the body of code to be 2142executed by the master thread. 2143 2144@item OMP_ORDERED 2145 2146Represents @code{#pragma omp ordered}. 2147 2148Operand @code{OMP_ORDERED_BODY} contains the body of code to be 2149executed in the sequential order dictated by the loop index 2150variable. 2151 2152@item OMP_CRITICAL 2153 2154Represents @code{#pragma omp critical [name]}. 2155 2156Operand @code{OMP_CRITICAL_BODY} is the critical section. 2157 2158Operand @code{OMP_CRITICAL_NAME} is an optional identifier to 2159label the critical section. 2160 2161@item OMP_RETURN 2162 2163This does not represent any OpenMP directive, it is an artificial 2164marker to indicate the end of the body of an OpenMP@. It is used 2165by the flow graph (@code{tree-cfg.c}) and OpenMP region 2166building code (@code{omp-low.c}). 2167 2168@item OMP_CONTINUE 2169 2170Similarly, this instruction does not represent an OpenMP 2171directive, it is used by @code{OMP_FOR} and 2172@code{OMP_SECTIONS} to mark the place where the code needs to 2173loop to the next iteration (in the case of @code{OMP_FOR}) or 2174the next section (in the case of @code{OMP_SECTIONS}). 2175 2176In some cases, @code{OMP_CONTINUE} is placed right before 2177@code{OMP_RETURN}. But if there are cleanups that need to 2178occur right after the looping body, it will be emitted between 2179@code{OMP_CONTINUE} and @code{OMP_RETURN}. 2180 2181@item OMP_ATOMIC 2182 2183Represents @code{#pragma omp atomic}. 2184 2185Operand 0 is the address at which the atomic operation is to be 2186performed. 2187 2188Operand 1 is the expression to evaluate. The gimplifier tries 2189three alternative code generation strategies. Whenever possible, 2190an atomic update built-in is used. If that fails, a 2191compare-and-swap loop is attempted. If that also fails, a 2192regular critical section around the expression is used. 2193 2194@item OMP_CLAUSE 2195 2196Represents clauses associated with one of the @code{OMP_} directives. 2197Clauses are represented by separate sub-codes defined in 2198@file{tree.h}. Clauses codes can be one of: 2199@code{OMP_CLAUSE_PRIVATE}, @code{OMP_CLAUSE_SHARED}, 2200@code{OMP_CLAUSE_FIRSTPRIVATE}, 2201@code{OMP_CLAUSE_LASTPRIVATE}, @code{OMP_CLAUSE_COPYIN}, 2202@code{OMP_CLAUSE_COPYPRIVATE}, @code{OMP_CLAUSE_IF}, 2203@code{OMP_CLAUSE_NUM_THREADS}, @code{OMP_CLAUSE_SCHEDULE}, 2204@code{OMP_CLAUSE_NOWAIT}, @code{OMP_CLAUSE_ORDERED}, 2205@code{OMP_CLAUSE_DEFAULT}, and @code{OMP_CLAUSE_REDUCTION}. Each code 2206represents the corresponding OpenMP clause. 2207 2208Clauses associated with the same directive are chained together 2209via @code{OMP_CLAUSE_CHAIN}. Those clauses that accept a list 2210of variables are restricted to exactly one, accessed with 2211@code{OMP_CLAUSE_VAR}. Therefore, multiple variables under the 2212same clause @code{C} need to be represented as multiple @code{C} clauses 2213chained together. This facilitates adding new clauses during 2214compilation. 2215 2216@end table 2217 2218@c --------------------------------------------------------------------- 2219@c Functions 2220@c --------------------------------------------------------------------- 2221 2222@node Functions 2223@section Functions 2224@cindex function 2225@tindex FUNCTION_DECL 2226 2227A function is represented by a @code{FUNCTION_DECL} node. It stores 2228the basic pieces of the function such as body, parameters, and return 2229type as well as information on the surrounding context, visibility, 2230and linkage. 2231 2232@menu 2233* Function Basics:: Function names, body, and parameters. 2234* Function Properties:: Context, linkage, etc. 2235@end menu 2236 2237@c --------------------------------------------------------------------- 2238@c Function Basics 2239@c --------------------------------------------------------------------- 2240 2241@node Function Basics 2242@subsection Function Basics 2243@findex DECL_NAME 2244@findex DECL_ASSEMBLER_NAME 2245@findex TREE_PUBLIC 2246@findex DECL_ARTIFICIAL 2247@findex DECL_FUNCTION_SPECIFIC_TARGET 2248@findex DECL_FUNCTION_SPECIFIC_OPTIMIZATION 2249 2250A function has four core parts: the name, the parameters, the result, 2251and the body. The following macros and functions access these parts 2252of a @code{FUNCTION_DECL} as well as other basic features: 2253@ftable @code 2254@item DECL_NAME 2255This macro returns the unqualified name of the function, as an 2256@code{IDENTIFIER_NODE}. For an instantiation of a function template, 2257the @code{DECL_NAME} is the unqualified name of the template, not 2258something like @code{f<int>}. The value of @code{DECL_NAME} is 2259undefined when used on a constructor, destructor, overloaded operator, 2260or type-conversion operator, or any function that is implicitly 2261generated by the compiler. See below for macros that can be used to 2262distinguish these cases. 2263 2264@item DECL_ASSEMBLER_NAME 2265This macro returns the mangled name of the function, also an 2266@code{IDENTIFIER_NODE}. This name does not contain leading underscores 2267on systems that prefix all identifiers with underscores. The mangled 2268name is computed in the same way on all platforms; if special processing 2269is required to deal with the object file format used on a particular 2270platform, it is the responsibility of the back end to perform those 2271modifications. (Of course, the back end should not modify 2272@code{DECL_ASSEMBLER_NAME} itself.) 2273 2274Using @code{DECL_ASSEMBLER_NAME} will cause additional memory to be 2275allocated (for the mangled name of the entity) so it should be used 2276only when emitting assembly code. It should not be used within the 2277optimizers to determine whether or not two declarations are the same, 2278even though some of the existing optimizers do use it in that way. 2279These uses will be removed over time. 2280 2281@item DECL_ARGUMENTS 2282This macro returns the @code{PARM_DECL} for the first argument to the 2283function. Subsequent @code{PARM_DECL} nodes can be obtained by 2284following the @code{TREE_CHAIN} links. 2285 2286@item DECL_RESULT 2287This macro returns the @code{RESULT_DECL} for the function. 2288 2289@item DECL_SAVED_TREE 2290This macro returns the complete body of the function. 2291 2292@item TREE_TYPE 2293This macro returns the @code{FUNCTION_TYPE} or @code{METHOD_TYPE} for 2294the function. 2295 2296@item DECL_INITIAL 2297A function that has a definition in the current translation unit will 2298have a non-@code{NULL} @code{DECL_INITIAL}. However, back ends should not make 2299use of the particular value given by @code{DECL_INITIAL}. 2300 2301It should contain a tree of @code{BLOCK} nodes that mirrors the scopes 2302that variables are bound in the function. Each block contains a list 2303of decls declared in a basic block, a pointer to a chain of blocks at 2304the next lower scope level, then a pointer to the next block at the 2305same level and a backpointer to the parent @code{BLOCK} or 2306@code{FUNCTION_DECL}. So given a function as follows: 2307 2308@smallexample 2309void foo() 2310@{ 2311 int a; 2312 @{ 2313 int b; 2314 @} 2315 int c; 2316@} 2317@end smallexample 2318 2319you would get the following: 2320 2321@smallexample 2322tree foo = FUNCTION_DECL; 2323tree decl_a = VAR_DECL; 2324tree decl_b = VAR_DECL; 2325tree decl_c = VAR_DECL; 2326tree block_a = BLOCK; 2327tree block_b = BLOCK; 2328tree block_c = BLOCK; 2329BLOCK_VARS(block_a) = decl_a; 2330BLOCK_SUBBLOCKS(block_a) = block_b; 2331BLOCK_CHAIN(block_a) = block_c; 2332BLOCK_SUPERCONTEXT(block_a) = foo; 2333BLOCK_VARS(block_b) = decl_b; 2334BLOCK_SUPERCONTEXT(block_b) = block_a; 2335BLOCK_VARS(block_c) = decl_c; 2336BLOCK_SUPERCONTEXT(block_c) = foo; 2337DECL_INITIAL(foo) = block_a; 2338@end smallexample 2339 2340@end ftable 2341 2342@c --------------------------------------------------------------------- 2343@c Function Properties 2344@c --------------------------------------------------------------------- 2345 2346@node Function Properties 2347@subsection Function Properties 2348@cindex function properties 2349@cindex statements 2350 2351To determine the scope of a function, you can use the 2352@code{DECL_CONTEXT} macro. This macro will return the class 2353(either a @code{RECORD_TYPE} or a @code{UNION_TYPE}) or namespace (a 2354@code{NAMESPACE_DECL}) of which the function is a member. For a virtual 2355function, this macro returns the class in which the function was 2356actually defined, not the base class in which the virtual declaration 2357occurred. 2358 2359In C, the @code{DECL_CONTEXT} for a function maybe another function. 2360This representation indicates that the GNU nested function extension 2361is in use. For details on the semantics of nested functions, see the 2362GCC Manual. The nested function can refer to local variables in its 2363containing function. Such references are not explicitly marked in the 2364tree structure; back ends must look at the @code{DECL_CONTEXT} for the 2365referenced @code{VAR_DECL}. If the @code{DECL_CONTEXT} for the 2366referenced @code{VAR_DECL} is not the same as the function currently 2367being processed, and neither @code{DECL_EXTERNAL} nor 2368@code{TREE_STATIC} hold, then the reference is to a local variable in 2369a containing function, and the back end must take appropriate action. 2370 2371@ftable @code 2372@item DECL_EXTERNAL 2373This predicate holds if the function is undefined. 2374 2375@item TREE_PUBLIC 2376This predicate holds if the function has external linkage. 2377 2378@item TREE_STATIC 2379This predicate holds if the function has been defined. 2380 2381@item TREE_THIS_VOLATILE 2382This predicate holds if the function does not return normally. 2383 2384@item TREE_READONLY 2385This predicate holds if the function can only read its arguments. 2386 2387@item DECL_PURE_P 2388This predicate holds if the function can only read its arguments, but 2389may also read global memory. 2390 2391@item DECL_VIRTUAL_P 2392This predicate holds if the function is virtual. 2393 2394@item DECL_ARTIFICIAL 2395This macro holds if the function was implicitly generated by the 2396compiler, rather than explicitly declared. In addition to implicitly 2397generated class member functions, this macro holds for the special 2398functions created to implement static initialization and destruction, to 2399compute run-time type information, and so forth. 2400 2401@item DECL_FUNCTION_SPECIFIC_TARGET 2402This macro returns a tree node that holds the target options that are 2403to be used to compile this particular function or @code{NULL_TREE} if 2404the function is to be compiled with the target options specified on 2405the command line. 2406 2407@item DECL_FUNCTION_SPECIFIC_OPTIMIZATION 2408This macro returns a tree node that holds the optimization options 2409that are to be used to compile this particular function or 2410@code{NULL_TREE} if the function is to be compiled with the 2411optimization options specified on the command line. 2412 2413@end ftable 2414 2415@subsubsection Statements 2416 2417There are tree nodes corresponding to all of the source-level 2418statement constructs, used within the C and C++ frontends. These are 2419enumerated here, together with a list of the various macros that can 2420be used to obtain information about them. There are a few macros that 2421can be used with all statements: 2422 2423@c --------------------------------------------------------------------- 2424@c Language-dependent trees 2425@c --------------------------------------------------------------------- 2426 2427@node Language-dependent trees 2428@section Language-dependent trees 2429@cindex language-dependent trees 2430 2431Front ends may wish to keep some state associated with various GENERIC 2432trees while parsing. To support this, trees provide a set of flags 2433that may be used by the front end. They are accessed using 2434@code{TREE_LANG_FLAG_n} where @samp{n} is currently 0 through 6. 2435 2436If necessary, a front end can use some language-dependent tree 2437codes in its GENERIC representation, so long as it provides a 2438hook for converting them to GIMPLE and doesn't expect them to 2439work with any (hypothetical) optimizers that run before the 2440conversion to GIMPLE@. The intermediate representation used while 2441parsing C and C++ looks very little like GENERIC, but the C and 2442C++ gimplifier hooks are perfectly happy to take it as input and 2443spit out GIMPLE@. 2444 2445 2446 2447@node C and C++ Trees 2448@section C and C++ Trees 2449 2450This section documents the internal representation used by GCC to 2451represent C and C++ source programs. When presented with a C or C++ 2452source program, GCC parses the program, performs semantic analysis 2453(including the generation of error messages), and then produces the 2454internal representation described here. This representation contains a 2455complete representation for the entire translation unit provided as 2456input to the front end. This representation is then typically processed 2457by a code-generator in order to produce machine code, but could also be 2458used in the creation of source browsers, intelligent editors, automatic 2459documentation generators, interpreters, and any other programs needing 2460the ability to process C or C++ code. 2461 2462This section explains the internal representation. In particular, it 2463documents the internal representation for C and C++ source 2464constructs, and the macros, functions, and variables that can be used to 2465access these constructs. The C++ representation is largely a superset 2466of the representation used in the C front end. There is only one 2467construct used in C that does not appear in the C++ front end and that 2468is the GNU ``nested function'' extension. Many of the macros documented 2469here do not apply in C because the corresponding language constructs do 2470not appear in C@. 2471 2472The C and C++ front ends generate a mix of GENERIC trees and ones 2473specific to C and C++. These language-specific trees are higher-level 2474constructs than the ones in GENERIC to make the parser's job easier. 2475This section describes those trees that aren't part of GENERIC as well 2476as aspects of GENERIC trees that are treated in a language-specific 2477manner. 2478 2479If you are developing a ``back end'', be it is a code-generator or some 2480other tool, that uses this representation, you may occasionally find 2481that you need to ask questions not easily answered by the functions and 2482macros available here. If that situation occurs, it is quite likely 2483that GCC already supports the functionality you desire, but that the 2484interface is simply not documented here. In that case, you should ask 2485the GCC maintainers (via mail to @email{gcc@@gcc.gnu.org}) about 2486documenting the functionality you require. Similarly, if you find 2487yourself writing functions that do not deal directly with your back end, 2488but instead might be useful to other people using the GCC front end, you 2489should submit your patches for inclusion in GCC@. 2490 2491@menu 2492* Types for C++:: Fundamental and aggregate types. 2493* Namespaces:: Namespaces. 2494* Classes:: Classes. 2495* Functions for C++:: Overloading and accessors for C++. 2496* Statements for C++:: Statements specific to C and C++. 2497* C++ Expressions:: From @code{typeid} to @code{throw}. 2498@end menu 2499 2500@node Types for C++ 2501@subsection Types for C++ 2502@tindex UNKNOWN_TYPE 2503@tindex TYPENAME_TYPE 2504@tindex TYPEOF_TYPE 2505@findex CP_TYPE_QUALS 2506@findex TYPE_UNQUALIFIED 2507@findex TYPE_QUAL_CONST 2508@findex TYPE_QUAL_VOLATILE 2509@findex TYPE_QUAL_RESTRICT 2510@findex TYPE_MAIN_VARIANT 2511@cindex qualified type 2512@findex TYPE_SIZE 2513@findex TYPE_ALIGN 2514@findex TYPE_PRECISION 2515@findex TYPE_ARG_TYPES 2516@findex TYPE_METHOD_BASETYPE 2517@findex TYPE_PTRMEM_P 2518@findex TYPE_OFFSET_BASETYPE 2519@findex TREE_TYPE 2520@findex TYPE_CONTEXT 2521@findex TYPE_NAME 2522@findex TYPENAME_TYPE_FULLNAME 2523@findex TYPE_FIELDS 2524@findex TYPE_PTROBV_P 2525 2526In C++, an array type is not qualified; rather the type of the array 2527elements is qualified. This situation is reflected in the intermediate 2528representation. The macros described here will always examine the 2529qualification of the underlying element type when applied to an array 2530type. (If the element type is itself an array, then the recursion 2531continues until a non-array type is found, and the qualification of this 2532type is examined.) So, for example, @code{CP_TYPE_CONST_P} will hold of 2533the type @code{const int ()[7]}, denoting an array of seven @code{int}s. 2534 2535The following functions and macros deal with cv-qualification of types: 2536@ftable @code 2537@item CP_TYPE_QUALS 2538This macro returns the set of type qualifiers applied to this type. 2539This value is @code{TYPE_UNQUALIFIED} if no qualifiers have been 2540applied. The @code{TYPE_QUAL_CONST} bit is set if the type is 2541@code{const}-qualified. The @code{TYPE_QUAL_VOLATILE} bit is set if the 2542type is @code{volatile}-qualified. The @code{TYPE_QUAL_RESTRICT} bit is 2543set if the type is @code{restrict}-qualified. 2544 2545@item CP_TYPE_CONST_P 2546This macro holds if the type is @code{const}-qualified. 2547 2548@item CP_TYPE_VOLATILE_P 2549This macro holds if the type is @code{volatile}-qualified. 2550 2551@item CP_TYPE_RESTRICT_P 2552This macro holds if the type is @code{restrict}-qualified. 2553 2554@item CP_TYPE_CONST_NON_VOLATILE_P 2555This predicate holds for a type that is @code{const}-qualified, but 2556@emph{not} @code{volatile}-qualified; other cv-qualifiers are ignored as 2557well: only the @code{const}-ness is tested. 2558 2559@end ftable 2560 2561A few other macros and functions are usable with all types: 2562@ftable @code 2563@item TYPE_SIZE 2564The number of bits required to represent the type, represented as an 2565@code{INTEGER_CST}. For an incomplete type, @code{TYPE_SIZE} will be 2566@code{NULL_TREE}. 2567 2568@item TYPE_ALIGN 2569The alignment of the type, in bits, represented as an @code{int}. 2570 2571@item TYPE_NAME 2572This macro returns a declaration (in the form of a @code{TYPE_DECL}) for 2573the type. (Note this macro does @emph{not} return an 2574@code{IDENTIFIER_NODE}, as you might expect, given its name!) You can 2575look at the @code{DECL_NAME} of the @code{TYPE_DECL} to obtain the 2576actual name of the type. The @code{TYPE_NAME} will be @code{NULL_TREE} 2577for a type that is not a built-in type, the result of a typedef, or a 2578named class type. 2579 2580@item CP_INTEGRAL_TYPE 2581This predicate holds if the type is an integral type. Notice that in 2582C++, enumerations are @emph{not} integral types. 2583 2584@item ARITHMETIC_TYPE_P 2585This predicate holds if the type is an integral type (in the C++ sense) 2586or a floating point type. 2587 2588@item CLASS_TYPE_P 2589This predicate holds for a class-type. 2590 2591@item TYPE_BUILT_IN 2592This predicate holds for a built-in type. 2593 2594@item TYPE_PTRMEM_P 2595This predicate holds if the type is a pointer to data member. 2596 2597@item TYPE_PTR_P 2598This predicate holds if the type is a pointer type, and the pointee is 2599not a data member. 2600 2601@item TYPE_PTRFN_P 2602This predicate holds for a pointer to function type. 2603 2604@item TYPE_PTROB_P 2605This predicate holds for a pointer to object type. Note however that it 2606does not hold for the generic pointer to object type @code{void *}. You 2607may use @code{TYPE_PTROBV_P} to test for a pointer to object type as 2608well as @code{void *}. 2609 2610@end ftable 2611 2612The table below describes types specific to C and C++ as well as 2613language-dependent info about GENERIC types. 2614 2615@table @code 2616 2617@item POINTER_TYPE 2618Used to represent pointer types, and pointer to data member types. If 2619@code{TREE_TYPE} 2620is a pointer to data member type, then @code{TYPE_PTRMEM_P} will hold. 2621For a pointer to data member type of the form @samp{T X::*}, 2622@code{TYPE_PTRMEM_CLASS_TYPE} will be the type @code{X}, while 2623@code{TYPE_PTRMEM_POINTED_TO_TYPE} will be the type @code{T}. 2624 2625@item RECORD_TYPE 2626Used to represent @code{struct} and @code{class} types in C and C++. If 2627@code{TYPE_PTRMEMFUNC_P} holds, then this type is a pointer-to-member 2628type. In that case, the @code{TYPE_PTRMEMFUNC_FN_TYPE} is a 2629@code{POINTER_TYPE} pointing to a @code{METHOD_TYPE}. The 2630@code{METHOD_TYPE} is the type of a function pointed to by the 2631pointer-to-member function. If @code{TYPE_PTRMEMFUNC_P} does not hold, 2632this type is a class type. For more information, see @pxref{Classes}. 2633 2634@item UNKNOWN_TYPE 2635This node is used to represent a type the knowledge of which is 2636insufficient for a sound processing. 2637 2638@item TYPENAME_TYPE 2639Used to represent a construct of the form @code{typename T::A}. The 2640@code{TYPE_CONTEXT} is @code{T}; the @code{TYPE_NAME} is an 2641@code{IDENTIFIER_NODE} for @code{A}. If the type is specified via a 2642template-id, then @code{TYPENAME_TYPE_FULLNAME} yields a 2643@code{TEMPLATE_ID_EXPR}. The @code{TREE_TYPE} is non-@code{NULL} if the 2644node is implicitly generated in support for the implicit typename 2645extension; in which case the @code{TREE_TYPE} is a type node for the 2646base-class. 2647 2648@item TYPEOF_TYPE 2649Used to represent the @code{__typeof__} extension. The 2650@code{TYPE_FIELDS} is the expression the type of which is being 2651represented. 2652 2653@end table 2654 2655 2656@c --------------------------------------------------------------------- 2657@c Namespaces 2658@c --------------------------------------------------------------------- 2659 2660@node Namespaces 2661@subsection Namespaces 2662@cindex namespace, scope 2663@tindex NAMESPACE_DECL 2664 2665The root of the entire intermediate representation is the variable 2666@code{global_namespace}. This is the namespace specified with @code{::} 2667in C++ source code. All other namespaces, types, variables, functions, 2668and so forth can be found starting with this namespace. 2669 2670However, except for the fact that it is distinguished as the root of the 2671representation, the global namespace is no different from any other 2672namespace. Thus, in what follows, we describe namespaces generally, 2673rather than the global namespace in particular. 2674 2675A namespace is represented by a @code{NAMESPACE_DECL} node. 2676 2677The following macros and functions can be used on a @code{NAMESPACE_DECL}: 2678 2679@ftable @code 2680@item DECL_NAME 2681This macro is used to obtain the @code{IDENTIFIER_NODE} corresponding to 2682the unqualified name of the name of the namespace (@pxref{Identifiers}). 2683The name of the global namespace is @samp{::}, even though in C++ the 2684global namespace is unnamed. However, you should use comparison with 2685@code{global_namespace}, rather than @code{DECL_NAME} to determine 2686whether or not a namespace is the global one. An unnamed namespace 2687will have a @code{DECL_NAME} equal to @code{anonymous_namespace_name}. 2688Within a single translation unit, all unnamed namespaces will have the 2689same name. 2690 2691@item DECL_CONTEXT 2692This macro returns the enclosing namespace. The @code{DECL_CONTEXT} for 2693the @code{global_namespace} is @code{NULL_TREE}. 2694 2695@item DECL_NAMESPACE_ALIAS 2696If this declaration is for a namespace alias, then 2697@code{DECL_NAMESPACE_ALIAS} is the namespace for which this one is an 2698alias. 2699 2700Do not attempt to use @code{cp_namespace_decls} for a namespace which is 2701an alias. Instead, follow @code{DECL_NAMESPACE_ALIAS} links until you 2702reach an ordinary, non-alias, namespace, and call 2703@code{cp_namespace_decls} there. 2704 2705@item DECL_NAMESPACE_STD_P 2706This predicate holds if the namespace is the special @code{::std} 2707namespace. 2708 2709@item cp_namespace_decls 2710This function will return the declarations contained in the namespace, 2711including types, overloaded functions, other namespaces, and so forth. 2712If there are no declarations, this function will return 2713@code{NULL_TREE}. The declarations are connected through their 2714@code{TREE_CHAIN} fields. 2715 2716Although most entries on this list will be declarations, 2717@code{TREE_LIST} nodes may also appear. In this case, the 2718@code{TREE_VALUE} will be an @code{OVERLOAD}. The value of the 2719@code{TREE_PURPOSE} is unspecified; back ends should ignore this value. 2720As with the other kinds of declarations returned by 2721@code{cp_namespace_decls}, the @code{TREE_CHAIN} will point to the next 2722declaration in this list. 2723 2724For more information on the kinds of declarations that can occur on this 2725list, @xref{Declarations}. Some declarations will not appear on this 2726list. In particular, no @code{FIELD_DECL}, @code{LABEL_DECL}, or 2727@code{PARM_DECL} nodes will appear here. 2728 2729This function cannot be used with namespaces that have 2730@code{DECL_NAMESPACE_ALIAS} set. 2731 2732@end ftable 2733 2734@c --------------------------------------------------------------------- 2735@c Classes 2736@c --------------------------------------------------------------------- 2737 2738@node Classes 2739@subsection Classes 2740@cindex class, scope 2741@tindex RECORD_TYPE 2742@tindex UNION_TYPE 2743@findex CLASSTYPE_DECLARED_CLASS 2744@findex TYPE_BINFO 2745@findex BINFO_TYPE 2746@findex TYPE_FIELDS 2747@findex TYPE_VFIELD 2748@findex TYPE_METHODS 2749 2750Besides namespaces, the other high-level scoping construct in C++ is the 2751class. (Throughout this manual the term @dfn{class} is used to mean the 2752types referred to in the ANSI/ISO C++ Standard as classes; these include 2753types defined with the @code{class}, @code{struct}, and @code{union} 2754keywords.) 2755 2756A class type is represented by either a @code{RECORD_TYPE} or a 2757@code{UNION_TYPE}. A class declared with the @code{union} tag is 2758represented by a @code{UNION_TYPE}, while classes declared with either 2759the @code{struct} or the @code{class} tag are represented by 2760@code{RECORD_TYPE}s. You can use the @code{CLASSTYPE_DECLARED_CLASS} 2761macro to discern whether or not a particular type is a @code{class} as 2762opposed to a @code{struct}. This macro will be true only for classes 2763declared with the @code{class} tag. 2764 2765Almost all non-function members are available on the @code{TYPE_FIELDS} 2766list. Given one member, the next can be found by following the 2767@code{TREE_CHAIN}. You should not depend in any way on the order in 2768which fields appear on this list. All nodes on this list will be 2769@samp{DECL} nodes. A @code{FIELD_DECL} is used to represent a non-static 2770data member, a @code{VAR_DECL} is used to represent a static data 2771member, and a @code{TYPE_DECL} is used to represent a type. Note that 2772the @code{CONST_DECL} for an enumeration constant will appear on this 2773list, if the enumeration type was declared in the class. (Of course, 2774the @code{TYPE_DECL} for the enumeration type will appear here as well.) 2775There are no entries for base classes on this list. In particular, 2776there is no @code{FIELD_DECL} for the ``base-class portion'' of an 2777object. 2778 2779The @code{TYPE_VFIELD} is a compiler-generated field used to point to 2780virtual function tables. It may or may not appear on the 2781@code{TYPE_FIELDS} list. However, back ends should handle the 2782@code{TYPE_VFIELD} just like all the entries on the @code{TYPE_FIELDS} 2783list. 2784 2785The function members are available on the @code{TYPE_METHODS} list. 2786Again, subsequent members are found by following the @code{TREE_CHAIN} 2787field. If a function is overloaded, each of the overloaded functions 2788appears; no @code{OVERLOAD} nodes appear on the @code{TYPE_METHODS} 2789list. Implicitly declared functions (including default constructors, 2790copy constructors, assignment operators, and destructors) will appear on 2791this list as well. 2792 2793Every class has an associated @dfn{binfo}, which can be obtained with 2794@code{TYPE_BINFO}. Binfos are used to represent base-classes. The 2795binfo given by @code{TYPE_BINFO} is the degenerate case, whereby every 2796class is considered to be its own base-class. The base binfos for a 2797particular binfo are held in a vector, whose length is obtained with 2798@code{BINFO_N_BASE_BINFOS}. The base binfos themselves are obtained 2799with @code{BINFO_BASE_BINFO} and @code{BINFO_BASE_ITERATE}. To add a 2800new binfo, use @code{BINFO_BASE_APPEND}. The vector of base binfos can 2801be obtained with @code{BINFO_BASE_BINFOS}, but normally you do not need 2802to use that. The class type associated with a binfo is given by 2803@code{BINFO_TYPE}. It is not always the case that @code{BINFO_TYPE 2804(TYPE_BINFO (x))}, because of typedefs and qualified types. Neither is 2805it the case that @code{TYPE_BINFO (BINFO_TYPE (y))} is the same binfo as 2806@code{y}. The reason is that if @code{y} is a binfo representing a 2807base-class @code{B} of a derived class @code{D}, then @code{BINFO_TYPE 2808(y)} will be @code{B}, and @code{TYPE_BINFO (BINFO_TYPE (y))} will be 2809@code{B} as its own base-class, rather than as a base-class of @code{D}. 2810 2811The access to a base type can be found with @code{BINFO_BASE_ACCESS}. 2812This will produce @code{access_public_node}, @code{access_private_node} 2813or @code{access_protected_node}. If bases are always public, 2814@code{BINFO_BASE_ACCESSES} may be @code{NULL}. 2815 2816@code{BINFO_VIRTUAL_P} is used to specify whether the binfo is inherited 2817virtually or not. The other flags, @code{BINFO_MARKED_P} and 2818@code{BINFO_FLAG_1} to @code{BINFO_FLAG_6} can be used for language 2819specific use. 2820 2821The following macros can be used on a tree node representing a class-type. 2822 2823@ftable @code 2824@item LOCAL_CLASS_P 2825This predicate holds if the class is local class @emph{i.e.}@: declared 2826inside a function body. 2827 2828@item TYPE_POLYMORPHIC_P 2829This predicate holds if the class has at least one virtual function 2830(declared or inherited). 2831 2832@item TYPE_HAS_DEFAULT_CONSTRUCTOR 2833This predicate holds whenever its argument represents a class-type with 2834default constructor. 2835 2836@item CLASSTYPE_HAS_MUTABLE 2837@itemx TYPE_HAS_MUTABLE_P 2838These predicates hold for a class-type having a mutable data member. 2839 2840@item CLASSTYPE_NON_POD_P 2841This predicate holds only for class-types that are not PODs. 2842 2843@item TYPE_HAS_NEW_OPERATOR 2844This predicate holds for a class-type that defines 2845@code{operator new}. 2846 2847@item TYPE_HAS_ARRAY_NEW_OPERATOR 2848This predicate holds for a class-type for which 2849@code{operator new[]} is defined. 2850 2851@item TYPE_OVERLOADS_CALL_EXPR 2852This predicate holds for class-type for which the function call 2853@code{operator()} is overloaded. 2854 2855@item TYPE_OVERLOADS_ARRAY_REF 2856This predicate holds for a class-type that overloads 2857@code{operator[]} 2858 2859@item TYPE_OVERLOADS_ARROW 2860This predicate holds for a class-type for which @code{operator->} is 2861overloaded. 2862 2863@end ftable 2864 2865@node Functions for C++ 2866@subsection Functions for C++ 2867@cindex function 2868@tindex FUNCTION_DECL 2869@tindex OVERLOAD 2870@findex OVL_CURRENT 2871@findex OVL_NEXT 2872 2873A function is represented by a @code{FUNCTION_DECL} node. A set of 2874overloaded functions is sometimes represented by an @code{OVERLOAD} node. 2875 2876An @code{OVERLOAD} node is not a declaration, so none of the 2877@samp{DECL_} macros should be used on an @code{OVERLOAD}. An 2878@code{OVERLOAD} node is similar to a @code{TREE_LIST}. Use 2879@code{OVL_CURRENT} to get the function associated with an 2880@code{OVERLOAD} node; use @code{OVL_NEXT} to get the next 2881@code{OVERLOAD} node in the list of overloaded functions. The macros 2882@code{OVL_CURRENT} and @code{OVL_NEXT} are actually polymorphic; you can 2883use them to work with @code{FUNCTION_DECL} nodes as well as with 2884overloads. In the case of a @code{FUNCTION_DECL}, @code{OVL_CURRENT} 2885will always return the function itself, and @code{OVL_NEXT} will always 2886be @code{NULL_TREE}. 2887 2888To determine the scope of a function, you can use the 2889@code{DECL_CONTEXT} macro. This macro will return the class 2890(either a @code{RECORD_TYPE} or a @code{UNION_TYPE}) or namespace (a 2891@code{NAMESPACE_DECL}) of which the function is a member. For a virtual 2892function, this macro returns the class in which the function was 2893actually defined, not the base class in which the virtual declaration 2894occurred. 2895 2896If a friend function is defined in a class scope, the 2897@code{DECL_FRIEND_CONTEXT} macro can be used to determine the class in 2898which it was defined. For example, in 2899@smallexample 2900class C @{ friend void f() @{@} @}; 2901@end smallexample 2902@noindent 2903the @code{DECL_CONTEXT} for @code{f} will be the 2904@code{global_namespace}, but the @code{DECL_FRIEND_CONTEXT} will be the 2905@code{RECORD_TYPE} for @code{C}. 2906 2907 2908The following macros and functions can be used on a @code{FUNCTION_DECL}: 2909@ftable @code 2910@item DECL_MAIN_P 2911This predicate holds for a function that is the program entry point 2912@code{::code}. 2913 2914@item DECL_LOCAL_FUNCTION_P 2915This predicate holds if the function was declared at block scope, even 2916though it has a global scope. 2917 2918@item DECL_ANTICIPATED 2919This predicate holds if the function is a built-in function but its 2920prototype is not yet explicitly declared. 2921 2922@item DECL_EXTERN_C_FUNCTION_P 2923This predicate holds if the function is declared as an 2924`@code{extern "C"}' function. 2925 2926@item DECL_LINKONCE_P 2927This macro holds if multiple copies of this function may be emitted in 2928various translation units. It is the responsibility of the linker to 2929merge the various copies. Template instantiations are the most common 2930example of functions for which @code{DECL_LINKONCE_P} holds; G++ 2931instantiates needed templates in all translation units which require them, 2932and then relies on the linker to remove duplicate instantiations. 2933 2934FIXME: This macro is not yet implemented. 2935 2936@item DECL_FUNCTION_MEMBER_P 2937This macro holds if the function is a member of a class, rather than a 2938member of a namespace. 2939 2940@item DECL_STATIC_FUNCTION_P 2941This predicate holds if the function a static member function. 2942 2943@item DECL_NONSTATIC_MEMBER_FUNCTION_P 2944This macro holds for a non-static member function. 2945 2946@item DECL_CONST_MEMFUNC_P 2947This predicate holds for a @code{const}-member function. 2948 2949@item DECL_VOLATILE_MEMFUNC_P 2950This predicate holds for a @code{volatile}-member function. 2951 2952@item DECL_CONSTRUCTOR_P 2953This macro holds if the function is a constructor. 2954 2955@item DECL_NONCONVERTING_P 2956This predicate holds if the constructor is a non-converting constructor. 2957 2958@item DECL_COMPLETE_CONSTRUCTOR_P 2959This predicate holds for a function which is a constructor for an object 2960of a complete type. 2961 2962@item DECL_BASE_CONSTRUCTOR_P 2963This predicate holds for a function which is a constructor for a base 2964class sub-object. 2965 2966@item DECL_COPY_CONSTRUCTOR_P 2967This predicate holds for a function which is a copy-constructor. 2968 2969@item DECL_DESTRUCTOR_P 2970This macro holds if the function is a destructor. 2971 2972@item DECL_COMPLETE_DESTRUCTOR_P 2973This predicate holds if the function is the destructor for an object a 2974complete type. 2975 2976@item DECL_OVERLOADED_OPERATOR_P 2977This macro holds if the function is an overloaded operator. 2978 2979@item DECL_CONV_FN_P 2980This macro holds if the function is a type-conversion operator. 2981 2982@item DECL_GLOBAL_CTOR_P 2983This predicate holds if the function is a file-scope initialization 2984function. 2985 2986@item DECL_GLOBAL_DTOR_P 2987This predicate holds if the function is a file-scope finalization 2988function. 2989 2990@item DECL_THUNK_P 2991This predicate holds if the function is a thunk. 2992 2993These functions represent stub code that adjusts the @code{this} pointer 2994and then jumps to another function. When the jumped-to function 2995returns, control is transferred directly to the caller, without 2996returning to the thunk. The first parameter to the thunk is always the 2997@code{this} pointer; the thunk should add @code{THUNK_DELTA} to this 2998value. (The @code{THUNK_DELTA} is an @code{int}, not an 2999@code{INTEGER_CST}.) 3000 3001Then, if @code{THUNK_VCALL_OFFSET} (an @code{INTEGER_CST}) is nonzero 3002the adjusted @code{this} pointer must be adjusted again. The complete 3003calculation is given by the following pseudo-code: 3004 3005@smallexample 3006this += THUNK_DELTA 3007if (THUNK_VCALL_OFFSET) 3008 this += (*((ptrdiff_t **) this))[THUNK_VCALL_OFFSET] 3009@end smallexample 3010 3011Finally, the thunk should jump to the location given 3012by @code{DECL_INITIAL}; this will always be an expression for the 3013address of a function. 3014 3015@item DECL_NON_THUNK_FUNCTION_P 3016This predicate holds if the function is @emph{not} a thunk function. 3017 3018@item GLOBAL_INIT_PRIORITY 3019If either @code{DECL_GLOBAL_CTOR_P} or @code{DECL_GLOBAL_DTOR_P} holds, 3020then this gives the initialization priority for the function. The 3021linker will arrange that all functions for which 3022@code{DECL_GLOBAL_CTOR_P} holds are run in increasing order of priority 3023before @code{main} is called. When the program exits, all functions for 3024which @code{DECL_GLOBAL_DTOR_P} holds are run in the reverse order. 3025 3026@item TYPE_RAISES_EXCEPTIONS 3027This macro returns the list of exceptions that a (member-)function can 3028raise. The returned list, if non @code{NULL}, is comprised of nodes 3029whose @code{TREE_VALUE} represents a type. 3030 3031@item TYPE_NOTHROW_P 3032This predicate holds when the exception-specification of its arguments 3033is of the form `@code{()}'. 3034 3035@item DECL_ARRAY_DELETE_OPERATOR_P 3036This predicate holds if the function an overloaded 3037@code{operator delete[]}. 3038 3039@end ftable 3040 3041@c --------------------------------------------------------------------- 3042@c Function Bodies 3043@c --------------------------------------------------------------------- 3044 3045@node Statements for C++ 3046@subsection Statements for C++ 3047@cindex statements 3048@tindex BREAK_STMT 3049@tindex CLEANUP_STMT 3050@findex CLEANUP_DECL 3051@findex CLEANUP_EXPR 3052@tindex CONTINUE_STMT 3053@tindex DECL_STMT 3054@findex DECL_STMT_DECL 3055@tindex DO_STMT 3056@findex DO_BODY 3057@findex DO_COND 3058@tindex EMPTY_CLASS_EXPR 3059@tindex EXPR_STMT 3060@findex EXPR_STMT_EXPR 3061@tindex FOR_STMT 3062@findex FOR_INIT_STMT 3063@findex FOR_COND 3064@findex FOR_EXPR 3065@findex FOR_BODY 3066@tindex HANDLER 3067@tindex IF_STMT 3068@findex IF_COND 3069@findex THEN_CLAUSE 3070@findex ELSE_CLAUSE 3071@tindex RETURN_STMT 3072@findex RETURN_EXPR 3073@tindex SUBOBJECT 3074@findex SUBOBJECT_CLEANUP 3075@tindex SWITCH_STMT 3076@findex SWITCH_COND 3077@findex SWITCH_BODY 3078@tindex TRY_BLOCK 3079@findex TRY_STMTS 3080@findex TRY_HANDLERS 3081@findex HANDLER_PARMS 3082@findex HANDLER_BODY 3083@findex USING_STMT 3084@tindex WHILE_STMT 3085@findex WHILE_BODY 3086@findex WHILE_COND 3087 3088A function that has a definition in the current translation unit will 3089have a non-@code{NULL} @code{DECL_INITIAL}. However, back ends should not make 3090use of the particular value given by @code{DECL_INITIAL}. 3091 3092The @code{DECL_SAVED_TREE} macro will give the complete body of the 3093function. 3094 3095@subsubsection Statements 3096 3097There are tree nodes corresponding to all of the source-level 3098statement constructs, used within the C and C++ frontends. These are 3099enumerated here, together with a list of the various macros that can 3100be used to obtain information about them. There are a few macros that 3101can be used with all statements: 3102 3103@ftable @code 3104@item STMT_IS_FULL_EXPR_P 3105In C++, statements normally constitute ``full expressions''; temporaries 3106created during a statement are destroyed when the statement is complete. 3107However, G++ sometimes represents expressions by statements; these 3108statements will not have @code{STMT_IS_FULL_EXPR_P} set. Temporaries 3109created during such statements should be destroyed when the innermost 3110enclosing statement with @code{STMT_IS_FULL_EXPR_P} set is exited. 3111 3112@end ftable 3113 3114Here is the list of the various statement nodes, and the macros used to 3115access them. This documentation describes the use of these nodes in 3116non-template functions (including instantiations of template functions). 3117In template functions, the same nodes are used, but sometimes in 3118slightly different ways. 3119 3120Many of the statements have substatements. For example, a @code{while} 3121loop will have a body, which is itself a statement. If the substatement 3122is @code{NULL_TREE}, it is considered equivalent to a statement 3123consisting of a single @code{;}, i.e., an expression statement in which 3124the expression has been omitted. A substatement may in fact be a list 3125of statements, connected via their @code{TREE_CHAIN}s. So, you should 3126always process the statement tree by looping over substatements, like 3127this: 3128@smallexample 3129void process_stmt (stmt) 3130 tree stmt; 3131@{ 3132 while (stmt) 3133 @{ 3134 switch (TREE_CODE (stmt)) 3135 @{ 3136 case IF_STMT: 3137 process_stmt (THEN_CLAUSE (stmt)); 3138 /* @r{More processing here.} */ 3139 break; 3140 3141 @dots{} 3142 @} 3143 3144 stmt = TREE_CHAIN (stmt); 3145 @} 3146@} 3147@end smallexample 3148In other words, while the @code{then} clause of an @code{if} statement 3149in C++ can be only one statement (although that one statement may be a 3150compound statement), the intermediate representation will sometimes use 3151several statements chained together. 3152 3153@table @code 3154@item BREAK_STMT 3155 3156Used to represent a @code{break} statement. There are no additional 3157fields. 3158 3159@item CLEANUP_STMT 3160 3161Used to represent an action that should take place upon exit from the 3162enclosing scope. Typically, these actions are calls to destructors for 3163local objects, but back ends cannot rely on this fact. If these nodes 3164are in fact representing such destructors, @code{CLEANUP_DECL} will be 3165the @code{VAR_DECL} destroyed. Otherwise, @code{CLEANUP_DECL} will be 3166@code{NULL_TREE}. In any case, the @code{CLEANUP_EXPR} is the 3167expression to execute. The cleanups executed on exit from a scope 3168should be run in the reverse order of the order in which the associated 3169@code{CLEANUP_STMT}s were encountered. 3170 3171@item CONTINUE_STMT 3172 3173Used to represent a @code{continue} statement. There are no additional 3174fields. 3175 3176@item CTOR_STMT 3177 3178Used to mark the beginning (if @code{CTOR_BEGIN_P} holds) or end (if 3179@code{CTOR_END_P} holds of the main body of a constructor. See also 3180@code{SUBOBJECT} for more information on how to use these nodes. 3181 3182@item DO_STMT 3183 3184Used to represent a @code{do} loop. The body of the loop is given by 3185@code{DO_BODY} while the termination condition for the loop is given by 3186@code{DO_COND}. The condition for a @code{do}-statement is always an 3187expression. 3188 3189@item EMPTY_CLASS_EXPR 3190 3191Used to represent a temporary object of a class with no data whose 3192address is never taken. (All such objects are interchangeable.) The 3193@code{TREE_TYPE} represents the type of the object. 3194 3195@item EXPR_STMT 3196 3197Used to represent an expression statement. Use @code{EXPR_STMT_EXPR} to 3198obtain the expression. 3199 3200@item FOR_STMT 3201 3202Used to represent a @code{for} statement. The @code{FOR_INIT_STMT} is 3203the initialization statement for the loop. The @code{FOR_COND} is the 3204termination condition. The @code{FOR_EXPR} is the expression executed 3205right before the @code{FOR_COND} on each loop iteration; often, this 3206expression increments a counter. The body of the loop is given by 3207@code{FOR_BODY}. Note that @code{FOR_INIT_STMT} and @code{FOR_BODY} 3208return statements, while @code{FOR_COND} and @code{FOR_EXPR} return 3209expressions. 3210 3211@item HANDLER 3212 3213Used to represent a C++ @code{catch} block. The @code{HANDLER_TYPE} 3214is the type of exception that will be caught by this handler; it is 3215equal (by pointer equality) to @code{NULL} if this handler is for all 3216types. @code{HANDLER_PARMS} is the @code{DECL_STMT} for the catch 3217parameter, and @code{HANDLER_BODY} is the code for the block itself. 3218 3219@item IF_STMT 3220 3221Used to represent an @code{if} statement. The @code{IF_COND} is the 3222expression. 3223 3224If the condition is a @code{TREE_LIST}, then the @code{TREE_PURPOSE} is 3225a statement (usually a @code{DECL_STMT}). Each time the condition is 3226evaluated, the statement should be executed. Then, the 3227@code{TREE_VALUE} should be used as the conditional expression itself. 3228This representation is used to handle C++ code like this: 3229 3230C++ distinguishes between this and @code{COND_EXPR} for handling templates. 3231 3232@smallexample 3233if (int i = 7) @dots{} 3234@end smallexample 3235 3236where there is a new local variable (or variables) declared within the 3237condition. 3238 3239The @code{THEN_CLAUSE} represents the statement given by the @code{then} 3240condition, while the @code{ELSE_CLAUSE} represents the statement given 3241by the @code{else} condition. 3242 3243@item SUBOBJECT 3244 3245In a constructor, these nodes are used to mark the point at which a 3246subobject of @code{this} is fully constructed. If, after this point, an 3247exception is thrown before a @code{CTOR_STMT} with @code{CTOR_END_P} set 3248is encountered, the @code{SUBOBJECT_CLEANUP} must be executed. The 3249cleanups must be executed in the reverse order in which they appear. 3250 3251@item SWITCH_STMT 3252 3253Used to represent a @code{switch} statement. The @code{SWITCH_STMT_COND} 3254is the expression on which the switch is occurring. See the documentation 3255for an @code{IF_STMT} for more information on the representation used 3256for the condition. The @code{SWITCH_STMT_BODY} is the body of the switch 3257statement. The @code{SWITCH_STMT_TYPE} is the original type of switch 3258expression as given in the source, before any compiler conversions. 3259 3260@item TRY_BLOCK 3261Used to represent a @code{try} block. The body of the try block is 3262given by @code{TRY_STMTS}. Each of the catch blocks is a @code{HANDLER} 3263node. The first handler is given by @code{TRY_HANDLERS}. Subsequent 3264handlers are obtained by following the @code{TREE_CHAIN} link from one 3265handler to the next. The body of the handler is given by 3266@code{HANDLER_BODY}. 3267 3268If @code{CLEANUP_P} holds of the @code{TRY_BLOCK}, then the 3269@code{TRY_HANDLERS} will not be a @code{HANDLER} node. Instead, it will 3270be an expression that should be executed if an exception is thrown in 3271the try block. It must rethrow the exception after executing that code. 3272And, if an exception is thrown while the expression is executing, 3273@code{terminate} must be called. 3274 3275@item USING_STMT 3276Used to represent a @code{using} directive. The namespace is given by 3277@code{USING_STMT_NAMESPACE}, which will be a NAMESPACE_DECL@. This node 3278is needed inside template functions, to implement using directives 3279during instantiation. 3280 3281@item WHILE_STMT 3282 3283Used to represent a @code{while} loop. The @code{WHILE_COND} is the 3284termination condition for the loop. See the documentation for an 3285@code{IF_STMT} for more information on the representation used for the 3286condition. 3287 3288The @code{WHILE_BODY} is the body of the loop. 3289 3290@end table 3291 3292@node C++ Expressions 3293@subsection C++ Expressions 3294 3295This section describes expressions specific to the C and C++ front 3296ends. 3297 3298@table @code 3299@item TYPEID_EXPR 3300 3301Used to represent a @code{typeid} expression. 3302 3303@item NEW_EXPR 3304@itemx VEC_NEW_EXPR 3305 3306Used to represent a call to @code{new} and @code{new[]} respectively. 3307 3308@item DELETE_EXPR 3309@itemx VEC_DELETE_EXPR 3310 3311Used to represent a call to @code{delete} and @code{delete[]} respectively. 3312 3313@item MEMBER_REF 3314 3315Represents a reference to a member of a class. 3316 3317@item THROW_EXPR 3318 3319Represents an instance of @code{throw} in the program. Operand 0, 3320which is the expression to throw, may be @code{NULL_TREE}. 3321 3322 3323@item AGGR_INIT_EXPR 3324An @code{AGGR_INIT_EXPR} represents the initialization as the return 3325value of a function call, or as the result of a constructor. An 3326@code{AGGR_INIT_EXPR} will only appear as a full-expression, or as the 3327second operand of a @code{TARGET_EXPR}. @code{AGGR_INIT_EXPR}s have 3328a representation similar to that of @code{CALL_EXPR}s. You can use 3329the @code{AGGR_INIT_EXPR_FN} and @code{AGGR_INIT_EXPR_ARG} macros to access 3330the function to call and the arguments to pass. 3331 3332If @code{AGGR_INIT_VIA_CTOR_P} holds of the @code{AGGR_INIT_EXPR}, then 3333the initialization is via a constructor call. The address of the 3334@code{AGGR_INIT_EXPR_SLOT} operand, which is always a @code{VAR_DECL}, 3335is taken, and this value replaces the first argument in the argument 3336list. 3337 3338In either case, the expression is void. 3339 3340 3341@end table 3342 3343 3344@node Java Trees 3345@section Java Trees 3346