Subversion Repositories openrisc_me

@c Copyright (c) 1999, 2000, 2001, 2002, 2003, 2004, 2005

@c Free Software Foundation, Inc.

@c This is part of the GCC manual.

@c For copying conditions, see the file gcc.texi.

@c ---------------------------------------------------------------------

@c Trees

@c ---------------------------------------------------------------------

@node Trees

@chapter Trees: The intermediate representation used by the C and C++ front ends

@cindex Trees

@cindex C/C++ Internal Representation

This chapter documents the internal representation used by GCC to

represent C and C++ source programs.  When presented with a C or C++

source program, GCC parses the program, performs semantic analysis

(including the generation of error messages), and then produces the

internal representation described here.  This representation contains a

complete representation for the entire translation unit provided as

input to the front end.  This representation is then typically processed

by a code-generator in order to produce machine code, but could also be

used in the creation of source browsers, intelligent editors, automatic

documentation generators, interpreters, and any other programs needing

the ability to process C or C++ code.

This chapter explains the internal representation.  In particular, it

documents the internal representation for C and C++ source

constructs, and the macros, functions, and variables that can be used to

access these constructs.  The C++ representation is largely a superset

of the representation used in the C front end.  There is only one

construct used in C that does not appear in the C++ front end and that

is the GNU ``nested function'' extension.  Many of the macros documented

here do not apply in C because the corresponding language constructs do

not appear in C@.

If you are developing a ``back end'', be it is a code-generator or some

other tool, that uses this representation, you may occasionally find

that you need to ask questions not easily answered by the functions and

macros available here.  If that situation occurs, it is quite likely

that GCC already supports the functionality you desire, but that the

interface is simply not documented here.  In that case, you should ask

the GCC maintainers (via mail to @email{gcc@@gcc.gnu.org}) about

documenting the functionality you require.  Similarly, if you find

yourself writing functions that do not deal directly with your back end,

but instead might be useful to other people using the GCC front end, you

should submit your patches for inclusion in GCC@.

@menu

* Deficiencies::        Topics net yet covered in this document.

* Tree overview::       All about @code{tree}s.

* Types::               Fundamental and aggregate types.

* Scopes::              Namespaces and classes.

* Functions::           Overloading, function bodies, and linkage.

* Declarations::        Type declarations and variables.

* Attributes::          Declaration and type attributes.

* Expression trees::    From @code{typeid} to @code{throw}.

@end menu

@c ---------------------------------------------------------------------

@c Deficiencies

@c ---------------------------------------------------------------------

@node Deficiencies

@section Deficiencies

There are many places in which this document is incomplet and incorrekt.

It is, as of yet, only @emph{preliminary} documentation.

@c ---------------------------------------------------------------------

@c Overview

@c ---------------------------------------------------------------------

@node Tree overview

@section Overview

@cindex tree

@findex TREE_CODE

The central data structure used by the internal representation is the

@code{tree}.  These nodes, while all of the C type @code{tree}, are of

many varieties.  A @code{tree} is a pointer type, but the object to

which it points may be of a variety of types.  From this point forward,

we will refer to trees in ordinary type, rather than in @code{this

font}, except when talking about the actual C type @code{tree}.

You can tell what kind of node a particular tree is by using the

@code{TREE_CODE} macro.  Many, many macros take trees as input and

return trees as output.  However, most macros require a certain kind of

tree node as input.  In other words, there is a type-system for trees,

but it is not reflected in the C type-system.

For safety, it is useful to configure GCC with @option{--enable-checking}.

Although this results in a significant performance penalty (since all

tree types are checked at run-time), and is therefore inappropriate in a

release version, it is extremely helpful during the development process.

Many macros behave as predicates.  Many, although not all, of these

predicates end in @samp{_P}.  Do not rely on the result type of these

macros being of any particular type.  You may, however, rely on the fact

that the type can be compared to @code{0}, so that statements like

@smallexample

if (TEST_P (t) && !TEST_P (y))

  x = 1;

@end smallexample

@noindent

and

@smallexample

int i = (TEST_P (t) != 0);

@end smallexample

@noindent

are legal.  Macros that return @code{int} values now may be changed to

return @code{tree} values, or other pointers in the future.  Even those

that continue to return @code{int} may return multiple nonzero codes

where previously they returned only zero and one.  Therefore, you should

not write code like

@smallexample

if (TEST_P (t) == 1)

@end smallexample

@noindent

as this code is not guaranteed to work correctly in the future.

You should not take the address of values returned by the macros or

functions described here.  In particular, no guarantee is given that the

values are lvalues.

In general, the names of macros are all in uppercase, while the names of

functions are entirely in lowercase.  There are rare exceptions to this

rule.  You should assume that any macro or function whose name is made

