\input texinfo @c -*-texinfo-*-
-@c Copyright (C) 1988-2019 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-2019 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-2019 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{~/.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 executes all the commands in
-that file.
+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
-To display the list of init files loaded by gdb at startup, you
-can use @kbd{gdb --help}.
+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.
-@cindex init file name
+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}.
+
+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.
command processes arbitrary expressions in any of the languages
supported by @value{GDBN}. With such commands, because raw input may
start with a leading dash that would be confused with an option or any
-of its abbreviations, e.g.@: @code{print -r} (short for @code{print
--raw} or printing negative @code{r}?), if you specify any command
+of its abbreviations, e.g.@: @code{print -p} (short for @code{print
+-pretty} or printing negative @code{p}?), if you specify any command
option, then you must use a double-dash (@code{--}) delimiter to
indicate the end of options.
@smallexample
(@value{GDBP}) print -@key{TAB}@key{TAB}
--address -max-depth -repeats -vtbl
--array -null-stop -static-members
--array-indexes -object -symbol
--elements -pretty -union
+-address -max-depth -raw-values -union
+-array -null-stop -repeats -vtbl
+-array-indexes -object -static-members
+-elements -pretty -symbol
@end smallexample
Completion will in some cases guide you with a suggestion of what kind
(@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
* Input/Output:: Your program's input and output
* Attach:: Debugging an already-running process
* Kill Process:: Killing the child process
-
-* Inferiors and Programs:: Debugging multiple inferiors and programs
+* Inferiors Connections and Programs:: Debugging multiple inferiors
+ connections and programs
* Threads:: Debugging programs with multiple threads
* Forks:: Debugging forks
* Checkpoint/Restart:: Setting a @emph{bookmark} to return to later
@itemx set auto-connect-native-target off
@itemx show auto-connect-native-target
-By default, if not connected to any target yet (e.g., with
-@code{target remote}), the @code{run} command starts your program as a
-native process under @value{GDBN}, on your local machine. If you're
-sure you don't want to debug programs on your local machine, you can
-tell @value{GDBN} to not connect to the native target automatically
-with the @code{set auto-connect-native-target off} command.
+By default, if the current inferior is not connected to any target yet
+(e.g., with @code{target remote}), the @code{run} command starts your
+program as a native process under @value{GDBN}, on your local machine.
+If you're sure you don't want to debug programs on your local machine,
+you can tell @value{GDBN} to not connect to the native target
+automatically with the @code{set auto-connect-native-target off}
+command.
-If @code{on}, which is the default, and if @value{GDBN} is not
+If @code{on}, which is the default, and if the current inferior is not
connected to a target already, the @code{run} command automaticaly
connects to the native target, if one is available.
-If @code{off}, and if @value{GDBN} is not connected to a target
-already, the @code{run} command fails with an error:
+If @code{off}, and if the current inferior is not connected to a
+target already, the @code{run} command fails with an error:
@smallexample
(@value{GDBP}) run
Don't know how to run. Try "help target".
@end smallexample
-If @value{GDBN} is already connected to a target, @value{GDBN} always
-uses it with the @code{run} command.
+If the current inferior is already connected to a target, @value{GDBN}
+always uses it with the @code{run} command.
In any case, you can explicitly connect to the native target with the
@code{target native} command. For example,
the @code{file} command to load the program. @xref{Files, ,Commands to
Specify Files}.
+@anchor{set exec-file-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 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
+Show the current value of @code{exec-file-mismatch}.
+
+@end table
+
The first thing @value{GDBN} does after arranging to debug the specified
process is to stop it. You can examine and modify an attached process
with all the @value{GDBN} commands that are ordinarily available when
reads the symbol table again (while trying to preserve your current
breakpoint settings).
-@node Inferiors and Programs
-@section Debugging Multiple Inferiors and Programs
+@node Inferiors Connections and Programs
+@section Debugging Multiple Inferiors Connections and Programs
@value{GDBN} lets you run and debug multiple programs in a single
session. In addition, @value{GDBN} on some systems may let you run
several programs simultaneously (otherwise you have to exit from one
-before starting another). In the most general case, you can have
-multiple threads of execution in each of multiple processes, launched
-from multiple executables.
+before starting another). On some systems @value{GDBN} may even let
+you debug several programs simultaneously on different remote systems.
+In the most general case, you can have multiple threads of execution
+in each of multiple processes, launched from multiple executables,
+running on different machines.
@cindex inferior
@value{GDBN} represents the state of each program execution with an
@item
the target system's inferior identifier
+@item
+the target connection the inferior is bound to, including the unique
+connection number assigned by @value{GDBN}, and the protocol used by
+the connection.
+
@item
the name of the executable the inferior is running.
@smallexample
(@value{GDBP}) info inferiors
- Num Description Executable
- 2 process 2307 hello
-* 1 process 3401 goodbye
+ Num Description Connection Executable
+* 1 process 3401 1 (native) goodbye
+ 2 process 2307 2 (extended-remote host:10000) hello
+@end smallexample
+
+To find out what open target connections exist at any moment, use
+@w{@code{info connections}}:
+
+@table @code
+@kindex info connections [ @var{id}@dots{} ]
+@item info connections
+Print a list of all open target connections currently being managed by
+@value{GDBN}. By default all connections are printed, but the
+argument @var{id}@dots{} -- a space separated list of connections
+numbers -- can be used to limit the display to just the requested
+connections.
+
+@value{GDBN} displays for each connection (in this order):
+
+@enumerate
+@item
+the connection number assigned by @value{GDBN}.
+
+@item
+the protocol used by the connection.
+
+@item
+a textual description of the protocol used by the connection.
+
+@end enumerate
+
+@noindent
+An asterisk @samp{*} preceding the connection number indicates the
+connection of the current inferior.
+
+For example,
+@end table
+@c end table here to get a little more width for example
+
+@smallexample
+(@value{GDBP}) info connections
+ Num What Description
+* 1 extended-remote host:10000 Extended remote serial target in gdb-specific protocol
+ 2 native Native process
+ 3 core Local core dump file
@end smallexample
To switch focus between inferiors, use the @code{inferior} command:
@table @code
@kindex add-inferior
-@item add-inferior [ -copies @var{n} ] [ -exec @var{executable} ]
+@item add-inferior [ -copies @var{n} ] [ -exec @var{executable} ] [-no-connection ]
Adds @var{n} inferiors to be run using @var{executable} as the
executable; @var{n} defaults to 1. If no executable is specified,
the inferiors begins empty, with no program. You can still assign or
change the program assigned to the inferior at any time by using the
@code{file} command with the executable name as its argument.
+By default, the new inferior begins connected to the same target
+connection as the current inferior. For example, if the current
+inferior was connected to @code{gdbserver} with @code{target remote},
+then the new inferior will be connected to the same @code{gdbserver}
+instance. The @samp{-no-connection} option starts the new inferior
+with no connection yet. You can then for example use the @code{target
+remote} command to connect to some other @code{gdbserver} instance,
+use @code{run} to spawn a local program, etc.
+
@kindex clone-inferior
@item clone-inferior [ -copies @var{n} ] [ @var{infno} ]
Adds @var{n} inferiors ready to execute the same program as inferior
@smallexample
(@value{GDBP}) info inferiors
- Num Description Executable
-* 1 process 29964 helloworld
+ Num Description Connection Executable
+* 1 process 29964 1 (native) helloworld
(@value{GDBP}) clone-inferior
Added inferior 2.
1 inferiors added.
(@value{GDBP}) info inferiors
- Num Description Executable
- 2 <null> helloworld
-* 1 process 29964 helloworld
+ Num Description Connection Executable
+* 1 process 29964 1 (native) helloworld
+ 2 <null> 1 (native) helloworld
@end smallexample
You can now simply switch focus to inferior 2 and run it.
value of @code{myglobal} in the current inferior.
-Occasionaly, when debugging @value{GDBN} itself, it may be useful to
+Occasionally, when debugging @value{GDBN} itself, it may be useful to
get more info about the relationship of inferiors, programs, address
spaces in a debug session. You can do that with the @w{@code{maint
info program-spaces}} command.
@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 ()
@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
will retain control of all forked processes (including nested forks).
You can list the forked processes under the control of @value{GDBN} by
using the @w{@code{info inferiors}} command, and switch from one fork
-to another by using the @code{inferior} command (@pxref{Inferiors and
-Programs, ,Debugging Multiple Inferiors and Programs}).
+to another by using the @code{inferior} command (@pxref{Inferiors Connections and
+Programs, ,Debugging Multiple Inferiors Connections and Programs}).
To quit debugging one of the forked processes, you can either detach
from it by using the @w{@code{detach inferiors}} command (allowing it
to run independently), or kill it using the @w{@code{kill inferiors}}
-command. @xref{Inferiors and Programs, ,Debugging Multiple Inferiors
-and Programs}.
+command. @xref{Inferiors Connections and Programs, ,Debugging
+Multiple Inferiors Connections and Programs}.
If you ask to debug a child process and a @code{vfork} is followed by an
@code{exec}, @value{GDBN} executes the new target up to the first
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
the command to use to catch such exceptions is @kbd{catch exception
Pck.Constraint_Error}.
+@vindex $_ada_exception@r{, convenience variable}
+The convenience variable @code{$_ada_exception} holds the address of
+the exception being thrown. This can be useful when setting a
+condition for such a catchpoint.
+
@item exception unhandled
@kindex catch exception unhandled
-An exception that was raised but is not handled by the program.
+An exception that was raised but is not handled by the program. The
+convenience variable @code{$_ada_exception} is set as for @code{catch
+exception}.
@item handlers @r{[}@var{name}@r{]}
@kindex catch handlers
command to use to catch such exceptions handling is
@kbd{catch handlers Pck.Constraint_Error}.
+The convenience variable @code{$_ada_exception} is set as for
+@code{catch exception}.
+
@item assert
@kindex catch assert
-A failed Ada assertion.
+A failed Ada assertion. Note that the convenience variable
+@code{$_ada_exception} is @emph{not} set by this catchpoint.
@item exec
@kindex catch exec
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.
results back to @value{GDBN}. Whatever the target reports back to
@value{GDBN}, @value{GDBN} will report back to the user. @value{GDBN}
assumes that the memory and registers that the target reports are in a
-consistant state, but @value{GDBN} accepts whatever it is given.
+consistent state, but @value{GDBN} accepts whatever it is given.
}.
On some platforms, @value{GDBN} has built-in support for reverse
disable the workarounds.
The argument @var{identifier} identifies the @sc{cpu} and is of the
-form: @code{@var{vendor}:@var{procesor identifier}}. In addition,
+form: @code{@var{vendor}:@var{processor identifier}}. In addition,
there are two special identifiers, @code{none} and @code{auto}
(default).
@item -raw-frame-arguments [@code{on}|@code{off}]
Set whether to print frame arguments in raw form.
Related setting: @ref{set print raw-frame-arguments}.
+
+@item -frame-info @code{auto}|@code{source-line}|@code{location}|@code{source-and-location}|@code{location-and-address}|@code{short-location}
+Set printing of frame information.
+Related setting: @ref{set print frame-info}.
@end table
The optional @var{qualifier} is maintained for backward compatibility.
only if it is a scalar (integer, pointer, enumeration, etc). See command
@kbd{set print frame-arguments} in @ref{Print Settings} for more details
on how to configure the way function parameter values are printed.
+The command @kbd{set print frame-info} (@pxref{Print Settings}) controls
+what frame information is printed.
@cindex optimized out, in backtrace
@cindex function call arguments, optimized out
@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}.
objfile /build/test frame-filters:
Priority Enabled Name
- 999 Yes BuildProgra Filter
+ 999 Yes BuildProgramFilter
(gdb) disable frame-filter /build/test BuildProgramFilter
(gdb) info frame-filter
in the list, until it finds a file with the desired name.
For example, suppose an executable references the file
-@file{/usr/src/foo-1.0/lib/foo.c}, and our source path is
-@file{/mnt/cross}. The file is first looked up literally; if this
-fails, @file{/mnt/cross/usr/src/foo-1.0/lib/foo.c} is tried; if this
-fails, @file{/mnt/cross/foo.c} is opened; if this fails, an error
-message is printed. @value{GDBN} does not look up the parts of the
+@file{/usr/src/foo-1.0/lib/foo.c}, does not record a compilation
+directory, and the @dfn{source path} is @file{/mnt/cross}.
+@value{GDBN} would look for the source file in the following
+locations:
+
+@enumerate
+
+@item @file{/usr/src/foo-1.0/lib/foo.c}
+@item @file{/mnt/cross/usr/src/foo-1.0/lib/foo.c}
+@item @file{/mnt/cross/foo.c}
+
+@end enumerate
+
+If the source file is not present at any of the above locations then
+an error is printed. @value{GDBN} does not look up the parts of the
source file name, such as @file{/mnt/cross/src/foo-1.0/lib/foo.c}.
Likewise, the subdirectories of the source path are not searched: if
the source path is @file{/mnt/cross}, and the binary refers to
@file{/mnt/cross/usr/src/foo-1.0/lib}.
Plain file names, relative file names with leading directories, file
-names containing dots, etc.@: are all treated as described above; for
-instance, if the source path is @file{/mnt/cross}, and the source file
-is recorded as @file{../lib/foo.c}, @value{GDBN} would first try
-@file{../lib/foo.c}, then @file{/mnt/cross/../lib/foo.c}, and after
-that---@file{/mnt/cross/foo.c}.
+names containing dots, etc.@: are all treated as described above,
+except that non-absolute file names are not looked up literally. If
+the @dfn{source path} is @file{/mnt/cross}, the source file is
+recorded as @file{../lib/foo.c}, and no compilation directory is
+recorded, then @value{GDBN} will search in the following locations:
+
+@enumerate
+
+@item @file{/mnt/cross/../lib/foo.c}
+@item @file{/mnt/cross/foo.c}
+
+@end enumerate
+
+@kindex cdir
+@kindex cwd
+@vindex $cdir@r{, convenience variable}
+@vindex $cwd@r{, convenience variable}
+@cindex compilation directory
+@cindex current directory
+@cindex working directory
+@cindex directory, current
+@cindex directory, compilation
+The @dfn{source path} will always include two special entries
+@samp{$cdir} and @samp{$cwd}, these refer to the compilation directory
+(if one is recorded) and the current working directory respectively.
+
+@samp{$cdir} causes @value{GDBN} to search within the compilation
+directory, if one is recorded in the debug information. If no
+compilation directory is recorded in the debug information then
+@samp{$cdir} is ignored.
+
+@samp{$cwd} is not the same as @samp{.}---the former tracks the
+current working directory as it changes during your @value{GDBN}
+session, while the latter is immediately expanded to the current
+directory at the time you add an entry to the source path.
+
+If a compilation directory is recorded in the debug information, and
+@value{GDBN} has not found the source file after the first search
+using @dfn{source path}, then @value{GDBN} will combine the
+compilation directory and the filename, and then search for the source
+file again using the @dfn{source path}.
+
+For example, if the executable records the source file as
+@file{/usr/src/foo-1.0/lib/foo.c}, the compilation directory is
+recorded as @file{/project/build}, and the @dfn{source path} is
+@file{/mnt/cross:$cdir:$cwd} while the current working directory of
+the @value{GDBN} session is @file{/home/user}, then @value{GDBN} will
+search for the source file in the following locations:
+
+@enumerate
+
+@item @file{/usr/src/foo-1.0/lib/foo.c}
+@item @file{/mnt/cross/usr/src/foo-1.0/lib/foo.c}
+@item @file{/project/build/usr/src/foo-1.0/lib/foo.c}
+@item @file{/home/user/usr/src/foo-1.0/lib/foo.c}
+@item @file{/mnt/cross/project/build/usr/src/foo-1.0/lib/foo.c}
+@item @file{/project/build/project/build/usr/src/foo-1.0/lib/foo.c}
+@item @file{/home/user/project/build/usr/src/foo-1.0/lib/foo.c}
+@item @file{/mnt/cross/foo.c}
+@item @file{/project/build/foo.c}
+@item @file{/home/user/foo.c}
+
+@end enumerate
+
+If the file name in the previous example had been recorded in the
+executable as a relative path rather than an absolute path, then the
+first look up would not have occurred, but all of the remaining steps
+would be similar.
+
+When searching for source files on MS-DOS and MS-Windows, where
+absolute paths start with a drive letter (e.g.
+@file{C:/project/foo.c}), @value{GDBN} will remove the drive letter
+from the file name before appending it to a search directory from
+@dfn{source path}; for instance if the executable references the
+source file @file{C:/project/foo.c} and @dfn{source path} is set to
+@file{D:/mnt/cross}, then @value{GDBN} will search in the following
+locations for the source file:
+
+@enumerate
+
+@item @file{C:/project/foo.c}
+@item @file{D:/mnt/cross/project/foo.c}
+@item @file{D:/mnt/cross/foo.c}
+
+@end enumerate
Note that the executable search path is @emph{not} used to locate the
source files.
@kindex directory
@kindex dir
-When you start @value{GDBN}, its source path includes only @samp{cdir}
-and @samp{cwd}, in that order.
+When you start @value{GDBN}, its source path includes only @samp{$cdir}
+and @samp{$cwd}, in that order.
To add other directories, use the @code{directory} command.
The search path is used to find both program source files and @value{GDBN}
whitespace. You may specify a directory that is already in the source
path; this moves it forward, so @value{GDBN} searches it sooner.
-@kindex cdir
-@kindex cwd
-@vindex $cdir@r{, convenience variable}
-@vindex $cwd@r{, convenience variable}
-@cindex compilation directory
-@cindex current directory
-@cindex working directory
-@cindex directory, current
-@cindex directory, compilation
-You can use the string @samp{$cdir} to refer to the compilation
-directory (if one is recorded), and @samp{$cwd} to refer to the current
-working directory. @samp{$cwd} is not the same as @samp{.}---the former
-tracks the current working directory as it changes during your @value{GDBN}
-session, while the latter is immediately expanded to the current
-directory at the time you add an entry to the source path.
+The special strings @samp{$cdir} (to refer to the compilation
+directory, if one is recorded), and @samp{$cwd} (to refer to the
+current working directory) can also be included in the list of
+directories @var{dirname}. Though these will already be in the source
+path they will be moved forward in the list so @value{GDBN} searches
+them sooner.
@item directory
Reset the source path to its default value (@samp{$cdir:$cwd} on Unix systems). This requires confirmation.
Set pretty formatting of structures. Related setting: @ref{set print
pretty}.
+@item -raw-values [@code{on}|@code{off}]
+Set whether to print values in raw form, bypassing any
+pretty-printers for that value. Related setting: @ref{set print
+raw-values}.
+
@item -repeats @var{number-of-repeats}|@code{unlimited}
Set threshold for repeated print elements. @code{unlimited} causes
all elements to be individually printed. Related setting: @ref{set
command option, then you must use a double dash (@code{--}) to mark
the end of option processing.
-For example, this prints the value of the @code{-r} expression:
+For example, this prints the value of the @code{-p} expression:
@smallexample
-(@value{GDBP}) print -r
+(@value{GDBP}) print -p
@end smallexample
While this repeats the last value in the value history (see below)
-with the @code{-raw} option in effect:
+with the @code{-pretty} option in effect:
@smallexample
-(@value{GDBP}) print -r --
+(@value{GDBP}) print -p --
@end smallexample
Here is an example including both on option and an expression:
@cindex printing frame argument values
@cindex print all frame argument values
@cindex print frame argument values for scalars only
-@cindex do not print frame argument values
+@cindex do not print frame arguments
This command allows to control how the values of arguments are printed
when the debugger prints a frame (@pxref{Frames}). The possible
values are:
#1 0x08048361 in call_me (i=@dots{}, s=@dots{}, ss=@dots{}, u=@dots{}, e=@dots{})
at frame-args.c:23
@end smallexample
+
+@item presence
+Only the presence of arguments is indicated by @code{@dots{}}.
+The @code{@dots{}} are not printed for function without any arguments.
+None of the argument names and values are printed.
+In this case, the example above now becomes:
+
+@smallexample
+#1 0x08048361 in call_me (@dots{}) at frame-args.c:23
+@end smallexample
+
@end table
By default, only scalar arguments are printed. This command can be used
Also, it improves performance when displaying Ada frames, because
the computation of large arguments can sometimes be CPU-intensive,
especially in large applications. Setting @code{print frame-arguments}
-to @code{scalars} (the default) or @code{none} avoids this computation,
-thus speeding up the display of each Ada frame.
+to @code{scalars} (the default), @code{none} or @code{presence} avoids
+this computation, thus speeding up the display of each Ada frame.
@item show print frame-arguments
Show how the value of arguments should be displayed when printing a frame.
Show the method being used for printing of frame argument values at function
entry.
+@anchor{set print frame-info}
+@item set print frame-info @var{value}
+@kindex set print frame-info
+@cindex printing frame information
+@cindex frame information, printing
+This command allows to control the information printed when
+the debugger prints a frame. See @ref{Frames}, @ref{Backtrace},
+for a general explanation about frames and frame information.
+Note that some other settings (such as @code{set print frame-arguments}
+and @code{set print address}) are also influencing if and how some frame
+information is displayed. In particular, the frame program counter is never
+printed if @code{set print address} is off.
+
+The possible values for @code{set print frame-info} are:
+@table @code
+@item short-location
+Print the frame level, the program counter (if not at the
+beginning of the location source line), the function, the function
+arguments.
+@item location
+Same as @code{short-location} but also print the source file and source line
+number.
+@item location-and-address
+Same as @code{location} but print the program counter even if located at the
+beginning of the location source line.
+@item source-line
+Print the program counter (if not at the beginning of the location
+source line), the line number and the source line.
+@item source-and-location
+Print what @code{location} and @code{source-line} are printing.
+@item auto
+The information printed for a frame is decided automatically
+by the @value{GDBN} command that prints a frame.
+For example, @code{frame} prints the information printed by
+@code{source-and-location} while @code{stepi} will switch between
+@code{source-line} and @code{source-and-location} depending on the program
+counter.
+The default value is @code{auto}.
+@end table
+
@anchor{set print repeats}
@item set print repeats @var{number-of-repeats}
@itemx set print repeats unlimited
@item show print pretty
Show which format @value{GDBN} is using to print structures.
+@anchor{set print raw-values}
+@item set print raw-values on
+Print values in raw form, without applying the pretty
+printers for the value.
+
+@item set print raw-values off
+Print values in pretty-printed form, if there is a pretty-printer
+for the value (@pxref{Pretty Printing}),
+otherwise print the value in raw form.
+
+The default setting is ``off''.
+
+@item show print raw-values
+Show whether to print values in raw form.
+
@item set print sevenbit-strings on
@cindex eight-bit characters in strings
@cindex octal escapes in strings
Note that for @code{bar} the entire printer can be disabled,
as can each individual subprinter.
+Printing values and frame arguments is done by default using
+the enabled pretty printers.
+
+The print option @code{-raw-values} and @value{GDBN} setting
+@code{set print raw-values} (@pxref{set print raw-values}) can be
+used to print values without applying the enabled pretty printers.
+
+Similarly, the backtrace option @code{-raw-frame-arguments} and
+@value{GDBN} setting @code{set print raw-frame-arguments}
+(@pxref{set print raw-frame-arguments}) can be used to ignore the
+enabled pretty printers when printing frame argument values.
+
@node Value History
@section Value History
The variable @code{$_exception} is set to the exception object being
thrown at an exception-related catchpoint. @xref{Set Catchpoints}.
+@item $_ada_exception
+The variable @code{$_ada_exception} is set to the address of the
+exception being caught or thrown at an Ada exception-related
+catchpoint. @xref{Set Catchpoints}.
+
@item $_probe_argc
@itemx $_probe_arg0@dots{}$_probe_arg11
Arguments to a static probe. @xref{Static Probe Points}.
This variable contains the address of the thread information block.
@item $_inferior
-The number of the current inferior. @xref{Inferiors and
-Programs, ,Debugging Multiple Inferiors and Programs}.
+The number of the current inferior. @xref{Inferiors Connections and
+Programs, ,Debugging Multiple Inferiors Connections and Programs}.
@item $_thread
The thread number of the current thread. @xref{thread numbers}.
$4 = 1
@end smallexample
+@item $_gdb_setting_str (@var{setting})
+@findex $_gdb_setting_str@r{, convenience function}
+Return the value of the @value{GDBN} @var{setting} as a string.
+@var{setting} is any setting that can be used in a @code{set} or
+@code{show} command (@pxref{Controlling GDB}).
+
+@smallexample
+(@value{GDBP}) show print frame-arguments
+Printing of non-scalar frame arguments is "scalars".
+(@value{GDBP}) p $_gdb_setting_str("print frame-arguments")
+$1 = "scalars"
+(@value{GDBP}) p $_gdb_setting_str("height")
+$2 = "30"
+(@value{GDBP})
+@end smallexample
+
+@item $_gdb_setting (@var{setting})
+@findex $_gdb_setting@r{, convenience function}
+Return the value of the @value{GDBN} @var{setting}.
+The type of the returned value depends on the setting.
+
+The value type for boolean and auto boolean settings is @code{int}.
+The boolean values @code{off} and @code{on} are converted to
+the integer values @code{0} and @code{1}. The value @code{auto} is
+converted to the value @code{-1}.
+
+The value type for integer settings is either @code{unsigned int}
+or @code{int}, depending on the setting.
+
+Some integer settings accept an @code{unlimited} value.
+Depending on the setting, the @code{set} command also accepts
+the value @code{0} or the value @code{@minus{}1} as a synonym for
+@code{unlimited}.
+For example, @code{set height unlimited} is equivalent to
+@code{set height 0}.
+
+Some other settings that accept the @code{unlimited} value
+use the value @code{0} to literally mean zero.
+For example, @code{set history size 0} indicates to not
+record any @value{GDBN} commands in the command history.
+For such settings, @code{@minus{}1} is the synonym
+for @code{unlimited}.
+
+See the documentation of the corresponding @code{set} command for
+the numerical value equivalent to @code{unlimited}.
+
+The @code{$_gdb_setting} function converts the unlimited value
+to a @code{0} or a @code{@minus{}1} value according to what the
+@code{set} command uses.
+
+@smallexample
+@group
+(@value{GDBP}) p $_gdb_setting_str("height")
+$1 = "30"
+(@value{GDBP}) p $_gdb_setting("height")
+$2 = 30
+(@value{GDBP}) set height unlimited
+(@value{GDBP}) p $_gdb_setting_str("height")
+$3 = "unlimited"
+(@value{GDBP}) p $_gdb_setting("height")
+$4 = 0
+@end group
+@group
+(@value{GDBP}) p $_gdb_setting_str("history size")
+$5 = "unlimited"
+(@value{GDBP}) p $_gdb_setting("history size")
+$6 = -1
+(@value{GDBP}) p $_gdb_setting_str("disassemble-next-line")
+$7 = "auto"
+(@value{GDBP}) p $_gdb_setting("disassemble-next-line")
+$8 = -1
+(@value{GDBP})
+@end group
+@end smallexample
+
+Other setting types (enum, filename, optional filename, string, string noescape)
+are returned as string values.
+
+
+@item $_gdb_maint_setting_str (@var{setting})
+@findex $_gdb_maint_setting_str@r{, convenience function}
+Like the @code{$_gdb_setting_str} function, but works with
+@code{maintenance set} variables.
+
+@item $_gdb_maint_setting (@var{setting})
+@findex $_gdb_maint_setting@r{, convenience function}
+Like the @code{$_gdb_setting} function, but works with
+@code{maintenance set} variables.
+
@end table
-These functions require @value{GDBN} to be configured with
+The following functions require @value{GDBN} to be configured with
@code{Python} support.
@table @code
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{reggoup} can be any of those returned by
+@var{reggroup}s. The @var{reggroup} can be any of those returned by
@code{maint print reggroups} (@pxref{Maintenance Commands}).
@item info registers @var{regname} @dots{}
@value{GDBN} caches data exchanged between the debugger and a target.
Each cache is associated with the address space of the inferior.
-@xref{Inferiors and Programs}, about inferior and address space.
+@xref{Inferiors Connections and Programs}, about inferior and address space.
Such caching generally improves performance in remote debugging
(@pxref{Remote Debugging}), because it reduces the overhead of the
remote protocol by bundling memory reads and writes into large chunks.
@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
@value{GDBN} to hold the contents of the value. It is possible in
some languages with dynamic typing systems, that an invalid program
may indicate a value that is incorrectly large, this in turn may cause
-@value{GDBN} to try and allocate an overly large ammount of memory.
+@value{GDBN} to try and allocate an overly large amount of memory.
@table @code
@kindex set max-value-size
@value{CALLSEQ2B}, @value{GDBN} cannot find which one from the inferior state.
@code{initial:} state shows some random possible calling sequence @value{GDBN}
-has found. It then finds another possible calling sequcen - that one is
+has found. It then finds another possible calling sequence - that one is
prefixed by @code{compare:}. The non-ambiguous intersection of these two is
printed as the @code{reduced:} calling sequence. That one could have many
-futher @code{compare:} and @code{reduced:} statements as long as there remain
+further @code{compare:} and @code{reduced:} statements as long as there remain
any non-ambiguous sequence entries.
For the frame of function @code{b} in both cases there are different possible
@code{$pc} values (@code{0x4004cc} or @code{0x4004ce}), therefore this frame is
-also ambigous. The only non-ambiguous frame is the one for function @code{a},
+also ambiguous. The only non-ambiguous frame is the one for function @code{a},
therefore this one is displayed to the user while the ambiguous frames are
omitted.
@value{GDBN} cannot find out from the inferior state if and how many times did
function @code{a} call itself (via function @code{b}) as these calls would be
-tail calls. Such tail calls would modify thue @code{i} variable, therefore
+tail calls. Such tail calls would modify the @code{i} variable, therefore
@value{GDBN} cannot be sure the value it knows would be right - @value{GDBN}
prints @code{<optimized out>} instead.
$_sdata}. This collects arbitrary user data passed in the probe point
call to the tracing library. In the UST example above, you'll see
that the third argument to @code{trace_mark} is a printf-like format
-string. The user data is then the result of running that formating
+string. The user data is then the result of running that formatting
string against the following arguments. Note that @code{info
static-tracepoint-markers} command output lists that format string in
the @samp{Data:} field.
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
types. Also suitable for unions. As unions aren't part of regular Fortran,
this can only happen when accessing a register that uses a gdbarch-defined
union type.
+@item ::
+The scope operator. Normally used to access variables in modules or
+to set breakpoints on subroutines nested in modules or in other
+subroutines (internal subroutines).
@end table
@node Fortran Defaults
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
@kindex info task @var{taskno}
@item info task @var{taskno}
-This command shows detailled informations on the specified task, as in
+This command shows detailed informations on the specified task, as in
the following example:
@smallexample
@iftex
* 2 807c468 1 15 Runnable task_1
(@value{GDBP}) info task 2
Ada Task: 0x807c468
-Name: task_1
+Name: "task_1"
Thread: 0
LWP: 0x1fac
-Parent: 1 (main_task)
+Parent: 1 ("main_task")
Base Priority: 15
State: Runnable
@end smallexample
@item task
@kindex task@r{ (Ada)}
@cindex current Ada task ID
-This command prints the ID of the current task.
+This command prints the ID and name of the current task.
@smallexample
@iftex
(@value{GDBP}) info tasks
ID TID P-ID Pri State Name
1 8077870 0 15 Child Activation Wait main_task
-* 2 807c458 1 15 Runnable t
+* 2 807c458 1 15 Runnable some_task
(@value{GDBP}) task
-[Current task is 2]
+[Current task is 2 "some_task"]
@end smallexample
@item task @var{taskno}
(@value{GDBP}) info tasks
ID TID P-ID Pri State Name
1 8077870 0 15 Child Activation Wait main_task
-* 2 807c458 1 15 Runnable t
+* 2 807c458 1 15 Runnable some_task
(@value{GDBP}) task 1
-[Switching to task 1]
+[Switching to task 1 "main_task"]
#0 0x8067726 in pthread_cond_wait ()
(@value{GDBP}) bt
#0 0x8067726 in pthread_cond_wait ()
@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
debugging information, organized into two lists: files whose symbols
have already been read, and files whose symbols will be read when needed.
+@item info sources [-dirname | -basename] [--] [@var{regexp}]
+Like @samp{info sources}, but only print the names of the files
+matching the provided @var{regexp}.
+By default, the @var{regexp} is used to match anywhere in the filename.
+If @code{-dirname}, only files having a dirname matching @var{regexp} are shown.
+If @code{-basename}, only files having a basename matching @var{regexp}
+are shown.
+The matching is case-sensitive, except on operating systems that
+have case-insensitive filesystem (e.g., MS-Windows).
+
@kindex info functions
-@item info functions [-q]
+@item info functions [-q] [-n]
Print the names and data types of all defined functions.
Similarly to @samp{info types}, this command groups its output by source
files and annotates each function definition with its source line
language of the function, other values mean to use
the manually specified language (see @ref{Manually, ,Set Language Manually}).
+The @samp{-n} flag excludes @dfn{non-debugging symbols} from the
+results. A non-debugging symbol is a symbol that comes from the
+executable's symbol table, not from the debug information (for
+example, DWARF) associated with the executable.
+
The optional flag @samp{-q}, which stands for @samp{quiet}, disables
printing header information and messages explaining why no functions
have been printed.
-@item info functions [-q] [-t @var{type_regexp}] [@var{regexp}]
+@item info functions [-q] [-n] [-t @var{type_regexp}] [@var{regexp}]
Like @samp{info functions}, but only print the names and data types
of the functions selected with the provided regexp(s).
@kindex info variables
-@item info variables [-q]
+@item info variables [-q] [-n]
Print the names and data types of all variables that are defined
outside of functions (i.e.@: excluding local variables).
The printed variables are grouped by source files and annotated with
language of the variable, other values mean to use
the manually specified language (see @ref{Manually, ,Set Language Manually}).
+The @samp{-n} flag excludes non-debugging symbols from the results.
+
The optional flag @samp{-q}, which stands for @samp{quiet}, disables
printing header information and messages explaining why no variables
have been printed.
-@item info variables [-q] [-t @var{type_regexp}] [@var{regexp}]
+@item info variables [-q] [-n] [-t @var{type_regexp}] [@var{regexp}]
Like @kbd{info variables}, but only print the variables selected
with the provided regexp(s).
is printed only if its name matches @var{regexp} and its type matches
@var{type_regexp}.
+@kindex info modules
+@cindex modules
+@item info modules @r{[}-q@r{]} @r{[}@var{regexp}@r{]}
+List all Fortran modules in the program, or all modules matching the
+optional regular expression @var{regexp}.
+
+The optional flag @samp{-q}, which stands for @samp{quiet}, disables
+printing header information and messages explaining why no modules
+have been printed.
+
+@kindex info module
+@cindex Fortran modules, information about
+@cindex functions and variables by Fortran module
+@cindex module functions and variables
+@item info module functions @r{[}-q@r{]} @r{[}-m @var{module-regexp}@r{]} @r{[}-t @var{type-regexp}@r{]} @r{[}@var{regexp}@r{]}
+@itemx info module variables @r{[}-q@r{]} @r{[}-m @var{module-regexp}@r{]} @r{[}-t @var{type-regexp}@r{]} @r{[}@var{regexp}@r{]}
+List all functions or variables within all Fortran modules. The set
+of functions or variables listed can be limited by providing some or
+all of the optional regular expressions. If @var{module-regexp} is
+provided, then only Fortran modules matching @var{module-regexp} will
+be searched. Only functions or variables whose type matches the
+optional regular expression @var{type-regexp} will be listed. And
+only functions or variables whose name matches the optional regular
+expression @var{regexp} will be listed.
+
+The optional flag @samp{-q}, which stands for @samp{quiet}, disables
+printing header information and messages explaining why no functions
+or variables have been printed.
+
@kindex info classes
@cindex Objective-C, classes and selectors
@item info classes
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
-for DWARF debugging information, not stabs. And, they do not
-currently work for programs using Ada.
+Indices only work when using DWARF debugging information, not stabs.
@subsection Automatic symbol index cache
@code{gdbserver} using the @option{--attach} option
(@pxref{Running gdbserver}).
+Some remote targets allow @value{GDBN} to determine the executable file running
+in the process the debugger is attaching to. In such a case, @value{GDBN}
+uses the value of @code{exec-file-mismatch} to handle a possible mismatch
+between the executable file name running in the process and the name of the
+current exec-file loaded by @value{GDBN} (@pxref{set exec-file-mismatch}).
+
@end table
@anchor{Host and target files}
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}:
@tab @code{qXfer:sdata:read}
@tab @code{print $_sdata}
-@item @code{read-spu-object}
-@tab @code{qXfer:spu:read}
-@tab @code{info spu}
-
-@item @code{write-spu-object}
-@tab @code{qXfer:spu:write}
-@tab @code{info spu}
-
@item @code{read-siginfo-object}
@tab @code{qXfer:siginfo:read}
@tab @code{print $_siginfo}
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
information available from a live process. Process information is
-currently avaiable from cores created on @sc{gnu}/Linux and FreeBSD
+currently available from cores created on @sc{gnu}/Linux and FreeBSD
systems.
@table @code
@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
* Alpha::
* MIPS::
* HPPA:: HP PA architecture
-* SPU:: Cell Broadband Engine SPU architecture
* PowerPC::
* Nios II::
* Sparc64::
is a known limitation of @value{GDBN} and does not affect the execution of the
target process.
+@subsubsection AArch64 Pointer Authentication.
+@cindex AArch64 Pointer Authentication.
+
+When @value{GDBN} is debugging the AArch64 architecture, and the program is
+using the v8.3-A feature Pointer Authentication (PAC), then whenever the link
+register @code{$lr} is pointing to an PAC function its value will be masked.
+When GDB prints a backtrace, any addresses that required unmasking will be
+postfixed with the marker [PAC]. When using the MI, this is printed as part
+of the @code{addr_flags} field.
@node i386
@subsection x86 Architecture-specific Issues
@end table
-@node SPU
-@subsection Cell Broadband Engine SPU architecture
-@cindex Cell Broadband Engine
-@cindex SPU
-
-When @value{GDBN} is debugging the Cell Broadband Engine SPU architecture,
-it provides the following special commands:
-
-@table @code
-@item info spu event
-@kindex info spu
-Display SPU event facility status. Shows current event mask
-and pending event status.
-
-@item info spu signal
-Display SPU signal notification facility status. Shows pending
-signal-control word and signal notification mode of both signal
-notification channels.
-
-@item info spu mailbox
-Display SPU mailbox facility status. Shows all pending entries,
-in order of processing, in each of the SPU Write Outbound,
-SPU Write Outbound Interrupt, and SPU Read Inbound mailboxes.
-
-@item info spu dma
-Display MFC DMA status. Shows all pending commands in the MFC
-DMA queue. For each entry, opcode, tag, class IDs, effective
-and local store addresses and transfer size are shown.
-
-@item info spu proxydma
-Display MFC Proxy-DMA status. Shows all pending commands in the MFC
-Proxy-DMA queue. For each entry, opcode, tag, class IDs, effective
-and local store addresses and transfer size are shown.
-
-@end table
-
-When @value{GDBN} is debugging a combined PowerPC/SPU application
-on the Cell Broadband Engine, it provides in addition the following
-special commands:
-
-@table @code
-@item set spu stop-on-load @var{arg}
-@kindex set spu
-Set whether to stop for new SPE threads. When set to @code{on}, @value{GDBN}
-will give control to the user when a new SPE thread enters its @code{main}
-function. The default is @code{off}.
-
-@item show spu stop-on-load
-@kindex show spu
-Show whether to stop for new SPE threads.
-
-@item set spu auto-flush-cache @var{arg}
-Set whether to automatically flush the software-managed cache. When set to
-@code{on}, @value{GDBN} will automatically cause the SPE software-managed
-cache to be flushed whenever SPE execution stops. This provides a consistent
-view of PowerPC memory that is accessed via the cache. If an application
-does not use the software-managed cache, this option has no effect.
-
-@item show spu auto-flush-cache
-Show whether to automatically flush the software-managed cache.
-
-@end table
-
@node PowerPC
@subsection PowerPC
@cindex PowerPC architecture
interface. Users unfamiliar with @sc{gnu} Emacs or @code{vi} are
encouraged to read that chapter.
+@cindex Readline application name
+@value{GDBN} sets the Readline application name to @samp{gdb}. This
+is useful for conditions in @file{.inputrc}.
+
+@cindex operate-and-get-next
+@value{GDBN} defines a bindable Readline command,
+@code{operate-and-get-next}. This is bound to @kbd{C-o} by default.
+This command accepts the current line for execution and fetches the
+next line relative to the current line from the history for editing.
+Any argument is ignored.
+
@node Command History
@section Command History
@cindex command history
@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
intensity is bold. Commands are using the title style to improve
-the readibility of large output. For example, the commands
+the readability of large output. For example, the commands
@command{apropos} and @command{help} are using the title style
for the command names.
the command @command{apropos -v REGEXP} uses the highlight style to
mark the documentation parts matching @var{regexp}.
+@item tui-border
+Control the styling of the TUI border. Note that, unlike other
+styling options, only the color of the border can be controlled via
+@code{set style}. This was done for compatibility reasons, as TUI
+controls to set the border's intensity predated the addition of
+general styling to @value{GDBN}. @xref{TUI Configuration}.
+
+@item tui-active-border
+Control the styling of the active TUI border; that is, the TUI window
+that has the focus.
+
@end table
@node Numbers
@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 remote
Displays the state of display of remote packets.
+@item set debug remote-packet-max-chars
+Sets the maximum number of characters to display for each remote packet when
+@code{set debug remote} is on. This is useful to prevent @value{GDBN} from
+displaying lengthy remote packets and polluting the console.
+
+The default value is @code{512}, which means @value{GDBN} will truncate each
+remote packet after 512 bytes.
+
+Setting this option to @code{unlimited} will disable truncation and will output
+the full length of the remote packets.
+@item show debug remote-packet-max-chars
+Displays the number of bytes to output for remote packet debugging.
+
@item set debug separate-debug-file
Turns on or off display of debug output about separate debug file search.
@item show debug separate-debug-file
@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 timestampping debugging info
+@cindex timestamping debugging info
Turns on or off display of timestamps with @value{GDBN} debugging info.
When enabled, seconds and microseconds are displayed before each debugging
message.
@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
@end table
+@ifset SYSTEM_GDBINIT_DIR
+This setting is not used for files in the system-wide gdbinit directory.
+Files in that directory must have an extension matching their language,
+or have a @file{.gdb} extension to be interpreted as regular @value{GDBN}
+commands. @xref{Startup}.
+@end ifset
+
@node Sequences
@section Canned Sequences of Commands
Define a command named @var{commandname}. If there is already a command
by that name, you are asked to confirm that you want to redefine it.
The argument @var{commandname} may be a bare command name consisting of letters,
-numbers, dashes, and underscores. It may also start with any predefined
-prefix command. For example, @samp{define target my-target} creates
+numbers, dashes, dots, and underscores. It may also start with any
+predefined or user-defined prefix command.
+For example, @samp{define target my-target} creates
a user-defined @samp{target my-target} command.
The definition of the command is made up of other @value{GDBN} command lines,
documentation of a command. Redefining the command with @code{define}
does not change the documentation.
+@kindex define-prefix
+@item define-prefix @var{commandname}
+Define or mark the command @var{commandname} as a user-defined prefix
+command. Once marked, @var{commandname} can be used as prefix command
+by the @code{define} command.
+Note that @code{define-prefix} can be used with a not yet defined
+@var{commandname}. In such a case, @var{commandname} is defined as
+an empty user-defined command.
+In case you redefine a command that was marked as a user-defined
+prefix command, the subcommands of the redefined command are kept
+(and @value{GDBN} indicates so to the user).
+
+Example:
+@example
+(gdb) define-prefix abc
+(gdb) define-prefix abc def
+(gdb) define abc def
+Type commands for definition of "abc def".
+End with a line saying just "end".
+>echo command initial def\n
+>end
+(gdb) define abc def ghi
+Type commands for definition of "abc def ghi".
+End with a line saying just "end".
+>echo command ghi\n
+>end
+(gdb) define abc def
+Keeping subcommands of prefix command "def".
+Redefine command "def"? (y or n) y
+Type commands for definition of "abc def".
+End with a line saying just "end".
+>echo command def\n
+>end
+(gdb) abc def ghi
+command ghi
+(gdb) abc def
+command def
+(gdb)
+@end example
+
@kindex dont-repeat
@cindex don't repeat command
@item dont-repeat
@kindex help user-defined
@item help user-defined
List all user-defined commands and all python commands defined in class
-COMAND_USER. The first line of the documentation or docstring is
+COMMAND_USER. The first line of the documentation or docstring is
included (if any).
@kindex show user
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
assembly and registers.
@end itemize
+These are the standard layouts, but other layouts can be defined.
+
A status line above the command window shows the following information:
@table @emph
the TUI mode, control is given back to the curses windows.
The screen is then refreshed.
+This key binding uses the bindable Readline function
+@code{tui-switch-mode}.
+
@kindex C-x 1
@item C-x 1
Use a TUI layout with only one window. The layout will
Think of this key binding as the Emacs @kbd{C-x 1} binding.
+This key binding uses the bindable Readline function
+@code{tui-delete-other-windows}.
+
@kindex C-x 2
@item C-x 2
Use a TUI layout with at least two windows. When the current
Think of it as the Emacs @kbd{C-x 2} binding.
+This key binding uses the bindable Readline function
+@code{tui-change-windows}.
+
@kindex C-x o
@item C-x o
Change the active window. The TUI associates several key bindings
Think of it as the Emacs @kbd{C-x o} binding.
+This key binding uses the bindable Readline function
+@code{tui-other-window}.
+
@kindex C-x s
@item C-x s
Switch in and out of the TUI SingleKey mode that binds single
keys to @value{GDBN} commands (@pxref{TUI Single Key Mode}).
+
+This key binding uses the bindable Readline function
+@code{next-keymap}.
@end table
The following key bindings only work in the TUI mode:
SingleKey mode is restored. The only way to permanently leave
this mode is by typing @kbd{q} or @kbd{C-x s}.
+@cindex SingleKey keymap name
+If @value{GDBN} was built with Readline 8.0 or later, the TUI
+SingleKey keymap will be named @samp{SingleKey}. This can be used in
+@file{.inputrc} to add additional bindings to this keymap.
@node TUI Commands
@section TUI-specific Commands
@item tui enable
@kindex tui enable
Activate TUI mode. The last active TUI window layout will be used if
-TUI mode has prevsiouly been used in the current debugging session,
+TUI mode has previously been used in the current debugging session,
otherwise a default layout is used.
@item tui disable
@kindex info win
List and give the size of all displayed windows.
+@item tui new-layout @var{name} @var{window} @var{weight} @r{[}@var{window} @var{weight}@dots{}@r{]}
+@kindex tui new-layout
+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 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. 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
+used to calculate how much of the screen is given to each window.
+
+For example:
+
+@example
+(gdb) tui new-layout example src 1 regs 1 status 0 cmd 1
+@end example
+
+Here, the new layout is called @samp{example}. It shows the source
+and register windows, followed by the status window, and then finally
+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. In each layout the command
-window is always displayed, the @var{name} parameter controls which
-additional windows are displayed, and can be any of the following:
+Changes which TUI windows are displayed. The @var{name} parameter
+controls which layout is shown. It can be either one of the built-in
+layout names, or the name of a layout defined by the user using
+@code{tui new-layout}.
+
+The built-in layouts are as follows:
@table @code
@item next
Set the width of tab stops to be @var{nchars} characters. This
setting affects the display of TAB characters in the source and
assembly windows.
+
+@item set tui compact-source @r{[}on@r{|}off@r{]}
+@kindex set tui compact-source
+Set whether the TUI source window is displayed in ``compact'' form.
+The default display uses more space for line numbers and starts the
+source text at the next tab stop; the compact display uses only as
+much space as is needed for the line numbers in the current file, and
+only a single space to separate the line numbers from the source.
@end table
+Note that the colors of the TUI borders can be controlled using the
+appropriate @code{set style} commands. @xref{Output Styling}.
+
@node Emacs
@chapter Using @value{GDBN} under @sc{gnu} Emacs
On some targets, @value{GDBN} is capable of processing MI commands
even while the target is running. This is called @dfn{asynchronous
command execution} (@pxref{Background Execution}). The frontend may
-specify a preferrence for asynchronous execution using the
+specify a preference for asynchronous execution using the
@code{-gdb-set mi-async 1} command, which should be emitted before
either running the executable or attaching to the target. After the
frontend has started the executable or attached to the target, it can
@node Thread groups
@subsection Thread groups
@value{GDBN} may be used to debug several processes at the same time.
-On some platfroms, @value{GDBN} may support debugging of several
+On some platforms, @value{GDBN} may support debugging of several
hardware systems, each one having several cores with several different
processes running on each core. This section describes the MI
mechanism to support such debugging scenarios.
In general, the content of a thread group may be only retrieved only
after attaching to that thread group.
-Thread groups are related to inferiors (@pxref{Inferiors and
+Thread groups are related to inferiors (@pxref{Inferiors Connections and
Programs}). Each inferior corresponds to a thread group of a special
type @samp{process}, and some additional operations are permitted on
such thread groups.
@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
multiple locations. This field will not be present if no address can
be determined. For example, a watchpoint does not have an address.
+@item addr_flags
+Optional field containing any flags related to the address. These flags are
+architecture-dependent; see @ref{Architectures} for their meaning for a
+particular CPU.
+
@item func
If known, the function in which the breakpoint appears.
If not known, this field is not present.
exceptionally present if the breakpoint is enabled and has a single, disabled
location.
-The value is a list of locations. The format of a location is decribed below.
+The value is a list of locations. The format of a location is described below.
@end table
@item addr
The address of this location as an hexidecimal number.
+@item addr_flags
+Optional field containing any flags related to the address. These flags are
+architecture-dependent; see @ref{Architectures} for their meaning for a
+particular CPU.
+
@item func
If known, the function in which the location appears.
If not known, this field is not present.
@item addr
The code address for the frame. This field is always present.
+@item addr_flags
+Optional field containing any flags related to the address. These flags are
+architecture-dependent; see @ref{Architectures} for their meaning for a
+particular CPU.
+
@item file
The name of the source files that correspond to the frame's code
address. This field may be absent.
@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 @code{-var-update}
@tab update the variable and its children
@item @code{-var-set-frozen}
-@tab set frozeness attribute
+@tab set frozenness attribute
@item @code{-var-set-update-range}
@tab set range of children to display on update
@end multitable
every address, which is not practical. Therefore, @value{GDBN} will
attempt to read all accessible memory units at either beginning or the end
of the region, using a binary division scheme. This heuristic works
-well for reading accross a memory map boundary. Note that if a region
+well for reading across a memory map boundary. Note that if a region
has a readable range that is neither at the beginning or the end,
@value{GDBN} will not read it.
@subsubheading Example
N.A.
+@end ignore
+
+@subheading The @code{-symbol-info-functions} Command
+@findex -symbol-info-functions
+@anchor{-symbol-info-functions}
+
+@subsubheading Synopsis
+
+@smallexample
+ -symbol-info-functions [--include-nondebug]
+ [--type @var{type_regexp}]
+ [--name @var{name_regexp}]
+ [--max-results @var{limit}]
+@end smallexample
+
+@noindent
+Return a list containing the names and types for all global functions
+taken from the debug information. The functions are grouped by source
+file, and shown with the line number on which each function is
+defined.
+
+The @code{--include-nondebug} option causes the output to include
+code symbols from the symbol table.
+
+The options @code{--type} and @code{--name} allow the symbols returned
+to be filtered based on either the name of the function, or the type
+signature of the function.
+
+The option @code{--max-results} restricts the command to return no
+more than @var{limit} results. If exactly @var{limit} results are
+returned then there might be additional results available if a higher
+limit is used.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{info functions}.
+@subsubheading Example
+@smallexample
+@group
+(gdb)
+-symbol-info-functions
+^done,symbols=
+ @{debug=
+ [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
+ symbols=[@{line="36", name="f4", type="void (int *)",
+ description="void f4(int *);"@},
+ @{line="42", name="main", type="int ()",
+ description="int main();"@},
+ @{line="30", name="f1", type="my_int_t (int, int)",
+ description="static my_int_t f1(int, int);"@}]@},
+ @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",
+ symbols=[@{line="33", name="f2", type="float (another_float_t)",
+ description="float f2(another_float_t);"@},
+ @{line="39", name="f3", type="int (another_int_t)",
+ description="int f3(another_int_t);"@},
+ @{line="27", name="f1", type="another_float_t (int)",
+ description="static another_float_t f1(int);"@}]@}]@}
+@end group
+@group
+(gdb)
+-symbol-info-functions --name f1
+^done,symbols=
+ @{debug=
+ [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
+ symbols=[@{line="30", name="f1", type="my_int_t (int, int)",
+ description="static my_int_t f1(int, int);"@}]@},
+ @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",
+ symbols=[@{line="27", name="f1", type="another_float_t (int)",
+ description="static another_float_t f1(int);"@}]@}]@}
+@end group
+@group
+(gdb)
+-symbol-info-functions --type void
+^done,symbols=
+ @{debug=
+ [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
+ symbols=[@{line="36", name="f4", type="void (int *)",
+ description="void f4(int *);"@}]@}]@}
+@end group
+@group
+(gdb)
+-symbol-info-functions --include-nondebug
+^done,symbols=
+ @{debug=
+ [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
+ symbols=[@{line="36", name="f4", type="void (int *)",
+ description="void f4(int *);"@},
+ @{line="42", name="main", type="int ()",
+ description="int main();"@},
+ @{line="30", name="f1", type="my_int_t (int, int)",
+ description="static my_int_t f1(int, int);"@}]@},
+ @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",
+ symbols=[@{line="33", name="f2", type="float (another_float_t)",
+ description="float f2(another_float_t);"@},
+ @{line="39", name="f3", type="int (another_int_t)",
+ description="int f3(another_int_t);"@},
+ @{line="27", name="f1", type="another_float_t (int)",
+ description="static another_float_t f1(int);"@}]@}],
+ nondebug=
+ [@{address="0x0000000000400398",name="_init"@},
+ @{address="0x00000000004003b0",name="_start"@},
+ ...
+ ]@}
+@end group
+@end smallexample
-@subheading The @code{-symbol-info-function} Command
-@findex -symbol-info-function
+@subheading The @code{-symbol-info-module-functions} Command
+@findex -symbol-info-module-functions
+@anchor{-symbol-info-module-functions}
@subsubheading Synopsis
@smallexample
- -symbol-info-function
+ -symbol-info-module-functions [--module @var{module_regexp}]
+ [--name @var{name_regexp}]
+ [--type @var{type_regexp}]
@end smallexample
-Show which function the symbol lives in.
+@noindent
+Return a list containing the names of all known functions within all
+know Fortran modules. The functions are grouped by source file and
+containing module, and shown with the line number on which each
+function is defined.
+
+The option @code{--module} only returns results for modules matching
+@var{module_regexp}. The option @code{--name} only returns functions
+whose name matches @var{name_regexp}, and @code{--type} only returns
+functions whose type matches @var{type_regexp}.
@subsubheading @value{GDBN} Command
-@samp{gdb_get_function} in @code{gdbtk}.
+The corresponding @value{GDBN} command is @samp{info module functions}.
@subsubheading Example
-N.A.
+@smallexample
+@group
+(gdb)
+-symbol-info-module-functions
+^done,symbols=
+ [@{module="mod1",
+ files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
+ symbols=[@{line="21",name="mod1::check_all",type="void (void)",
+ description="void mod1::check_all(void);"@}]@}]@},
+ @{module="mod2",
+ files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
+ symbols=[@{line="30",name="mod2::check_var_i",type="void (void)",
+ description="void mod2::check_var_i(void);"@}]@}]@},
+ @{module="mod3",
+ files=[@{filename="/projec/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
+ fullname="/projec/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
+ symbols=[@{line="21",name="mod3::check_all",type="void (void)",
+ description="void mod3::check_all(void);"@},
+ @{line="27",name="mod3::check_mod2",type="void (void)",
+ description="void mod3::check_mod2(void);"@}]@}]@},
+ @{module="modmany",
+ files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
+ symbols=[@{line="35",name="modmany::check_some",type="void (void)",
+ description="void modmany::check_some(void);"@}]@}]@},
+ @{module="moduse",
+ files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
+ symbols=[@{line="44",name="moduse::check_all",type="void (void)",
+ description="void moduse::check_all(void);"@},
+ @{line="49",name="moduse::check_var_x",type="void (void)",
+ description="void moduse::check_var_x(void);"@}]@}]@}]
+@end group
+@end smallexample
+
+@subheading The @code{-symbol-info-module-variables} Command
+@findex -symbol-info-module-variables
+@anchor{-symbol-info-module-variables}
+
+@subsubheading Synopsis
+
+@smallexample
+ -symbol-info-module-variables [--module @var{module_regexp}]
+ [--name @var{name_regexp}]
+ [--type @var{type_regexp}]
+@end smallexample
+
+@noindent
+Return a list containing the names of all known variables within all
+know Fortran modules. The variables are grouped by source file and
+containing module, and shown with the line number on which each
+variable is defined.
+
+The option @code{--module} only returns results for modules matching
+@var{module_regexp}. The option @code{--name} only returns variables
+whose name matches @var{name_regexp}, and @code{--type} only returns
+variables whose type matches @var{type_regexp}.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{info module variables}.
+
+@subsubheading Example
+
+@smallexample
+@group
+(gdb)
+-symbol-info-module-variables
+^done,symbols=
+ [@{module="mod1",
+ files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
+ symbols=[@{line="18",name="mod1::var_const",type="integer(kind=4)",
+ description="integer(kind=4) mod1::var_const;"@},
+ @{line="17",name="mod1::var_i",type="integer(kind=4)",
+ description="integer(kind=4) mod1::var_i;"@}]@}]@},
+ @{module="mod2",
+ files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
+ symbols=[@{line="28",name="mod2::var_i",type="integer(kind=4)",
+ description="integer(kind=4) mod2::var_i;"@}]@}]@},
+ @{module="mod3",
+ files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
+ symbols=[@{line="18",name="mod3::mod1",type="integer(kind=4)",
+ description="integer(kind=4) mod3::mod1;"@},
+ @{line="17",name="mod3::mod2",type="integer(kind=4)",
+ description="integer(kind=4) mod3::mod2;"@},
+ @{line="19",name="mod3::var_i",type="integer(kind=4)",
+ description="integer(kind=4) mod3::var_i;"@}]@}]@},
+ @{module="modmany",
+ files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
+ symbols=[@{line="33",name="modmany::var_a",type="integer(kind=4)",
+ description="integer(kind=4) modmany::var_a;"@},
+ @{line="33",name="modmany::var_b",type="integer(kind=4)",
+ description="integer(kind=4) modmany::var_b;"@},
+ @{line="33",name="modmany::var_c",type="integer(kind=4)",
+ description="integer(kind=4) modmany::var_c;"@},
+ @{line="33",name="modmany::var_i",type="integer(kind=4)",
+ description="integer(kind=4) modmany::var_i;"@}]@}]@},
+ @{module="moduse",
+ files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
+ symbols=[@{line="42",name="moduse::var_x",type="integer(kind=4)",
+ description="integer(kind=4) moduse::var_x;"@},
+ @{line="42",name="moduse::var_y",type="integer(kind=4)",
+ description="integer(kind=4) moduse::var_y;"@}]@}]@}]
+@end group
+@end smallexample
+
+@subheading The @code{-symbol-info-modules} Command
+@findex -symbol-info-modules
+@anchor{-symbol-info-modules}
+
+@subsubheading Synopsis
+
+@smallexample
+ -symbol-info-modules [--name @var{name_regexp}]
+ [--max-results @var{limit}]
+
+@end smallexample
+
+@noindent
+Return a list containing the names of all known Fortran modules. The
+modules are grouped by source file, and shown with the line number on
+which each modules is defined.
+
+The option @code{--name} allows the modules returned to be filtered
+based the name of the module.
+
+The option @code{--max-results} restricts the command to return no
+more than @var{limit} results. If exactly @var{limit} results are
+returned then there might be additional results available if a higher
+limit is used.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{info modules}.
+
+@subsubheading Example
+@smallexample
+@group
+(gdb)
+-symbol-info-modules
+^done,symbols=
+ @{debug=
+ [@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
+ symbols=[@{line="16",name="mod1"@},
+ @{line="22",name="mod2"@}]@},
+ @{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
+ symbols=[@{line="16",name="mod3"@},
+ @{line="22",name="modmany"@},
+ @{line="26",name="moduse"@}]@}]@}
+@end group
+@group
+(gdb)
+-symbol-info-modules --name mod[123]
+^done,symbols=
+ @{debug=
+ [@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
+ symbols=[@{line="16",name="mod1"@},
+ @{line="22",name="mod2"@}]@},
+ @{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
+ symbols=[@{line="16",name="mod3"@}]@}]@}
+@end group
+@end smallexample
+
+@subheading The @code{-symbol-info-types} Command
+@findex -symbol-info-types
+@anchor{-symbol-info-types}
+
+@subsubheading Synopsis
+
+@smallexample
+ -symbol-info-types [--name @var{name_regexp}]
+ [--max-results @var{limit}]
+
+@end smallexample
+
+@noindent
+Return a list of all defined types. The types are grouped by source
+file, and shown with the line number on which each user defined type
+is defined. Some base types are not defined in the source code but
+are added to the debug information by the compiler, for example
+@code{int}, @code{float}, etc.; these types do not have an associated
+line number.
+
+The option @code{--name} allows the list of types returned to be
+filtered by name.
+
+The option @code{--max-results} restricts the command to return no
+more than @var{limit} results. If exactly @var{limit} results are
+returned then there might be additional results available if a higher
+limit is used.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{info types}.
+
+@subsubheading Example
+@smallexample
+@group
+(gdb)
+-symbol-info-types
+^done,symbols=
+ @{debug=
+ [@{filename="gdb.mi/mi-sym-info-1.c",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
+ symbols=[@{name="float"@},
+ @{name="int"@},
+ @{line="27",name="typedef int my_int_t;"@}]@},
+ @{filename="gdb.mi/mi-sym-info-2.c",
+ fullname="/project/gdb.mi/mi-sym-info-2.c",
+ symbols=[@{line="24",name="typedef float another_float_t;"@},
+ @{line="23",name="typedef int another_int_t;"@},
+ @{name="float"@},
+ @{name="int"@}]@}]@}
+@end group
+@group
+(gdb)
+-symbol-info-types --name _int_
+^done,symbols=
+ @{debug=
+ [@{filename="gdb.mi/mi-sym-info-1.c",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
+ symbols=[@{line="27",name="typedef int my_int_t;"@}]@},
+ @{filename="gdb.mi/mi-sym-info-2.c",
+ fullname="/project/gdb.mi/mi-sym-info-2.c",
+ symbols=[@{line="23",name="typedef int another_int_t;"@}]@}]@}
+@end group
+@end smallexample
+
+@subheading The @code{-symbol-info-variables} Command
+@findex -symbol-info-variables
+@anchor{-symbol-info-variables}
+
+@subsubheading Synopsis
+
+@smallexample
+ -symbol-info-variables [--include-nondebug]
+ [--type @var{type_regexp}]
+ [--name @var{name_regexp}]
+ [--max-results @var{limit}]
+
+@end smallexample
+
+@noindent
+Return a list containing the names and types for all global variables
+taken from the debug information. The variables are grouped by source
+file, and shown with the line number on which each variable is
+defined.
+
+The @code{--include-nondebug} option causes the output to include
+data symbols from the symbol table.
+The options @code{--type} and @code{--name} allow the symbols returned
+to be filtered based on either the name of the variable, or the type
+of the variable.
+
+The option @code{--max-results} restricts the command to return no
+more than @var{limit} results. If exactly @var{limit} results are
+returned then there might be additional results available if a higher
+limit is used.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{info variables}.
+
+@subsubheading Example
+@smallexample
+@group
+(gdb)
+-symbol-info-variables
+^done,symbols=
+ @{debug=
+ [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
+ symbols=[@{line="25",name="global_f1",type="float",
+ description="static float global_f1;"@},
+ @{line="24",name="global_i1",type="int",
+ description="static int global_i1;"@}]@},
+ @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",
+ symbols=[@{line="21",name="global_f2",type="int",
+ description="int global_f2;"@},
+ @{line="20",name="global_i2",type="int",
+ description="int global_i2;"@},
+ @{line="19",name="global_f1",type="float",
+ description="static float global_f1;"@},
+ @{line="18",name="global_i1",type="int",
+ description="static int global_i1;"@}]@}]@}
+@end group
+@group
+(gdb)
+-symbol-info-variables --name f1
+^done,symbols=
+ @{debug=
+ [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
+ symbols=[@{line="25",name="global_f1",type="float",
+ description="static float global_f1;"@}]@},
+ @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",
+ symbols=[@{line="19",name="global_f1",type="float",
+ description="static float global_f1;"@}]@}]@}
+@end group
+@group
+(gdb)
+-symbol-info-variables --type float
+^done,symbols=
+ @{debug=
+ [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
+ symbols=[@{line="25",name="global_f1",type="float",
+ description="static float global_f1;"@}]@},
+ @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",
+ symbols=[@{line="19",name="global_f1",type="float",
+ description="static float global_f1;"@}]@}]@}
+@end group
+@group
+(gdb)
+-symbol-info-variables --include-nondebug
+^done,symbols=
+ @{debug=
+ [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
+ symbols=[@{line="25",name="global_f1",type="float",
+ description="static float global_f1;"@},
+ @{line="24",name="global_i1",type="int",
+ description="static int global_i1;"@}]@},
+ @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",
+ fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",
+ symbols=[@{line="21",name="global_f2",type="int",
+ description="int global_f2;"@},
+ @{line="20",name="global_i2",type="int",
+ description="int global_i2;"@},
+ @{line="19",name="global_f1",type="float",
+ description="static float global_f1;"@},
+ @{line="18",name="global_i1",type="int",
+ description="static int global_i1;"@}]@}],
+ nondebug=
+ [@{address="0x00000000004005d0",name="_IO_stdin_used"@},
+ @{address="0x00000000004005d8",name="__dso_handle"@}
+ ...
+ ]@}
+@end group
+@end smallexample
+
+@ignore
@subheading The @code{-symbol-info-line} Command
@findex -symbol-info-line
@ftable @samp
@item frozen-varobjs
Indicates support for the @code{-var-set-frozen} command, as well
-as possible presense of the @code{frozen} field in the output
+as possible presence of the @code{frozen} field in the output
of @code{-varobj-create}.
@item pending-breakpoints
Indicates support for the @option{-f} option to the @code{-break-insert}
-add-inferior
@end smallexample
-Creates a new inferior (@pxref{Inferiors and Programs}). The created
+Creates a new inferior (@pxref{Inferiors Connections and Programs}). The created
inferior is not associated with any executable. Such association may
be established with the @samp{-file-exec-and-symbols} command
(@pxref{GDB/MI File Commands}). The command response has a single
Broadly speaking, the JIT interface mirrors the dynamic loader interface. The
JIT compiler communicates with @value{GDBN} by writing data into a global
-variable and calling a fuction at a well-known symbol. When @value{GDBN}
+variable and calling a function at a well-known symbol. When @value{GDBN}
attaches, it reads a linked list of symbol files from the global variable to
find existing code, and puts a breakpoint in the function so that it can find
out about additional code.
functions. These functions are executed to read the debug info
generated by the JIT compiler (@code{read}), to unwind stack frames
(@code{unwind}) and to create canonical frame IDs
-(@code{get_Frame_id}). It also has a callback that is called when the
+(@code{get_frame_id}). It also has a callback that is called when the
reader is being unloaded (@code{destroy}). The struct looks like this
@smallexample
@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}
@item --with-gdb-datadir=@var{path}
Set the @value{GDBN}-specific data directory. @value{GDBN} will look
here for certain supporting files or scripts. This defaults to the
-@file{gdb} subdirectory of @samp{datadi} (which can be set using
+@file{gdb} subdirectory of @samp{datadir} (which can be set using
@code{--datadir}).
@item --with-relocated-sources=@var{dir}
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
@item --with-system-readline
Use the readline library installed on the host, rather than the
-library supplied as part of @value{GDBN}.
+library supplied as part of @value{GDBN}. Readline 7 or newer is
+required; this is enforced by the build system.
@item --with-system-zlib
Use the zlib library installed on the host, rather than the library
another location after being built, the location of the system-wide
init file will be adjusted accordingly.
+@item --with-system-gdbinit-dir=@var{directory}
+Configure @value{GDBN} to automatically load init files from a
+system-wide directory. @var{directory} should be an absolute directory
+name. If @var{directory} is in a directory under the configured
+prefix, and @value{GDBN} is moved to another location after being
+built, the location of the system-wide init directory will be
+adjusted accordingly.
+
@item --enable-build-warnings
When building the @value{GDBN} sources, ask the compiler to warn about
any code which looks even vaguely suspicious. It passes many
@section System-wide configuration and settings
@cindex system-wide init file
-@value{GDBN} can be configured to have a system-wide init file;
-this file will be read and executed at startup (@pxref{Startup, , What
-@value{GDBN} does during startup}).
+@value{GDBN} can be configured to have a system-wide init file and a
+system-wide init file directory; this file and files in that directory
+(if they have a recognized file extension) will be read and executed at
+startup (@pxref{Startup, , What @value{GDBN} does during startup}).
-Here is the corresponding configure option:
+Here are the corresponding configure options:
@table @code
@item --with-system-gdbinit=@var{file}
Specify that the default location of the system-wide init file is
@var{file}.
+@item --with-system-gdbinit-dir=@var{directory}
+Specify that the default location of the system-wide init file directory
+is @var{directory}.
@end table
If @value{GDBN} has been configured with the option @option{--prefix=$prefix},
-it may be subject to relocation. Two possible cases:
+they may be subject to relocation. Two possible cases:
@itemize @bullet
@item
-If the default location of this init file contains @file{$prefix},
+If the default location of this init file/directory contains @file{$prefix},
it will be subject to relocation. Suppose that the configure options
are @option{--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit};
if @value{GDBN} is moved from @file{$prefix} to @file{$install}, the system
started with the @code{set data-directory} command, the file will not be
reread.
+This applies similarly to the system-wide directory specified in
+@option{--with-system-gdbinit-dir}.
+
+Any supported scripting language can be used for these init files, as long
+as the file extension matches the scripting language. To be interpreted
+as regular @value{GDBN} commands, the files needs to have a @file{.gdb}
+extension.
+
@menu
* System-wide Configuration Scripts:: Installed System-wide Configuration Scripts
@end menu
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
If DWARF frame unwinders are not supported for a particular target
architecture, then enabling this flag does not cause them to be used.
+
+@kindex maint set worker-threads
+@kindex maint show worker-threads
+@item maint set worker-threads
+@item maint show worker-threads
+Control the number of worker threads that may be used by @value{GDBN}.
+On capable hosts, @value{GDBN} may use multiple threads to speed up
+certain CPU-intensive operations, such as demangling symbol names.
+While the number of threads used by @value{GDBN} may vary, this
+command can be used to set an upper bound on this number. The default
+is @code{unlimited}, which lets @value{GDBN} choose a reasonable
+number. Note that this only controls worker threads started by
+@value{GDBN} itself; libraries used by @value{GDBN} may start threads
+of their own.
+
@kindex maint set profile
@kindex maint show profile
@cindex profiling GDB
target supports it.
@end table
+@kindex maint set tui-resize-message
+@kindex maint show tui-resize-message
+@item maint set tui-resize-message
+@item maint show tui-resize-message
+Control whether @value{GDBN} displays a message each time the terminal
+is resized when in TUI mode. The default is @code{off}, which means
+that @value{GDBN} is silent during resizes. When @code{on},
+@value{GDBN} will display a message after a resize is completed; the
+message will include a number indicating how many times the terminal
+has been resized. This setting is intended for use by the test suite,
+where it would otherwise be difficult to determine when a resize and
+refresh has been completed.
+
@kindex maint set per-command
@kindex maint show per-command
@item maint set per-command
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.
stopped.
@emph{Note:} In non-stop mode, a thread is considered running until
-@value{GDBN} acknowleges an asynchronous stop notification for it with
+@value{GDBN} acknowledges an asynchronous stop notification for it with
the @samp{vStopped} packet (@pxref{Remote Non-Stop}).
The stub must support @samp{vCont} if it reports support for
@command{gdbserver} handles unknown packets, it is important that this
packet be handled in the same way as other unknown @samp{v} packets.
If this packet is handled differently to other unknown @samp{v}
-packets then it is possile that @value{GDBN} may run into problems in
+packets then it is possible that @value{GDBN} may run into problems in
other areas, specifically around use of @samp{vFile:setfs:}.
@item vRun;@var{filename}@r{[};@var{argument}@r{]}@dots{}
@table @samp
@item OK
The stub has switched to no-acknowledgment mode.
-@value{GDBN} acknowledges this reponse,
+@value{GDBN} acknowledges this response,
but neither the stub nor @value{GDBN} shall send or expect further
@samp{+}/@samp{-} acknowledgments in the current connection.
@item @w{}
@tab @samp{-}
@tab Yes
-@item @samp{qXfer:spu:read}
-@tab No
-@tab @samp{-}
-@tab Yes
-
-@item @samp{qXfer:spu:write}
-@tab No
-@tab @samp{-}
-@tab Yes
-
@item @samp{qXfer:siginfo:read}
@tab No
@tab @samp{-}
The remote stub understands the @samp{qXfer:sdata:read} packet
(@pxref{qXfer sdata read}).
-@item qXfer:spu:read
-The remote stub understands the @samp{qXfer:spu:read} packet
-(@pxref{qXfer spu read}).
-
-@item qXfer:spu:write
-The remote stub understands the @samp{qXfer:spu:write} packet
-(@pxref{qXfer spu write}).
-
@item qXfer:siginfo:read
The remote stub understands the @samp{qXfer:siginfo:read} packet
(@pxref{qXfer siginfo read}).
by supplying an appropriate @samp{qSupported} response
(@pxref{qSupported}).
-@item qXfer:spu:read:@var{annex}:@var{offset},@var{length}
-@anchor{qXfer spu read}
-Read contents of an @code{spufs} file on the target system. The
-annex specifies which file to read; it must be of the form
-@file{@var{id}/@var{name}}, where @var{id} specifies an SPU context ID
-in the target process, and @var{name} identifes the @code{spufs} file
-in that context to be accessed.
-
-This packet is not probed by default; the remote stub must request it,
-by supplying an appropriate @samp{qSupported} response
-(@pxref{qSupported}).
-
@item qXfer:threads:read::@var{offset},@var{length}
@anchor{qXfer threads read}
Access the list of threads on target. @xref{Thread List Format}. The
This packet is not probed by default; the remote stub must request it,
by supplying an appropriate @samp{qSupported} response
(@pxref{qSupported}).
-
-@item qXfer:spu:write:@var{annex}:@var{offset}:@var{data}@dots{}
-@anchor{qXfer spu write}
-Write @var{data} to an @code{spufs} file on the target system. The
-annex specifies which file to write; it must be of the form
-@file{@var{id}/@var{name}}, where @var{id} specifies an SPU context ID
-in the target process, and @var{name} identifes the @code{spufs} file
-in that context to be accessed.
-
-This packet is not probed by default; the remote stub must request it,
-by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
@end table
@item qXfer:@var{object}:@var{operation}:@dots{}
to @var{fd}. Start the write at @var{offset} from the start of the
file. Unlike many @code{write} system calls, there is no
separate @var{count} argument; the length of @var{data} in the
-packet is used. @samp{vFile:write} returns the number of bytes written,
+packet is used. @samp{vFile:pwrite} returns the number of bytes written,
which may be shorter than the length of @var{data}, or -1 if an
error occurred.
* OpenRISC 1000 Features::
* PowerPC Features::
* RISC-V Features::
+* RX Features::
* S/390 and System z Features::
* Sparc Features::
* TIC6x Features::
@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
This feature is optional. If present, it should contain registers
@samp{fp0} through @samp{fp7}, @samp{fpcontrol}, @samp{fpstatus} and
@samp{fpiaddr}.
+
+Note that, despite the fact that this feature's name says
+@samp{coldfire}, it is used to describe any floating point registers.
+The size of the registers must match the main m68k flavor; so, for
+example, if the primary feature is reported as @samp{coldfire}, then
+64-bit floating point registers are required.
@end table
@node NDS32 Features
feature if the target has the floating point control registers, but no
other floating point hardware.
+@node RX Features
+@subsection RX Features
+@cindex target descriptions, RX Features
+
+The @samp{org.gnu.gdb.rx.core} feature is required for RX
+targets. It should contain the registers @samp{r0} through
+@samp{r15}, @samp{usp}, @samp{isp}, @samp{psw}, @samp{pc}, @samp{intb},
+@samp{bpsw}, @samp{bpc}, @samp{fintv}, @samp{fpsw}, and @samp{acc}.
+
@node S/390 and System z Features
@subsection S/390 and System z Features
@cindex target descriptions, S/390 features
target features mechanism (@pxref{Target Descriptions}), but focuses
on a different aspect of target.
-Operating system information is retrived from the target via the
+Operating system information is retrieved from the target via the
remote protocol, using @samp{qXfer} requests (@pxref{qXfer osdata
read}). The object name in the request should be @samp{osdata}, and
the @var{annex} identifies the data to be fetched.
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
@command{gdbserver} can also debug multiple inferiors at once,
described in
@ifset man
-the @value{GDBN} manual in node @code{Inferiors and Programs}
--- shell command @code{info -f gdb -n 'Inferiors and Programs'}.
+the @value{GDBN} manual in node @code{Inferiors Connections and Programs}
+-- shell command @code{info -f gdb -n 'Inferiors Connections and Programs'}.
@end ifset
@ifclear man
-@ref{Inferiors and Programs}.
+@ref{Inferiors Connections and Programs}.
@end ifclear
In such case use the @code{extended-remote} @value{GDBN} command variant:
@value{SYSTEM_GDBINIT}
@end ifset
+@ifset SYSTEM_GDBINIT_DIR
+@value{SYSTEM_GDBINIT_DIR}/*
+@end ifset
+
+~/.config/gdb/gdbinit
+
~/.gdbinit
./.gdbinit
the @value{GDBN} manual in node @code{System-wide configuration}
-- shell command @code{info -f gdb -n 'System-wide configuration'}.
@end ifset
+@ifset SYSTEM_GDBINIT_DIR
+@item @value{SYSTEM_GDBINIT_DIR}
+@end ifset
+@ifclear SYSTEM_GDBINIT_DIR
+@item (not enabled with @code{--with-system-gdbinit-dir} during compilation)
+@end ifclear
+System-wide initialization directory. All files in this directory are
+executed on startup unless user specified @value{GDBN} option @code{-nx} or
+@code{-n}, as long as they have a recognized file extension.
+See more in
+@ifset man
+the @value{GDBN} manual in node @code{System-wide configuration}
+-- shell command @code{info -f gdb -n 'System-wide configuration'}.
+@end ifset
@ifclear man
@ref{System-wide configuration}.
@end ifclear
-@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