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