up entirely of uppercase letters may evaluate its arguments more than

once.  You may assume that a macro or function whose name is made up

entirely of lowercase letters will evaluate its arguments only once.

The @code{error_mark_node} is a special tree.  Its tree code is

@code{ERROR_MARK}, but since there is only ever one node with that code,

the usual practice is to compare the tree against

@code{error_mark_node}.  (This test is just a test for pointer

equality.)  If an error has occurred during front-end processing the

flag @code{errorcount} will be set.  If the front end has encountered

code it cannot handle, it will issue a message to the user and set

@code{sorrycount}.  When these flags are set, any macro or function

which normally returns a tree of a particular kind may instead return

the @code{error_mark_node}.  Thus, if you intend to do any processing of

erroneous code, you must be prepared to deal with the

@code{error_mark_node}.

Occasionally, a particular tree slot (like an operand to an expression,

or a particular field in a declaration) will be referred to as

``reserved for the back end''.  These slots are used to store RTL when

the tree is converted to RTL for use by the GCC back end.  However, if

that process is not taking place (e.g., if the front end is being hooked

up to an intelligent editor), then those slots may be used by the

back end presently in use.

If you encounter situations that do not match this documentation, such

as tree nodes of types not mentioned here, or macros documented to

return entities of a particular kind that instead return entities of

some different kind, you have found a bug, either in the front end or in

the documentation.  Please report these bugs as you would any other

bug.

@menu

* Macros and Functions::Macros and functions that can be used with all trees.

* Identifiers::         The names of things.

* Containers::          Lists and vectors.

@end menu

@c ---------------------------------------------------------------------

@c Trees

@c ---------------------------------------------------------------------

@node Macros and Functions

@subsection Trees

@cindex tree

This section is not here yet.

@c ---------------------------------------------------------------------

@c Identifiers

@c ---------------------------------------------------------------------

@node Identifiers

@subsection Identifiers

@cindex identifier

@cindex name

@tindex IDENTIFIER_NODE

An @code{IDENTIFIER_NODE} represents a slightly more general concept

that the standard C or C++ concept of identifier.  In particular, an

@code{IDENTIFIER_NODE} may contain a @samp{$}, or other extraordinary

characters.

There are never two distinct @code{IDENTIFIER_NODE}s representing the

same identifier.  Therefore, you may use pointer equality to compare

@code{IDENTIFIER_NODE}s, rather than using a routine like @code{strcmp}.

You can use the following macros to access identifiers:

@ftable @code

@item IDENTIFIER_POINTER

The string represented by the identifier, represented as a

@code{char*}.  This string is always @code{NUL}-terminated, and contains

no embedded @code{NUL} characters.

@item IDENTIFIER_LENGTH

The length of the string returned by @code{IDENTIFIER_POINTER}, not

including the trailing @code{NUL}.  This value of

@code{IDENTIFIER_LENGTH (x)} is always the same as @code{strlen

(IDENTIFIER_POINTER (x))}.

@item IDENTIFIER_OPNAME_P

This predicate holds if the identifier represents the name of an

overloaded operator.  In this case, you should not depend on the

contents of either the @code{IDENTIFIER_POINTER} or the

@code{IDENTIFIER_LENGTH}.

@item IDENTIFIER_TYPENAME_P

This predicate holds if the identifier represents the name of a

user-defined conversion operator.  In this case, the @code{TREE_TYPE} of

the @code{IDENTIFIER_NODE} holds the type to which the conversion

operator converts.

@end ftable

@c ---------------------------------------------------------------------

@c Containers

@c ---------------------------------------------------------------------

@node Containers

@subsection Containers

@cindex container

@cindex list

@cindex vector

@tindex TREE_LIST

@tindex TREE_VEC

@findex TREE_PURPOSE

@findex TREE_VALUE

@findex TREE_VEC_LENGTH

@findex TREE_VEC_ELT

Two common container data structures can be represented directly with

tree nodes.  A @code{TREE_LIST} is a singly linked list containing two

trees per node.  These are the @code{TREE_PURPOSE} and @code{TREE_VALUE}

of each node.  (Often, the @code{TREE_PURPOSE} contains some kind of

tag, or additional information, while the @code{TREE_VALUE} contains the

majority of the payload.  In other cases, the @code{TREE_PURPOSE} is

simply @code{NULL_TREE}, while in still others both the

@code{TREE_PURPOSE} and @code{TREE_VALUE} are of equal stature.)  Given

one @code{TREE_LIST} node, the next node is found by following the

@code{TREE_CHAIN}.  If the @code{TREE_CHAIN} is @code{NULL_TREE}, then

you have reached the end of the list.

A @code{TREE_VEC} is a simple vector.  The @code{TREE_VEC_LENGTH} is an

integer (not a tree) giving the number of nodes in the vector.  The

