c-tree.texi

GCC

@findex FOR_COND
@findex FOR_EXPR
@findex FOR_BODY
@tindex GOTO_STMT
@findex GOTO_DESTINATION
@tindex HANDLER
@tindex IF_STMT
@findex IF_COND
@findex THEN_CLAUSE
@findex ELSE_CLAUSE
@tindex LABEL_STMT
@tindex LABEL_STMT_LABEL
@tindex RETURN_INIT
@tindex RETURN_STMT
@findex RETURN_EXPR
@tindex SCOPE_STMT
@findex SCOPE_BEGIN_P
@findex SCOPE_END_P
@findex SCOPE_NULLIFIED_P
@tindex START_CATCH_STMT
@findex START_CATCH_TYPE
@tindex SUBOBJECT
@findex SUBOBJECT_CLEANUP
@tindex SWITCH_STMT
@findex SWITCH_COND
@findex SWITCH_BODY
@tindex TRY_BLOCK
@findex TRY_STMTS
@findex TRY_HANDLERS
@findex HANDLER_PARMS
@findex HANDLER_BODY
@findex USING_STMT
@tindex WHILE_STMT
@findex WHILE_BODY
@findex WHILE_COND

A function that has a definition in the current translation unit will
have a non-NULL @code{DECL_INITIAL}.  However, back-ends should not make
use of the particular value given by @code{DECL_INITIAL}.

The @code{DECL_SAVED_TREE} macro will give the complete body of the
function.  This node will usually be a @code{COMPOUND_STMT} representing
the outermost block of the function, but it may also be a
@code{TRY_BLOCK}, a @code{RETURN_INIT}, or any other valid statement.

@subsubsection Statements

There are tree nodes corresponding to all of the source-level statement
constructs.  These are enumerated here, together with a list of the
various macros that can be used to obtain information about them.  There
are a few macros that can be used with all statements:

@ftable @code
@item STMT_LINENO
This macro returns the line number for the statement.  If the statement
spans multiple lines, this value will be the number of the first line on
which the statement occurs.  Although we mention @code{CASE_LABEL} below
as if it were a statement, they do not allow the use of
@code{STMT_LINENO}.  There is no way to obtain the line number for a
@code{CASE_LABEL}.

Statements do not contain information about
the file from which they came; that information is implicit in the
@code{FUNCTION_DECL} from which the statements originate.

@item STMT_IS_FULL_EXPR_P
In C++, statements normally constitute ``full expressions''; temporaries
created during a statement are destroyed when the statement is complete.
However, G++ sometimes represents expressions by statements; these
statements will not have @code{STMT_IS_FULL_EXPR_P} set.  Temporaries
created during such statements should be destroyed when the innermost
enclosing statement with @code{STMT_IS_FULL_EXPR_P} set is exited.

@end ftable

Here is the list of the various statement nodes, and the macros used to
access them.  This documentation describes the use of these nodes in
non-template functions (including instantiations of template functions).
In template functions, the same nodes are used, but sometimes in
slightly different ways.

Many of the statements have substatements.  For example, a @code{while}
loop will have a body, which is itself a statement.  If the substatement
is @code{NULL_TREE}, it is considered equivalent to a statement
consisting of a single @code{;}, i.e., an expression statement in which
the expression has been omitted.  A substatement may in fact be a list
of statements, connected via their @code{TREE_CHAIN}s.  So, you should
always process the statement tree by looping over substatements, like
this:
@example
void process_stmt (stmt)
     tree stmt;
@{
  while (stmt)
    @{
      switch (TREE_CODE (stmt))
        @{
        case IF_STMT:
          process_stmt (THEN_CLAUSE (stmt));
          /* More processing here.  */
          break;

        @dots{}
        @}

      stmt = TREE_CHAIN (stmt);
    @}
@}
@end example
In other words, while the @code{then} clause of an @code{if} statement
in C++ can be only one statement (although that one statement may be a
compound statement), the intermediate representation will sometimes use
several statements chained together.

@table @code
@item ASM_STMT

