merge from gcc

[deliverable/binutils-gdb.git] / gdb / macrotab.h

diff --git a/gdb/macrotab.h b/gdb/macrotab.h
index cbc6d1b53d7910886d57e206efd0dff29ff173fe..eb546bccf7faa885be28bab7efc983a0d35abc17 100644 (file)
--- a/gdb/macrotab.h
+++ b/gdb/macrotab.h
@@ -1,12 +1,12 @@
 /* Interface to C preprocessor macro tables for GDB.
-   Copyright 2002 Free Software Foundation, Inc.
+   Copyright (C) 2002, 2007, 2008 Free Software Foundation, Inc.
    Contributed by Red Hat, Inc.
 
    This file is part of GDB.
 
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
-   the Free Software Foundation; either version 2 of the License, or
+   the Free Software Foundation; either version 3 of the License, or
    (at your option) any later version.
 
    This program is distributed in the hope that it will be useful,
@@ -15,15 +15,13 @@
    GNU General Public License for more details.
 
    You should have received a copy of the GNU General Public License
-   along with this program; if not, write to the Free Software
-   Foundation, Inc., 59 Temple Place - Suite 330,
-   Boston, MA 02111-1307, USA.  */
+   along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
 
 #ifndef MACROTAB_H
 #define MACROTAB_H
 
-#include "obstack.h"
-#include "bcache.h"
+struct obstack;
+struct bcache;
 
 /* How do we represent a source location?  I mean, how should we
    represent them within GDB; the user wants to use all sorts of
@@ -83,6 +81,15 @@ struct macro_table;
    tree mapping the #inclusions that contributed to the compilation
    unit, with the main source file as its root.
 
+   Beware --- not every source file mentioned in a compilation unit's
+   symtab structures will appear in the #inclusion tree!  As of Oct
+   2002, GCC does record the effect of #line directives in the source
+   line info, but not in macro info.  This means that GDB's symtabs
+   (built from the former, among other things) may mention filenames
+   that the #inclusion tree (built from the latter) doesn't have any
+   record of.  See macroscope.c:sal_macro_scope for how to accomodate
+   this.
+
    It's worth noting that libcpp has a simpler way of representing all
    this, which we should consider switching to.  It might even be
    suitable for ordinary non-macro line number info.
@@ -145,15 +152,15 @@ struct macro_source_file
    amongst compilation units in an executable file; if BCACHE is zero,
    don't cache these things.
 
-   Note that, if either OBSTACK or BCACHE are non-zero, then you
-   should only ever add information the macro table --- you should
-   never remove things from it.  You'll get an error if you try.  At
-   the moment, since we only provide obstacks and bcaches for macro
-   tables for symtabs, this restriction makes a nice sanity check.
-   Obstacks and bcaches are pretty much grow-only structures anyway.
-   However, if we find that it's occasionally useful to delete things
-   even from the symtab's tables, and the storage leak isn't a
-   problem, this restriction could be lifted.  */
+   Note that, if either OBSTACK or BCACHE are non-zero, then removing
+   information from the table may leak memory.  Neither obstacks nor
+   bcaches really allow you to remove information, so although we can
+   update the data structure to record the change, we can't free the
+   old data.  At the moment, since we only provide obstacks and
+   bcaches for macro tables for symtabs, this isn't a problem; only
+   odd debugging information makes a definition and then deletes it at
+   the same source location (although 'gcc -DFOO -UFOO -DFOO=2' does
+   do that in GCC 4.1.2.).  */
 struct macro_table *new_macro_table (struct obstack *obstack,
                                      struct bcache *bcache);