..
  Copyright 1988-2022 Free Software Foundation, Inc.
  This is part of the GCC manual.
  For copying conditions, see the copyright.rst file.

.. index:: function

.. _functions:

Functions
*********

.. index:: FUNCTION_DECL

A function is represented by a ``FUNCTION_DECL`` node.  It stores
the basic pieces of the function such as body, parameters, and return
type as well as information on the surrounding context, visibility,
and linkage.

.. toctree::
  :maxdepth: 2


.. -
   Function Basics
   -

.. index:: DECL_NAME, DECL_ASSEMBLER_NAME, TREE_PUBLIC, DECL_ARTIFICIAL, DECL_FUNCTION_SPECIFIC_TARGET, DECL_FUNCTION_SPECIFIC_OPTIMIZATION

.. _function-basics:

Function Basics
^^^^^^^^^^^^^^^

A function has four core parts: the name, the parameters, the result,
and the body.  The following macros and functions access these parts
of a ``FUNCTION_DECL`` as well as other basic features:

.. envvar:: DECL_NAME

  This macro returns the unqualified name of the function, as an
  ``IDENTIFIER_NODE``.  For an instantiation of a function template,
  the ``DECL_NAME`` is the unqualified name of the template, not
  something like ``f<int>``.  The value of ``DECL_NAME`` is
  undefined when used on a constructor, destructor, overloaded operator,
  or type-conversion operator, or any function that is implicitly
  generated by the compiler.  See below for macros that can be used to
  distinguish these cases.

.. envvar:: DECL_ASSEMBLER_NAME

  This macro returns the mangled name of the function, also an
  ``IDENTIFIER_NODE``.  This name does not contain leading underscores
  on systems that prefix all identifiers with underscores.  The mangled
  name is computed in the same way on all platforms; if special processing
  is required to deal with the object file format used on a particular
  platform, it is the responsibility of the back end to perform those
  modifications.  (Of course, the back end should not modify
  ``DECL_ASSEMBLER_NAME`` itself.)

  Using ``DECL_ASSEMBLER_NAME`` will cause additional memory to be
  allocated (for the mangled name of the entity) so it should be used
  only when emitting assembly code.  It should not be used within the
  optimizers to determine whether or not two declarations are the same,
  even though some of the existing optimizers do use it in that way.
  These uses will be removed over time.

.. envvar:: DECL_ARGUMENTS

  This macro returns the ``PARM_DECL`` for the first argument to the
  function.  Subsequent ``PARM_DECL`` nodes can be obtained by
  following the ``TREE_CHAIN`` links.

.. envvar:: DECL_RESULT

  This macro returns the ``RESULT_DECL`` for the function.

.. envvar:: DECL_SAVED_TREE

  This macro returns the complete body of the function.

.. envvar:: TREE_TYPE

  This macro returns the ``FUNCTION_TYPE`` or ``METHOD_TYPE`` for
  the function.

.. envvar:: DECL_INITIAL

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

  It should contain a tree of ``BLOCK`` nodes that mirrors the scopes
  that variables are bound in the function.  Each block contains a list
  of decls declared in a basic block, a pointer to a chain of blocks at
  the next lower scope level, then a pointer to the next block at the
  same level and a backpointer to the parent ``BLOCK`` or
  ``FUNCTION_DECL``.  So given a function as follows:

  .. code-block:: c++

    void foo()
    {
      int a;
      {
        int b;
      }
      int c;
    }

  you would get the following:

  .. code-block:: c++

    tree foo = FUNCTION_DECL;
    tree decl_a = VAR_DECL;
    tree decl_b = VAR_DECL;
    tree decl_c = VAR_DECL;
    tree block_a = BLOCK;
    tree block_b = BLOCK;
    tree block_c = BLOCK;
    BLOCK_VARS(block_a) = decl_a;
    BLOCK_SUBBLOCKS(block_a) = block_b;
    BLOCK_CHAIN(block_a) = block_c;
    BLOCK_SUPERCONTEXT(block_a) = foo;
    BLOCK_VARS(block_b) = decl_b;
    BLOCK_SUPERCONTEXT(block_b) = block_a;
    BLOCK_VARS(block_c) = decl_c;
    BLOCK_SUPERCONTEXT(block_c) = foo;
    DECL_INITIAL(foo) = block_a;

.. -
   Function Properties
   -

.. index:: function properties, statements

.. _function-properties:

Function Properties
^^^^^^^^^^^^^^^^^^^

To determine the scope of a function, you can use the
``DECL_CONTEXT`` macro.  This macro will return the class
(either a ``RECORD_TYPE`` or a ``UNION_TYPE``) or namespace (a
``NAMESPACE_DECL``) of which the function is a member.  For a virtual
function, this macro returns the class in which the function was
actually defined, not the base class in which the virtual declaration
occurred.

In C, the ``DECL_CONTEXT`` for a function maybe another function.
This representation indicates that the GNU nested function extension
is in use.  For details on the semantics of nested functions, see the
GCC Manual.  The nested function can refer to local variables in its
containing function.  Such references are not explicitly marked in the
tree structure; back ends must look at the ``DECL_CONTEXT`` for the
referenced ``VAR_DECL``.  If the ``DECL_CONTEXT`` for the
referenced ``VAR_DECL`` is not the same as the function currently
being processed, and neither ``DECL_EXTERNAL`` nor
``TREE_STATIC`` hold, then the reference is to a local variable in
a containing function, and the back end must take appropriate action.

.. envvar:: DECL_EXTERNAL

  This predicate holds if the function is undefined.

.. envvar:: TREE_PUBLIC

  This predicate holds if the function has external linkage.

.. envvar:: TREE_STATIC

  This predicate holds if the function has been defined.

.. envvar:: TREE_THIS_VOLATILE

  This predicate holds if the function does not return normally.

.. envvar:: TREE_READONLY

  This predicate holds if the function can only read its arguments.

.. envvar:: DECL_PURE_P

  This predicate holds if the function can only read its arguments, but
  may also read global memory.

.. envvar:: DECL_VIRTUAL_P

  This predicate holds if the function is virtual.

.. envvar:: DECL_ARTIFICIAL

  This macro holds if the function was implicitly generated by the
  compiler, rather than explicitly declared.  In addition to implicitly
  generated class member functions, this macro holds for the special
  functions created to implement static initialization and destruction, to
  compute run-time type information, and so forth.

.. envvar:: DECL_FUNCTION_SPECIFIC_TARGET

  This macro returns a tree node that holds the target options that are
  to be used to compile this particular function or ``NULL_TREE`` if
  the function is to be compiled with the target options specified on
  the command line.

.. envvar:: DECL_FUNCTION_SPECIFIC_OPTIMIZATION

  This macro returns a tree node that holds the optimization options
  that are to be used to compile this particular function or
  ``NULL_TREE`` if the function is to be compiled with the
  optimization options specified on the command line.