Used to represent an inline assembly statement.  For an inline assembly
statement like:
@example
asm ("mov x, y");
@end example
The @code{ASM_STRING} macro will return a @code{STRING_CST} node for
@code{"mov x, y"}.  If the original statement made use of the
extended-assembly syntax, then @code{ASM_OUTPUTS},
@code{ASM_INPUTS}, and @code{ASM_CLOBBERS} will be the outputs, inputs,
and clobbers for the statement, represented as @code{STRING_CST} nodes.
The extended-assembly syntax looks like:
@example
asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
@end example
The first string is the @code{ASM_STRING}, containing the instruction
template.  The next two strings are the output and inputs, respectively;
this statement has no clobbers.  As this example indicates, ``plain''
assembly statements are merely a special case of extended assembly
statements; they have no cv-qualifiers, outputs, inputs, or clobbers.
All of the strings will be @code{NUL}-terminated, and will contain no
embedded @code{NUL}-characters.

If the assembly statement is declared @code{volatile}, or if the
statement was not an extended assembly statement, and is therefore
implicitly volatile, then the predicate @code{ASM_VOLATILE_P} will hold
of the @code{ASM_STMT}.

@item BREAK_STMT

Used to represent a @code{break} statement.  There are no additional
fields.

@item CASE_LABEL

Use to represent a @code{case} label, range of @code{case} labels, or a
@code{default} label.  If @code{CASE_LOW} is NULL_TREE, then this is a a
@code{default} label.  Otherwise, if @code{CASE_HIGH} is NULL_TREE, then
this is an ordinary @code{case} label.  In this case, @code{CASE_LOW} is
an expression giving the value of the label.  Both @code{CASE_LOW} and
@code{CASE_HIGH} are @code{INTEGER_CST} nodes.  These values will have
the same type as the condition expression in the switch statement.

Otherwise, if both @code{CASE_LOW} and @code{CASE_HIGH} are defined, the
statement is a range of case labels.  Such statements originate with the
extension that allows users to write things of the form:
@example
case 2 ... 5:
@end example
The first value will be @code{CASE_LOW}, while the second will be
@code{CASE_HIGH}.

@item CLEANUP_STMT

Used to represent an action that should take place upon exit from the
enclosing scope.  Typically, these actions are calls to destructors for
local objects, but back-ends cannot rely on this fact.  If these nodes
are in fact representing such destructors, @code{CLEANUP_DECL} will be
the @code{VAR_DECL} destroyed.  Otherwise, @code{CLEANUP_DECL} will be
@code{NULL_TREE}.  In any case, the @code{CLEANUP_EXPR} is the
expression to execute.  The cleanups executed on exit from a scope
should be run in the reverse order of the order in which the associated
@code{CLEANUP_STMT}s were encountered.

@item COMPOUND_STMT

Used to represent a brace-enclosed block.  The first substatement is
given by @code{COMPOUND_BODY}.  Subsequent substatements are found by
following the @code{TREE_CHAIN} link from one substatement to the next.

@item CONTINUE_STMT

Used to represent a @code{continue} statement.  There are no additional
fields.

@item CTOR_STMT

