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