@c readline appendices use @vindex
@syncodeindex vr cp
-@c ===> NOTE! <==
-@c Determine the edition number in *three* places by hand:
-@c 1. First ifinfo section 2. title page 3. top node
-@c To find the locations, search for !!set
+@c !!set GDB manual's edition---not the same as GDB version!
+@set EDITION 4.10
+
+@c !!set GDB manual's revision date
+@set DATE November 1993
@c GDB CHANGELOG CONSULTED BETWEEN:
@c Fri Oct 11 23:27:06 1991 John Gilmore (gnu at cygnus.com)
@ifinfo
This file documents the GNU debugger @value{GDBN}.
-@c !!set edition, date, version
-This is Edition 4.09, August 1993,
+
+This is Edition @value{EDITION}, @value{DATE},
of @cite{Debugging with @value{GDBN}: the GNU Source-Level Debugger}
for GDB Version @value{GDBVN}.
@subtitle (@value{TARGET})
@end ifclear
@sp 1
-@c !!set edition, date, version
-@subtitle Edition 4.09, for @value{GDBN} version @value{GDBVN}
-@subtitle August 1993
+@subtitle Edition @value{EDITION}, for @value{GDBN} version @value{GDBVN}
+@subtitle @value{DATE}
@author Richard M. Stallman and Roland H. Pesch
@page
@tex
This file describes @value{GDBN}, the GNU symbolic debugger.
-@c !!set edition, date, version
-This is Edition 4.09, April 1993, for GDB Version @value{GDBVN}.
+This is Edition @value{EDITION}, @value{DATE}, for GDB Version @value{GDBVN}.
@menu
* Summary:: Summary of @value{GDBN}
@end itemize
@ifclear CONLY
-@ifclear MOD2
-You can use @value{GDBN} to debug programs written in C or C++.
-@end ifclear
+You can use @value{GDBN} to debug programs written in C or C++. For
+more information, see @ref{C,,C and C++}.
+
@ifset MOD2
-You can use @value{GDBN} to debug programs written in C, C++, and
-Modula-2.
+@c "MOD2" used as a "miscellaneous languages" flag here.
+@c This is acceptable while there is no real doc for Chill and Pascal.
+Support for Modula-2 and Chill is partial. For information on Modula-2,
+see @ref{Modula-2,,Modula-2}; there is no further documentation on Chill yet.
+
+Debugging pascal programs which use sets, subranges, file variables, or nested
+functions does not currently work. @value{GDBN} does not support
+entering expressions, printing values, etc. using Pascal syntax.
@end ifset
@ifset FORTRAN
@cindex Fortran
So that they may not regard their long labor as thankless, we
particularly thank those who shepherded GDB through major releases: Fred
-Fish (release 4.9), Stu Grossman and John Gilmore (releases 4.8, 4.7,
-4.6, 4.5, 4.4), John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); Jim
-Kingdon (releases 3.5, 3.4, 3.3); and Randy Smith (releases 3.2, 3.1,
-3.0). As major maintainer of GDB for some period, each contributed
-significantly to the structure, stability, and capabilities of the
-entire debugger.
+Fish (releases 4.11, 4.10, 4.9), Stu Grossman and John Gilmore (releases
+4.8, 4.7, 4.6, 4.5, 4.4), John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and
+3.9); Jim Kingdon (releases 3.5, 3.4, 3.3); and Randy Smith (releases
+3.2, 3.1, 3.0). As major maintainer of GDB for some period, each
+contributed significantly to the structure, stability, and capabilities
+of the entire debugger.
Richard Stallman, assisted at various times by Peter TerMaat, Chris
Hanson, and Richard Mlynarik, handled releases through 2.8.
GDB 4 can debug programs and core files that use SunOS, SVR4, or IBM RS/6000
shared libraries.
+@item Threads
+On some systems, GDB 4 has facilities to debug multi-thread programs.
+
@item Reference Card
GDB 4 has a reference card. @xref{Formatting Documentation,,Formatting
the Documentation}, for instructions about how to print it.
* Attach:: Debugging an already-running process
* Kill Process:: Killing the child process
* Process Information:: Additional process information
+* Threads:: Debugging programs with multiple threads
@end ifclear
@end menu
@item info proc all
Show all the above information about the process.
@end table
+
+@node Threads
+@section Debugging programs with multiple threads
+
+@cindex threads of execution
+@cindex multiple threads
+@cindex switching threads
+In some operating systems, a single program may have more than one
+@dfn{thread} of execution. The precise semantics of threads differ from
+one operating system to another, but in general the threads of a single
+program are akin to multiple processes---except that they share one
+address space (that is, they can all examine and modify the same
+variables). On the other hand, each thread has its own registers and
+execution stack, and perhaps private memory.
+
+@value{GDBN} provides these facilities for debugging multi-thread
+programs:
+
+@itemize @bullet
+@item automatic notification of new threads
+@item @samp{thread @var{threadno}}, a command to switch among threads
+@item @samp{info threads}, a command to inquire about existing threads
+@item thread-specific breakpoints
+@end itemize
+
+@quotation
+@emph{Warning:} These facilities are not yet available on every
+@value{GDBN} configuration where the operating system supports threads.
+If your @value{GDBN} does not support threads, these commands have no
+effect. For example, a system without thread support shows no output
+from @samp{info threads}, and always rejects the @code{thread} command,
+like this:
+
+@smallexample
+(@value{GDBP}) info threads
+(@value{GDBP}) thread 1
+Thread ID 1 not known. Use the "info threads" command to
+see the IDs of currently known threads.
+@end smallexample
+@c FIXME to implementors: how hard would it be to say "sorry, this GDB
+@c doesn't support threads"?
+@end quotation
+
+@cindex focus of debugging
+@cindex current thread
+The @value{GDBN} thread debugging facility allows you to observe all
+threads while your program runs---but whenever @value{GDBN} takes
+control, one thread in particular is always the focus of debugging.
+This thread is called the @dfn{current thread}. Debugging commands show
+program information from the perspective of the current thread.
+
+@kindex New @var{systag}
+@cindex thread identifier (system)
+@c FIXME-implementors!! It would be more helpful if the [New...] message
+@c included GDB's numeric thread handle, so you could just go to that
+@c thread without first checking `info threads'.
+Whenever @value{GDBN} detects a new thread in your program, it displays
+the target system's identification for the thread with a message in the
+form @samp{[New @var{systag}]}. @var{systag} is a thread identifier
+whose form varies depending on the particular system. For example, on
+LynxOS, you might see
+
+@example
+[New process 35 thread 27]
+@end example
+
+@noindent
+when @value{GDBN} notices a new thread. In contrast, on an SGI system,
+the @var{systag} is simply something like @samp{process 368}, with no
+further qualifier.
+
+@c FIXME!! (1) Does the [New...] message appear even for the very first
+@c thread of a program, or does it only appear for the
+@c second---i.e., when it becomes obvious we have a multithread
+@c program?
+@c (2) *Is* there necessarily a first thread always? Or do some
+@c multithread systems permit starting a program with multiple
+@c threads ab initio?
+
+@cindex thread number
+@cindex thread identifier (GDB)
+For debugging purposes, @value{GDBN} associates its own thread
+number---always a single integer---with each thread in your program.
+
+@table @code
+@item info threads
+@kindex info threads
+Display a summary of all threads currently in your
+program. @value{GDBN} displays for each thread (in this order):
+
+@enumerate
+@item the thread number assigned by @value{GDBN}
+
+@item the target system's thread identifier (@var{systag})
+
+@item the current stack frame summary for that thread
+@end enumerate
+
+@noindent
+An asterisk @samp{*} to the left of the @value{GDBN} thread number
+indicates the current thread.
+
+For example,
+@end table
+@c end table here to get a little more width for example
+
+@smallexample
+(@value{GDBP}) info threads
+ 3 process 35 thread 27 0x34e5 in sigpause ()
+ 2 process 35 thread 23 0x34e5 in sigpause ()
+* 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8)
+ at threadtest.c:68
+@end smallexample
+
+@table @code
+@item thread @var{threadno}
+@kindex thread @var{threadno}
+Make thread number @var{threadno} the current thread. The command
+argument @var{threadno} is the internal @value{GDBN} thread number, as
+shown in the first field of the @samp{info threads} display.
+@value{GDBN} responds by displaying the system identifier of the thread
+you selected, and its current stack frame summary:
+
+@smallexample
+@c FIXME!! This example made up; find a GDB w/threads and get real one
+(@value{GDBP}) thread 2
+[Switching to process 35 thread 23]
+0x34e5 in sigpause ()
+@end smallexample
+
+@noindent
+As with the @samp{[New @dots{}]} message, the form of the text after
+@samp{Switching to} depends on your system's conventions for identifying
+threads.
+@end table
+
+@cindex automatic thread selection
+@cindex switching threads automatically
+@cindex threads, automatic switching
+Whenever @value{GDBN} stops your program, due to a breakpoint or a
+signal, it automatically selects the thread where that breakpoint or
+signal happened. @value{GDBN} alerts you to the context switch with a
+message of the form @samp{[Switching to @var{systag}]} to identify the
+thread.
+
+@xref{Thread Stops,,Stopping and starting multi-thread programs}, for
+more information about how @value{GDBN} behaves when you stop and start
+programs with multiple threads.
+
+@xref{Set Watchpoints,,Setting watchpoints}, for information about
+watchpoints in programs with multiple threads.
@end ifclear
@node Stopping
@ifset POSIX
* Signals:: Signals
@end ifset
+@ifclear BARETARGET
+* Thread Stops:: Stopping and starting multi-thread programs
+@end ifclear
@end menu
@c makeinfo node-defaulting requires adjacency of @node and sectioning cmds
in the program.
@ifclear CONLY
In languages with exception handling (such as GNU C++), you can also set
-breakpoints where an exception is raised (@pxref{Exception Handling,
-,Breakpoints and exceptions}).
+breakpoints where an exception is raised (@pxref{Exception Handling,,
+Breakpoints and exceptions}).
@end ifclear
@cindex watchpoints
and watchpoints using the same commands.
You can arrange to have values from your program displayed automatically
-whenever @value{GDBN} stops at a breakpoint. @xref{Auto Display,
-,Automatic display}.
+whenever @value{GDBN} stops at a breakpoint. @xref{Auto Display,,
+Automatic display}.
@cindex breakpoint numbers
@cindex numbers for breakpoints
same as @code{info break}.
@end table
+@ifclear BARETARGET
+@quotation
+@cindex watchpoints and threads
+@cindex threads and watchpoints
+@emph{Warning:} in multi-thread programs, watchpoints have only limited
+usefulness. With the current watchpoint implementation, @value{GDBN}
+can only watch the value of an expression @emph{in a single thread}. If
+you are confident that the expression can only change due to the current
+thread's activity (and if you are also confident that the same thread
+will remain current), then you can use watchpoints as usual. However,
+@value{GDBN} may not notice when a non-current thread's activity changes
+the expression.
+@end quotation
+@end ifclear
+
@ifclear CONLY
@node Exception Handling
@subsection Breakpoints and exceptions
program a signal}.
@end ifset
+@ifclear BARETARGET
+@node Thread Stops
+@section Stopping and starting multi-thread programs
+
+When your program has multiple threads (@pxref{Threads,, Debugging
+programs with multiple threads}), you can choose whether to set
+breakpoints on all threads, or on a particular thread.
+
+@table @code
+@cindex breakpoints and threads
+@cindex thread breakpoints
+@kindex break @dots{} thread @var{threadno}
+@item break @var{linespec} thread @var{threadno}
+@itemx break @var{linespec} thread @var{threadno} if @dots{}
+Use the qualifier @samp{thread @var{threadno}} with a breakpoint command
+to specify that you only want @value{GDBN} to stop the program when a
+particular thread reaches this breakpoint. @var{threadno} is one of the
+numeric thread identifiers assigned by @value{GDBN}, shown in the first
+column of the @samp{info threads} display.
+
+If you do not specify @samp{thread @var{threadno}} when you set a
+breakpoint, the breakpoint applies to @emph{all} threads of your
+program.
+
+You can use the @code{thread} qualifier on conditional breakpoints as
+well; in this case, place @samp{thread @var{threadno}} before the
+breakpoint condition, like this:
+
+@smallexample
+(gdb) break frik.c:13 thread 28 if bartab > lim
+@end smallexample
+@end table
+
+@cindex stopped threads
+@cindex threads, stopped
+Whenever your program stops under @value{GDBN} for any reason,
+@emph{all} threads of execution stop, not just the current thread. This
+allows you to examine the overall state of the program, including
+switching between threads, without worrying that things may change
+underfoot.
+
+@cindex continuing threads
+@cindex threads, continuing
+Conversely, whenever you restart the program, @emph{all} threads start
+executing. @emph{This is true even when single-stepping} with commands
+like @code{step} or @code{next}.
+
+In particular, @value{GDBN} cannot single-step all threads in lockstep.
+Since thread scheduling is up to your debugging target's operating
+system (not controlled by @value{GDBN}), other threads may
+execute more than one statement while the current thread completes a
+single step. Moreover, in general other threads stop in the middle of a
+statement, rather than at a clean statement boundary, when the program
+stops.
+
+You might even find your program stopped in another thread after
+continuing or even single-stepping. This happens whenever some other
+thread runs into a breakpoint, a signal, or an exception before the
+first thread completes whatever you requested.
+@end ifclear
+
@node Stack
@chapter Examining the Stack
@cindex @code{heuristic-fence-post} (MIPS)
@table @code
@item set heuristic-fence-post @var{limit}
-Restrict @var{GDBN} to examining at most @var{limit} bytes in its search
+Restrict @value{GDBN} to examining at most @var{limit} bytes in its search
for the beginning of a function. A value of @code{0} (the default)
means there is no limit.
whitespace. You may specify a directory that is already in the source
path; this moves it forward, so it will be searched sooner.
+@kindex cdir
+@kindex cwd
+@kindex $cdir
+@kindex $cwd
+@cindex compilation directory
+@cindex current directory
+@cindex working directory
+@cindex directory, current
+@cindex directory, compilation
You can use the string @samp{$cdir} to refer to the compilation
directory (if one is recorded), and @samp{$cwd} to refer to the current
working directory. @samp{$cwd} is not the same as @samp{.}---the former
@kindex g++
@cindex GNU C++
The C++ debugging facilities are jointly implemented by the GNU C++
-compiler and @value{GDBN}. Therefore, to debug your C++ code effectively,
-you must compile your C++ programs with the GNU C++ compiler,
-@code{g++}.
+compiler and @value{GDBN}. Therefore, to debug your C++ code
+effectively, you must compile your C++ programs with the GNU C++
+compiler, @code{g++}.
+
+For best results when debugging C++ programs, use the stabs debugging
+format. You can select that format explicitly with the @code{g++}
+command-line options @samp{-gstabs} or @samp{-gstabs+}. See
+@ref{Debugging Options,,Options for Debugging Your Program or GNU CC,
+gcc.info, Using GNU CC}, for more information.
@end ifclear
@ifset CONLY
@node C
@kindex ptype
Print a description of data type @var{typename}. @var{typename} may be
the name of a type, or for C code it may have the form
+@ifclear CONLY
+@samp{class @var{class-name}},
+@end ifclear
@samp{struct @var{struct-tag}}, @samp{union @var{union-tag}} or
@samp{enum @var{enum-tag}}.
@end ifset
The file is loaded at whatever address is specified in the executable.
-For some object file formats, like a.out, the object file format fixes
-the address and so it won't necessarily match the address you gave to
-the linker.
+For some object file formats, you can specify the load address when you
+link the program; for other formats, like a.out, the object file format
+specifies a fixed address.
+@c FIXME! This would be a good place for an xref to the GNU linker doc.
@ifset VXWORKS
On VxWorks, @code{load} will dynamically link @var{filename} on the
@cindex init file
@cindex @file{@value{GDBINIT}}
When you start @value{GDBN}, it automatically executes commands from its
-@dfn{init files}. These are files named @file{@value{GDBINIT}}. @value{GDBN} reads
-the init file (if any) in your home directory and then the init file
-(if any) in the current working directory. (The init files are not
-executed if you use the @samp{-nx} option; @pxref{Mode Options,
-,Choosing modes}.)
+@dfn{init files}. These are files named @file{@value{GDBINIT}}.
+@value{GDBN} reads the init file (if any) in your home directory, then
+processes command line options and operands, and then reads the init
+file (if any) in the current working directory. This is so the init
+file in your home directory can set options (such as @code{set
+complaints}) which affect the processing of the command line options and
+operands. The init files are not executed if you use the @samp{-nx}
+option; @pxref{Mode Options, ,Choosing modes}.
@ifset GENERIC
@cindex init file name
projects / deliverable / binutils-gdb.git / blobdiff