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

Christopher Faylor
2003-02-23T17:53:36Z

Eli,
I'll check this in if this addresses all of your concerns.

cgf

On Sun, Feb 23, 2003 at 05:46:54PM -0000, Raoul Gough wrote:
>----- 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.
>

>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