\input texinfo @c -*-texinfo-*-
-@c Copyright (C) 1988-2019 Free Software Foundation, Inc.
+@c Copyright (C) 1988--2020 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-2020 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@end ifset
Version @value{GDBVN}.
-Copyright (C) 1988-2019 Free Software Foundation, Inc.
+Copyright (C) 1988-2020 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
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
* 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,
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.
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
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:
@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
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}.
@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.
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
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
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.
-symbol-info-functions [--include-nondebug]
[--type @var{type_regexp}]
[--name @var{name_regexp}]
+ [--max-results @var{limit}]
@end smallexample
@noindent
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}.
@end group
@end smallexample
+@subheading The @code{-symbol-info-module-functions} Command
+@findex -symbol-info-module-functions
+@anchor{-symbol-info-module-functions}
+
+@subsubheading Synopsis
+
+@smallexample
+ -symbol-info-module-functions [--module @var{module_regexp}]
+ [--name @var{name_regexp}]
+ [--type @var{type_regexp}]
+@end smallexample
+
+@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
+
+The corresponding @value{GDBN} command is @samp{info module functions}.
+
+@subsubheading Example
+
+@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}
@smallexample
-symbol-info-modules [--name @var{name_regexp}]
+ [--max-results @var{limit}]
+
@end smallexample
@noindent
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}.
@smallexample
-symbol-info-types [--name @var{name_regexp}]
+ [--max-results @var{limit}]
+
@end smallexample
@noindent
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}.
-symbol-info-variables [--include-nondebug]
[--type @var{type_regexp}]
[--name @var{name_regexp}]
+ [--max-results @var{limit}]
+
@end smallexample
@noindent
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}.
-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
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
@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:
projects / deliverable / binutils-gdb.git / blobdiff