OSDN Git Service

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