gdb/macrotab.h

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