Debian Codegraph @

gcc/doc/generic.texi

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