\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
* Commands:: @value{GDBN} commands
* Running:: Running programs under @value{GDBN}
* Stopping:: Stopping and continuing
+* Reverse Execution:: Running programs backward
* Stack:: Examining the stack
* Source:: Examining source files
* Data:: Examining data
* 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}
@xref{Ambiguous Expressions,,Ambiguous Expressions}, for a discussion of
that situation.
+It is also possible to insert a breakpoint that will stop the program
+only if a specific thread (@pxref{Thread-Specific Breakpoints})
+or a specific task (@pxref{Ada Tasks}) hits that breakpoint.
+
@item break
When called without any arguments, @code{break} sets a breakpoint at
the next instruction to be executed in the selected stack frame
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
another command. In background execution, @value{GDBN} immediately gives
a command prompt so that you can issue other commands while your program runs.
+You need to explicitly enable asynchronous mode before you can use
+background execution commands. You can use these commands to
+manipulate the asynchronous mode setting:
+
+@table @code
+@kindex set target-async
+@item set target-async on
+Enable asynchronous mode.
+@item set target-async off
+Disable asynchronous mode.
+@kindex show target-async
+@item show target-async
+Show the current target-async setting.
+@end table
+
+If the target doesn't support async mode, @value{GDBN} issues an error
+message if you attempt to use the background execution commands.
+
To specify background execution, add a @code{&} to the command. For example,
the background form of the @code{continue} command is @code{continue&}, or
just @code{c&}. The execution commands that accept background execution
@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}.
use @code{interrupt -a}.
@end table
-You may need to explicitly enable async mode before you can use background
-execution commands, with the @code{set target-async 1} command. If the
-target doesn't support async mode, @value{GDBN} issues an error message
-if you attempt to use the background execution commands.
-
@node Thread-Specific Breakpoints
@subsection Thread-Specific Breakpoints
prematurely, even though your program does not appear to stop.
+@node Reverse Execution
+@chapter Running programs backward
+@cindex reverse execution
+@cindex running programs backward
+
+When you are debugging a program, it is not unusual to realize that
+you have gone too far, and some event of interest has already happened.
+If the target environment supports it, @value{GDBN} can allow you to
+``rewind'' the program by running it backward.
+
+A target environment that supports reverse execution should be able
+to ``undo'' the changes in machine state that have taken place as the
+program was executing normally. Variables, registers etc.@: should
+revert to their previous values. Obviously this requires a great
+deal of sophistication on the part of the target environment; not
+all target environments can support reverse execution.
+
+When a program is executed in reverse, the instructions that
+have most recently been executed are ``un-executed'', in reverse
+order. The program counter runs backward, following the previous
+thread of execution in reverse. As each instruction is ``un-executed'',
+the values of memory and/or registers that were changed by that
+instruction are reverted to their previous states. After executing
+a piece of source code in reverse, all side effects of that code
+should be ``undone'', and all variables should be returned to their
+prior values@footnote{
+Note that some side effects are easier to undo than others. For instance,
+memory and registers are relatively easy, but device I/O is hard. Some
+targets may be able undo things like device I/O, and some may not.
+
+The contract between @value{GDBN} and the reverse executing target
+requires only that the target do something reasonable when
+@value{GDBN} tells it to execute backwards, and then report the
+results back to @value{GDBN}. Whatever the target reports back to
+@value{GDBN}, @value{GDBN} will report back to the user. @value{GDBN}
+assumes that the memory and registers that the target reports are in a
+consistant state, but @value{GDBN} accepts whatever it is given.
+}.
+
+If you are debugging in a target environment that supports
+reverse execution, @value{GDBN} provides the following commands.
+
+@table @code
+@kindex reverse-continue
+@kindex rc @r{(@code{reverse-continue})}
+@item reverse-continue @r{[}@var{ignore-count}@r{]}
+@itemx rc @r{[}@var{ignore-count}@r{]}
+Beginning at the point where your program last stopped, start executing
+in reverse. Reverse execution will stop for breakpoints and synchronous
+exceptions (signals), just like normal execution. Behavior of
+asynchronous signals depends on the target environment.
+
+@kindex reverse-step
+@kindex rs @r{(@code{step})}
+@item reverse-step @r{[}@var{count}@r{]}
+Run the program backward until control reaches the start of a
+different source line; then stop it, and return control to @value{GDBN}.
+
+Like the @code{step} command, @code{reverse-step} will only stop
+at the beginning of a source line. It ``un-executes'' the previously
+executed source line. If the previous source line included calls to
+debuggable functions, @code{reverse-step} will step (backward) into
+the called function, stopping at the beginning of the @emph{last}
+statement in the called function (typically a return statement).
+
+Also, as with the @code{step} command, if non-debuggable functions are
+called, @code{reverse-step} will run thru them backward without stopping.
+
+@kindex reverse-stepi
+@kindex rsi @r{(@code{reverse-stepi})}
+@item reverse-stepi @r{[}@var{count}@r{]}
+Reverse-execute one machine instruction. Note that the instruction
+to be reverse-executed is @emph{not} the one pointed to by the program
+counter, but the instruction executed prior to that one. For instance,
+if the last instruction was a jump, @code{reverse-stepi} will take you
+back from the destination of the jump to the jump instruction itself.
+
+@kindex reverse-next
+@kindex rn @r{(@code{reverse-next})}
+@item reverse-next @r{[}@var{count}@r{]}
+Run backward to the beginning of the previous line executed in
+the current (innermost) stack frame. If the line contains function
+calls, they will be ``un-executed'' without stopping. Starting from
+the first line of a function, @code{reverse-next} will take you back
+to the caller of that function, @emph{before} the function was called,
+just as the normal @code{next} command would take you from the last
+line of a function back to its return to its caller
+@footnote{Unles the code is too heavily optimized.}.
+
+@kindex reverse-nexti
+@kindex rni @r{(@code{reverse-nexti})}
+@item reverse-nexti @r{[}@var{count}@r{]}
+Like @code{nexti}, @code{reverse-nexti} executes a single instruction
+in reverse, except that called functions are ``un-executed'' atomically.
+That is, if the previously executed instruction was a return from
+another instruction, @code{reverse-nexti} will continue to execute
+in reverse until the call to that function (from the current stack
+frame) is reached.
+
+@kindex reverse-finish
+@item reverse-finish
+Just as the @code{finish} command takes you to the point where the
+current function returns, @code{reverse-finish} takes you to the point
+where it was called. Instead of ending up at the end of the current
+function invocation, you end up at the beginning.
+
+@kindex set exec-direction
+@item set exec-direction
+Set the direction of target execution.
+@itemx set exec-direction reverse
+@cindex execute forward or backward in time
+@value{GDBN} will perform all execution commands in reverse, until the
+exec-direction mode is changed to ``forward''. Affected commands include
+@code{step, stepi, next, nexti, continue, and finish}. The @code{return}
+command cannot be used in reverse mode.
+@item set exec-direction forward
+@value{GDBN} will perform all execution commands in the normal fashion.
+This is the default.
+@end table
+
@node Stack
@chapter Examining the Stack
@group
#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
at builtin.c:993
-#1 0x6e38 in expand_macro (sym=0x2b600) at macro.c:242
+#1 0x6e38 in expand_macro (sym=0x2b600, data=...) at macro.c:242
#2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)
at macro.c:71
(More stack frames follow...)
value, indicating that your program has stopped at the beginning of the
code for line @code{993} of @code{builtin.c}.
+@noindent
+The value of parameter @code{data} in frame 1 has been replaced by
+@code{@dots{}}. By default, @value{GDBN} prints the value of a parameter
+only if it is a scalar (integer, pointer, enumeration, etc). See command
+@kbd{set print frame-arguments} in @ref{Print Settings} for more details
+on how to configure the way function parameter values are printed.
+
@cindex value optimized out, in backtrace
@cindex function call arguments, optimized out
If your program was compiled with optimizations, some compilers will
located at the original location, a substitution rule is the only
method available to point @value{GDBN} at the new location.
+@cindex @samp{--with-relocated-sources}
+@cindex default source path substitution
+You can configure a default source path substitution rule by
+configuring @value{GDBN} with the
+@samp{--with-relocated-sources=@var{dir}} option. The @var{dir}
+should be the name of a directory under @value{GDBN}'s configured
+prefix (set with @samp{--prefix} or @samp{--exec-prefix}), and
+directory names in debug information under @var{dir} will be adjusted
+automatically if the installed @value{GDBN} is moved to a new
+location. This is useful if @value{GDBN}, libraries or executables
+with debug information and corresponding source code are being moved
+together.
+
@table @code
@item directory @var{dirname} @dots{}
@item dir @var{dirname} @dots{}
You can use the command @code{info line} to map source lines to program
addresses (and vice versa), and the command @code{disassemble} to display
-a range of addresses as machine instructions. When run under @sc{gnu} Emacs
+a range of addresses as machine instructions. You can use the command
+@code{set disassemble-next-line} to set whether to disassemble next
+source line when execution stops. When run under @sc{gnu} Emacs
mode, the @code{info line} command causes the arrow to point to the
line specified. Also, @code{info line} prints addresses in symbolic form as
well as hex.
Show the current setting of the disassembly flavor.
@end table
+@table @code
+@kindex set disassemble-next-line
+@kindex show disassemble-next-line
+@item set disassemble-next-line
+@itemx show disassemble-next-line
+Control whether or not @value{GDBN} will disassemble the next source
+line or instruction when execution stops. If ON, @value{GDBN} will
+display disassembly of the next source line when execution of the
+program being debugged stops. This is @emph{in addition} to
+displaying the source line itself, which @value{GDBN} always does if
+possible. If the next source line cannot be displayed for some reason
+(e.g., if @value{GDBN} cannot find the source file, or there's no line
+info in the debug info), @value{GDBN} will display disassembly of the
+next @emph{instruction} instead of showing the next source line. If
+AUTO, @value{GDBN} will display disassembly of next instruction only
+if the source line cannot be displayed. This setting causes
+@value{GDBN} to display some feedback when you step through a function
+with no line info or whose source file is unavailable. The default is
+OFF, which means never display the disassembly of the next line or
+instruction.
+@end table
+
@node Data
@chapter Examining Data
If the number is 0, then the printing is unlimited.
@item set print frame-arguments @var{value}
+@kindex set print frame-arguments
@cindex printing frame argument values
@cindex print all frame argument values
@cindex print frame argument values for scalars only
@table @code
@item all
-The values of all arguments are printed. This is the default.
+The values of all arguments are printed.
@item scalars
Print the value of an argument only if it is a scalar. The value of more
complex arguments such as arrays, structures, unions, etc, is replaced
-by @code{@dots{}}. Here is an example where only scalar arguments are shown:
+by @code{@dots{}}. This is the default. Here is an example where
+only scalar arguments are shown:
@smallexample
#1 0x08048361 in call_me (i=3, s=@dots{}, ss=0xbf8d508c, u=@dots{}, e=green)
@end smallexample
@end table
-By default, all argument values are always printed. But this command
-can be useful in several cases. For instance, it can be used to reduce
-the amount of information printed in each frame, making the backtrace
-more readable. Also, this command can be used to improve performance
-when displaying Ada frames, because the computation of large arguments
-can sometimes be CPU-intensive, especiallly in large applications.
-Setting @code{print frame-arguments} to @code{scalars} or @code{none}
-avoids this computation, thus speeding up the display of each Ada frame.
+By default, only scalar arguments are printed. This command can be used
+to configure the debugger to print the value of all arguments, regardless
+of their type. However, it is often advantageous to not print the value
+of more complex parameters. For instance, it reduces the amount of
+information printed in each frame, making the backtrace more readable.
+Also, it improves performance when displaying Ada frames, because
+the computation of large arguments can sometimes be CPU-intensive,
+especially in large applications. Setting @code{print frame-arguments}
+to @code{scalars} (the default) or @code{none} avoids this computation,
+thus speeding up the display of each Ada frame.
@item show print frame-arguments
Show how the value of arguments should be displayed when printing a frame.
@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
begins with a dollar sign, @value{GDBN} searches for a user or system
name first, before it searches for a convenience variable.
+@cindex convenience functions
+@value{GDBN} also supplies some @dfn{convenience functions}. These
+have a syntax similar to convenience variables. A convenience
+function can be used in an expression just like an ordinary function;
+however, a convenience function is implemented internally to
+@value{GDBN}.
+
+@table @code
+@item help function
+@kindex help function
+@cindex show all convenience functions
+Print a list of all convenience functions.
+@end table
+
@node Registers
@section Registers
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
@table @code
@item set target-charset @var{charset}
@kindex set target-charset
-Set the current target character set to @var{charset}. We list the
-character set names @value{GDBN} recognizes below, but if you type
-@code{set target-charset} followed by @key{TAB}@key{TAB}, @value{GDBN} will
-list the target character sets it supports.
-@end table
+Set the current target character set to @var{charset}. To display the
+list of supported target character sets, type
+@kbd{@w{set target-charset @key{TAB}@key{TAB}}}.
-@table @code
@item set host-charset @var{charset}
@kindex set host-charset
Set the current host character set to @var{charset}.
By default, @value{GDBN} uses a host character set appropriate to the
system it is running on; you can override that default using the
-@code{set host-charset} command.
+@code{set host-charset} command. On some systems, @value{GDBN} cannot
+automatically determine the appropriate host character set. In this
+case, @value{GDBN} uses @samp{UTF-8}.
@value{GDBN} can only use certain character sets as its host character
-set. We list the character set names @value{GDBN} recognizes below, and
-indicate which can be host character sets, but if you type
-@code{set target-charset} followed by @key{TAB}@key{TAB}, @value{GDBN} will
-list the host character sets it supports.
+set. If you type @kbd{@w{set target-charset @key{TAB}@key{TAB}}},
+@value{GDBN} will list the host character sets it supports.
@item set charset @var{charset}
@kindex set charset
Set the current host and target character sets to @var{charset}. As
-above, if you type @code{set charset} followed by @key{TAB}@key{TAB},
-@value{GDBN} will list the name of the character sets that can be used
+above, if you type @kbd{@w{set charset @key{TAB}@key{TAB}}},
+@value{GDBN} will list the names of the character sets that can be used
for both host and target.
-
@item show charset
@kindex show charset
-Show the names of the current host and target charsets.
+Show the names of the current host and target character sets.
-@itemx show host-charset
+@item show host-charset
@kindex show host-charset
-Show the name of the current host charset.
+Show the name of the current host character set.
-@itemx show target-charset
+@item show target-charset
@kindex show target-charset
-Show the name of the current target charset.
-
-@end table
-
-@value{GDBN} currently includes support for the following character
-sets:
-
-@table @code
+Show the name of the current target character set.
-@item ASCII
-@cindex ASCII character set
-Seven-bit U.S. @sc{ascii}. @value{GDBN} can use this as its host
-character set.
-
-@item ISO-8859-1
-@cindex ISO 8859-1 character set
-@cindex ISO Latin 1 character set
-The ISO Latin 1 character set. This extends @sc{ascii} with accented
-characters needed for French, German, and Spanish. @value{GDBN} can use
-this as its host character set.
-
-@item EBCDIC-US
-@itemx IBM1047
-@cindex EBCDIC character set
-@cindex IBM1047 character set
-Variants of the @sc{ebcdic} character set, used on some of IBM's
-mainframe operating systems. (@sc{gnu}/Linux on the S/390 uses U.S. @sc{ascii}.)
-@value{GDBN} cannot use these as its host character set.
+@item set target-wide-charset @var{charset}
+@kindex set target-wide-charset
+Set the current target's wide character set to @var{charset}. This is
+the character set used by the target's @code{wchar_t} type. To
+display the list of supported wide character sets, type
+@kbd{@w{set target-wide-charset @key{TAB}@key{TAB}}}.
+@item show target-wide-charset
+@kindex show target-wide-charset
+Show the name of the current target's wide character set.
@end table
-Note that these are all single-byte character sets. More work inside
-@value{GDBN} is needed to support multi-byte or variable-width character
-encodings, like the UTF-8 and UCS-2 encodings of Unicode.
-
Here is an example of @value{GDBN}'s character set support in action.
Assume that the following source code has been placed in the file
@file{charset-test.c}:
@cindex definition, showing a macro's
@item info macro @var{macro}
Show the definition of the macro named @var{macro}, and describe the
-source location where that definition was established.
+source location or compiler command-line where that definition was established.
@kindex macro define
@cindex user-defined macros
(@value{GDBP})
@end smallexample
+In addition to source files, macros can be defined on the compilation command
+line using the @option{-D@var{name}=@var{value}} syntax. For macros defined in
+such a way, @value{GDBN} displays the location of their definition as line zero
+of the source file submitted to the compiler.
+
+@smallexample
+(@value{GDBP}) info macro __STDC__
+Defined at /home/jimb/gdb/macros/play/sample.c:0
+-D__STDC__=1
+(@value{GDBP})
+@end smallexample
+
@node Tracepoints
@chapter Tracepoints
@section Commands to Set Tracepoints
Before running such a @dfn{trace experiment}, an arbitrary number of
-tracepoints can be set. Like a breakpoint (@pxref{Set Breaks}), a
-tracepoint has a number assigned to it by @value{GDBN}. Like with
-breakpoints, tracepoint numbers are successive integers starting from
-one. Many of the commands associated with tracepoints take the
-tracepoint number as their argument, to identify which tracepoint to
-work on.
+tracepoints can be set. A tracepoint is actually a special type of
+breakpoint (@pxref{Set Breaks}), so you can manipulate it using
+standard breakpoint commands. For instance, as with breakpoints,
+tracepoint numbers are successive integers starting from one, and many
+of the commands associated with tracepoints take the tracepoint number
+as their argument, to identify which tracepoint to work on.
For each tracepoint, you can specify, in advance, some arbitrary set
of data that you want the target to collect in the trace buffer when
commands to examine the values these data had at the time the
tracepoint was hit.
+Tracepoints do not support every breakpoint feature. Conditional
+expressions and ignore counts on tracepoints have no effect, and
+tracepoints cannot run @value{GDBN} commands when they are
+hit. Tracepoints may not be thread-specific either.
+
This section describes commands to set tracepoints and associated
conditions and actions.
@table @code
@cindex set tracepoint
@kindex trace
-@item trace
+@item trace @var{location}
The @code{trace} command is very similar to the @code{break} command.
-Its argument can be a source line, a function name, or an address in
-the target program. @xref{Set Breaks}. The @code{trace} command
-defines a tracepoint, which is a point in the target program where the
-debugger will briefly stop, collect some data, and then allow the
-program to continue. Setting a tracepoint or changing its commands
-doesn't take effect until the next @code{tstart} command; thus, you
-cannot change the tracepoint attributes once a trace experiment is
-running.
+Its argument @var{location} can be a source line, a function name, or
+an address in the target program. @xref{Specify Location}. The
+@code{trace} command defines a tracepoint, which is a point in the
+target program where the debugger will briefly stop, collect some
+data, and then allow the program to continue. Setting a tracepoint or
+changing its actions doesn't take effect until the next @code{tstart}
+command, and once a trace experiment is running, further changes will
+not have any effect until the next trace experiment starts.
Here are some examples of using the @code{trace} command:
@cindex tracepoint deletion
@item delete tracepoint @r{[}@var{num}@r{]}
Permanently delete one or more tracepoints. With no argument, the
-default is to delete all tracepoints.
+default is to delete all tracepoints. Note that the regular
+@code{delete} command can remove tracepoints also.
Examples:
@node Enable and Disable Tracepoints
@subsection Enable and Disable Tracepoints
+These commands are deprecated; they are equivalent to plain @code{disable} and @code{enable}.
+
@table @code
@kindex disable tracepoint
@item disable tracepoint @r{[}@var{num}@r{]}
@kindex info tp
@cindex information about tracepoints
@item info tracepoints @r{[}@var{num}@r{]}
-Display information about the tracepoint @var{num}. If you don't specify
-a tracepoint number, displays information about all the tracepoints
-defined so far. For each tracepoint, the following information is
-shown:
+Display information about the tracepoint @var{num}. If you don't
+specify a tracepoint number, displays information about all the
+tracepoints defined so far. The format is similar to that used for
+@code{info breakpoints}; in fact, @code{info tracepoints} is the same
+command, simply restricting itself to tracepoints.
+
+A tracepoint's listing may include additional information specific to
+tracing:
@itemize @bullet
@item
-its number
-@item
-whether it is enabled or disabled
-@item
-its address
-@item
its passcount as given by the @code{passcount @var{n}} command
@item
its step count as given by the @code{while-stepping @var{n}} command
@item
-where in the source files is the tracepoint set
-@item
-its action list as given by the @code{actions} command
+its action list as given by the @code{actions} command. The actions
+are prefixed with an @samp{A} so as to distinguish them from commands.
@end itemize
@smallexample
(@value{GDBP}) @b{info trace}
-Num Enb Address PassC StepC What
-1 y 0x002117c4 0 0 <gdb_asm>
-2 y 0x0020dc64 0 0 in g_test at g_test.c:1375
-3 y 0x0020b1f4 0 0 in get_data at ../foo.c:41
+Num Type Disp Enb Address What
+1 tracepoint keep y 0x0804ab57 in foo() at main.cxx:7
+ pass count 1200
+ step count 20
+ A while-stepping 20
+ A collect globfoo, $regs
+ A end
+ A collect globfoo2
+ A end
(@value{GDBP})
@end smallexample
@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 Runnable 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 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 Runnable 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 Runnable 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 Runnable 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
+
+@item break @var{linespec} task @var{taskno}
+@itemx break @var{linespec} task @var{taskno} if @dots{}
+@cindex breakpoints and tasks, in Ada
+@cindex task breakpoints, in Ada
+@kindex break @dots{} task @var{taskno}@r{ (Ada)}
+These commands are like the @code{break @dots{} thread @dots{}}
+command (@pxref{Thread Stops}).
+@var{linespec} specifies source lines, as described
+in @ref{Specify Location}.
+
+Use the qualifier @samp{task @var{taskno}} with a breakpoint command
+to specify that you only want @value{GDBN} to stop the program when a
+particular Ada task reaches this breakpoint. @var{taskno} is one of the
+numeric task identifiers assigned by @value{GDBN}, shown in the first
+column of the @samp{info tasks} display.
+
+If you do not specify @samp{task @var{taskno}} when you set a
+breakpoint, the breakpoint applies to @emph{all} tasks of your
+program.
+
+You can use the @code{task} qualifier on conditional breakpoints as
+well; in this case, place @samp{task @var{taskno}} before the
+breakpoint condition (before the @code{if}).
+
+For example,
+
+@smallexample
+@iftex
+@leftskip=0.5cm
+@end iftex
+(@value{GDBP}) info tasks
+ ID TID P-ID Pri State Name
+ 1 140022020 0 15 Child Activation Wait main_task
+ 2 140045060 1 15 Accept/Select Wait t2
+ 3 140044840 1 15 Runnable t1
+* 4 140056040 1 15 Runnable t3
+(@value{GDBP}) b 15 task 2
+Breakpoint 5 at 0x120044cb0: file test_task_debug.adb, line 15.
+(@value{GDBP}) cont
+Continuing.
+task # 1 running
+task # 2 running
+
+Breakpoint 5, test_task_debug () at test_task_debug.adb:15
+15 flush;
+(@value{GDBP}) info tasks
+ ID TID P-ID Pri State Name
+ 1 140022020 0 15 Child Activation Wait main_task
+* 2 140045060 1 15 Runnable t2
+ 3 140044840 1 15 Runnable t1
+ 4 140056040 1 15 Delay Sleep t3
+@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
and Stepping, ,Continuing and Stepping}) resumes execution until the
selected stack frame returns naturally.
+@value{GDBN} needs to know how the @var{expression} argument should be set for
+the inferior. The concrete registers assignment depends on the OS ABI and the
+type being returned by the selected stack frame. For example it is common for
+OS ABI to return floating point values in FPU registers while integer values in
+CPU registers. Still some ABIs return even floating point values in CPU
+registers. Larger integer widths (such as @code{long long int}) also have
+specific placement rules. @value{GDBN} already knows the OS ABI from its
+current target so it needs to find out also the type being returned to make the
+assignment into the right register(s).
+
+Normally, the selected stack frame has debug info. @value{GDBN} will always
+use the debug info instead of the implicit type of @var{expression} when the
+debug info is available. For example, if you type @kbd{return -1}, and the
+function in the current stack frame is declared to return a @code{long long
+int}, @value{GDBN} transparently converts the implicit @code{int} value of -1
+into a @code{long long int}:
+
+@smallexample
+Breakpoint 1, func () at gdb.base/return-nodebug.c:29
+29 return 31;
+(@value{GDBP}) return -1
+Make func return now? (y or n) y
+#0 0x004004f6 in main () at gdb.base/return-nodebug.c:43
+43 printf ("result=%lld\n", func ());
+(@value{GDBP})
+@end smallexample
+
+However, if the selected stack frame does not have a debug info, e.g., if the
+function was compiled without debug info, @value{GDBN} has to find out the type
+to return from user. Specifying a different type by mistake may set the value
+in different inferior registers than the caller code expects. For example,
+typing @kbd{return -1} with its implicit type @code{int} would set only a part
+of a @code{long long int} result for a debug info less function (on 32-bit
+architectures). Therefore the user is required to specify the return type by
+an appropriate cast explicitly:
+
+@smallexample
+Breakpoint 2, 0x0040050b in func ()
+(@value{GDBP}) return -1
+Return value type not available for selected stack frame.
+Please use an explicit cast of the value to return.
+(@value{GDBP}) return (long long int) -1
+Make selected stack frame return now? (y or n) y
+#0 0x00400526 in main ()
+(@value{GDBP})
+@end smallexample
+
@node Calling
@section Calling Program Functions
@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
* Files:: Commands to specify files
* Separate Debug Files:: Debugging information in separate files
* Symbol Errors:: Errors reading symbol files
+* Data Files:: GDB data files
@end menu
@node Files
@end table
+@node Data Files
+@section GDB Data Files
+
+@cindex prefix for data files
+@value{GDBN} will sometimes read an auxiliary data file. These files
+are kept in a directory known as the @dfn{data directory}.
+
+You can set the data directory's name, and view the name @value{GDBN}
+is currently using.
+
+@table @code
+@kindex set data-directory
+@item set data-directory @var{directory}
+Set the directory which @value{GDBN} searches for auxiliary data files
+to @var{directory}.
+
+@kindex show data-directory
+@item show data-directory
+Show the directory @value{GDBN} searches for auxiliary data files.
+@end table
+
+@cindex default data directory
+@cindex @samp{--with-gdb-datadir}
+You can set the default data directory by using the configure-time
+@samp{--with-gdb-datadir} option. If the data directory is inside
+@value{GDBN}'s configured binary prefix (set with @samp{--prefix} or
+@samp{--exec-prefix}), then the default data directory will be updated
+automatically if the installed @value{GDBN} is moved to a new
+location.
+
@node Targets
@chapter Specifying a Debugging Target
@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}
+
+@item @code{query-attached}
+@tab @code{qAttached}
+@tab Querying remote process attach state.
@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).
@menu
* Basic Python:: Basic Python Functions.
* Exception Handling::
+* Values From Inferior::
+* Commands In Python:: Implementing new commands in Python.
+* Functions In Python:: Writing new convenience functions.
+* Frames In Python:: Acessing inferior stack frames from 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.
Python statement closest to where the @value{GDBN} error occured as the
traceback.
-@node Interpreters
-@chapter Command Interpreters
-@cindex command interpreters
+@node Values From Inferior
+@subsubsection Values From Inferior
+@cindex values from inferior, with Python
+@cindex python, working with values from inferior
-@value{GDBN} supports multiple command interpreters, and some command
-infrastructure to allow users or user interface writers to switch
-between interpreters or run commands in other interpreters.
+@cindex @code{gdb.Value}
+@value{GDBN} provides values it obtains from the inferior program in
+an object of type @code{gdb.Value}. @value{GDBN} uses this object
+for its internal bookkeeping of the inferior's values, and for
+fetching values when necessary.
-@value{GDBN} currently supports two command interpreters, the console
-interpreter (sometimes called the command-line interpreter or @sc{cli})
-and the machine interface interpreter (or @sc{gdb/mi}). This manual
-describes both of these interfaces in great detail.
+Inferior values that are simple scalars can be used directly in
+Python expressions that are valid for the value's data type. Here's
+an example for an integer or floating-point value @code{some_val}:
-By default, @value{GDBN} will start with the console interpreter.
-However, the user may choose to start @value{GDBN} with another
-interpreter by specifying the @option{-i} or @option{--interpreter}
-startup options. Defined interpreters include:
+@smallexample
+bar = some_val + 2
+@end smallexample
-@table @code
-@item console
-@cindex console interpreter
-The traditional console or command-line interpreter. This is the most often
-used interpreter with @value{GDBN}. With no interpreter specified at runtime,
-@value{GDBN} will use this interpreter.
+@noindent
+As result of this, @code{bar} will also be a @code{gdb.Value} object
+whose values are of the same type as those of @code{some_val}.
+
+Inferior values that are structures or instances of some class can
+be accessed using the Python @dfn{dictionary syntax}. For example, if
+@code{some_val} is a @code{gdb.Value} instance holding a structure, you
+can access its @code{foo} element with:
+
+@smallexample
+bar = some_val['foo']
+@end smallexample
+
+Again, @code{bar} will also be a @code{gdb.Value} object.
+
+The following attributes are provided:
+
+@table @code
+@defmethod Value address
+If this object is addressable, this read-only attribute holds a
+@code{gdb.Value} object representing the address. Otherwise,
+this attribute holds @code{None}.
+@end defmethod
+
+@cindex optimized out value in Python
+@defmethod Value is_optimized_out
+This read-only boolean attribute is true if the compiler optimized out
+this value, thus it is not available for fetching from the inferior.
+@end defmethod
+@end table
+
+The following methods are provided:
+
+@table @code
+@defmethod Value dereference
+For pointer data types, this method returns a new @code{gdb.Value} object
+whose contents is the object pointed to by the pointer. For example, if
+@code{foo} is a C pointer to an @code{int}, declared in your C program as
+
+@smallexample
+int *foo;
+@end smallexample
+
+@noindent
+then you can use the corresponding @code{gdb.Value} to access what
+@code{foo} points to like this:
+
+@smallexample
+bar = foo.dereference ()
+@end smallexample
+
+The result @code{bar} will be a @code{gdb.Value} object holding the
+value pointed to by @code{foo}.
+@end defmethod
+
+@defmethod Value string @r{[}encoding@r{]} @r{[}errors@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
+@end table
+
+@node Commands In Python
+@subsubsection Commands In Python
+
+@cindex commands in python
+@cindex python commands
+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}@r{]} @r{[}@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 Functions In Python
+@subsubsection Writing new convenience functions
+
+@cindex writing convenience functions
+@cindex convenience functions in python
+@cindex python convenience functions
+@tindex gdb.Function
+@tindex Function
+You can implement new convenience functions (@pxref{Convenience Vars})
+in Python. A convenience function is an instance of a subclass of the
+class @code{gdb.Function}.
+
+@defmethod Function __init__ name
+The initializer for @code{Function} registers the new function with
+@value{GDBN}. The argument @var{name} is the name of the function,
+a string. The function will be visible to the user as a convenience
+variable of type @code{internal function}, whose name is the same as
+the given @var{name}.
+
+The documentation for the new function is taken from the documentation
+string for the new class.
+@end defmethod
+
+@defmethod Function invoke @var{*args}
+When a convenience function is evaluated, its arguments are converted
+to instances of @code{gdb.Value}, and then the function's
+@code{invoke} method is called. Note that @value{GDBN} does not
+predetermine the arity of convenience functions. Instead, all
+available arguments are passed to @code{invoke}, following the
+standard Python calling convention. In particular, a convenience
+function can have default values for parameters without ill effect.
+
+The return value of this method is used as its value in the enclosing
+expression. If an ordinary Python value is returned, it is converted
+to a @code{gdb.Value} following the usual rules.
+@end defmethod
+
+The following code snippet shows how a trivial convenience function can
+be implemented in Python:
+
+@smallexample
+class Greet (gdb.Function):
+ """Return string to greet someone.
+Takes a name as argument."""
+
+ def __init__ (self):
+ super (Greet, self).__init__ ("greet")
+
+ def invoke (self, name):
+ return "Hello, %s!" % name.string ()
+
+Greet ()
+@end smallexample
+
+The last line instantiates the class, and is necessary to trigger the
+registration of the function 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 Frames In Python
+@subsubsection Acessing inferior stack frames from Python.
+
+@cindex frames in python
+When the debugged program stops, @value{GDBN} is able to analyze its call
+stack (@pxref{Frames,,Stack frames}). The @code{gdb.Frame} class
+represents a frame in the stack. A @code{gdb.Frame} object is only valid
+while its corresponding frame exists in the inferior's stack. If you try
+to use an invalid frame object, @value{GDBN} will throw a @code{RuntimeError}
+exception.
+
+Two @code{gdb.Frame} objects can be compared for equality with the @code{==}
+operator, like:
+
+@smallexample
+(@value{GDBP}) python print gdb.newest_frame() == gdb.selected_frame ()
+True
+@end smallexample
+
+The following frame-related functions are available in the @code{gdb} module:
+
+@findex gdb.selected_frame
+@defun selected_frame
+Return the selected frame object. (@pxref{Selection,,Selecting a Frame}).
+@end defun
+
+@defun frame_stop_reason_string reason
+Return a string explaining the reason why @value{GDBN} stopped unwinding
+frames, as expressed by the given @var{reason} code (an integer, see the
+@code{unwind_stop_reason} method further down in this section).
+@end defun
+
+A @code{gdb.Frame} object has the following methods:
+
+@table @code
+@defmethod Frame is_valid
+Returns true if the @code{gdb.Frame} object is valid, false if not.
+A frame object can become invalid if the frame it refers to doesn't
+exist anymore in the inferior. All @code{gdb.Frame} methods will throw
+an exception if it is invalid at the time the method is called.
+@end defmethod
+
+@defmethod Frame name
+Returns the function name of the frame, or @code{None} if it can't be
+obtained.
+@end defmethod
+
+@defmethod Frame type
+Returns the type of the frame. The value can be one of
+@code{gdb.NORMAL_FRAME}, @code{gdb.DUMMY_FRAME}, @code{gdb.SIGTRAMP_FRAME}
+or @code{gdb.SENTINEL_FRAME}.
+@end defmethod
+
+@defmethod Frame unwind_stop_reason
+Return an integer representing the reason why it's not possible to find
+more frames toward the outermost frame. Use
+@code{gdb.frame_stop_reason_string} to convert the value returned by this
+function to a string.
+@end defmethod
+
+@defmethod Frame pc
+Returns the frame's resume address.
+@end defmethod
+
+@defmethod Frame older
+Return the frame that called this frame.
+@end defmethod
+
+@defmethod Frame newer
+Return the frame called by this frame.
+@end defmethod
+
+@defmethod Frame read_var variable
+Return the value of the given variable in this frame. @var{variable} must
+be a string.
+@end defmethod
+@end table
+
+@node Interpreters
+@chapter Command Interpreters
+@cindex command interpreters
+
+@value{GDBN} supports multiple command interpreters, and some command
+infrastructure to allow users or user interface writers to switch
+between interpreters or run commands in other interpreters.
+
+@value{GDBN} currently supports two command interpreters, the console
+interpreter (sometimes called the command-line interpreter or @sc{cli})
+and the machine interface interpreter (or @sc{gdb/mi}). This manual
+describes both of these interfaces in great detail.
+
+By default, @value{GDBN} will start with the console interpreter.
+However, the user may choose to start @value{GDBN} with another
+interpreter by specifying the @option{-i} or @option{--interpreter}
+startup options. Defined interpreters include:
+
+@table @code
+@item console
+@cindex console interpreter
+The traditional console or command-line interpreter. This is the most often
+used interpreter with @value{GDBN}. With no interpreter specified at runtime,
+@value{GDBN} will use this interpreter.
@item mi
@cindex mi interpreter
@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}.
(gdb)
@end smallexample
+@subheading The @code{-exec-jump} Command
+@findex -exec-jump
+
+@subsubheading Synopsis
+
+@smallexample
+ -exec-jump @var{location}
+@end smallexample
+
+Resumes execution of the inferior program at the location specified by
+parameter. @xref{Specify Location}, for a description of the
+different forms of @var{location}.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{jump}.
+
+@subsubheading Example
+
+@smallexample
+-exec-jump foo.c:10
+*running,thread-id="all"
+^running
+@end smallexample
+
@subheading The @code{-exec-next} Command
@findex -exec-next
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
distribution; if it is not, you can get the latest version from
@url{http://zlib.net}.
+@item iconv
+@value{GDBN}'s features related to character sets (@pxref{Character
+Sets}) require a functioning @code{iconv} implementation. If you are
+on a GNU system, then this is provided by the GNU C Library. Some
+other systems also provide a working @code{iconv}.
+
+On systems with @code{iconv}, you can install GNU Libiconv. If you
+have previously installed Libiconv, you can use the
+@option{--with-libiconv-prefix} option to configure.
+
+@value{GDBN}'s top-level @file{configure} and @file{Makefile} will
+arrange to build Libiconv if a directory named @file{libiconv} appears
+in the top-most source directory. If Libiconv is built this way, and
+if the operating system does not provide a suitable @code{iconv}
+implementation, then the just-built library will automatically be used
+by @value{GDBN}. One easy way to set this up is to download GNU
+Libiconv, unpack it, and then rename the directory holding the
+Libiconv source code to @samp{libiconv}.
@end table
@node Running Configure
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,
Configuring with @samp{--enable-profiling} arranges for @value{GDBN} to be
compiled with the @samp{-pg} compiler option.
-@kindex maint set linux-async
-@kindex maint show linux-async
-@cindex asynchronous support
-@item maint set linux-async
-@itemx maint show linux-async
-Control the GNU/Linux native asynchronous support
-(@pxref{Background Execution}) of @value{GDBN}.
-
-GNU/Linux native asynchronous support will be disabled until you use
-the @samp{maint set linux-async} command to enable it.
-
-@kindex maint set remote-async
-@kindex maint show remote-async
-@cindex asynchronous support
-@item maint set remote-async
-@itemx maint show remote-async
-Control the remote asynchronous support
-(@pxref{Background Execution}) of @value{GDBN}.
-
-Remote asynchronous support will be disabled until you use
-the @samp{maint set remote-async} command to enable it.
-
@kindex maint show-debug-regs
-@cindex x86 hardware debug registers
+@cindex hardware debug registers
@item maint show-debug-regs
-Control whether to show variables that mirror the x86 hardware debug
+Control whether to show variables that mirror the hardware debug
registers. Use @code{ON} to enable, @code{OFF} to disable. If
enabled, the debug registers values are shown when @value{GDBN} inserts or
removes a hardware breakpoint or watchpoint, and when the inferior
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.
Don't use this packet. Use the @samp{Z} and @samp{z} packets instead
(@pxref{insert breakpoint or watchpoint packet}).
+@item bc
+@cindex @samp{bc} packet
+Backward continue. Execute the target system in reverse. No parameter.
+@xref{Reverse Execution}, for more information.
+
+Reply:
+@xref{Stop Reply Packets}, for the reply specifications.
+
+@item bs
+@cindex @samp{bs} packet
+Backward single step. Execute one instruction in reverse. No parameter.
+@xref{Reverse Execution}, for more information.
+
+Reply:
+@xref{Stop Reply Packets}, for the reply specifications.
+
@item c @r{[}@var{addr}@r{]}
@cindex @samp{c} packet
Continue. @var{addr} is address to resume. If @var{addr} is omitted,
@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.
The packet indicates that the loaded libraries have changed.
@value{GDBN} should use @samp{qXfer:libraries:read} to fetch a new
list of loaded libraries. @var{r} is ignored.
+
+@cindex replay log events, remote reply
+@item replaylog
+The packet indicates that the target cannot continue replaying
+logged execution events, because it has reached the end (or the
+beginning when executing backward) of the log. The value of @var{r}
+will be either @samp{begin} or @samp{end}. @xref{Reverse Execution},
+for more information.
+
+
@end table
@item W @var{AA}
@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
@var{object} does not recognize the @var{operation} keyword, the stub
must respond with an empty packet.
+@item qAttached:@var{pid}
+@cindex query attached, remote request
+@cindex @samp{qAttached} packet
+Return an indication of whether the remote server attached to an
+existing process or created a new process. When the multiprocess
+protocol extensions are supported (@pxref{multiprocess extensions}),
+@var{pid} is an integer in hexadecimal format identifying the target
+process. Otherwise, @value{GDBN} will omit the @var{pid} field and
+the query packet will be simplified as @samp{qAttached}.
+
+This query is used, for example, to know whether the remote process
+should be detached or killed when a @value{GDBN} session is ended with
+the @code{quit} command.
+
+Reply:
+@table @samp
+@item 1
+The remote server attached to an existing process.
+@item 0
+The remote server created a new process.
+@item E @var{NN}
+A badly formed request or an error was encountered.
+@end table
+
@end table
@node Register Packet Format
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
projects / deliverable / binutils-gdb.git / blobdiff