\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
@page
@ifnottex
-@node Top, Summary, (dir), (dir)
+@node Top, Summary
@top Debugging with @value{GDBN}
@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
of Jeremy Bennett, Franck Jullien, Stefan Wallentowitz and
Stafford Horne.
+Weimin Pan, David Faust and Jose E. Marchesi contributed support for
+the Linux kernel BPF virtual architecture. This work was sponsored by
+Oracle.
+
@node Sample Session
@chapter A Sample @value{GDBN} Session
* 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}
@itemx !@var{command-string}
Invoke a standard shell to execute @var{command-string}.
Note that no space is needed between @code{!} and @var{command-string}.
-If it exists, the environment variable @code{SHELL} determines which
-shell to run. Otherwise @value{GDBN} uses the default shell
-(@file{/bin/sh} on Unix systems, @file{COMMAND.COM} on MS-DOS, etc.).
+On GNU and Unix systems, the environment variable @code{SHELL}, if it
+exists, determines which shell to run. Otherwise @value{GDBN} uses
+the default shell (@file{/bin/sh} on GNU and Unix systems,
+@file{cmd.exe} on MS-Windows, @file{COMMAND.COM} on MS-DOS, etc.).
@end table
The utility @code{make} is often needed in development environments.
(@value{GDBP}) help
List of classes of commands:
-aliases -- Aliases of other commands
+aliases -- User-defined aliases of other commands
breakpoints -- Making program stop at certain points
data -- Examining data
files -- Specifying and examining files
@item help @var{class}
Using one of the general help classes as an argument, you can get a
-list of the individual commands in that class. For example, here is the
-help display for the class @code{status}:
+list of the individual commands in that class. If a command has
+aliases, the aliases are given after the command name, separated by
+commas. If an alias has default arguments, the full definition of
+the alias is given after the first line.
+For example, here is the help display for the class @code{status}:
@smallexample
(@value{GDBP}) help status
@c Line break in "show" line falsifies real output, but needed
@c to fit in smallbook page size.
-info -- Generic command for showing things
+info, inf, i -- Generic command for showing things
about the program being debugged
-show -- Generic command for showing things
+info address, iamain -- Describe where symbol SYM is stored.
+ alias iamain = info address main
+info all-registers -- List of all registers and their contents,
+ for selected stack frame.
+...
+show, info set -- Generic command for showing things
about the debugger
Type "help" followed by command name for full
@item help @var{command}
With a command name as @code{help} argument, @value{GDBN} displays a
-short paragraph on how to use that command.
+short paragraph on how to use that command. If that command has
+one or more aliases, @value{GDBN} will display a first line with
+the command name and all its aliases separated by commas.
+This first line will be followed by the full definition of all aliases
+having default arguments.
@kindex apropos
@item apropos [-v] @var{regexp}
@smallexample
@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
+aliases -- User-defined aliases of other commands
@end group
@end smallexample
Specify Files}.
@anchor{set exec-file-mismatch}
-If the debugger can determine the name of the executable file running
-in the process it is attaching to, and this file name does not match
-the name of the current exec-file loaded by @value{GDBN}, the option
-@code{exec-file-mismatch} specifies how to handle the mismatch.
+If the debugger can determine that the executable file running in the
+process it is attaching to does not match the current exec-file loaded
+by @value{GDBN}, the option @code{exec-file-mismatch} specifies how to
+handle the mismatch. @value{GDBN} tries to compare the files by
+comparing their build IDs (@pxref{build ID}), if available.
@table @code
@kindex exec-file-mismatch
@cindex set exec-file-mismatch
@item set exec-file-mismatch @samp{ask|warn|off}
-Whether to detect mismatch between the name of the current executable
-file loaded by @value{GDBN} and the name of the executable file used to
-start the process. If @samp{ask}, the default, display a warning
-and ask the user whether to load the process executable file; if
-@samp{warn}, just display a warning; if @samp{off}, don't attempt to
-detect a mismatch.
+Whether to detect mismatch between the current executable file loaded
+by @value{GDBN} and the executable file used to start the process. If
+@samp{ask}, the default, display a warning and ask the user whether to
+load the process executable file; if @samp{warn}, just display a
+warning; if @samp{off}, don't attempt to detect a mismatch.
+If the user confirms loading the process executable file, then its symbols
+will be loaded as well.
@cindex show exec-file-mismatch
@item show exec-file-mismatch
@end smallexample
The @code{tfaas} command accepts the same options as the @code{frame
-apply} command. @xref{frame apply}.
+apply} command. @xref{Frame Apply,,frame apply}.
@kindex thread name
@cindex name a thread
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.
@node Frame Apply
@section Applying a Command to Several Frames.
-@anchor{frame apply}
@kindex frame apply
@cindex apply command to several frames
@table @code
@end smallexample
The @code{faas} command accepts the same options as the @code{frame
-apply} command. @xref{frame apply}.
+apply} command. @xref{Frame Apply,,frame apply}.
Note that the command @code{tfaas @var{command}} applies @var{command}
on all frames of all threads. See @xref{Threads,,Threads}.
Print the names and values of all registers, including floating-point
and vector registers (in the selected stack frame).
+@anchor{info_registers_reggroup}
@item info registers @var{reggroup} @dots{}
Print the name and value of the registers in each of the specified
@var{reggroup}s. The @var{reggroup} can be any of those returned by
@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
@end table
+@cindex Ravenscar thread
+When Ravenscar task-switching is enabled, Ravenscar tasks are
+announced by @value{GDBN} as if they were threads:
+
+@smallexample
+(gdb) continue
+[New Ravenscar Thread 0x2b8f0]
+@end smallexample
+
+Both Ravenscar tasks and the underlying CPU threads will show up in
+the output of @code{info threads}:
+
+@smallexample
+(gdb) info threads
+ Id Target Id Frame
+ 1 Thread 1 (CPU#0 [running]) simple () at simple.adb:10
+ 2 Thread 2 (CPU#1 [running]) 0x0000000000003d34 in __gnat_initialize_cpu_devices ()
+ 3 Thread 3 (CPU#2 [running]) 0x0000000000003d28 in __gnat_initialize_cpu_devices ()
+ 4 Thread 4 (CPU#3 [halted ]) 0x000000000000c6ec in system.task_primitives.operations.idle ()
+* 5 Ravenscar Thread 0x2b8f0 simple () at simple.adb:10
+ 6 Ravenscar Thread 0x2f150 0x000000000000c6ec in system.task_primitives.operations.idle ()
+@end smallexample
+
+One known limitation of the Ravenscar support in @value{GDBN} is that
+it isn't currently possible to single-step through the runtime
+initialization sequence. If you need to debug this code, you should
+use @code{set ravenscar task-switching off}.
+
@node Ada Settings
@subsubsection Ada Settings
@cindex Ada settings
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
add symbol table from file "/home/user/gdb/mylib.so" at
.text_addr = 0x7ffff7ff9480
(y or n) y
-Reading symbols from /home/user/gdb/mylib.so...done.
+Reading symbols from /home/user/gdb/mylib.so...
(gdb) remove-symbol-file -a 0x7ffff7ff9480
Remove symbol table from file "/home/user/gdb/mylib.so"? (y or n) y
(gdb)
to use @code{catch load} and @code{catch unload} (@pxref{Set
Catchpoints}).
-@value{GDBN} also supports the the @code{set stop-on-solib-events}
+@value{GDBN} also supports the @code{set stop-on-solib-events}
command for this. This command exists for historical reasons. It is
less useful than setting a catchpoint, because it does not allow for
conditions or commands as a catchpoint does.
the executable and the debug file came from the same build.
@item
+@anchor{build ID}
The executable contains a @dfn{build ID}, a unique bit string that is
also present in the corresponding debug info file. (This is supported
only on some operating systems, when using the ELF or PE file formats
$ gdb -iex "set use-deprecated-index-sections on" <program>
@end smallexample
-There are currently some limitation on indices. They only work when
-using DWARF debugging information, not stabs. And, only the
-@code{-dwarf-5} index works for programs using Ada.
+Indices only work when using DWARF debugging information, not stabs.
@subsection Automatic symbol index cache
Unix domain sockets.
@item target remote @code{@var{host}:@var{port}}
-@itemx target remote @code{@var{[host]}:@var{port}}
+@itemx target remote @code{[@var{host}]:@var{port}}
@itemx target remote @code{tcp:@var{host}:@var{port}}
-@itemx target remote @code{tcp:@var{[host]}:@var{port}}
+@itemx target remote @code{tcp:[@var{host}]:@var{port}}
@itemx target remote @code{tcp4:@var{host}:@var{port}}
@itemx target remote @code{tcp6:@var{host}:@var{port}}
-@itemx target remote @code{tcp6:@var{[host]}:@var{port}}
+@itemx target remote @code{tcp6:[@var{host}]:@var{port}}
@itemx target extended-remote @code{@var{host}:@var{port}}
-@itemx target extended-remote @code{@var{[host]}:@var{port}}
+@itemx target extended-remote @code{[@var{host}]:@var{port}}
@itemx target extended-remote @code{tcp:@var{host}:@var{port}}
-@itemx target extended-remote @code{tcp:@var{[host]}:@var{port}}
+@itemx target extended-remote @code{tcp:[@var{host}]:@var{port}}
@itemx target extended-remote @code{tcp4:@var{host}:@var{port}}
@itemx target extended-remote @code{tcp6:@var{host}:@var{port}}
-@itemx target extended-remote @code{tcp6:@var{[host]}:@var{port}}
+@itemx target extended-remote @code{tcp6:[@var{host}]:@var{port}}
@cindex @acronym{TCP} port, @code{target remote}
Debug using a @acronym{TCP} connection to @var{port} on @var{host}.
The @var{host} may be either a host name, a numeric @acronym{IPv4}
Note that the colon is still required here.
@item target remote @code{udp:@var{host}:@var{port}}
-@itemx target remote @code{udp:@var{[host]}:@var{port}}
+@itemx target remote @code{udp:[@var{host}]:@var{port}}
@itemx target remote @code{udp4:@var{host}:@var{port}}
-@itemx target remote @code{udp6:@var{[host]}:@var{port}}
+@itemx target remote @code{udp6:[@var{host}]:@var{port}}
@itemx target extended-remote @code{udp:@var{host}:@var{port}}
@itemx target extended-remote @code{udp:@var{host}:@var{port}}
-@itemx target extended-remote @code{udp:@var{[host]}:@var{port}}
+@itemx target extended-remote @code{udp:[@var{host}]:@var{port}}
@itemx target extended-remote @code{udp4:@var{host}:@var{port}}
@itemx target extended-remote @code{udp6:@var{host}:@var{port}}
-@itemx target extended-remote @code{udp6:@var{[host]}:@var{port}}
+@itemx target extended-remote @code{udp6:[@var{host}]:@var{port}}
@cindex @acronym{UDP} port, @code{target remote}
Debug using @acronym{UDP} packets to @var{port} on @var{host}. For example, to
connect to @acronym{UDP} port 2828 on a terminal server named @code{manyfarms}:
subroutines. This facility is supported on @sc{gnu}/Linux and Solaris
systems.
-On FreeBSD systems, system control nodes are used to query process
-information.
+On FreeBSD and NetBSD systems, system control nodes are used to query
+process information.
In addition, some systems may provide additional process information
in core files. Note that a core file may include a subset of the
@item info proc cmdline
@cindex info proc cmdline
Show the original command line of the process. This command is
-supported on @sc{gnu}/Linux and FreeBSD.
+supported on @sc{gnu}/Linux, FreeBSD and NetBSD.
@item info proc cwd
@cindex info proc cwd
Show the current working directory of the process. This command is
-supported on @sc{gnu}/Linux and FreeBSD.
+supported on @sc{gnu}/Linux, FreeBSD and NetBSD.
@item info proc exe
@cindex info proc exe
Show the name of executable of the process. This command is supported
-on @sc{gnu}/Linux and FreeBSD.
+on @sc{gnu}/Linux, FreeBSD and NetBSD.
@item info proc files
@cindex info proc files
@item info proc mappings
@cindex memory address space mappings
Report the memory address space ranges accessible in a process. On
-Solaris and FreeBSD systems, each memory range includes information on
-whether the process has read, write, or execute access rights to each
-range. On @sc{gnu}/Linux and FreeBSD systems, each memory range
+Solaris, FreeBSD and NetBSD systems, each memory range includes information
+on whether the process has read, write, or execute access rights to each
+range. On @sc{gnu}/Linux, FreeBSD and NetBSD systems, each memory range
includes the object file which is mapped to that range.
@item info proc stat
group ID; virtual memory usage; the signals that are pending, blocked,
and ignored; its TTY; its consumption of system and user time; its
stack size; its @samp{nice} value; etc. These commands are supported
-on @sc{gnu}/Linux and FreeBSD.
+on @sc{gnu}/Linux, FreeBSD and NetBSD.
For @sc{gnu}/Linux systems, see the @samp{proc} man page for more
information (type @kbd{man 5 proc} from your shell prompt).
-For FreeBSD systems, @code{info proc stat} is an alias for @code{info
-proc status}.
+For FreeBSD and NetBSD systems, @code{info proc stat} is an alias for
+@code{info proc status}.
@item info proc all
Show all the information about the process described under all of the
@menu
* ARC:: Synopsys ARC
* ARM:: ARM
+* BPF:: eBPF
* M68K:: Motorola M68K
* MicroBlaze:: Xilinx MicroBlaze
* MIPS Embedded:: MIPS Embedded
@end table
@end table
+@node BPF
+@subsection BPF
+
+@table @code
+@item target sim @r{[}@var{simargs}@r{]} @dots{}
+The @value{GDBN} BPF simulator accepts the following optional arguments.
+
+@table @code
+@item --skb-data-offset=@var{offset}
+Tell the simulator the offset, measured in bytes, of the
+@code{skb_data} field in the kernel @code{struct sk_buff} structure.
+This offset is used by some BPF specific-purpose load/store
+instructions. Defaults to 0.
+@end table
+@end table
+
@node M68K
@subsection M68k
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
@cindex history file
@kindex set history filename
@cindex @env{GDBHISTFILE}, environment variable
-@item set history filename @var{fname}
+@item set history filename @r{[}@var{fname}@r{]}
Set the name of the @value{GDBN} command history file to @var{fname}.
This is the file where @value{GDBN} reads an initial command history
list, and where it writes the command history from this session when it
@file{./.gdb_history} (@file{./_gdb_history} on MS-DOS) if this variable
is not set.
+The @code{GDBHISTFILE} environment variable is read after processing
+any @value{GDBN} initialization files (@pxref{Startup}) and after
+processing any commands passed using command line options (for
+example, @code{-ex}).
+
+If the @var{fname} argument is not given, or if the @code{GDBHISTFILE}
+is the empty string then @value{GDBN} will neither try to load an
+existing history file, nor will it try to save the history on exit.
+
@cindex save command history
@kindex set history save
@item set history save
@itemx set history save on
Record command history in a file, whose name may be specified with the
-@code{set history filename} command. By default, this option is disabled.
+@code{set history filename} command. By default, this option is
+disabled. The command history will be recorded when @value{GDBN}
+exits. If @code{set history filename} is set to the empty string then
+history saving is disabled, even when @code{set history save} is
+@code{on}.
@item set history save off
-Stop recording command history in a file.
+Don't record the command history into the file specified by @code{set
+history filename} when @value{GDBN} exits.
@cindex history size
@kindex set history size
either a negative number or the empty string, then the number of commands
@value{GDBN} keeps in the history list is unlimited.
+The @code{GDBHISTSIZE} environment variable is read after processing
+any @value{GDBN} initialization files (@pxref{Startup}) and after
+processing any commands passed using command line options (for
+example, @code{-ex}).
+
@cindex remove duplicate history
@kindex set history remove-duplicates
@item set history remove-duplicates @var{count}
@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
@smallexample
$ ./gdb -q ./gdb
-Reading symbols from /home/user/gdb/gdb...done.
+Reading symbols from /home/user/gdb/gdb...
warning: File "/home/user/gdb/gdb-gdb.gdb" auto-loading has been
declined by your `auto-load safe-path' set
to "$debugdir:$datadir/auto-load".
@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}
If this file does not exist, then @value{GDBN} will look for
@var{script-name} file in all of the directories as specified below.
+(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.)
Note that loading of these files requires an accordingly configured
@code{auto-load safe-path} (@pxref{Auto-loading safe path}).
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}
-
-@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.
-
-The @samp{-a} option specifies that the new alias is an abbreviation
-of the command. Abbreviations are not shown in command
-lists displayed by the @samp{help} command.
-
-The @samp{--} option specifies the end of options,
-and is useful when @var{ALIAS} begins with a dash.
-
-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
@value{GDBN} (e.g. @code{--interpreter=mi2}) to make sure they get an
interpreter with the MI version they expect.
-The following table gives a summary of the the released versions of the MI
+The following table gives a summary of the released versions of the MI
interface: the version number, the version of GDB in which it first appeared
and the breaking changes compared to the previous version.
@item *running,thread-id="@var{thread}"
The target is now running. The @var{thread} field can be the global
-thread ID of the the thread that is now running, and it can be
+thread ID of the thread that is now running, and it can be
@samp{all} if all threads are running. The frontend should assume
that no interaction with a running thread is possible after this
notification is produced. The frontend should not assume that this
@subsubheading Synopsis
@smallexample
- -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ]
+ -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ] [ --qualified ]
[ -c @var{condition} ] [ -i @var{ignore-count} ]
[ -p @var{thread-id} ] [ @var{location} ]
@end smallexample
@item -p @var{thread-id}
Restrict the breakpoint to the thread with the specified global
@var{thread-id}.
+@item --qualified
+This option makes @value{GDBN} interpret a function name specified as
+a complete fully-qualified name.
@end table
@subsubheading Result
@subsubheading Synopsis
@smallexample
- -dprintf-insert [ -t ] [ -f ] [ -d ]
+ -dprintf-insert [ -t ] [ -f ] [ -d ] [ --qualified ]
[ -c @var{condition} ] [ -i @var{ignore-count} ]
[ -p @var{thread-id} ] [ @var{location} ] [ @var{format} ]
[ @var{argument} ]
@end smallexample
@noindent
-If supplied, @var{location} may be specified the same way as for
-the @code{-break-insert} command. @xref{-break-insert}.
+If supplied, @var{location} and @code{--qualified} may be specified
+the same way as for the @code{-break-insert} command.
+@xref{-break-insert}.
The possible optional parameters of this command are:
@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
+file. By default print the target description for the current target,
+but if the optional argument @var{file} is provided, then that file is
+read in by GDB and then used to produce the description. The
+@var{file} should be an XML document, of the form described in
+@ref{Target Description Format}.
+
@kindex maint check xml-descriptions
@item maint check xml-descriptions @var{dir}
Check that the target descriptions dynamically created by @value{GDBN}
@code{libthread_db} uses. Note that parts of the test may be skipped
on some platforms when debugging core files.
+@kindex maint print core-file-backed-mappings
+@cindex memory address space mappings
+@item maint print core-file-backed-mappings
+Print the file-backed mappings which were loaded from a core file note.
+This output represents state internal to @value{GDBN} and should be
+similar to the mappings displayed by the @code{info proc mappings}
+command.
+
@kindex maint print dummy-frames
@item maint print dummy-frames
Prints the contents of @value{GDBN}'s internal dummy-frame stack.
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
protocol. A newer @value{GDBN} can tell if a packet is supported based
on that response.
-At a minimum, a stub is required to support the @samp{g} and @samp{G}
+At a minimum, a stub is required to support the @samp{?} command to
+tell @value{GDBN} the reason for halting, @samp{g} and @samp{G}
commands for register access, and the @samp{m} and @samp{M} commands
for memory access. Stubs that only control single-threaded targets
-can implement run control with the @samp{c} (continue), and @samp{s}
-(step) commands. Stubs that support multi-threading targets should
-support the @samp{vCont} command. All other commands are optional.
+can implement run control with the @samp{c} (continue) command, and if
+the target architecture supports hardware-assisted single-stepping,
+the @samp{s} (step) command. Stubs that support multi-threading
+targets should support the @samp{vCont} command. All other commands
+are optional.
@node Packets
@section Packets
@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.
@subsection ARC Features
@cindex target descriptions, ARC Features
-ARC processors are highly configurable, so even core registers and their number
-are not completely predetermined. In addition flags and PC registers which are
-important to @value{GDBN} are not ``core'' registers in ARC. It is required
-that one of the core registers features is present.
-@samp{org.gnu.gdb.arc.aux-minimal} feature is mandatory.
-
-The @samp{org.gnu.gdb.arc.core.v2} feature is required for ARC EM and ARC HS
-targets with a normal register file. It should contain registers @samp{r0}
-through @samp{r25}, @samp{gp}, @samp{fp}, @samp{sp}, @samp{r30}, @samp{blink},
-@samp{lp_count} and @samp{pcl}. This feature may contain register @samp{ilink}
-and any of extension core registers @samp{r32} through @samp{r59/acch}.
-@samp{ilink} and extension core registers are not available to read/write, when
-debugging GNU/Linux applications, thus @samp{ilink} is made optional.
-
-The @samp{org.gnu.gdb.arc.core-reduced.v2} feature is required for ARC EM and
-ARC HS targets with a reduced register file. It should contain registers
-@samp{r0} through @samp{r3}, @samp{r10} through @samp{r15}, @samp{gp},
-@samp{fp}, @samp{sp}, @samp{r30}, @samp{blink}, @samp{lp_count} and @samp{pcl}.
-This feature may contain register @samp{ilink} and any of extension core
-registers @samp{r32} through @samp{r59/acch}.
-
-The @samp{org.gnu.gdb.arc.core.arcompact} feature is required for ARCompact
-targets with a normal register file. It should contain registers @samp{r0}
-through @samp{r25}, @samp{gp}, @samp{fp}, @samp{sp}, @samp{r30}, @samp{blink},
-@samp{lp_count} and @samp{pcl}. This feature may contain registers
-@samp{ilink1}, @samp{ilink2} and any of extension core registers @samp{r32}
-through @samp{r59/acch}. @samp{ilink1} and @samp{ilink2} and extension core
-registers are not available when debugging GNU/Linux applications. The only
-difference with @samp{org.gnu.gdb.arc.core.v2} feature is in the names of
-@samp{ilink1} and @samp{ilink2} registers and that @samp{r30} is mandatory in
-ARC v2, but @samp{ilink2} is optional on ARCompact.
-
-The @samp{org.gnu.gdb.arc.aux-minimal} feature is required for all ARC
-targets. It should contain registers @samp{pc} and @samp{status32}.
+ARC processors are so configurable that even core registers and their numbers
+are not predetermined completely. Moreover, @emph{flags} and @emph{PC}
+registers, which are important to @value{GDBN}, are not ``core'' registers in
+ARC. Therefore, there are two features that their presence is mandatory:
+@samp{org.gnu.gdb.arc.core} and @samp{org.gnu.gdb.arc.aux}.
+
+The @samp{org.gnu.gdb.arc.core} feature is required for all targets. It must
+contain registers:
+
+@itemize @minus
+@item
+@samp{r0} through @samp{r25} for normal register file targets.
+@item
+@samp{r0} through @samp{r3}, and @samp{r10} through @samp{r15} for reduced
+register file targets.
+@item
+@samp{gp}, @samp{fp}, @samp{sp}, @samp{r30}@footnote{Not necessary for ARCv1.},
+@samp{blink}, @samp{lp_count}, @samp{pcl}.
+@end itemize
+
+In case of an ARCompact target (ARCv1 ISA), the @samp{org.gnu.gdb.arc.core}
+feature may contain registers @samp{ilink1} and @samp{ilink2}. While in case
+of ARC EM and ARC HS targets (ARCv2 ISA), register @samp{ilink} may be present.
+The difference between ARCv1 and ARCv2 is the naming of registers @emph{29th}
+and @emph{30th}. They are called @samp{ilink1} and @samp{ilink2} for ARCv1 and
+are optional. For ARCv2, they are called @samp{ilink} and @samp{r30} and only
+@samp{ilink} is optional. The optionality of @samp{ilink*} registers is
+because of their inaccessibility during user space debugging sessions.
+
+Extension core registers @samp{r32} through @samp{r59} are optional and their
+existence depends on the configuration. When debugging GNU/Linux applications,
+i.e.@: user space debugging, these core registers are not available.
+
+The @samp{org.gnu.gdb.arc.aux} feature is required for all ARC targets. Here
+is the list of registers pertinent to this feature:
+
+@itemize @minus
+@item
+mandatory: @samp{pc} and @samp{status32}.
+@item
+optional: @samp{lp_start}, @samp{lp_end}, and @samp{bta}.
+@end itemize
@node ARM Features
@subsection ARM Features
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