\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.
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.
-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