nodes themselves are accessed using the @code{TREE_VEC_ELT} macro, which

takes two arguments.  The first is the @code{TREE_VEC} in question; the

second is an integer indicating which element in the vector is desired.

The elements are indexed from zero.

@c ---------------------------------------------------------------------

@c Types

@c ---------------------------------------------------------------------

@node Types

@section Types

@cindex type

@cindex pointer

@cindex reference

@cindex fundamental type

@cindex array

@tindex VOID_TYPE

@tindex INTEGER_TYPE

@tindex TYPE_MIN_VALUE

@tindex TYPE_MAX_VALUE

@tindex REAL_TYPE

@tindex COMPLEX_TYPE

@tindex ENUMERAL_TYPE

@tindex BOOLEAN_TYPE

@tindex POINTER_TYPE

@tindex REFERENCE_TYPE

@tindex FUNCTION_TYPE

@tindex METHOD_TYPE

@tindex ARRAY_TYPE

@tindex RECORD_TYPE

@tindex UNION_TYPE

@tindex UNKNOWN_TYPE

@tindex OFFSET_TYPE

@tindex TYPENAME_TYPE

@tindex TYPEOF_TYPE

@findex CP_TYPE_QUALS

@findex TYPE_UNQUALIFIED

@findex TYPE_QUAL_CONST

@findex TYPE_QUAL_VOLATILE

@findex TYPE_QUAL_RESTRICT

@findex TYPE_MAIN_VARIANT

@cindex qualified type

@findex TYPE_SIZE

@findex TYPE_ALIGN

@findex TYPE_PRECISION

@findex TYPE_ARG_TYPES

@findex TYPE_METHOD_BASETYPE

@findex TYPE_PTRMEM_P

@findex TYPE_OFFSET_BASETYPE

@findex TREE_TYPE

@findex TYPE_CONTEXT

@findex TYPE_NAME

@findex TYPENAME_TYPE_FULLNAME

@findex TYPE_FIELDS

@findex TYPE_PTROBV_P

All types have corresponding tree nodes.  However, you should not assume

that there is exactly one tree node corresponding to each type.  There

are often several nodes each of which correspond to the same type.

For the most part, different kinds of types have different tree codes.

(For example, pointer types use a @code{POINTER_TYPE} code while arrays

use an @code{ARRAY_TYPE} code.)  However, pointers to member functions

use the @code{RECORD_TYPE} code.  Therefore, when writing a

@code{switch} statement that depends on the code associated with a

particular type, you should take care to handle pointers to member

functions under the @code{RECORD_TYPE} case label.

In C++, an array type is not qualified; rather the type of the array

elements is qualified.  This situation is reflected in the intermediate

representation.  The macros described here will always examine the

qualification of the underlying element type when applied to an array

type.  (If the element type is itself an array, then the recursion

continues until a non-array type is found, and the qualification of this

type is examined.)  So, for example, @code{CP_TYPE_CONST_P} will hold of

the type @code{const int ()[7]}, denoting an array of seven @code{int}s.

The following functions and macros deal with cv-qualification of types:

@ftable @code

@item CP_TYPE_QUALS

This macro returns the set of type qualifiers applied to this type.

This value is @code{TYPE_UNQUALIFIED} if no qualifiers have been

applied.  The @code{TYPE_QUAL_CONST} bit is set if the type is

@code{const}-qualified.  The @code{TYPE_QUAL_VOLATILE} bit is set if the

type is @code{volatile}-qualified.  The @code{TYPE_QUAL_RESTRICT} bit is

set if the type is @code{restrict}-qualified.

@item CP_TYPE_CONST_P

This macro holds if the type is @code{const}-qualified.

@item CP_TYPE_VOLATILE_P

This macro holds if the type is @code{volatile}-qualified.

@item CP_TYPE_RESTRICT_P

This macro holds if the type is @code{restrict}-qualified.

@item CP_TYPE_CONST_NON_VOLATILE_P

This predicate holds for a type that is @code{const}-qualified, but

@emph{not} @code{volatile}-qualified; other cv-qualifiers are ignored as

well: only the @code{const}-ness is tested.

@item TYPE_MAIN_VARIANT

This macro returns the unqualified version of a type.  It may be applied

to an unqualified type, but it is not always the identity function in

that case.

@end ftable

A few other macros and functions are usable with all types:

@ftable @code

@item TYPE_SIZE

The number of bits required to represent the type, represented as an

@code{INTEGER_CST}.  For an incomplete type, @code{TYPE_SIZE} will be

@code{NULL_TREE}.

@item TYPE_ALIGN

The alignment of the type, in bits, represented as an @code{int}.

@item TYPE_NAME

This macro returns a declaration (in the form of a @code{TYPE_DECL}) for

