gdb/macrotab.h

   1 /* Interface to C preprocessor macro tables for GDB.
   2    Copyright (C) 2002-2013 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 /* The definition of a single macro.  */
  76 struct macro_definition;
  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    Beware --- not every source file mentioned in a compilation unit's
  87    symtab structures will appear in the #inclusion tree!  As of Oct
  88    2002, GCC does record the effect of #line directives in the source
  89    line info, but not in macro info.  This means that GDB's symtabs
  90    (built from the former, among other things) may mention filenames
  91    that the #inclusion tree (built from the latter) doesn't have any
  92    record of.  See macroscope.c:sal_macro_scope for how to accomodate
  93    this.
  94
  95    It's worth noting that libcpp has a simpler way of representing all
  96    this, which we should consider switching to.  It might even be
  97    suitable for ordinary non-macro line number info.
  98
  99    Suppose you take your main source file, and after each line
 100    containing an #include directive you insert the text of the
 101    #included file.  The result is a big file that pretty much
 102    corresponds to the full text the compiler's going to see.  There's
 103    a one-to-one correspondence between lines in the big file and
 104    per-inclusion lines in the source files.  (Obviously, #include
 105    directives that are #if'd out don't count.  And you'll need to
 106    append a newline to any file that doesn't end in one, to avoid
 107    splicing the last #included line with the next line of the
 108    #including file.)
 109
 110    Libcpp calls line numbers in this big imaginary file "logical line
 111    numbers", and has a data structure called a "line map" that can map
 112    logical line numbers onto actual source filenames and line numbers,
 113    and also tell you the chain of #inclusions responsible for any
 114    particular logical line number.  Basically, this means you can pass
 115    around a single line number and some kind of "compilation unit"
 116    object and you get nice, unambiguous source code locations that
 117    distinguish between multiple #inclusions of the same file, etc.
 118
 119    Pretty neat, huh?  */
 120
 121 struct macro_source_file
 122 {
 123
 124   /* The macro table for the compilation unit this source location is
 125      a part of.  */
 126   struct macro_table *table;
 127
 128   /* A source file --- possibly a header file.  This filename is relative to
 129      the compilation directory (table->comp_dir), it exactly matches the
 130      symtab->filename content.  */
 131   const char *filename;
 132
 133   /* The location we were #included from, or zero if we are the
 134      compilation unit's main source file.  */
 135   struct macro_source_file *included_by;
 136
 137   /* If `included_from' is non-zero, the line number in that source
 138      file at which we were included.  */
 139   int included_at_line;
 140
 141   /* Head of a linked list of the source files #included by this file;
 142      our children in the #inclusion tree.  This list is sorted by its
 143      elements' `included_at_line' values, which are unique.  (The
 144      macro splay tree's ordering function needs this property.)  */
 145   struct macro_source_file *includes;
 146
 147   /* The next file #included by our `included_from' file; our sibling
 148      in the #inclusion tree.  */
 149   struct macro_source_file *next_included;
 150 };
 151
 152
 153 /* Create a new, empty macro table.  Allocate it in OBSTACK, or use
 154    xmalloc if OBSTACK is zero.  Use BCACHE to store all macro names,
 155    arguments, definitions, and anything else that might be the same
 156    amongst compilation units in an executable file; if BCACHE is zero,
 157    don't cache these things.  COMP_DIR optionally contains the compilation
 158    directory of all files for this macro table.
 159
 160    Note that, if either OBSTACK or BCACHE are non-zero, then removing
 161    information from the table may leak memory.  Neither obstacks nor
 162    bcaches really allow you to remove information, so although we can
 163    update the data structure to record the change, we can't free the
 164    old data.  At the moment, since we only provide obstacks and
 165    bcaches for macro tables for symtabs, this isn't a problem; only
 166    odd debugging information makes a definition and then deletes it at
 167    the same source location (although 'gcc -DFOO -UFOO -DFOO=2' does
 168    do that in GCC 4.1.2.).  */
 169 struct macro_table *new_macro_table (struct obstack *obstack,
 170                                      struct bcache *bcache,
 171                                      const char *comp_dir);
 172
 173
 174 /* Free TABLE, and any macro definitions, source file structures,
 175    etc. it owns.  This will raise an internal error if TABLE was
 176    allocated on an obstack, or if it uses a bcache.  */
 177 void free_macro_table (struct macro_table *table);
 178
 179
 180 /* Set FILENAME as the main source file of TABLE.  Return a source
 181    file structure describing that file; if we record the #definition
 182    of macros, or the #inclusion of other files into FILENAME, we'll
 183    use that source file structure to indicate the context.
 184
 185    The "main source file" is the one that was given to the compiler;
 186    all other source files that contributed to the compilation unit are
 187    #included, directly or indirectly, from this one.
 188
 189    The macro table makes its own copy of FILENAME; the caller is
 190    responsible for freeing FILENAME when it is no longer needed.  */
 191 struct macro_source_file *macro_set_main (struct macro_table *table,
 192                                           const char *filename);
 193
 194
 195 /* Return the main source file of the macro table TABLE.  */
 196 struct macro_source_file *macro_main (struct macro_table *table);
 197
 198 /* Mark the macro table TABLE so that macros defined in this table can
 199    be redefined without error.  Note that it invalid to call this if
 200    TABLE is allocated on an obstack.  */
 201 void macro_allow_redefinitions (struct macro_table *table);
 202
 203
 204 /* Record a #inclusion.
 205    Record in SOURCE's macro table that, at line number LINE in SOURCE,
 206    we #included the file INCLUDED.  Return a source file structure we
 207    can use for symbols #defined or files #included into that.  If we've
 208    already created a source file structure for this #inclusion, return
 209    the same structure we created last time.
 210
 211    The first line of the source file has a line number of 1, not 0.
 212
 213    The macro table makes its own copy of INCLUDED; the caller is
 214    responsible for freeing INCLUDED when it is no longer needed.  */
 215 struct macro_source_file *macro_include (struct macro_source_file *source,
 216                                          int line,
 217                                          const char *included);
 218
 219 /* Define any special macros, like __FILE__ or __LINE__.  This should
 220    be called once, on the main source file.  */
 221
 222 void macro_define_special (struct macro_table *table);
 223
 224 /* Find any source file structure for a file named NAME, either
 225    included into SOURCE, or SOURCE itself.  Return zero if we have
 226    none.  NAME is only the final portion of the filename, not the full
 227    path.  e.g., `stdio.h', not `/usr/include/stdio.h'.  If NAME
 228    appears more than once in the inclusion tree, return the
 229    least-nested inclusion --- the one closest to the main source file.  */
 230 struct macro_source_file *(macro_lookup_inclusion
 231                            (struct macro_source_file *source,
 232                             const char *name));
 233
 234
 235 /* Record an object-like #definition (i.e., one with no parameter list).
 236    Record in SOURCE's macro table that, at line number LINE in SOURCE,
 237    we #defined a preprocessor symbol named NAME, whose replacement
 238    string is REPLACEMENT.  This function makes copies of NAME and
 239    REPLACEMENT; the caller is responsible for freeing them.  */
 240 void macro_define_object (struct macro_source_file *source, int line,
 241                           const char *name, const char *replacement);
 242
 243
 244 /* Record an function-like #definition (i.e., one with a parameter list).
 245
 246    Record in SOURCE's macro table that, at line number LINE in SOURCE,
 247    we #defined a preprocessor symbol named NAME, with ARGC arguments
 248    whose names are given in ARGV, whose replacement string is REPLACEMENT.  If
 249    the macro takes a variable number of arguments, then ARGC should be
 250    one greater than the number of named arguments, and ARGV[ARGC-1]
 251    should be the string "...".  This function makes its own copies of
 252    NAME, ARGV, and REPLACEMENT; the caller is responsible for freeing
 253    them.  */
 254 void macro_define_function (struct macro_source_file *source, int line,
 255                             const char *name, int argc, const char **argv,
 256                             const char *replacement);
 257
 258
 259 /* Record an #undefinition.
 260    Record in SOURCE's macro table that, at line number LINE in SOURCE,
 261    we removed the definition for the preprocessor symbol named NAME.  */
 262 void macro_undef (struct macro_source_file *source, int line,
 263                   const char *name);
 264
 265 /* Different kinds of macro definitions.  */
 266 enum macro_kind
 267 {
 268   macro_object_like,
 269   macro_function_like
 270 };
 271
 272 /* Different kinds of special macros.  */
 273
 274 enum macro_special_kind
 275 {
 276   /* Ordinary.  */
 277   macro_ordinary,
 278   /* The special macro __FILE__.  */
 279   macro_FILE,
 280   /* The special macro __LINE__.  */
 281   macro_LINE
 282 };
 283
 284 /* A preprocessor symbol definition.  */
 285 struct macro_definition
 286 {
 287   /* The table this definition lives in.  */
 288   struct macro_table *table;
 289
 290   /* What kind of macro it is.  */
 291   ENUM_BITFIELD (macro_kind) kind : 1;
 292
 293   /* If `kind' is `macro_function_like', the number of arguments it
 294      takes, and their names.  The names, and the array of pointers to
 295      them, are in the table's bcache, if it has one.  If `kind' is
 296      `macro_object_like', then this is actually a `macro_special_kind'
 297      describing the macro.  */
 298   int argc : 30;
 299   const char * const *argv;
 300
 301   /* The replacement string (body) of the macro.  For ordinary macros,
 302      this is in the table's bcache, if it has one.  For special macros
 303      like __FILE__, this value is only valid until the next use of any
 304      special macro definition; that is, it is reset each time any
 305      special macro is looked up or iterated over.  */
 306   const char *replacement;
 307 };
 308
 309
 310 /* Return a pointer to the macro definition for NAME in scope at line
 311    number LINE of SOURCE.  If LINE is -1, return the definition in
 312    effect at the end of the file.  The macro table owns the structure;
 313    the caller need not free it.  Return zero if NAME is not #defined
 314    at that point.  */
 315 struct macro_definition *(macro_lookup_definition
 316                           (struct macro_source_file *source,
 317                            int line, const char *name));
 318
 319
 320 /* Return the source location of the definition for NAME in scope at
 321    line number LINE of SOURCE.  Set *DEFINITION_LINE to the line
 322    number of the definition, and return a source file structure for
 323    the file.  Return zero if NAME has no definition in scope at that
 324    point, and leave *DEFINITION_LINE unchanged.  */
 325 struct macro_source_file *(macro_definition_location
 326                            (struct macro_source_file *source,
 327                             int line,
 328                             const char *name,
 329                             int *definition_line));
 330
 331 /* Callback function when walking a macro table.  NAME is the name of
 332    the macro, and DEFINITION is the definition.  SOURCE is the file at the
 333    start of the include path, and LINE is the line number of the SOURCE file
 334    where the macro was defined.  USER_DATA is an arbitrary pointer which is
 335    passed by the caller to macro_for_each or macro_for_each_in_scope.  */
 336 typedef void (*macro_callback_fn) (const char *name,
 337                                    const struct macro_definition *definition,
 338                                    struct macro_source_file *source,
 339                                    int line,
 340                                    void *user_data);
 341
 342 /* Call the function FN for each macro in the macro table TABLE.
 343    USER_DATA is passed, untranslated, to FN.  */
 344 void macro_for_each (struct macro_table *table, macro_callback_fn fn,
 345                      void *user_data);
 346
 347 /* Call the function FN for each macro that is visible in a given
 348    scope.  The scope is represented by FILE and LINE.  USER_DATA is
 349    passed, untranslated, to FN.  */
 350 void macro_for_each_in_scope (struct macro_source_file *file, int line,
 351                               macro_callback_fn fn,
 352                               void *user_data);
 353
 354 /* Return FILE->filename with possibly prepended compilation directory name.
 355    This is raw concatenation without the "set substitute-path" and gdb_realpath
 356    applications done by symtab_to_fullname.  Returned string must be freed by
 357    xfree.
 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 char *macro_source_fullname (struct macro_source_file *file);
 363
 364 #endif /* MACROTAB_H */