Debian Codegraph @

gcc/doc/generic.texi

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