(such as wildcard expansion or variable substitution) in describing
the arguments.
In Unix systems, you can control which shell is used with the
-@code{SHELL} environment variable.
-@xref{Arguments, ,Your Program's Arguments}.
+@code{SHELL} environment variable. If you do not define @code{SHELL},
+@value{GDBN} uses the default shell (@file{/bin/sh}). You can disable
+use of any shell with the @code{set startup-with-shell} command (see
+below for details).
@item The @emph{environment.}
Your program normally inherits its environment from @value{GDBN}, but you can
This command is available when debugging locally on most targets, excluding
@sc{djgpp}, Cygwin, MS Windows, and QNX Neutrino.
+@kindex set startup-with-shell
+@item set startup-with-shell
+@itemx set startup-with-shell on
+@itemx set startup-with-shell off
+@itemx show set startup-with-shell
+On Unix systems, by default, if a shell is available on your target,
+@value{GDBN}) uses it to start your program. Arguments of the
+@code{run} command are passed to the shell, which does variable
+substitution, expands wildcard characters and performs redirection of
+I/O. In some circumstances, it may be useful to disable such use of a
+shell, for example, when debugging the shell itself or diagnosing
+startup failures such as:
+
+@smallexample
+(@value{GDBP}) run
+Starting program: ./a.out
+During startup program terminated with signal SIGSEGV, Segmentation fault.
+@end smallexample
+
+@noindent
+which indicates the shell or the wrapper specified with
+@samp{exec-wrapper} crashed, not your program. Most often, this is
+caused by something odd in your shell's non-interactive mode
+initialization file---such as @file{.cshrc} for C-shell,
+$@file{.zshenv} for the Z shell, or the file specified in the
+@samp{BASH_ENV} environment variable for BASH.
+
@kindex set disable-randomization
@item set disable-randomization
@itemx set disable-randomization on
@end table
@emph{Warning:} On Unix systems, @value{GDBN} runs your program using
-the shell indicated
-by your @code{SHELL} environment variable if it exists (or
-@code{/bin/sh} if not). If your @code{SHELL} variable names a shell
-that runs an initialization file---such as @file{.cshrc} for C-shell, or
-@file{.bashrc} for BASH---any variables you set in that file affect
-your program. You may wish to move setting of environment variables to
-files that are only run when you sign on, such as @file{.login} or
-@file{.profile}.
+the shell indicated by your @code{SHELL} environment variable if it
+exists (or @code{/bin/sh} if not). If your @code{SHELL} variable
+names a shell that runs an initialization file when started
+non-interactively---such as @file{.cshrc} for C-shell, $@file{.zshenv}
+for the Z shell, or the file specified in the @samp{BASH_ENV}
+environment variable for BASH---any variables you set in that file
+affect your program. You may wish to move setting of environment
+variables to files that are only run when you sign on, such as
+@file{.login} or @file{.profile}.
@node Working Directory
@section Your Program's Working Directory
@end table
+Thread-specific breakpoints are automatically deleted when
+@value{GDBN} detects the corresponding thread is no longer in the
+thread list. For example:
+
+@smallexample
+(@value{GDBP}) c
+Thread-specific breakpoint 3 deleted - thread 28 no longer in the thread list.
+@end smallexample
+
+There are several ways for a thread to disappear, such as a regular
+thread exit, but also when you detach from the process with the
+@code{detach} command (@pxref{Attach, ,Debugging an Already-running
+Process}), or if @value{GDBN} loses the remote connection
+(@pxref{Remote Debugging}), etc. Note that with some targets,
+@value{GDBN} is only able to detect a thread has exited when the user
+explictly asks for the thread list with the @code{info threads}
+command.
+
@node Interrupted System Calls
@subsection Interrupted System Calls
* Core File Generation:: Cause a program dump its core
* Character Sets:: Debugging programs that use a different
character set than GDB does
-* Caching Remote Data:: Data caching for remote targets
+* Caching Target Data:: Data caching for targets
* Searching Memory:: Searching memory for a sequence of bytes
@end menu
@end smallexample
@cindex C@t{++} scope resolution
-These uses of @samp{::} are very rarely in conflict with the very similar
-use of the same notation in C@t{++}. @value{GDBN} also supports use of the C@t{++}
-scope resolution operator in @value{GDBN} expressions.
-@c FIXME: Um, so what happens in one of those rare cases where it's in
-@c conflict?? --mew
+These uses of @samp{::} are very rarely in conflict with the very
+similar use of the same notation in C@t{++}. When they are in
+conflict, the C@t{++} meaning takes precedence; however, this can be
+overridden by quoting the file or function name with single quotes.
+
+For example, suppose the program is stopped in a method of a class
+that has a field named @code{includefile}, and there is also an
+include file named @file{includefile} that defines a variable,
+@code{some_global}.
+
+@smallexample
+(@value{GDBP}) p includefile
+$1 = 23
+(@value{GDBP}) p includefile::some_global
+A syntax error in expression, near `'.
+(@value{GDBP}) p 'includefile'::some_global
+$2 = 27
+@end smallexample
@cindex wrong values
@cindex variable values, wrong
strings. Single-byte members of a vector are displayed as an integer
array.
+@item z
+Like @samp{x} formatting, the value is treated as an integer and
+printed as hexadecimal, but leading zeros are printed to pad the value
+to the size of the integer type.
+
@item r
@cindex raw printing
Print using the @samp{raw} formatting. By default, @value{GDBN} will
@item show print frame-arguments
Show how the value of arguments should be displayed when printing a frame.
+@item set print raw frame-arguments on
+Print frame arguments in raw, non pretty-printed, form.
+
+@item set print raw frame-arguments off
+Print frame arguments in pretty-printed form, if there is a pretty-printer
+for the value (@pxref{Pretty Printing}),
+otherwise print the value in raw form.
+This is the default.
+
+@item show print raw frame-arguments
+Show whether to print frame arguments in raw form.
+
@anchor{set print entry-values}
@item set print entry-values @var{value}
@kindex set print entry-values
@item $_exitcode
@vindex $_exitcode@r{, convenience variable}
-The variable @code{$_exitcode} is automatically set to the exit code when
-the program being debugged terminates.
+When the program being debugged terminates normally, @value{GDBN}
+automatically sets this variable to the exit code of the program, and
+resets @code{$_exitsignal} to @code{void}.
+
+@item $_exitsignal
+@vindex $_exitsignal@r{, convenience variable}
+When the program being debugged dies due to an uncaught signal,
+@value{GDBN} automatically sets this variable to that signal's number,
+and resets @code{$_exitcode} to @code{void}.
+
+To distinguish between whether the program being debugged has exited
+(i.e., @code{$_exitcode} is not @code{void}) or signalled (i.e.,
+@code{$_exitsignal} is not @code{void}), the convenience function
+@code{$_isvoid} can be used (@pxref{Convenience Funs,, Convenience
+Functions}). For example, considering the following source code:
+
+@smallexample
+#include <signal.h>
+
+int
+main (int argc, char *argv[])
+@{
+ raise (SIGALRM);
+ return 0;
+@}
+@end smallexample
+
+A valid way of telling whether the program being debugged has exited
+or signalled would be:
+
+@smallexample
+(@value{GDBP}) define has_exited_or_signalled
+Type commands for definition of ``has_exited_or_signalled''.
+End with a line saying just ``end''.
+>if $_isvoid ($_exitsignal)
+ >echo The program has exited\n
+ >else
+ >echo The program has signalled\n
+ >end
+>end
+(@value{GDBP}) run
+Starting program:
+
+Program terminated with signal SIGALRM, Alarm clock.
+The program no longer exists.
+(@value{GDBP}) has_exited_or_signalled
+The program has signalled
+@end smallexample
+
+As can be seen, @value{GDBN} correctly informs that the program being
+debugged has signalled, since it calls @code{raise} and raises a
+@code{SIGALRM} signal. If the program being debugged had not called
+@code{raise}, then @value{GDBN} would report a normal exit:
+
+@smallexample
+(@value{GDBP}) has_exited_or_signalled
+The program has exited
+@end smallexample
@item $_exception
The variable @code{$_exception} is set to the exception object being
however, a convenience function is implemented internally to
@value{GDBN}.
+These functions do not require @value{GDBN} to be configured with
+@code{Python} support, which means that they are always available.
+
+@table @code
+
+@item $_isvoid (@var{expr})
+@findex $_isvoid@r{, convenience function}
+Return one if the expression @var{expr} is @code{void}. Otherwise it
+returns zero.
+
+A @code{void} expression is an expression where the type of the result
+is @code{void}. For example, you can examine a convenience variable
+(see @ref{Convenience Vars,, Convenience Variables}) to check whether
+it is @code{void}:
+
+@smallexample
+(@value{GDBP}) print $_exitcode
+$1 = void
+(@value{GDBP}) print $_isvoid ($_exitcode)
+$2 = 1
+(@value{GDBP}) run
+Starting program: ./a.out
+[Inferior 1 (process 29572) exited normally]
+(@value{GDBP}) print $_exitcode
+$3 = 0
+(@value{GDBP}) print $_isvoid ($_exitcode)
+$4 = 0
+@end smallexample
+
+In the example above, we used @code{$_isvoid} to check whether
+@code{$_exitcode} is @code{void} before and after the execution of the
+program being debugged. Before the execution there is no exit code to
+be examined, therefore @code{$_exitcode} is @code{void}. After the
+execution the program being debugged returned zero, therefore
+@code{$_exitcode} is zero, which means that it is not @code{void}
+anymore.
+
+The @code{void} expression can also be a call of a function from the
+program being debugged. For example, given the following function:
+
+@smallexample
+void
+foo (void)
+@{
+@}
+@end smallexample
+
+The result of calling it inside @value{GDBN} is @code{void}:
+
+@smallexample
+(@value{GDBP}) print foo ()
+$1 = void
+(@value{GDBP}) print $_isvoid (foo ())
+$2 = 1
+(@value{GDBP}) set $v = foo ()
+(@value{GDBP}) print $v
+$3 = void
+(@value{GDBP}) print $_isvoid ($v)
+$4 = 1
+@end smallexample
+
+@end table
+
These functions require @value{GDBN} to be configured with
@code{Python} support.
true contents of hardware registers, you must select the innermost
frame (with @samp{frame 0}).
-However, @value{GDBN} must deduce where registers are saved, from the machine
-code generated by your compiler. If some registers are not saved, or if
-@value{GDBN} is unable to locate the saved registers, the selected stack
-frame makes no difference.
+@cindex caller-saved registers
+@cindex call-clobbered registers
+@cindex volatile registers
+@cindex <not saved> values
+Usually ABIs reserve some registers as not needed to be saved by the
+callee (a.k.a.: ``caller-saved'', ``call-clobbered'' or ``volatile''
+registers). It may therefore not be possible for @value{GDBN} to know
+the value a register had before the call (in other words, in the outer
+frame), if the register value has since been changed by the callee.
+@value{GDBN} tries to deduce where the inner frame saved
+(``callee-saved'') registers, from the debug info, unwind info, or the
+machine code generated by your compiler. If some register is not
+saved, and @value{GDBN} knows the register is ``caller-saved'' (via
+its own knowledge of the ABI, or because the debug/unwind info
+explicitly says the register's value is undefined), @value{GDBN}
+displays @w{@samp{<not saved>}} as the register's value. With targets
+that @value{GDBN} has no knowledge of the register saving convention,
+if a register was not saved by the callee, then its value and location
+in the outer frame are assumed to be the same of the inner frame.
+This is usually harmless, because if the register is call-clobbered,
+the caller either does not care what is in the register after the
+call, or has code to restore the value that it does care about. Note,
+however, that if you change such a register in the outer frame, you
+may also be affecting the inner frame. Also, the more ``outer'' the
+frame is you're looking at, the more likely a call-clobbered
+register's value is to be wrong, in the sense that it doesn't actually
+represent the value the register had just before the call.
@node Floating Point Hardware
@section Floating Point Hardware
The @sc{ibm1047} character set uses the number 78 to encode the @samp{+}
character.
-@node Caching Remote Data
-@section Caching Data of Remote Targets
-@cindex caching data of remote targets
-
-@value{GDBN} caches data exchanged between the debugger and a
-remote target (@pxref{Remote Debugging}). Such caching generally improves
-performance, because it reduces the overhead of the remote protocol by
-bundling memory reads and writes into large chunks. Unfortunately, simply
-caching everything would lead to incorrect results, since @value{GDBN}
-does not necessarily know anything about volatile values, memory-mapped I/O
-addresses, etc. Furthermore, in non-stop mode (@pxref{Non-Stop Mode})
-memory can be changed @emph{while} a gdb command is executing.
+@node Caching Target Data
+@section Caching Data of Targets
+@cindex caching data of targets
+
+@value{GDBN} caches data exchanged between the debugger and a target.
+Each cache is associated with the address space of the inferior.
+@xref{Inferiors and Programs}, about inferior and address space.
+Such caching generally improves performance in remote debugging
+(@pxref{Remote Debugging}), because it reduces the overhead of the
+remote protocol by bundling memory reads and writes into large chunks.
+Unfortunately, simply caching everything would lead to incorrect results,
+since @value{GDBN} does not necessarily know anything about volatile
+values, memory-mapped I/O addresses, etc. Furthermore, in non-stop mode
+(@pxref{Non-Stop Mode}) memory can be changed @emph{while} a gdb command
+is executing.
Therefore, by default, @value{GDBN} only caches data
known to be on the stack@footnote{In non-stop mode, it is moderately
rare for a running thread to modify the stack of a stopped thread
in a way that would interfere with a backtrace, and caching of
stack reads provides a significant speed up of remote backtraces.}.
Other regions of memory can be explicitly marked as
-cacheable; see @pxref{Memory Region Attributes}.
+cacheable; @pxref{Memory Region Attributes}.
@table @code
@kindex set remotecache
@kindex set stack-cache
@item set stack-cache on
@itemx set stack-cache off
-Enable or disable caching of stack accesses. When @code{ON}, use
-caching. By default, this option is @code{ON}.
+Enable or disable caching of stack accesses. When @code{on}, use
+caching. By default, this option is @code{on}.
@kindex show stack-cache
@item show stack-cache
@kindex info dcache
@item info dcache @r{[}line@r{]}
-Print the information about the data cache performance. The
-information displayed includes the dcache width and depth, and for
-each cache line, its number, address, and how many times it was
-referenced. This command is useful for debugging the data cache
-operation.
+Print the information about the performance of data cache of the
+current inferior's address space. The information displayed
+includes the dcache width and depth, and for each cache line, its
+number, address, and how many times it was referenced. This
+command is useful for debugging the data cache operation.
If a line number is specified, the contents of that line will be
printed in hex.
@item show dcache size
@kindex show dcache size
-Show maximum number of dcache entries. See also @ref{Caching Remote Data, info dcache}.
+Show maximum number of dcache entries. @xref{Caching Target Data, info dcache}.
@item show dcache line-size
@kindex show dcache line-size
-Show default size of dcache lines. See also @ref{Caching Remote Data, info dcache}.
+Show default size of dcache lines.
@end table
@table @code
@item show language
+@anchor{show language}
@kindex show language
Display the current working language. This is the
language you can use with commands such as @code{print} to
There are two encodings in use, depending on the architecture: BID (Binary
Integer Decimal) for x86 and x86-64, and DPD (Densely Packed Decimal) for
-PowerPC. @value{GDBN} will use the appropriate encoding for the configured
-target.
+PowerPC and S/390. @value{GDBN} will use the appropriate encoding for the
+configured target.
Because of a limitation in @file{libdecnumber}, the library used by @value{GDBN}
to manipulate decimal floating point numbers, it is not possible to convert
* 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 Exceptions:: Ada Exceptions
* Ada Tasks:: Listing and setting breakpoints in tasks.
* Ada Tasks and Core Files:: Tasking Support when Debugging Core Files
* Ravenscar Profile:: Tasking Support when using the Ravenscar
elaboration, simply use the following two commands:
@code{tbreak adainit} and @code{run}.
+@node Ada Exceptions
+@subsubsection Ada Exceptions
+
+A command is provided to list all Ada exceptions:
+
+@table @code
+@kindex info exceptions
+@item info exceptions
+@itemx info exceptions @var{regexp}
+The @code{info exceptions} command allows you to list all Ada exceptions
+defined within the program being debugged, as well as their addresses.
+With a regular expression, @var{regexp}, as argument, only those exceptions
+whose names match @var{regexp} are listed.
+@end table
+
+Below is a small example, showing how the command can be used, first
+without argument, and next with a regular expression passed as an
+argument.
+
+@smallexample
+(@value{GDBP}) info exceptions
+All defined Ada exceptions:
+constraint_error: 0x613da0
+program_error: 0x613d20
+storage_error: 0x613ce0
+tasking_error: 0x613ca0
+const.aint_global_e: 0x613b00
+(@value{GDBP}) info exceptions const.aint
+All Ada exceptions matching regular expression "const.aint":
+constraint_error: 0x613da0
+const.aint_global_e: 0x613b00
+@end smallexample
+
+It is also possible to ask @value{GDBN} to stop your program's execution
+when an exception is raised. For more details, see @ref{Set Catchpoints}.
+
@node Ada Tasks
@subsubsection Extensions for Ada Tasks
@cindex Ada, tasking
@cindex symbol dump
@kindex maint print psymbols
@cindex partial symbol dump
+@kindex maint print msymbols
+@cindex minimal symbol dump
@item maint print symbols @var{filename}
@itemx maint print psymbols @var{filename}
@itemx maint print msymbols @var{filename}
The symbol table of the file @var{filename} is added to the symbol table
originally read with the @code{symbol-file} command. You can use the
@code{add-symbol-file} command any number of times; the new symbol data
-thus read keeps adding to the old. To discard all old symbol data
-instead, use the @code{symbol-file} command without any arguments.
+thus read is kept in addition to the old.
+
+Changes can be reverted using the command @code{remove-symbol-file}.
@cindex relocatable object files, reading symbols from
@cindex object files, relocatable, reading symbols from
@code{add-symbol-file} does not repeat if you press @key{RET} after using it.
+@kindex remove-symbol-file
+@item remove-symbol-file @var{filename}
+@item remove-symbol-file -a @var{address}
+Remove a symbol file added via the @code{add-symbol-file} command. The
+file to remove can be identified by its @var{filename} or by an @var{address}
+that lies within the boundaries of this symbol file in memory. Example:
+
+@smallexample
+(gdb) add-symbol-file /home/user/gdb/mylib.so 0x7ffff7ff9480
+add symbol table from file "/home/user/gdb/mylib.so" at
+ .text_addr = 0x7ffff7ff9480
+(y or n) y
+Reading symbols from /home/user/gdb/mylib.so...done.
+(gdb) remove-symbol-file -a 0x7ffff7ff9480
+Remove symbol table from file "/home/user/gdb/mylib.so"? (y or n) y
+(gdb)
+@end smallexample
+
+
+@code{remove-symbol-file} does not repeat if you press @key{RET} after using it.
+
@kindex add-symbol-file-from-memory
@cindex @code{syscall DSO}
@cindex load symbols from memory
@smallexample
# Extract the dynamic symbols from the main binary, there is no need
-# to also have these in the normal symbol table
+# to also have these in the normal symbol table.
nm -D @var{binary} --format=posix --defined-only \
| awk '@{ print $1 @}' | sort > dynsyms
-# Extract all the text (i.e. function) symbols from the debuginfo .
+# Extract all the text (i.e. function) symbols from the debuginfo.
+# (Note that we actually also accept "D" symbols, for the benefit
+# of platforms like PowerPC64 that use function descriptors.)
nm @var{binary} --format=posix --defined-only \
- | awk '@{ if ($2 == "T" || $2 == "t") print $1 @}' \
+ | awk '@{ if ($2 == "T" || $2 == "t" || $2 == "D") print $1 @}' \
| sort > funcsyms
# Keep all the function symbols not already in the dynamic symbol
# table.
comm -13 dynsyms funcsyms > keep_symbols
+# Separate full debug info into debug binary.
+objcopy --only-keep-debug @var{binary} debug
+
# Copy the full debuginfo, keeping only a minimal set of symbols and
# removing some unnecessary sections.
objcopy -S --remove-section .gdb_index --remove-section .comment \
- --keep-symbols=keep_symbols @var{binary} mini_debuginfo
+ --keep-symbols=keep_symbols debug mini_debuginfo
+
+# Drop the full debug info from the original binary.
+strip --strip-all -R .comment @var{binary}
# Inject the compressed data into the .gnu_debugdata section of the
# original binary.
@end table
-Some configurations may include these targets as well:
-
-@table @code
-
-@item target nrom @var{dev}
-@cindex NetROM ROM emulator target
-NetROM ROM emulator. This target only supports downloading.
-
-@end table
-
Different targets are available on different configurations of @value{GDBN};
your configuration may have more or fewer targets.
@end smallexample
If you're using a serial line, you may want to give @value{GDBN} the
-@w{@samp{--baud}} option, or use the @code{set remotebaud} command
-(@pxref{Remote Configuration, set remotebaud}) before the
+@samp{--baud} option, or use the @code{set serial baud} command
+(@pxref{Remote Configuration, set serial baud}) before the
@code{target} command.
@item target remote @code{@var{host}:@var{port}}
@cindex @option{--once}, @code{gdbserver} option
By default, @code{gdbserver} keeps the listening TCP port open, so that
-additional connections are possible. However, if you start @code{gdbserver}
+subsequent connections are possible. However, if you start @code{gdbserver}
with the @option{--once} option, it will stop listening for any further
connection attempts after connecting to the first @value{GDBN} session. This
means no further connections to @code{gdbserver} will be possible after the
@item show remoteaddresssize
Show the current value of remote address size in bits.
-@item set remotebaud @var{n}
+@item set serial baud @var{n}
@cindex baud rate for remote targets
Set the baud rate for the remote serial I/O to @var{n} baud. The
value is used to set the speed of the serial port used for debugging
remote targets.
-@item show remotebaud
+@item show serial baud
Show the current speed of the remote connection.
@item set remotebreak
@item set debug dwarf2-read
@cindex DWARF2 Reading
Turns on or off display of debugging messages related to reading
-DWARF debug info. The default is off.
+DWARF debug info. The default is 0 (off).
+A value of 1 provides basic information.
+A value greater than 1 provides more verbose information.
@item show debug dwarf2-read
Show the current state of DWARF2 reader debugging.
@item set debug displaced
@item show debug solib-frv
Display the current state of FR-V shared-library code debugging
messages.
+@item set debug symfile
+@cindex symbol file functions
+Turns on or off display of debugging messages related to symbol file functions.
+The default is off. @xref{Files}.
+@item show debug symfile
+Show the current state of symbol file debugging messages.
@item set debug symtab-create
@cindex symbol table creation
Turns on or off display of debugging messages related to symbol table creation.
-The default is off.
+The default is 0 (off).
+A value of 1 provides basic information.
+A value greater than 1 provides more verbose information.
@item show debug symtab-create
Show the current state of symbol table creation debugging.
@item set debug target
* Blocks In Python:: Accessing blocks from Python.
* Symbols In Python:: Python representation of symbols.
* Symbol Tables In Python:: Python representation of symbol tables.
+* Line Tables In Python:: Python representation of line tables.
* Breakpoints In Python:: Manipulating breakpoints using Python.
* Finish Breakpoints in Python:: Setting Breakpoints on function return
using Python.
@item gdb.COMPLETE_SYMBOL
This constant means that completion should be done using symbol names
as the source.
+
+@findex COMPLETE_EXPRESSION
+@findex gdb.COMPLETE_EXPRESSION
+@item gdb.COMPLETE_EXPRESSION
+This constant means that completion should be done on expressions.
+Often this means completing on symbol names, but some language
+parsers also have support for completing on field names.
@end table
The following code snippet shows how a trivial CLI command can be
@xref{Blocks In Python}.
@end defun
+@defun Symtab.linetable ()
+Return the line table associated with the symbol table.
+@xref{Line Tables In Python}.
+@end defun
+
+@node Line Tables In Python
+@subsubsection Manipulating line tables using Python
+
+@cindex line tables in python
+@tindex gdb.LineTable
+
+Python code can request and inspect line table information from a
+symbol table that is loaded in @value{GDBN}. A line table is a
+mapping of source lines to their executable locations in memory. To
+acquire the line table information for a particular symbol table, use
+the @code{linetable} function (@pxref{Symbol Tables In Python}).
+
+A @code{gdb.LineTable} is iterable. The iterator returns
+@code{LineTableEntry} objects that correspond to the source line and
+address for each line table entry. @code{LineTableEntry} objects have
+the following attributes:
+
+@defvar LineTableEntry.line
+The source line number for this line table entry. This number
+corresponds to the actual line of source. This attribute is not
+writable.
+@end defvar
+
+@defvar LineTableEntry.pc
+The address that is associated with the line table entry where the
+executable code for that source line resides in memory. This
+attribute is not writable.
+@end defvar
+
+As there can be multiple addresses for a single source line, you may
+receive multiple @code{LineTableEntry} objects with matching
+@code{line} attributes, but with different @code{pc} attributes. The
+iterator is sorted in ascending @code{pc} order. Here is a small
+example illustrating iterating over a line table.
+
+@smallexample
+symtab = gdb.selected_frame().find_sal().symtab
+linetable = symtab.linetable()
+for line in linetable:
+ print "Line: "+str(line.line)+" Address: "+hex(line.pc)
+@end smallexample
+
+This will have the following output:
+
+@smallexample
+Line: 33 Address: 0x4005c8L
+Line: 37 Address: 0x4005caL
+Line: 39 Address: 0x4005d2L
+Line: 40 Address: 0x4005f8L
+Line: 42 Address: 0x4005ffL
+Line: 44 Address: 0x400608L
+Line: 42 Address: 0x40060cL
+Line: 45 Address: 0x400615L
+@end smallexample
+
+In addition to being able to iterate over a @code{LineTable}, it also
+has the following direct access methods:
+
+@defun LineTable.line (line)
+Return a Python @code{Tuple} of @code{LineTableEntry} objects for any
+entries in the line table for the given @var{line}. @var{line} refers
+to the source code line. If there are no entries for that source code
+@var{line}, the Python @code{None} is returned.
+@end defun
+
+@defun LineTable.has_line (line)
+Return a Python @code{Boolean} indicating whether there is an entry in
+the line table for this source line. Return @code{True} if an entry
+is found, or @code{False} if not.
+@end defun
+
+@defun LineTable.source_lines ()
+Return a Python @code{List} of the source line numbers in the symbol
+table. Only lines with executable code locations are returned. The
+contents of the @code{List} will just be the source line entries
+represented as Python @code{Long} values.
+@end defun
+
@node Breakpoints In Python
@subsubsection Manipulating breakpoints using Python
Python code can manipulate breakpoints via the @code{gdb.Breakpoint}
class.
-@defun Breakpoint.__init__ (spec @r{[}, type @r{[}, wp_class @r{[},internal@r{]]]})
-Create a new breakpoint. @var{spec} is a string naming the
-location of the breakpoint, or an expression that defines a
-watchpoint. The contents can be any location recognized by the
-@code{break} command, or in the case of a watchpoint, by the @code{watch}
-command. The optional @var{type} denotes the breakpoint to create
-from the types defined later in this chapter. This argument can be
-either: @code{gdb.BP_BREAKPOINT} or @code{gdb.BP_WATCHPOINT}. @var{type}
-defaults to @code{gdb.BP_BREAKPOINT}. The optional @var{internal} argument
-allows the breakpoint to become invisible to the user. The breakpoint
-will neither be reported when created, nor will it be listed in the
-output from @code{info breakpoints} (but will be listed with the
-@code{maint info breakpoints} command). The optional @var{wp_class}
-argument defines the class of watchpoint to create, if @var{type} is
-@code{gdb.BP_WATCHPOINT}. If a watchpoint class is not provided, it is
-assumed to be a @code{gdb.WP_WRITE} class.
+@defun Breakpoint.__init__ (spec @r{[}, type @r{[}, wp_class @r{[},internal @r{[},temporary@r{]]]]})
+Create a new breakpoint. @var{spec} is a string naming the location
+of the breakpoint, or an expression that defines a watchpoint. The
+contents can be any location recognized by the @code{break} command,
+or in the case of a watchpoint, by the @code{watch} command. The
+optional @var{type} denotes the breakpoint to create from the types
+defined later in this chapter. This argument can be either:
+@code{gdb.BP_BREAKPOINT} or @code{gdb.BP_WATCHPOINT}. @var{type}
+defaults to @code{gdb.BP_BREAKPOINT}. The optional @var{internal}
+argument allows the breakpoint to become invisible to the user. The
+breakpoint will neither be reported when created, nor will it be
+listed in the output from @code{info breakpoints} (but will be listed
+with the @code{maint info breakpoints} command). The optional
+@var{temporary} argument makes the breakpoint a temporary breakpoint.
+Temporary breakpoints are deleted after they have been hit. Any
+further access to the Python breakpoint after it has been hit will
+result in a runtime error (as that breakpoint has now been
+automatically deleted). The optional @var{wp_class} argument defines
+the class of watchpoint to create, if @var{type} is
+@code{gdb.BP_WATCHPOINT}. If a watchpoint class is not provided, it
+is assumed to be a @code{gdb.WP_WRITE} class.
@end defun
@defun Breakpoint.stop (self)
The @code{gdb.Breakpoint} class can be sub-classed and, in
particular, you may choose to implement the @code{stop} method.
-If this method is defined as a sub-class of @code{gdb.Breakpoint},
+If this method is defined in a sub-class of @code{gdb.Breakpoint},
it will be called when the inferior reaches any location of a
breakpoint which instantiates that sub-class. If the method returns
@code{True}, the inferior will be stopped at the location of the
attribute is not writable.
@end defvar
+@defvar Breakpoint.temporary
+This attribute indicates whether the breakpoint was created as a
+temporary breakpoint. Temporary breakpoints are automatically deleted
+after that breakpoint has been hit. Access to this attribute, and all
+other attributes and functions other than the @code{is_valid}
+function, will result in an error after the breakpoint has been hit
+(as it has been automatically deleted). This attribute is not
+writable.
+@end defvar
+
The available types are represented by constants defined in the @code{gdb}
module:
@end ignore
* GDB/MI Target Manipulation::
* GDB/MI File Transfer Commands::
+* GDB/MI Ada Exceptions Commands::
* GDB/MI Miscellaneous Commands::
@end menu
@node Context management
@subsection Context management
+@subsubsection Threads and Frames
+
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
right, so it is suggested to just always pass the @samp{--thread} and
@samp{--frame} options.
+@subsubsection Language
+
+The execution of several commands depends on which language is selected.
+By default, the current language (@pxref{show language}) is used.
+But for commands known to be language-sensitive, it is recommended
+to use the @samp{--language} option. This option takes one argument,
+which is the name of the language to use while executing the command.
+For instance:
+
+@smallexample
+-data-evaluate-expression --language c "sizeof (void*)"
+^done,value="4"
+(gdb)
+@end smallexample
+
+The valid language names are the same names accepted by the
+@samp{set language} command (@pxref{Manually}), excluding @samp{auto},
+@samp{local} or @samp{unknown}.
+
@node Asynchronous and non-stop modes
@subsection Asynchronous command execution and non-stop mode
This section documents @sc{gdb/mi} commands for manipulating
catchpoints.
+@menu
+* Shared Library GDB/MI Catchpoint Commands::
+* Ada Exception GDB/MI Catchpoint Commands::
+@end menu
+
+@node Shared Library GDB/MI Catchpoint Commands
+@subsection Shared Library @sc{gdb/mi} Catchpoints
+
@subheading The @code{-catch-load} Command
@findex -catch-load
(gdb)
@end smallexample
+@node Ada Exception GDB/MI Catchpoint Commands
+@subsection Ada Exception @sc{gdb/mi} Catchpoints
+
+The following @sc{gdb/mi} commands can be used to create catchpoints
+that stop the execution when Ada exceptions are being raised.
+
+@subheading The @code{-catch-assert} Command
+@findex -catch-assert
+
+@subsubheading Synopsis
+
+@smallexample
+ -catch-assert [ -c @var{condition}] [ -d ] [ -t ]
+@end smallexample
+
+Add a catchpoint for failed Ada assertions.
+
+The possible optional parameters for this command are:
+
+@table @samp
+@item -c @var{condition}
+Make the catchpoint conditional on @var{condition}.
+@item -d
+Create a disabled catchpoint.
+@item -t
+Create a temporary catchpoint.
+@end table
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{catch assert}.
+
+@subsubheading Example
+
+@smallexample
+-catch-assert
+^done,bkptno="5",bkpt=@{number="5",type="breakpoint",disp="keep",
+enabled="y",addr="0x0000000000404888",what="failed Ada assertions",
+thread-groups=["i1"],times="0",
+original-location="__gnat_debug_raise_assert_failure"@}
+(gdb)
+@end smallexample
+
+@subheading The @code{-catch-exception} Command
+@findex -catch-exception
+
+@subsubheading Synopsis
+
+@smallexample
+ -catch-exception [ -c @var{condition}] [ -d ] [ -e @var{exception-name} ]
+ [ -t ] [ -u ]
+@end smallexample
+
+Add a catchpoint stopping when Ada exceptions are raised.
+By default, the command stops the program when any Ada exception
+gets raised. But it is also possible, by using some of the
+optional parameters described below, to create more selective
+catchpoints.
+
+The possible optional parameters for this command are:
+
+@table @samp
+@item -c @var{condition}
+Make the catchpoint conditional on @var{condition}.
+@item -d
+Create a disabled catchpoint.
+@item -e @var{exception-name}
+Only stop when @var{exception-name} is raised. This option cannot
+be used combined with @samp{-u}.
+@item -t
+Create a temporary catchpoint.
+@item -u
+Stop only when an unhandled exception gets raised. This option
+cannot be used combined with @samp{-e}.
+@end table
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} commands are @samp{catch exception}
+and @samp{catch exception unhandled}.
+
+@subsubheading Example
+
+@smallexample
+-catch-exception -e Program_Error
+^done,bkptno="4",bkpt=@{number="4",type="breakpoint",disp="keep",
+enabled="y",addr="0x0000000000404874",
+what="`Program_Error' Ada exception", thread-groups=["i1"],
+times="0",original-location="__gnat_debug_raise_exception"@}
+(gdb)
+@end smallexample
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Program Context
@subsubheading Synopsis
@smallexample
- -exec-run [--all | --thread-group N]
+ -exec-run [ --all | --thread-group N ] [ --start ]
@end smallexample
Starts execution of the inferior from the beginning. The inferior
exits. In the latter case the output will include an exit code, if
the program has exited exceptionally.
-When no option is specified, the current inferior is started. If the
+When neither the @samp{--all} nor the @samp{--thread-group} option
+is specified, the current inferior is started. If the
@samp{--thread-group} option is specified, it should refer to a thread
group of type @samp{process}, and that thread group will be started.
If the @samp{--all} option is specified, then all inferiors will be started.
+Using the @samp{--start} option instructs the debugger to stop
+the execution at the start of the inferior's main subprogram,
+following the same behavior as the @code{start} command
+(@pxref{Starting}).
+
@subsubheading @value{GDBN} Command
The corresponding @value{GDBN} command is @samp{run}.
@subsubheading Synopsis
@smallexample
- -stack-list-arguments [ --no-frame-filters ] @var{print-values}
+ -stack-list-arguments [ --no-frame-filters ] [ --skip-unavailable ] @var{print-values}
[ @var{low-frame} @var{high-frame} ]
@end smallexample
structures and unions. If the option @code{--no-frame-filters} is
supplied, then Python frame filters will not be executed.
+If the @code{--skip-unavailable} option is specified, arguments that
+are not available are not listed. Partially available arguments
+are still displayed, however.
Use of this command to obtain arguments in a single frame is
deprecated in favor of the @samp{-stack-list-variables} command.
@subsubheading Synopsis
@smallexample
- -stack-list-locals [ --no-frame-filters ] @var{print-values}
+ -stack-list-locals [ --no-frame-filters ] [ --skip-unavailable ] @var{print-values}
@end smallexample
Display the local variable names for the selected frame. If
more detail. If the option @code{--no-frame-filters} is supplied, then
Python frame filters will not be executed.
+If the @code{--skip-unavailable} option is specified, local variables
+that are not available are not listed. Partially available local
+variables are still displayed, however.
+
This command is deprecated in favor of the
@samp{-stack-list-variables} command.
@subsubheading Synopsis
@smallexample
- -stack-list-variables [ --no-frame-filters ] @var{print-values}
+ -stack-list-variables [ --no-frame-filters ] [ --skip-unavailable ] @var{print-values}
@end smallexample
Display the names of local variables and function arguments for the selected frame. If
structures and unions. If the option @code{--no-frame-filters} is
supplied, then Python frame filters will not be executed.
+If the @code{--skip-unavailable} option is specified, local variables
+and arguments that are not available are not listed. Partially
+available arguments and local variables are still displayed, however.
+
@subsubheading Example
@smallexample
@item frozen
If the variable object is frozen, this variable will be present with a value of 1.
+
+@item displayhint
+A dynamic varobj can supply a display hint to the front end. The
+value comes directly from the Python pretty-printer object's
+@code{display_hint} method. @xref{Pretty Printing API}.
+
+@item dynamic
+This attribute will be present and have the value @samp{1} if the
+varobj is a dynamic varobj. If the varobj is not a dynamic varobj,
+then this attribute will not be present.
+
@end table
The result may have its own attributes:
@end smallexample
@noindent
-Here, the values of @code{lang} can be @code{@{"C" | "C++" | "Java"@}}.
+Here, the value of @code{lang} is the language name, which can be
+found in @ref{Supported Languages}.
Note that the output of the @code{-var-list-children} command also
includes those expressions, so the @code{-var-info-expression} command
@subsubheading Synopsis
@smallexample
- -data-list-register-values @var{fmt} [ ( @var{regno} )*]
+ -data-list-register-values
+ [ @code{--skip-unavailable} ] @var{fmt} [ ( @var{regno} )*]
@end smallexample
Display the registers' contents. @var{fmt} is the format according to
which the registers' contents are to be returned, followed by an optional
list of numbers specifying the registers to display. A missing list of
-numbers indicates that the contents of all the registers must be returned.
+numbers indicates that the contents of all the registers must be
+returned. The @code{--skip-unavailable} option indicates that only
+the available registers are to be returned.
Allowed formats for @var{fmt} are:
The corresponding @value{GDBN} command is @samp{tvariable}.
+@subheading The @code{-trace-frame-collected} Command
+@findex -trace-frame-collected
+
+@subsubheading Synopsis
+
+@smallexample
+ -trace-frame-collected
+ [--var-print-values @var{var_pval}]
+ [--comp-print-values @var{comp_pval}]
+ [--registers-format @var{regformat}]
+ [--memory-contents]
+@end smallexample
+
+This command returns the set of collected objects, register names,
+trace state variable names, memory ranges and computed expressions
+that have been collected at a particular trace frame. The optional
+parameters to the command affect the output format in different ways.
+See the output description table below for more details.
+
+The reported names can be used in the normal manner to create
+varobjs and inspect the objects themselves. The items returned by
+this command are categorized so that it is clear which is a variable,
+which is a register, which is a trace state variable, which is a
+memory range and which is a computed expression.
+
+For instance, if the actions were
+@smallexample
+collect myVar, myArray[myIndex], myObj.field, myPtr->field, myCount + 2
+collect *(int*)0xaf02bef0@@40
+@end smallexample
+
+@noindent
+the object collected in its entirety would be @code{myVar}. The
+object @code{myArray} would be partially collected, because only the
+element at index @code{myIndex} would be collected. The remaining
+objects would be computed expressions.
+
+An example output would be:
+
+@smallexample
+(gdb)
+-trace-frame-collected
+^done,
+ explicit-variables=[@{name="myVar",value="1"@}],
+ computed-expressions=[@{name="myArray[myIndex]",value="0"@},
+ @{name="myObj.field",value="0"@},
+ @{name="myPtr->field",value="1"@},
+ @{name="myCount + 2",value="3"@},
+ @{name="$tvar1 + 1",value="43970027"@}],
+ registers=[@{number="0",value="0x7fe2c6e79ec8"@},
+ @{number="1",value="0x0"@},
+ @{number="2",value="0x4"@},
+ ...
+ @{number="125",value="0x0"@}],
+ tvars=[@{name="$tvar1",current="43970026"@}],
+ memory=[@{address="0x0000000000602264",length="4"@},
+ @{address="0x0000000000615bc0",length="4"@}]
+(gdb)
+@end smallexample
+
+Where:
+
+@table @code
+@item explicit-variables
+The set of objects that have been collected in their entirety (as
+opposed to collecting just a few elements of an array or a few struct
+members). For each object, its name and value are printed.
+The @code{--var-print-values} option affects how or whether the value
+field is output. If @var{var_pval} is 0, then print only the names;
+if it is 1, print also their values; and if it is 2, print the name,
+type and value for simple data types, and the name and type for
+arrays, structures and unions.
+
+@item computed-expressions
+The set of computed expressions that have been collected at the
+current trace frame. The @code{--comp-print-values} option affects
+this set like the @code{--var-print-values} option affects the
+@code{explicit-variables} set. See above.
+
+@item registers
+The registers that have been collected at the current trace frame.
+For each register collected, the name and current value are returned.
+The value is formatted according to the @code{--registers-format}
+option. See the @command{-data-list-register-values} command for a
+list of the allowed formats. The default is @samp{x}.
+
+@item tvars
+The trace state variables that have been collected at the current
+trace frame. For each trace state variable collected, the name and
+current value are returned.
+
+@item memory
+The set of memory ranges that have been collected at the current trace
+frame. Its content is a list of tuples. Each tuple represents a
+collected memory range and has the following fields:
+
+@table @code
+@item address
+The start address of the memory range, as hexadecimal literal.
+
+@item length
+The length of the memory range, as decimal literal.
+
+@item contents
+The contents of the memory block, in hex. This field is only present
+if the @code{--memory-contents} option is specified.
+
+@end table
+
+@end table
+
+@subsubheading @value{GDBN} Command
+
+There is no corresponding @value{GDBN} command.
+
+@subsubheading Example
+
@subheading -trace-list-variables
@findex -trace-list-variables
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Ada Exceptions Commands
+@section Ada Exceptions @sc{gdb/mi} Commands
+
+@subheading The @code{-info-ada-exceptions} Command
+@findex -info-ada-exceptions
+
+@subsubheading Synopsis
+
+@smallexample
+ -info-ada-exceptions [ @var{regexp}]
+@end smallexample
+
+List all Ada exceptions defined within the program being debugged.
+With a regular expression @var{regexp}, only those exceptions whose
+names match @var{regexp} are listed.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{info exceptions}.
+
+@subsubheading Result
+
+The result is a table of Ada exceptions. The following columns are
+defined for each exception:
+
+@table @samp
+@item name
+The name of the exception.
+
+@item address
+The address of the exception.
+
+@end table
+
+@subsubheading Example
+
+@smallexample
+-info-ada-exceptions aint
+^done,ada-exceptions=@{nr_rows="2",nr_cols="2",
+hdr=[@{width="1",alignment="-1",col_name="name",colhdr="Name"@},
+@{width="1",alignment="-1",col_name="address",colhdr="Address"@}],
+body=[@{name="constraint_error",address="0x0000000000613da0"@},
+@{name="const.aint_global_e",address="0x0000000000613b00"@}]@}
+@end smallexample
+
+@subheading Catching Ada Exceptions
+
+The commands describing how to ask @value{GDBN} to stop when a program
+raises an exception are described at @ref{Ada Exception GDB/MI
+Catchpoint Commands}.
+
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Miscellaneous Commands
@section Miscellaneous @sc{gdb/mi} Commands
CLI will be announced via async records.
@item ada-task-info
Indicates support for the @code{-ada-task-info} command.
+@item ada-exceptions
+Indicates support for the following commands, all of them related to Ada
+exceptions: @code{-info-ada-exceptions}, @code{-catch-assert} and
+@code{-catch-exception}.
+@item language-option
+Indicates that all @sc{gdb/mi} commands accept the @option{--language}
+option (@pxref{Context management}).
@end table
@subheading The @code{-list-target-features} Command
Example output:
@smallexample
-(gdb) -list-features
+(gdb) -list-target-features
^done,result=["async"]
@end smallexample
inferior is not associated with any executable. Such association may
be established with the @samp{-file-exec-and-symbols} command
(@pxref{GDB/MI File Commands}). The command response has a single
-field, @samp{thread-group}, whose value is the identifier of the
+field, @samp{inferior}, whose value is the identifier of the
thread group corresponding to the new inferior.
@subheading Example
@smallexample
@value{GDBP}
-add-inferior
-^done,thread-group="i3"
+^done,inferior="i3"
@end smallexample
@subheading The @code{-interpreter-exec} Command
started with the @code{set data-directory} command, the file will not be
reread.
-@node Installed System-wide Configuration Scripts
+@menu
+* System-wide Configuration Scripts:: Installed System-wide Configuration Scripts
+@end menu
+
+@node System-wide Configuration Scripts
@subsection Installed System-wide Configuration Scripts
@cindex system-wide configuration scripts
to user; the command @code{maint print register-groups} includes the
groups that each register is a member of; and the command @code{maint
print remote-registers} includes the remote target's register numbers
-and offsets in the `G' packets. @xref{Registers,, Registers, gdbint,
-@value{GDBN} Internals}.
+and offsets in the `G' packets.
These commands take an optional parameter, a file name to which to
write the information.
@kindex maint print objfiles
@cindex info for known object files
-@item maint print objfiles
-Print a dump of all known object files. For each object file, this
-command prints its name, address in memory, and all of its psymtabs
-and symtabs.
+@item maint print objfiles @r{[}@var{regexp}@r{]}
+Print a dump of all known object files.
+If @var{regexp} is specified, only print object files whose names
+match @var{regexp}. For each object file, this command prints its name,
+address in memory, and all of its psymtabs and symtabs.
@kindex maint print section-scripts
@cindex info for known .debug_gdb_scripts-loaded scripts
@item maint set show-debug-regs
@itemx maint show show-debug-regs
Control whether to show variables that mirror the hardware debug
-registers. Use @code{ON} to enable, @code{OFF} to disable. If
+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
triggers a hardware-assisted breakpoint or watchpoint.
@tab @samp{-}
@tab Yes
+@item @samp{qXfer:libraries-svr4:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
+@item @samp{augmented-libraries-svr4-read}
+@tab No
+@tab @samp{-}
+@tab No
+
@item @samp{qXfer:memory-map:read}
@tab No
@tab @samp{-}
The remote stub understands the @samp{qXfer:libraries-svr4:read} packet
(@pxref{qXfer svr4 library list read}).
+@item augmented-libraries-svr4-read
+The remote stub understands the augmented form of the
+@samp{qXfer:libraries-svr4:read} packet
+(@pxref{qXfer svr4 library list read}).
+
@item qXfer:memory-map:read
The remote stub understands the @samp{qXfer:memory-map:read} packet
(@pxref{qXfer memory map read}).
@anchor{qXfer svr4 library list read}
Access the target's list of loaded libraries when the target is an SVR4
platform. @xref{Library List Format for SVR4 Targets}. The annex part
-of the generic @samp{qXfer} packet must be empty (@pxref{qXfer read}).
+of the generic @samp{qXfer} packet must be empty unless the remote
+stub indicated it supports the augmented form of this packet
+by supplying an appropriate @samp{qSupported} response
+(@pxref{qXfer read}, @ref{qSupported}).
This packet is optional for better performance on SVR4 targets.
@value{GDBN} uses memory read packets to read the SVR4 library list otherwise.
This packet is not probed by default; the remote stub must request it,
by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+If the remote stub indicates it supports the augmented form of this
+packet then the annex part of the generic @samp{qXfer} packet may
+contain a semicolon-separated list of @samp{@var{name}=@var{value}}
+arguments. The currently supported arguments are:
+
+@table @code
+@item start=@var{address}
+A hexadecimal number specifying the address of the @samp{struct
+link_map} to start reading the library list from. If unset or zero
+then the first @samp{struct link_map} in the library list will be
+chosen as the starting point.
+
+@item prev=@var{address}
+A hexadecimal number specifying the address of the @samp{struct
+link_map} immediately preceding the @samp{struct link_map}
+specified by the @samp{start} argument. If unset or zero then
+the remote stub will expect that no @samp{struct link_map}
+exists prior to the starting point.
+
+@end table
+
+Arguments that are not understood by the remote stub will be silently
+ignored.
+
@item qXfer:memory-map:read::@var{offset},@var{length}
@anchor{qXfer memory map read}
Access the target's @dfn{memory-map}. @xref{Memory Map Format}. The
<memory start="@var{addr}" length="@var{length}"/>
@end smallexample
+@item
+A block indicating trace state variable numbered @var{number} has been
+collected:
+
+@smallexample
+<tvar id="@var{number}"/>
+@end smallexample
+
@end itemize
The formal DTD for the traceframe info format is given below:
@smallexample
-<!ELEMENT traceframe-info (memory)* >
+<!ELEMENT traceframe-info (memory | tvar)* >
<!ATTLIST traceframe-info version CDATA #FIXED "1.0">
<!ELEMENT memory EMPTY>
<!ATTLIST memory start CDATA #REQUIRED
length CDATA #REQUIRED>
+<!ELEMENT tvar>
+<!ATTLIST tvar id CDATA #REQUIRED>
@end smallexample
@node Branch Trace Format
* M68K Features::
* Nios II Features::
* PowerPC Features::
+* S/390 and System z Features::
* TIC6x Features::
@end menu
these to present registers @samp{ev0} through @samp{ev31} to the
user.
+@node S/390 and System z Features
+@subsection S/390 and System z Features
+@cindex target descriptions, S/390 features
+@cindex target descriptions, System z features
+
+The @samp{org.gnu.gdb.s390.core} feature is required for S/390 and
+System z targets. It should contain the PSW and the 16 general
+registers. In particular, System z targets should provide the 64-bit
+registers @samp{pswm}, @samp{pswa}, and @samp{r0} through @samp{r15}.
+S/390 targets should provide the 32-bit versions of these registers.
+A System z target that runs in 31-bit addressing mode should provide
+32-bit versions of @samp{pswm} and @samp{pswa}, as well as the general
+register's upper halves @samp{r0h} through @samp{r15h}, and their
+lower halves @samp{r0l} through @samp{r15l}.
+
+The @samp{org.gnu.gdb.s390.fpr} feature is required. It should
+contain the 64-bit registers @samp{f0} through @samp{f15}, and
+@samp{fpc}.
+
+The @samp{org.gnu.gdb.s390.acr} feature is required. It should
+contain the 32-bit registers @samp{acr0} through @samp{acr15}.
+
+The @samp{org.gnu.gdb.s390.linux} feature is optional. It should
+contain the register @samp{orig_r2}, which is 64-bit wide on System z
+targets and 32-bit otherwise. In addition, the feature may contain
+the @samp{last_break} register, whose width depends on the addressing
+mode, as well as the @samp{system_call} register, which is always
+32-bit wide.
+
+The @samp{org.gnu.gdb.s390.tdb} feature is optional. It should
+contain the 64-bit registers @samp{tdb0}, @samp{tac}, @samp{tct},
+@samp{atia}, and @samp{tr0} through @samp{tr15}.
+
@node TIC6x Features
@subsection TMS320C6x Features
@cindex target descriptions, TIC6x features
projects / platform / upstream / binutils.git / blobdiff