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 : 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