Commit | Line | Data |
---|---|---|
ec2bcbe7 | 1 | /* Interface to C preprocessor macro tables for GDB. |
42a4f53d | 2 | Copyright (C) 2002-2019 Free Software Foundation, Inc. |
ec2bcbe7 JB |
3 | Contributed by Red Hat, Inc. |
4 | ||
5 | This file is part of GDB. | |
6 | ||
7 | This program is free software; you can redistribute it and/or modify | |
8 | it under the terms of the GNU General Public License as published by | |
a9762ec7 | 9 | the Free Software Foundation; either version 3 of the License, or |
ec2bcbe7 JB |
10 | (at your option) any later version. |
11 | ||
12 | This program is distributed in the hope that it will be useful, | |
13 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
14 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
15 | GNU General Public License for more details. | |
16 | ||
17 | You should have received a copy of the GNU General Public License | |
a9762ec7 | 18 | along with this program. If not, see <http://www.gnu.org/licenses/>. */ |
ec2bcbe7 JB |
19 | |
20 | #ifndef MACROTAB_H | |
21 | #define MACROTAB_H | |
22 | ||
268a13a5 | 23 | #include "gdbsupport/function-view.h" |
14bc53a8 | 24 | |
aa84d1bb AC |
25 | struct obstack; |
26 | struct bcache; | |
43f3e411 | 27 | struct compunit_symtab; |
ec2bcbe7 JB |
28 | |
29 | /* How do we represent a source location? I mean, how should we | |
30 | represent them within GDB; the user wants to use all sorts of | |
31 | ambiguous abbreviations, like "break 32" and "break foo.c:32" | |
32 | ("foo.c" may have been #included into several compilation units), | |
33 | but what do we disambiguate those things to? | |
34 | ||
35 | - Answer 1: "Filename and line number." (Or column number, if | |
36 | you're picky.) That's not quite good enough. For example, the | |
37 | same source file can be #included into several different | |
38 | compilation units --- which #inclusion do you mean? | |
39 | ||
40 | - Answer 2: "Compilation unit, filename, and line number." This is | |
41 | a pretty good answer; GDB's `struct symtab_and_line' basically | |
42 | embodies this representation. But it's still ambiguous; what if a | |
43 | given compilation unit #includes the same file twice --- how can I | |
44 | set a breakpoint on line 12 of the fifth #inclusion of "foo.c"? | |
45 | ||
46 | - Answer 3: "Compilation unit, chain of #inclusions, and line | |
47 | number." This is analogous to the way GCC reports errors in | |
48 | #include files: | |
49 | ||
50 | $ gcc -c base.c | |
51 | In file included from header2.h:8, | |
52 | from header1.h:3, | |
53 | from base.c:5: | |
54 | header3.h:1: parse error before ')' token | |
55 | $ | |
56 | ||
57 | GCC tells you exactly what path of #inclusions led you to the | |
58 | problem. It gives you complete information, in a way that the | |
59 | following would not: | |
60 | ||
61 | $ gcc -c base.c | |
62 | header3.h:1: parse error before ')' token | |
63 | $ | |
64 | ||
65 | Converting all of GDB to use this is a big task, and I'm not really | |
66 | suggesting it should be a priority. But this module's whole | |
67 | purpose is to maintain structures describing the macro expansion | |
68 | process, so I think it's appropriate for us to take a little care | |
69 | to do that in a complete fashion. | |
70 | ||
71 | In this interface, the first line of a file is numbered 1, not 0. | |
72 | This is the same convention the rest of GDB uses. */ | |
73 | ||
74 | ||
75 | /* A table of all the macro definitions for a given compilation unit. */ | |
76 | struct macro_table; | |
77 | ||
d7d9f01e TT |
78 | /* The definition of a single macro. */ |
79 | struct macro_definition; | |
ec2bcbe7 JB |
80 | |
81 | /* A source file that participated in a compilation unit --- either a | |
82 | main file, or an #included file. If a file is #included more than | |
83 | once, the presence of the `included_from' and `included_at_line' | |
84 | members means that we need to make one instance of this structure | |
85 | for each #inclusion. Taken as a group, these structures form a | |
86 | tree mapping the #inclusions that contributed to the compilation | |
87 | unit, with the main source file as its root. | |
88 | ||
f8302a57 JB |
89 | Beware --- not every source file mentioned in a compilation unit's |
90 | symtab structures will appear in the #inclusion tree! As of Oct | |
91 | 2002, GCC does record the effect of #line directives in the source | |
92 | line info, but not in macro info. This means that GDB's symtabs | |
93 | (built from the former, among other things) may mention filenames | |
94 | that the #inclusion tree (built from the latter) doesn't have any | |
95 | record of. See macroscope.c:sal_macro_scope for how to accomodate | |
96 | this. | |
97 | ||
ec2bcbe7 JB |
98 | It's worth noting that libcpp has a simpler way of representing all |
99 | this, which we should consider switching to. It might even be | |
100 | suitable for ordinary non-macro line number info. | |
101 | ||
102 | Suppose you take your main source file, and after each line | |
103 | containing an #include directive you insert the text of the | |
104 | #included file. The result is a big file that pretty much | |
105 | corresponds to the full text the compiler's going to see. There's | |
106 | a one-to-one correspondence between lines in the big file and | |
107 | per-inclusion lines in the source files. (Obviously, #include | |
108 | directives that are #if'd out don't count. And you'll need to | |
109 | append a newline to any file that doesn't end in one, to avoid | |
110 | splicing the last #included line with the next line of the | |
111 | #including file.) | |
112 | ||
113 | Libcpp calls line numbers in this big imaginary file "logical line | |
114 | numbers", and has a data structure called a "line map" that can map | |
115 | logical line numbers onto actual source filenames and line numbers, | |
116 | and also tell you the chain of #inclusions responsible for any | |
117 | particular logical line number. Basically, this means you can pass | |
118 | around a single line number and some kind of "compilation unit" | |
119 | object and you get nice, unambiguous source code locations that | |
120 | distinguish between multiple #inclusions of the same file, etc. | |
121 | ||
122 | Pretty neat, huh? */ | |
123 | ||
124 | struct macro_source_file | |
125 | { | |
126 | ||
127 | /* The macro table for the compilation unit this source location is | |
128 | a part of. */ | |
129 | struct macro_table *table; | |
130 | ||
233d95b5 JK |
131 | /* A source file --- possibly a header file. This filename is relative to |
132 | the compilation directory (table->comp_dir), it exactly matches the | |
133 | symtab->filename content. */ | |
ec2bcbe7 JB |
134 | const char *filename; |
135 | ||
136 | /* The location we were #included from, or zero if we are the | |
137 | compilation unit's main source file. */ | |
138 | struct macro_source_file *included_by; | |
139 | ||
140 | /* If `included_from' is non-zero, the line number in that source | |
141 | file at which we were included. */ | |
142 | int included_at_line; | |
143 | ||
144 | /* Head of a linked list of the source files #included by this file; | |
145 | our children in the #inclusion tree. This list is sorted by its | |
146 | elements' `included_at_line' values, which are unique. (The | |
147 | macro splay tree's ordering function needs this property.) */ | |
148 | struct macro_source_file *includes; | |
149 | ||
150 | /* The next file #included by our `included_from' file; our sibling | |
151 | in the #inclusion tree. */ | |
152 | struct macro_source_file *next_included; | |
153 | }; | |
154 | ||
155 | ||
156 | /* Create a new, empty macro table. Allocate it in OBSTACK, or use | |
157 | xmalloc if OBSTACK is zero. Use BCACHE to store all macro names, | |
158 | arguments, definitions, and anything else that might be the same | |
159 | amongst compilation units in an executable file; if BCACHE is zero, | |
43f3e411 DE |
160 | don't cache these things. CUST is a pointer to the containing |
161 | compilation unit, or NULL if there isn't one. | |
ec2bcbe7 | 162 | |
32623386 JB |
163 | Note that, if either OBSTACK or BCACHE are non-zero, then removing |
164 | information from the table may leak memory. Neither obstacks nor | |
165 | bcaches really allow you to remove information, so although we can | |
166 | update the data structure to record the change, we can't free the | |
167 | old data. At the moment, since we only provide obstacks and | |
168 | bcaches for macro tables for symtabs, this isn't a problem; only | |
169 | odd debugging information makes a definition and then deletes it at | |
170 | the same source location (although 'gcc -DFOO -UFOO -DFOO=2' does | |
171 | do that in GCC 4.1.2.). */ | |
ec2bcbe7 | 172 | struct macro_table *new_macro_table (struct obstack *obstack, |
233d95b5 | 173 | struct bcache *bcache, |
43f3e411 | 174 | struct compunit_symtab *cust); |
ec2bcbe7 JB |
175 | |
176 | ||
177 | /* Free TABLE, and any macro definitions, source file structures, | |
178 | etc. it owns. This will raise an internal error if TABLE was | |
179 | allocated on an obstack, or if it uses a bcache. */ | |
180 | void free_macro_table (struct macro_table *table); | |
181 | ||
182 | ||
183 | /* Set FILENAME as the main source file of TABLE. Return a source | |
184 | file structure describing that file; if we record the #definition | |
185 | of macros, or the #inclusion of other files into FILENAME, we'll | |
186 | use that source file structure to indicate the context. | |
187 | ||
188 | The "main source file" is the one that was given to the compiler; | |
189 | all other source files that contributed to the compilation unit are | |
190 | #included, directly or indirectly, from this one. | |
191 | ||
192 | The macro table makes its own copy of FILENAME; the caller is | |
193 | responsible for freeing FILENAME when it is no longer needed. */ | |
194 | struct macro_source_file *macro_set_main (struct macro_table *table, | |
195 | const char *filename); | |
196 | ||
197 | ||
198 | /* Return the main source file of the macro table TABLE. */ | |
199 | struct macro_source_file *macro_main (struct macro_table *table); | |
200 | ||
d7d9f01e TT |
201 | /* Mark the macro table TABLE so that macros defined in this table can |
202 | be redefined without error. Note that it invalid to call this if | |
203 | TABLE is allocated on an obstack. */ | |
204 | void macro_allow_redefinitions (struct macro_table *table); | |
205 | ||
ec2bcbe7 JB |
206 | |
207 | /* Record a #inclusion. | |
208 | Record in SOURCE's macro table that, at line number LINE in SOURCE, | |
209 | we #included the file INCLUDED. Return a source file structure we | |
210 | can use for symbols #defined or files #included into that. If we've | |
211 | already created a source file structure for this #inclusion, return | |
212 | the same structure we created last time. | |
213 | ||
214 | The first line of the source file has a line number of 1, not 0. | |
215 | ||
216 | The macro table makes its own copy of INCLUDED; the caller is | |
217 | responsible for freeing INCLUDED when it is no longer needed. */ | |
218 | struct macro_source_file *macro_include (struct macro_source_file *source, | |
219 | int line, | |
220 | const char *included); | |
221 | ||
abc9d0dc TT |
222 | /* Define any special macros, like __FILE__ or __LINE__. This should |
223 | be called once, on the main source file. */ | |
224 | ||
225 | void macro_define_special (struct macro_table *table); | |
ec2bcbe7 JB |
226 | |
227 | /* Find any source file structure for a file named NAME, either | |
228 | included into SOURCE, or SOURCE itself. Return zero if we have | |
229 | none. NAME is only the final portion of the filename, not the full | |
230 | path. e.g., `stdio.h', not `/usr/include/stdio.h'. If NAME | |
231 | appears more than once in the inclusion tree, return the | |
232 | least-nested inclusion --- the one closest to the main source file. */ | |
7fa29be9 EB |
233 | struct macro_source_file *macro_lookup_inclusion |
234 | (struct macro_source_file *source, | |
235 | const char *name); | |
ec2bcbe7 JB |
236 | |
237 | ||
238 | /* Record an object-like #definition (i.e., one with no parameter list). | |
239 | Record in SOURCE's macro table that, at line number LINE in SOURCE, | |
240 | we #defined a preprocessor symbol named NAME, whose replacement | |
241 | string is REPLACEMENT. This function makes copies of NAME and | |
242 | REPLACEMENT; the caller is responsible for freeing them. */ | |
243 | void macro_define_object (struct macro_source_file *source, int line, | |
244 | const char *name, const char *replacement); | |
245 | ||
246 | ||
247 | /* Record an function-like #definition (i.e., one with a parameter list). | |
248 | ||
249 | Record in SOURCE's macro table that, at line number LINE in SOURCE, | |
250 | we #defined a preprocessor symbol named NAME, with ARGC arguments | |
251 | whose names are given in ARGV, whose replacement string is REPLACEMENT. If | |
252 | the macro takes a variable number of arguments, then ARGC should be | |
253 | one greater than the number of named arguments, and ARGV[ARGC-1] | |
254 | should be the string "...". This function makes its own copies of | |
255 | NAME, ARGV, and REPLACEMENT; the caller is responsible for freeing | |
256 | them. */ | |
257 | void macro_define_function (struct macro_source_file *source, int line, | |
258 | const char *name, int argc, const char **argv, | |
259 | const char *replacement); | |
260 | ||
261 | ||
262 | /* Record an #undefinition. | |
263 | Record in SOURCE's macro table that, at line number LINE in SOURCE, | |
264 | we removed the definition for the preprocessor symbol named NAME. */ | |
265 | void macro_undef (struct macro_source_file *source, int line, | |
266 | const char *name); | |
267 | ||
ec2bcbe7 JB |
268 | /* Different kinds of macro definitions. */ |
269 | enum macro_kind | |
270 | { | |
271 | macro_object_like, | |
272 | macro_function_like | |
273 | }; | |
274 | ||
abc9d0dc TT |
275 | /* Different kinds of special macros. */ |
276 | ||
277 | enum macro_special_kind | |
278 | { | |
279 | /* Ordinary. */ | |
280 | macro_ordinary, | |
281 | /* The special macro __FILE__. */ | |
282 | macro_FILE, | |
283 | /* The special macro __LINE__. */ | |
284 | macro_LINE | |
285 | }; | |
ec2bcbe7 JB |
286 | |
287 | /* A preprocessor symbol definition. */ | |
288 | struct macro_definition | |
289 | { | |
290 | /* The table this definition lives in. */ | |
291 | struct macro_table *table; | |
292 | ||
293 | /* What kind of macro it is. */ | |
2e668a5d | 294 | ENUM_BITFIELD (macro_kind) kind : 1; |
ec2bcbe7 JB |
295 | |
296 | /* If `kind' is `macro_function_like', the number of arguments it | |
297 | takes, and their names. The names, and the array of pointers to | |
abc9d0dc TT |
298 | them, are in the table's bcache, if it has one. If `kind' is |
299 | `macro_object_like', then this is actually a `macro_special_kind' | |
300 | describing the macro. */ | |
301 | int argc : 30; | |
ec2bcbe7 JB |
302 | const char * const *argv; |
303 | ||
abc9d0dc TT |
304 | /* The replacement string (body) of the macro. For ordinary macros, |
305 | this is in the table's bcache, if it has one. For special macros | |
306 | like __FILE__, this value is only valid until the next use of any | |
307 | special macro definition; that is, it is reset each time any | |
308 | special macro is looked up or iterated over. */ | |
ec2bcbe7 JB |
309 | const char *replacement; |
310 | }; | |
311 | ||
312 | ||
313 | /* Return a pointer to the macro definition for NAME in scope at line | |
314 | number LINE of SOURCE. If LINE is -1, return the definition in | |
315 | effect at the end of the file. The macro table owns the structure; | |
316 | the caller need not free it. Return zero if NAME is not #defined | |
317 | at that point. */ | |
7fa29be9 EB |
318 | struct macro_definition *macro_lookup_definition |
319 | (struct macro_source_file *source, | |
320 | int line, const char *name); | |
ec2bcbe7 JB |
321 | |
322 | ||
323 | /* Return the source location of the definition for NAME in scope at | |
324 | line number LINE of SOURCE. Set *DEFINITION_LINE to the line | |
325 | number of the definition, and return a source file structure for | |
326 | the file. Return zero if NAME has no definition in scope at that | |
327 | point, and leave *DEFINITION_LINE unchanged. */ | |
7fa29be9 EB |
328 | struct macro_source_file *macro_definition_location |
329 | (struct macro_source_file *source, | |
330 | int line, | |
331 | const char *name, | |
332 | int *definition_line); | |
ec2bcbe7 | 333 | |
14bc53a8 PA |
334 | /* Prototype for a callback callable when walking a macro table. NAME |
335 | is the name of the macro, and DEFINITION is the definition. SOURCE | |
336 | is the file at the start of the include path, and LINE is the line | |
337 | number of the SOURCE file where the macro was defined. */ | |
338 | typedef void (macro_callback_fn) (const char *name, | |
339 | const struct macro_definition *definition, | |
340 | struct macro_source_file *source, | |
341 | int line); | |
342 | ||
343 | /* Call the callable FN for each macro in the macro table TABLE. */ | |
344 | void macro_for_each (struct macro_table *table, | |
345 | gdb::function_view<macro_callback_fn> fn); | |
346 | ||
347 | /* Call FN for each macro that is visible in a given scope. The scope | |
348 | is represented by FILE and LINE. */ | |
9a044a89 | 349 | void macro_for_each_in_scope (struct macro_source_file *file, int line, |
14bc53a8 | 350 | gdb::function_view<macro_callback_fn> fn); |
d7d9f01e | 351 | |
233d95b5 JK |
352 | /* Return FILE->filename with possibly prepended compilation directory name. |
353 | This is raw concatenation without the "set substitute-path" and gdb_realpath | |
9409233b | 354 | applications done by symtab_to_fullname. |
233d95b5 JK |
355 | |
356 | THis function ignores the "set filename-display" setting. Its default | |
357 | setting is "relative" which is backward compatible but the former behavior | |
358 | of macro filenames printing was "absolute". */ | |
9409233b | 359 | extern std::string macro_source_fullname (struct macro_source_file *file); |
ec2bcbe7 JB |
360 | |
361 | #endif /* MACROTAB_H */ |