@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
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
@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.
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
@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.
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
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).
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
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.
@smallexample
-catch-throw -r exception_type
-^done,bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
- addr="0x00000000004006c0",what="exception throw",
- catch-type="throw",thread-groups=["i1"],
+^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
@smallexample
-catch-rethrow -r exception_type
-^done,bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
- addr="0x00000000004006c0",what="exception rethrow",
- catch-type="rethrow",thread-groups=["i1"],
+^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
@smallexample
-catch-catch -r exception_type
-^done,bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
- addr="0x00000000004006c0",what="exception catch",
- catch-type="catch",thread-groups=["i1"],
+^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
@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
subcommands. This is used by the testsuite to validate completion
support in the command options framework.
-@kindex maint test-settings
-@item maint test-settings set @var{kind}
-@itemx maint test-settings show @var{kind}
+@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
* 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
projects / deliverable / binutils-gdb.git / blobdiff