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