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