3 @c ---------------------------------------------------------------------
4 @c This file is part of GNU CC.
6 @c GNU CC is free software; you can redistribute it and/or modify
7 @c it under the terms of the GNU General Public License as published by
8 @c the Free Software Foundation; either version 2, or (at your option)
11 @c GNU CC is distributed in the hope that it will be useful,
12 @c but WITHOUT ANY WARRANTY; without even the implied warranty of
13 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 @c GNU General Public License for more details.
16 @c You should have received a copy of the GNU General Public License
17 @c along with GNU CC; see the file COPYING. If not, write to
18 @c the Free Software Foundation, 59 Temple Place - Suite 330,
19 @c Boston, MA 02111-1307, USA.
20 @c ---------------------------------------------------------------------
22 @c ---------------------------------------------------------------------
24 @c ---------------------------------------------------------------------
27 @settitle G++ Internal Representation
31 This manual documents the internal representation used by G++ to represent
34 Copyright (c) 1999, 2000 Free Software Foundation, Inc.
37 @c ---------------------------------------------------------------------
39 @c ---------------------------------------------------------------------
42 @title G++ Internal Representation
43 @author CodeSourcery, LLC <info@@codesourcery.com>
45 @vskip 0pt plus 1filll
46 Copyright @copyright{} 1999, 2000 Free Software Foundation, Inc.
49 @c ---------------------------------------------------------------------
51 @c ---------------------------------------------------------------------
54 @top G++ Internal Representation
56 This manual documents the internal representation used by G++ to
57 represent C++ source programs. When presented with a C++ source
58 program, G++ parses the program, performs semantic analysis (including
59 the generation of error messages), and then produces the internal
60 representation described here. This representation contains a complete
61 representation for the entire translation unit provided as input to the
62 G++ front-end. This representation is then typically processed by a
63 code-generator in order to produce machine code, but could also be used
64 in the creation of source browsers, intelligent editors, automatic
65 documentation generators, interpreters, and any other programs needing
66 the ability to process C++ code.
68 This manual explains the internal representation. In particular, this
69 manual documents the internal representation for C++ source constructs,
70 and the macros, functions, and variables that can be used to access
73 If you are developing a ``back-end'', be it is a code-generator or some
74 other tool, that uses this representation, you may occasionally find
75 that you need to ask questions not easily answered by the functions and
76 macros available here. If that situation occurs, it is quite likely
77 that G++ already supports the functionality you desire, but that the
78 interface is simply not documented here. In that case, you should ask
79 the G++ maintainers (via mail to @url{mailto:gcc@@gcc.gnu.org}) about
80 documenting the functionality you require. Similarly, if you find
81 yourself writing functions that do not deal directly with your back-end,
82 but instead might be useful to other people using the G++ front-end, you
83 should submit your patches for inclusion in G++.
86 * Deficiencies:: Topics net yet covered in this document.
87 * Overview:: All about @code{tree}s.
88 * Types:: Fundamental and aggregate types.
89 * Scopes:: Namespaces and classes.
90 * Functions:: Overloading, function bodies, and linkage.
91 * Declarations:: Type declarations and variables.
92 * Expressions:: From @code{typeid} to @code{throw}.
93 * Node Index:: The various types of tree nodes.
94 * Function Index:: Functions and macros described in this manual.
95 * Concept Index:: Index.
98 @c ---------------------------------------------------------------------
100 @c ---------------------------------------------------------------------
103 @chapter Deficiencies
105 There are many places in which this document is incomplet and incorrekt.
106 It is, as of yet, only @emph{preliminary} documentation.
108 @c ---------------------------------------------------------------------
110 @c ---------------------------------------------------------------------
117 The central data structure used by the internal representation is the
118 @code{tree}. These nodes, while all of the C type @code{tree}, are of
119 many varieties. A @code{tree} is a pointer type, but the object to
120 which it points may be of a variety of types. From this point forward,
121 we will refer to trees in ordinary type, rather than in @code{this
122 font}, except when talking about the actual C type @code{tree}.
124 You can tell what kind of node a particular tree is by using the
125 @code{TREE_CODE} macro. Many, many macros take a trees as input and
126 return trees as output. However, most macros require a certain kinds of
127 tree node as input. In other words, there is a type-system for trees,
128 but it is not reflected in the C type-system.
130 For safety, it is useful to configure G++ with @code{--enable-checking}.
131 Although this results in a significant performance penalty (since all
132 tree types are checked at run-time), and is therefore inappropriate in a
133 release version, it is extremely helpful during the development process.
135 Many macros behave as predicates. Many, although not all, of these
136 predicates end in @samp{_P}. Do not rely on the result type of these
137 macros being of any particular type. You may, however, rely on the fact
138 that the type can be compared to @code{0}, so that statements like
140 if (TEST_P (t) && !TEST_P (y))
146 int i = (TEST_P (t) != 0);
149 are legal. Macros that return @code{int} values now may be changed to
150 return @code{tree} values, or other pointers in the future. Even those
151 that continue to return @code{int} may return multiple non-zero codes
152 where previously they returned only zero and one. Therefore, you should
158 as this code is not guaranteed to work correctly in the future.
160 You should not take the address of values returned by the macros or
161 functions described here. In particular, no guarantee is given that the
164 In general, the names of macros are all in uppercase, while the names of
165 functions are entirely in lower case. There are rare exceptions to this
166 rule. You should assume that any macro or function whose name is made
167 up entirely of uppercase letters may evaluate its arguments more than
168 once. You may assume that a macro or function whose name is made up
169 entirely of lowercase letters will evaluate its arguments only once.
171 The @code{error_mark_node} is a special tree. Its tree code is
172 @code{ERROR_MARK}, but since there is only ever one node with that code,
173 the usual practice is to compare the tree against
174 @code{error_mark_node}. (This test is just a test for pointer
175 equality.) If an error has occurred during front-end processing the
176 flag @code{errorcount} will be set. If the front-end has encountered
177 code it cannot handle, it will issue a message to the user and set
178 @code{sorrycount}. When these flags are set, any macro or function
179 which normally returns a tree of a particular kind may instead return
180 the @code{error_mark_node}. Thus, if you intend to do any processing of
181 erroneous code, you must be prepared to deal with the
182 @code{error_mark_node}.
184 Occasionally, a particular tree slot (like an operand to an expression,
185 or a particular field in a declaration) will be referred to as
186 ``reserved for the back-end.'' These slots are used to store RTL when
187 the tree is converted to RTL for use by the GCC back-end. However, if
188 that process is not taking place (e.g., if the front-end is being hooked
189 up to an intelligent editor), then those slots may be used by the
190 back-end presently in use.
192 If you encounter situations that do not match this documentation, such
193 as tree nodes of types not mentioned here, or macros documented to
194 return entities of a particular kind that instead return entities of
195 some different kind, you have found a bug, either in the front-end or in
196 the documentation. Please report these bugs as you would any other
200 * Trees:: Macros and functions that can be used with all trees.
201 * Identifiers:: The names of things.
202 * Containers:: Lists and vectors.
205 @c ---------------------------------------------------------------------
207 @c ---------------------------------------------------------------------
213 This section is not here yet.
215 @c ---------------------------------------------------------------------
217 @c ---------------------------------------------------------------------
223 @tindex IDENTIFIER_NODE
225 An @code{IDENTIFIER_NODE} represents a slightly more general concept
226 that the standard C or C++ concept of identifier. In particular, an
227 @code{IDENTIFIER_NODE} may contain a @samp{$}, or other extraordinary
230 There are never two distinct @code{IDENTIFIER_NODE}s representing the
231 same identifier. Therefore, you may use pointer equality to compare
232 @code{IDENTIFIER_NODE}s, rather than using a routine like @code{strcmp}.
234 You can use the following macros to access identifiers:
236 @item IDENTIFIER_POINTER
237 The string represented by the identifier, represented as a
238 @code{char*}. This string is always @code{NUL}-terminated, and contains
239 no embedded @code{NUL} characters.
241 @item IDENTIFIER_LENGTH
242 The length of the string returned by @code{IDENTIFIER_POINTER}, not
243 including the trailing @code{NUL}. This value of
244 @code{IDENTIFIER_POINTER (x)} is always the same as @code{strlen
245 (IDENTIFIER_POINTER (x))}.
247 @item IDENTIFIER_OPNAME_P
248 This predicate holds if the identifier represents the name of an
249 overloaded operator. In this case, you should not depend on the
250 contents of either the @code{IDENTIFIER_POINTER} or the
251 @code{IDENTIFIER_LENGTH}.
253 @item IDENTIFIER_TYPENAME_P
254 This predicate holds if the identifier represents the name of a
255 user-defined conversion operator. In this case, the @code{TREE_TYPE} of
256 the @code{IDENTIFIER_NODE} holds the type to which the conversion
261 @c ---------------------------------------------------------------------
263 @c ---------------------------------------------------------------------
274 @findex TREE_VEC_LENGTH
277 Two common container data structures can be represented directly with
278 tree nodes. A @code{TREE_LIST} is a singly linked list containing two
279 trees per node. These are the @code{TREE_PURPOSE} and @code{TREE_VALUE}
280 of each node. (Often, the @code{TREE_PURPOSE} contains some kind of
281 tag, or additional information, while the @code{TREE_VALUE} contains the
282 majority of the payload. In other cases, the @code{TREE_PURPOSE} is
283 simply @code{NULL_TREE}, while in still others both the
284 @code{TREE_PURPOSE} and @code{TREE_VALUE} are of equal stature.) Given
285 one @code{TREE_LIST} node, the next node is found by following the
286 @code{TREE_CHAIN}. If the @code{TREE_CHAIN} is @code{NULL_TREE}, then
287 you have reached the end of the list.
289 A @code{TREE_VEC} is a simple vector. The @code{TREE_VEC_LENGTH} is an
290 integer (not a tree) giving the number of nodes in the vector. The
291 nodes themselves are accessed using the @code{TREE_VEC_ELT} macro, which
292 takes two arguments. The first is the @code{TREE_VEC} in question; the
293 second is an integer indicating which element in the vector is desired.
294 The elements are indexed from zero.
296 @c ---------------------------------------------------------------------
298 @c ---------------------------------------------------------------------
305 @cindex fundamental type
309 @tindex TYPE_MIN_VALUE
310 @tindex TYPE_MAX_VALUE
313 @tindex ENUMERAL_TYPE
316 @tindex REFERENCE_TYPE
317 @tindex FUNCTION_TYPE
322 @findex CP_TYPE_QUALS
323 @findex TYPE_UNQUALIFIED
324 @findex TYPE_QUAL_CONST
325 @findex TYPE_QUAL_VOLATILE
326 @findex TYPE_QUAL_RESTRICT
327 @cindex qualified type
330 @findex TYPE_PRECISION
331 @findex TYPE_ARG_TYPES
332 @findex TYPE_METHOD_BASETYPE
333 @findex TYPE_PTRMEM_P
335 All C++ types have corresponding tree nodes. However, you should not
336 assume that there is exactly one tree node corresponding to each C++
337 type. There are often several.
339 For the most part, different kinds of types have different tree codes.
340 (For example, pointer types use a @code{POINTER_TYPE} code while arrays
341 use an @code{ARRAY_TYPE} code.) However, pointers to member functions
342 use the @code{RECORD_TYPE} code. Therefore, when writing a
343 @code{switch} statement that depends on the code associated with a
344 particular type, you should take care to handle pointers to member
345 functions under the @code{RECORD_TYPE} case label.
347 In C++, an array type is not qualified; rather the type of the array
348 elements is qualified. This situation is reflected in the intermediate
349 representation. The macros described here will always examine the
350 qualification of the underlying element type when applied to an array
351 type. (If the element type is itself an array, then the recursion
352 continues until a non-array type is found, and the qualification of this
353 type is examined.) So, for example, @code{CP_TYPE_CONST_P} will hold of
354 the type @code{const int ()[7]}, denoting an array of seven @code{int}s.
356 The following functions and macros deal with cv-qualification of types:
359 This macro returns the set of type qualifiers applied to this type.
360 This value is @code{TYPE_UNQUALIFIED} if no qualifiers have been
361 applied. The @code{TYPE_QUAL_CONST} bit is set if the type is
362 @code{const}-qualified. The @code{TYPE_QUAL_VOLATILE} bit is set if the
363 type is @code{volatile}-qualified. The @code{TYPE_QUAL_RESTRICT} bit is
364 set if the type is @code{restrict}-qualified.
366 @item CP_TYPE_CONST_P
367 This macro holds if the type is @code{const}-qualified.
369 @item CP_TYPE_VOLATILE_P
370 This macro holds if the type is @code{volatile}-qualified.
372 @item CP_TYPE_RESTRICT_P
373 This macro holds if the type is @code{restrict}-qualified.
375 @item TYPE_MAIN_VARIANT
376 This macro returns the unqualified version of a type. It may be applied
377 to an unqualified type, but it is not always the identity function in
381 A few other macros and functions are usable with all types:
384 The number of bits required to represent the type, represented as an
385 @code{INTEGER_CST}. For an incomplete type, @code{TYPE_SIZE} will be
389 The alignment of the type, in bits, represented as an @code{int}.
392 This macro returns a declaration (in the form of a @code{TYPE_DECL}) for
393 the type. (Note this macro does @emph{not} return a
394 @code{IDENTIFIER_NODE}, as you might expect, given its name!) You can
395 look at the @code{DECL_NAME} of the @code{TYPE_DECL} to obtain the
396 actual name of the type. The @code{TYPE_NAME} will be @code{NULL_TREE}
397 for a type that is not a builtin type, the result of a typedef, or a
401 This predicate takes two types as input, and holds if they are the same
402 type. For example, if one type is a @code{typedef} for the other, or
403 both are @code{typedef}s for the same type. This predicate also holds if
404 the two trees given as input are simply copies of one another; i.e.,
405 there is no difference between them at the source level, but, for
406 whatever reason, a duplicate has been made in the representation. You
407 should never use @code{==} (pointer equality) to compare types; always
408 use @code{same_type_p} instead.
411 Detailed below are the various kinds of types, and the macros that can
412 be used to access them. Although other kinds of types are used
413 elsewhere in G++, the types described here are the only ones that you
414 will encounter while examining the intermediate representation.
418 Used to represent the @code{void} type.
421 Used to represent the various integral types, including @code{char},
422 @code{short}, @code{int}, @code{long}, and @code{long long}. This code
423 is not used for enumeration types, nor for the @code{bool} type. Note
424 that GCC's @code{CHAR_TYPE} node is @emph{not} used to represent
425 @code{char}. The @code{TYPE_PRECISION} is the number of bits used in
426 the representation, represented as an @code{unsigned int}. (Note that
427 in the general case this is not the same value as @code{TYPE_SIZE};
428 suppose that there were a 24-bit integer type, but that alignment
429 requirements for the ABI required 32-bit alignment. Then,
430 @code{TYPE_SIZE} would be an @code{INTEGER_CST} for 32, while
431 @code{TYPE_PRECISION} would be 24.) The integer type is unsigned if
432 @code{TREE_UNSIGNED} holds; otherwise, it is signed.
434 The @code{TYPE_MIN_VALUE} is an @code{INTEGER_CST} for the smallest
435 integer that may be represented by this type. Similarly, the
436 @code{TYPE_MAX_VALUE} is an @code{INTEGER_CST} for the largest integer
437 that may be represented by this type.
440 Used to represent the @code{float}, @code{double}, and @code{long
441 double} types. The number of bits in the floating-point representation
442 is given by @code{TYPE_PRECISION}, as in the @code{INTEGER_TYPE} case.
445 FIXME: The __complex__ extension is supported in G++. Document.
448 Used to represent an enumeration type. The @code{TYPE_PRECISION} gives
449 (as an @code{int}), the number of bits used to represent the type. If
450 there are no negative enumeration constants, @code{TREE_UNSIGNED} will
451 hold. The minimum and maximum enumeration constants may be obtained
452 with @code{TYPE_MIN_VALUE} and @code{TYPE_MAX_VALUE}, respectively; each
453 of these macros returns an @code{INTEGER_CST}.
455 The actual enumeration constants themselves may be obtained by looking
456 at the @code{TYPE_VALUES}. This macro will return a @code{TREE_LIST},
457 containing the constants. The @code{TREE_PURPOSE} of each node will be
458 an @code{IDENTIFIER_NODE} giving the name of the constant; the
459 @code{TREE_VALUE} will be an @code{INTEGER_CST} giving the value
460 assigned to that constant. These constants will appear in the order in
461 which they were declared. The @code{TREE_TYPE} of each of these
462 constants will be the type of enumeration type itself.
465 Used to represent the @code{bool} type.
468 Used to represent pointer types, and pointer to data member types. The
469 @code{TREE_TYPE} gives the type to which this type points. If the type
470 is a pointer to data member type, then @code{TYPE_PTRMEM_P} will hold.
471 For a pointer to data member type of the form @samp{T X::*},
472 @code{TYPE_PTRMEM_CLASS_TYPE} will be the type @code{X}, while
473 @code{TYPE_PTRMEM_POINTED_TO_TYPE} will be the type @code{T}.
476 Used to represent reference types. The @code{TREE_TYPE} gives the type
477 to which this type refers.
480 Used to represent the type of non-member functions and of static member
481 functions. The @code{TREE_TYPE} gives the return type of the function.
482 The @code{TYPE_ARG_TYPES} are a @code{TREE_LIST} of the argument types.
483 The @code{TREE_VALUE} of each node in this list is the type of the
484 corresponding argument; the @code{TREE_PURPOSE} is an expression for the
485 default argument value, if any. If the last node in the list is
486 @code{void_list_node} (a @code{TREE_LIST} node whose @code{TREE_VALUE}
487 is the @code{void_type_node}), then functions of this type do not take
488 variable arguments. Otherwise, they do take a variable number of
492 Used to represent the type of a non-static member function. Like a
493 @code{FUNCTION_TYPE}, the return type is given by the @code{TREE_TYPE}.
494 The type of @code{*this}, i.e., the class of which functions of this
495 type are a member, is given by the @code{TYPE_METHOD_BASETYPE}. The
496 @code{TYPE_ARG_TYPES} is the parameter list, as for a
497 @code{FUNCTION_TYPE}, and includes the @code{this} argument.
500 Used to represent array types. The @code{TREE_TYPE} gives the type of
501 the elements in the array. If the array-bound is present in the type,
502 the @code{TYPE_DOMAIN} is an @code{INTEGER_TYPE} whose
503 @code{TYPE_MIN_VALUE} and @code{TYPE_MAX_VALUE} will be the lower and
504 upper bounds of the array, respectively. The @code{TYPE_MIN_VALUE} will
505 always be an @code{INTEGER_CST} for zero, while the
506 @code{TYPE_MAX_VALUE} will be one less than the number of elements in
507 the array, i.e., the highest value which may be used to index an element
511 Used to represent @code{struct} and @code{class} types, as well as
512 pointers to member functions. If @code{TYPE_PTRMEMFUNC_P} holds, then
513 this type is a pointer-to-member type. In that case, the
514 @code{TYPE_PTRMEMFUNC_FN_TYPE} is a @code{POINTER_TYPE} pointing to a
515 @code{METHOD_TYPE}. The @code{METHOD_TYPE} is the type of a function
516 pointed to by the pointer-to-member function. If
517 @code{TYPE_PTRMEMFUNC_P} does not hold, this type is a class type. For
518 more information, see @pxref{Classes}.
521 Used to represent @code{union} types. For more information, @pxref{Classes}.
524 There are variables whose values represent some of the basic types.
528 A node for @code{void}.
530 @item integer_type_node
531 A node for @code{int}.
533 @item unsigned_type_node.
534 A node for @code{unsigned int}.
536 @item char_type_node.
537 A node for @code{char}.
540 It may sometimes be useful to compare one of these variables with a type
541 in hand, using @code{same_type_p}.
543 @c ---------------------------------------------------------------------
545 @c ---------------------------------------------------------------------
549 @cindex namespace, class, scope
551 The root of the entire intermediate representation is the variable
552 @code{global_namespace}. This is the namespace specified with @code{::}
553 in C++ source code. All other namespaces, types, variables, functions,
554 and so forth can be found starting with this namespace.
556 Besides namespaces, the other high-level scoping construct in C++ is the
557 class. (Throughout this manual the term @dfn{class} is used to mean the
558 types referred to in the ANSI/ISO C++ Standard as classes; these include
559 types defined with the @code{class}, @code{struct}, and @code{union}
563 * Namespaces:: Member functions, types, etc.
564 * Classes:: Members, bases, friends, etc.
567 @c ---------------------------------------------------------------------
569 @c ---------------------------------------------------------------------
574 @tindex NAMESPACE_DECL
576 A namespace is represented by a @code{NAMESPACE_DECL} node.
578 However, except for the fact that it is distinguished as the root of the
579 representation, the global namespace is no different from any other
580 namespace. Thus, in what follows, we describe namespaces generally,
581 rather than the global namespace in particular.
583 The @code{::std} namespace, however, @emph{is} special, unless
584 @code{flag_honor_std} is set. This variable is set by the use
585 @samp{-fhonor-std} (or an option that implies it, like
586 @samp{-fnew-abi}), when invoking G++. When @code{flag_honor_std} is
587 set, the @code{std} namespace is just like any other namespace. When
588 @code{flag_honor_std} is not set, however, the @code{::std} namespace is
589 treated as a synonym for the global namespace, thereby allowing users to
590 write code that will work with compilers that put the standard library
591 in the @code{::std} namespace, even though the library supplied with G++
592 does not do so, as of GCC 2.95. The @code{std} namespace is represented
593 by the variable @code{std_node}. Although @code{std_node} is a
594 @code{NAMESPACE_DECL}, it does not have all the fields required of a
595 real namespace, and the macros and functions described here do not work,
596 in general. It is safest simply to ignore @code{std_node} should you
597 encounter it while examining the internal representation. In
598 particular, you will encounter @code{std_node} while looking at the
599 members of the global namespace. Just skip it without attempting to
602 The following macros and functions can be used on a @code{NAMESPACE_DECL}:
606 This macro is used to obtain the @code{IDENTIFIER_NODE} corresponding to
607 the unqualified name of the name of the namespace (@pxref{Identifiers}).
608 The name of the global namespace is @samp{::}, even though in C++ the
609 global namespace is unnamed. However, you should use comparison with
610 @code{global_namespace}, rather than @code{DECL_NAME} to determine
611 whether or not a namespaces is the global one. An unnamed namespace
612 will have a @code{DECL_NAME} equal to @code{anonymous_namespace_name}.
613 Within a single translation unit, all unnamed namespaces will have the
617 This macro returns the enclosing namespace. The @code{DECL_CONTEXT} for
618 the @code{global_namespace} is @code{NULL_TREE}.
620 @item DECL_NAMESPACE_ALIAS
622 If this declaration is for a namespace alias, then
623 @code{DECL_NAMESPACE_ALIAS} is the namespace for which this one is an
626 Do not attempt to use @code{cp_namespace_decls} for a namespace which is
627 an alias. Instead, follow @code{DECL_NAMESPACE_ALIAS} links until you
628 reach an ordinary, non-alias, namespace, and call
629 @code{cp_namespace_decls} there.
631 @item cp_namespace_decls
632 This function will return the declarations contained in the namespace,
633 including types, overloaded functions, other namespaces, and so forth.
634 If there are no declarations, this function will return
635 @code{NULL_TREE}. The declarations are connected through their
636 @code{TREE_CHAIN} fields.
638 Although most entries on this list will be declarations,
639 @code{TREE_LIST} nodes may also appear. In this case, the
640 @code{TREE_VALUE} will be an @code{OVERLOAD}. The value of the
641 @code{TREE_PURPOSE} is unspecified; back-ends should ignore this value.
642 As with the other kinds of declarations returned by
643 @code{cp_namespace_decls}, the @code{TREE_CHAIN} will point to the next
644 declaration in this list.
646 For more information on the kinds of declarations that can occur on this
647 list, @xref{Declarations}. Some declarations will not appear on this
648 list. In particular, no @code{FIELD_DECL}, @code{LABEL_DECL}, or
649 @code{PARM_DECL} nodes will appear here.
651 This function cannot be used with namespaces that have
652 @code{DECL_NAMESPACE_ALIAS} set.
656 @c ---------------------------------------------------------------------
658 @c ---------------------------------------------------------------------
665 @findex CLASSTYPE_DECLARED_CLASS
668 @findex TREE_VIA_PUBLIC
669 @findex TREE_VIA_PROTECTED
670 @findex TREE_VIA_PRIVATE
675 A class type is represented by either a @code{RECORD_TYPE} or a
676 @code{UNION_TYPE}. A class declared with the @code{union} tag is
677 represented by a @code{UNION_TYPE}, while classes declared with either
678 the @code{struct} or the @code{class} tag are represented by
679 @code{RECORD_TYPE}s. You can use the @code{CLASSTYPE_DECLARED_CLASS}
680 macro to discern whether or not a particular type is a @code{class} as
681 opposed to a @code{struct}. This macro will be true only for classes
682 declared with the @code{class} tag.
684 Almost all non-function members are available on the @code{TYPE_FIELDS}
685 list. Given one member, the next can be found by following the
686 @code{TREE_CHAIN}. You should not depend in any way on the order in
687 which fields appear on this list. All nodes on this list will be
688 @samp{DECL} nodes. A @code{FIELD_DECL} is used to represent a non-static
689 data member, a @code{VAR_DECL} is used to represent a static data
690 member, and a @code{TYPE_DECL} is used to represent a type. Note that
691 the @code{CONST_DECL} for an enumeration constant will appear on this
692 list, if the enumeration type was declared in the class. (Of course,
693 the @code{TYPE_DECL} for the enumeration type will appear here as well.)
694 There are no entries for base classes on this list. In particular,
695 there is no @code{FIELD_DECL} for the ``base-class portion'' of an
698 The @code{TYPE_VFIELD} is a compiler-generated field used to point to
699 virtual function tables. It may or may not appear on the
700 @code{TYPE_FIELDS} list. However, back-ends should handle the
701 @code{TYPE_VFIELD} just like all the entries on the @code{TYPE_FIELDS}
704 The function members are available on the @code{TYPE_METHODS} list.
705 Again, subsequent members are found by following the @code{TREE_CHAIN}
706 field. If a function is overloaded, each of the overloaded functions
707 appears; no @code{OVERLOAD} nodes appear on the @code{TYPE_METHODS}
708 list. Implicitly declared functions (including default constructors,
709 copy constructors, assignment operators, and destructors) will appear on
712 Every class has an associated @dfn{binfo}, which can be obtained with
713 @code{TYPE_BINFO}. Binfos are used to represent base-classes. The
714 binfo given by @code{TYPE_BINFO} is the degenerate case, whereby every
715 class is considered to be its own base-class. The base classes for a
716 particular binfo can be obtained with @code{BINFO_BASETYPES}. These
717 base-classes are themselves binfos. The class type associated with a
718 binfo is given by @code{BINFO_TYPE}. It is always the case that
719 @code{BINFO_TYPE (TYPE_BINFO (x))} is the same type as @code{x}, up to
720 qualifiers. However, it is not always the case that @code{TYPE_BINFO
721 (BINFO_TYPE (y))} is always the same binfo as @code{y}. The reason is
722 that if @code{y} is a binfo representing a base-class @code{B} of a
723 derived class @code{D}, then @code{BINFO_TYPE (y)} will be @code{B}, and
724 @code{TYPE_INFO (BINFO_TYPE (y))} will be @code{B} as its own
725 base-class, rather than as a base-class of @code{D}.
727 The @code{BINFO_BASETYPES} is a @code{TREE_VEC} (@pxref{Containers}).
728 Base types appear in left-to-right order in this vector. You can tell
729 whether or @code{public}, @code{protected}, or @code{private}
730 inheritance was used by using the @code{TREE_VIA_PUBLIC},
731 @code{TREE_VIA_PROTECTED}, and @code{TREE_VIA_PRIVATE} macros. Each of
732 these macros takes a @code{BINFO} and is true if and only if the
733 indicated kind of inheritance was used. If @code{TREE_VIA_VIRTUAL}
734 holds of a binfo, then its @code{BINFO_TYPE} was inherited from
737 FIXME: Talk about @code{TYPE_NONCOPIED_PARTS}.
739 @c ---------------------------------------------------------------------
741 @c ---------------------------------------------------------------------
744 @chapter Declarations
747 @cindex type declaration
754 @tindex NAMESPACE_DECL
756 @tindex TEMPLATE_DECL
763 @findex DECL_EXTERNAL
765 This chapter covers the various kinds of declarations that appear in the
766 internal representation, except for declarations of functions
767 (represented by @code{FUNCTION_DECL} nodes), which are described in
770 Some macros can be used with any kind of declaration. These include:
773 This macro returns an @code{IDENTIFIER_NODE} giving the name of the
777 This macro returns the type of the entity declared.
779 @item DECL_SOURCE_FILE
780 This macro returns the name of the file in which the entity was
781 declared, as a @code{char*}. For an entity declared implicitly by the
782 compiler (like @code{__builtin_memcpy}), this will be the string
785 @item DECL_SOURCE_LINE
786 This macro returns the line number at which the entity was declared, as
789 @item DECL_ARTIFICIAL
790 This predicate holds if the declaration was implicitly generated by the
791 compiler. For example, this predicate will hold of an implicitly
792 declared member function, or of the @code{TYPE_DECL} implicitly
793 generated for a class type. Recall that in C++ code like:
798 is roughly equivalent to C code like:
803 The implicitly generated @code{typedef} declaration is represented by a
804 @code{TYPE_DECL} for which @code{DECL_ARTIFICIAL} holds.
807 The various kinds of declarations include:
810 These nodes are used to represent labels in function bodies. For more
811 information, see @ref{Functions}. These nodes only appear in block
815 These nodes are used to represent enumeration constants. The value of
816 the constant is given by @code{DECL_INITIAL} which will be an
817 @code{INTEGER_CST} with the same type as the @code{TREE_TYPE} of the
818 @code{CONST_DECL}, i.e., an @code{ENUMERAL_TYPE}.
821 These nodes represent the value returned by a function. When a value is
822 assigned to a @code{RESULT_DECL}, that indicates that the value should
823 be returned, via bitwise copy, by the function. You can use
824 @code{DECL_SIZE} and @code{DECL_ALIGN} on a @code{RESULT_DECL}, just as
825 with a @code{VAR_DECL}.
828 These nodes represent @code{typedef} declarations. The @code{TREE_TYPE}
829 is the type declared to have the name given by @code{DECL_NAME}. In
830 some cases, there is no associated name.
833 These nodes represent variables with namespace or block scope, as well
834 as static data members. The @code{DECL_SIZE} and @code{DECL_ALIGN} are
835 analogous to @code{TYPE_SIZE} and @code{TYPE_ALIGN}. For a declaration,
836 you should always use the @code{DECL_SIZE} and @code{DECL_ALIGN} rather
837 than the @code{TYPE_SIZE} and @code{TYPE_ALIGN} given by the
838 @code{TREE_TYPE}, since special attributes may have been applied to the
839 variable to give it a particular size and alignment.
841 If this variable is initialized (but does not require a constructor),
842 the @code{DECL_INITIAL} will be an expression for the initializer. The
843 initializer should be evaluated, and a bitwise copy into the variable
844 performed. If the @code{DECL_INITIAL} is the @code{error_mark_node},
845 there is an initializer, but it is given by an explicit statement later
846 in the code; no bitwise copy is required.
849 Used to represent a parameter to a function. Treat these nodes
850 similarly to @code{VAR_DECL} nodes. These nodes only appear in the
851 @code{DECL_ARGUMENTS} for a @code{FUNCTION_DECL}.
853 The @code{DECL_ARG_TYPE} for a @code{PARM_DECL} is the type that will
854 actually be used when a value is passed to this function. It may be a
855 wider type than the @code{TREE_TYPE} of the parameter; for example, the
856 ordinary type might be @code{short} while the @code{DECL_ARG_TYPE} is
860 These nodes represent non-static data members. The @code{DECL_SIZE} and
861 @code{DECL_ALIGN} behave as for @code{VAR_DECL} nodes. The
862 @code{DECL_FIELD_BITPOS} gives the first bit used for this field, as an
863 @code{INTEGER_CST}. These values are indexed from zero, where zero
864 indicates the first bit in the object.
866 If @code{DECL_C_BIT_FIELD} holds, this field is a bitfield.
873 These nodes are used to represent class, function, and variable (static
874 data member) templates. The @code{DECL_TEMPLATE_SPECIALIZATIONS} are a
875 @code{TREE_LIST}. The @code{TREE_VALUE} of each node in the lst is a
876 @code{TEMPLATE_DECL}s or @code{FUNCTION_DECL}s representing
877 specializations (including instantiations) of this template. Back-ends
878 can safely ignore @code{TEMPLATE_DECL}s, but should examine
879 @code{FUNCTION_DECL} nodes on the specializations list just as they
880 would ordinary @code{FUNCTION_DECL} nodes.
882 For a class template, the @code{DECL_TEMPLATE_INSTANTIATIONS} list
883 contains the instantiations. The @code{TREE_VALUE} of each node is an
884 instantiation of the class. The @code{DECL_TEMPLATE_SPECIALIZATIONS}
885 contains partial specializations of the class.
889 These nodes represent stub code that adjusts the @code{this} pointer and
890 then jumps to another function. When the jumped-to function returns,
891 control is transferred directly to the caller, without returning to the
892 thunk. The first parameter to the thunk is always the @code{this}
893 pointer; the thunk should add @code{THUNK_DELTA} to this value. (The
894 @code{THUNK_DELTA} is an @code{int}, not an @code{INTEGER_CST}.) Then,
895 the thunk should jump to the location given by @code{DECL_INITIAL}; this
896 will always be an expression for the address of a function.
898 You can use @code{DECL_ASSEMBLER_NAME}, @code{TREE_PUBLIC}, and
899 @code{DECL_ARGUMENTS} with a @code{THUNK_DECL}, just as with a
900 @code{FUNCTION_DECL}.
904 Back-ends can safely ignore these nodes.
908 @c ---------------------------------------------------------------------
910 @c ---------------------------------------------------------------------
915 @tindex FUNCTION_DECL
920 A function is represented by a @code{FUNCTION_DECL} node. A set of
921 overloaded functions is sometimes represented by a @code{OVERLOAD} node.
923 An @code{OVERLOAD} node is not a declaration, so none of the
924 @samp{DECL_} macros should be used on an @code{OVERLOAD}. An
925 @code{OVERLOAD} node is similar to a @code{TREE_LIST}. Use
926 @code{OVL_CURRENT} to get the function associated with an
927 @code{OVERLOAD} node; use @code{OVL_NEXT} to get the next
928 @code{OVERLOAD} node in the list of overloaded functions. The macros
929 @code{OVL_CURRENT} and @code{OVL_NEXT} are actually polymorphic; you can
930 use them to work with @code{FUNCTION_DECL} nodes as well as with
931 overlods. In the case of a @code{FUNCTION_DECL}, @code{OVL_CURRENT}
932 will always return the function itself, and @code{OVL_NEXT} will always
935 To determine the scope of a function, you can use the
936 @code{DECL_REAL_CONTEXT} macro. This macro will return the class
937 (either a @code{RECORD_TYPE} or a @code{UNION_TYPE}) or namespace (a
938 @code{NAMESPACE_DECL}) of which the function is a member. For a virtual
939 function, this macro returns the class in which the function was
940 actually defined, not the base class in which the virtual declaration
941 occurred. If a friend function is defined in a class scope, the
942 @code{DECL_CLASS_CONTEXT} macro can be used to determine the class in
943 which it was defined. For example, in
945 class C @{ friend void f() @{@} @};
947 the @code{DECL_REAL_CONTEXT} for @code{f} will be the
948 @code{global_namespace}, but the @code{DECL_CLASS_CONTEXT} will be the
949 @code{RECORD_TYPE} for @code{C}.
952 * Function Basics:: Function names, linkage, and so forth.
953 * Function Bodies:: The statements that make up a function body.
956 @c ---------------------------------------------------------------------
958 @c ---------------------------------------------------------------------
960 @node Function Basics
961 @section Function Basics
964 @cindex copy constructor
965 @cindex assignment operator
968 @findex DECL_ASSEMBLER_NAME
970 @findex DECL_LINKONCE_P
971 @findex DECL_FUNCTION_MEMBER_P
972 @findex DECL_CONSTRUCTOR_P
973 @findex DECL_DESTRUCTOR_P
974 @findex DECL_OVERLOADED_OPERATOR_P
975 @findex DECL_CONV_FN_P
976 @findex DECL_ARTIFIICIAL
977 @findex DECL_GLOBAL_CTOR_P
978 @findex DECL_GLOBAL_DTOR_P
979 @findex GLOBAL_INIT_PRIORITY
981 The following macros and functions can be used on a @code{FUNCTION_DECL}:
984 This macro returns the unqualified name of the function, as an
985 @code{IDENTIFIER_NODE}. For an instantiation of a function template,
986 the @code{DECL_NAME} is the unqualified name of the template, not
987 something like @code{f<int>}. The value of @code{DECL_NAME} is
988 undefined when used on a constructor, destructor, overloaded operator,
989 or type-conversion operator, or any function that is implicitly
990 generated by the compiler. See below for macros that can be used to
991 distinguish these cases.
993 @item DECL_ASSEMBLER_NAME
994 This macro returns the mangled name of the function, also an
995 @code{IDENTIFIER_NODE}. This name does not contain leading underscores
996 on systems that prefix all identifiers with underscores. The mangled
997 name is computed in the same way on all platforms; if special processing
998 is required to deal with the object file format used on a particular
999 platform, it is the responsibility of the back-end to perform those
1000 modifications. (Of course, the back-end should not modify
1001 @code{DECL_ASSEMBLER_NAME} itself.)
1004 This predicate holds if the function is undefined.
1007 This predicate holds if the function has external linkage.
1009 @item DECL_LINKONCE_P
1010 This macro holds if multiple copies of this function may be emitted in
1011 various translation units. It is the responsibility of the linker to
1012 merge the various copies. Template instantiations are the most common
1013 example of functions for which @code{DECL_LINKONCE_P} holds; G++
1014 instantiates needed templates in all translation units which require them,
1015 and then relies on the linker to remove duplicate instantiations.
1017 FIXME: This macro is not yet implemented.
1019 @item DECL_FUNCTION_MEMBER_P
1020 This macro holds if the function is a member of a class, rather than a
1021 member of a namespace.
1023 @item DECL_NONSTATIC_MEMBER_FUNCTION_P
1024 This macro holds for a non-static member function.
1026 @item DECL_CONSTRUCTOR_P
1027 This macro holds if the function is a constructor.
1029 @item DECL_DESTRUCTOR_P
1030 This macro holds if the function is a destructor.
1032 @item DECL_OVERLOADED_OPERATOR_P
1033 This macro holds if the function is an overloaded operator.
1035 @item DECL_CONV_FN_P
1036 This macro holds if the function is a type-conversion operator.
1038 @item DECL_GLOBAL_CTOR_P
1039 This predicate holds if the function is a file-scope initialization
1042 @item DECL_GLOBAL_DTOR_P
1043 This predicate holds if the function is a file-scope finalization
1046 @item GLOBAL_INIT_PRIORITY
1047 If either @code{DECL_GLOBAL_CTOR_P} or @code{DECL_GLOBAL_DTOR_P} holds,
1048 then this gives the initialization priority for the function. The
1049 linker will arrange that all functions for which
1050 @code{DECL_GLOBAL_CTOR_P} holds are run in increasing order of priority
1051 before @code{main} is called. When the program exits, all functions for
1052 which @code{DECL_GLOBAL_DTOR_P} holds are run in the reverse order.
1054 @item DECL_ARTIFICIAL
1055 This macro holds if the function was implicitly generated by the
1056 compiler, rather than explicitly declared. In addition to implicitly
1057 generated class member functions, this macro holds for the special
1058 functions created to implement static initialization and destruction, to
1059 compute run-time type information, and so forth.
1061 @item DECL_ARGUMENTS
1062 This macro returns the @code{PARM_DECL} for the first argument to the
1063 function. Subsequent @code{PARM_DECL} nodes can be obtained by
1064 following the @code{TREE_CHAIN} links.
1067 This macro returns the @code{RESULT_DECL} for the function.
1070 This macro returns the @code{FUNCTION_TYPE} or @code{METHOD_TYPE} for
1075 @c ---------------------------------------------------------------------
1077 @c ---------------------------------------------------------------------
1079 @node Function Bodies
1080 @section Function Bodies
1081 @cindex function body
1088 @findex ASM_CLOBBERS
1090 @tindex CLEANUP_STMT
1091 @findex CLEANUP_DECL
1092 @findex CLEANUP_EXPR
1093 @tindex COMPOUND_STMT
1094 @findex COMPOUND_BODY
1095 @tindex CONTINUE_STMT
1097 @findex DECL_STMT_DECL
1101 @tindex EMPTY_CLASS_EXPR
1103 @findex EXPR_STMT_EXPR
1105 @findex FOR_INIT_STMT
1110 @findex GOTO_DESTINATION
1117 @tindex LABEL_STMT_LABEL
1122 @findex SCOPE_BEGIN_P
1124 @findex SCOPE_NULLIFIED_P
1125 @tindex START_CATCH_STMT
1126 @findex START_CATCH_TYPE
1128 @findex SUBOBJECT_CLEANUP
1134 @findex TRY_HANDLERS
1135 @findex HANDLER_PARMS
1136 @findex HANDLER_BODY
1141 A function that has a definition in the current translation unit will
1142 have a non-NULL @code{DECL_INITIAL}. However, back-ends should not make
1143 use of the particular value given by @code{DECL_INITIAL}.
1145 The @code{DECL_SAVED_TREE} macro will give the complete body of the
1146 function. This node will usually be a @code{COMPOUND_STMT} representing
1147 the outermost block of the function, but it may also be a
1148 @code{TRY_BLOCK}, a @code{RETURN_INIT}, or any other valid statement.
1150 @subsection Statements
1152 There are tree nodes corresponding to all of the source-level statement
1153 constructs. These are enumerated here, together with a list of the
1154 various macros that can be used to obtain information about them. There
1155 are a few macros that can be used with all statements:
1159 This macro returns the line number for the statement. If the statement
1160 spans multiple lines, this value will be the number of the first line on
1161 which the statement occurs. Although we mention @code{CASE_LABEL} below
1162 as if it were a statement, they do not allow the use of
1163 @code{STMT_LINENO}. There is no way to obtain the line number for a
1166 Statements do not contain information about
1167 the file from which they came; that information is implicit in the
1168 @code{FUNCTION_DECL} from which the statements originate.
1170 @item STMT_IS_FULL_EXPR_P
1171 In C++, statements normally constitute ``full expressions''; temporaries
1172 created during a statement are destroyed when the statement is complete.
1173 However, G++ sometimes represents expressions by statements; these
1174 statements will not have @code{STMT_IS_FULL_EXPR_P} set. Temporaries
1175 created during such statements should be destroyed when the innermost
1176 enclosing statement with @code{STMT_IS_FULL_EXPR_P} set is exited.
1180 Here is the list of the various statement nodes, and the macros used to
1181 access them. This documentation describes the use of these nodes in
1182 non-template functions (including instantiations of template functions).
1183 In template functions, the same nodes are used, but sometimes in
1184 slightly different ways.
1186 Many of the statements have substatements. For example, a @code{while}
1187 loop will have a body, which is itself a statement. If the substatement
1188 is @code{NULL_TREE}, it is considered equivalent to a statement
1189 consisting of a single @code{;}, i.e., an expression statement in which
1190 the expression has been omitted. A substatement may in fact be a list
1191 of statements, connected via their @code{TREE_CHAIN}s. So, you should
1192 always process the statement tree by looping over substatements, like
1195 void process_stmt (stmt)
1200 switch (TREE_CODE (stmt))
1203 process_stmt (THEN_CLAUSE (stmt));
1204 /* More processing here. */
1210 stmt = TREE_CHAIN (stmt);
1214 In other words, while the @code{then} clause of an @code{if} statement
1215 in C++ can be only one statement (although that one statement may be a
1216 compound statement), the intermediate representation will sometimes use
1217 several statements chained together.
1222 Used to represent an inline assembly statement. For an inline assembly
1227 The @code{ASM_STRING} macro will return a @code{STRING_CST} node for
1228 @code{"mov x, y"}. If the original statement made use of G++'s
1229 extended-assembly syntax, then @code{ASM_OUTPUTS},
1230 @code{ASM_INPUTS}, and @code{ASM_CLOBBERS} will be the outputs, inputs,
1231 and clobbers for the statement, represented as @code{STRING_CST} nodes.
1232 The extended-assembly syntax looks like:
1234 asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
1236 The first string is the @code{ASM_STRING}, containing the instruction
1237 template. The next two strings are the output and inputs, respectively;
1238 this statement has no clobbers. As this example indicates, ``plain''
1239 assembly statements are merely a special case of extended assembly
1240 statements; they have no cv-qualifiers, outputs, inputs, or clobbers.
1241 All of the strings will be @code{NUL}-terminated, and will contain no
1242 embedded @code{NUL}-characters.
1244 If the assembly statement is declared @code{volatile}, or if the
1245 statement was not an extended assembly statement, and is therefore
1246 implicitly volatile, then the predicate @code{ASM_VOLATILE_P} will hold
1247 of the @code{ASM_STMT}.
1251 Used to represent a @code{break} statement. There are no additional
1256 Use to represent a @code{case} label, range of @code{case} labels, or a
1257 @code{default} label. If @code{CASE_LOW} is NULL_TREE, then this is a a
1258 @code{default} label. Otherwise, if @code{CASE_HIGH} is NULL_TREE, then
1259 this is an ordinary @code{case} label. In this case, @code{CASE_LOW} is
1260 an expression giving the value of the label. Both @code{CASE_LOW} and
1261 @code{CASE_HIGH} are @code{INTEGER_CST} nodes. These values will have
1262 the same type as the condition expression in the switch statement.
1264 Otherwise, if both @code{CASE_LOW} and @code{CASE_HIGH} are defined, the
1265 statement is a range of case labels. Such statements originate with the
1266 G++ extension that allows users to write things of the form:
1270 The first value will be @code{CASE_LOW}, while the second will be
1275 Used to represent an action that should take place upon exit from the
1276 enclosing scope. Typically, these actions are calls to destructors for
1277 local objects, but back-ends cannot rely on this fact. If these nodes
1278 are in fact representing such destructors, @code{CLEANUP_DECL} will be
1279 the @code{VAR_DECL} destroyed. Otherwise, @code{CLEANUP_DECL} will be
1280 @code{NULL_TREE}. In any case, the @code{CLEANUP_EXPR} is the
1281 expression to execute. The cleanups executed on exit from a scope
1282 should be run in the reverse order of the order in which the associated
1283 @code{CLEANUP_STMT}s were encountered.
1287 Used to represent a brace-enclosed block. The first substatement is
1288 given by @code{COMPOUND_BODY}. Subsequent substatements are found by
1289 following the @code{TREE_CHAIN} link from one substatement to the next.
1293 Used to represent a @code{continue} statement. There are no additional
1298 Used to mark the beginning (if @code{CTOR_BEGIN_P} holds) or end (if
1299 @code{CTOR_END_P} holds of the main body of a constructor. See also
1300 @code{SUBOBJECT} for more information on how to use these nodes.
1304 Used to represent a local declaration. The @code{DECL_STMT_DECL} macro
1305 can be used to obtain the entity declared. This declaration may be a
1306 @code{LABEL_DECL}, indicating that the label declared is a local label.
1307 (As an extension, GCC allows the declaration of labels with scope.)
1311 Used to represent a @code{do} loop. The body of the loop is given by
1312 @code{DO_BODY} while the termination condition for the loop is given by
1313 @code{DO_COND}. The condition for a @code{do}-statement is always an
1316 @item EMPTY_CLASS_EXPR
1318 Used to represent a temporary object of a class with no data whose
1319 address is never taken. (All such objects are interchangeable.) The
1320 @code{TREE_TYPE} represents the type of the object.
1324 Used to represent an expression statement. Use @code{EXPR_STMT_EXPR} to
1325 obtain the expression.
1329 Used to represent a @code{for} statement. The @code{FOR_INIT_STMT} is
1330 the initialization statement for the loop. The @code{FOR_COND} is the
1331 termination condition. The @code{FOR_EXPR} is the expression executed
1332 right before the @code{FOR_COND} on each loop iteration; often, this
1333 expression increments a counter. The body of the loop is given by
1334 @code{FOR_BODY}. Note that @code{FOR_INIT_STMT} and @code{FOR_BODY}
1335 return statements, while @code{FOR_COND} and @code{FOR_EXPR} return
1340 Used to represent a @code{goto} statement. The @code{GOTO_DESTINATION}
1341 will usually be a @code{LABEL_DECL}. However, if G++'s ``computed
1342 goto'' extension has been used, the @code{GOTO_DESTINATION} will be an
1343 arbitrary expression indicating the destination. This expression will
1344 always have pointer type.
1348 Used to represent an @code{if} statement. The @code{IF_COND} is the
1349 expression or statement used as the condition. If the condition is a
1350 statement, it will always be a @code{DECL_STMT}; the variable will then
1351 be used as the condition.
1353 The @code{THEN_CLAUSE} represents the statement given by the @code{then}
1354 condition, while the @code{ELSE_CLAUSE} represents the statement given
1355 by the @code{else} condition.
1359 Used to represent a label. The @code{LABEL_DECL} declared by this
1360 statement can be obtained with the @code{LABEL_STMT_LABEL} macro. The
1361 @code{IDENTIFIER_NODE} giving the name of the label can be obtained from
1362 the @code{LABEL_DECL} with @code{DECL_NAME}.
1366 If the function uses the G++ ``named return value'' extension, meaning
1367 that the function has been defined like:
1369 S f(int) return s @{...@}
1371 then there will be a @code{RETURN_INIT}. There is never a named
1372 returned value for a constructor. The first argument to the
1373 @code{RETURN_INIT} is the name of the object returned; the second
1374 argument is the initializer for the object. The object is initialized
1375 when the @code{RETURN_INIT} is encountered. The object referred to is
1376 the actual object returned; this extension is a manual way of doing the
1377 ``return-value optimization.'' Therefore, the object must actually be
1378 constructed in the place where the object will be returned.
1382 Used to represent a @code{return} statement. The @code{RETURN_EXPR} is
1383 the expression returned; it will be @code{NULL_TREE} if the statement
1391 A scope-statement represents the beginning or end of a scope. If
1392 @code{SCOPE_BEGIN_P} holds, this statement represents the beginning of a
1393 scope; if @code{SCOPE_END_P} holds this statement represents the end of
1394 a scope. On exit from a scope, all cleanups from @code{CLEANUP_STMT}s
1395 occurring in the scope must be run, in reverse order to the order in
1396 which they were encountered. If @code{SCOPE_NULLIFIED_P} or
1397 @code{SCOPE_NO_CLEANUPS_P} holds of the scope, back-ends should behave
1398 as if the @code{SCOPE_STMT} were not present at all.
1400 @item START_CATCH_STMT
1402 These statements represent the location to which control is transferred
1403 when an exception is thrown. The @code{START_CATCH_TYPE} is the type of
1404 exception that will be caught by this handler; it is equal (by pointer
1405 equalit) to @code{CATCH_ALL_TYPE} if this handler is for all types.
1409 In a constructor, these nodes are used to mark the point at which a
1410 subobject of @code{this} is fully constructed. If, after this point, an
1411 exception is thrown before a @code{CTOR_STMT} with @code{CTOR_END_P} set
1412 is encountered, the @code{SUBOBJECT_CLEANUP} must be executed. The
1413 cleanups must be executed in the reverse order in which they appear.
1417 Used to represent a @code{switch} statement. The @code{SWITCH_COND} is
1418 the expression on which the switch is occurring. (It may be either a
1419 statement, or an expression.) The @code{SWITCH_BODY} is the body of the
1423 Used to represent a @code{try} block. The body of the try block is
1424 given by @code{TRY_STMTS}. Each of the catch blocks is a @code{HANDLER}
1425 node. The first handler is given by @code{TRY_HANDLERS}. Subsequent
1426 handlers are obtained by following the @code{TREE_CHAIN} link from one
1427 handler to the next. The body of the handler is given by
1428 @code{HANDLER_BODY}.
1430 If @code{CLEANUP_P} holds of the @code{TRY_BLOCK}, then the
1431 @code{TRY_HANDLERS} will not be a @code{HANDLER} node. Instead, it will
1432 be an expression that should be executed if an exception is thrown in
1433 the try block. It must rethrow the exception after executing that code.
1434 And, if an exception is thrown while the expression is executing,
1435 @code{terminate} must be called.
1439 Used to represent a @code{while} loop. The @code{WHILE_COND} is the
1440 termination condition for the loop. This condition may be either a
1441 statement or an expression. If the condition is a statement, it will
1442 always be a @code{DECL_STMT}; see @code{IF_STMT} for more information.
1444 The @code{WHILE_BODY} is the body of the loop.
1448 @c ---------------------------------------------------------------------
1450 @c ---------------------------------------------------------------------
1453 @chapter Expressions
1455 @findex TREE_OPERAND
1457 @findex TREE_INT_CST_HIGH
1458 @findex TREE_INT_CST_LOW
1459 @findex tree_int_cst_lt
1460 @findex tree_int_cst_equal
1463 @findex TREE_STRING_LENGTH
1464 @findex TREE_STRING_POINTER
1466 @findex PTRMEM_CST_CLASS
1467 @findex PTRMEM_CST_MEMBER
1470 @tindex BIT_NOT_EXPR
1471 @tindex TRUTH_NOT_EXPR
1473 @tindex INDIRECT_REF
1474 @tindex FIX_TRUNC_EXPR
1477 @tindex CONVERT_EXPR
1481 @tindex BIT_IOR_EXPR
1482 @tindex BIT_XOR_EXPR
1483 @tindex BIT_AND_EXPR
1484 @tindex TRUTH_ANDIF_EXPR
1485 @tindex TRUTH_ORIF_EXPR
1486 @tindex TRUTH_AND_EXPR
1487 @tindex TRUTH_OR_EXPR
1488 @tindex TRUTH_XOR_EXPR
1492 @tindex TRUNC_DIV_EXPR
1493 @tindex TRUNC_MOD_EXPR
1503 @tindex COMPONENT_REF
1504 @tindex COMPOUND_EXPR
1512 @tindex CLEANUP_POINT_EXPR
1515 The internal representation for expressions is for the most part quite
1516 straightforward. However, there are a few facts that one must bear in
1517 mind. In particular, the expression ``tree'' is actually a directed
1518 acyclic graph. (For example there may be many references to the integer
1519 constant zero throughout the source program; many of these will be
1520 represented by the same expression node.) You should not rely on
1521 certain kinds of node being shared, nor should rely on certain kinds of
1522 nodes being unshared.
1524 The following macros can be used with all expression nodes:
1527 Returns the type of the expression. This value may not be precisely the
1528 same type that would be given the expression in the original C++
1532 In what follows, some nodes that one might expect to always have type
1533 @code{bool} are documented to have either integral or boolean type. At
1534 some point in the future, the C front-end may also make use of this same
1535 intermediate representation, and at this point these nodes will
1536 certainly have integral type. The previous sentence is not meant to
1537 imply that the C++ front-end does not or will not give these nodes
1540 Below, we list the various kinds of expression nodes. Except where
1541 noted otherwise, the operands to an expression are accessed using the
1542 @code{TREE_OPERAND} macro. For example, to access the first operand to
1543 a binary plus expression @code{expr}, use:
1545 TREE_OPERAND (expr, 0)
1548 As this example indicates, the operands are zero-indexed.
1550 The table below begins with constants, moves on to unary expressions,
1551 then proceeds to binary expressions, and concludes with various other
1552 kinds of expressions:
1555 These nodes represent integer constants. Note that the type of these
1556 constants is obtained with @code{TREE_TYPE}; they are not always of type
1557 @code{int}. In particular, @code{char} constants are represented with
1558 @code{INTEGER_CST} nodes. The value of the integer constant @code{e} is
1560 ((TREE_INT_CST_HIGH (e) << HOST_BITS_PER_WIDE_INT)
1561 + TREE_INST_CST_LOW (e))
1564 HOST_BITS_PER_WIDE_INT is at least thirty-two on all platforms. Both
1565 @code{TREE_INT_CST_HIGH} and @code{TREE_INT_CST_LOW} return a
1566 @code{HOST_WIDE_INT}. The value of an @code{INTEGER_CST} is interpreted
1567 as a signed or unsigned quantity depending on the type of the constant.
1568 In general, the expression given above will overflow, so it should not
1569 be used to calculate the value of the constant.
1571 The variable @code{integer_zero_node} is a integer constant with value
1572 zero. Similarly, @code{integer_one_node} is an integer constant with
1573 value one. The @code{size_zero_node} and @code{size_one_node} variables
1574 are analogous, but have type @code{size_t} rather than @code{int}.
1576 The function @code{tree_int_cst_lt} is a predicate which holds if its
1577 first argument is less than its second. Both constants are assumed to
1578 have the same signedness (i.e., either both should be signed or both
1579 should be unsigned.) The full width of the constant is used when doing
1580 the comparison; the usual rules about promotions and conversions are
1581 ignored. Similarly, @code{tree_int_cst_equal} holds if the two
1582 constants are equal. The @code{tree_int_cst_sgn} function returns the
1583 sign of a constant. The value is @code{1}, @code{0}, or @code{-1}
1584 according on whether the constant is greater than, equal to, or less
1585 than zero. Again, the signedness of the constant's type is taken into
1586 account; an unsigned constant is never less than zero, no matter what
1591 FIXME: Talk about how to obtain representations of this constant, do
1592 comparisons, and so forth.
1595 These nodes represent string-constants. The @code{TREE_STRING_LENGTH}
1596 returns the length of the string, as an @code{int}. The
1597 @code{TREE_STRING_POINTER} is a @code{char*} containing the string
1598 itself. The string may not be @code{NUL}-terminated, and it may contain
1599 embedded @code{NUL} characters. Therefore, the
1600 @code{TREE_STRING_LENGTH} includes the trailing @code{NUL} if it is
1603 FIXME: How are wide strings represented?
1606 These nodes are used to represent pointer-to-member constants. The
1607 @code{PTRMEM_CST_CLASS} is the class type (either a @code{RECORD_TYPE}
1608 or @code{UNION_TYPE} within which the pointer points), and the
1609 @code{PTRMEM_CST_MEMBER} is the declaration for the pointed to object.
1610 Note that the @code{DECL_CONTEXT} for the @code{PTRMEM_CST_MEMBER} is in
1611 general different from from the @code{PTRMEM_CST_CLASS}. For example,
1614 struct B @{ int i; @};
1615 struct D : public B @{@};
1619 The @code{PTRMEM_CST_CLASS} for @code{&D::I} is @code{D}, even though
1620 the @code{DECL_CONTEXT} for the @code{PTRMEM_CST_MEMBER} is @code{B},
1621 since @code{B::I} is a member of @code{B}, not @code{D}.
1625 These nodes represent variables, including static data members. For
1626 more information, @pxref{Declarations}.
1629 These nodes represent unary negation of the single operand, for both
1630 integer and floating-point types. The type of negation can be
1631 determined by looking at the type of the expression.
1634 These nodes represent bitwise complement, and will always have integral
1635 type. The only operand is the value to be complemented.
1637 @item TRUTH_NOT_EXPR
1638 These nodes represent logical negation, and will always have integral
1639 (or boolean) type. The operand is the value being negated.
1641 @item PREDECREMENT_EXPR
1642 @itemx PREINCREMENT_EXPR
1643 @itemx POSTDECREMENT_EXPR
1644 @itemx POSTINCREMENT_EXPR
1645 These nodes represent increment and decrement expressions. The value of
1646 the single operand is computed, and the operand incremented or
1647 decremented. In the case of @code{PREDECREMENT_EXPR} and
1648 @code{PREINCREMENT_EXPR}, the value of the expression is the value
1649 resulting after the increment or decrement; in the case of
1650 @code{POSTDECREMENT_EXPR} and @code{POSTINCREMENT_EXPR} is the value
1651 before the increment or decrement occurs. The type of the operand, like
1652 that of the result, will be either integral, boolean, or floating-point.
1655 These nodes are used to represent the address of an object. (These
1656 expression will always have pointer or reference type.) The operand may
1657 be another expression, or it may be a declaration.
1659 As an extension, G++ allows users to take the address of a label. In
1660 this case, the operand of the @code{ADDR_EXPR} will be a
1661 @code{LABEL_DECL}. The type of such an expression is @code{void*}.
1663 If the object addressed is not an lvalue, a temporary is created, and
1664 the address of the temporary is used.
1667 These nodes are used to represent the object pointed to by a pointer.
1668 The operand is the pointer being dereferenced; it will always have
1669 pointer or reference type.
1671 @item FIX_TRUNC_EXPR
1672 These nodes represent conversion of a floating-point value to an
1673 integer. The single operand will have a floating-point type, while the
1674 the complete expression will have an integral (or boolean) type. The
1675 operand is rounded towards zero.
1678 These nodes represent conversion of an integral (or boolean) value to a
1679 floating-point value. The single operand will have integral type, while
1680 the complete expression will have a floating-point type.
1682 FIXME: How is the operand supposed to be rounded? Is this dependent on
1685 @item NON_LVALUE_EXPR
1686 These nodes indicate that their one and only operand is not an lvalue.
1687 A back-end can treat these identically to the single operand.
1690 These nodes are used to represent conversions that do not require any
1691 code-generation. For example, conversion of a @code{char*} to an
1692 @code{int*} does not require any code be generated; such a conversion is
1693 represented by a @code{NOP_EXPR}. The single operand is the expression
1694 to be converted. The conversion from a pointer to a reference is also
1695 represented with a @code{NOP_EXPR}.
1698 These nodes are similar to @code{NOP_EXPR}s, but are used in those
1699 situations where code may need to be generated. For example, if an
1700 @code{int*} is converted to an @code{int} code may need to be generated
1701 on some platforms. These nodes are never used for C++-specific
1702 conversions, like conversions between pointers to different classes in
1703 an inheritance hierarchy. Any adjustments that need to be made in such
1704 cases are always indicated explicitly. Similarly, a user-defined
1705 conversion is never represented by a @code{CONVERT_EXPR}; instead, the
1706 function calls are made explicit.
1709 These nodes represent @code{throw} expressions. The single operand is
1710 an expression for the code that should be executed to throw the
1711 exception. However, there is one implicit action not represented in
1712 that expression; namely the call to @code{__throw}. This function takes
1713 no arguments. If @code{setjmp}/@code{longjmp} exceptions are used, the
1714 function @code{__sjthrow} is called instead. The normal G++ back-end
1715 uses the function @code{emit_throw} to generate this code; you can
1716 examine this function to see what needs to be done.
1720 These nodes represent left and right shifts, respectively. The first
1721 operand is the value to shift; it will always be of integral type. The
1722 second operand is an expression for the number of bits by which to
1723 shift. Right shift should be treated as arithmetic, i.e., the
1724 high-order bits should be zero-filled when the expression has unsigned
1725 type and filled with the sign bit when the expression has signed type.
1730 These nodes represent bitwise inclusive or, bitwise exclusive or, and
1731 bitwise and, respectively. Both operands will always have integral
1734 @item TRUTH_ANDIF_EXPR
1735 @itemx TRUTH_ORIF_EXPR
1736 These nodes represent logical and and logical or, respectively. These
1737 operators are not strict; i.e., the second operand is evaluated only if
1738 the value of the expression is not determined by evaluation of the first
1739 operand. The type of the operands, and the result type, is always of
1740 boolean or integral type.
1742 @item TRUTH_AND_EXPR
1743 @itemx TRUTH_OR_EXPR
1744 @itemx TRUTH_XOR_EXPR
1745 These nodes represent logical and, logical or, and logical exclusive or.
1746 They are strict; both arguments are always evaluated. There are no
1747 corresponding operators in C++, but the front-end will sometimes
1748 generate these expressions anyhow, if it can tell that strictness does
1754 @itemx TRUNC_DIV_EXPR
1755 @itemx TRUNC_MOD_EXPR
1757 These nodes represent various binary arithmetic operations.
1758 Respectively, these operations are addition, subtraction (of the second
1759 operand from the first), multiplication, integer division, integer
1760 remainder, and floating-point division. The operands to the first three
1761 of these may have either integral or floating type, but there will never
1762 be case in which one operand is of floating type and the other is of
1765 The result of a @code{TRUNC_DIV_EXPR} is always rounded towards zero.
1766 The @code{TRUNC_MOD_EXPR} of two operands @code{a} and @code{b} is
1767 always @code{a - a/b} where the division is as if computed by a
1768 @code{TRUNC_DIV_EXPR}.
1771 These nodes represent array accesses. The first operand is the array;
1772 the second is the index. To calculate the address of the memory
1773 accessed, you must scale the index by the size of the type of the array
1776 @item EXACT_DIV_EXPR
1786 These nodes represent the less than, less than or equal to, greater
1787 than, greater than or equal to, equal, and not equal comparison
1788 operators. The first and second operand with either be both of integral
1789 type or both of floating type. The result type of these expressions
1790 will always be of integral or boolean type.
1793 These nodes represent assignment. The left-hand side is the first
1794 operand; the right-hand side is the second operand. The left-hand side
1795 will be a @code{VAR_DECL}, @code{INDIRECT_REF}, @code{COMPONENT_REF}, or
1798 These nodes are used to represent not only assignment with @samp{=} but
1799 also compount assignments (like @samp{+=}), by reduction to @samp{=}
1800 assignment. In other words, the representation for @samp{i += 3} looks
1801 just like that for @samp{i = i + 3}.
1804 These nodes are just like @code{MODIFY_EXPR}, but are used only when a
1805 variable is initialized, rather than assigned to subsequently.
1808 These nodes represent non-static data member accesses. The first
1809 operand is the object (rather than a pointer to it); the second operand
1810 is the @code{FIELD_DECL} for the data member.
1813 These nodes represent C or C++ comma-expressions. The first operand is
1814 an expression whose value is computed and thrown away prior to the
1815 evaluation of the second operand. The value of the entire expression is
1816 the value of the second operand.
1819 These nodes represent C or C++ @code{?:} expressions. The first operand
1820 is of boolean or integral type. If it evaluates to a non-zero value,
1821 the second operand should be evaluated, and returned as the value of the
1822 expression. Otherwise, the third operand is evaluated, and returned as
1823 the value of the expression. As a GNU extension, the middle operand of
1824 the @code{?:} operator may be omitted in the source, like this:
1829 which is equivalent to
1833 assuming that @code{x} is an expression without side-effects. However,
1834 in the case that the first operation causes side effects, the
1835 side-effects occur only once. Consumers of the internal representation
1836 do not need to worry about this oddity; the second operand will be
1837 always be present in the internal representation.
1840 These nodes are used to represent calls to functions, including
1841 non-static member functions. The first operand is a pointer to the
1842 function to call; it is always an expresion whose type is a
1843 @code{POINTER_TYPE}. The second argument is a @code{TREE_LIST}. The
1844 arguments to the call appear left-to-right in the list. The
1845 @code{TREE_VALUE} of each list node contains the expression
1846 corresponding to that argument. (The value of @code{TREE_PURPOSE} for
1847 these nodes is unspecified, and should be ignored.) For non-static
1848 member functions, there will be an operand corresponding to the
1849 @code{this} pointer. There will always be expressions corresponding to
1850 all of the arguments, even if the function is declared with default
1851 arguments and some arguments are not explicitly provided at the call
1855 These nodes are used to represent G++'s statement-expression extension.
1856 The statement-expression extension allows code like this:
1858 int f() @{ return (@{ int j; j = 3; j + 7; @}); @}
1860 In other words, an sequence of statements may occur where a single
1861 expression would normally appear. The @code{STMT_EXPR} node represents
1862 such an expression. The @code{STMT_EXPR_STMT} gives the statement
1863 contained in the expression; this is always a @code{COMPOUND_STMT}. The
1864 value of the expression is the value of the last sub-statement in the
1865 @code{COMPOUND_STMT}. More precisely, the value is the value computed
1866 by the last @code{EXPR_STMT} in the outermost scope of the
1867 @code{COMPOUND_STMT}. For example, in:
1871 the value is @code{3} while in:
1873 (@{ if (x) { 3; } @})
1875 (represented by a nested @code{COMPOUND_STMT}), there is no value. If
1876 the @code{STMT_EXPR} does not yield a value, it's type will be
1880 These nodes represent local blocks. The first operand is a list of
1881 temporary variables, connected via their @code{TREE_CHAIN} field. These
1882 will never require cleanups. The scope of these variables is just the
1883 body of the @code{BIND_EXPR}. The body of the @code{BIND_EXPR} is the
1887 These nodes represent ``infinite'' loops. The @code{LOOP_EXPR_BODY}
1888 represents the body of the loop. It should be executed forever, unless
1889 an @code{EXIT_EXPR} is encountered.
1892 These nodes represent conditional exits from the nearest enclosing
1893 @code{LOOP_EXPR}. The single operand is the condition; if it is
1894 non-zero, then the loop should be exited. An @code{EXIT_EXPR} will only
1895 appear within a @code{LOOP_EXPR}.
1897 @item CLEANUP_POINT_EXPR
1898 These nodes represent full-expressions. The single oeprand is an
1899 expression to evaluate. Any destructor calls engendered by the creation
1900 of temporaries during the evaluation of that expression should be
1901 performed immediately after the expression is evaluated.
1904 These nodes represent the brace-enclosed initializers for a structure or
1905 array. The first operand is reserved for use by the back-end. The
1906 second operand is a @code{TREE_LIST}. If the @code{TREE_TYPE} of the
1907 @code{CONSTRUCTOR} is a @code{RECORD_TYPE} or @code{UNION_TYPE}, then
1908 the @code{TREE_PURPOSE} of each node in the @code{TREE_LIST} will be a
1909 @code{FIELD_DECL} and the @code{TREE_VALUE} of each node will be the
1910 expression used to initialize that field. You should not depend on the
1911 fields appearing in any particular order, nor should you assume that all
1912 fields will be represented. Unrepresented fields may be assigned any
1915 If the @code{TREE_TYPE} of the @code{CONSTRUCTOR} is an
1916 @code{ARRAY_TYPE}, then the @code{TREE_PURPOSE} of each element in the
1917 @code{TREE_LIST} will be an @code{INTEGER_CST}. This constant indicates
1918 which element of the array (indexed from zero) is being assigned to;
1919 again, the @code{TREE_VALUE} is the corresponding initializer. If the
1920 @code{TREE_PURPOSE} is @code{NULL_TREE}, then the initializer is for the
1921 next available array element.
1923 Conceptually, before any initialization is done, the entire area of
1924 storage is initialized to zero.
1928 A @code{SAVE_EXPR} represents an expression (possibly involving
1929 side-effects) that is used more than once. The side-effects should
1930 occur only the first time the expression is evaluated. Subsequent uses
1931 should juse reuse the computed value. The first operand to the
1932 @code{SAVE_EXPR} is the expression to evaluate. The side-effects should
1933 be executed where the @code{SAVE_EXPR} is first encountered in a
1934 depth-first preorder traversal of the expression tree.
1937 A @code{TARGET_EXPR} represents a temporary object. The first operand
1938 is a @code{VAR_DECL} for the temporary variable. The second operand is
1939 the initializer for the temporary. The initializer is evaluated, and
1940 copied (bitwise) into the temporary.
1942 Often, a @code{TARGET_EXPR} occurs on the right-hand side of an
1943 assignment, or as the second operand to a comma-expression which is
1944 itself the right-hand side of an assignment, etc. In this case, we say
1945 that the @code{TARGET_EXPR} is ``normal''; otherwise, we say it is
1946 ``orphaned''. For a normal @code{TARGET_EXPR} the temporary variable
1947 should be treated as an alias for the left-hand side of the assignment,
1948 rather than as a new temporary variable.
1950 The third operand to the @code{TARGET_EXPR}, if present, is a
1951 cleanup-expression (i.e., destructor call) for the temporary. If this
1952 expression is orphaned, then this expression must be executed when the
1953 statement containing this expression is complete. These cleanups must
1954 always be executed in the order opposite to that in which they were
1955 encountered. Note that if a temporary is created on one branch of a
1956 conditional operator (i.e., in the second or third operand to a
1957 @code{COND_EXPR}), the cleanup must be run only if that branch is
1960 See @code{STMT_IS_FULL_EXPR_P} for more information about running these
1963 @item AGGR_INIT_EXPR
1964 An @code{AGGR_INIT_EXPR} represents the initialization as the return
1965 value of a function call, or as the result of a constructor. An
1966 @code{AGGR_INIT_EXPR} will only appear as the second operand of a
1967 @code{TARGET_EXPR}. The first operand to the @code{AGGR_INIT_EXPR} is
1968 the address of a function to call, just as in a @code{CALL_EXPR}. The
1969 second operand are the arguments to pass that function, as a
1970 @code{TREE_LIST}, again in a manner similar to that of a
1971 @code{CALL_EXPR}. The value of the expression is that returned by the
1974 If @code{AGGR_INIT_VIA_CTOR_P} holds of the @code{AGGR_INIT_EXPR}, then
1975 the initialization is via a constructor call. The address of the third
1976 operand of the @code{AGGR_INIT_EXPR}, which is always a @code{VAR_DECL},
1977 is taken, and this value replaces the first argument in the argument
1978 list. In this case, the value of the expression is the @code{VAR_DECL}
1979 given by the third operand to the @code{AGGR_INIT_EXPR}; constructors do
1984 @c ---------------------------------------------------------------------
1986 @c ---------------------------------------------------------------------
1989 @unnumbered Node Index
1993 @c ---------------------------------------------------------------------
1995 @c ---------------------------------------------------------------------
1997 @node Function Index
1998 @unnumbered Function Index
2002 @c ---------------------------------------------------------------------
2004 @c ---------------------------------------------------------------------
2007 @unnumbered Concept Index
2011 @c ---------------------------------------------------------------------
2013 @c ---------------------------------------------------------------------