Used to mark the beginning (if @code{CTOR_BEGIN_P} holds) or end (if
@code{CTOR_END_P} holds of the main body of a constructor.  See also
@code{SUBOBJECT} for more information on how to use these nodes.

@item DECL_STMT

Used to represent a local declaration.  The @code{DECL_STMT_DECL} macro
can be used to obtain the entity declared.  This declaration may be a
@code{LABEL_DECL}, indicating that the label declared is a local label.
(As an extension, GCC allows the declaration of labels with scope.)  In
C, this declaration may be a @code{FUNCTION_DECL}, indicating the
use of the GCC nested function extension.  For more information,
@pxref{Functions}.

@item DO_STMT

Used to represent a @code{do} loop.  The body of the loop is given by
@code{DO_BODY} while the termination condition for the loop is given by
@code{DO_COND}.  The condition for a @code{do}-statement is always an
expression.

@item EMPTY_CLASS_EXPR

Used to represent a temporary object of a class with no data whose
address is never taken.  (All such objects are interchangeable.)  The
@code{TREE_TYPE} represents the type of the object.

@item EXPR_STMT

Used to represent an expression statement.  Use @code{EXPR_STMT_EXPR} to
obtain the expression.

@item FOR_STMT

Used to represent a @code{for} statement.  The @code{FOR_INIT_STMT} is
the initialization statement for the loop.  The @code{FOR_COND} is the
termination condition.  The @code{FOR_EXPR} is the expression executed
right before the @code{FOR_COND} on each loop iteration; often, this
expression increments a counter.  The body of the loop is given by
@code{FOR_BODY}.  Note that @code{FOR_INIT_STMT} and @code{FOR_BODY}
return statements, while @code{FOR_COND} and @code{FOR_EXPR} return
expressions.

@item GOTO_STMT

Used to represent a @code{goto} statement.  The @code{GOTO_DESTINATION}
will usually be a @code{LABEL_DECL}.  However, if the ``computed
goto'' extension has been used, the @code{GOTO_DESTINATION} will be an
arbitrary expression indicating the destination.  This expression will
always have pointer type.

@item IF_STMT

Used to represent an @code{if} statement.  The @code{IF_COND} is the
expression.

If the condition is a @code{TREE_LIST}, then the @code{TREE_PURPOSE} is
a statement (usually a @code{DECL_STMT}).  Each time the condition is
evaluated, the statement should be executed.  Then, the
@code{TREE_VALUE} should be used as the conditional expression itself.
This representation is used to handle C++ code like this:

@example
if (int i = 7) @dots{}
@end example

where there is a new local variable (or variables) declared within the
condition.

The @code{THEN_CLAUSE} represents the statement given by the @code{then}
condition, while the @code{ELSE_CLAUSE} represents the statement given
by the @code{else} condition.

@item LABEL_STMT

Used to represent a label.  The @code{LABEL_DECL} declared by this
statement can be obtained with the @code{LABEL_STMT_LABEL} macro.  The
@code{IDENTIFIER_NODE} giving the name of the label can be obtained from
the @code{LABEL_DECL} with @code{DECL_NAME}.

@item RETURN_INIT

If the function uses the G++ ``named return value'' extension, meaning
that the function has been defined like:
@example
S f(int) return s @{@dots{}@}
@end example
then there will be a @code{RETURN_INIT}.  There is never a named
returned value for a constructor.  The first argument to the
@code{RETURN_INIT} is the name of the object returned; the second
argument is the initializer for the object.  The object is initialized
when the @code{RETURN_INIT} is encountered.  The object referred to is
the actual object returned; this extension is a manual way of doing the
``return-value optimization.''  Therefore, the object must actually be
constructed in the place where the object will be returned.

@item RETURN_STMT

Used to represent a @code{return} statement.  The @code{RETURN_EXPR} is
the expression returned; it will be @code{NULL_TREE} if the statement
was just
@example
return;
@end example

@item SCOPE_STMT

A scope-statement represents the beginning or end of a scope.  If
@code{SCOPE_BEGIN_P} holds, this statement represents the beginning of a
scope; if @code{SCOPE_END_P} holds this statement represents the end of
a scope.  On exit from a scope, all cleanups from @code{CLEANUP_STMT}s
occurring in the scope must be run, in reverse order to the order in
which they were encountered.  If @code{SCOPE_NULLIFIED_P} or
@code{SCOPE_NO_CLEANUPS_P} holds of the scope, back-ends should behave
as if the @code{SCOPE_STMT} were not present at all.

@item START_CATCH_STMT

These statements represent the location to which control is transferred
when an exception is thrown.  The @code{START_CATCH_TYPE} is the type of
exception that will be caught by this handler; it is equal (by pointer
equality) to @code{CATCH_ALL_TYPE} if this handler is for all types.

@item SUBOBJECT

In a constructor, these nodes are used to mark the point at which a
subobject of @code{this} is fully constructed.  If, after this point, an
exception is thrown before a @code{CTOR_STMT} with @code{CTOR_END_P} set
is encountered, the @code{SUBOBJECT_CLEANUP} must