the type.  (Note this macro does @emph{not} return a

@code{IDENTIFIER_NODE}, as you might expect, given its name!)  You can

look at the @code{DECL_NAME} of the @code{TYPE_DECL} to obtain the

actual name of the type.  The @code{TYPE_NAME} will be @code{NULL_TREE}

for a type that is not a built-in type, the result of a typedef, or a

named class type.

@item CP_INTEGRAL_TYPE

This predicate holds if the type is an integral type.  Notice that in

C++, enumerations are @emph{not} integral types.

@item ARITHMETIC_TYPE_P

This predicate holds if the type is an integral type (in the C++ sense)

or a floating point type.

@item CLASS_TYPE_P

This predicate holds for a class-type.

@item TYPE_BUILT_IN

This predicate holds for a built-in type.

@item TYPE_PTRMEM_P

This predicate holds if the type is a pointer to data member.

@item TYPE_PTR_P

This predicate holds if the type is a pointer type, and the pointee is

not a data member.

@item TYPE_PTRFN_P

This predicate holds for a pointer to function type.

@item TYPE_PTROB_P

This predicate holds for a pointer to object type.  Note however that it

does not hold for the generic pointer to object type @code{void *}.  You

may use @code{TYPE_PTROBV_P} to test for a pointer to object type as

well as @code{void *}.

@item same_type_p

This predicate takes two types as input, and holds if they are the same

type.  For example, if one type is a @code{typedef} for the other, or

both are @code{typedef}s for the same type.  This predicate also holds if

the two trees given as input are simply copies of one another; i.e.,

there is no difference between them at the source level, but, for

whatever reason, a duplicate has been made in the representation.  You

should never use @code{==} (pointer equality) to compare types; always

use @code{same_type_p} instead.

@end ftable

Detailed below are the various kinds of types, and the macros that can

be used to access them.  Although other kinds of types are used

elsewhere in G++, the types described here are the only ones that you

will encounter while examining the intermediate representation.

@table @code

@item VOID_TYPE

Used to represent the @code{void} type.

@item INTEGER_TYPE

Used to represent the various integral types, including @code{char},

@code{short}, @code{int}, @code{long}, and @code{long long}.  This code

is not used for enumeration types, nor for the @code{bool} type.

The @code{TYPE_PRECISION} is the number of bits used in

the representation, represented as an @code{unsigned int}.  (Note that

in the general case this is not the same value as @code{TYPE_SIZE};

suppose that there were a 24-bit integer type, but that alignment

requirements for the ABI required 32-bit alignment.  Then,

@code{TYPE_SIZE} would be an @code{INTEGER_CST} for 32, while

@code{TYPE_PRECISION} would be 24.)  The integer type is unsigned if

@code{TYPE_UNSIGNED} holds; otherwise, it is signed.

The @code{TYPE_MIN_VALUE} is an @code{INTEGER_CST} for the smallest

integer that may be represented by this type.  Similarly, the

@code{TYPE_MAX_VALUE} is an @code{INTEGER_CST} for the largest integer

that may be represented by this type.

@item REAL_TYPE

Used to represent the @code{float}, @code{double}, and @code{long

double} types.  The number of bits in the floating-point representation

is given by @code{TYPE_PRECISION}, as in the @code{INTEGER_TYPE} case.

@item COMPLEX_TYPE

Used to represent GCC built-in @code{__complex__} data types.  The

@code{TREE_TYPE} is the type of the real and imaginary parts.

@item ENUMERAL_TYPE

Used to represent an enumeration type.  The @code{TYPE_PRECISION} gives

(as an @code{int}), the number of bits used to represent the type.  If

there are no negative enumeration constants, @code{TYPE_UNSIGNED} will

hold.  The minimum and maximum enumeration constants may be obtained

with @code{TYPE_MIN_VALUE} and @code{TYPE_MAX_VALUE}, respectively; each

of these macros returns an @code{INTEGER_CST}.

The actual enumeration constants themselves may be obtained by looking

at the @code{TYPE_VALUES}.  This macro will return a @code{TREE_LIST},

containing the constants.  The @code{TREE_PURPOSE} of each node will be

an @code{IDENTIFIER_NODE} giving the name of the constant; the

@code{TREE_VALUE} will be an @code{INTEGER_CST} giving the value

assigned to that constant.  These constants will appear in the order in

which they were declared.  The @code{TREE_TYPE} of each of these

constants will be the type of enumeration type itself.

@item BOOLEAN_TYPE

Used to represent the @code{bool} type.

@item POINTER_TYPE

Used to represent pointer types, and pointer to data member types.  The

@code{TREE_TYPE} gives the type to which this type points.  If the type

is a pointer to data member type, then @code{TYPE_PTRMEM_P} will hold.

