Re: [RFA] DLLs without debugging symbols (repost)

["Raoul Gough" <RaoulGough@yahoo.co.uk>]

[-- Attachment #1: Type: text/plain, Size: 1449 bytes --]

----- Original Message -----
From: "Zaretskii Eli" <ezaretski@elta.co.il>
To: "Elena Zannoni" <ezannoni@redhat.com>; "Raoul Gough"
<RaoulGough@yahoo.co.uk>
Cc: <gdb-patches@sources.redhat.com>
Sent: Thursday, February 20, 2003 7:08 AM
Subject: RE: [RFA] DLLs without debugging symbols (repost)
> > From: Elena Zannoni [mailto:ezannoni@redhat.com]
> > Sent: Thursday, February 20, 2003 4:00 AM
> >
> > The texinfo stuff should be approved by Eli. Mybe post it as a
> > separate [RFA/doco] message, it will be more likely to be noticed.
>
> Sorry, I did miss the original message.
>
> The doco patch is approved, but please put "kernel32.dll" inside
@file.

Done (new diff attached).

>
> Also, please use "---" (three dashes in a row) instead of just "-"
when
> you want an em-dash in the manual.

Also done (assuming an em-dash is one of them free-standing ones,
rather than one in a compound word).

>
> Symbol names such as ``KERNEL32!CreateFileA'' should be in @code
(and
> without the quotes).

Done.

>
> Instead of "(see @ref{Symbols})", please use "(@pxref{Symbols})".

Done.

>
> Finally, I suggest some @cindex entry about symbol names in
non-debug
> DLLs somewhere in the text.  Users might look for this information
in
> the index.

You might have missed the one I already had ("DLLs with no debugging
symbols") but I've added another one for good (?) measure - "Minimal
symbols and DLLs"

>
> Thanks!

Thank you!

Regards,
Raoul Gough.


[-- Attachment #2: gdb.texinfo.diff.txt --]
[-- Type: text/plain, Size: 6546 bytes --]

Index: src/gdb/doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.148
diff -c -p -r1.148 gdb.texinfo
*** src/gdb/doc/gdb.texinfo	20 Feb 2003 13:43:14 -0000	1.148
--- src/gdb/doc/gdb.texinfo	23 Feb 2003 17:44:37 -0000
*************** This command is supported only with some
*** 11164,11172 ****
  @cindex native Cygwin debugging
  @cindex Cygwin-specific commands
  
! @value{GDBN} supports native debugging of MS Windows programs, and
! defines a few commands specific to the Cygwin port.  This
! subsection describes those commands.
  
  @table @code
  @kindex info w32
--- 11164,11175 ----
  @cindex native Cygwin debugging
  @cindex Cygwin-specific commands
  
! @value{GDBN} supports native debugging of MS Windows programs, including
! DLLs with and without symbolic debugging information. There are various
! additional Cygwin-specific commands, described in this subsection.  The
! subsubsection @pxref{Non-debug DLL symbols} describes working with DLLs
! that have no debugging symbols.
! 
  
  @table @code
  @kindex info w32
*************** via a shell or directly (default value i
*** 11243,11248 ****
--- 11246,11375 ----
  Displays if the debuggee will be started with a shell.
  
  @end table
+ 
+ @menu
+ * Non-debug DLL symbols::  Support for DLLs without debugging symbols
+ @end menu
+ 
+ @node Non-debug DLL symbols
+ @subsubsection Support for DLLs without debugging symbols
+ @cindex DLLs with no debugging symbols
+ @cindex Minimal symbols and DLLs
+ 
+ Very often on windows, some of the DLLs that your program relies on do
+ not include symbolic debugging information (for example,
+ @file{kernel32.dll}). When @value{GDBN} doesn't recognize any debugging
+ symbols in a DLL, it relies on the minimal amount of symbolic
+ information contained in the DLL's export table. This subsubsection
+ describes working with such symbols, known internally to @value{GDBN} as
+ ``minimal symbols''.
+ 
+ Note that before the debugged program has started execution, no DLLs
+ will have been loaded. The easiest way around this problem is simply to
+ start the program --- either by setting a breakpoint or letting the
+ program run once to completion. It is also possible to force
+ @value{GDBN} to load a particular DLL before starting the executable ---
+ see the shared library information in @pxref{Files} or the
+ @code{dll-symbols} command in @pxref{Cygwin Native}. Currently,
+ explicitly loading symbols from a DLL with no debugging information will
+ cause the symbol names to be duplicated in @value{GDBN}'s lookup table,
+ which may adversely affect symbol lookup performance.
+ 
+ @subsubsection DLL name prefixes
+ 
+ In keeping with the naming conventions used by the Microsoft debugging
+ tools, DLL export symbols are made available with a prefix based on the
+ DLL name, for instance @code{KERNEL32!CreateFileA}.  The plain name is
+ also entered into the symbol table, so @code{CreateFileA} is often
+ sufficient. In some cases there will be name clashes within a program
+ (particularly if the executable itself includes full debugging symbols)
+ necessitating the use of the fully qualified name when referring to the
+ contents of the DLL. Use single-quotes around the name to avoid the
+ exclamation mark (``!'')  being interpreted as a language operator.
+ 
+ Note that the internal name of the DLL may be all upper-case, even
+ though the file name of the DLL is lower-case, or vice-versa. Since
+ symbols within @value{GDBN} are @emph{case-sensitive} this may cause
+ some confusion. If in doubt, try the @code{info functions} and
+ @code{info variables} commands or even @code{maint print msymbols} (see
+ @pxref{Symbols}). Here's an example:
+ 
+ @smallexample
+ (gdb) info function CreateFileA
+ All functions matching regular expression "CreateFileA":
+ 
+ Non-debugging symbols:
+ 0x77e885f4  CreateFileA
+ 0x77e885f4  KERNEL32!CreateFileA
+ @end smallexample
+ 
+ @smallexample
+ (gdb) info function !
+ All functions matching regular expression "!":
+ 
+ Non-debugging symbols:
+ 0x6100114c  cygwin1!__assert
+ 0x61004034  cygwin1!_dll_crt0@@0
+ 0x61004240  cygwin1!dll_crt0(per_process *)
+ [etc...]
+ @end smallexample
+ 
+ @subsubsection Working with minimal symbols
+ 
+ Symbols extracted from a DLL's export table do not contain very much
+ type information. All that @value{GDBN} can do is guess whether a symbol
+ refers to a function or variable depending on the linker section that
+ contains the symbol. Also note that the actual contents of the memory
+ contained in a DLL are not available unless the program is running. This
+ means that you cannot examine the contents of a variable or disassemble
+ a function within a DLL without a running program.
+ 
+ Variables are generally treated as pointers and dereferenced
+ automatically. For this reason, it is often necessary to prefix a
+ variable name with the address-of operator (``&'') and provide explicit
+ type information in the command. Here's an example of the type of
+ problem:
+ 
+ @smallexample
+ (gdb) print 'cygwin1!__argv'
+ $1 = 268572168
+ @end smallexample
+ 
+ @smallexample
+ (gdb) x 'cygwin1!__argv'
+ 0x10021610:      "\230y\""
+ @end smallexample
+ 
+ And two possible solutions:
+ 
+ @smallexample
+ (gdb) print ((char **)'cygwin1!__argv')[0]
+ $2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram"
+ @end smallexample
+ 
+ @smallexample
+ (gdb) x/2x &'cygwin1!__argv'
+ 0x610c0aa8 <cygwin1!__argv>:    0x10021608      0x00000000
+ (gdb) x/x 0x10021608
+ 0x10021608:     0x0022fd98
+ (gdb) x/s 0x0022fd98
+ 0x22fd98:        "/cygdrive/c/mydirectory/myprogram"
+ @end smallexample
+ 
+ Setting a break point within a DLL is possible even before the program
+ starts execution. However, under these circumstances, @value{GDBN} can't
+ examine the initial instructions of the function in order to skip the
+ function's frame set-up code. You can work around this by using ``*&''
+ to set the breakpoint at a raw memory address:
+ 
+ @smallexample
+ (gdb) break *&'python22!PyOS_Readline'
+ Breakpoint 1 at 0x1e04eff0
+ @end smallexample
+ 
+ The author of these extensions is not entirely convinced that setting a
+ break point within a shared DLL like @file{kernel32.dll} is completely
+ safe.
  
  @node Embedded OS
  @section Embedded Operating Systems