@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. 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 -- Describe where symbol SYM is stored.
+...
+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.
@kindex apropos
@item apropos [-v] @var{regexp}
@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
@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.
@cindex show exec-file-mismatch
@item show exec-file-mismatch
@smallexample
(@value{GDBP}) info threads
- Id Target Id Frame
+ Id Target Id Frame
* 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8)
2 process 35 thread 23 0x34e5 in sigpause ()
3 process 35 thread 27 0x34e5 in sigpause ()
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
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
@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}
@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".
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.
+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.
Create a new TUI layout. The new layout will be named @var{name}, and
can be accessed using the @code{layout} command (see below).
-Each @var{window} parameter is the name of a window to display. The
-windows will be displayed from top to bottom in the order listed. The
-names of the windows are the same as the ones given to the
+Each @var{window} parameter is either the name of a window to display,
+or a window description. The windows will be displayed from top to
+bottom in the order listed.
+
+The names of the windows are the same as the ones given to the
@code{focus} command (see below); additional, the @code{status}
-window can be specified.
+window can be specified. Note that, because it is of fixed height,
+the weight assigned to the status window is of no importance. It is
+conventional to use @samp{0} here.
+
+A window description looks a bit like an invocation of @code{tui
+new-layout}, and is of the form
+@{@r{[}@code{-horizontal}@r{]}@var{window} @var{weight} @r{[}@var{window} @var{weight}@dots{}@r{]}@}.
+
+This specifies a sub-layout. If @code{-horizontal} is given, the
+windows in this description will be arranged side-by-side, rather than
+top-to-bottom.
Each @var{weight} is an integer. It is the weight of this window
relative to all the other windows in the layout. These numbers are
the command window. The non-status windows all have the same weight,
so the terminal will be split into three roughly equal sections.
+Here is a more complex example, showing a horizontal layout:
+
+@example
+(gdb) tui new-layout example @{-horizontal src 1 asm 1@} 2 status 0 cmd 1
+@end example
+
+This will result in side-by-side source and assembly windows; with the
+status and command window being beneath these, filling the entire
+width of the terminal. Because they have weight 2, the source and
+assembly windows will be twice the height of the command window.
+
@item layout @var{name}
@kindex layout
Changes which TUI windows are displayed. The @var{name} parameter
@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
Use the curses library instead of the termcap library, for text-mode
terminal operations.
+@item --with-debuginfod
+Build @value{GDBN} with libdebuginfod, the debuginfod client library.
+Used to automatically fetch source files and separate debug files from
+debuginfod servers using the associated executable's build ID. Enabled
+by default if libdebuginfod is installed and found at configure time.
+debuginfod is packaged with elfutils, starting with version 0.178. You
+can get the latest version from `https://sourceware.org/elfutils/'.
+
@item --with-libunwind-ia64
Use the libunwind library for unwinding function call stack on ia64
target platforms. See http://www.nongnu.org/libunwind/index.html for
projects / deliverable / binutils-gdb.git / blobdiff