For a pointer to data member type of the form @samp{T X::*},

@code{TYPE_PTRMEM_CLASS_TYPE} will be the type @code{X}, while

@code{TYPE_PTRMEM_POINTED_TO_TYPE} will be the type @code{T}.

@item REFERENCE_TYPE

Used to represent reference types.  The @code{TREE_TYPE} gives the type

to which this type refers.

@item FUNCTION_TYPE

Used to represent the type of non-member functions and of static member

functions.  The @code{TREE_TYPE} gives the return type of the function.

The @code{TYPE_ARG_TYPES} are a @code{TREE_LIST} of the argument types.

The @code{TREE_VALUE} of each node in this list is the type of the

corresponding argument; the @code{TREE_PURPOSE} is an expression for the

default argument value, if any.  If the last node in the list is

@code{void_list_node} (a @code{TREE_LIST} node whose @code{TREE_VALUE}

is the @code{void_type_node}), then functions of this type do not take

variable arguments.  Otherwise, they do take a variable number of

arguments.

Note that in C (but not in C++) a function declared like @code{void f()}

is an unprototyped function taking a variable number of arguments; the

@code{TYPE_ARG_TYPES} of such a function will be @code{NULL}.

@item METHOD_TYPE

Used to represent the type of a non-static member function.  Like a

@code{FUNCTION_TYPE}, the return type is given by the @code{TREE_TYPE}.

The type of @code{*this}, i.e., the class of which functions of this

type are a member, is given by the @code{TYPE_METHOD_BASETYPE}.  The

@code{TYPE_ARG_TYPES} is the parameter list, as for a

@code{FUNCTION_TYPE}, and includes the @code{this} argument.

@item ARRAY_TYPE

Used to represent array types.  The @code{TREE_TYPE} gives the type of

the elements in the array.  If the array-bound is present in the type,

the @code{TYPE_DOMAIN} is an @code{INTEGER_TYPE} whose

@code{TYPE_MIN_VALUE} and @code{TYPE_MAX_VALUE} will be the lower and

upper bounds of the array, respectively.  The @code{TYPE_MIN_VALUE} will

always be an @code{INTEGER_CST} for zero, while the

@code{TYPE_MAX_VALUE} will be one less than the number of elements in

the array, i.e., the highest value which may be used to index an element

in the array.

@item RECORD_TYPE

Used to represent @code{struct} and @code{class} types, as well as

pointers to member functions and similar constructs in other languages.

@code{TYPE_FIELDS} contains the items contained in this type, each of

which can be a @code{FIELD_DECL}, @code{VAR_DECL}, @code{CONST_DECL}, or

@code{TYPE_DECL}.  You may not make any assumptions about the ordering

of the fields in the type or whether one or more of them overlap.  If

@code{TYPE_PTRMEMFUNC_P} holds, then this type is a pointer-to-member

type.  In that case, the @code{TYPE_PTRMEMFUNC_FN_TYPE} is a

@code{POINTER_TYPE} pointing to a @code{METHOD_TYPE}.  The

@code{METHOD_TYPE} is the type of a function pointed to by the

pointer-to-member function.  If @code{TYPE_PTRMEMFUNC_P} does not hold,

this type is a class type.  For more information, see @pxref{Classes}.

@item UNION_TYPE

Used to represent @code{union} types.  Similar to @code{RECORD_TYPE}

except that all @code{FIELD_DECL} nodes in @code{TYPE_FIELD} start at

bit position zero.

@item QUAL_UNION_TYPE

Used to represent part of a variant record in Ada.  Similar to

@code{UNION_TYPE} except that each @code{FIELD_DECL} has a

@code{DECL_QUALIFIER} field, which contains a boolean expression that

indicates whether the field is present in the object.  The type will only

have one field, so each field's @code{DECL_QUALIFIER} is only evaluated

if none of the expressions in the previous fields in @code{TYPE_FIELDS}

are nonzero.  Normally these expressions will reference a field in the

outer object using a @code{PLACEHOLDER_EXPR}.

@item UNKNOWN_TYPE

This node is used to represent a type the knowledge of which is

insufficient for a sound processing.

@item OFFSET_TYPE

This node is used to represent a pointer-to-data member.  For a data

member @code{X::m} the @code{TYPE_OFFSET_BASETYPE} is @code{X} and the

@code{TREE_TYPE} is the type of @code{m}.

@item TYPENAME_TYPE

Used to represent a construct of the form @code{typename T::A}.  The

@code{TYPE_CONTEXT} is @code{T}; the @code{TYPE_NAME} is an

@code{IDENTIFIER_NODE} for @code{A}.  If the type is specified via a

template-id, then @code{TYPENAME_TYPE_FULLNAME} yields a

@code{TEMPLATE_ID_EXPR}.  The @code{TREE_TYPE} is non-@code{NULL} if the

