gdb/macrotab.h

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