@value{GDBP} @var{program} @var{core}
@end smallexample
-You can, instead, specify a process ID as a second argument, if you want
-to debug a running process:
+You can, instead, specify a process ID as a second argument or use option
+@code{-p}, if you want to debug a running process:
@smallexample
@value{GDBP} @var{program} 1234
+@value{GDBP} -p 1234
@end smallexample
@noindent
-would attach @value{GDBN} to process @code{1234} (unless you also have a file
-named @file{1234}; @value{GDBN} does check for a core file first).
+would attach @value{GDBN} to process @code{1234}. With option @option{-p} you
+can omit the @var{program} filename.
Taking advantage of the second command-line argument requires a fairly
complete operating system; when you use @value{GDBN} as a remote
configure option (@pxref{System-wide configuration}).
It is loaded first when @value{GDBN} starts, before command line options
have been processed.
+@item @file{system.gdbinit.d}
+This is the system-wide init directory.
+Its location is specified with the @code{--with-system-gdbinit-dir}
+configure option (@pxref{System-wide configuration}).
+Files in this directory are loaded in alphabetical order immediately after
+system.gdbinit (if enabled) when @value{GDBN} starts, before command line
+options have been processed. Files need to have a recognized scripting
+language extension (@file{.py}/@file{.scm}) or be named with a @file{.gdb}
+extension to be interpreted as regular @value{GDBN} commands. @value{GDBN}
+will not recurse into any subdirectories of this directory.
@item @file{~/.gdbinit}
This is the init file in your home directory.
It is loaded next, after @file{system.gdbinit}, and before
@cindex init file
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.
+ ,System-wide configuration and settings}) and the files in the system-wide
+gdbinit directory (if @option{--with-system-gdbinit-dir} was used) and executes
+all the commands in those files. The files need to be named with a @file{.gdb}
+extension to be interpreted as @value{GDBN} commands, or they can be written
+in a supported scripting language with an appropriate file extension.
@anchor{Home Directory Init File}
@item
arguments. This is equivalent to @samp{shell make @var{make-args}}.
@end table
+@table @code
+@kindex pipe
+@kindex |
+@cindex send the output of a gdb command to a shell command
+@anchor{pipe}
+@item pipe [@var{command}] | @var{shell_command}
+@itemx | [@var{command}] | @var{shell_command}
+@itemx pipe -d @var{delim} @var{command} @var{delim} @var{shell_command}
+@itemx | -d @var{delim} @var{command} @var{delim} @var{shell_command}
+Executes @var{command} and sends its output to @var{shell_command}.
+Note that no space is needed around @code{|}.
+If no @var{command} is provided, the last command executed is repeated.
+
+In case the @var{command} contains a @code{|}, the option @code{-d @var{delim}}
+can be used to specify an alternate delimiter string @var{delim} that separates
+the @var{command} from the @var{shell_command}.
+
+Example:
+@smallexample
+@group
+(gdb) p var
+$1 = @{
+ black = 144,
+ red = 233,
+ green = 377,
+ blue = 610,
+ white = 987
+@}
+@end group
+@group
+(gdb) pipe p var|wc
+ 7 19 80
+(gdb) |p var|wc -l
+7
+@end group
+@group
+(gdb) p /x var
+$4 = @{
+ black = 0x90,
+ red = 0xe9,
+ green = 0x179,
+ blue = 0x262,
+ white = 0x3db
+@}
+(gdb) ||grep red
+ red => 0xe9,
+@end group
+@group
+(gdb) | -d ! echo this contains a | char\n ! sed -e 's/|/PIPE/'
+this contains a PIPE char
+(gdb) | -d xxx echo this contains a | char!\n xxx sed -e 's/|/PIPE/'
+this contains a PIPE char!
+(gdb)
+@end group
+@end smallexample
+@end table
+
+The convenience variables @code{$_shell_exitcode} and @code{$_shell_exitsignal}
+can be used to examine the exit status of the last shell command launched
+by @code{shell}, @code{make}, @code{pipe} and @code{|}.
+@xref{Convenience Vars,, Convenience Variables}.
+
@node Logging Output
@section Logging Output
@cindex logging @value{GDBN} output
@item set logging redirect [on|off]
By default, @value{GDBN} output will go to both the terminal and the logfile.
Set @code{redirect} if you want output to go only to the log file.
+@item set logging debugredirect [on|off]
+By default, @value{GDBN} debug output will go to both the terminal and the logfile.
+Set @code{debugredirect} if you want debug output to go only to the log file.
@kindex show logging
@item show logging
Show the current values of the logging settings.
@end table
+You can also redirect the output of a @value{GDBN} command to a
+shell command. @xref{pipe}.
@node Commands
@chapter @value{GDBN} Commands
@menu
* Command Syntax:: How to give commands to @value{GDBN}
+* Command Settings:: How to change default behavior of commands
* Completion:: Command completion
+* Command Options:: Command options
* Help:: How to ask @value{GDBN} for help
@end menu
then fetches the next line relative to the current line from the history
for editing.
+
+@node Command Settings
+@section Command Settings
+@cindex default behavior of commands, changing
+@cindex default settings, changing
+
+Many commands change their behavior according to command-specific
+variables or settings. These settings can be changed with the
+@code{set} subcommands. For example, the @code{print} command
+(@pxref{Data, ,Examining Data}) prints arrays differently depending on
+settings changeable with the commands @code{set print elements
+NUMBER-OF-ELEMENTS} and @code{set print array-indexes}, among others.
+
+You can change these settings to your preference in the gdbinit files
+loaded at @value{GDBN} startup. @xref{Startup}.
+
+The settings can also be changed interactively during the debugging
+session. For example, to change the limit of array elements to print,
+you can do the following:
+@smallexample
+(@value{GDBN}) set print elements 10
+(@value{GDBN}) print some_array
+$1 = @{0, 10, 20, 30, 40, 50, 60, 70, 80, 90...@}
+@end smallexample
+
+The above @code{set print elements 10} command changes the number of
+elements to print from the default of 200 to 10. If you only intend
+this limit of 10 to be used for printing @code{some_array}, then you
+must restore the limit back to 200, with @code{set print elements
+200}.
+
+Some commands allow overriding settings with command options. For
+example, the @code{print} command supports a number of options that
+allow overriding relevant global print settings as set by @code{set
+print} subcommands. @xref{print options}. The example above could be
+rewritten as:
+@smallexample
+(@value{GDBN}) print -elements 10 -- some_array
+$1 = @{0, 10, 20, 30, 40, 50, 60, 70, 80, 90...@}
+@end smallexample
+
+Alternatively, you can use the @code{with} command to change a setting
+temporarily, for the duration of a command invocation.
+
+@table @code
+@kindex with command
+@kindex w @r{(@code{with})}
+@cindex settings
+@cindex temporarily change settings
+@item with @var{setting} [@var{value}] [-- @var{command}]
+@itemx w @var{setting} [@var{value}] [-- @var{command}]
+Temporarily set @var{setting} to @var{value} for the duration of
+@var{command}.
+
+@var{setting} is any setting you can change with the @code{set}
+subcommands. @var{value} is the value to assign to @code{setting}
+while running @code{command}.
+
+If no @var{command} is provided, the last command executed is
+repeated.
+
+If a @var{command} is provided, it must be preceded by a double dash
+(@code{--}) separator. This is required because some settings accept
+free-form arguments, such as expressions or filenames.
+
+For example, the command
+@smallexample
+(@value{GDBN}) with print array on -- print some_array
+@end smallexample
+@noindent
+is equivalent to the following 3 commands:
+@smallexample
+(@value{GDBN}) set print array on
+(@value{GDBN}) print some_array
+(@value{GDBN}) set print array off
+@end smallexample
+
+The @code{with} command is particularly useful when you want to
+override a setting while running user-defined commands, or commands
+defined in Python or Guile. @xref{Extending GDB,, Extending GDB}.
+
+@smallexample
+(@value{GDBN}) with print pretty on -- my_complex_command
+@end smallexample
+
+To change several settings for the same command, you can nest
+@code{with} commands. For example, @code{with language ada -- with
+print elements 10} temporarily changes the language to Ada and sets a
+limit of 10 elements to print for arrays and strings.
+
+@end table
+
@node Completion
@section Command Completion
@value{GDBN} can fill in the rest of a word in a command for you, if there is
only one possibility; it can also show you what the valid possibilities
are for the next word in a command, at any time. This works for @value{GDBN}
-commands, @value{GDBN} subcommands, and the names of symbols in your program.
+commands, @value{GDBN} subcommands, command options, and the names of symbols
+in your program.
Press the @key{TAB} key whenever you want @value{GDBN} to fill out the rest
of a word. If there is only one possibility, @value{GDBN} fills in the
@}
@end smallexample
+@node Command Options
+@section Command options
+
+@cindex command options
+Some commands accept options starting with a leading dash. For
+example, @code{print -pretty}. Similarly to command names, you can
+abbreviate a @value{GDBN} option to the first few letters of the
+option name, if that abbreviation is unambiguous, and you can also use
+the @key{TAB} key to get @value{GDBN} to fill out the rest of a word
+in an option (or to show you the alternatives available, if there is
+more than one possibility).
+
+@cindex command options, raw input
+Some commands take raw input as argument. For example, the print
+command processes arbitrary expressions in any of the languages
+supported by @value{GDBN}. With such commands, because raw input may
+start with a leading dash that would be confused with an option or any
+of its abbreviations, e.g.@: @code{print -r} (short for @code{print
+-raw} or printing negative @code{r}?), if you specify any command
+option, then you must use a double-dash (@code{--}) delimiter to
+indicate the end of options.
+
+@cindex command options, boolean
+
+Some options are described as accepting an argument which can be
+either @code{on} or @code{off}. These are known as @dfn{boolean
+options}. Similarly to boolean settings commands---@code{on} and
+@code{off} are the typical values, but any of @code{1}, @code{yes} and
+@code{enable} can also be used as ``true'' value, and any of @code{0},
+@code{no} and @code{disable} can also be used as ``false'' value. You
+can also omit a ``true'' value, as it is implied by default.
+
+For example, these are equivalent:
+
+@smallexample
+(@value{GDBP}) print -object on -pretty off -element unlimited -- *myptr
+(@value{GDBP}) p -o -p 0 -e u -- *myptr
+@end smallexample
+
+You can discover the set of options some command accepts by completing
+on @code{-} after the command name. For example:
+
+@smallexample
+(@value{GDBP}) print -@key{TAB}@key{TAB}
+-address -max-depth -repeats -vtbl
+-array -null-stop -static-members
+-array-indexes -object -symbol
+-elements -pretty -union
+@end smallexample
+
+Completion will in some cases guide you with a suggestion of what kind
+of argument an option expects. For example:
+
+@smallexample
+(@value{GDBP}) print -elements @key{TAB}@key{TAB}
+NUMBER unlimited
+@end smallexample
+
+Here, the option expects a number (e.g., @code{100}), not literal
+@code{NUMBER}. Such metasyntactical arguments are always presented in
+uppercase.
+
+(For more on using the @code{print} command, see @ref{Data, ,Examining
+Data}.)
@node Help
@section Getting Help
short paragraph on how to use that command.
@kindex apropos
-@item apropos @var{args}
+@item apropos [-v] @var{regexp}
The @code{apropos} command searches through all of the @value{GDBN}
commands, and their documentation, for the regular expression specified in
-@var{args}. It prints out all matches found. For example:
+@var{args}. It prints out all matches found. The optional flag @samp{-v},
+which stands for @samp{verbose}, indicates to output the full documentation
+of the matching commands and highlight the parts of the documentation
+matching @var{regexp}. For example:
@smallexample
apropos alias
results in:
@smallexample
-@c @group
+@group
alias -- Define a new command that is an alias of an existing command
aliases -- Aliases of other commands
d -- Delete some breakpoints or auto-display expressions
del -- Delete some breakpoints or auto-display expressions
delete -- Delete some breakpoints or auto-display expressions
-@c @end group
+@end group
+@end smallexample
+
+@noindent
+while
+
+@smallexample
+apropos -v cut.*thread apply
+@end smallexample
+
+@noindent
+results in the below output, where @samp{cut for 'thread apply}
+is highlighted if styling is enabled.
+
+@smallexample
+@group
+taas -- Apply a command to all threads (ignoring errors
+and empty output).
+Usage: taas COMMAND
+shortcut for 'thread apply all -s COMMAND'
+
+tfaas -- Apply a command to all frames of all threads
+(ignoring errors and empty output).
+Usage: tfaas COMMAND
+shortcut for 'thread apply all -s frame apply all -s COMMAND'
+@end group
@end smallexample
@kindex complete
@samp{Switching to} depends on your system's conventions for identifying
threads.
+@anchor{thread apply all}
@kindex thread apply
@cindex apply command to several threads
@item thread apply [@var{thread-id-list} | all [-ascending]] [@var{flag}]@dots{} @var{command}
@kindex taas
@cindex apply command to all threads (ignoring errors and empty output)
-@item taas @var{command}
-Shortcut for @code{thread apply all -s @var{command}}.
+@item taas [@var{option}]@dots{} @var{command}
+Shortcut for @code{thread apply all -s [@var{option}]@dots{} @var{command}}.
Applies @var{command} on all threads, ignoring errors and empty output.
+The @code{taas} command accepts the same options as the @code{thread
+apply all} command. @xref{thread apply all}.
+
@kindex tfaas
@cindex apply a command to all frames of all threads (ignoring errors and empty output)
-@item tfaas @var{command}
-Shortcut for @code{thread apply all -s frame apply all -s @var{command}}.
+@item tfaas [@var{option}]@dots{} @var{command}
+Shortcut for @code{thread apply all -s -- frame apply all -s [@var{option}]@dots{} @var{command}}.
Applies @var{command} on all frames of all threads, ignoring errors
and empty output. Note that the flag @code{-s} is specified twice:
The first @code{-s} ensures that @code{thread apply} only shows the thread
(@value{GDBP}) tfaas p some_local_var_i_do_not_remember_where_it_is
@end smallexample
+The @code{tfaas} command accepts the same options as the @code{frame
+apply} command. @xref{frame apply}.
@kindex thread name
@cindex name a thread
You cannot install an exception handler interactively.
@end itemize
-@item exception
+@item exception @r{[}@var{name}@r{]}
@kindex catch exception
@cindex Ada exception catching
@cindex catch Ada exceptions
the command to use to catch such exceptions is @kbd{catch exception
Pck.Constraint_Error}.
-@item handlers
+@vindex $_ada_exception@r{, convenience variable}
+The convenience variable @code{$_ada_exception} holds the address of
+the exception being thrown. This can be useful when setting a
+condition for such a catchpoint.
+
+@item exception unhandled
+@kindex catch exception unhandled
+An exception that was raised but is not handled by the program. The
+convenience variable @code{$_ada_exception} is set as for @code{catch
+exception}.
+
+@item handlers @r{[}@var{name}@r{]}
@kindex catch handlers
@cindex Ada exception handlers catching
@cindex catch Ada exceptions when handled
command to use to catch such exceptions handling is
@kbd{catch handlers Pck.Constraint_Error}.
-@item exception unhandled
-@kindex catch exception unhandled
-An exception that was raised but is not handled by the program.
+The convenience variable @code{$_ada_exception} is set as for
+@code{catch exception}.
@item assert
@kindex catch assert
-A failed Ada assertion.
+A failed Ada assertion. Note that the convenience variable
+@code{$_ada_exception} is @emph{not} set by this catchpoint.
@item exec
@kindex catch exec
@kindex catch vfork
A call to @code{vfork}.
-@item load @r{[}regexp@r{]}
-@itemx unload @r{[}regexp@r{]}
+@item load @r{[}@var{regexp}@r{]}
+@itemx unload @r{[}@var{regexp}@r{]}
@kindex catch load
@kindex catch unload
The loading or unloading of a shared library. If @var{regexp} is
Contrast this with the @code{return} command (@pxref{Returning,
,Returning from a Function}).
+@kindex set print finish
+@kindex show print finish
+@item set print finish @r{[}on|off@r{]}
+@itemx show print finish
+By default the @code{finish} command will show the value that is
+returned by the function. This can be disabled using @code{set print
+finish off}. When disabled, the value is still entered into the value
+history (@pxref{Value History}), but not displayed.
+
@kindex until
@kindex u @r{(@code{until})}
@cindex run until specified location
consistant state, but @value{GDBN} accepts whatever it is given.
}.
+On some platforms, @value{GDBN} has built-in support for reverse
+execution, activated with the @code{record} or @code{record btrace}
+commands. @xref{Process Record and Replay}. Some remote targets,
+typically full system emulators, support reverse execution directly
+without requiring any special command.
+
If you are debugging in a target environment that supports
reverse execution, @value{GDBN} provides the following commands.
previous instruction; otherwise, it will work in record mode, if the
platform supports reverse execution, or stop if not.
+Currently, process record and replay is supported on ARM, Aarch64,
+Moxie, PowerPC, PowerPC64, S/390, and x86 (i386/amd64) running
+GNU/Linux. Process record and replay can be used both when native
+debugging, and when remote debugging via @code{gdbserver}.
+
For architecture environments that support process record and replay,
@value{GDBN} provides the following commands:
execution.
@item btrace @var{format}
-Hardware-supported instruction recording. This method does not record
-data. Further, the data is collected in a ring buffer so old data will
-be overwritten when the buffer is full. It allows limited reverse
-execution. Variables and registers are not available during reverse
-execution. In remote debugging, recording continues on disconnect.
-Recorded data can be inspected after reconnecting. The recording may
-be stopped using @code{record stop}.
+Hardware-supported instruction recording, supported on Intel
+processors. This method does not record data. Further, the data is
+collected in a ring buffer so old data will be overwritten when the
+buffer is full. It allows limited reverse execution. Variables and
+registers are not available during reverse execution. In remote
+debugging, recording continues on disconnect. Recorded data can be
+inspected after reconnecting. The recording may be stopped using
+@code{record stop}.
The recording format can be specified as parameter. Without a parameter
the command chooses the recording format. The following recording
interrupt character, normally @kbd{Ctrl-c}.
@table @code
-@item backtrace [@var{args}@dots{}]
-@itemx bt [@var{args}@dots{}]
-Print the backtrace of the entire stack. The optional @var{args} can
-be one of the following:
+@item backtrace [@var{option}]@dots{} [@var{qualifier}]@dots{} [@var{count}]
+@itemx bt [@var{option}]@dots{} [@var{qualifier}]@dots{} [@var{count}]
+Print the backtrace of the entire stack.
+
+The optional @var{count} can be one of the following:
@table @code
@item @var{n}
@itemx -@var{n}
Print only the outermost @var{n} frames, where @var{n} is a positive
number.
+@end table
-@item full
+Options:
+
+@table @code
+@item -full
Print the values of the local variables also. This can be combined
-with a number to limit the number of frames shown.
+with the optional @var{count} to limit the number of frames shown.
-@item no-filters
+@item -no-filters
Do not run Python frame filters on this backtrace. @xref{Frame
Filter API}, for more information. Additionally use @ref{disable
frame-filter all} to turn off all frame filters. This is only
relevant when @value{GDBN} has been configured with @code{Python}
support.
-@item hide
+@item -hide
A Python frame filter might decide to ``elide'' some frames. Normally
such elided frames are still printed, but they are indented relative
-to the filtered frames that cause them to be elided. The @code{hide}
+to the filtered frames that cause them to be elided. The @code{-hide}
option causes elided frames to not be printed at all.
@end table
+
+The @code{backtrace} command also supports a number of options that
+allow overriding relevant global print settings as set by @code{set
+backtrace} and @code{set print} subcommands:
+
+@table @code
+@item -past-main [@code{on}|@code{off}]
+Set whether backtraces should continue past @code{main}. Related setting:
+@ref{set backtrace past-main}.
+
+@item -past-entry [@code{on}|@code{off}]
+Set whether backtraces should continue past the entry point of a program.
+Related setting: @ref{set backtrace past-entry}.
+
+@item -entry-values @code{no}|@code{only}|@code{preferred}|@code{if-needed}|@code{both}|@code{compact}|@code{default}
+Set printing of function arguments at function entry.
+Related setting: @ref{set print entry-values}.
+
+@item -frame-arguments @code{all}|@code{scalars}|@code{none}
+Set printing of non-scalar frame arguments.
+Related setting: @ref{set print frame-arguments}.
+
+@item -raw-frame-arguments [@code{on}|@code{off}]
+Set whether to print frame arguments in raw form.
+Related setting: @ref{set print raw-frame-arguments}.
+
+@item -frame-info @code{auto}|@code{source-line}|@code{location}|@code{source-and-location}|@code{location-and-address}|@code{short-location}
+Set printing of frame information.
+Related setting: @ref{set print frame-info}.
+@end table
+
+The optional @var{qualifier} is maintained for backward compatibility.
+It can be one of the following:
+
+@table @code
+@item full
+Equivalent to the @code{-full} option.
+
+@item no-filters
+Equivalent to the @code{-no-filters} option.
+
+@item hide
+Equivalent to the @code{-hide} option.
+@end table
+
@end table
@kindex where
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.
+The command @kbd{set print frame-info} (@pxref{Print Settings}) controls
+what frame information is printed.
@cindex optimized out, in backtrace
@cindex function call arguments, optimized out
@table @code
@item set backtrace past-main
@itemx set backtrace past-main on
+@anchor{set backtrace past-main}
@kindex set backtrace
Backtraces will continue past the user entry point.
@item set backtrace past-entry
@itemx set backtrace past-entry on
+@anchor{set backtrace past-entry}
Backtraces will continue past the internal entry point of an application.
This entry point is encoded by the linker when the application is built,
and is likely before the user entry point @code{main} (or equivalent) is called.
@item set backtrace limit @var{n}
@itemx set backtrace limit 0
@itemx set backtrace limit unlimited
+@anchor{set backtrace limit}
@cindex backtrace limit
Limit the backtrace to @var{n} levels. A value of @code{unlimited}
or zero means unlimited levels.
@node Frame Apply
@section Applying a Command to Several Frames.
+@anchor{frame apply}
@kindex frame apply
@cindex apply command to several frames
@table @code
-@item frame apply [all | @var{count} | @var{-count} | level @var{level}@dots{}] [@var{flag}]@dots{} @var{command}
+@item frame apply [all | @var{count} | @var{-count} | level @var{level}@dots{}] [@var{option}]@dots{} @var{command}
The @code{frame apply} command allows you to apply the named
@var{command} to one or more frames.
@end table
-@end table
-
Note that the frames on which @code{frame apply} applies a command are
also influenced by the @code{set backtrace} settings such as @code{set
-backtrace past-main} and @code{set backtrace limit N}. See
+backtrace past-main} and @code{set backtrace limit N}.
@xref{Backtrace,,Backtraces}.
-The @var{flag} arguments control what output to produce and how to handle
-errors raised when applying @var{command} to a frame. @var{flag}
-must start with a @code{-} directly followed by one letter in
-@code{qcs}. If several flags are provided, they must be given
-individually, such as @code{-c -q}.
+The @code{frame apply} command also supports a number of options that
+allow overriding relevant @code{set backtrace} settings:
+
+@table @code
+@item -past-main [@code{on}|@code{off}]
+Whether backtraces should continue past @code{main}.
+Related setting: @ref{set backtrace past-main}.
+
+@item -past-entry [@code{on}|@code{off}]
+Whether backtraces should continue past the entry point of a program.
+Related setting: @ref{set backtrace past-entry}.
+@end table
By default, @value{GDBN} displays some frame information before the
output produced by @var{command}, and an error raised during the
execution of a @var{command} will abort @code{frame apply}. The
-following flags can be used to fine-tune this behavior:
+following options can be used to fine-tune these behaviors:
@table @code
@item -c
@end group
@end smallexample
-If flag @code{-q} is given, no frame information is printed:
+If the flag @code{-q} is given, no frame information is printed:
@smallexample
@group
(gdb) frame apply all -q p $sp
@end group
@end smallexample
+@end table
+
@table @code
@kindex faas
(@value{GDBP}) faas p some_local_var_i_do_not_remember_where_it_is
@end smallexample
+The @code{faas} command accepts the same options as the @code{frame
+apply} command. @xref{frame apply}.
+
Note that the command @code{tfaas @var{command}} applies @var{command}
on all frames of all threads. See @xref{Threads,,Threads}.
@end table
in the list, until it finds a file with the desired name.
For example, suppose an executable references the file
-@file{/usr/src/foo-1.0/lib/foo.c}, and our source path is
-@file{/mnt/cross}. The file is first looked up literally; if this
-fails, @file{/mnt/cross/usr/src/foo-1.0/lib/foo.c} is tried; if this
-fails, @file{/mnt/cross/foo.c} is opened; if this fails, an error
-message is printed. @value{GDBN} does not look up the parts of the
+@file{/usr/src/foo-1.0/lib/foo.c}, does not record a compilation
+directory, and the @dfn{source path} is @file{/mnt/cross}.
+@value{GDBN} would look for the source file in the following
+locations:
+
+@enumerate
+
+@item @file{/usr/src/foo-1.0/lib/foo.c}
+@item @file{/mnt/cross/usr/src/foo-1.0/lib/foo.c}
+@item @file{/mnt/cross/foo.c}
+
+@end enumerate
+
+If the source file is not present at any of the above locations then
+an error is printed. @value{GDBN} does not look up the parts of the
source file name, such as @file{/mnt/cross/src/foo-1.0/lib/foo.c}.
Likewise, the subdirectories of the source path are not searched: if
the source path is @file{/mnt/cross}, and the binary refers to
@file{/mnt/cross/usr/src/foo-1.0/lib}.
Plain file names, relative file names with leading directories, file
-names containing dots, etc.@: are all treated as described above; for
-instance, if the source path is @file{/mnt/cross}, and the source file
-is recorded as @file{../lib/foo.c}, @value{GDBN} would first try
-@file{../lib/foo.c}, then @file{/mnt/cross/../lib/foo.c}, and after
-that---@file{/mnt/cross/foo.c}.
+names containing dots, etc.@: are all treated as described above,
+except that non-absolute file names are not looked up literally. If
+the @dfn{source path} is @file{/mnt/cross}, the source file is
+recorded as @file{../lib/foo.c}, and no compilation directory is
+recorded, then @value{GDBN} will search in the following locations:
+
+@enumerate
+
+@item @file{/mnt/cross/../lib/foo.c}
+@item @file{/mnt/cross/foo.c}
+
+@end enumerate
+
+@kindex cdir
+@kindex cwd
+@vindex $cdir@r{, convenience variable}
+@vindex $cwd@r{, convenience variable}
+@cindex compilation directory
+@cindex current directory
+@cindex working directory
+@cindex directory, current
+@cindex directory, compilation
+The @dfn{source path} will always include two special entries
+@samp{$cdir} and @samp{$cwd}, these refer to the compilation directory
+(if one is recorded) and the current working directory respectively.
+
+@samp{$cdir} causes @value{GDBN} to search within the compilation
+directory, if one is recorded in the debug information. If no
+compilation directory is recorded in the debug information then
+@samp{$cdir} is ignored.
+
+@samp{$cwd} is not the same as @samp{.}---the former tracks the
+current working directory as it changes during your @value{GDBN}
+session, while the latter is immediately expanded to the current
+directory at the time you add an entry to the source path.
+
+If a compilation directory is recorded in the debug information, and
+@value{GDBN} has not found the source file after the first search
+using @dfn{source path}, then @value{GDBN} will combine the
+compilation directory and the filename, and then search for the source
+file again using the @dfn{source path}.
+
+For example, if the executable records the source file as
+@file{/usr/src/foo-1.0/lib/foo.c}, the compilation directory is
+recorded as @file{/project/build}, and the @dfn{source path} is
+@file{/mnt/cross:$cdir:$cwd} while the current working directory of
+the @value{GDBN} session is @file{/home/user}, then @value{GDBN} will
+search for the source file in the following loctions:
+
+@enumerate
+
+@item @file{/usr/src/foo-1.0/lib/foo.c}
+@item @file{/mnt/cross/usr/src/foo-1.0/lib/foo.c}
+@item @file{/project/build/usr/src/foo-1.0/lib/foo.c}
+@item @file{/home/user/usr/src/foo-1.0/lib/foo.c}
+@item @file{/mnt/cross/project/build/usr/src/foo-1.0/lib/foo.c}
+@item @file{/project/build/project/build/usr/src/foo-1.0/lib/foo.c}
+@item @file{/home/user/project/build/usr/src/foo-1.0/lib/foo.c}
+@item @file{/mnt/cross/foo.c}
+@item @file{/project/build/foo.c}
+@item @file{/home/user/foo.c}
+
+@end enumerate
+
+If the file name in the previous example had been recorded in the
+executable as a relative path rather than an absolute path, then the
+first look up would not have occurred, but all of the remaining steps
+would be similar.
+
+When searching for source files on MS-DOS and MS-Windows, where
+absolute paths start with a drive letter (e.g.
+@file{C:/project/foo.c}), @value{GDBN} will remove the drive letter
+from the file name before appending it to a search directory from
+@dfn{source path}; for instance if the executable references the
+source file @file{C:/project/foo.c} and @dfn{source path} is set to
+@file{D:/mnt/cross}, then @value{GDBN} will search in the following
+locations for the source file:
+
+@enumerate
+
+@item @file{C:/project/foo.c}
+@item @file{D:/mnt/cross/project/foo.c}
+@item @file{D:/mnt/cross/foo.c}
+
+@end enumerate
Note that the executable search path is @emph{not} used to locate the
source files.
@kindex directory
@kindex dir
-When you start @value{GDBN}, its source path includes only @samp{cdir}
-and @samp{cwd}, in that order.
+When you start @value{GDBN}, its source path includes only @samp{$cdir}
+and @samp{$cwd}, in that order.
To add other directories, use the @code{directory} command.
The search path is used to find both program source files and @value{GDBN}
whitespace. You may specify a directory that is already in the source
path; this moves it forward, so @value{GDBN} searches it sooner.
-@kindex cdir
-@kindex cwd
-@vindex $cdir@r{, convenience variable}
-@vindex $cwd@r{, convenience variable}
-@cindex compilation directory
-@cindex current directory
-@cindex working directory
-@cindex directory, current
-@cindex directory, compilation
-You can use the string @samp{$cdir} to refer to the compilation
-directory (if one is recorded), and @samp{$cwd} to refer to the current
-working directory. @samp{$cwd} is not the same as @samp{.}---the former
-tracks the current working directory as it changes during your @value{GDBN}
-session, while the latter is immediately expanded to the current
-directory at the time you add an entry to the source path.
+The special strings @samp{$cdir} (to refer to the compilation
+directory, if one is recorded), and @samp{$cwd} (to refer to the
+current working directory) can also be included in the list of
+directories @var{dirname}. Though these will already be in the source
+path they will be moved forward in the list so @value{GDBN} searches
+them sooner.
@item directory
Reset the source path to its default value (@samp{$cdir:$cwd} on Unix systems). This requires confirmation.
Python-based pretty-printer (@pxref{Pretty Printing}).
@table @code
-@item print @var{expr}
-@itemx print /@var{f} @var{expr}
+@item print [[@var{options}] --] @var{expr}
+@itemx print [[@var{options}] --] /@var{f} @var{expr}
@var{expr} is an expression (in the source language). By default the
value of @var{expr} is printed in a format appropriate to its data type;
you can choose a different format by specifying @samp{/@var{f}}, where
@var{f} is a letter specifying the format; see @ref{Output Formats,,Output
Formats}.
-@item print
-@itemx print /@var{f}
+@anchor{print options}
+The @code{print} command supports a number of options that allow
+overriding relevant global print settings as set by @code{set print}
+subcommands:
+
+@table @code
+@item -address [@code{on}|@code{off}]
+Set printing of addresses.
+Related setting: @ref{set print address}.
+
+@item -array [@code{on}|@code{off}]
+Pretty formatting of arrays.
+Related setting: @ref{set print array}.
+
+@item -array-indexes [@code{on}|@code{off}]
+Set printing of array indexes.
+Related setting: @ref{set print array-indexes}.
+
+@item -elements @var{number-of-elements}|@code{unlimited}
+Set limit on string chars or array elements to print. The value
+@code{unlimited} causes there to be no limit. Related setting:
+@ref{set print elements}.
+
+@item -max-depth @var{depth}|@code{unlimited}
+Set the threshold after which nested structures are replaced with
+ellipsis. Related setting: @ref{set print max-depth}.
+
+@item -null-stop [@code{on}|@code{off}]
+Set printing of char arrays to stop at first null char. Related
+setting: @ref{set print null-stop}.
+
+@item -object [@code{on}|@code{off}]
+Set printing C@t{++} virtual function tables. Related setting:
+@ref{set print object}.
+
+@item -pretty [@code{on}|@code{off}]
+Set pretty formatting of structures. Related setting: @ref{set print
+pretty}.
+
+@item -repeats @var{number-of-repeats}|@code{unlimited}
+Set threshold for repeated print elements. @code{unlimited} causes
+all elements to be individually printed. Related setting: @ref{set
+print repeats}.
+
+@item -static-members [@code{on}|@code{off}]
+Set printing C@t{++} static members. Related setting: @ref{set print
+static-members}.
+
+@item -symbol [@code{on}|@code{off}]
+Set printing of symbol names when printing pointers. Related setting:
+@ref{set print symbol}.
+
+@item -union [@code{on}|@code{off}]
+Set printing of unions interior to structures. Related setting:
+@ref{set print union}.
+
+@item -vtbl [@code{on}|@code{off}]
+Set printing of C++ virtual function tables. Related setting:
+@ref{set print vtbl}.
+@end table
+
+Because the @code{print} command accepts arbitrary expressions which
+may look like options (including abbreviations), if you specify any
+command option, then you must use a double dash (@code{--}) to mark
+the end of option processing.
+
+For example, this prints the value of the @code{-r} expression:
+
+@smallexample
+(@value{GDBP}) print -r
+@end smallexample
+
+While this repeats the last value in the value history (see below)
+with the @code{-raw} option in effect:
+
+@smallexample
+(@value{GDBP}) print -r --
+@end smallexample
+
+Here is an example including both on option and an expression:
+
+@smallexample
+@group
+(@value{GDBP}) print -pretty -- *myptr
+$1 = @{
+ next = 0x0,
+ flags = @{
+ sweet = 1,
+ sour = 1
+ @},
+ meat = 0x54 "Pork"
+@}
+@end group
+@end smallexample
+
+@item print [@var{options}]
+@itemx print [@var{options}] /@var{f}
@cindex reprint the last value
If you omit @var{expr}, @value{GDBN} displays the last value again (from the
@dfn{value history}; @pxref{Value History, ,Value History}). This allows you to
@table @code
@kindex set print
+@anchor{set print address}
@item set print address
@itemx set print address on
@cindex print/don't print memory addresses
You can also enable @samp{/a}-like formatting all the time using
@samp{set print symbol on}:
+@anchor{set print symbol}
@table @code
@item set print symbol on
Tell @value{GDBN} to print the symbol corresponding to an address, if
Other settings control how different kinds of objects are printed:
@table @code
+@anchor{set print array}
@item set print array
@itemx set print array on
@cindex pretty print arrays
arrays.
@cindex print array indexes
+@anchor{set print array-indexes}
@item set print array-indexes
@itemx set print array-indexes on
Print the index of each element when displaying arrays. May be more
Show whether the index of each element is printed when displaying
arrays.
+@anchor{set print elements}
@item set print elements @var{number-of-elements}
@itemx set print elements unlimited
@cindex number of array elements to print
Display the number of elements of a large array that @value{GDBN} will print.
If the number is 0, then the printing is unlimited.
+@anchor{set print frame-arguments}
@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
-@cindex do not print frame argument values
+@cindex do not print frame arguments
This command allows to control how the values of arguments are printed
when the debugger prints a frame (@pxref{Frames}). The possible
values are:
#1 0x08048361 in call_me (i=@dots{}, s=@dots{}, ss=@dots{}, u=@dots{}, e=@dots{})
at frame-args.c:23
@end smallexample
+
+@item presence
+Only the presence of arguments is indicated by @code{@dots{}}.
+The @code{@dots{}} are not printed for function without any arguments.
+None of the argument names and values are printed.
+In this case, the example above now becomes:
+
+@smallexample
+#1 0x08048361 in call_me (@dots{}) at frame-args.c:23
+@end smallexample
+
@end table
By default, only scalar arguments are printed. This command can be used
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.
+to @code{scalars} (the default), @code{none} or @code{presence} 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.
-@item set print raw frame-arguments on
+@anchor{set print raw-frame-arguments}
+@item set print raw-frame-arguments on
Print frame arguments in raw, non pretty-printed, form.
-@item set print raw frame-arguments off
+@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
+@item show print raw-frame-arguments
Show whether to print frame arguments in raw form.
@anchor{set print entry-values}
Show the method being used for printing of frame argument values at function
entry.
+@anchor{set print frame-info}
+@item set print frame-info @var{value}
+@kindex set print frame-info
+@cindex printing frame information
+@cindex frame information, printing
+This command allows to control the information printed when
+the debugger prints a frame. See @ref{Frames}, @ref{Backtrace},
+for a general explanation about frames and frame information.
+Note that some other settings (such as @code{set print frame-arguments}
+and @code{set print address}) are also influencing if and how some frame
+information is displayed. In particular, the frame program counter is never
+printed if @code{set print address} is off.
+
+The possible values for @code{set print frame-info} are:
+@table @code
+@item short-location
+Print the frame level, the program counter (if not at the
+beginning of the location source line), the function, the function
+arguments.
+@item location
+Same as @code{short-location} but also print the source file and source line
+number.
+@item location-and-address
+Same as @code{location} but print the program counter even if located at the
+beginning of the location source line.
+@item source-line
+Print the program counter (if not at the beginning of the location
+source line), the line number and the source line.
+@item source-and-location
+Print what @code{location} and @code{source-line} are printing.
+@item auto
+The information printed for a frame is decided automatically
+by the @value{GDBN} command that prints a frame.
+For example, @code{frame} prints the information printed by
+@code{source-and-location} while @code{stepi} will switch between
+@code{source-line} and @code{source-and-location} depending on the program
+counter.
+The default value is @code{auto}.
+@end table
+
+@anchor{set print repeats}
@item set print repeats @var{number-of-repeats}
@itemx set print repeats unlimited
@cindex repeated array elements
Display the current threshold for printing repeated identical
elements.
+@anchor{set print max-depth}
+@item set print max-depth @var{depth}
+@item set print max-depth unlimited
+@cindex printing nested structures
+Set the threshold after which nested structures are replaced with
+ellipsis, this can make visualising deeply nested structures easier.
+
+For example, given this C code
+
+@smallexample
+typedef struct s1 @{ int a; @} s1;
+typedef struct s2 @{ s1 b; @} s2;
+typedef struct s3 @{ s2 c; @} s3;
+typedef struct s4 @{ s3 d; @} s4;
+
+s4 var = @{ @{ @{ @{ 3 @} @} @} @};
+@end smallexample
+
+The following table shows how different values of @var{depth} will
+effect how @code{var} is printed by @value{GDBN}:
+
+@multitable @columnfractions .3 .7
+@headitem @var{depth} setting @tab Result of @samp{p var}
+@item unlimited
+@tab @code{$1 = @{d = @{c = @{b = @{a = 3@}@}@}@}}
+@item @code{0}
+@tab @code{$1 = @{...@}}
+@item @code{1}
+@tab @code{$1 = @{d = @{...@}@}}
+@item @code{2}
+@tab @code{$1 = @{d = @{c = @{...@}@}@}}
+@item @code{3}
+@tab @code{$1 = @{d = @{c = @{b = @{...@}@}@}@}}
+@item @code{4}
+@tab @code{$1 = @{d = @{c = @{b = @{a = 3@}@}@}@}}
+@end multitable
+
+To see the contents of structures that have been hidden the user can
+either increase the print max-depth, or they can print the elements of
+the structure that are visible, for example
+
+@smallexample
+(gdb) set print max-depth 2
+(gdb) p var
+$1 = @{d = @{c = @{...@}@}@}
+(gdb) p var.d
+$2 = @{c = @{b = @{...@}@}@}
+(gdb) p var.d.c
+$3 = @{b = @{a = 3@}@}
+@end smallexample
+
+The pattern used to replace nested structures varies based on
+language, for most languages @code{@{...@}} is used, but Fortran uses
+@code{(...)}.
+
+@item show print max-depth
+Display the current threshold after which nested structures are
+replaces with ellipsis.
+
+@anchor{set print null-stop}
@item set print null-stop
@cindex @sc{null} elements in arrays
Cause @value{GDBN} to stop printing the characters of an array when the first
Show whether @value{GDBN} stops printing an array on the first
@sc{null} character.
+@anchor{set print pretty}
@item set print pretty on
@cindex print structures in indented form
@cindex indentation in structure display
@item show print sevenbit-strings
Show whether or not @value{GDBN} is printing only seven-bit characters.
+@anchor{set print union}
@item set print union on
@cindex unions in structures, printing
Tell @value{GDBN} to print unions which are contained in structures
@item show demangle-style
Display the encoding style currently in use for decoding C@t{++} symbols.
+@anchor{set print object}
@item set print object
@itemx set print object on
@cindex derived type of an object, printing
@item show print object
Show whether actual, or declared, object types are displayed.
+@anchor{set print static-members}
@item set print static-members
@itemx set print static-members on
@cindex static members of C@t{++} objects
Show whether Pascal static members are printed or not.
@c These don't work with HP ANSI C++ yet.
+@anchor{set print vtbl}
@item set print vtbl
@itemx set print vtbl on
@cindex pretty print C@t{++} virtual function tables
The variable @code{$_exception} is set to the exception object being
thrown at an exception-related catchpoint. @xref{Set Catchpoints}.
+@item $_ada_exception
+The variable @code{$_ada_exception} is set to the address of the
+exception being caught or thrown at an Ada exception-related
+catchpoint. @xref{Set Catchpoints}.
+
@item $_probe_argc
@itemx $_probe_arg0@dots{}$_probe_arg11
Arguments to a static probe. @xref{Static Probe Points}.
write scripts that work with different versions of @value{GDBN}
without errors caused by features unavailable in some of those
versions.
+
+@item $_shell_exitcode
+@itemx $_shell_exitsignal
+@vindex $_shell_exitcode@r{, convenience variable}
+@vindex $_shell_exitsignal@r{, convenience variable}
+@cindex shell command, exit code
+@cindex shell command, exit signal
+@cindex exit status of shell commands
+@value{GDBN} commands such as @code{shell} and @code{|} are launching
+shell commands. When a launched command terminates, @value{GDBN}
+automatically maintains the variables @code{$_shell_exitcode}
+and @code{$_shell_exitsignal} according to the exit status of the last
+launched command. These variables are set and used similarly to
+the variables @code{$_exitcode} and @code{$_exitsignal}.
+
@end table
@node Convenience Funs
$4 = 1
@end smallexample
+@item $_gdb_setting_str (@var{setting})
+@findex $_gdb_setting_str@r{, convenience function}
+Return the value of the @value{GDBN} @var{setting} as a string.
+@var{setting} is any setting that can be used in a @code{set} or
+@code{show} command (@pxref{Controlling GDB}).
+
+@smallexample
+(@value{GDBP}) show print frame-arguments
+Printing of non-scalar frame arguments is "scalars".
+(@value{GDBP}) p $_gdb_setting_str("print frame-arguments")
+$1 = "scalars"
+(@value{GDBP}) p $_gdb_setting_str("height")
+$2 = "30"
+(@value{GDBP})
+@end smallexample
+
+@item $_gdb_setting (@var{setting})
+@findex $_gdb_setting@r{, convenience function}
+Return the value of the @value{GDBN} @var{setting}.
+The type of the returned value depends on the setting.
+
+The value type for boolean and auto boolean settings is @code{int}.
+The boolean values @code{off} and @code{on} are converted to
+the integer values @code{0} and @code{1}. The value @code{auto} is
+converted to the value @code{-1}.
+
+The value type for integer settings is either @code{unsigned int}
+or @code{int}, depending on the setting.
+
+Some integer settings accept an @code{unlimited} value.
+Depending on the setting, the @code{set} command also accepts
+the value @code{0} or the value @code{@minus{}1} as a synonym for
+@code{unlimited}.
+For example, @code{set height unlimited} is equivalent to
+@code{set height 0}.
+
+Some other settings that accept the @code{unlimited} value
+use the value @code{0} to literally mean zero.
+For example, @code{set history size 0} indicates to not
+record any @value{GDBN} commands in the command history.
+For such settings, @code{@minus{}1} is the synonym
+for @code{unlimited}.
+
+See the documentation of the corresponding @code{set} command for
+the numerical value equivalent to @code{unlimited}.
+
+The @code{$_gdb_setting} function converts the unlimited value
+to a @code{0} or a @code{@minus{}1} value according to what the
+@code{set} command uses.
+
+@smallexample
+@group
+(@value{GDBP}) p $_gdb_setting_str("height")
+$1 = "30"
+(@value{GDBP}) p $_gdb_setting("height")
+$2 = 30
+(@value{GDBP}) set height unlimited
+(@value{GDBP}) p $_gdb_setting_str("height")
+$3 = "unlimited"
+(@value{GDBP}) p $_gdb_setting("height")
+$4 = 0
+@end group
+@group
+(@value{GDBP}) p $_gdb_setting_str("history size")
+$5 = "unlimited"
+(@value{GDBP}) p $_gdb_setting("history size")
+$6 = -1
+(@value{GDBP}) p $_gdb_setting_str("disassemble-next-line")
+$7 = "auto"
+(@value{GDBP}) p $_gdb_setting("disassemble-next-line")
+$8 = -1
+(@value{GDBP})
+@end group
+@end smallexample
+
+Other setting types (enum, filename, optional filename, string, string noescape)
+are returned as string values.
+
+
+@item $_gdb_maint_setting_str (@var{setting})
+@findex $_gdb_maint_setting_str@r{, convenience function}
+Like the @code{$_gdb_setting_str} function, but works with
+@code{maintenance set} variables.
+
+@item $_gdb_maint_setting (@var{setting})
+@findex $_gdb_maint_setting@r{, convenience function}
+Like the @code{$_gdb_setting} function, but works with
+@code{maintenance set} variables.
+
@end table
-These functions require @value{GDBN} to be configured with
+The following functions require @value{GDBN} to be configured with
@code{Python} support.
@table @code
Visiting node of type NODE_INTEGER
@end smallexample
+@item $_cimag(@var{value})
+@itemx $_creal(@var{value})
+@findex $_cimag@r{, convenience function}
+@findex $_creal@r{, convenience function}
+Return the imaginary (@code{$_cimag}) or real (@code{$_creal}) part of
+the complex number @var{value}.
+
+The type of the imaginary or real part depends on the type of the
+complex number, e.g., using @code{$_cimag} on a @code{float complex}
+will return an imaginary part of type @code{float}.
+
@end table
@value{GDBN} provides the ability to list and get help on
types. Also suitable for unions. As unions aren't part of regular Fortran,
this can only happen when accessing a register that uses a gdbarch-defined
union type.
+@item ::
+The scope operator. Normally used to access variables in modules or
+to set breakpoints on subroutines nested in modules or in other
+subroutines (internal subroutines).
@end table
@node Fortran Defaults
* 2 807c468 1 15 Runnable task_1
(@value{GDBP}) info task 2
Ada Task: 0x807c468
-Name: task_1
+Name: "task_1"
Thread: 0
LWP: 0x1fac
-Parent: 1 (main_task)
+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.
+This command prints the ID and name of the current task.
@smallexample
@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
+* 2 807c458 1 15 Runnable some_task
(@value{GDBP}) task
-[Current task is 2]
+[Current task is 2 "some_task"]
@end smallexample
@item task @var{taskno}
(@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
+* 2 807c458 1 15 Runnable some_task
(@value{GDBP}) task 1
-[Switching to task 1]
+[Switching to task 1 "main_task"]
#0 0x8067726 in pthread_cond_wait ()
(@value{GDBP}) bt
#0 0x8067726 in pthread_cond_wait ()
/* XXX 3-bit hole */
/* XXX 4-byte hole */
/* 8 | 8 */ int64_t a5;
-/* 16:27 | 4 */ int a6 : 5;
-/* 16:56 | 8 */ int64_t a7 : 3;
+/* 16: 0 | 4 */ int a6 : 5;
+/* 16: 5 | 8 */ int64_t a7 : 3;
+"/* XXX 7-byte padding */
/* total size (bytes): 24 */
@}
@end smallexample
-Note how the offset information is now extended to also include how
-many bits are left to be used in each bitfield.
+Note how the offset information is now extended to also include the
+first bit of the bitfield.
@end table
@kindex ptype
of such variables.
@kindex info types
-@item info types @var{regexp}
-@itemx info types
+@item info types [-q] [@var{regexp}]
Print a brief description of all types whose names match the regular
expression @var{regexp} (or all types in your program, if you supply
no argument). Each complete typename is matched as though it were a
@code{whatis}, it does not print a detailed description; second, it
lists all source files and line numbers where a type is defined.
+The output from @samp{into types} is proceeded with a header line
+describing what types are being listed. The optional flag @samp{-q},
+which stands for @samp{quiet}, disables printing this header
+information.
+
@kindex info type-printers
@item info type-printers
Versions of @value{GDBN} that ship with Python scripting enabled may
debugging information, organized into two lists: files whose symbols
have already been read, and files whose symbols will be read when needed.
+@item info sources [-dirname | -basename] [--] [@var{regexp}]
+Like @samp{info sources}, but only print the names of the files
+matching the provided @var{regexp}.
+By default, the @var{regexp} is used to match anywhere in the filename.
+If @code{-dirname}, only files having a dirname matching @var{regexp} are shown.
+If @code{-basename}, only files having a basename matching @var{regexp}
+are shown.
+The matching is case-sensitive, except on operating systems that
+have case-insensitive filesystem (e.g., MS-Windows).
+
@kindex info functions
-@item info functions [-q]
+@item info functions [-q] [-n]
Print the names and data types of all defined functions.
Similarly to @samp{info types}, this command groups its output by source
files and annotates each function definition with its source line
language of the function, other values mean to use
the manually specified language (see @ref{Manually, ,Set Language Manually}).
+The @samp{-n} flag excludes @dfn{non-debugging symbols} from the
+results. A non-debugging symbol is a symbol that comes from the
+executable's symbol table, not from the debug information (for
+example, DWARF) associated with the executable.
+
The optional flag @samp{-q}, which stands for @samp{quiet}, disables
printing header information and messages explaining why no functions
have been printed.
-@item info functions [-q] [-t @var{type_regexp}] [@var{regexp}]
+@item info functions [-q] [-n] [-t @var{type_regexp}] [@var{regexp}]
Like @samp{info functions}, but only print the names and data types
of the functions selected with the provided regexp(s).
@kindex info variables
-@item info variables [-q]
+@item info variables [-q] [-n]
Print the names and data types of all variables that are defined
outside of functions (i.e.@: excluding local variables).
The printed variables are grouped by source files and annotated with
language of the variable, other values mean to use
the manually specified language (see @ref{Manually, ,Set Language Manually}).
+The @samp{-n} flag excludes non-debugging symbols from the results.
+
The optional flag @samp{-q}, which stands for @samp{quiet}, disables
printing header information and messages explaining why no variables
have been printed.
-@item info variables [-q] [-t @var{type_regexp}] [@var{regexp}]
+@item info variables [-q] [-n] [-t @var{type_regexp}] [@var{regexp}]
Like @kbd{info variables}, but only print the variables selected
with the provided regexp(s).
Show the current setting of stack unwinding in the functions called by
@value{GDBN}.
+@item set may-call-functions
+@kindex set may-call-functions
+@cindex disabling calling functions in the program
+@cindex calling functions in the program, disabling
+Set permission to call functions in the program.
+This controls whether @value{GDBN} will attempt to call functions in
+the program, such as with expressions in the @code{print} command. It
+defaults to @code{on}.
+
+To call a function in the program, @value{GDBN} has to temporarily
+modify the state of the inferior. This has potentially undesired side
+effects. Also, having @value{GDBN} call nested functions is likely to
+be erroneous and may even crash the program being debugged. You can
+avoid such hazards by forbidding @value{GDBN} from calling functions
+in the program being debugged. If calling functions in the program
+is forbidden, GDB will throw an error when a command (such as printing
+an expression) starts a function call in the program.
+
+@item show may-call-functions
+@kindex show may-call-functions
+Show permission to call functions in the program.
+
@end table
@subsection Calling functions with no debug info
@end table
@table @code
-@item compile print @var{expr}
-@itemx compile print /@var{f} @var{expr}
+@item compile print [[@var{options}] --] @var{expr}
+@itemx compile print [[@var{options}] --] /@var{f} @var{expr}
Compile and execute @var{expr} with the compiler language found as the
current language in @value{GDBN} (@pxref{Languages}). By default the
value of @var{expr} is printed in a format appropriate to its data type;
you can choose a different format by specifying @samp{/@var{f}}, where
@var{f} is a letter specifying the format; see @ref{Output Formats,,Output
-Formats}.
+Formats}. The @code{compile print} command accepts the same options
+as the @code{print} command; see @ref{print options}.
-@item compile print
-@itemx compile print /@var{f}
+@item compile print [[@var{options}] --]
+@itemx compile print [[@var{options}] --] /@var{f}
@cindex reprint the last value
Alternatively you can enter the expression (source code producing it) as
multiple lines of text. To enter this mode, invoke the @samp{compile print}
@item
For the ``debug link'' method, @value{GDBN} looks up the named file in
the directory of the executable file, then in a subdirectory of that
-directory named @file{.debug}, and finally under each one of the global debug
-directories, in a subdirectory whose name is identical to the leading
-directories of the executable's absolute file name.
+directory named @file{.debug}, and finally under each one of the
+global debug directories, in a subdirectory whose name is identical to
+the leading directories of the executable's absolute file name. (On
+MS-Windows/MS-DOS, the drive letter of the executable's leading
+directories is converted to a one-letter subdirectory, i.e.@:
+@file{d:/usr/bin/} is converted to @file{/d/usr/bin/}, because Windows
+filesystems disallow colons in file names.)
@item
For the ``build ID'' method, @value{GDBN} looks in the
@end smallexample
There are currently some limitation on indices. They only work when
-for DWARF debugging information, not stabs. And, they do not
-currently work for programs using Ada.
+using DWARF debugging information, not stabs. And, only the
+@code{-dwarf-5} index works for programs using Ada.
@subsection Automatic symbol index cache
+@cindex automatic symbol index cache
It is possible for @value{GDBN} to automatically save a copy of this index in a
cache on disk and retrieve it from there when loading the same binary in the
future. This feature can be turned on with @kbd{set index-cache on}. The
@table @code
+@kindex set index-cache
@item set index-cache on
@itemx set index-cache off
Enable or disable the use of the symbol index cache.
@item set index-cache directory @var{directory}
+@kindex show index-cache
@itemx show index-cache directory
Set/show the directory where index files will be saved.
status information about the debugging process.
@cindex @option{--remote-debug}, @code{gdbserver} option
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.
+remote protocol debug output.
+@cindex @option{--debug-file}, @code{gdbserver} option
+@cindex @code{gdbserver}, send all debug output to a single file
+The @option{--debug-file=@var{filename}} option tells @code{gdbserver} to
+write any debug output to the given @var{filename}. These options are intended
+for @code{gdbserver} development and for bug reports to the developers.
@cindex @option{--debug-format}, @code{gdbserver} option
The @option{--debug-format=option1[,option2,...]} option tells
Disable or enable specific debugging messages associated with the remote
protocol (@pxref{Remote Protocol}).
+@item monitor set debug-file filename
+@itemx monitor set debug-file
+Send any debug output to the given file, or to stderr.
+
@item monitor set debug-format option1@r{[},option2,...@r{]}
Specify additional text to add to debugging messages.
Possible options are:
@tab @code{qXfer:sdata:read}
@tab @code{print $_sdata}
-@item @code{read-spu-object}
-@tab @code{qXfer:spu:read}
-@tab @code{info spu}
-
-@item @code{write-spu-object}
-@tab @code{qXfer:spu:write}
-@tab @code{info spu}
-
@item @code{read-siginfo-object}
@tab @code{qXfer:siginfo:read}
@tab @code{print $_siginfo}
* Alpha::
* MIPS::
* HPPA:: HP PA architecture
-* SPU:: Cell Broadband Engine SPU architecture
* PowerPC::
* Nios II::
* Sparc64::
is a known limitation of @value{GDBN} and does not affect the execution of the
target process.
+@subsubsection AArch64 Pointer Authentication.
+@cindex AArch64 Pointer Authentication.
+
+When @value{GDBN} is debugging the AArch64 architecture, and the program is
+using the v8.3-A feature Pointer Authentication (PAC), then whenever the link
+register @code{$lr} is pointing to an PAC function its value will be masked.
+When GDB prints a backtrace, any addresses that required unmasking will be
+postfixed with the marker [PAC]. When using the MI, this is printed as part
+of the @code{addr_flags} field.
@node i386
@subsection x86 Architecture-specific Issues
@end table
-@node SPU
-@subsection Cell Broadband Engine SPU architecture
-@cindex Cell Broadband Engine
-@cindex SPU
-
-When @value{GDBN} is debugging the Cell Broadband Engine SPU architecture,
-it provides the following special commands:
-
-@table @code
-@item info spu event
-@kindex info spu
-Display SPU event facility status. Shows current event mask
-and pending event status.
-
-@item info spu signal
-Display SPU signal notification facility status. Shows pending
-signal-control word and signal notification mode of both signal
-notification channels.
-
-@item info spu mailbox
-Display SPU mailbox facility status. Shows all pending entries,
-in order of processing, in each of the SPU Write Outbound,
-SPU Write Outbound Interrupt, and SPU Read Inbound mailboxes.
-
-@item info spu dma
-Display MFC DMA status. Shows all pending commands in the MFC
-DMA queue. For each entry, opcode, tag, class IDs, effective
-and local store addresses and transfer size are shown.
-
-@item info spu proxydma
-Display MFC Proxy-DMA status. Shows all pending commands in the MFC
-Proxy-DMA queue. For each entry, opcode, tag, class IDs, effective
-and local store addresses and transfer size are shown.
-
-@end table
-
-When @value{GDBN} is debugging a combined PowerPC/SPU application
-on the Cell Broadband Engine, it provides in addition the following
-special commands:
-
-@table @code
-@item set spu stop-on-load @var{arg}
-@kindex set spu
-Set whether to stop for new SPE threads. When set to @code{on}, @value{GDBN}
-will give control to the user when a new SPE thread enters its @code{main}
-function. The default is @code{off}.
-
-@item show spu stop-on-load
-@kindex show spu
-Show whether to stop for new SPE threads.
-
-@item set spu auto-flush-cache @var{arg}
-Set whether to automatically flush the software-managed cache. When set to
-@code{on}, @value{GDBN} will automatically cause the SPE software-managed
-cache to be flushed whenever SPE execution stops. This provides a consistent
-view of PowerPC memory that is accessed via the cache. If an application
-does not use the software-managed cache, this option has no effect.
-
-@item show spu auto-flush-cache
-Show whether to automatically flush the software-managed cache.
-
-@end table
-
@node PowerPC
@subsection PowerPC
@cindex PowerPC architecture
interface. Users unfamiliar with @sc{gnu} Emacs or @code{vi} are
encouraged to read that chapter.
+@cindex Readline application name
+@value{GDBN} sets the Readline application name to @samp{gdb}. This
+is useful for conditions in @file{.inputrc}.
+
@node Command History
@section Command History
@cindex command history
(the default), @samp{bold}, and @samp{dim}.
@end table
+The @code{show style} command and its subcommands are styling
+a style name in their output using its own style.
+So, use @command{show style} to see the complete list of styles,
+their characteristics and the visual aspect of each style.
+
The style-able objects are:
@table @code
@item filename
Control the styling of addresses. These are managed with the
@code{set style address} family of commands. By default, this style's
foreground color is blue.
+
+@item title
+Control the styling of titles. These are managed with the
+@code{set style title} family of commands. By default, this style's
+intensity is bold. Commands are using the title style to improve
+the readibility of large output. For example, the commands
+@command{apropos} and @command{help} are using the title style
+for the command names.
+
+@item highlight
+Control the styling of highlightings. These are managed with the
+@code{set style highlight} family of commands. By default, this style's
+foreground color is red. Commands are using the highlight style to draw
+the user attention to some specific parts of their output. For example,
+the command @command{apropos -v REGEXP} uses the highlight style to
+mark the documentation parts matching @var{regexp}.
+
@end table
@node Numbers
@end table
+@ifset SYSTEM_GDBINIT_DIR
+This setting is not used for files in the system-wide gdbinit directory.
+Files in that directory must have an extension matching their language,
+or have a @file{.gdb} extension to be interpreted as regular @value{GDBN}
+commands. @xref{Startup}.
+@end ifset
+
@node Sequences
@section Canned Sequences of Commands
SingleKey mode is restored. The only way to permanently leave
this mode is by typing @kbd{q} or @kbd{C-x s}.
+@cindex SingleKey keymap name
+If @value{GDBN} was built with Readline 8.0 or later, the TUI
+SingleKey keymap will be named @samp{SingleKey}. This can be used in
+@file{.inputrc} to add additional bindings to this keymap.
@node TUI Commands
@section TUI-specific Commands
@item tui enable
@kindex tui enable
Activate TUI mode. The last active TUI window layout will be used if
-TUI mode has prevsiouly been used in the current debugging session,
+TUI mode has previously been used in the current debugging session,
otherwise a default layout is used.
@item tui disable
multiple locations. This field will not be present if no address can
be determined. For example, a watchpoint does not have an address.
+@item addr_flags
+Optional field containing any flags related to the address. These flags are
+architecture-dependent; see @ref{Architectures} for their meaning for a
+particular CPU.
+
@item func
If known, the function in which the breakpoint appears.
If not known, this field is not present.
@item addr
The address of this location as an hexidecimal number.
+@item addr_flags
+Optional field containing any flags related to the address. These flags are
+architecture-dependent; see @ref{Architectures} for their meaning for a
+particular CPU.
+
@item func
If known, the function in which the location appears.
If not known, this field is not present.
@item addr
The code address for the frame. This field is always present.
+@item addr_flags
+Optional field containing any flags related to the address. These flags are
+architecture-dependent; see @ref{Architectures} for their meaning for a
+particular CPU.
+
@item file
The name of the source files that correspond to the frame's code
address. This field may be absent.
@menu
* Shared Library GDB/MI Catchpoint Commands::
* Ada Exception GDB/MI Catchpoint Commands::
+* C++ Exception GDB/MI Catchpoint Commands::
@end menu
@node Shared Library GDB/MI Catchpoint Commands
(gdb)
@end smallexample
+@node C++ Exception GDB/MI Catchpoint Commands
+@subsection C@t{++} Exception @sc{gdb/mi} Catchpoints
+
+The following @sc{gdb/mi} commands can be used to create catchpoints
+that stop the execution when C@t{++} exceptions are being throw, rethrown,
+or caught.
+
+@subheading The @code{-catch-throw} Command
+@findex -catch-throw
+
+@subsubheading Synopsis
+
+@smallexample
+ -catch-throw [ -t ] [ -r @var{regexp}]
+@end smallexample
+
+Stop when the debuggee throws a C@t{++} exception. If @var{regexp} is
+given, then only exceptions whose type matches the regular expression
+will be caught.
+
+If @samp{-t} is given, then the catchpoint is enabled only for one
+stop, the catchpoint is automatically deleted after stopping once for
+the event.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} commands are @samp{catch throw}
+and @samp{tcatch throw} (@pxref{Set Catchpoints}).
+
+@subsubheading Example
+
+@smallexample
+-catch-throw -r exception_type
+^done,bkpt=@{number="1",type="catchpoint",disp="keep",enabled="y",
+ what="exception throw",catch-type="throw",
+ thread-groups=["i1"],
+ regexp="exception_type",times="0"@}
+(gdb)
+-exec-run
+^running
+(gdb)
+~"\n"
+~"Catchpoint 1 (exception thrown), 0x00007ffff7ae00ed
+ in __cxa_throw () from /lib64/libstdc++.so.6\n"
+*stopped,bkptno="1",reason="breakpoint-hit",disp="keep",
+ frame=@{addr="0x00007ffff7ae00ed",func="__cxa_throw",
+ args=[],from="/lib64/libstdc++.so.6",arch="i386:x86-64"@},
+ thread-id="1",stopped-threads="all",core="6"
+(gdb)
+@end smallexample
+
+@subheading The @code{-catch-rethrow} Command
+@findex -catch-rethrow
+
+@subsubheading Synopsis
+
+@smallexample
+ -catch-rethrow [ -t ] [ -r @var{regexp}]
+@end smallexample
+
+Stop when a C@t{++} exception is re-thrown. If @var{regexp} is given,
+then only exceptions whose type matches the regular expression will be
+caught.
+
+If @samp{-t} is given, then the catchpoint is enabled only for one
+stop, the catchpoint is automatically deleted after the first event is
+caught.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} commands are @samp{catch rethrow}
+and @samp{tcatch rethrow} (@pxref{Set Catchpoints}).
+
+@subsubheading Example
+
+@smallexample
+-catch-rethrow -r exception_type
+^done,bkpt=@{number="1",type="catchpoint",disp="keep",enabled="y",
+ what="exception rethrow",catch-type="rethrow",
+ thread-groups=["i1"],
+ regexp="exception_type",times="0"@}
+(gdb)
+-exec-run
+^running
+(gdb)
+~"\n"
+~"Catchpoint 1 (exception rethrown), 0x00007ffff7ae00ed
+ in __cxa_rethrow () from /lib64/libstdc++.so.6\n"
+*stopped,bkptno="1",reason="breakpoint-hit",disp="keep",
+ frame=@{addr="0x00007ffff7ae00ed",func="__cxa_rethrow",
+ args=[],from="/lib64/libstdc++.so.6",arch="i386:x86-64"@},
+ thread-id="1",stopped-threads="all",core="6"
+(gdb)
+@end smallexample
+
+@subheading The @code{-catch-catch} Command
+@findex -catch-catch
+
+@subsubheading Synopsis
+
+@smallexample
+ -catch-catch [ -t ] [ -r @var{regexp}]
+@end smallexample
+
+Stop when the debuggee catches a C@t{++} exception. If @var{regexp}
+is given, then only exceptions whose type matches the regular
+expression will be caught.
+
+If @samp{-t} is given, then the catchpoint is enabled only for one
+stop, the catchpoint is automatically deleted after the first event is
+caught.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} commands are @samp{catch catch}
+and @samp{tcatch catch} (@pxref{Set Catchpoints}).
+
+@subsubheading Example
+
+@smallexample
+-catch-catch -r exception_type
+^done,bkpt=@{number="1",type="catchpoint",disp="keep",enabled="y",
+ what="exception catch",catch-type="catch",
+ thread-groups=["i1"],
+ regexp="exception_type",times="0"@}
+(gdb)
+-exec-run
+^running
+(gdb)
+~"\n"
+~"Catchpoint 1 (exception caught), 0x00007ffff7ae00ed
+ in __cxa_begin_catch () from /lib64/libstdc++.so.6\n"
+*stopped,bkptno="1",reason="breakpoint-hit",disp="keep",
+ frame=@{addr="0x00007ffff7ae00ed",func="__cxa_begin_catch",
+ args=[],from="/lib64/libstdc++.so.6",arch="i386:x86-64"@},
+ thread-id="1",stopped-threads="all",core="6"
+(gdb)
+@end smallexample
+
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Program Context
@section @sc{gdb/mi} Program Context
(gdb)
@end smallexample
+@subheading The @code{-complete} Command
+@findex -complete
+
+@subheading Synopsis
+
+@smallexample
+-complete @var{command}
+@end smallexample
+
+Show a list of completions for partially typed CLI @var{command}.
+
+This command is intended for @sc{gdb/mi} frontends that cannot use two separate
+CLI and MI channels --- for example: because of lack of PTYs like on Windows or
+because @value{GDBN} is used remotely via a SSH connection.
+
+@subheading Result
+
+The result consists of two or three fields:
+
+@table @samp
+@item completion
+This field contains the completed @var{command}. If @var{command}
+has no known completions, this field is omitted.
+
+@item matches
+This field contains a (possibly empty) array of matches. It is always present.
+
+@item max_completions_reached
+This field contains @code{1} if number of known completions is above
+@code{max-completions} limit (@pxref{Completion}), otherwise it contains
+@code{0}. It is always present.
+
+@end table
+
+@subheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{complete}.
+
+@subheading Example
+
+@smallexample
+(gdb)
+-complete br
+^done,completion="break",
+ matches=["break","break-range"],
+ max_completions_reached="0"
+(gdb)
+-complete "b ma"
+^done,completion="b ma",
+ matches=["b madvise","b main"],max_completions_reached="0"
+(gdb)
+-complete "b push_b"
+^done,completion="b push_back(",
+ matches=[
+ "b A::push_back(void*)",
+ "b std::string::push_back(char)",
+ "b std::vector<int, std::allocator<int> >::push_back(int&&)"],
+ max_completions_reached="0"
+(gdb)
+-complete "nonexist"
+^done,matches=[],max_completions_reached="0"
+(gdb)
+
+@end smallexample
+
@node Annotations
@chapter @value{GDBN} Annotations
@item --with-system-readline
Use the readline library installed on the host, rather than the
-library supplied as part of @value{GDBN}.
+library supplied as part of @value{GDBN}. Readline 7 or newer is
+required; this is enforced by the build system.
@item --with-system-zlib
Use the zlib library installed on the host, rather than the library
another location after being built, the location of the system-wide
init file will be adjusted accordingly.
+@item --with-system-gdbinit-dir=@var{directory}
+Configure @value{GDBN} to automatically load init files from a
+system-wide directory. @var{directory} should be an absolute directory
+name. If @var{directory} is in a directory under the configured
+prefix, and @value{GDBN} is moved to another location after being
+built, the location of the system-wide init directory will be
+adjusted accordingly.
+
@item --enable-build-warnings
When building the @value{GDBN} sources, ask the compiler to warn about
any code which looks even vaguely suspicious. It passes many
@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}).
+@value{GDBN} can be configured to have a system-wide init file and a
+system-wide init file directory; this file and files in that directory
+(if they have a recognized file extension) will be read and executed at
+startup (@pxref{Startup, , What @value{GDBN} does during startup}).
-Here is the corresponding configure option:
+Here are the corresponding configure options:
@table @code
@item --with-system-gdbinit=@var{file}
Specify that the default location of the system-wide init file is
@var{file}.
+@item --with-system-gdbinit-dir=@var{directory}
+Specify that the default location of the system-wide init file directory
+is @var{directory}.
@end table
If @value{GDBN} has been configured with the option @option{--prefix=$prefix},
-it may be subject to relocation. Two possible cases:
+they may be subject to relocation. Two possible cases:
@itemize @bullet
@item
-If the default location of this init file contains @file{$prefix},
+If the default location of this init file/directory 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
started with the @code{set data-directory} command, the file will not be
reread.
+This applies similarly to the system-wide directory specified in
+@option{--with-system-gdbinit-dir}.
+
+Any supported scripting language can be used for these init files, as long
+as the file extension matches the scripting language. To be interpreted
+as regular @value{GDBN} commands, the files needs to have a @file{.gdb}
+extension.
+
@menu
* System-wide Configuration Scripts:: Installed System-wide Configuration Scripts
@end menu
If a @var{filter} is passed, only the tests with @var{filter} in their
name will by ran.
-@kindex "maint info selftests"
+@kindex maint info selftests
@cindex self tests
@item maint info selftests
List the selftests compiled in to @value{GDBN}.
is also printed. For dynamically linked executables, the name of
executable or shared library containing the symbol is printed as well.
+@kindex maint test-options
+@item maint test-options require-delimiter
+@itemx maint test-options unknown-is-error
+@itemx maint test-options unknown-is-operand
+These commands are used by the testsuite to validate the command
+options framework. The @code{require-delimiter} variant requires a
+double-dash delimiter to indicate end of options. The
+@code{unknown-is-error} and @code{unknown-is-operand} do not. The
+@code{unknown-is-error} variant throws an error on unknown option,
+while @code{unknown-is-operand} treats unknown options as the start of
+the command's operands. When run, the commands output the result of
+the processed options. When completed, the commands store the
+internal result of completion in a variable exposed by the @code{maint
+show test-options-completion-result} command.
+
+@kindex maint show test-options-completion-result
+@item maint show test-options-completion-result
+Shows the result of completing the @code{maint test-options}
+subcommands. This is used by the testsuite to validate completion
+support in the command options framework.
+
+@kindex maint set test-settings
+@kindex maint show test-settings
+@item maint set test-settings @var{kind}
+@itemx maint show test-settings @var{kind}
+These are representative commands for each @var{kind} of setting type
+@value{GDBN} supports. They are used by the testsuite for exercising
+the settings infrastructure.
+
+@kindex maint with
+@item maint with @var{setting} [@var{value}] [-- @var{command}]
+Like the @code{with} command, but works with @code{maintenance set}
+variables. This is used by the testsuite to exercise the @code{with}
+command's infrastructure.
+
@end table
The following command is useful for non-interactive invocations of
@tab @samp{-}
@tab Yes
-@item @samp{qXfer:spu:read}
-@tab No
-@tab @samp{-}
-@tab Yes
-
-@item @samp{qXfer:spu:write}
-@tab No
-@tab @samp{-}
-@tab Yes
-
@item @samp{qXfer:siginfo:read}
@tab No
@tab @samp{-}
The remote stub understands the @samp{qXfer:sdata:read} packet
(@pxref{qXfer sdata read}).
-@item qXfer:spu:read
-The remote stub understands the @samp{qXfer:spu:read} packet
-(@pxref{qXfer spu read}).
-
-@item qXfer:spu:write
-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}).
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
-annex specifies which file to read; it must be of the form
-@file{@var{id}/@var{name}}, where @var{id} specifies an SPU context ID
-in the target process, and @var{name} identifes the @code{spufs} file
-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}).
-
@item qXfer:threads:read::@var{offset},@var{length}
@anchor{qXfer threads read}
Access the list of threads on target. @xref{Thread List Format}. The
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
-@file{@var{id}/@var{name}}, where @var{id} specifies an SPU context ID
-in the target process, and @var{name} identifes the @code{spufs} file
-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}).
@end table
@item qXfer:@var{object}:@var{operation}:@dots{}
* OpenRISC 1000 Features::
* PowerPC Features::
* RISC-V Features::
+* RX Features::
* S/390 and System z Features::
* Sparc Features::
* TIC6x Features::
feature if the target has the floating point control registers, but no
other floating point hardware.
+@node RX Features
+@subsection RX Features
+@cindex target descriptions, RX Features
+
+The @samp{org.gnu.gdb.rx.core} feature is required for RX
+targets. It should contain the registers @samp{r0} through
+@samp{r15}, @samp{usp}, @samp{isp}, @samp{psw}, @samp{pc}, @samp{intb},
+@samp{bpsw}, @samp{bpc}, @samp{fintv}, @samp{fpsw}, and @samp{acc}.
+
@node S/390 and System z Features
@subsection S/390 and System z Features
@cindex target descriptions, S/390 features
gdb program core
@end smallexample
-You can, instead, specify a process ID as a second argument, if you want
-to debug a running process:
+You can, instead, specify a process ID as a second argument or use option
+@code{-p}, if you want to debug a running process:
@smallexample
gdb program 1234
@end smallexample
@noindent
-would attach @value{GDBN} to process @code{1234} (unless you also have a file
-named @file{1234}; @value{GDBN} does check for a core file first).
-With option @option{-p} you can omit the @var{program} filename.
+would attach @value{GDBN} to process @code{1234}. With option @option{-p} you
+can omit the @var{program} filename.
Here are some of the most frequently needed @value{GDBN} commands:
This option is intended for @code{gdbserver} development and for bug reports to
the developers.
+@item --debug-file=@var{filename}
+Instruct @code{gdbserver} to send any debug output to the given @var{filename}.
+This option is intended for @code{gdbserver} development and for bug reports to
+the developers.
+
@item --debug-format=option1@r{[},option2,...@r{]}
Instruct @code{gdbserver} to include extra information in each line
of debugging output.
@value{SYSTEM_GDBINIT}
@end ifset
+@ifset SYSTEM_GDBINIT_DIR
+@value{SYSTEM_GDBINIT_DIR}/*
+@end ifset
+
~/.gdbinit
./.gdbinit
the @value{GDBN} manual in node @code{System-wide configuration}
-- shell command @code{info -f gdb -n 'System-wide configuration'}.
@end ifset
+@ifset SYSTEM_GDBINIT_DIR
+@item @value{SYSTEM_GDBINIT_DIR}
+@end ifset
+@ifclear SYSTEM_GDBINIT_DIR
+@item (not enabled with @code{--with-system-gdbinit-dir} during compilation)
+@end ifclear
+System-wide initialization directory. All files in this directory are
+executed on startup unless user specified @value{GDBN} option @code{-nx} or
+@code{-n}, as long as they have a recognized file extension.
+See more in
+@ifset man
+the @value{GDBN} manual in node @code{System-wide configuration}
+-- shell command @code{info -f gdb -n 'System-wide configuration'}.
+@end ifset
@ifclear man
@ref{System-wide configuration}.
@end ifclear
projects / binutils-gdb.git / blobdiff