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