node is implicitly generated in support for the implicit typename

extension; in which case the @code{TREE_TYPE} is a type node for the

base-class.

@item TYPEOF_TYPE

Used to represent the @code{__typeof__} extension.  The

@code{TYPE_FIELDS} is the expression the type of which is being

represented.

@end table

There are variables whose values represent some of the basic types.

These include:

@table @code

@item void_type_node

A node for @code{void}.

@item integer_type_node

A node for @code{int}.

@item unsigned_type_node.

A node for @code{unsigned int}.

@item char_type_node.

A node for @code{char}.

@end table

@noindent

It may sometimes be useful to compare one of these variables with a type

in hand, using @code{same_type_p}.

@c ---------------------------------------------------------------------

@c Scopes

@c ---------------------------------------------------------------------

@node Scopes

@section Scopes

@cindex namespace, class, scope

The root of the entire intermediate representation is the variable

@code{global_namespace}.  This is the namespace specified with @code{::}

in C++ source code.  All other namespaces, types, variables, functions,

and so forth can be found starting with this namespace.

Besides namespaces, the other high-level scoping construct in C++ is the

class.  (Throughout this manual the term @dfn{class} is used to mean the

types referred to in the ANSI/ISO C++ Standard as classes; these include

types defined with the @code{class}, @code{struct}, and @code{union}

keywords.)

@menu

* Namespaces::          Member functions, types, etc.

* Classes::             Members, bases, friends, etc.

@end menu

@c ---------------------------------------------------------------------

@c Namespaces

@c ---------------------------------------------------------------------

@node Namespaces

@subsection Namespaces

@cindex namespace

@tindex NAMESPACE_DECL

A namespace is represented by a @code{NAMESPACE_DECL} node.

However, except for the fact that it is distinguished as the root of the

representation, the global namespace is no different from any other

namespace.  Thus, in what follows, we describe namespaces generally,

rather than the global namespace in particular.

The following macros and functions can be used on a @code{NAMESPACE_DECL}:

@ftable @code

@item DECL_NAME

This macro is used to obtain the @code{IDENTIFIER_NODE} corresponding to

the unqualified name of the name of the namespace (@pxref{Identifiers}).

The name of the global namespace is @samp{::}, even though in C++ the

global namespace is unnamed.  However, you should use comparison with

@code{global_namespace}, rather than @code{DECL_NAME} to determine

whether or not a namespace is the global one.  An unnamed namespace

will have a @code{DECL_NAME} equal to @code{anonymous_namespace_name}.

Within a single translation unit, all unnamed namespaces will have the

same name.

@item DECL_CONTEXT

This macro returns the enclosing namespace.  The @code{DECL_CONTEXT} for

the @code{global_namespace} is @code{NULL_TREE}.

@item DECL_NAMESPACE_ALIAS

If this declaration is for a namespace alias, then

@code{DECL_NAMESPACE_ALIAS} is the namespace for which this one is an

alias.

Do not attempt to use @code{cp_namespace_decls} for a namespace which is

an alias.  Instead, follow @code{DECL_NAMESPACE_ALIAS} links until you

reach an ordinary, non-alias, namespace, and call

@code{cp_namespace_decls} there.

@item DECL_NAMESPACE_STD_P

This predicate holds if the namespace is the special @code{::std}

namespace.

@item cp_namespace_decls

This function will return the declarations contained in the namespace,

including types, overloaded functions, other namespaces, and so forth.

If there are no declarations, this function will return

@code{NULL_TREE}.  The declarations are connected through their

@code{TREE_CHAIN} fields.

Although most entries on this list will be declarations,

@code{TREE_LIST} nodes may also appear.  In this case, the

@code{TREE_VALUE} will be an @code{OVERLOAD}.  The value of the

@code{TREE_PURPOSE} is unspecified; back ends should ignore this value.

As with the other kinds of declarations returned by

@code{cp_namespace_decls}, the @code{TREE_CHAIN} will point to the next

declaration in this list.

For more information on the kinds of declarations that can occur on this

list, @xref{Declarations}.  Some declarations will not appear on this

list.  In particular, no @code{FIELD_DECL}, @code{LABEL_DECL}, or

@code{PARM_DECL} nodes will appear here.

This function cannot be used with namespaces that have

@code{DECL_NAMESPACE_ALIAS} set.

@end ftable

@c ---------------------------------------------------------------------

@c Classes

@c ---------------------------------------------------------------------

@node Classes

@subsection Classes

@cindex class

@tindex RECORD_TYPE

@tindex UNION_TYPE

@findex CLASSTYPE_DECLARED_CLASS

@findex TYPE_BINFO

@findex BINFO_TYPE

@findex TYPE_FIELDS

