gdb/macrotab.h

   1 /* Interface to C preprocessor macro tables for GDB.
   2    Copyright 2002 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 2 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, write to the Free Software
  19    Foundation, Inc., 59 Temple Place - Suite 330,
  20    Boston, MA 02111-1307, USA.  */
  21
  22 #ifndef MACROTAB_H
  23 #define MACROTAB_H
  24
  25 struct obstack;
  26 struct bcache;
  27
  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?
  33
  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?
  38
  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"?
  44
  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:
  48
  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         $
  55
  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:
  59
  60         $ gcc -c base.c
  61         header3.h:1: parse error before ')' token
  62         $
  63
  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.
  69
  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.  */
  72
  73
  74 /* A table of all the macro definitions for a given compilation unit.  */
  75 struct macro_table;
  76
  77
  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.
  85
  86    It's worth noting that libcpp has a simpler way of representing all
  87    this, which we should consider switching to.  It might even be
  88    suitable for ordinary non-macro line number info.
  89
  90    Suppose you take your main source file, and after each line
  91    containing an #include directive you insert the text of the
  92    #included file.  The result is a big file that pretty much
  93    corresponds to the full text the compiler's going to see.  There's
  94    a one-to-one correspondence between lines in the big file and
  95    per-inclusion lines in the source files.  (Obviously, #include
  96    directives that are #if'd out don't count.  And you'll need to
  97    append a newline to any file that doesn't end in one, to avoid
  98    splicing the last #included line with the next line of the
  99    #including file.)
 100
 101    Libcpp calls line numbers in this big imaginary file "logical line
 102    numbers", and has a data structure called a "line map" that can map
 103    logical line numbers onto actual source filenames and line numbers,
 104    and also tell you the chain of #inclusions responsible for any
 105    particular logical line number.  Basically, this means you can pass
 106    around a single line number and some kind of "compilation unit"
 107    object and you get nice, unambiguous source code locations that
 108    distinguish between multiple #inclusions of the same file, etc.
 109
 110    Pretty neat, huh?  */
 111
 112 struct macro_source_file
 113 {
 114
 115   /* The macro table for the compilation unit this source location is
 116      a part of.  */
 117   struct macro_table *table;
 118
 119   /* A source file --- possibly a header file.  */
 120   const char *filename;
 121
 122   /* The location we were #included from, or zero if we are the
 123      compilation unit's main source file.  */
 124   struct macro_source_file *included_by;
 125
 126   /* If `included_from' is non-zero, the line number in that source
 127      file at which we were included.  */
 128   int included_at_line;
 129
 130   /* Head of a linked list of the source files #included by this file;
 131      our children in the #inclusion tree.  This list is sorted by its
 132      elements' `included_at_line' values, which are unique.  (The
 133      macro splay tree's ordering function needs this property.)  */
 134   struct macro_source_file *includes;
 135
 136   /* The next file #included by our `included_from' file; our sibling
 137      in the #inclusion tree.  */
 138   struct macro_source_file *next_included;
 139 };
 140
 141
 142 /* Create a new, empty macro table.  Allocate it in OBSTACK, or use
 143    xmalloc if OBSTACK is zero.  Use BCACHE to store all macro names,
 144    arguments, definitions, and anything else that might be the same
 145    amongst compilation units in an executable file; if BCACHE is zero,
 146    don't cache these things.
 147
 148    Note that, if either OBSTACK or BCACHE are non-zero, then you
 149    should only ever add information the macro table --- you should
 150    never remove things from it.  You'll get an error if you try.  At
 151    the moment, since we only provide obstacks and bcaches for macro
 152    tables for symtabs, this restriction makes a nice sanity check.
 153    Obstacks and bcaches are pretty much grow-only structures anyway.
 154    However, if we find that it's occasionally useful to delete things
 155    even from the symtab's tables, and the storage leak isn't a
 156    problem, this restriction could be lifted.  */
 157 struct macro_table *new_macro_table (struct obstack *obstack,
 158                                      struct bcache *bcache);
 159
 160
 161 /* Free TABLE, and any macro definitions, source file structures,
 162    etc. it owns.  This will raise an internal error if TABLE was
 163    allocated on an obstack, or if it uses a bcache.  */
 164 void free_macro_table (struct macro_table *table);
 165
 166
 167 /* Set FILENAME as the main source file of TABLE.  Return a source
 168    file structure describing that file; if we record the #definition
 169    of macros, or the #inclusion of other files into FILENAME, we'll
 170    use that source file structure to indicate the context.
 171
 172    The "main source file" is the one that was given to the compiler;
 173    all other source files that contributed to the compilation unit are
 174    #included, directly or indirectly, from this one.
 175
 176    The macro table makes its own copy of FILENAME; the caller is
 177    responsible for freeing FILENAME when it is no longer needed.  */
 178 struct macro_source_file *macro_set_main (struct macro_table *table,
 179                                           const char *filename);
 180
 181
 182 /* Return the main source file of the macro table TABLE.  */
 183 struct macro_source_file *macro_main (struct macro_table *table);
 184
 185
 186 /* Record a #inclusion.
 187    Record in SOURCE's macro table that, at line number LINE in SOURCE,
 188    we #included the file INCLUDED.  Return a source file structure we
 189    can use for symbols #defined or files #included into that.  If we've
 190    already created a source file structure for this #inclusion, return
 191    the same structure we created last time.
 192
 193    The first line of the source file has a line number of 1, not 0.
 194
 195    The macro table makes its own copy of INCLUDED; the caller is
 196    responsible for freeing INCLUDED when it is no longer needed.  */
 197 struct macro_source_file *macro_include (struct macro_source_file *source,
 198                                          int line,
 199                                          const char *included);
 200
 201
 202 /* Find any source file structure for a file named NAME, either
 203    included into SOURCE, or SOURCE itself.  Return zero if we have
 204    none.  NAME is only the final portion of the filename, not the full
 205    path.  e.g., `stdio.h', not `/usr/include/stdio.h'.  If NAME
 206    appears more than once in the inclusion tree, return the
 207    least-nested inclusion --- the one closest to the main source file.  */
 208 struct macro_source_file *(macro_lookup_inclusion
 209                            (struct macro_source_file *source,
 210                             const char *name));
 211
 212
 213 /* Record an object-like #definition (i.e., one with no parameter list).
 214    Record in SOURCE's macro table that, at line number LINE in SOURCE,
 215    we #defined a preprocessor symbol named NAME, whose replacement
 216    string is REPLACEMENT.  This function makes copies of NAME and
 217    REPLACEMENT; the caller is responsible for freeing them.  */
 218 void macro_define_object (struct macro_source_file *source, int line,
 219                           const char *name, const char *replacement);
 220
 221
 222 /* Record an function-like #definition (i.e., one with a parameter list).
 223
 224    Record in SOURCE's macro table that, at line number LINE in SOURCE,
 225    we #defined a preprocessor symbol named NAME, with ARGC arguments
 226    whose names are given in ARGV, whose replacement string is REPLACEMENT.  If
 227    the macro takes a variable number of arguments, then ARGC should be
 228    one greater than the number of named arguments, and ARGV[ARGC-1]
 229    should be the string "...".  This function makes its own copies of
 230    NAME, ARGV, and REPLACEMENT; the caller is responsible for freeing
 231    them.  */
 232 void macro_define_function (struct macro_source_file *source, int line,
 233                             const char *name, int argc, const char **argv,
 234                             const char *replacement);
 235
 236
 237 /* Record an #undefinition.
 238    Record in SOURCE's macro table that, at line number LINE in SOURCE,
 239    we removed the definition for the preprocessor symbol named NAME.  */
 240 void macro_undef (struct macro_source_file *source, int line,
 241                   const char *name);
 242
 243
 244 /* Different kinds of macro definitions.  */
 245 enum macro_kind
 246 {
 247   macro_object_like,
 248   macro_function_like
 249 };
 250
 251
 252 /* A preprocessor symbol definition.  */
 253 struct macro_definition
 254 {
 255   /* The table this definition lives in.  */
 256   struct macro_table *table;
 257
 258   /* What kind of macro it is.  */
 259   enum macro_kind kind;
 260
 261   /* If `kind' is `macro_function_like', the number of arguments it
 262      takes, and their names.  The names, and the array of pointers to
 263      them, are in the table's bcache, if it has one.  */
 264   int argc;
 265   const char * const *argv;
 266
 267   /* The replacement string (body) of the macro.  This is in the
 268      table's bcache, if it has one.  */
 269   const char *replacement;
 270 };
 271
 272
 273 /* Return a pointer to the macro definition for NAME in scope at line
 274    number LINE of SOURCE.  If LINE is -1, return the definition in
 275    effect at the end of the file.  The macro table owns the structure;
 276    the caller need not free it.  Return zero if NAME is not #defined
 277    at that point.  */
 278 struct macro_definition *(macro_lookup_definition
 279                           (struct macro_source_file *source,
 280                            int line, const char *name));
 281
 282
 283 /* Return the source location of the definition for NAME in scope at
 284    line number LINE of SOURCE.  Set *DEFINITION_LINE to the line
 285    number of the definition, and return a source file structure for
 286    the file.  Return zero if NAME has no definition in scope at that
 287    point, and leave *DEFINITION_LINE unchanged.  */
 288 struct macro_source_file *(macro_definition_location
 289                            (struct macro_source_file *source,
 290                             int line,
 291                             const char *name,
 292                             int *definition_line));
 293
 294
 295 #endif /* MACROTAB_H */