gcc/doc/gccint/generic/functions.rst

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. index:: function
   7
   8 .. _functions:
   9
  10 Functions
  11 *********
  12
  13 .. index:: FUNCTION_DECL
  14
  15 A function is represented by a ``FUNCTION_DECL`` node.  It stores
  16 the basic pieces of the function such as body, parameters, and return
  17 type as well as information on the surrounding context, visibility,
  18 and linkage.
  19
  20 .. toctree::
  21   :maxdepth: 2
  22
  23
  24 .. -
  25    Function Basics
  26    -
  27
  28 .. index:: DECL_NAME, DECL_ASSEMBLER_NAME, TREE_PUBLIC, DECL_ARTIFICIAL, DECL_FUNCTION_SPECIFIC_TARGET, DECL_FUNCTION_SPECIFIC_OPTIMIZATION
  29
  30 .. _function-basics:
  31
  32 Function Basics
  33 ^^^^^^^^^^^^^^^
  34
  35 A function has four core parts: the name, the parameters, the result,
  36 and the body.  The following macros and functions access these parts
  37 of a ``FUNCTION_DECL`` as well as other basic features:
  38
  39 .. envvar:: DECL_NAME
  40
  41   This macro returns the unqualified name of the function, as an
  42   ``IDENTIFIER_NODE``.  For an instantiation of a function template,
  43   the ``DECL_NAME`` is the unqualified name of the template, not
  44   something like ``f<int>``.  The value of ``DECL_NAME`` is
  45   undefined when used on a constructor, destructor, overloaded operator,
  46   or type-conversion operator, or any function that is implicitly
  47   generated by the compiler.  See below for macros that can be used to
  48   distinguish these cases.
  49
  50 .. envvar:: DECL_ASSEMBLER_NAME
  51
  52   This macro returns the mangled name of the function, also an
  53   ``IDENTIFIER_NODE``.  This name does not contain leading underscores
  54   on systems that prefix all identifiers with underscores.  The mangled
  55   name is computed in the same way on all platforms; if special processing
  56   is required to deal with the object file format used on a particular
  57   platform, it is the responsibility of the back end to perform those
  58   modifications.  (Of course, the back end should not modify
  59   ``DECL_ASSEMBLER_NAME`` itself.)
  60
  61   Using ``DECL_ASSEMBLER_NAME`` will cause additional memory to be
  62   allocated (for the mangled name of the entity) so it should be used
  63   only when emitting assembly code.  It should not be used within the
  64   optimizers to determine whether or not two declarations are the same,
  65   even though some of the existing optimizers do use it in that way.
  66   These uses will be removed over time.
  67
  68 .. envvar:: DECL_ARGUMENTS
  69
  70   This macro returns the ``PARM_DECL`` for the first argument to the
  71   function.  Subsequent ``PARM_DECL`` nodes can be obtained by
  72   following the ``TREE_CHAIN`` links.
  73
  74 .. envvar:: DECL_RESULT
  75
  76   This macro returns the ``RESULT_DECL`` for the function.
  77
  78 .. envvar:: DECL_SAVED_TREE
  79
  80   This macro returns the complete body of the function.
  81
  82 .. envvar:: TREE_TYPE
  83
  84   This macro returns the ``FUNCTION_TYPE`` or ``METHOD_TYPE`` for
  85   the function.
  86
  87 .. envvar:: DECL_INITIAL
  88
  89   A function that has a definition in the current translation unit will
  90   have a non- ``NULL`` ``DECL_INITIAL``.  However, back ends should not make
  91   use of the particular value given by ``DECL_INITIAL``.
  92
  93   It should contain a tree of ``BLOCK`` nodes that mirrors the scopes
  94   that variables are bound in the function.  Each block contains a list
  95   of decls declared in a basic block, a pointer to a chain of blocks at
  96   the next lower scope level, then a pointer to the next block at the
  97   same level and a backpointer to the parent ``BLOCK`` or
  98   ``FUNCTION_DECL``.  So given a function as follows:
  99
 100   .. code-block:: c++
 101
 102     void foo()
 103     {
 104       int a;
 105       {
 106         int b;
 107       }
 108       int c;
 109     }
 110
 111   you would get the following:
 112
 113   .. code-block:: c++
 114
 115     tree foo = FUNCTION_DECL;
 116     tree decl_a = VAR_DECL;
 117     tree decl_b = VAR_DECL;
 118     tree decl_c = VAR_DECL;
 119     tree block_a = BLOCK;
 120     tree block_b = BLOCK;
 121     tree block_c = BLOCK;
 122     BLOCK_VARS(block_a) = decl_a;
 123     BLOCK_SUBBLOCKS(block_a) = block_b;
 124     BLOCK_CHAIN(block_a) = block_c;
 125     BLOCK_SUPERCONTEXT(block_a) = foo;
 126     BLOCK_VARS(block_b) = decl_b;
 127     BLOCK_SUPERCONTEXT(block_b) = block_a;
 128     BLOCK_VARS(block_c) = decl_c;
 129     BLOCK_SUPERCONTEXT(block_c) = foo;
 130     DECL_INITIAL(foo) = block_a;
 131
 132 .. -
 133    Function Properties
 134    -
 135
 136 .. index:: function properties, statements
 137
 138 .. _function-properties:
 139
 140 Function Properties
 141 ^^^^^^^^^^^^^^^^^^^
 142
 143 To determine the scope of a function, you can use the
 144 ``DECL_CONTEXT`` macro.  This macro will return the class
 145 (either a ``RECORD_TYPE`` or a ``UNION_TYPE``) or namespace (a
 146 ``NAMESPACE_DECL``) of which the function is a member.  For a virtual
 147 function, this macro returns the class in which the function was
 148 actually defined, not the base class in which the virtual declaration
 149 occurred.
 150
 151 In C, the ``DECL_CONTEXT`` for a function maybe another function.
 152 This representation indicates that the GNU nested function extension
 153 is in use.  For details on the semantics of nested functions, see the
 154 GCC Manual.  The nested function can refer to local variables in its
 155 containing function.  Such references are not explicitly marked in the
 156 tree structure; back ends must look at the ``DECL_CONTEXT`` for the
 157 referenced ``VAR_DECL``.  If the ``DECL_CONTEXT`` for the
 158 referenced ``VAR_DECL`` is not the same as the function currently
 159 being processed, and neither ``DECL_EXTERNAL`` nor
 160 ``TREE_STATIC`` hold, then the reference is to a local variable in
 161 a containing function, and the back end must take appropriate action.
 162
 163 .. envvar:: DECL_EXTERNAL
 164
 165   This predicate holds if the function is undefined.
 166
 167 .. envvar:: TREE_PUBLIC
 168
 169   This predicate holds if the function has external linkage.
 170
 171 .. envvar:: TREE_STATIC
 172
 173   This predicate holds if the function has been defined.
 174
 175 .. envvar:: TREE_THIS_VOLATILE
 176
 177   This predicate holds if the function does not return normally.
 178
 179 .. envvar:: TREE_READONLY
 180
 181   This predicate holds if the function can only read its arguments.
 182
 183 .. envvar:: DECL_PURE_P
 184
 185   This predicate holds if the function can only read its arguments, but
 186   may also read global memory.
 187
 188 .. envvar:: DECL_VIRTUAL_P
 189
 190   This predicate holds if the function is virtual.
 191
 192 .. envvar:: DECL_ARTIFICIAL
 193
 194   This macro holds if the function was implicitly generated by the
 195   compiler, rather than explicitly declared.  In addition to implicitly
 196   generated class member functions, this macro holds for the special
 197   functions created to implement static initialization and destruction, to
 198   compute run-time type information, and so forth.
 199
 200 .. envvar:: DECL_FUNCTION_SPECIFIC_TARGET
 201
 202   This macro returns a tree node that holds the target options that are
 203   to be used to compile this particular function or ``NULL_TREE`` if
 204   the function is to be compiled with the target options specified on
 205   the command line.
 206
 207 .. envvar:: DECL_FUNCTION_SPECIFIC_OPTIMIZATION
 208
 209   This macro returns a tree node that holds the optimization options
 210   that are to be used to compile this particular function or
 211   ``NULL_TREE`` if the function is to be compiled with the
 212   optimization options specified on the command line.