gdb/macrotab.h - gdb

Data types defined

Macros defined

Source code

  1. /* Interface to C preprocessor macro tables for GDB.
  2.    Copyright (C) 2002-2015 Free Software Foundation, Inc.
  3.    Contributed by Red Hat, Inc.

  5.    This file is part of GDB.

  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.

  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.

  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/>.  */

  20. #ifndef MACROTAB_H
  21. ‌#define MACROTAB_H

  23. struct obstack;
  24. struct bcache;
  25. struct compunit_symtab;

  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?

  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?

  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"?

  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:

  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.         $

  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:

  59.         $ gcc -c base.c
  60.         header3.h:1: parse error before ')' token
  61.         $

  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.

  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.  */


  73. /* A table of all the macro definitions for a given compilation unit.  */
  74. struct macro_table;

  76. /* The definition of a single macro.  */
  77. struct macro_definition;

  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.

  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.

  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.

  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.)

  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.

  120.    Pretty neat, huh?  */

  122. ‌struct macro_source_file
  123. {

  125.   /* The macro table for the compilation unit this source location is
  126.      a part of.  */
  127.   struct macro_table *table;

  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;

  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;

  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;

  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;

  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. };


  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.

  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);


  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);


  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.

  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.

  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);


  196. /* Return the main source file of the macro table TABLE.  */
  197. struct macro_source_file *macro_main (struct macro_table *table);

  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);


  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.

  212.    The first line of the source file has a line number of 1, not 0.

  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);

  220. /* Define any special macros, like __FILE__ or __LINE__.  This should
  221.    be called once, on the main source file.  */

  223. void macro_define_special (struct macro_table *table);

  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));


  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);


  245. /* Record an function-like #definition (i.e., one with a parameter list).

  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);


  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);

  266. /* Different kinds of macro definitions.  */
  267. ‌enum macro_kind
  268. {
  269.   macro_object_like,
  270.   macro_function_like
  271. };

  273. /* Different kinds of special macros.  */

  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. };

  285. /* A preprocessor symbol definition.  */
  286. ‌struct macro_definition
  287. {
  288.   /* The table this definition lives in.  */
  289.   struct macro_table *table;

  291.   /* What kind of macro it is.  */
  292.   ENUM_BITFIELD (macro_kind) kind : 1;

  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;

  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. };


  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));


  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));

  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);

  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);

  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);

  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.

  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);

  365. #endif /* MACROTAB_H */