OSDN Git Service

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