gdb/macrotab.h

   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
  23 struct obstack;
  24 struct 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.  */
  73 struct 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
 119 struct 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.  */
 164 struct 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.  */
 171 void 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.  */
 185 struct 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.  */
 190 struct 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.  */
 204 struct 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.  */
 215 struct 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.  */
 225 void 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.  */
 239 void 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.  */
 247 void macro_undef (struct macro_source_file *source, int line,
 248                   const char *name);
 249
 250
 251 /* Different kinds of macro definitions.  */
 252 enum macro_kind
 253 {
 254   macro_object_like,
 255   macro_function_like
 256 };
 257
 258
 259 /* A preprocessor symbol definition.  */
 260 struct 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.  */
 285 struct 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.  */
 295 struct 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 */