1/* Interface to C preprocessor macro tables for GDB.
2   Copyright (C) 2002, 2007 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
23struct obstack;
24struct bcache;
25
26/* How do we represent a source location?  I mean, how should we
27   represent them within GDB; the user wants to use all sorts of
28   ambiguous abbreviations, like "break 32" and "break foo.c:32"
29   ("foo.c" may have been #included into several compilation units),
30   but what do we disambiguate those things to?
31
32   - Answer 1: "Filename and line number."  (Or column number, if
33   you're picky.)  That's not quite good enough.  For example, the
34   same source file can be #included into several different
35   compilation units --- which #inclusion do you mean?
36
37   - Answer 2: "Compilation unit, filename, and line number."  This is
38   a pretty good answer; GDB's `struct symtab_and_line' basically
39   embodies this representation.  But it's still ambiguous; what if a
40   given compilation unit #includes the same file twice --- how can I
41   set a breakpoint on line 12 of the fifth #inclusion of "foo.c"?
42
43   - Answer 3: "Compilation unit, chain of #inclusions, and line
44   number."  This is analogous to the way GCC reports errors in
45   #include files:
46
47        $ gcc -c base.c
48        In file included from header2.h:8,
49                         from header1.h:3,
50                         from base.c:5:
51        header3.h:1: parse error before ')' token
52        $
53
54   GCC tells you exactly what path of #inclusions led you to the
55   problem.  It gives you complete information, in a way that the
56   following would not:
57
58        $ gcc -c base.c
59        header3.h:1: parse error before ')' token
60        $
61
62   Converting all of GDB to use this is a big task, and I'm not really
63   suggesting it should be a priority.  But this module's whole
64   purpose is to maintain structures describing the macro expansion
65   process, so I think it's appropriate for us to take a little care
66   to do that in a complete fashion.
67
68   In this interface, the first line of a file is numbered 1, not 0.
69   This is the same convention the rest of GDB uses.  */
70
71
72/* A table of all the macro definitions for a given compilation unit.  */
73struct macro_table;
74
75
76/* A source file that participated in a compilation unit --- either a
77   main file, or an #included file.  If a file is #included more than
78   once, the presence of the `included_from' and `included_at_line'
79   members means that we need to make one instance of this structure
80   for each #inclusion.  Taken as a group, these structures form a
81   tree mapping the #inclusions that contributed to the compilation
82   unit, with the main source file as its root.
83
84   Beware --- not every source file mentioned in a compilation unit's
85   symtab structures will appear in the #inclusion tree!  As of Oct
86   2002, GCC does record the effect of #line directives in the source
87   line info, but not in macro info.  This means that GDB's symtabs
88   (built from the former, among other things) may mention filenames
89   that the #inclusion tree (built from the latter) doesn't have any
90   record of.  See macroscope.c:sal_macro_scope for how to accomodate
91   this.
92
93   It's worth noting that libcpp has a simpler way of representing all
94   this, which we should consider switching to.  It might even be
95   suitable for ordinary non-macro line number info.
96
97   Suppose you take your main source file, and after each line
98   containing an #include directive you insert the text of the
99   #included file.  The result is a big file that pretty much
100   corresponds to the full text the compiler's going to see.  There's
101   a one-to-one correspondence between lines in the big file and
102   per-inclusion lines in the source files.  (Obviously, #include
103   directives that are #if'd out don't count.  And you'll need to
104   append a newline to any file that doesn't end in one, to avoid
105   splicing the last #included line with the next line of the
106   #including file.)
107
108   Libcpp calls line numbers in this big imaginary file "logical line
109   numbers", and has a data structure called a "line map" that can map
110   logical line numbers onto actual source filenames and line numbers,
111   and also tell you the chain of #inclusions responsible for any
112   particular logical line number.  Basically, this means you can pass
113   around a single line number and some kind of "compilation unit"
114   object and you get nice, unambiguous source code locations that
115   distinguish between multiple #inclusions of the same file, etc.
116
117   Pretty neat, huh?  */
118
119struct macro_source_file
120{
121
122  /* The macro table for the compilation unit this source location is
123     a part of.  */
124  struct macro_table *table;
125
126  /* A source file --- possibly a header file.  */
127  const char *filename;
128
129  /* The location we were #included from, or zero if we are the
130     compilation unit's main source file.  */
131  struct macro_source_file *included_by;
132
133  /* If `included_from' is non-zero, the line number in that source
134     file at which we were included.  */
135  int included_at_line;
136
137  /* Head of a linked list of the source files #included by this file;
138     our children in the #inclusion tree.  This list is sorted by its
139     elements' `included_at_line' values, which are unique.  (The
140     macro splay tree's ordering function needs this property.)  */
141  struct macro_source_file *includes;
142
143  /* The next file #included by our `included_from' file; our sibling
144     in the #inclusion tree.  */
145  struct macro_source_file *next_included;
146};
147
148
149/* Create a new, empty macro table.  Allocate it in OBSTACK, or use
150   xmalloc if OBSTACK is zero.  Use BCACHE to store all macro names,
151   arguments, definitions, and anything else that might be the same
152   amongst compilation units in an executable file; if BCACHE is zero,
153   don't cache these things.
154
155   Note that, if either OBSTACK or BCACHE are non-zero, then you
156   should only ever add information the macro table --- you should
157   never remove things from it.  You'll get an error if you try.  At
158   the moment, since we only provide obstacks and bcaches for macro
159   tables for symtabs, this restriction makes a nice sanity check.
160   Obstacks and bcaches are pretty much grow-only structures anyway.
161   However, if we find that it's occasionally useful to delete things
162   even from the symtab's tables, and the storage leak isn't a
163   problem, this restriction could be lifted.  */
164struct macro_table *new_macro_table (struct obstack *obstack,
165                                     struct bcache *bcache);
166
167
168/* Free TABLE, and any macro definitions, source file structures,
169   etc. it owns.  This will raise an internal error if TABLE was
170   allocated on an obstack, or if it uses a bcache.  */
171void free_macro_table (struct macro_table *table);
172
173
174/* Set FILENAME as the main source file of TABLE.  Return a source
175   file structure describing that file; if we record the #definition
176   of macros, or the #inclusion of other files into FILENAME, we'll
177   use that source file structure to indicate the context.
178
179   The "main source file" is the one that was given to the compiler;
180   all other source files that contributed to the compilation unit are
181   #included, directly or indirectly, from this one.
182
183   The macro table makes its own copy of FILENAME; the caller is
184   responsible for freeing FILENAME when it is no longer needed.  */
185struct macro_source_file *macro_set_main (struct macro_table *table,
186                                          const char *filename);
187
188
189/* Return the main source file of the macro table TABLE.  */
190struct macro_source_file *macro_main (struct macro_table *table);
191
192
193/* Record a #inclusion.
194   Record in SOURCE's macro table that, at line number LINE in SOURCE,
195   we #included the file INCLUDED.  Return a source file structure we
196   can use for symbols #defined or files #included into that.  If we've
197   already created a source file structure for this #inclusion, return
198   the same structure we created last time.
199
200   The first line of the source file has a line number of 1, not 0.
201
202   The macro table makes its own copy of INCLUDED; the caller is
203   responsible for freeing INCLUDED when it is no longer needed.  */
204struct macro_source_file *macro_include (struct macro_source_file *source,
205                                         int line,
206                                         const char *included);
207
208
209/* Find any source file structure for a file named NAME, either
210   included into SOURCE, or SOURCE itself.  Return zero if we have
211   none.  NAME is only the final portion of the filename, not the full
212   path.  e.g., `stdio.h', not `/usr/include/stdio.h'.  If NAME
213   appears more than once in the inclusion tree, return the
214   least-nested inclusion --- the one closest to the main source file.  */
215struct macro_source_file *(macro_lookup_inclusion
216                           (struct macro_source_file *source,
217                            const char *name));
218
219
220/* Record an object-like #definition (i.e., one with no parameter list).
221   Record in SOURCE's macro table that, at line number LINE in SOURCE,
222   we #defined a preprocessor symbol named NAME, whose replacement
223   string is REPLACEMENT.  This function makes copies of NAME and
224   REPLACEMENT; the caller is responsible for freeing them.  */
225void macro_define_object (struct macro_source_file *source, int line,
226                          const char *name, const char *replacement);
227
228
229/* Record an function-like #definition (i.e., one with a parameter list).
230
231   Record in SOURCE's macro table that, at line number LINE in SOURCE,
232   we #defined a preprocessor symbol named NAME, with ARGC arguments
233   whose names are given in ARGV, whose replacement string is REPLACEMENT.  If
234   the macro takes a variable number of arguments, then ARGC should be
235   one greater than the number of named arguments, and ARGV[ARGC-1]
236   should be the string "...".  This function makes its own copies of
237   NAME, ARGV, and REPLACEMENT; the caller is responsible for freeing
238   them.  */
239void macro_define_function (struct macro_source_file *source, int line,
240                            const char *name, int argc, const char **argv,
241                            const char *replacement);
242
243
244/* Record an #undefinition.
245   Record in SOURCE's macro table that, at line number LINE in SOURCE,
246   we removed the definition for the preprocessor symbol named NAME.  */
247void macro_undef (struct macro_source_file *source, int line,
248                  const char *name);
249
250
251/* Different kinds of macro definitions.  */
252enum macro_kind
253{
254  macro_object_like,
255  macro_function_like
256};
257
258
259/* A preprocessor symbol definition.  */
260struct macro_definition
261{
262  /* The table this definition lives in.  */
263  struct macro_table *table;
264
265  /* What kind of macro it is.  */
266  enum macro_kind kind;
267
268  /* If `kind' is `macro_function_like', the number of arguments it
269     takes, and their names.  The names, and the array of pointers to
270     them, are in the table's bcache, if it has one.  */
271  int argc;
272  const char * const *argv;
273
274  /* The replacement string (body) of the macro.  This is in the
275     table's bcache, if it has one.  */
276  const char *replacement;
277};
278
279
280/* Return a pointer to the macro definition for NAME in scope at line
281   number LINE of SOURCE.  If LINE is -1, return the definition in
282   effect at the end of the file.  The macro table owns the structure;
283   the caller need not free it.  Return zero if NAME is not #defined
284   at that point.  */
285struct macro_definition *(macro_lookup_definition
286                          (struct macro_source_file *source,
287                           int line, const char *name));
288
289
290/* Return the source location of the definition for NAME in scope at
291   line number LINE of SOURCE.  Set *DEFINITION_LINE to the line
292   number of the definition, and return a source file structure for
293   the file.  Return zero if NAME has no definition in scope at that
294   point, and leave *DEFINITION_LINE unchanged.  */
295struct macro_source_file *(macro_definition_location
296                           (struct macro_source_file *source,
297                            int line,
298                            const char *name,
299                            int *definition_line));
300
301
302#endif /* MACROTAB_H */
303