\input texinfo @c -*-texinfo-*-
@c Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,
-@c 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
+@c 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009
@c Free Software Foundation, Inc.
@c
@c %**start of header
* Gdb: (gdb). The GNU debugger.
@end direntry
-@ifinfo
-This file documents the @sc{gnu} debugger @value{GDBN}.
-
-
-This is the @value{EDITION} Edition, of @cite{Debugging with
-@value{GDBN}: the @sc{gnu} Source-Level Debugger} for @value{GDBN}
-@ifset VERSION_PACKAGE
-@value{VERSION_PACKAGE}
-@end ifset
-Version @value{GDBVN}.
-
-Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,@*
- 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006@*
- Free Software Foundation, Inc.
+@copying
+Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
+1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009
+Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
(a) The FSF's Back-Cover Text is: ``You are free to copy and modify
this GNU Manual. Buying copies from GNU Press supports the FSF in
developing GNU and promoting software freedom.''
-@end ifinfo
+@end copying
+
+@ifnottex
+This file documents the @sc{gnu} debugger @value{GDBN}.
+
+This is the @value{EDITION} Edition, of @cite{Debugging with
+@value{GDBN}: the @sc{gnu} Source-Level Debugger} for @value{GDBN}
+@ifset VERSION_PACKAGE
+@value{VERSION_PACKAGE}
+@end ifset
+Version @value{GDBVN}.
+
+@insertcopying
+@end ifnottex
@titlepage
@title Debugging with @value{GDBN}
@end tex
@vskip 0pt plus 1filll
-Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995,
-1996, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2006
-Free Software Foundation, Inc.
-@sp 2
Published by the Free Software Foundation @*
51 Franklin Street, Fifth Floor,
Boston, MA 02110-1301, USA@*
ISBN 1-882114-77-9 @*
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with the
-Invariant Sections being ``Free Software'' and ``Free Software Needs
-Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
-and with the Back-Cover Texts as in (a) below.
-
-(a) The FSF's Back-Cover Text is: ``You are free to copy and modify
-this GNU Manual. Buying copies from GNU Press supports the FSF in
-developing GNU and promoting software freedom.''
+@insertcopying
@page
This edition of the GDB manual is dedicated to the memory of Fred
Fish. Fred was a long-standing contributor to GDB and to Free
@end ifset
Version @value{GDBVN}.
-Copyright (C) 1988-2006 Free Software Foundation, Inc.
+Copyright (C) 1988-2009 Free Software Foundation, Inc.
This edition of the GDB manual is dedicated to the memory of Fred
Fish. Fred was a long-standing contributor to GDB and to Free
* Agent Expressions:: The GDB Agent Expression Mechanism
* Target Descriptions:: How targets can describe themselves to
@value{GDBN}
+* Operating System Information:: Getting additional information from
+ the operating system
* Copying:: GNU General Public License says
how you can copy and share GDB
* GNU Free Documentation License:: The license for this documentation
@item
@cindex init file
-Reads the @dfn{init file} (if any) in your home directory@footnote{On
+Reads the system-wide @dfn{init file} (if @option{--with-system-gdbinit} was
+used when building @value{GDBN}; @pxref{System-wide configuration,
+ ,System-wide configuration and settings}) and executes all the commands in
+that file.
+
+@item
+Reads the init file (if any) in your home directory@footnote{On
DOS/Windows systems, the home directory is the one pointed to by the
@code{HOME} environment variable.} and executes all the commands in
that file.
and operands. Init files are not executed if you use the @samp{-nx}
option (@pxref{Mode Options, ,Choosing Modes}).
+To display the list of init files loaded by gdb at startup, you
+can use @kbd{gdb --help}.
+
@cindex init file name
@cindex @file{.gdbinit}
@cindex @file{gdb.ini}
A call to @code{vfork}. This is currently only available for HP-UX
and @sc{gnu}/Linux.
-@item load
-@itemx load @var{libname}
-@cindex break on load/unload of shared library
-The dynamic loading of any shared library, or the loading of the library
-@var{libname}. This is currently only available for HP-UX.
-
-@item unload
-@itemx unload @var{libname}
-The unloading of any dynamically loaded shared library, or the unloading
-of the library @var{libname}. This is currently only available for HP-UX.
@end table
@item tcatch @var{event}
@c @ifclear BARETARGET
@node Error in Breakpoints
@subsection ``Cannot insert breakpoints''
-@c
-@c FIXME!! 14/6/95 Is there a real example of this? Let's use it.
-@c
-Under some operating systems, breakpoints cannot be used in a program if
-any other process is running that program. In this situation,
-attempting to run or continue a program with a breakpoint causes
-@value{GDBN} to print an error message:
-
-@smallexample
-Cannot insert breakpoints.
-The same program may be running in another process.
-@end smallexample
-
-When this happens, you have three ways to proceed:
-
-@enumerate
-@item
-Remove or disable the breakpoints, then continue.
-
-@item
-Suspend @value{GDBN}, and copy the file containing your program to a new
-name. Resume @value{GDBN} and use the @code{exec-file} command to specify
-that @value{GDBN} should run your program under that name.
-Then start your program again.
-
-@item
-Relink your program so that the text segment is nonsharable, using the
-linker option @samp{-N}. The operating system limitation may not apply
-to nonsharable executables.
-@end enumerate
-@c @end ifclear
-A similar message can be printed if you request too many active
-hardware-assisted breakpoints and watchpoints:
+If you request too many active hardware-assisted breakpoints and
+watchpoints, you will see this error message:
@c FIXME: the precise wording of this message may change; the relevant
@c source change is not committed yet (Sep 3, 1999).
you can continue with @samp{signal 0}. @xref{Signaling, ,Giving your
Program a Signal}.
+@cindex extra signal information
+@anchor{extra signal information}
+
+On some targets, @value{GDBN} can inspect extra signal information
+associated with the intercepted signal, before it is actually
+delivered to the program being debugged. This information is exported
+by the convenience variable @code{$_siginfo}, and consists of data
+that is passed by the kernel to the signal handler at the time of the
+receipt of a signal. The data type of the information itself is
+target dependent. You can see the data type using the @code{ptype
+$_siginfo} command. On Unix systems, it typically corresponds to the
+standard @code{siginfo_t} type, as defined in the @file{signal.h}
+system header.
+
+Here's an example, on a @sc{gnu}/Linux system, printing the stray
+referenced address that raised a segmentation fault.
+
+@smallexample
+@group
+(@value{GDBP}) continue
+Program received signal SIGSEGV, Segmentation fault.
+0x0000000000400766 in main ()
+69 *(int *)p = 0;
+(@value{GDBP}) ptype $_siginfo
+type = struct @{
+ int si_signo;
+ int si_errno;
+ int si_code;
+ union @{
+ int _pad[28];
+ struct @{...@} _kill;
+ struct @{...@} _timer;
+ struct @{...@} _rt;
+ struct @{...@} _sigchld;
+ struct @{...@} _sigfault;
+ struct @{...@} _sigpoll;
+ @} _sifields;
+@}
+(@value{GDBP}) ptype $_siginfo._sifields._sigfault
+type = struct @{
+ void *si_addr;
+@}
+(@value{GDBP}) p $_siginfo._sifields._sigfault.si_addr
+$1 = (void *) 0x7ffff7ff7000
+@end group
+@end smallexample
+
+Depending on target support, @code{$_siginfo} may also be writable.
+
@node Thread Stops
@section Stopping and Starting Multi-thread Programs
@kindex next&
@xref{Continuing and Stepping, next}.
+@item nexti
+@kindex nexti&
+@xref{Continuing and Stepping, nexti}.
+
@item continue
@kindex continue&
@xref{Continuing and Stepping, continue}.
@vindex $_exitcode@r{, convenience variable}
The variable @code{$_exitcode} is automatically set to the exit code when
the program being debugged terminates.
+
+@item $_siginfo
+@vindex $_siginfo@r{, convenience variable}
+The variable @code{$_siginfo} is bound to extra signal information
+inspection (@pxref{extra signal information}).
@end table
On HP-UX systems, if you refer to a function or variable name that
an unrecognized tag.
@end table
+On some targets, @value{GDBN} can access operating-system-specific information
+and display it to user, without interpretation. For remote targets,
+this functionality depends on the remote stub's support of the
+@samp{qXfer:osdata:read} packet, see @ref{qXfer osdata read}.
+
+@table @code
+@kindex info os processes
+@item info os processes
+Display the list of processes on the target. For each process,
+@value{GDBN} prints the process identifier, the name of the user, and
+the command corresponding to the process.
+@end table
@node Memory Region Attributes
@section Memory Region Attributes
@vindex colon-colon@r{, in Modula-2}
@c Info cannot handle :: but TeX can.
@end ifinfo
-@iftex
+@ifnotinfo
@vindex ::@r{, in Modula-2}
-@end iftex
+@end ifnotinfo
There are a few subtle differences between the Modula-2 scope operator
(@code{.}) and the @value{GDBN} scope operator (@code{::}). The two have
* Omissions from Ada:: Restrictions on the Ada expression syntax.
* Additions to Ada:: Extensions of the Ada expression syntax.
* Stopping Before Main Program:: Debugging the program during elaboration.
+* Ada Tasks:: Listing and setting breakpoints in tasks.
+* Ada Tasks and Core Files:: Tasking Support when Debugging Core Files
* Ada Glitches:: Known peculiarities of Ada mode.
@end menu
permitted only on the right sides of assignments, as in these examples:
@smallexample
-set An_Array := (1, 2, 3, 4, 5, 6)
-set An_Array := (1, others => 0)
-set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6)
-set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9))
-set A_Record := (1, "Peter", True);
-set A_Record := (Name => "Peter", Id => 1, Alive => True)
+(@value{GDBP}) set An_Array := (1, 2, 3, 4, 5, 6)
+(@value{GDBP}) set An_Array := (1, others => 0)
+(@value{GDBP}) set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6)
+(@value{GDBP}) set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9))
+(@value{GDBP}) set A_Record := (1, "Peter", True);
+(@value{GDBP}) set A_Record := (Name => "Peter", Id => 1, Alive => True)
@end smallexample
Changing a
assignments:
@smallexample
-set A_Rec.Len := 4
-set A_Rec := (Id => 42, Vals => (1, 2, 3, 4))
+(@value{GDBP}) set A_Rec.Len := 4
+(@value{GDBP}) set A_Rec := (Id => 42, Vals => (1, 2, 3, 4))
@end smallexample
As this example also illustrates, @value{GDBN} is very loose about the usual
its right-hand operand as its value. Thus, you may enter
@smallexample
-set x := y + 3
-print A(tmp := y + 1)
+(@value{GDBP}) set x := y + 3
+(@value{GDBP}) print A(tmp := y + 1)
@end smallexample
@item
complex conditional breaks:
@smallexample
-break f
-condition 1 (report(i); k += 1; A(k) > 100)
+(@value{GDBP}) break f
+(@value{GDBP}) condition 1 (report(i); k += 1; A(k) > 100)
@end smallexample
@item
to write
@smallexample
-print 'max(x, y)
+(@value{GDBP}) print 'max(x, y)
@end smallexample
@item
enclose them in angle brackets to avoid the lower-case mapping.
For example,
@smallexample
-@value{GDBP} print <JMPBUF_SAVE>[0]
+(@value{GDBP}) print <JMPBUF_SAVE>[0]
@end smallexample
@item
elaboration, simply use the following two commands:
@code{tbreak adainit} and @code{run}.
+@node Ada Tasks
+@subsubsection Extensions for Ada Tasks
+@cindex Ada, tasking
+
+Support for Ada tasks is analogous to that for threads (@pxref{Threads}).
+@value{GDBN} provides the following task-related commands:
+
+@table @code
+@kindex info tasks
+@item info tasks
+This command shows a list of current Ada tasks, as in the following example:
+
+
+@smallexample
+@iftex
+@leftskip=0.5cm
+@end iftex
+(@value{GDBP}) info tasks
+ ID TID P-ID Pri State Name
+ 1 8088000 0 15 Child Activation Wait main_task
+ 2 80a4000 1 15 Accept Statement b
+ 3 809a800 1 15 Child Activation Wait a
+* 4 80ae800 3 15 Running c
+
+@end smallexample
+
+@noindent
+In this listing, the asterisk before the last task indicates it to be the
+task currently being inspected.
+
+@table @asis
+@item ID
+Represents @value{GDBN}'s internal task number.
+
+@item TID
+The Ada task ID.
+
+@item P-ID
+The parent's task ID (@value{GDBN}'s internal task number).
+
+@item Pri
+The base priority of the task.
+
+@item State
+Current state of the task.
+
+@table @code
+@item Unactivated
+The task has been created but has not been activated. It cannot be
+executing.
+
+@item Running
+The task currently running.
+
+@item Runnable
+The task is not blocked for any reason known to Ada. (It may be waiting
+for a mutex, though.) It is conceptually "executing" in normal mode.
+
+@item Terminated
+The task is terminated, in the sense of ARM 9.3 (5). Any dependents
+that were waiting on terminate alternatives have been awakened and have
+terminated themselves.
+
+@item Child Activation Wait
+The task is waiting for created tasks to complete activation.
+
+@item Accept Statement
+The task is waiting on an accept or selective wait statement.
+
+@item Waiting on entry call
+The task is waiting on an entry call.
+
+@item Async Select Wait
+The task is waiting to start the abortable part of an asynchronous
+select statement.
+
+@item Delay Sleep
+The task is waiting on a select statement with only a delay
+alternative open.
+
+@item Child Termination Wait
+The task is sleeping having completed a master within itself, and is
+waiting for the tasks dependent on that master to become terminated or
+waiting on a terminate Phase.
+
+@item Wait Child in Term Alt
+The task is sleeping waiting for tasks on terminate alternatives to
+finish terminating.
+
+@item Accepting RV with @var{taskno}
+The task is accepting a rendez-vous with the task @var{taskno}.
+@end table
+
+@item Name
+Name of the task in the program.
+
+@end table
+
+@kindex info task @var{taskno}
+@item info task @var{taskno}
+This command shows detailled informations on the specified task, as in
+the following example:
+@smallexample
+@iftex
+@leftskip=0.5cm
+@end iftex
+(@value{GDBP}) info tasks
+ ID TID P-ID Pri State Name
+ 1 8077880 0 15 Child Activation Wait main_task
+* 2 807c468 1 15 Running task_1
+(@value{GDBP}) info task 2
+Ada Task: 0x807c468
+Name: task_1
+Thread: 0x807f378
+Parent: 1 (main_task)
+Base Priority: 15
+State: Runnable
+@end smallexample
+
+@item task
+@kindex task@r{ (Ada)}
+@cindex current Ada task ID
+This command prints the ID of the current task.
+
+@smallexample
+@iftex
+@leftskip=0.5cm
+@end iftex
+(@value{GDBP}) info tasks
+ ID TID P-ID Pri State Name
+ 1 8077870 0 15 Child Activation Wait main_task
+* 2 807c458 1 15 Running t
+(@value{GDBP}) task
+[Current task is 2]
+@end smallexample
+
+@item task @var{taskno}
+@cindex Ada task switching
+This command is like the @code{thread @var{threadno}}
+command (@pxref{Threads}). It switches the context of debugging
+from the current task to the given task.
+
+@smallexample
+@iftex
+@leftskip=0.5cm
+@end iftex
+(@value{GDBP}) info tasks
+ ID TID P-ID Pri State Name
+ 1 8077870 0 15 Child Activation Wait main_task
+* 2 807c458 1 15 Running t
+(@value{GDBP}) task 1
+[Switching to task 1]
+#0 0x8067726 in pthread_cond_wait ()
+(@value{GDBP}) bt
+#0 0x8067726 in pthread_cond_wait ()
+#1 0x8056714 in system.os_interface.pthread_cond_wait ()
+#2 0x805cb63 in system.task_primitives.operations.sleep ()
+#3 0x806153e in system.tasking.stages.activate_tasks ()
+#4 0x804aacc in un () at un.adb:5
+@end smallexample
+
+@end table
+
+@node Ada Tasks and Core Files
+@subsubsection Tasking Support when Debugging Core Files
+@cindex Ada tasking and core file debugging
+
+When inspecting a core file, as opposed to debugging a live program,
+tasking support may be limited or even unavailable, depending on
+the platform being used.
+For instance, on x86-linux, the list of tasks is available, but task
+switching is not supported. On Tru64, however, task switching will work
+as usual.
+
+On certain platforms, including Tru64, the debugger needs to perform some
+memory writes in order to provide Ada tasking support. When inspecting
+a core file, this means that the core file must be opened with read-write
+privileges, using the command @samp{"set write on"} (@pxref{Patching}).
+Under these circumstances, you should make a backup copy of the core
+file before inspecting it with @value{GDBN}.
+
@node Ada Glitches
@subsubsection Known Peculiarities of Ada Mode
@cindex Ada, problems
floating-point arithmetic, and may give results that only approximate those on
the host machine.
-@item
-The type of the @t{'Address} attribute may not be @code{System.Address}.
-
@item
The GNAT compiler never generates the prefix @code{Standard} for any of
the standard symbols defined by the Ada language. @value{GDBN} knows about
This is the opposite of the @code{info address} command. You can use
it to find out the name of a variable or a function given its address.
+For dynamically linked executables, the name of executable or shared
+library containing the symbol is also printed:
+
+@smallexample
+(@value{GDBP}) info symbol 0x400225
+_start + 5 in section .text of /tmp/a.out
+(@value{GDBP}) info symbol 0x2aaaac2811cf
+__read_nocancel + 6 in section .text of /usr/lib64/libc.so.6
+@end smallexample
+
@kindex whatis
@item whatis [@var{arg}]
Print the data type of @var{arg}, which can be either an expression or
@item set write on
@itemx set write off
If you specify @samp{set write on}, @value{GDBN} opens executable and
-core files for both reading and writing; if you specify @samp{set write
+core files for both reading and writing; if you specify @kbd{set write
off} (the default), @value{GDBN} opens them read-only.
If you have already loaded a file, you must load it again (using the
@subsubsection Other Command-Line Arguments for @code{gdbserver}
-You can include @option{--debug} on the @code{gdbserver} command line.
-@code{gdbserver} will display extra status information about the debugging
-process. This option is intended for @code{gdbserver} development and
-for bug reports to the developers.
+The @option{--debug} option tells @code{gdbserver} to display extra
+status information about the debugging process. The
+@option{--remote-debug} option tells @code{gdbserver} to display
+remote protocol debug output. These options are intended for
+@code{gdbserver} development and for bug reports to the developers.
The @option{--wrapper} option specifies a wrapper to launch programs
for debugging. The option should be followed by the name of the
extended-remote}. This should be set to a filename valid on the
target system. If it is not set, the target will use a default
filename (e.g.@: the last program run).
+
+@kindex set tcp
+@kindex show tcp
+@item set tcp auto-retry on
+@cindex auto-retry, for remote TCP target
+Enable auto-retry for remote TCP connections. This is useful if the remote
+debugging agent is launched in parallel with @value{GDBN}; there is a race
+condition because the agent may not become ready to accept the connection
+before @value{GDBN} attempts to connect. When auto-retry is
+enabled, if the initial attempt to connect fails, @value{GDBN} reattempts
+to establish the connection using the timeout specified by
+@code{set tcp connect-timeout}.
+
+@item set tcp auto-retry off
+Do not auto-retry failed TCP connections.
+
+@item show tcp auto-retry
+Show the current auto-retry setting.
+
+@item set tcp connect-timeout @var{seconds}
+@cindex connection timeout, for remote TCP target
+@cindex timeout, for remote target connection
+Set the timeout for establishing a TCP connection to the remote target to
+@var{seconds}. The timeout affects both polling to retry failed connections
+(enabled by @code{set tcp auto-retry on}) and waiting for connections
+that are merely slow to complete, and represents an approximate cumulative
+value.
+
+@item show tcp connect-timeout
+Show the current connection timeout setting.
@end table
@cindex remote packets, enabling and disabling
@tab @code{qXfer:spu:write}
@tab @code{info spu}
+@item @code{read-siginfo-object}
+@tab @code{qXfer:siginfo:read}
+@tab @code{print $_siginfo}
+
+@item @code{write-siginfo-object}
+@tab @code{qXfer:siginfo:write}
+@tab @code{set $_siginfo}
+
@item @code{get-thread-local-@*storage-address}
@tab @code{qGetTLSAddr}
@tab Displaying @code{__thread} variables
@item @code{noack-packet}
@tab @code{QStartNoAckMode}
@tab Packet acknowledgment
+
+@item @code{osdata}
+@tab @code{qXfer:osdata:read}
+@tab @code{info os}
@end multitable
@node Remote Stub
* Cygwin Native:: Features specific to the Cygwin port
* Hurd Native:: Features specific to @sc{gnu} Hurd
* Neutrino:: Features specific to QNX Neutrino
+* Darwin:: Features specific to Darwin
@end menu
@node HP-UX
Show the current state of QNX Neutrino messages.
@end table
+@node Darwin
+@subsection Darwin
+@cindex Darwin
+
+@value{GDBN} provides the following commands specific to the Darwin target:
+
+@table @code
+@item set debug darwin @var{num}
+@kindex set debug darwin
+When set to a non zero value, enables debugging messages specific to
+the Darwin support. Higher values produce more verbose output.
+
+@item show debug darwin
+@kindex show debug darwin
+Show the current state of Darwin messages.
+
+@item set debug mach-o @var{num}
+@kindex set debug mach-o
+When set to a non zero value, enables debugging messages while
+@value{GDBN} is reading Darwin object files. (@dfn{Mach-O} is the
+file format used on Darwin for object and executable files.) Higher
+values produce more verbose output. This is a command to diagnose
+problems internal to @value{GDBN} and should not be needed in normal
+usage.
+
+@item show debug mach-o
+@kindex show debug mach-o
+Show the current state of Mach-O file messages.
+
+@item set mach-exceptions on
+@itemx set mach-exceptions off
+@kindex set mach-exceptions
+On Darwin, faults are first reported as a Mach exception and are then
+mapped to a Posix signal. Use this command to turn on trapping of
+Mach exceptions in the inferior. This might be sometimes useful to
+better understand the cause of a fault. The default is off.
+
+@item show mach-exceptions
+@kindex show mach-exceptions
+Show the current state of exceptions trapping.
+@end table
+
@node Embedded OS
@section Embedded Operating Systems
@item define @var{commandname}
Define a command named @var{commandname}. If there is already a command
by that name, you are asked to confirm that you want to redefine it.
+@var{commandname} may be a bare command name consisting of letters,
+numbers, dashes, and underscores. It may also start with any predefined
+prefix command. For example, @samp{define target my-target} creates
+a user-defined @samp{target my-target} command.
The definition of the command is made up of other @value{GDBN} command lines,
which are given following the @code{define} command. The end of these
name, e.g.@: @code{backtrace} rather than @code{bt}.
@c FIXME! So how does Joe User discover whether a command is an alias
@c or not?
+You can hook a multi-word command by adding @code{hook-} or
+@code{hookpost-} to the last word of the command, e.g.@:
+@samp{define target hook-remote} to add a hook to @samp{target remote}.
+
If an error occurs during the execution of your hook, execution of
@value{GDBN} commands stops and @value{GDBN} issues a prompt
(before the command that you actually typed had a chance to run).
* Basic Python:: Basic Python Functions.
* Exception Handling::
* Values From Inferior::
+* Commands In Python:: Implementing new commands in Python.
@end menu
@node Basic Python
use in all scripts evaluated by the @code{python} command.
@findex gdb.execute
-@defun execute command
+@defun execute command [from_tty]
Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
If a GDB exception happens while @var{command} runs, it is
translated as described in @ref{Exception Handling,,Exception Handling}.
If no exceptions occur, this function returns @code{None}.
+
+@var{from_tty} specifies whether @value{GDBN} ought to consider this
+command as having originated from the user invoking it interactively.
+It must be a boolean value. If omitted, it defaults to @code{False}.
@end defun
@findex gdb.get_parameter
a Python value of the appropriate type, and returned.
@end defun
+@findex gdb.history
+@defun history number
+Return a value from @value{GDBN}'s value history (@pxref{Value
+History}). @var{number} indicates which history element to return.
+If @var{number} is negative, then @value{GDBN} will take its absolute value
+and count backward from the last element (i.e., the most recent element) to
+find the value to return. If @var{number} is zero, then @value{GDBN} will
+return the most recent element. If the element specified by @var{number}
+doesn't exist in the value history, a @code{RuntimeError} exception will be
+raised.
+
+If no exception is raised, the return value is always an instance of
+@code{gdb.Value} (@pxref{Values From Inferior}).
+@end defun
+
@findex gdb.write
@defun write string
Print a string to @value{GDBN}'s paginated standard output stream.
value pointed to by @code{foo}.
@end defmethod
+@defmethod Value string @r{[}encoding @r{[}errors@r{]}@r{]}
+If this @code{gdb.Value} represents a string, then this method
+converts the contents to a Python string. Otherwise, this method will
+throw an exception.
+
+Strings are recognized in a language-specific way; whether a given
+@code{gdb.Value} represents a string is determined by the current
+language.
+
+For C-like languages, a value is a string if it is a pointer to or an
+array of characters or ints. The string is assumed to be terminated
+by a zero of the appropriate width.
+
+If the optional @var{encoding} argument is given, it must be a string
+naming the encoding of the string in the @code{gdb.Value}, such as
+@code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. It accepts
+the same encodings as the corresponding argument to Python's
+@code{string.decode} method, and the Python codec machinery will be used
+to convert the string. If @var{encoding} is not given, or if
+@var{encoding} is the empty string, then either the @code{target-charset}
+(@pxref{Character Sets}) will be used, or a language-specific encoding
+will be used, if the current language is able to supply one.
+
+The optional @var{errors} argument is the same as the corresponding
+argument to Python's @code{string.decode} method.
+@end defmethod
+
+@node Commands In Python
+@subsubsection Commands In Python
+
+@cindex commands in python
+@cindex python commands
+@tindex Command
+@tindex gdb.Command
+You can implement new @value{GDBN} CLI commands in Python. A CLI
+command is implemented using an instance of the @code{gdb.Command}
+class, most commonly using a subclass.
+
+@defmethod Command __init__ name @var{command-class} @r{[}@var{completer-class} @var{prefix}@r{]}
+The object initializer for @code{Command} registers the new command
+with @value{GDBN}. This initializer is normally invoked from the
+subclass' own @code{__init__} method.
+
+@var{name} is the name of the command. If @var{name} consists of
+multiple words, then the initial words are looked for as prefix
+commands. In this case, if one of the prefix commands does not exist,
+an exception is raised.
+
+There is no support for multi-line commands.
+
+@var{command-class} should be one of the @samp{COMMAND_} constants
+defined below. This argument tells @value{GDBN} how to categorize the
+new command in the help system.
+
+@var{completer-class} is an optional argument. If given, it should be
+one of the @samp{COMPLETE_} constants defined below. This argument
+tells @value{GDBN} how to perform completion for this command. If not
+given, @value{GDBN} will attempt to complete using the object's
+@code{complete} method (see below); if no such method is found, an
+error will occur when completion is attempted.
+
+@var{prefix} is an optional argument. If @code{True}, then the new
+command is a prefix command; sub-commands of this command may be
+registered.
+
+The help text for the new command is taken from the Python
+documentation string for the command's class, if there is one. If no
+documentation string is provided, the default value ``This command is
+not documented.'' is used.
+@end defmethod
+
+@cindex don't repeat Python command
+@defmethod Command dont_repeat
+By default, a @value{GDBN} command is repeated when the user enters a
+blank line at the command prompt. A command can suppress this
+behavior by invoking the @code{dont_repeat} method. This is similar
+to the user command @code{dont-repeat}, see @ref{Define, dont-repeat}.
+@end defmethod
+
+@defmethod Command invoke argument from_tty
+This method is called by @value{GDBN} when this command is invoked.
+
+@var{argument} is a string. It is the argument to the command, after
+leading and trailing whitespace has been stripped.
+
+@var{from_tty} is a boolean argument. When true, this means that the
+command was entered by the user at the terminal; when false it means
+that the command came from elsewhere.
+
+If this method throws an exception, it is turned into a @value{GDBN}
+@code{error} call. Otherwise, the return value is ignored.
+@end defmethod
+
+@cindex completion of Python commands
+@defmethod Command complete text word
+This method is called by @value{GDBN} when the user attempts
+completion on this command. All forms of completion are handled by
+this method, that is, the @key{TAB} and @key{M-?} key bindings
+(@pxref{Completion}), and the @code{complete} command (@pxref{Help,
+complete}).
+
+The arguments @var{text} and @var{word} are both strings. @var{text}
+holds the complete command line up to the cursor's location.
+@var{word} holds the last word of the command line; this is computed
+using a word-breaking heuristic.
+
+The @code{complete} method can return several values:
+@itemize @bullet
+@item
+If the return value is a sequence, the contents of the sequence are
+used as the completions. It is up to @code{complete} to ensure that the
+contents actually do complete the word. A zero-length sequence is
+allowed, it means that there were no completions available. Only
+string elements of the sequence are used; other elements in the
+sequence are ignored.
+
+@item
+If the return value is one of the @samp{COMPLETE_} constants defined
+below, then the corresponding @value{GDBN}-internal completion
+function is invoked, and its result is used.
+
+@item
+All other results are treated as though there were no available
+completions.
+@end itemize
+@end defmethod
+
+When a new command is registered, it must be declared as a member of
+some general class of commands. This is used to classify top-level
+commands in the on-line help system; note that prefix commands are not
+listed under their own category but rather that of their top-level
+command. The available classifications are represented by constants
+defined in the @code{gdb} module:
+
+@table @code
+@findex COMMAND_NONE
+@findex gdb.COMMAND_NONE
+@item COMMAND_NONE
+The command does not belong to any particular class. A command in
+this category will not be displayed in any of the help categories.
+
+@findex COMMAND_RUNNING
+@findex gdb.COMMAND_RUNNING
+@item COMMAND_RUNNING
+The command is related to running the inferior. For example,
+@code{start}, @code{step}, and @code{continue} are in this category.
+Type @kbd{help running} at the @value{GDBN} prompt to see a list of
+commands in this category.
+
+@findex COMMAND_DATA
+@findex gdb.COMMAND_DATA
+@item COMMAND_DATA
+The command is related to data or variables. For example,
+@code{call}, @code{find}, and @code{print} are in this category. Type
+@kbd{help data} at the @value{GDBN} prompt to see a list of commands
+in this category.
+
+@findex COMMAND_STACK
+@findex gdb.COMMAND_STACK
+@item COMMAND_STACK
+The command has to do with manipulation of the stack. For example,
+@code{backtrace}, @code{frame}, and @code{return} are in this
+category. Type @kbd{help stack} at the @value{GDBN} prompt to see a
+list of commands in this category.
+
+@findex COMMAND_FILES
+@findex gdb.COMMAND_FILES
+@item COMMAND_FILES
+This class is used for file-related commands. For example,
+@code{file}, @code{list} and @code{section} are in this category.
+Type @kbd{help files} at the @value{GDBN} prompt to see a list of
+commands in this category.
+
+@findex COMMAND_SUPPORT
+@findex gdb.COMMAND_SUPPORT
+@item COMMAND_SUPPORT
+This should be used for ``support facilities'', generally meaning
+things that are useful to the user when interacting with @value{GDBN},
+but not related to the state of the inferior. For example,
+@code{help}, @code{make}, and @code{shell} are in this category. Type
+@kbd{help support} at the @value{GDBN} prompt to see a list of
+commands in this category.
+
+@findex COMMAND_STATUS
+@findex gdb.COMMAND_STATUS
+@item COMMAND_STATUS
+The command is an @samp{info}-related command, that is, related to the
+state of @value{GDBN} itself. For example, @code{info}, @code{macro},
+and @code{show} are in this category. Type @kbd{help status} at the
+@value{GDBN} prompt to see a list of commands in this category.
+
+@findex COMMAND_BREAKPOINTS
+@findex gdb.COMMAND_BREAKPOINTS
+@item COMMAND_BREAKPOINTS
+The command has to do with breakpoints. For example, @code{break},
+@code{clear}, and @code{delete} are in this category. Type @kbd{help
+breakpoints} at the @value{GDBN} prompt to see a list of commands in
+this category.
+
+@findex COMMAND_TRACEPOINTS
+@findex gdb.COMMAND_TRACEPOINTS
+@item COMMAND_TRACEPOINTS
+The command has to do with tracepoints. For example, @code{trace},
+@code{actions}, and @code{tfind} are in this category. Type
+@kbd{help tracepoints} at the @value{GDBN} prompt to see a list of
+commands in this category.
+
+@findex COMMAND_OBSCURE
+@findex gdb.COMMAND_OBSCURE
+@item COMMAND_OBSCURE
+The command is only used in unusual circumstances, or is not of
+general interest to users. For example, @code{checkpoint},
+@code{fork}, and @code{stop} are in this category. Type @kbd{help
+obscure} at the @value{GDBN} prompt to see a list of commands in this
+category.
+
+@findex COMMAND_MAINTENANCE
+@findex gdb.COMMAND_MAINTENANCE
+@item COMMAND_MAINTENANCE
+The command is only useful to @value{GDBN} maintainers. The
+@code{maintenance} and @code{flushregs} commands are in this category.
+Type @kbd{help internals} at the @value{GDBN} prompt to see a list of
+commands in this category.
+@end table
+
+A new command can use a predefined completion function, either by
+specifying it via an argument at initialization, or by returning it
+from the @code{complete} method. These predefined completion
+constants are all defined in the @code{gdb} module:
+
+@table @code
+@findex COMPLETE_NONE
+@findex gdb.COMPLETE_NONE
+@item COMPLETE_NONE
+This constant means that no completion should be done.
+
+@findex COMPLETE_FILENAME
+@findex gdb.COMPLETE_FILENAME
+@item COMPLETE_FILENAME
+This constant means that filename completion should be performed.
+
+@findex COMPLETE_LOCATION
+@findex gdb.COMPLETE_LOCATION
+@item COMPLETE_LOCATION
+This constant means that location completion should be done.
+@xref{Specify Location}.
+
+@findex COMPLETE_COMMAND
+@findex gdb.COMPLETE_COMMAND
+@item COMPLETE_COMMAND
+This constant means that completion should examine @value{GDBN}
+command names.
+
+@findex COMPLETE_SYMBOL
+@findex gdb.COMPLETE_SYMBOL
+@item COMPLETE_SYMBOL
+This constant means that completion should be done using symbol names
+as the source.
+@end table
+
+The following code snippet shows how a trivial CLI command can be
+implemented in Python:
+
+@smallexample
+class HelloWorld (gdb.Command):
+ """Greet the whole world."""
+
+ def __init__ (self):
+ super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_OBSCURE)
+
+ def invoke (self, arg, from_tty):
+ print "Hello, World!"
+
+HelloWorld ()
+@end smallexample
+
+The last line instantiates the class, and is necessary to trigger the
+registration of the command with @value{GDBN}. Depending on how the
+Python code is read into @value{GDBN}, you may need to import the
+@code{gdb} module explicitly.
+
@node Interpreters
@chapter Command Interpreters
@cindex command interpreters
@end ignore
@menu
+* GDB/MI General Design::
* GDB/MI Command Syntax::
* GDB/MI Compatibility with CLI::
* GDB/MI Development and Front Ends::
* GDB/MI Miscellaneous Commands::
@end menu
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI General Design
+@section @sc{gdb/mi} General Design
+@cindex GDB/MI General Design
+
+Interaction of a @sc{GDB/MI} frontend with @value{GDBN} involves three
+parts---commands sent to @value{GDBN}, responses to those commands
+and notifications. Each command results in exactly one response,
+indicating either successful completion of the command, or an error.
+For the commands that do not resume the target, the response contains the
+requested information. For the commands that resume the target, the
+response only indicates whether the target was successfully resumed.
+Notifications is the mechanism for reporting changes in the state of the
+target, or in @value{GDBN} state, that cannot conveniently be associated with
+a command and reported as part of that command response.
+
+The important examples of notifications are:
+@itemize @bullet
+
+@item
+Exec notifications. These are used to report changes in
+target state---when a target is resumed, or stopped. It would not
+be feasible to include this information in response of resuming
+commands, because one resume commands can result in multiple events in
+different threads. Also, quite some time may pass before any event
+happens in the target, while a frontend needs to know whether the resuming
+command itself was successfully executed.
+
+@item
+Console output, and status notifications. Console output
+notifications are used to report output of CLI commands, as well as
+diagnostics for other commands. Status notifications are used to
+report the progress of a long-running operation. Naturally, including
+this information in command response would mean no output is produced
+until the command is finished, which is undesirable.
+
+@item
+General notifications. Commands may have various side effects on
+the @value{GDBN} or target state beyond their official purpose. For example,
+a command may change the selected thread. Although such changes can
+be included in command response, using notification allows for more
+orthogonal frontend design.
+
+@end itemize
+
+There's no guarantee that whenever an MI command reports an error,
+@value{GDBN} or the target are in any specific state, and especially,
+the state is not reverted to the state before the MI command was
+processed. Therefore, whenever an MI command results in an error,
+we recommend that the frontend refreshes all the information shown in
+the user interface.
+
+@subsection Context management
+
+In most cases when @value{GDBN} accesses the target, this access is
+done in context of a specific thread and frame (@pxref{Frames}).
+Often, even when accessing global data, the target requires that a thread
+be specified. The CLI interface maintains the selected thread and frame,
+and supplies them to target on each command. This is convenient,
+because a command line user would not want to specify that information
+explicitly on each command, and because user interacts with
+@value{GDBN} via a single terminal, so no confusion is possible as
+to what thread and frame are the current ones.
+
+In the case of MI, the concept of selected thread and frame is less
+useful. First, a frontend can easily remember this information
+itself. Second, a graphical frontend can have more than one window,
+each one used for debugging a different thread, and the frontend might
+want to access additional threads for internal purposes. This
+increases the risk that by relying on implicitly selected thread, the
+frontend may be operating on a wrong one. Therefore, each MI command
+should explicitly specify which thread and frame to operate on. To
+make it possible, each MI command accepts the @samp{--thread} and
+@samp{--frame} options, the value to each is @value{GDBN} identifier
+for thread and frame to operate on.
+
+Usually, each top-level window in a frontend allows the user to select
+a thread and a frame, and remembers the user selection for further
+operations. However, in some cases @value{GDBN} may suggest that the
+current thread be changed. For example, when stopping on a breakpoint
+it is reasonable to switch to the thread where breakpoint is hit. For
+another example, if the user issues the CLI @samp{thread} command via
+the frontend, it is desirable to change the frontend's selected thread to the
+one specified by user. @value{GDBN} communicates the suggestion to
+change current thread using the @samp{=thread-selected} notification.
+No such notification is available for the selected frame at the moment.
+
+Note that historically, MI shares the selected thread with CLI, so
+frontends used the @code{-thread-select} to execute commands in the
+right context. However, getting this to work right is cumbersome. The
+simplest way is for frontend to emit @code{-thread-select} command
+before every command. This doubles the number of commands that need
+to be sent. The alternative approach is to suppress @code{-thread-select}
+if the selected thread in @value{GDBN} is supposed to be identical to the
+thread the frontend wants to operate on. However, getting this
+optimization right can be tricky. In particular, if the frontend
+sends several commands to @value{GDBN}, and one of the commands changes the
+selected thread, then the behaviour of subsequent commands will
+change. So, a frontend should either wait for response from such
+problematic commands, or explicitly add @code{-thread-select} for
+all subsequent commands. No frontend is known to do this exactly
+right, so it is suggested to just always pass the @samp{--thread} and
+@samp{--frame} options.
+
+@subsection Asynchronous command execution and non-stop mode
+
+On some targets, @value{GDBN} is capable of processing MI commands
+even while the target is running. This is called @dfn{asynchronous
+command execution} (@pxref{Background Execution}). The frontend may
+specify a preferrence for asynchronous execution using the
+@code{-gdb-set target-async 1} command, which should be emitted before
+either running the executable or attaching to the target. After the
+frontend has started the executable or attached to the target, it can
+find if asynchronous execution is enabled using the
+@code{-list-target-features} command.
+
+Even if @value{GDBN} can accept a command while target is running,
+many commands that access the target do not work when the target is
+running. Therefore, asynchronous command execution is most useful
+when combined with non-stop mode (@pxref{Non-Stop Mode}). Then,
+it is possible to examine the state of one thread, while other threads
+are running.
+
+When a given thread is running, MI commands that try to access the
+target in the context of that thread may not work, or may work only on
+some targets. In particular, commands that try to operate on thread's
+stack will not work, on any target. Commands that read memory, or
+modify breakpoints, may work or not work, depending on the target. Note
+that even commands that operate on global state, such as @code{print},
+@code{set}, and breakpoint commands, still access the target in the
+context of a specific thread, so frontend should try to find a
+stopped thread and perform the operation on that thread (using the
+@samp{--thread} option).
+
+Which commands will work in the context of a running thread is
+highly target dependent. However, the two commands
+@code{-exec-interrupt}, to stop a thread, and @code{-thread-info},
+to find the state of a thread, will always work.
+
+@subsection Thread groups
+@value{GDBN} may be used to debug several processes at the same time.
+On some platfroms, @value{GDBN} may support debugging of several
+hardware systems, each one having several cores with several different
+processes running on each core. This section describes the MI
+mechanism to support such debugging scenarios.
+
+The key observation is that regardless of the structure of the
+target, MI can have a global list of threads, because most commands that
+accept the @samp{--thread} option do not need to know what process that
+thread belongs to. Therefore, it is not necessary to introduce
+neither additional @samp{--process} option, nor an notion of the
+current process in the MI interface. The only strictly new feature
+that is required is the ability to find how the threads are grouped
+into processes.
+
+To allow the user to discover such grouping, and to support arbitrary
+hierarchy of machines/cores/processes, MI introduces the concept of a
+@dfn{thread group}. Thread group is a collection of threads and other
+thread groups. A thread group always has a string identifier, a type,
+and may have additional attributes specific to the type. A new
+command, @code{-list-thread-groups}, returns the list of top-level
+thread groups, which correspond to processes that @value{GDBN} is
+debugging at the moment. By passing an identifier of a thread group
+to the @code{-list-thread-groups} command, it is possible to obtain
+the members of specific thread group.
+
+To allow the user to easily discover processes, and other objects, he
+wishes to debug, a concept of @dfn{available thread group} is
+introduced. Available thread group is an thread group that
+@value{GDBN} is not debugging, but that can be attached to, using the
+@code{-target-attach} command. The list of available top-level thread
+groups can be obtained using @samp{-list-thread-groups --available}.
+In general, the content of a thread group may be only retrieved only
+after attaching to that thread group.
+
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Command Syntax
@section @sc{gdb/mi} Command Syntax
* GDB/MI Result Records::
* GDB/MI Stream Records::
* GDB/MI Async Records::
+* GDB/MI Frame Information::
@end menu
@node GDB/MI Result Records
all threads together, or even for a single thread, if the thread must
be stepped though some code before letting it run freely.
-@item *stopped,reason="@var{reason}"
+@item *stopped,reason="@var{reason}",thread-id="@var{id}",stopped-threads="@var{stopped}"
The target has stopped. The @var{reason} field can have one of the
following values:
A signal was received by the inferior.
@end table
-@item =thread-created,id="@var{id}"
-@itemx =thread-exited,id="@var{id}"
+The @var{id} field identifies the thread that directly caused the stop
+-- for example by hitting a breakpoint. Depending on whether all-stop
+mode is in effect (@pxref{All-Stop Mode}), @value{GDBN} may either
+stop all threads, or only the thread that directly triggered the stop.
+If all threads are stopped, the @var{stopped} field will have the
+value of @code{"all"}. Otherwise, the value of the @var{stopped}
+field will be a list of thread identifiers. Presently, this list will
+always include a single thread, but frontend should be prepared to see
+several threads in the list.
+
+@item =thread-group-created,id="@var{id}"
+@itemx =thread-group-exited,id="@var{id}"
+A thread thread group either was attached to, or has exited/detached
+from. The @var{id} field contains the @value{GDBN} identifier of the
+thread group.
+
+@item =thread-created,id="@var{id}",group-id="@var{gid}"
+@itemx =thread-exited,id="@var{id}",group-id="@var{gid}"
A thread either was created, or has exited. The @var{id} field
-contains the @value{GDBN} identifier of the thread.
+contains the @value{GDBN} identifier of the thread. The @var{gid}
+field identifies the thread group this thread belongs to.
+
+@item =thread-selected,id="@var{id}"
+Informs that the selected thread was changed as result of the last
+command. This notification is not emitted as result of @code{-thread-select}
+command but is emitted whenever an MI command that is not documented
+to change the selected thread actually changes it. In particular,
+invoking, directly or indirectly (via user-defined command), the CLI
+@code{thread} command, will generate this notification.
+
+We suggest that in response to this notification, front ends
+highlight the selected thread and cause subsequent commands to apply to
+that thread.
+
+@item =library-loaded,...
+Reports that a new library file was loaded by the program. This
+notification has 4 fields---@var{id}, @var{target-name},
+@var{host-name}, and @var{symbols-loaded}. The @var{id} field is an
+opaque identifier of the library. For remote debugging case,
+@var{target-name} and @var{host-name} fields give the name of the
+library file on the target, and on the host respectively. For native
+debugging, both those fields have the same value. The
+@var{symbols-loaded} field reports if the debug symbols for this
+library are loaded.
+
+@item =library-unloaded,...
+Reports that a library was unloaded by the program. This notification
+has 3 fields---@var{id}, @var{target-name} and @var{host-name} with
+the same meaning as for the @code{=library-loaded} notification
+
@end table
+@node GDB/MI Frame Information
+@subsection @sc{gdb/mi} Frame Information
+
+Response from many MI commands includes an information about stack
+frame. This information is a tuple that may have the following
+fields:
+
+@table @code
+@item level
+The level of the stack frame. The innermost frame has the level of
+zero. This field is always present.
+
+@item func
+The name of the function corresponding to the frame. This field may
+be absent if @value{GDBN} is unable to determine the function name.
+
+@item addr
+The code address for the frame. This field is always present.
+
+@item file
+The name of the source files that correspond to the frame's code
+address. This field may be absent.
+
+@item line
+The source line corresponding to the frames' code address. This field
+may be absent.
+
+@item from
+The name of the binary file (either executable or shared library) the
+corresponds to the frame's code address. This field may be absent.
+
+@end table
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@subsubheading Synopsis
@smallexample
- -break-insert [ -t ] [ -h ] [ -f ]
+ -break-insert [ -t ] [ -h ] [ -f ] [ -d ]
[ -c @var{condition} ] [ -i @var{ignore-count} ]
[ -p @var{thread} ] [ @var{location} ]
@end smallexample
breakpoint. Without this flag, @value{GDBN} will report
an error, and won't create a breakpoint, if @var{location}
cannot be parsed.
+@item -d
+Create a disabled breakpoint.
@end table
@subsubheading Result
-thread-info
^done,threads=[
@{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)",
- frame=@{level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]@},
+ frame=@{level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]@},state="running"@},
@{id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",
frame=@{level="0",addr="0x0804891f",func="foo",args=[@{name="i",value="10"@}],
- file="/tmp/a.c",fullname="/tmp/a.c",line="158"@}@}],
+ file="/tmp/a.c",fullname="/tmp/a.c",line="158"@},state="running"@}],
current-thread-id="1"
(gdb)
@end smallexample
+The @samp{state} field may have the following values:
+
+@table @code
+@item stopped
+The thread is stopped. Frame information is available for stopped
+threads.
+
+@item running
+The thread is running. There's no frame information for running
+threads.
+
+@end table
+
@subheading The @code{-thread-list-ids} Command
@findex -thread-list-ids
Produces a list of the currently known @value{GDBN} thread ids. At the
end of the list it also prints the total number of such threads.
+This command is retained for historical reasons, the
+@code{-thread-info} command should be used instead.
+
@subsubheading @value{GDBN} Command
Part of @samp{info threads} supplies the same information.
@subsubheading Example
-No threads present, besides the main process:
-
-@smallexample
-(gdb)
--thread-list-ids
-^done,thread-ids=@{@},number-of-threads="0"
-(gdb)
-@end smallexample
-
-
-Several threads:
-
@smallexample
(gdb)
-thread-list-ids
^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
-number-of-threads="3"
+current-thread-id="1",number-of-threads="3"
(gdb)
@end smallexample
Make @var{threadnum} the current thread. It prints the number of the new
current thread, and the topmost frame for that thread.
+This command is deprecated in favor of explicitly using the
+@samp{--thread} option to each command.
+
@subsubheading @value{GDBN} Command
The corresponding @value{GDBN} command is @samp{thread}.
@subsubheading Synopsis
@smallexample
- -exec-continue
+ -exec-continue [--all|--thread-group N]
@end smallexample
Resumes the execution of the inferior program until a breakpoint is
-encountered, or until the inferior exits.
+encountered, or until the inferior exits. In all-stop mode
+(@pxref{All-Stop Mode}), may resume only one thread, or all threads,
+depending on the value of the @samp{scheduler-locking} variable. In
+non-stop mode (@pxref{Non-Stop Mode}), if the @samp{--all} is not
+specified, only the thread specified with the @samp{--thread} option
+(or current thread, if no @samp{--thread} is provided) is resumed. If
+@samp{--all} is specified, all threads will be resumed. The
+@samp{--all} option is ignored in all-stop mode. If the
+@samp{--thread-group} options is specified, then all threads in that
+thread group are resumed.
@subsubheading @value{GDBN} Command
@subsubheading Synopsis
@smallexample
- -exec-interrupt
+ -exec-interrupt [--all|--thread-group N]
@end smallexample
Interrupts the background execution of the target. Note how the token
appears in the @samp{^done} output. If the user is trying to
interrupt a non-running program, an error message will be printed.
+Note that when asynchronous execution is enabled, this command is
+asynchronous just like other execution commands. That is, first the
+@samp{^done} response will be printed, and the target stop will be
+reported after that using the @samp{*stopped} notification.
+
+In non-stop mode, only the context thread is interrupted by default.
+All threads will be interrupted if the @samp{--all} option is
+specified. If the @samp{--thread-group} option is specified, all
+threads in that group will be interrupted.
+
@subsubheading @value{GDBN} Command
The corresponding @value{GDBN} command is @samp{interrupt}.
Change the selected frame. Select a different frame @var{framenum} on
the stack.
+This command in deprecated in favor of passing the @samp{--frame}
+option to every command.
+
@subsubheading @value{GDBN} Command
The corresponding @value{GDBN} commands are @samp{frame}, @samp{up},
called ``frozen variable objects''. Such variable objects are never
implicitly updated.
+Variable objects can be either @dfn{fixed} or @dfn{floating}. For the
+fixed variable object, the expression is parsed when the variable
+object is created, including associating identifiers to specific
+variables. The meaning of expression never changes. For a floating
+variable object the values of variables whose names appear in the
+expressions are re-evaluated every time in the context of the current
+frame. Consider this example:
+
+@smallexample
+void do_work(...)
+@{
+ struct work_state state;
+
+ if (...)
+ do_work(...);
+@}
+@end smallexample
+
+If a fixed variable object for the @code{state} variable is created in
+this function, and we enter the recursive call, the the variable
+object will report the value of @code{state} in the top-level
+@code{do_work} invocation. On the other hand, a floating variable
+object will report the value of @code{state} in the current frame.
+
+If an expression specified when creating a fixed variable object
+refers to a local variable, the variable object becomes bound to the
+thread and frame in which the variable object is created. When such
+variable object is updated, @value{GDBN} makes sure that the
+thread/frame combination the variable object is bound to still exists,
+and re-evaluates the variable object in context of that thread/frame.
+
The following is the complete set of @sc{gdb/mi} operations defined to
access this functionality:
@smallexample
-var-create @{@var{name} | "-"@}
- @{@var{frame-addr} | "*"@} @var{expression}
+ @{@var{frame-addr} | "*" | "@@"@} @var{expression}
@end smallexample
This operation creates a variable object, which allows the monitoring of
The @var{name} parameter is the string by which the object can be
referenced. It must be unique. If @samp{-} is specified, the varobj
system will generate a string ``varNNNNNN'' automatically. It will be
-unique provided that one does not specify @var{name} on that format.
+unique provided that one does not specify @var{name} of that format.
The command fails if a duplicate name is found.
The frame under which the expression should be evaluated can be
specified by @var{frame-addr}. A @samp{*} indicates that the current
-frame should be used.
+frame should be used. A @samp{@@} indicates that a floating variable
+object must be created.
@var{expression} is any expression valid on the current language set (must not
begin with a @samp{*}), or one of the following:
This operation returns the name, number of children and the type of the
object created. Type is returned as a string as the ones generated by
-the @value{GDBN} CLI:
+the @value{GDBN} CLI. If a fixed variable object is bound to a
+specific thread, the thread is is also printed:
@smallexample
- name="@var{name}",numchild="N",type="@var{type}"
+ name="@var{name}",numchild="@var{N}",type="@var{type}",thread-id="@var{M}"
@end smallexample
recommended to use the @samp{--all-values} option, to reduce the
number of MI commands needed on each program stop.
+With the @samp{*} parameter, if a variable object is bound to a
+currently running thread, it will not be updated, without any
+diagnostic.
@subsubheading Example
@subsubheading Synopsis
@smallexample
- -target-attach @var{pid} | @var{file}
+ -target-attach @var{pid} | @var{gid} | @var{file}
@end smallexample
-Attach to a process @var{pid} or a file @var{file} outside of @value{GDBN}.
+Attach to a process @var{pid} or a file @var{file} outside of
+@value{GDBN}, or a thread group @var{gid}. If attaching to a thread
+group, the id previously returned by
+@samp{-list-thread-groups --available} must be used.
@subsubheading @value{GDBN} Command
@subsubheading Synopsis
@smallexample
- -target-detach
+ -target-detach [ @var{pid} | @var{gid} ]
@end smallexample
Detach from the remote target which normally resumes its execution.
-There's no output.
+If either @var{pid} or @var{gid} is specified, detaches from either
+the specified process, or specified thread group. There's no output.
@subsubheading @value{GDBN} Command
@end table
+@subheading The @code{-list-thread-groups} Command
+@findex -list-thread-groups
+
+@subheading Synopsis
+
+@smallexample
+-list-thread-groups [ --available ] [ @var{group} ]
+@end smallexample
+
+When used without the @var{group} parameter, lists top-level thread
+groups that are being debugged. When used with the @var{group}
+parameter, the children of the specified group are listed. The
+children can be either threads, or other groups. At present,
+@value{GDBN} will not report both threads and groups as children at
+the same time, but it may change in future.
+
+With the @samp{--available} option, instead of reporting groups that
+are been debugged, GDB will report all thread groups available on the
+target. Using the @samp{--available} option together with @var{group}
+is not allowed.
+
+@subheading Example
+
+@smallexample
+@value{GDBP}
+-list-thread-groups
+^done,groups=[@{id="17",type="process",pid="yyy",num_children="2"@}]
+-list-thread-groups 17
+^done,threads=[@{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)",
+ frame=@{level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]@},state="running"@},
+@{id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",
+ frame=@{level="0",addr="0x0804891f",func="foo",args=[@{name="i",value="10"@}],
+ file="/tmp/a.c",fullname="/tmp/a.c",line="158"@},state="running"@}]]
+@end smallexample
@subheading The @code{-interpreter-exec} Command
@findex -interpreter-exec
* Separate Objdir:: Compiling @value{GDBN} in another directory
* Config Names:: Specifying names for hosts and targets
* Configure Options:: Summary of options for configure
+* System-wide configuration:: Having a system-wide init file
@end menu
@node Requirements
There are many other options available as well, but they are generally
needed for special purposes only.
+@node System-wide configuration
+@section System-wide configuration and settings
+@cindex system-wide init file
+
+@value{GDBN} can be configured to have a system-wide init file;
+this file will be read and executed at startup (@pxref{Startup, , What
+@value{GDBN} does during startup}).
+
+Here is the corresponding configure option:
+
+@table @code
+@item --with-system-gdbinit=@var{file}
+Specify that the default location of the system-wide init file is
+@var{file}.
+@end table
+
+If @value{GDBN} has been configured with the option @option{--prefix=$prefix},
+it may be subject to relocation. Two possible cases:
+
+@itemize @bullet
+@item
+If the default location of this init file contains @file{$prefix},
+it will be subject to relocation. Suppose that the configure options
+are @option{--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit};
+if @value{GDBN} is moved from @file{$prefix} to @file{$install}, the system
+init file is looked for as @file{$install/etc/gdbinit} instead of
+@file{$prefix/etc/gdbinit}.
+
+@item
+By contrast, if the default location does not contain the prefix,
+it will not be relocated. E.g.@: if @value{GDBN} has been configured with
+@option{--prefix=/usr/local --with-system-gdbinit=/usr/share/gdb/gdbinit},
+then @value{GDBN} will always look for @file{/usr/share/gdb/gdbinit},
+wherever @value{GDBN} is installed.
+@end itemize
+
@node Maintenance Commands
@appendix Maintenance Commands
@cindex maintenance commands
@end table
-@kindex maint set can-use-displaced-stepping
-@kindex maint show can-use-displaced-stepping
+@kindex set displaced-stepping
+@kindex show displaced-stepping
@cindex displaced stepping support
@cindex out-of-line single-stepping
-@item maint set can-use-displaced-stepping
-@itemx maint show can-use-displaced-stepping
+@item set displaced-stepping
+@itemx show displaced-stepping
Control whether or not @value{GDBN} will do @dfn{displaced stepping}
-if the target supports it. The default is on. Displaced stepping is
-a way to single-step over breakpoints without removing them from the
-inferior, by executing an out-of-line copy of the instruction that was
-originally at the breakpoint location. It is also known as
-out-of-line single-stepping.
+if the target supports it. Displaced stepping is a way to single-step
+over breakpoints without removing them from the inferior, by executing
+an out-of-line copy of the instruction that was originally at the
+breakpoint location. It is also known as out-of-line single-stepping.
+
+@table @code
+@item set displaced-stepping on
+If the target architecture supports it, @value{GDBN} will use
+displaced stepping to step over breakpoints.
+
+@item set displaced-stepping off
+@value{GDBN} will not use displaced stepping to step over breakpoints,
+even if such is supported by the target architecture.
+
+@cindex non-stop mode, and @samp{set displaced-stepping}
+@item set displaced-stepping auto
+This is the default mode. @value{GDBN} will use displaced stepping
+only if non-stop mode is active (@pxref{Non-Stop Mode}) and the target
+architecture supports displaced stepping.
+@end table
@kindex maint check-symtabs
@item maint check-symtabs
(@value{GDBP})
@end smallexample
+@cindex @value{GDBN} internal error
+@cindex internal errors, control of @value{GDBN} behavior
+
+@kindex maint set internal-error
+@kindex maint show internal-error
+@kindex maint set internal-warning
+@kindex maint show internal-warning
+@item maint set internal-error @var{action} [ask|yes|no]
+@itemx maint show internal-error @var{action}
+@itemx maint set internal-warning @var{action} [ask|yes|no]
+@itemx maint show internal-warning @var{action}
+When @value{GDBN} reports an internal problem (error or warning) it
+gives the user the opportunity to both quit @value{GDBN} and create a
+core file of the current @value{GDBN} session. These commands let you
+override the default behaviour for each particular @var{action},
+described in the table below.
+
+@table @samp
+@item quit
+You can specify that @value{GDBN} should always (yes) or never (no)
+quit. The default is to ask the user what to do.
+
+@item corefile
+You can specify that @value{GDBN} should always (yes) or never (no)
+create a core file. The default is to ask the user what to do.
+@end table
+
@kindex maint packet
@item maint packet @var{text}
If @value{GDBN} is talking to an inferior via the serial protocol,
the @code{info address} command (@pxref{Symbols}), except that this
command also allows to find symbols in other sections.
+If section was not specified, the section in which the symbol was found
+is also printed. For dynamically linked executables, the name of
+executable or shared library containing the symbol is printed as well.
+
@end table
The following command is useful for non-interactive invocations of
* Tracepoint Packets::
* Host I/O Packets::
* Interrupts::
+* Notification Packets::
+* Remote Non-Stop::
* Packet Acknowledgment::
* Examples::
* File-I/O Remote Protocol Extension::
@cindex protocol, @value{GDBN} remote serial
@cindex serial protocol, @value{GDBN} remote
@cindex remote serial protocol
-All @value{GDBN} commands and responses (other than acknowledgments) are
-sent as a @var{packet}. A @var{packet} is introduced with the character
+All @value{GDBN} commands and responses (other than acknowledgments
+and notifications, see @ref{Notification Packets}) are sent as a
+@var{packet}. A @var{packet} is introduced with the character
@samp{$}, the actual @var{packet-data}, and the terminating character
@samp{#} followed by a two-digit @var{checksum}:
The host (@value{GDBN}) sends @var{command}s, and the target (the
debugging stub incorporated in your program) sends a @var{response}. In
the case of step and continue @var{command}s, the response is only sent
-when the operation has completed (the target has again stopped).
+when the operation has completed, and the target has again stopped all
+threads in all attached processes. This is the default all-stop mode
+behavior, but the remote protocol also supports @value{GDBN}'s non-stop
+execution mode; see @ref{Remote Non-Stop}, for details.
@var{packet-data} consists of a sequence of characters with the
exception of @samp{#} and @samp{$} (see @samp{X} packet for additional
@item ?
@cindex @samp{?} packet
Indicate the reason the target halted. The reply is the same as for
-step and continue.
+step and continue. This packet has a special interpretation when the
+target is in non-stop mode; see @ref{Remote Non-Stop}.
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
@item vAttach;@var{pid}
@cindex @samp{vAttach} packet
-Attach to a new process with the specified process ID. @var{pid} is a
-hexadecimal integer identifying the process. The attached process is
-stopped.
+Attach to a new process with the specified process ID @var{pid}.
+The process ID is a
+hexadecimal integer identifying the process. In all-stop mode, all
+threads in the attached process are stopped; in non-stop mode, it may be
+attached without being stopped if that is supported by the target.
+
+@c In non-stop mode, on a successful vAttach, the stub should set the
+@c current thread to a thread of the newly-attached process. After
+@c attaching, GDB queries for the attached process's thread ID with qC.
+@c Also note that, from a user perspective, whether or not the
+@c target is stopped on attach in non-stop mode depends on whether you
+@c use the foreground or background version of the attach command, not
+@c on what vAttach does; GDB does the right thing with respect to either
+@c stopping or restarting threads.
This packet is only available in extended mode (@pxref{extended mode}).
@item E @var{nn}
for an error
@item @r{Any stop packet}
-for success (@pxref{Stop Reply Packets})
+for success in all-stop mode (@pxref{Stop Reply Packets})
+@item OK
+for success in non-stop mode (@pxref{Remote Non-Stop})
@end table
@item vCont@r{[};@var{action}@r{[}:@var{thread-id}@r{]]}@dots{}
Resume the inferior, specifying different actions for each thread.
If an action is specified with no @var{thread-id}, then it is applied to any
threads that don't have a specific action specified; if no default action is
-specified then other threads should remain stopped. Specifying multiple
+specified then other threads should remain stopped in all-stop mode and
+in their current state in non-stop mode.
+Specifying multiple
default actions is an error; specifying no actions is also an error.
Thread IDs are specified using the syntax described in @ref{thread-id syntax}.
@item c
Continue.
@item C @var{sig}
-Continue with signal @var{sig}. @var{sig} should be two hex digits.
+Continue with signal @var{sig}. The signal @var{sig} should be two hex digits.
@item s
Step.
@item S @var{sig}
-Step with signal @var{sig}. @var{sig} should be two hex digits.
+Step with signal @var{sig}. The signal @var{sig} should be two hex digits.
+@item t
+Stop.
+@item T @var{sig}
+Stop with signal @var{sig}. The signal @var{sig} should be two hex digits.
@end table
-The optional @var{addr} argument normally associated with these packets is
+The optional argument @var{addr} normally associated with the
+@samp{c}, @samp{C}, @samp{s}, and @samp{S} packets is
not supported in @samp{vCont}.
+The @samp{t} and @samp{T} actions are only relevant in non-stop mode
+(@pxref{Remote Non-Stop}) and may be ignored by the stub otherwise.
+A stop reply should be generated for any affected thread not already stopped.
+When a thread is stopped by means of a @samp{t} action,
+the corresponding stop reply should indicate that the thread has stopped with
+signal @samp{0}, regardless of whether the target uses some other signal
+as an implementation detail.
+
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
(e.g.@: the last program run). The program is created in the stopped
state.
+@c FIXME: What about non-stop mode?
+
This packet is only available in extended mode (@pxref{extended mode}).
Reply:
for success (@pxref{Stop Reply Packets})
@end table
+@item vStopped
+@anchor{vStopped packet}
+@cindex @samp{vStopped} packet
+
+In non-stop mode (@pxref{Remote Non-Stop}), acknowledge a previous stop
+reply and prompt for the stub to report another one.
+
+Reply:
+@table @samp
+@item @r{Any stop packet}
+if there is another unreported stop event (@pxref{Stop Reply Packets})
+@item OK
+if there are no unreported stop events
+@end table
+
@item X @var{addr},@var{length}:@var{XX@dots{}}
@anchor{X packet}
@cindex @samp{X} packet
@section Stop Reply Packets
@cindex stop reply packets
-The @samp{C}, @samp{c}, @samp{S}, @samp{s} and @samp{?} packets can
-receive any of the below as a reply. In the case of the @samp{C},
-@samp{c}, @samp{S} and @samp{s} packets, that reply is only returned
+The @samp{C}, @samp{c}, @samp{S}, @samp{s}, @samp{vCont},
+@samp{vAttach}, @samp{vRun}, @samp{vStopped}, and @samp{?} packets can
+receive any of the below as a reply. Except for @samp{?}
+and @samp{vStopped}, that reply is only returned
when the target halts. In the below the exact meaning of @dfn{signal
number} is defined by the header @file{include/gdb/signals.h} in the
@value{GDBN} source code.
@samp{@var{XX}@dots{}} is hex encoding of @sc{ascii} data, to be
written as the program's console output. This can happen at any time
while the program is running and the debugger should continue to wait
-for @samp{W}, @samp{T}, etc.
+for @samp{W}, @samp{T}, etc. This reply is not permitted in non-stop mode.
@item F @var{call-id},@var{parameter}@dots{}
@var{call-id} is the identifier which says which host system call should
Reply: see @code{remote.c:remote_unpack_thread_info_response()}.
+@item QNonStop:1
+@item QNonStop:0
+@cindex non-stop mode, remote request
+@cindex @samp{QNonStop} packet
+@anchor{QNonStop}
+Enter non-stop (@samp{QNonStop:1}) or all-stop (@samp{QNonStop:0}) mode.
+@xref{Remote Non-Stop}, for more information.
+
+Reply:
+@table @samp
+@item OK
+The request succeeded.
+
+@item E @var{nn}
+An error occurred. @var{nn} are hex digits.
+
+@item
+An empty reply indicates that @samp{QNonStop} is not supported by
+the stub.
+@end table
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+Use of this packet is controlled by the @code{set non-stop} command;
+@pxref{Non-Stop Mode}.
+
@item QPassSignals: @var{signal} @r{[};@var{signal}@r{]}@dots{}
@cindex pass signals to inferior, remote request
@cindex @samp{QPassSignals} packet
@tab @samp{-}
@tab Yes
+@item @samp{qXfer:siginfo:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
+@item @samp{qXfer:siginfo:write}
+@tab No
+@tab @samp{-}
+@tab Yes
+
+@item @samp{QNonStop}
+@tab No
+@tab @samp{-}
+@tab Yes
+
@item @samp{QPassSignals}
@tab No
@tab @samp{-}
The remote stub understands the @samp{qXfer:spu:write} packet
(@pxref{qXfer spu write}).
+@item qXfer:siginfo:read
+The remote stub understands the @samp{qXfer:siginfo:read} packet
+(@pxref{qXfer siginfo read}).
+
+@item qXfer:siginfo:write
+The remote stub understands the @samp{qXfer:siginfo:write} packet
+(@pxref{qXfer siginfo write}).
+
+@item QNonStop
+The remote stub understands the @samp{QNonStop} packet
+(@pxref{QNonStop}).
+
@item QPassSignals
The remote stub understands the @samp{QPassSignals} packet
(@pxref{QPassSignals}).
multiprocess extensions in packet replies unless @value{GDBN} has also
indicated it supports them in its @samp{qSupported} request.
+@item qXfer:osdata:read
+The remote stub understands the @samp{qXfer:osdata:read} packet
+((@pxref{qXfer osdata read}).
+
@end table
@item qSymbol::
This packet is not probed by default; the remote stub must request it,
by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+@item qXfer:siginfo:read::@var{offset},@var{length}
+@anchor{qXfer siginfo read}
+Read contents of the extra signal information on the target
+system. The annex part of the generic @samp{qXfer} packet must be
+empty (@pxref{qXfer read}).
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response
+(@pxref{qSupported}).
+
@item qXfer:spu:read:@var{annex}:@var{offset},@var{length}
@anchor{qXfer spu read}
Read contents of an @code{spufs} file on the target system. The
in that context to be accessed.
This packet is not probed by default; the remote stub must request it,
-by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+by supplying an appropriate @samp{qSupported} response
+(@pxref{qSupported}).
+
+@item qXfer:osdata:read::@var{offset},@var{length}
+@anchor{qXfer osdata read}
+Access the target's @dfn{operating system information}.
+@xref{Operating System Information}.
+
@end table
Reply:
@item qXfer:@var{object}:write:@var{annex}:@var{offset}:@var{data}@dots{}
@cindex write data into object, remote request
+@anchor{qXfer write}
Write uninterpreted bytes into the target's special data area
identified by the keyword @var{object}, starting at @var{offset} bytes
into the data. @var{data}@dots{} is the binary-encoded data
formats, listed below.
@table @samp
-@item qXfer:@var{spu}:write:@var{annex}:@var{offset}:@var{data}@dots{}
+@item qXfer:siginfo:write::@var{offset}:@var{data}@dots{}
+@anchor{qXfer siginfo write}
+Write @var{data} to the extra signal information on the target system.
+The annex part of the generic @samp{qXfer} packet must be
+empty (@pxref{qXfer write}).
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response
+(@pxref{qSupported}).
+
+@item qXfer:spu:write:@var{annex}:@var{offset}:@var{data}@dots{}
@anchor{qXfer spu write}
Write @var{data} to an @code{spufs} file on the target system. The
annex specifies which file to write; it must be of the form
Stubs are not required to recognize these interrupt mechanisms and the
precise meaning associated with receipt of the interrupt is
-implementation defined. If the stub is successful at interrupting the
-running program, it is expected that it will send one of the Stop
-Reply Packets (@pxref{Stop Reply Packets}) to @value{GDBN} as a result
-of successfully stopping the program. Interrupts received while the
-program is stopped will be discarded.
+implementation defined. If the target supports debugging of multiple
+threads and/or processes, it should attempt to interrupt all
+currently-executing threads and processes.
+If the stub is successful at interrupting the
+running program, it should send one of the stop
+reply packets (@pxref{Stop Reply Packets}) to @value{GDBN} as a result
+of successfully stopping the program in all-stop mode, and a stop reply
+for each stopped thread in non-stop mode.
+Interrupts received while the
+program is stopped are discarded.
+
+@node Notification Packets
+@section Notification Packets
+@cindex notification packets
+@cindex packets, notification
+
+The @value{GDBN} remote serial protocol includes @dfn{notifications},
+packets that require no acknowledgment. Both the GDB and the stub
+may send notifications (although the only notifications defined at
+present are sent by the stub). Notifications carry information
+without incurring the round-trip latency of an acknowledgment, and so
+are useful for low-impact communications where occasional packet loss
+is not a problem.
+
+A notification packet has the form @samp{% @var{data} #
+@var{checksum}}, where @var{data} is the content of the notification,
+and @var{checksum} is a checksum of @var{data}, computed and formatted
+as for ordinary @value{GDBN} packets. A notification's @var{data}
+never contains @samp{$}, @samp{%} or @samp{#} characters. Upon
+receiving a notification, the recipient sends no @samp{+} or @samp{-}
+to acknowledge the notification's receipt or to report its corruption.
+
+Every notification's @var{data} begins with a name, which contains no
+colon characters, followed by a colon character.
+
+Recipients should silently ignore corrupted notifications and
+notifications they do not understand. Recipients should restart
+timeout periods on receipt of a well-formed notification, whether or
+not they understand it.
+
+Senders should only send the notifications described here when this
+protocol description specifies that they are permitted. In the
+future, we may extend the protocol to permit existing notifications in
+new contexts; this rule helps older senders avoid confusing newer
+recipients.
+
+(Older versions of @value{GDBN} ignore bytes received until they see
+the @samp{$} byte that begins an ordinary packet, so new stubs may
+transmit notifications without fear of confusing older clients. There
+are no notifications defined for @value{GDBN} to send at the moment, but we
+assume that most older stubs would ignore them, as well.)
+
+The following notification packets from the stub to @value{GDBN} are
+defined:
+
+@table @samp
+@item Stop: @var{reply}
+Report an asynchronous stop event in non-stop mode.
+The @var{reply} has the form of a stop reply, as
+described in @ref{Stop Reply Packets}. Refer to @ref{Remote Non-Stop},
+for information on how these notifications are acknowledged by
+@value{GDBN}.
+@end table
+
+@node Remote Non-Stop
+@section Remote Protocol Support for Non-Stop Mode
+
+@value{GDBN}'s remote protocol supports non-stop debugging of
+multi-threaded programs, as described in @ref{Non-Stop Mode}. If the stub
+supports non-stop mode, it should report that to @value{GDBN} by including
+@samp{QNonStop+} in its @samp{qSupported} response (@pxref{qSupported}).
+
+@value{GDBN} typically sends a @samp{QNonStop} packet only when
+establishing a new connection with the stub. Entering non-stop mode
+does not alter the state of any currently-running threads, but targets
+must stop all threads in any already-attached processes when entering
+all-stop mode. @value{GDBN} uses the @samp{?} packet as necessary to
+probe the target state after a mode change.
+
+In non-stop mode, when an attached process encounters an event that
+would otherwise be reported with a stop reply, it uses the
+asynchronous notification mechanism (@pxref{Notification Packets}) to
+inform @value{GDBN}. In contrast to all-stop mode, where all threads
+in all processes are stopped when a stop reply is sent, in non-stop
+mode only the thread reporting the stop event is stopped. That is,
+when reporting a @samp{S} or @samp{T} response to indicate completion
+of a step operation, hitting a breakpoint, or a fault, only the
+affected thread is stopped; any other still-running threads continue
+to run. When reporting a @samp{W} or @samp{X} response, all running
+threads belonging to other attached processes continue to run.
+
+Only one stop reply notification at a time may be pending; if
+additional stop events occur before @value{GDBN} has acknowledged the
+previous notification, they must be queued by the stub for later
+synchronous transmission in response to @samp{vStopped} packets from
+@value{GDBN}. Because the notification mechanism is unreliable,
+the stub is permitted to resend a stop reply notification
+if it believes @value{GDBN} may not have received it. @value{GDBN}
+ignores additional stop reply notifications received before it has
+finished processing a previous notification and the stub has completed
+sending any queued stop events.
+
+Otherwise, @value{GDBN} must be prepared to receive a stop reply
+notification at any time. Specifically, they may appear when
+@value{GDBN} is not otherwise reading input from the stub, or when
+@value{GDBN} is expecting to read a normal synchronous response or a
+@samp{+}/@samp{-} acknowledgment to a packet it has sent.
+Notification packets are distinct from any other communication from
+the stub so there is no ambiguity.
+
+After receiving a stop reply notification, @value{GDBN} shall
+acknowledge it by sending a @samp{vStopped} packet (@pxref{vStopped packet})
+as a regular, synchronous request to the stub. Such acknowledgment
+is not required to happen immediately, as @value{GDBN} is permitted to
+send other, unrelated packets to the stub first, which the stub should
+process normally.
+
+Upon receiving a @samp{vStopped} packet, if the stub has other queued
+stop events to report to @value{GDBN}, it shall respond by sending a
+normal stop reply response. @value{GDBN} shall then send another
+@samp{vStopped} packet to solicit further responses; again, it is
+permitted to send other, unrelated packets as well which the stub
+should process normally.
+
+If the stub receives a @samp{vStopped} packet and there are no
+additional stop events to report, the stub shall return an @samp{OK}
+response. At this point, if further stop events occur, the stub shall
+send a new stop reply notification, @value{GDBN} shall accept the
+notification, and the process shall be repeated.
+
+In non-stop mode, the target shall respond to the @samp{?} packet as
+follows. First, any incomplete stop reply notification/@samp{vStopped}
+sequence in progress is abandoned. The target must begin a new
+sequence reporting stop events for all stopped threads, whether or not
+it has previously reported those events to @value{GDBN}. The first
+stop reply is sent as a synchronous reply to the @samp{?} packet, and
+subsequent stop replies are sent as responses to @samp{vStopped} packets
+using the mechanism described above. The target must not send
+asynchronous stop reply notifications until the sequence is complete.
+If all threads are running when the target receives the @samp{?} packet,
+or if the target is not attached to any process, it shall respond
+@samp{OK}.
@node Packet Acknowledgment
@section Packet Acknowledgment
there is also no protocol request to re-enable the acknowledgments
for the current connection, once disabled.
-
@node Examples
@section Examples
named pipes, sockets or any other communication method on the host
system are not supported by this protocol.
+File I/O is not supported in non-stop mode.
+
@node Protocol Basics
@subsection Protocol Basics
@cindex protocol basics, file-i/o
@itemx @samp{org.gnu.gdb.coldfire.core}
@itemx @samp{org.gnu.gdb.fido.core}
One of those features must be always present.
-The feature that is present determines which flavor of m86k is
+The feature that is present determines which flavor of m68k is
used. The feature that is present should contain registers
@samp{d0} through @samp{d7}, @samp{a0} through @samp{a5}, @samp{fp},
@samp{sp}, @samp{ps} and @samp{pc}.
these to present registers @samp{ev0} through @samp{ev31} to the
user.
+@node Operating System Information
+@appendix Operating System Information
+@cindex operating system information
+
+@menu
+* Process list::
+@end menu
+
+Users of @value{GDBN} often wish to obtain information about the state of
+the operating system running on the target---for example the list of
+processes, or the list of open files. This section describes the
+mechanism that makes it possible. This mechanism is similar to the
+target features mechanism (@pxref{Target Descriptions}), but focuses
+on a different aspect of target.
+
+Operating system information is retrived from the target via the
+remote protocol, using @samp{qXfer} requests (@pxref{qXfer osdata
+read}). The object name in the request should be @samp{osdata}, and
+the @var{annex} identifies the data to be fetched.
+
+@node Process list
+@appendixsection Process list
+@cindex operating system information, process list
+
+When requesting the process list, the @var{annex} field in the
+@samp{qXfer} request should be @samp{processes}. The returned data is
+an XML document. The formal syntax of this document is defined in
+@file{gdb/features/osdata.dtd}.
+
+An example document is:
+
+@smallexample
+<?xml version="1.0"?>
+<!DOCTYPE target SYSTEM "osdata.dtd">
+<osdata type="processes">
+ <item>
+ <column name="pid">1</column>
+ <column name="user">root</column>
+ <column name="command">/sbin/init</column>
+ </item>
+</osdata>
+@end smallexample
+
+Each item should include a column whose name is @samp{pid}. The value
+of that column should identify the process on the target. The
+@samp{user} and @samp{command} columns are optional, and will be
+displayed by @value{GDBN}. Target may provide additional columns,
+which @value{GDBN} currently ignores.
+
@include gpl.texi
@raisesections