@findex TYPE_VFIELD

@findex TYPE_METHODS

A class type is represented by either a @code{RECORD_TYPE} or a

@code{UNION_TYPE}.  A class declared with the @code{union} tag is

represented by a @code{UNION_TYPE}, while classes declared with either

the @code{struct} or the @code{class} tag are represented by

@code{RECORD_TYPE}s.  You can use the @code{CLASSTYPE_DECLARED_CLASS}

macro to discern whether or not a particular type is a @code{class} as

opposed to a @code{struct}.  This macro will be true only for classes

declared with the @code{class} tag.

Almost all non-function members are available on the @code{TYPE_FIELDS}

list.  Given one member, the next can be found by following the

@code{TREE_CHAIN}.  You should not depend in any way on the order in

which fields appear on this list.  All nodes on this list will be

@samp{DECL} nodes.  A @code{FIELD_DECL} is used to represent a non-static

data member, a @code{VAR_DECL} is used to represent a static data

member, and a @code{TYPE_DECL} is used to represent a type.  Note that

the @code{CONST_DECL} for an enumeration constant will appear on this

list, if the enumeration type was declared in the class.  (Of course,

the @code{TYPE_DECL} for the enumeration type will appear here as well.)

There are no entries for base classes on this list.  In particular,

there is no @code{FIELD_DECL} for the ``base-class portion'' of an

object.

The @code{TYPE_VFIELD} is a compiler-generated field used to point to

virtual function tables.  It may or may not appear on the

@code{TYPE_FIELDS} list.  However, back ends should handle the

@code{TYPE_VFIELD} just like all the entries on the @code{TYPE_FIELDS}

list.

The function members are available on the @code{TYPE_METHODS} list.

Again, subsequent members are found by following the @code{TREE_CHAIN}

field.  If a function is overloaded, each of the overloaded functions

appears; no @code{OVERLOAD} nodes appear on the @code{TYPE_METHODS}

list.  Implicitly declared functions (including default constructors,

copy constructors, assignment operators, and destructors) will appear on

this list as well.

Every class has an associated @dfn{binfo}, which can be obtained with

@code{TYPE_BINFO}.  Binfos are used to represent base-classes.  The

binfo given by @code{TYPE_BINFO} is the degenerate case, whereby every

class is considered to be its own base-class.  The base binfos for a

particular binfo are held in a vector, whose length is obtained with

@code{BINFO_N_BASE_BINFOS}.  The base binfos themselves are obtained

with @code{BINFO_BASE_BINFO} and @code{BINFO_BASE_ITERATE}.  To add a

new binfo, use @code{BINFO_BASE_APPEND}.  The vector of base binfos can

be obtained with @code{BINFO_BASE_BINFOS}, but normally you do not need

to use that.  The class type associated with a binfo is given by

@code{BINFO_TYPE}.  It is not always the case that @code{BINFO_TYPE

(TYPE_BINFO (x))}, because of typedefs and qualified types.  Neither is

it the case that @code{TYPE_BINFO (BINFO_TYPE (y))} is the same binfo as

@code{y}.  The reason is that if @code{y} is a binfo representing a

base-class @code{B} of a derived class @code{D}, then @code{BINFO_TYPE

(y)} will be @code{B}, and @code{TYPE_BINFO (BINFO_TYPE (y))} will be

@code{B} as its own base-class, rather than as a base-class of @code{D}.

The access to a base type can be found with @code{BINFO_BASE_ACCESS}.

This will produce @code{access_public_node}, @code{access_private_node}

or @code{access_protected_node}.  If bases are always public,

@code{BINFO_BASE_ACCESSES} may be @code{NULL}.

@code{BINFO_VIRTUAL_P} is used to specify whether the binfo is inherited

virtually or not.  The other flags, @code{BINFO_MARKED_P} and

@code{BINFO_FLAG_1} to @code{BINFO_FLAG_6} can be used for language

specific use.

The following macros can be used on a tree node representing a class-type.

@ftable @code

@item LOCAL_CLASS_P

This predicate holds if the class is local class @emph{i.e.}@: declared

inside a function body.

@item TYPE_POLYMORPHIC_P

This predicate holds if the class has at least one virtual function

(declared or inherited).

@item TYPE_HAS_DEFAULT_CONSTRUCTOR

This predicate holds whenever its argument represents a class-type with

default constructor.

@item CLASSTYPE_HAS_MUTABLE

@itemx TYPE_HAS_MUTABLE_P

These predicates hold for a class-type having a mutable data member.

@item CLASSTYPE_NON_POD_P

This predicate holds only for class-types that are not PODs.

@item TYPE_HAS_NEW_OPERATOR

This predicate holds for a class-type that defines

@code{operator new}.

@item TYPE_HAS_ARRAY_NEW_OPERATOR

