\input texinfo @c -*-texinfo-*-
-@c Copyright (C) 1988--2020 Free Software Foundation, Inc.
+@c Copyright (C) 1988--2021 Free Software Foundation, Inc.
@c
@c %**start of header
@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use
@copying
@c man begin COPYRIGHT
-Copyright @copyright{} 1988-2020 Free Software Foundation, Inc.
+Copyright @copyright{} 1988-2021 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@end ifset
Version @value{GDBVN}.
-Copyright (C) 1988-2020 Free Software Foundation, Inc.
+Copyright (C) 1988-2021 Free Software Foundation, Inc.
This edition of the GDB manual is dedicated to the memory of Fred
Fish. Fred was a long-standing contributor to GDB and to Free
* File Options:: Choosing files
* Mode Options:: Choosing modes
* Startup:: What @value{GDBN} does during startup
+* Initialization Files:: Initialization Files
@end menu
@node File Options
@itemx -n
@cindex @code{--nx}
@cindex @code{-n}
-Do not execute commands found in any initialization file.
-There are three init files, loaded in the following order:
-
-@table @code
-@item @file{system.gdbinit}
-This is the system-wide init file.
-Its location is specified with the @code{--with-system-gdbinit}
-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
-command options have been processed.
-@item @file{./.gdbinit}
-This is the init file in the current directory.
-It is loaded last, after command line options other than @code{-x} and
-@code{-ex} have been processed. Command line options @code{-x} and
-@code{-ex} are processed last, after @file{./.gdbinit} has been loaded.
-@end table
-
-For further documentation on startup processing, @xref{Startup}.
-For documentation on how to write command files,
-@xref{Command Files,,Command Files}.
+Do not execute commands found in any initialization files
+(@pxref{Initialization Files}).
@anchor{-nh}
@item -nh
@cindex @code{--nh}
-Do not execute commands found in @file{~/.gdbinit}, the init file
-in your home directory.
-@xref{Startup}.
+Do not execute commands found in any home directory initialization
+file (@pxref{Initialization Files,,Home directory initialization
+file}). The system wide and current directory initialization files
+are still loaded.
@item -quiet
@itemx -silent
@item
@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 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.
+Reads the system wide initialization file and the files from the
+system wide initialization directory, @pxref{System Wide Init Files}.
-@anchor{Home Directory Init File}
@item
-Reads the init file (if any) in your home directory@footnote{On
-DOS/Windows systems, the home directory is the one pointed to by the
-@code{HOME} environment variable.} and executes all the commands in
-that file.
+Reads the initialization file (if any) in your home directory and
+executes all the commands in that file, @pxref{Home Directory Init
+File}.
@anchor{Option -init-eval-command}
@item
@item
Processes command line options and operands.
-@anchor{Init File in the Current Directory during Startup}
@item
-Reads and executes the commands from init file (if any) in the current
-working directory as long as @samp{set auto-load local-gdbinit} is set to
-@samp{on} (@pxref{Init File in the Current Directory}).
-This is only done if the current directory is
-different from your home directory. Thus, you can have more than one
-init file, one generic in your home directory, and another, specific
-to the program you are debugging, in the directory where you invoke
-@value{GDBN}.
+Reads and executes the commands from the initialization file (if any)
+in the current working directory as long as @samp{set auto-load
+local-gdbinit} is set to @samp{on} (@pxref{Init File in the Current
+Directory}). This is only done if the current directory is different
+from your home directory. Thus, you can have more than one init file,
+one generic in your home directory, and another, specific to the
+program you are debugging, in the directory where you invoke
+@value{GDBN}. @xref{Init File in the Current Directory during
+Startup}.
@item
If the command line specified a program to debug, or a process to
files where @value{GDBN} records it.
@end enumerate
-Init files use the same syntax as @dfn{command files} (@pxref{Command
-Files}) and are processed by @value{GDBN} in the same way. The init
-file in your home directory can set options (such as @samp{set
-complaints}) that affect subsequent processing of command line options
-and operands. Init files are not executed if you use the @samp{-nx}
-option (@pxref{Mode Options, ,Choosing Modes}).
+@node Initialization Files
+@subsection Initialization Files
+@cindex init file name
+
+During startup (@pxref{Startup}) @value{GDBN} will execute commands
+from several initialization files. These initialization files use the
+same syntax as @dfn{command files} (@pxref{Command Files}) and are
+processed by @value{GDBN} in the same way.
-To display the list of init files loaded by gdb at startup, you
-can use @kbd{gdb --help}.
+To display the list of initialization files loaded by @value{GDBN} at
+startup, in the order they will be loaded, you can use @kbd{gdb
+--help}.
-@cindex init file name
+As the system wide and home directory initialization files are
+processed before most command line options, changes to settings
+(e.g. @samp{set complaints}) can affect subsequent processing of
+command line options and operands.
+
+The following sections describe where @value{GDBN} looks for the
+initialization and the order that the files are searched for.
+
+@anchor{System Wide Init Files}
+@subsubsection System wide initialization files
+
+There are two locations that are searched for system wide
+initialization files. Both of these locations are always checked:
+
+@table @code
+
+@item @file{system.gdbinit}
+This is a single system-wide initialization file. Its location is
+specified with the @code{--with-system-gdbinit} 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 initialization 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 @file{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.
+
+@end table
+
+It is possible to prevent the system wide initialization files from
+being loaded using the @samp{-nx} command line option, @pxref{Mode
+Options,,Choosing Modes}.
+
+@anchor{Home Directory Init File}
+@subsubsection Home directory initialization file
+@cindex @file{gdbinit}
@cindex @file{.gdbinit}
@cindex @file{gdb.ini}
-The @value{GDBN} init files are normally called @file{.gdbinit}.
-The DJGPP port of @value{GDBN} uses the name @file{gdb.ini}, due to
-the limitations of file names imposed by DOS filesystems. The Windows
-port of @value{GDBN} uses the standard name, but if it finds a
-@file{gdb.ini} file in your home directory, it warns you about that
-and suggests to rename the file to the standard name.
+After loading the system wide initialization files @value{GDBN} will
+look for an initialization file in the users home
+directory@footnote{On DOS/Windows systems, the home directory is the
+one pointed to by the @code{HOME} environment variable.}. There are a
+number of locations that @value{GDBN} will search in the home
+directory, these locations are searched in order and @value{GDBN} will
+load the first file that it finds, and subsequent locations will not
+be checked.
+
+On non-Apple hosts the locations searched are:
+@table @file
+@item $XDG_CONFIG_HOME/gdb/gdbinit
+@item $HOME/.config/gdb/gdbinit
+@item $HOME/.gdbinit
+@end table
+
+While on Apple hosts the locations searched are:
+@table @file
+@item $HOME/Library/Preferences/gdb/gdbinit
+@item $HOME/.gdbinit
+@end table
+
+It is possible to prevent the home directory initialization file from
+being loaded using the @samp{-nx} or @samp{-nh} command line options,
+@pxref{Mode Options,,Choosing Modes}.
+
+The DJGPP port of @value{GDBN} uses the name @file{gdb.ini} instead of
+@file{.gdbinit} or @file{gdbinit}, due to the limitations of file
+names imposed by DOS filesystems. The Windows port of @value{GDBN}
+uses the standard name, but if it finds a @file{gdb.ini} file in your
+home directory, it warns you about that and suggests to rename the
+file to the standard name.
+
+@anchor{Init File in the Current Directory during Startup}
+@subsubsection Local directory initialization file
+
+@value{GDBN} will check the current directory for a file called
+@file{.gdbinit}. It is loaded last, after command line options
+other than @samp{-x} and @samp{-ex} have been processed. The command
+line options @samp{-x} and @samp{-ex} are processed last, after
+@file{.gdbinit} has been loaded, @pxref{File Options,,Choosing
+Files}.
+
+If the file in the current directory was already loaded as the home
+directory initialization file then it will not be loaded a second
+time.
+
+It is possible to prevent the local directory initialization file from
+being loaded using the @samp{-nx} command line option, @pxref{Mode
+Options,,Choosing Modes}.
@node Quitting GDB
@section Quitting @value{GDBN}
* Command Settings:: How to change default behavior of commands
* Completion:: Command completion
* Command Options:: Command options
-* Command aliases default args:: Automatically prepend default arguments to user-defined aliases
* Help:: How to ask @value{GDBN} for help
@end menu
(For more on using the @code{print} command, see @ref{Data, ,Examining
Data}.)
-@node Command aliases default args
-@section Automatically prepend default arguments to user-defined aliases
-
-You can tell @value{GDBN} to always prepend some default arguments to
-the list of arguments provided explicitly by the user when using a
-user-defined alias.
-
-If you repeatedly use the same arguments or options for a command, you
-can define an alias for this command and tell @value{GDBN} to
-automatically prepend these arguments or options to the list of
-arguments you type explicitly when using the alias@footnote{@value{GDBN}
-could easily accept default arguments for pre-defined commands and aliases,
-but it was deemed this would be confusing, and so is not allowed.}.
-
-For example, if you often use the command @code{thread apply all}
-specifying to work on the threads in ascending order and to continue in case it
-encounters an error, you can tell @value{GDBN} to automatically preprend
-the @code{-ascending} and @code{-c} options by using:
-
-@smallexample
-(@value{GDBP}) alias thread apply asc-all = thread apply all -ascending -c
-@end smallexample
-
-Once you have defined this alias with its default args, any time you type
-the @code{thread apply asc-all} followed by @code{some arguments},
-@value{GDBN} will execute @code{thread apply all -ascending -c some arguments}.
-
-To have even less to type, you can also define a one word alias:
-@smallexample
-(@value{GDBP}) alias t_a_c = thread apply all -ascending -c
-@end smallexample
-
-As usual, unambiguous abbreviations can be used for @var{alias}
-and @var{default-args}.
-
-The different aliases of a command do not share their default args.
-For example, you define a new alias @code{bt_ALL} showing all possible
-information and another alias @code{bt_SMALL} showing very limited information
-using:
-@smallexample
-(@value{GDBP}) alias bt_ALL = backtrace -entry-values both -frame-arg all \
- -past-main -past-entry -full
-(@value{GDBP}) alias bt_SMALL = backtrace -entry-values no -frame-arg none \
- -past-main off -past-entry off
-@end smallexample
-
-(For more on using the @code{alias} command, see @ref{Aliases}.)
-
-Default args are not limited to the arguments and options of @var{command},
-but can specify nested commands if @var{command} accepts such a nested command
-as argument.
-For example, the below defines @code{faalocalsoftype} that lists the
-frames having locals of a certain type, together with the matching
-local vars:
-@smallexample
-(@value{GDBP}) alias faalocalsoftype = frame apply all info locals -q -t
-(@value{GDBP}) faalocalsoftype int
-#1 0x55554f5e in sleeper_or_burner (v=0xdf50) at sleepers.c:86
-i = 0
-ret = 21845
-@end smallexample
-
-This is also very useful to define an alias for a set of nested @code{with}
-commands to have a particular combination of temporary settings. For example,
-the below defines the alias @code{pp10} that pretty prints an expression
-argument, with a maximum of 10 elements if the expression is a string or
-an array:
-@smallexample
-(@value{GDBP}) alias pp10 = with print pretty -- with print elements 10 -- print
-@end smallexample
-This defines the alias @code{pp10} as being a sequence of 3 commands.
-The first part @code{with print pretty --} temporarily activates the setting
-@code{set print pretty}, then launches the command that follows the separator
-@code{--}.
-The command following the first part is also a @code{with} command that
-temporarily changes the setting @code{set print elements} to 10, then
-launches the command that follows the second separator @code{--}.
-The third part @code{print} is the command the @code{pp10} alias will launch,
-using the temporary values of the settings and the arguments explicitly given
-by the user.
-For more information about the @code{with} command usage,
-see @ref{Command Settings}.
-
@node Help
@section Getting Help
@cindex online documentation
above (or no argument) specifying where to break. @xref{Conditions,
,Break Conditions}, for more information on breakpoint conditions.
+The breakpoint may be mapped to multiple locations. If the breakpoint
+condition @var{cond} is invalid at some but not all of the locations,
+the locations for which the condition is invalid are disabled. For
+example, @value{GDBN} reports below that two of the three locations
+are disabled.
+
+@smallexample
+(@value{GDBP}) break func if a == 10
+warning: failed to validate condition at location 0x11ce, disabling:
+ No symbol "a" in current context.
+warning: failed to validate condition at location 0x11b6, disabling:
+ No symbol "a" in current context.
+Breakpoint 1 at 0x11b6: func. (3 locations)
+@end smallexample
+
+Locations that are disabled because of the condition are denoted by an
+uppercase @code{N} in the output of the @code{info breakpoints}
+command:
+
+@smallexample
+(@value{GDBP}) info breakpoints
+Num Type Disp Enb Address What
+1 breakpoint keep y <MULTIPLE>
+ stop only if a == 10
+1.1 N* 0x00000000000011b6 in ...
+1.2 y 0x00000000000011c2 in ...
+1.3 N* 0x00000000000011ce in ...
+(*): Breakpoint condition is invalid at this location.
+@end smallexample
+
+If the breakpoint condition @var{cond} is invalid in the context of
+@emph{all} the locations of the breakpoint, @value{GDBN} refuses to
+define the breakpoint. For example, if variable @code{foo} is an
+undefined variable:
+
+@smallexample
+(@value{GDBP}) break func if foo
+No symbol "foo" in current context.
+@end smallexample
+
+@item break @dots{} -force-condition if @var{cond}
+There may be cases where the condition @var{cond} is invalid at all
+the current locations, but the user knows that it will be valid at a
+future location; for example, because of a library load. In such
+cases, by using the @code{-force-condition} keyword before @samp{if},
+@value{GDBN} can be forced to define the breakpoint with the given
+condition expression instead of refusing it.
+
+@smallexample
+(@value{GDBP}) break func -force-condition if foo
+warning: failed to validate condition at location 1, disabling:
+ No symbol "foo" in current context.
+warning: failed to validate condition at location 2, disabling:
+ No symbol "foo" in current context.
+warning: failed to validate condition at location 3, disabling:
+ No symbol "foo" in current context.
+Breakpoint 1 at 0x1158: test.c:18. (3 locations)
+@end smallexample
+
+This causes all the present locations where the breakpoint would
+otherwise be inserted, to be disabled, as seen in the example above.
+However, if there exist locations at which the condition is valid, the
+@code{-force-condition} keyword has no effect.
+
@kindex tbreak
@item tbreak @var{args}
Set a breakpoint enabled only for one stop. The @var{args} are the
command (or a command that sets a breakpoint with a condition, like
@code{break if @dots{}}) is given, however. @xref{Expressions, ,Expressions}.
+@item condition -force @var{bnum} @var{expression}
+When the @code{-force} flag is used, define the condition even if
+@var{expression} is invalid at all the current locations of breakpoint
+@var{bnum}. This is similar to the @code{-force-condition} option
+of the @code{break} command.
+
@item condition @var{bnum}
Remove the condition from breakpoint number @var{bnum}. It becomes
an ordinary unconditional breakpoint.
@kindex show dcache line-size
Show default size of dcache lines.
+@item maint flush dcache
+@cindex dcache, flushing
+@kindex maint flush dcache
+Flush the contents (if any) of the dcache. This maintainer command is
+useful when debugging the dcache implementation.
+
@end table
@node Searching Memory
memory that the process does not own (a typical example from many Unix
systems).
-@item show range
+@item show check range
Show the current setting of the range checker, and whether or not it is
being set automatically by @value{GDBN}.
@end table
block whose name is @var{common-name}. With no argument, the names of
all @code{COMMON} blocks visible at the current program location are
printed.
+@cindex arrays slices (Fortran)
+@kindex set fortran repack-array-slices
+@kindex show fortran repack-array-slices
+@item set fortran repack-array-slices [on|off]
+@item show fortran repack-array-slices
+When taking a slice from an array, a Fortran compiler can choose to
+either produce an array descriptor that describes the slice in place,
+or it may repack the slice, copying the elements of the slice into a
+new region of memory.
+
+When this setting is on, then @value{GDBN} will also repack array
+slices in some situations. When this setting is off, then
+@value{GDBN} will create array descriptors for slices that reference
+the original data in place.
+
+@value{GDBN} will never repack an array slice if the data for the
+slice is contiguous within the original array.
+
+@value{GDBN} will always repack string slices if the data for the
+slice is non-contiguous within the original string as @value{GDBN}
+does not support printing non-contiguous strings.
+
+The default for this setting is @code{off}.
@end table
@node Pascal
Print symbol cache usage statistics.
This helps determine how well the cache is being utilized.
+@kindex maint flush symbol-cache
@kindex maint flush-symbol-cache
@cindex symbol cache, flushing
-@item maint flush-symbol-cache
-Flush the contents of the symbol cache, all entries are removed.
-This command is useful when debugging the symbol cache.
-It is also useful when collecting performance data.
+@item maint flush symbol-cache
+@itemx maint flush-symbol-cache
+Flush the contents of the symbol cache, all entries are removed. This
+command is useful when debugging the symbol cache. It is also useful
+when collecting performance data. The command @code{maint
+flush-symbol-cache} is deprecated in favor of @code{maint flush
+symbol-cache}..
@end table
implement in hardware simple hardware watchpoint conditions of the form:
@smallexample
-(@value{GDBP}) watch @var{ADDRESS|VARIABLE} \
- if @var{ADDRESS|VARIABLE} == @var{CONSTANT EXPRESSION}
+(@value{GDBP}) watch @var{address|variable} \
+ if @var{address|variable} == @var{constant expression}
@end smallexample
The DVC register will be automatically used when @value{GDBN} detects
@code{set style address} family of commands. By default, this style's
foreground color is blue.
+@item version
+Control the styling of @value{GDBN}'s version number text. By
+default, this style's foreground color is magenta and it has bold
+intensity. The version number is displayed in two places, the output
+of @command{show version}, and when @value{GDBN} starts up.
+
+Currently the version string displayed at startup is printed before
+@value{GDBN} has parsed any command line options, or parsed any
+command files, so there is currently no way to control the styling of
+this string. However, @value{GDBN}'s @code{--quiet} command line option
+can be used to disable printing of the version string on startup.
+
@item title
Control the styling of titles. These are managed with the
@code{set style title} family of commands. By default, this style's
@item show exec-done-display
Displays the current setting of asynchronous command completion
notification.
+
@kindex set debug
@cindex ARM AArch64
@item set debug aarch64
@item show debug aarch64
Displays the current state of displaying debugging messages related to
ARM AArch64.
+
@cindex gdbarch debugging info
@cindex architecture debugging info
@item set debug arch
Turns on or off display of gdbarch debugging info. The default is off
@item show debug arch
Displays the current state of displaying gdbarch debugging info.
+
@item set debug aix-solib
@cindex AIX shared library debugging
Control display of debugging messages from the AIX shared library
support module. The default is off.
-@item show debug aix-thread
+@item show debug aix-solib
Show the current state of displaying AIX shared library debugging messages.
+
@item set debug aix-thread
@cindex AIX threads
Display debugging messages about inner workings of the AIX thread
module.
@item show debug aix-thread
Show the current state of AIX thread debugging info display.
+
@item set debug check-physname
@cindex physname
Check the results of the ``physname'' computation. When reading DWARF
both ways and display any discrepancies.
@item show debug check-physname
Show the current state of ``physname'' checking.
+
@item set debug coff-pe-read
@cindex COFF/PE exported symbols
Control display of debugging messages related to reading of COFF/PE
@item show debug coff-pe-read
Displays the current state of displaying debugging messages related to
reading of COFF/PE exported symbols.
+
@item set debug dwarf-die
@cindex DWARF DIEs
Dump DWARF DIEs after they are read in.
A value of zero turns off the display.
@item show debug dwarf-die
Show the current state of DWARF DIE debugging.
+
@item set debug dwarf-line
@cindex DWARF Line Tables
Turns on or off display of debugging messages related to reading
A value greater than 1 provides more verbose information.
@item show debug dwarf-line
Show the current state of DWARF line table debugging.
+
@item set debug dwarf-read
@cindex DWARF Reading
Turns on or off display of debugging messages related to reading
A value greater than 1 provides more verbose information.
@item show debug dwarf-read
Show the current state of DWARF reader debugging.
+
@item set debug displaced
@cindex displaced stepping debugging info
Turns on or off display of @value{GDBN} debugging info for the
@item show debug displaced
Displays the current state of displaying @value{GDBN} debugging info
related to displaced stepping.
+
@item set debug event
@cindex event debugging info
Turns on or off display of @value{GDBN} event debugging info. The
@item show debug event
Displays the current state of displaying @value{GDBN} event debugging
info.
+
+@item set debug event-loop
+@cindex event-loop debugging
+Controls output of debugging info about the event loop. The possible
+values are @samp{off}, @samp{all} (shows all debugging info) and
+@samp{all-except-ui} (shows all debugging info except those about
+UI-related events).
+@item show debug event-loop
+Shows the current state of displaying debugging info about the event
+loop.
+
@item set debug expression
@cindex expression debugging info
Turns on or off display of debugging info about @value{GDBN}
@item show debug expression
Displays the current state of displaying debugging info about
@value{GDBN} expression parsing.
+
@item set debug fbsd-lwp
@cindex FreeBSD LWP debug messages
Turns on or off debugging messages from the FreeBSD LWP debug support.
@item show debug fbsd-lwp
Show the current state of FreeBSD LWP debugging messages.
+
@item set debug fbsd-nat
@cindex FreeBSD native target debug messages
Turns on or off debugging messages from the FreeBSD native target.
@item show debug fbsd-nat
Show the current state of FreeBSD native target debugging messages.
+
+@item set debug fortran-array-slicing
+@cindex fortran array slicing debugging info
+Turns on or off display of @value{GDBN} Fortran array slicing
+debugging info. The default is off.
+
+@item show debug fortran-array-slicing
+Displays the current state of displaying @value{GDBN} Fortran array
+slicing debugging info.
+
@item set debug frame
@cindex frame debugging info
Turns on or off display of @value{GDBN} frame debugging info. The
@item show debug frame
Displays the current state of displaying @value{GDBN} frame debugging
info.
+
@item set debug gnu-nat
@cindex @sc{gnu}/Hurd debug messages
Turn on or off debugging messages from the @sc{gnu}/Hurd debug support.
@item show debug gnu-nat
Show the current state of @sc{gnu}/Hurd debugging messages.
+
@item set debug infrun
@cindex inferior debugging info
Turns on or off display of @value{GDBN} debugging info for running the inferior.
for implementing operations such as single-stepping the inferior.
@item show debug infrun
Displays the current state of @value{GDBN} inferior debugging.
+
@item set debug jit
@cindex just-in-time compilation, debugging messages
Turn on or off debugging messages from JIT debug support.
@item show debug jit
Displays the current state of @value{GDBN} JIT debugging.
+
@item set debug lin-lwp
@cindex @sc{gnu}/Linux LWP debug messages
@cindex Linux lightweight processes
Turn on or off debugging messages from the Linux LWP debug support.
@item show debug lin-lwp
Show the current state of Linux LWP debugging messages.
+
@item set debug linux-namespaces
@cindex @sc{gnu}/Linux namespaces debug messages
Turn on or off debugging messages from the Linux namespaces debug support.
@item show debug linux-namespaces
Show the current state of Linux namespaces debugging messages.
+
@item set debug mach-o
@cindex Mach-O symbols processing
Control display of debugging messages related to Mach-O symbols
@item show debug mach-o
Displays the current state of displaying debugging messages related to
reading of COFF/PE exported symbols.
+
@item set debug notification
@cindex remote async notification debugging info
Turn on or off debugging messages about remote async notification.
The default is off.
@item show debug notification
Displays the current state of remote async notification debugging messages.
+
@item set debug observer
@cindex observer debugging info
Turns on or off display of @value{GDBN} observer debugging. This
includes info such as the notification of observable events.
@item show debug observer
Displays the current state of observer debugging.
+
@item set debug overload
@cindex C@t{++} overload debugging info
Turns on or off display of @value{GDBN} C@t{++} overload debugging
@item show debug overload
Displays the current state of displaying @value{GDBN} C@t{++} overload
debugging info.
+
@cindex expression parser, debugging info
@cindex debug expression parser
@item set debug parser
details. The default is off.
@item show debug parser
Show the current state of expression parser debugging.
+
@cindex packets, reporting on stdout
@cindex serial connections, debugging
@cindex debug remote protocol
@item show debug serial
Displays the current state of displaying @value{GDBN} serial debugging
info.
+
@item set debug solib-frv
@cindex FR-V shared-library debugging
Turn on or off debugging messages for FR-V shared-library code.
@item show debug solib-frv
Display the current state of FR-V shared-library code debugging
messages.
+
@item set debug symbol-lookup
@cindex symbol lookup
Turns on or off display of debugging messages related to symbol lookup.
A value greater than 1 provides more verbose information.
@item show debug symbol-lookup
Show the current state of symbol lookup debugging messages.
+
@item set debug symfile
@cindex symbol file functions
Turns on or off display of debugging messages related to symbol file functions.
The default is off. @xref{Files}.
@item show debug symfile
Show the current state of symbol file debugging messages.
+
@item set debug symtab-create
@cindex symbol table creation
Turns on or off display of debugging messages related to symbol table creation.
A value greater than 1 provides more verbose information.
@item show debug symtab-create
Show the current state of symbol table creation debugging.
+
@item set debug target
@cindex target debugging info
Turns on or off display of @value{GDBN} target debugging info. This info
@item show debug target
Displays the current state of displaying @value{GDBN} target debugging
info.
+
@item set debug timestamp
@cindex timestamping debugging info
Turns on or off display of timestamps with @value{GDBN} debugging info.
@item show debug timestamp
Displays the current state of displaying timestamps with @value{GDBN}
debugging info.
+
@item set debug varobj
@cindex variable object debugging info
Turns on or off display of @value{GDBN} variable object debugging
@item show debug varobj
Displays the current state of displaying @value{GDBN} variable object
debugging info.
+
@item set debug xml
@cindex XML parser debugging
Turn on or off debugging messages for built-in XML parsers.
@menu
* Sequences:: Canned Sequences of @value{GDBN} Commands
+* Aliases:: Command Aliases
* Python:: Extending @value{GDBN} using Python
* Guile:: Extending @value{GDBN} using Guile
* Auto-loading extensions:: Automatically loading extensions
* Multiple Extension Languages:: Working with multiple extension languages
-* Aliases:: Creating new spellings of existing commands
@end menu
To facilitate the use of extension languages, @value{GDBN} is capable
If @var{regexp} is supplied only canned sequences of commands scripts with
matching names are printed.
+@node Aliases
+@section Command Aliases
+@cindex aliases for commands
+
+Aliases allow you to define alternate spellings for existing commands.
+For example, if a new @value{GDBN} command defined in Python
+(@pxref{Python}) has a long name, it is handy to have an abbreviated
+version of it that involves less typing.
+
+@value{GDBN} itself uses aliases. For example @samp{s} is an alias
+of the @samp{step} command even though it is otherwise an ambiguous
+abbreviation of other commands like @samp{set} and @samp{show}.
+
+Aliases are also used to provide shortened or more common versions
+of multi-word commands. For example, @value{GDBN} provides the
+@samp{tty} alias of the @samp{set inferior-tty} command.
+
+You can define a new alias with the @samp{alias} command.
+
+@table @code
+
+@kindex alias
+@item alias [-a] [--] @var{alias} = @var{command} [@var{default-args}]
+
+@end table
+
+@var{alias} specifies the name of the new alias. Each word of
+@var{alias} must consist of letters, numbers, dashes and underscores.
+
+@var{command} specifies the name of an existing command
+that is being aliased.
+
+@var{command} can also be the name of an existing alias. In this
+case, @var{command} cannot be an alias that has default arguments.
+
+The @samp{-a} option specifies that the new alias is an abbreviation
+of the command. Abbreviations are not used in command completion.
+
+The @samp{--} option specifies the end of options,
+and is useful when @var{alias} begins with a dash.
+
+You can specify @var{default-args} for your alias. These
+@var{default-args} will be automatically added before the alias
+arguments typed explicitly on the command line.
+
+For example, the below defines an alias @code{btfullall} that shows all local
+variables and all frame arguments:
+@smallexample
+(@value{GDBP}) alias btfullall = backtrace -full -frame-arguments all
+@end smallexample
+
+For more information about @var{default-args}, see @ref{Command
+aliases default args, ,Default Arguments}.
+
+Here is a simple example showing how to make an abbreviation of a
+command so that there is less to type. Suppose you were tired of
+typing @samp{disas}, the current shortest unambiguous abbreviation of
+the @samp{disassemble} command and you wanted an even shorter version
+named @samp{di}. The following will accomplish this.
+
+@smallexample
+(gdb) alias -a di = disas
+@end smallexample
+
+Note that aliases are different from user-defined commands. With a
+user-defined command, you also need to write documentation for it with
+the @samp{document} command. An alias automatically picks up the
+documentation of the existing command.
+
+Here is an example where we make @samp{elms} an abbreviation of
+@samp{elements} in the @samp{set print elements} command.
+This is to show that you can make an abbreviation of any part
+of a command.
+
+@smallexample
+(gdb) alias -a set print elms = set print elements
+(gdb) alias -a show print elms = show print elements
+(gdb) set p elms 20
+(gdb) show p elms
+Limit on string chars or array elements to print is 200.
+@end smallexample
+
+Note that if you are defining an alias of a @samp{set} command,
+and you want to have an alias for the corresponding @samp{show}
+command, then you need to define the latter separately.
+
+Unambiguously abbreviated commands are allowed in @var{command} and
+@var{alias}, just as they are normally.
+
+@smallexample
+(gdb) alias -a set pr elms = set p ele
+@end smallexample
+
+Finally, here is an example showing the creation of a one word
+alias for a more complex command.
+This creates alias @samp{spe} of the command @samp{set print elements}.
+
+@smallexample
+(gdb) alias spe = set print elements
+(gdb) spe 20
+@end smallexample
+
+@menu
+* Command aliases default args:: Default arguments for aliases
+@end menu
+
+@node Command aliases default args
+@subsection Default Arguments
+@cindex aliases for commands, default arguments
+
+You can tell @value{GDBN} to always prepend some default arguments to
+the list of arguments provided explicitly by the user when using a
+user-defined alias.
+
+If you repeatedly use the same arguments or options for a command, you
+can define an alias for this command and tell @value{GDBN} to
+automatically prepend these arguments or options to the list of
+arguments you type explicitly when using the alias@footnote{@value{GDBN}
+could easily accept default arguments for pre-defined commands and aliases,
+but it was deemed this would be confusing, and so is not allowed.}.
+
+For example, if you often use the command @code{thread apply all}
+specifying to work on the threads in ascending order and to continue in case it
+encounters an error, you can tell @value{GDBN} to automatically preprend
+the @code{-ascending} and @code{-c} options by using:
+
+@smallexample
+(@value{GDBP}) alias thread apply asc-all = thread apply all -ascending -c
+@end smallexample
+
+Once you have defined this alias with its default args, any time you type
+the @code{thread apply asc-all} followed by @code{some arguments},
+@value{GDBN} will execute @code{thread apply all -ascending -c some arguments}.
+
+To have even less to type, you can also define a one word alias:
+@smallexample
+(@value{GDBP}) alias t_a_c = thread apply all -ascending -c
+@end smallexample
+
+As usual, unambiguous abbreviations can be used for @var{alias}
+and @var{default-args}.
+
+The different aliases of a command do not share their default args.
+For example, you define a new alias @code{bt_ALL} showing all possible
+information and another alias @code{bt_SMALL} showing very limited information
+using:
+@smallexample
+(@value{GDBP}) alias bt_ALL = backtrace -entry-values both -frame-arg all \
+ -past-main -past-entry -full
+(@value{GDBP}) alias bt_SMALL = backtrace -entry-values no -frame-arg none \
+ -past-main off -past-entry off
+@end smallexample
+
+(For more on using the @code{alias} command, see @ref{Aliases}.)
+
+Default args are not limited to the arguments and options of @var{command},
+but can specify nested commands if @var{command} accepts such a nested command
+as argument.
+For example, the below defines @code{faalocalsoftype} that lists the
+frames having locals of a certain type, together with the matching
+local vars:
+@smallexample
+(@value{GDBP}) alias faalocalsoftype = frame apply all info locals -q -t
+(@value{GDBP}) faalocalsoftype int
+#1 0x55554f5e in sleeper_or_burner (v=0xdf50) at sleepers.c:86
+i = 0
+ret = 21845
+@end smallexample
+
+This is also very useful to define an alias for a set of nested @code{with}
+commands to have a particular combination of temporary settings. For example,
+the below defines the alias @code{pp10} that pretty prints an expression
+argument, with a maximum of 10 elements if the expression is a string or
+an array:
+@smallexample
+(@value{GDBP}) alias pp10 = with print pretty -- with print elements 10 -- print
+@end smallexample
+This defines the alias @code{pp10} as being a sequence of 3 commands.
+The first part @code{with print pretty --} temporarily activates the setting
+@code{set print pretty}, then launches the command that follows the separator
+@code{--}.
+The command following the first part is also a @code{with} command that
+temporarily changes the setting @code{set print elements} to 10, then
+launches the command that follows the second separator @code{--}.
+The third part @code{print} is the command the @code{pp10} alias will launch,
+using the temporary values of the settings and the arguments explicitly given
+by the user.
+For more information about the @code{with} command usage,
+see @ref{Command Settings}.
+
@c Python docs live in a separate file.
@include python.texi
@section Auto-loading extensions
@cindex auto-loading extensions
-@value{GDBN} provides two mechanisms for automatically loading extensions
-when a new object file is read (for example, due to the @code{file}
-command, or because the inferior has loaded a shared library):
-@file{@var{objfile}-gdb.@var{ext}} and the @code{.debug_gdb_scripts}
-section of modern file formats like ELF.
-
-@menu
-* objfile-gdb.ext file: objfile-gdbdotext file. The @file{@var{objfile}-gdb.@var{ext}} file
-* .debug_gdb_scripts section: dotdebug_gdb_scripts section. The @code{.debug_gdb_scripts} section
-* Which flavor to choose?::
-@end menu
+@value{GDBN} provides two mechanisms for automatically loading
+extensions when a new object file is read (for example, due to the
+@code{file} command, or because the inferior has loaded a shared
+library): @file{@var{objfile}-gdb.@var{ext}} (@pxref{objfile-gdbdotext
+file,,The @file{@var{objfile}-gdb.@var{ext}} file}) and the
+@code{.debug_gdb_scripts} section of modern file formats like ELF
+(@pxref {dotdebug_gdb_scripts section,,The @code{.debug_gdb_scripts}
+section}). For a discussion of the differences between these two
+approaches see @ref{Which flavor to choose?}.
The auto-loading feature is useful for supplying application-specific
debugging commands and features.
Note that loading of this script file also requires accordingly configured
@code{auto-load safe-path} (@pxref{Auto-loading safe path}).
+@menu
+* objfile-gdbdotext file:: The @file{@var{objfile}-gdb.@var{ext}} file
+* dotdebug_gdb_scripts section:: The @code{.debug_gdb_scripts} section
+* Which flavor to choose?:: Choosing between these approaches
+@end menu
+
@node objfile-gdbdotext file
@subsection The @file{@var{objfile}-gdb.@var{ext}} file
@cindex @file{@var{objfile}-gdb.gdb}
while, for example, trying to pretty-print an object then the error is
reported and any following extension languages are not tried.
-@node Aliases
-@section Creating new spellings of existing commands
-@cindex aliases for commands
-
-It is often useful to define alternate spellings of existing commands.
-For example, if a new @value{GDBN} command defined in Python has
-a long name to type, it is handy to have an abbreviated version of it
-that involves less typing.
-
-@value{GDBN} itself uses aliases. For example @samp{s} is an alias
-of the @samp{step} command even though it is otherwise an ambiguous
-abbreviation of other commands like @samp{set} and @samp{show}.
-
-Aliases are also used to provide shortened or more common versions
-of multi-word commands. For example, @value{GDBN} provides the
-@samp{tty} alias of the @samp{set inferior-tty} command.
-
-You can define a new alias with the @samp{alias} command.
-
-@table @code
-
-@kindex alias
-@item alias [-a] [--] @var{ALIAS} = @var{COMMAND} [DEFAULT-ARGS...]
-
-@end table
-
-@var{ALIAS} specifies the name of the new alias.
-Each word of @var{ALIAS} must consist of letters, numbers, dashes and
-underscores.
-
-@var{COMMAND} specifies the name of an existing command
-that is being aliased.
-
-@var{COMMAND} can also be the name of an existing alias. In this case,
-@var{COMMAND} cannot be an alias that has default arguments.
-
-The @samp{-a} option specifies that the new alias is an abbreviation
-of the command. Abbreviations are not used in command completion.
-
-The @samp{--} option specifies the end of options,
-and is useful when @var{ALIAS} begins with a dash.
-
-You can specify @var{default-args} for your alias.
-These @var{default-args} will be automatically added before the alias
-arguments typed explicitly on the command line.
-
-For example, the below defines an alias @code{btfullall} that shows all local
-variables and all frame arguments:
-@smallexample
-(@value{GDBP}) alias btfullall = backtrace -full -frame-arguments all
-@end smallexample
-
-For more information about @var{default-args}, see @ref{Command aliases default args,
-,Automatically prepend default arguments to user-defined aliases}.
-
-Here is a simple example showing how to make an abbreviation
-of a command so that there is less to type.
-Suppose you were tired of typing @samp{disas}, the current
-shortest unambiguous abbreviation of the @samp{disassemble} command
-and you wanted an even shorter version named @samp{di}.
-The following will accomplish this.
-
-@smallexample
-(gdb) alias -a di = disas
-@end smallexample
-
-Note that aliases are different from user-defined commands.
-With a user-defined command, you also need to write documentation
-for it with the @samp{document} command.
-An alias automatically picks up the documentation of the existing command.
-
-Here is an example where we make @samp{elms} an abbreviation of
-@samp{elements} in the @samp{set print elements} command.
-This is to show that you can make an abbreviation of any part
-of a command.
-
-@smallexample
-(gdb) alias -a set print elms = set print elements
-(gdb) alias -a show print elms = show print elements
-(gdb) set p elms 20
-(gdb) show p elms
-Limit on string chars or array elements to print is 200.
-@end smallexample
-
-Note that if you are defining an alias of a @samp{set} command,
-and you want to have an alias for the corresponding @samp{show}
-command, then you need to define the latter separately.
-
-Unambiguously abbreviated commands are allowed in @var{COMMAND} and
-@var{ALIAS}, just as they are normally.
-
-@smallexample
-(gdb) alias -a set pr elms = set p ele
-@end smallexample
-
-Finally, here is an example showing the creation of a one word
-alias for a more complex command.
-This creates alias @samp{spe} of the command @samp{set print elements}.
-
-@smallexample
-(gdb) alias spe = set print elements
-(gdb) spe 20
-@end smallexample
-
@node Interpreters
@chapter Command Interpreters
@cindex command interpreters
@item GNU make
@value{GDBN}'s build system relies on features only found in the GNU
make program. Other variants of @code{make} will not work.
+
+@item GMP (The GNU Multiple Precision Arithmetic Library)
+@value{GDBN} now uses GMP to perform some of its arithmetics.
+This library may be included with your operating system distribution;
+if it is not, you can get the latest version from
+@url{https://gmplib.org/}. If GMP is installed at an unusual path,
+you can use the @option{--with-libgmp-prefix} option to specify
+its location.
+
@end table
@heading Tools/Packages Optional for Building @value{GDBN}
Print the entire architecture configuration. The optional argument
@var{file} names the file where the output goes.
-@kindex maint print c-tdesc @r{[}@var{file}@r{]}
-@item maint print c-tdesc
+@kindex maint print c-tdesc
+@item maint print c-tdesc @r{[}-single-feature@r{]} @r{[}@var{file}@r{]}
Print the target description (@pxref{Target Descriptions}) as
a C source file. By default, the target description is for the current
target, but if the optional argument @var{file} is provided, that file
built again. This command is used by developers after they add or
modify XML target descriptions.
+When the optional flag @samp{-single-feature} is provided then the
+target description being processed (either the default, or from
+@var{file}) must only contain a single feature. The source file
+produced is different in this case.
+
@kindex maint print xml-tdesc
@item maint print xml-tdesc @r{[}@var{file}@r{]}
Print the target description (@pxref{Target Descriptions}) as an XML
restore internal
@end smallexample
+@kindex maint flush register-cache
@kindex flushregs
-@item flushregs
-This command forces @value{GDBN} to flush its internal register cache.
+@cindex register cache, flushing
+@item maint flush register-cache
+@itemx flushregs
+Flush the contents of the register cache and as a consequence the
+frame cache. This command is useful when debugging issues related to
+register fetching, or frame unwinding. The command @code{flushregs}
+is deprecated in favor of @code{maint flush register-cache}.
@kindex maint print objfiles
@cindex info for known object files
@item ?
@cindex @samp{?} packet
@anchor{? packet}
-Indicate the reason the target halted. The reply is the same as for
-step and continue. This packet has a special interpretation when the
-target is in non-stop mode; see @ref{Remote Non-Stop}.
+This is sent when connection is first established to query the reason
+the target halted. The reply is the same as for step and continue.
+This packet has a special interpretation when the target is in
+non-stop mode; see @ref{Remote Non-Stop}.
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
Add @var{directory} to the path to search for source files.
@item -nh
-Do not execute commands from @file{~/.gdbinit}.
+Do not execute commands from @file{~/.config/gdb/gdbinit} or
+@file{~/.gdbinit}.
@item -nx
@itemx -n
@value{SYSTEM_GDBINIT_DIR}/*
@end ifset
+~/.config/gdb/gdbinit
+
~/.gdbinit
./.gdbinit
@ref{System-wide configuration}.
@end ifclear
-@item ~/.gdbinit
+@item @file{~/.config/gdb/gdbinit} or @file{~/.gdbinit}
User initialization file. It is executed unless user specified
@value{GDBN} options @code{-nx}, @code{-n} or @code{-nh}.
-@item ./.gdbinit
+@item @file{.gdbinit}
Initialization file for current directory. It may need to be enabled with
@value{GDBN} security command @code{set auto-load local-gdbinit}.
See more in
projects / binutils-gdb.git / blobdiff