gdb/macrotab.h

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