* 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.

2 files changed, 136 insertions, 3 deletions

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index f00c495..7f10b0a 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,9 @@
+2003-02-23  Raoul Gough  <RaoulGough@yahoo.co.uk>
+
+	* 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  <ac131313@redhat.com>
 
 	* gdb.texinfo (Set Breaks): Add cross reference to "set remote
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 9e9a0b8..0bad40b 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 <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