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