Re: [rfa] SYMBOL_NATURAL_NAME, SYMBOL_LINKAGE_NAME

[Elena Zannoni <ezannoni@redhat.com>]

David Carlton writes:
 > This patch adds macros SYMBOL_NATURAL_NAME and SYMBOL_LINKAGE_NAME to
 > symtab.h.  The former returns what the programmer thinks a symbol is
 > called; the latter returns what the linker thinks a symbol is called.
 > In C, these are the same thing; in C++, the former is the demangled
 > name, and the latter is the mangled name.

Good move.  A couple of things.  I think the sentence "the programmer
thinks a symbol is called" is a bit vague.  Maybe something like the
'name of a symbol as it appears in the high level programming
language', or 'name of a symbol as it was declared in the high level
program' or something like that? 

Second thing, more important. I think that if we are going to try to
switch away from using SYMBOL_NAME, we should be renaming it to
DEPRECATED_SYMBOL_NAME, because this will be more effective than
putting a 'suggested use' in a comment.  It's a bit more of slog work,
but we could then even ARI the DEPRECATED_SYMBOL_NAME.

what do you think?

elena


 > 
 > SYMBOL_NATURAL_NAME is implemented by calling a function
 > symbol_natural_name, since that seems to be the way we're going with
 > this sort of macro.  SYMBOL_LINKAGE_NAME is implemented by just
 > calling SYMBOL_NAME.  But SYMBOL_LINKAGE_NAME has the advantage that,
 > if somebody uses SYMBOL_LINKAGE_NAME, then you know that they really
 > meant the linkage name, whereas if they use SYMBOL_NAME, they might
 > not have thought about the issue.
 > 
 > The only place this patch actually uses these functions is to redefine
 > SYMBOL_PRINT_NAME in terms of them.  This redefinition shouldn't
 > change GDB's behavior.  At some point in the future, I'll try to go
 > through uses of SYMBOL_PRINT_NAME in GDB to see which of them should
 > be changed to SYMBOL_NATURAL_NAME; I'll also try to go through uses of
 > SYMBOL_NAME to see if I can figure out which of them should be changed
 > to SYMBOL_LINKAGE_NAME and which to SYMBOL_NATURAL_NAME, though I
 > expect that will be harder.
 > 
 > Tested on i686-pc-linux-gnu/GCC3.1/DWARF-2; OK to commit?
 > 
 > David Carlton
 > carlton@math.stanford.edu
 > 
 > 2003-02-24  David Carlton  <carlton@math.stanford.edu>
 > 
 > 	* symtab.h (SYMBOL_NATURAL_NAME): New macro.
 > 	(SYMBOL_LINKAGE_NAME): Ditto.
 > 	(SYMBOL_PRINT_NAME): Use SYMBOL_NATURAL_NAME and
 > 	SYMBOL_LINKAGE_NAME.
 > 	* symtab.c (symbol_natural_name): New function.
 > 
 > Index: symtab.h
 > ===================================================================
 > RCS file: /cvs/src/src/gdb/symtab.h,v
 > retrieving revision 1.62
 > diff -u -p -r1.62 symtab.h
 > --- symtab.h	21 Feb 2003 15:24:18 -0000	1.62
 > +++ symtab.h	25 Feb 2003 00:26:12 -0000
 > @@ -160,6 +160,36 @@ extern void symbol_set_names (struct gen
 >  			      const char *name, int len,
 >  			      struct objfile *objfile);
 >  
 > +/* Now come lots of name accessor macros.  Short version as to when to
 > +   use which: Use SYMBOL_NATURAL_NAME if you want to know what the
 > +   programmer thinks the symbol's name is.  Use SYMBOL_LINKAGE_NAME if
 > +   you want to know what the linker thinks the symbol's name is.  Use
 > +   SYMBOL_PRINT_NAME for output.  Use SYMBOL_DEMANGLED_NAME if you
 > +   specifically need to know whether SYMBOL_NATURAL_NAME and
 > +   SYMBOL_LINKAGE_NAME are different.  Try to avoid using SYMBOL_NAME
 > +   entirely (usually SYMBOL_NATURAL_NAME or SYMBOL_LINKAGE_NAME is a
 > +   better choice).  */
 > +
 > +/* Return SYMBOL's "natural" name, by which I mean the name that it
 > +   was called in the original source code.  In languages like C++
 > +   where symbols may be mangled for ease of manipulation by the
 > +   linker, this is the demangled name.  */
 > +
 > +#define SYMBOL_NATURAL_NAME(symbol) \
 > +  (symbol_natural_name (&(symbol)->ginfo))
 > +extern char *symbol_natural_name (const struct general_symbol_info *symbol);
 > +
 > +/* Return SYMBOL's name from the point of view of the linker.  In
 > +   languages like C++ where symbols may be mangled for ease of
 > +   manipulation by the linker, this is the mangled name; otherwise,
 > +   it's the same as SYMBOL_NATURAL_NAME.  This is currently identical
 > +   to SYMBOL_NAME, but please use SYMBOL_LINKAGE_NAME when
 > +   appropriate: it conveys the additional semantic information that
 > +   you really have thought about the issue and decided that you mean
 > +   SYMBOL_LINKAGE_NAME instead of SYMBOL_NATURAL_NAME.  */
 > +
 > +#define SYMBOL_LINKAGE_NAME(symbol)	SYMBOL_NAME (symbol)
 > +
 >  /* Return the demangled name for a symbol based on the language for
 >     that symbol.  If no demangled name exists, return NULL. */
 >  #define SYMBOL_DEMANGLED_NAME(symbol) \
 > @@ -175,9 +205,7 @@ extern char *symbol_demangled_name (stru
 >     output.  */
 >  
 >  #define SYMBOL_PRINT_NAME(symbol)					\
 > -  (demangle && SYMBOL_DEMANGLED_NAME (symbol) != NULL			\
 > -   ? SYMBOL_DEMANGLED_NAME (symbol)					\
 > -   : SYMBOL_NAME (symbol))
 > +  (demangle ? SYMBOL_NATURAL_NAME (symbol) : SYMBOL_LINKAGE_NAME (symbol))
 >  
 >  /* Macro that tests a symbol for a match against a specified name string.
 >     First test the unencoded name, then looks for and test a C++ encoded
 > Index: symtab.c
 > ===================================================================
 > RCS file: /cvs/src/src/gdb/symtab.c,v
 > retrieving revision 1.94
 > diff -u -p -r1.94 symtab.c
 > --- symtab.c	24 Feb 2003 23:40:50 -0000	1.94
 > +++ symtab.c	25 Feb 2003 00:26:23 -0000
 > @@ -575,6 +575,25 @@ symbol_init_demangled_name (struct gener
 >      }
 >  }
 >  
 > +/* Return the source code name of a symbol.  In languages where
 > +   demangling is necessary, this is the demangled name.  */
 > +
 > +char *
 > +symbol_natural_name (const struct general_symbol_info *gsymbol)
 > +{
 > +  if ((gsymbol->language == language_cplus
 > +       || gsymbol->language == language_java
 > +       || gsymbol->language == language_objc)
 > +      && (gsymbol->language_specific.cplus_specific.demangled_name != NULL))
 > +    {
 > +      return gsymbol->language_specific.cplus_specific.demangled_name;
 > +    }
 > +  else
 > +    {
 > +      return gsymbol->name;
 > +    }
 > +}
 > +
 >  /* Return the demangled name for a symbol based on the language for
 >     that symbol.  If no demangled name exists, return NULL. */
 >  char *