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