From be448670426df804030abad621f23972a540b8b5 Mon Sep 17 00:00:00 2001 From: Christopher Faylor Date: Sun, 23 Feb 2003 22:19:48 +0000 Subject: [PATCH] * gdb.texinfo (Cygwin Native): Links to Non-debug DLL symbols. (Non-debug DLL symbols): New node, describing the minimal symbols loaded from DLLs without real debugging symbols. --- gdb/doc/ChangeLog | 6 ++ gdb/doc/gdb.texinfo | 133 +++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 136 insertions(+), 3 deletions(-) diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index f00c495f40..7f10b0ae28 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,9 @@ +2003-02-23 Raoul Gough + + * gdb.texinfo (Cygwin Native): Links to Non-debug DLL symbols. + (Non-debug DLL symbols): New node, describing the minimal symbols + loaded from DLLs without real debugging symbols. + 2003-02-20 Andrew Cagney * gdb.texinfo (Set Breaks): Add cross reference to "set remote diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 9e9a0b8c3b..0bad40be7e 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -11164,9 +11164,12 @@ This command is supported only with some DPMI servers. @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. +@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 @@ -11244,6 +11247,130 @@ 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 : 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