]>
Commit | Line | Data |
---|---|---|
c63539ff ML |
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 | |
3ed1b4ce | 212 | optimization options specified on the command line. |