This predicate holds for a class-type for which

@code{operator new[]} is defined.

@item TYPE_OVERLOADS_CALL_EXPR

This predicate holds for class-type for which the function call

@code{operator()} is overloaded.

@item TYPE_OVERLOADS_ARRAY_REF

This predicate holds for a class-type that overloads

@code{operator[]}

@item TYPE_OVERLOADS_ARROW

This predicate holds for a class-type for which @code{operator->} is

overloaded.

@end ftable

@c ---------------------------------------------------------------------

@c Declarations

@c ---------------------------------------------------------------------

@node Declarations

@section Declarations

@cindex declaration

@cindex variable

@cindex type declaration

@tindex LABEL_DECL

@tindex CONST_DECL

@tindex TYPE_DECL

@tindex VAR_DECL

@tindex PARM_DECL

@tindex FIELD_DECL

@tindex NAMESPACE_DECL

@tindex RESULT_DECL

@tindex TEMPLATE_DECL

@tindex THUNK_DECL

@tindex USING_DECL

@findex THUNK_DELTA

@findex DECL_INITIAL

@findex DECL_SIZE

@findex DECL_ALIGN

@findex DECL_EXTERNAL

This section covers the various kinds of declarations that appear in the

internal representation, except for declarations of functions

(represented by @code{FUNCTION_DECL} nodes), which are described in

@ref{Functions}.

@menu

* Working with declarations::  Macros and functions that work on

declarations.

* Internal structure:: How declaration nodes are represented.

@end menu

@node Working with declarations

@subsection Working with declarations

Some macros can be used with any kind of declaration.  These include:

@ftable @code

@item DECL_NAME

This macro returns an @code{IDENTIFIER_NODE} giving the name of the

entity.

@item TREE_TYPE

This macro returns the type of the entity declared.

@item TREE_FILENAME

This macro returns the name of the file in which the entity was

declared, as a @code{char*}.  For an entity declared implicitly by the

compiler (like @code{__builtin_memcpy}), this will be the string

@code{"<internal>"}.

@item TREE_LINENO

This macro returns the line number at which the entity was declared, as

an @code{int}.

@item DECL_ARTIFICIAL

This predicate holds if the declaration was implicitly generated by the

compiler.  For example, this predicate will hold of an implicitly

declared member function, or of the @code{TYPE_DECL} implicitly

generated for a class type.  Recall that in C++ code like:

@smallexample

struct S @{@};

@end smallexample

@noindent

is roughly equivalent to C code like:

@smallexample

struct S @{@};

typedef struct S S;

@end smallexample

The implicitly generated @code{typedef} declaration is represented by a

@code{TYPE_DECL} for which @code{DECL_ARTIFICIAL} holds.

@item DECL_NAMESPACE_SCOPE_P

This predicate holds if the entity was declared at a namespace scope.

@item DECL_CLASS_SCOPE_P

This predicate holds if the entity was declared at a class scope.

@item DECL_FUNCTION_SCOPE_P

This predicate holds if the entity was declared inside a function

body.

@end ftable

The various kinds of declarations include:

@table @code

@item LABEL_DECL

These nodes are used to represent labels in function bodies.  For more

information, see @ref{Functions}.  These nodes only appear in block

scopes.

@item CONST_DECL

These nodes are used to represent enumeration constants.  The value of

the constant is given by @code{DECL_INITIAL} which will be an

@code{INTEGER_CST} with the same type as the @code{TREE_TYPE} of the

@code{CONST_DECL}, i.e., an @code{ENUMERAL_TYPE}.

@item RESULT_DECL

These nodes represent the value returned by a function.  When a value is

assigned to a @code{RESULT_DECL}, that indicates that the value should

be returned, via bitwise copy, by the function.  You can use

@code{DECL_SIZE} and @code{DECL_ALIGN} on a @code{RESULT_DECL}, just as

with a @code{VAR_DECL}.

@item TYPE_DECL

These nodes represent @code{typedef} declarations.  The @code{TREE_TYPE}

is the type declared to have the name given by @code{DECL_NAME}.  In

some cases, there is no associated name.

@item VAR_DECL

These nodes represent variables with namespace or block scope, as well

as static data members.  The @code{DECL_SIZE} and @code{DECL_ALIGN} are

analogous to @code{TYPE_SIZE} and @code{TYPE_ALIGN}.  For a declaration,

you should always use the @code{DECL_SIZE} and @code{DECL_ALIGN} rather

than the @code{TYPE_SIZE} and @code{TYPE_ALIGN} given by the

@code{TREE_TYPE}, since special attributes may have been applied to the

variable to give it a particular size and alignment.  You may use the

predicates @code{DECL_THIS_STATIC} or @code{DECL_THIS_EXTERN} to test