the DWARF debugging format, and specify the option @option{-g3}.
@xref{Debugging Options,,Options for Debugging Your Program or GCC,
-gcc.info, Using the @sc{gnu} Compiler Collection (GCC)}, for more
+gcc, Using the @sc{gnu} Compiler Collection (GCC)}, for more
information on @value{NGCC} options affecting debug information.
You will have the best debugging experience if you use the latest
inferiors}}:
@table @code
-@kindex info inferiors
+@kindex info inferiors [ @var{id}@dots{} ]
@item info inferiors
Print a list of all inferiors currently being managed by @value{GDBN}.
+By default all inferiors are printed, but the argument @var{id}@dots{}
+-- a space separated list of inferior numbers -- can be used to limit
+the display to just the requested inferiors.
@value{GDBN} displays for each inferior (in this order):
@item automatic notification of new threads
@item @samp{thread @var{thread-id}}, a command to switch among threads
@item @samp{info threads}, a command to inquire about existing threads
-@item @samp{thread apply [@var{thread-id-list}] [@var{all}] @var{args}},
+@item @samp{thread apply [@var{thread-id-list} | all] @var{args}},
a command to apply a command to a list of threads
@item thread-specific breakpoints
@item @samp{set print thread-events}, which controls printing of
@kindex thread apply
@cindex apply command to several threads
-@item thread apply [@var{thread-id-list} | all [-ascending]] @var{command}
+@item thread apply [@var{thread-id-list} | all [-ascending]] [@var{flag}]@dots{} @var{command}
The @code{thread apply} command allows you to apply the named
@var{command} to one or more threads. Specify the threads that you
want affected using the thread ID list syntax (@pxref{thread ID
@var{command}}. To apply a command to all threads in ascending order,
type @kbd{thread apply all -ascending @var{command}}.
+The @var{flag} arguments control what output to produce and how to handle
+errors raised when applying @var{command} to a thread. @var{flag}
+must start with a @code{-} directly followed by one letter in
+@code{qcs}. If several flags are provided, they must be given
+individually, such as @code{-c -q}.
+
+By default, @value{GDBN} displays some thread information before the
+output produced by @var{command}, and an error raised during the
+execution of a @var{command} will abort @code{thread apply}. The
+following flags can be used to fine-tune this behavior:
+
+@table @code
+@item -c
+The flag @code{-c}, which stands for @samp{continue}, causes any
+errors in @var{command} to be displayed, and the execution of
+@code{thread apply} then continues.
+@item -s
+The flag @code{-s}, which stands for @samp{silent}, causes any errors
+or empty output produced by a @var{command} to be silently ignored.
+That is, the execution continues, but the thread information and errors
+are not printed.
+@item -q
+The flag @code{-q} (@samp{quiet}) disables printing the thread
+information.
+@end table
+
+Flags @code{-c} and @code{-s} cannot be used together.
+
+@kindex taas
+@cindex apply command to all threads (ignoring errors and empty output)
+@item taas @var{command}
+Shortcut for @code{thread apply all -s @var{command}}.
+Applies @var{command} on all threads, ignoring errors and empty output.
+
+@kindex tfaas
+@cindex apply a command to all frames of all threads (ignoring errors and empty output)
+@item tfaas @var{command}
+Shortcut for @code{thread apply all -s frame apply all -s @var{command}}.
+Applies @var{command} on all frames of all threads, ignoring errors
+and empty output. Note that the flag @code{-s} is specified twice:
+The first @code{-s} ensures that @code{thread apply} only shows the thread
+information of the threads for which @code{frame apply} produces
+some output. The second @code{-s} is needed to ensure that @code{frame
+apply} shows the frame information of a frame only if the
+@var{command} successfully produced some output.
+
+It can for example be used to print a local variable or a function
+argument without knowing the thread or frame where this variable or argument
+is, using:
+@smallexample
+(@value{GDBP}) tfaas p some_local_var_i_do_not_remember_where_it_is
+@end smallexample
+
@kindex thread name
@cindex name a thread
Disable the specified skip(s). If @var{range} is not specified, disable all
skips.
+@kindex set debug skip
+@item set debug skip @r{[}on|off@r{]}
+Set whether to print the debug output about skipping files and functions.
+
+@kindex show debug skip
+@item show debug skip
+Show whether the debug output about skipping files and functions is printed.
+
@end table
@node Signals
If the target doesn't support async mode, @value{GDBN} issues an error
message if you attempt to use the background execution commands.
+@cindex @code{&}, background execution of commands
To specify background execution, add a @code{&} to the command. For example,
the background form of the @code{continue} command is @code{continue&}, or
just @code{c&}. The execution commands that accept background execution
* Backtrace:: Backtraces
* Selection:: Selecting a frame
* Frame Info:: Information on a frame
+* Frame Apply:: Applying a command to several frames
* Frame Filter Management:: Managing frame filters
@end menu
in a register called the @dfn{frame pointer register}
(@pxref{Registers, $fp}) while execution is going on in that frame.
+@cindex frame level
@cindex frame number
-@value{GDBN} assigns numbers to all existing stack frames, starting with
-zero for the innermost frame, one for the frame that called it,
-and so on upward. These numbers do not really exist in your program;
-they are assigned by @value{GDBN} to give you a way of designating stack
-frames in @value{GDBN} commands.
+@value{GDBN} labels each existing stack frame with a @dfn{level}, a
+number that is zero for the innermost frame, one for the frame that
+called it, and so on upward. These level numbers give you a way of
+designating stack frames in @value{GDBN} commands. The terms
+@dfn{frame number} and @dfn{frame level} can be used interchangeably to
+describe this number.
@c The -fomit-frame-pointer below perennially causes hbox overflow
@c underflow problems.
@table @code
@kindex frame@r{, selecting}
@kindex f @r{(@code{frame})}
-@item frame @var{n}
-@itemx f @var{n}
-Select frame number @var{n}. Recall that frame zero is the innermost
+@item frame @r{[} @var{frame-selection-spec} @r{]}
+@item f @r{[} @var{frame-selection-spec} @r{]}
+The @command{frame} command allows different stack frames to be
+selected. The @var{frame-selection-spec} can be any of the following:
+
+@table @code
+@kindex frame level
+@item @var{num}
+@item level @var{num}
+Select frame level @var{num}. Recall that frame zero is the innermost
(currently executing) frame, frame one is the frame that called the
-innermost one, and so on. The highest-numbered frame is the one for
-@code{main}.
+innermost one, and so on. The highest level frame is usually the one
+for @code{main}.
+
+As this is the most common method of navigating the frame stack, the
+string @command{level} can be omitted. For example, the following two
+commands are equivalent:
+
+@smallexample
+(@value{GDBP}) frame 3
+(@value{GDBP}) frame level 3
+@end smallexample
+
+@kindex frame address
+@item address @var{stack-address}
+Select the frame with stack address @var{stack-address}. The
+@var{stack-address} for a frame can be seen in the output of
+@command{info frame}, for example:
+
+@smallexample
+(gdb) info frame
+Stack level 1, frame at 0x7fffffffda30:
+ rip = 0x40066d in b (amd64-entry-value.cc:59); saved rip 0x4004c5
+ tail call frame, caller of frame at 0x7fffffffda30
+ source language c++.
+ Arglist at unknown address.
+ Locals at unknown address, Previous frame's sp is 0x7fffffffda30
+@end smallexample
+
+The @var{stack-address} for this frame is @code{0x7fffffffda30} as
+indicated by the line:
+
+@smallexample
+Stack level 1, frame at 0x7fffffffda30:
+@end smallexample
-@item frame @var{stack-addr} [ @var{pc-addr} ]
-@itemx f @var{stack-addr} [ @var{pc-addr} ]
-Select the frame at address @var{stack-addr}. This is useful mainly if the
-chaining of stack frames has been damaged by a bug, making it
-impossible for @value{GDBN} to assign numbers properly to all frames. In
-addition, this can be useful when your program has multiple stacks and
-switches between them. The optional @var{pc-addr} can also be given to
-specify the value of PC for the stack frame.
+@kindex frame function
+@item function @var{function-name}
+Select the stack frame for function @var{function-name}. If there are
+multiple stack frames for function @var{function-name} then the inner
+most stack frame is selected.
+
+@kindex frame view
+@item view @var{stack-address} @r{[} @var{pc-addr} @r{]}
+View a frame that is not part of @value{GDBN}'s backtrace. The frame
+viewed has stack address @var{stack-addr}, and optionally, a program
+counter address of @var{pc-addr}.
+
+This is useful mainly if the chaining of stack frames has been
+damaged by a bug, making it impossible for @value{GDBN} to assign
+numbers properly to all frames. In addition, this can be useful
+when your program has multiple stacks and switches between them.
+
+When viewing a frame outside the current backtrace using
+@command{frame view} then you can always return to the original
+stack using one of the previous stack frame selection instructions,
+for example @command{frame level 0}.
+
+@end table
@kindex up
@item up @var{n}
@table @code
@kindex select-frame
-@item select-frame
+@item select-frame @r{[} @var{frame-selection-spec} @r{]}
The @code{select-frame} command is a variant of @code{frame} that does
not display the new frame after selecting it. This command is
intended primarily for use in @value{GDBN} command scripts, where the
-output might be unnecessary and distracting.
+output might be unnecessary and distracting. The
+@var{frame-selection-spec} is as for the @command{frame} command
+described in @ref{Selection, ,Selecting a Frame}.
@kindex down-silently
@kindex up-silently
something has gone wrong that has made the stack format fail to fit
the usual conventions.
-@item info frame @var{addr}
-@itemx info f @var{addr}
-Print a verbose description of the frame at address @var{addr}, without
-selecting that frame. The selected frame remains unchanged by this
-command. This requires the same kind of address (more than one for some
-architectures) that you specify in the @code{frame} command.
-@xref{Selection, ,Selecting a Frame}.
+@item info frame @r{[} @var{frame-selection-spec} @r{]}
+@itemx info f @r{[} @var{frame-selection-spec} @r{]}
+Print a verbose description of the frame selected by
+@var{frame-selection-spec}. The @var{frame-selection-spec} is the
+same as for the @command{frame} command (@pxref{Selection, ,Selecting
+a Frame}). The selected frame remains unchanged by this command.
@kindex info args
@item info args
@end table
+@node Frame Apply
+@section Applying a Command to Several Frames.
+@kindex frame apply
+@cindex apply command to several frames
+@table @code
+@item frame apply [all | @var{count} | @var{-count} | level @var{level}@dots{}] [@var{flag}]@dots{} @var{command}
+The @code{frame apply} command allows you to apply the named
+@var{command} to one or more frames.
+
+@table @code
+@item @code{all}
+Specify @code{all} to apply @var{command} to all frames.
+
+@item @var{count}
+Use @var{count} to apply @var{command} to the innermost @var{count}
+frames, where @var{count} is a positive number.
+
+@item @var{-count}
+Use @var{-count} to apply @var{command} to the outermost @var{count}
+frames, where @var{count} is a positive number.
+
+@item @code{level}
+Use @code{level} to apply @var{command} to the set of frames identified
+by the @var{level} list. @var{level} is a frame level or a range of frame
+levels as @var{level1}-@var{level2}. The frame level is the number shown
+in the first field of the @samp{backtrace} command output.
+E.g., @samp{2-4 6-8 3} indicates to apply @var{command} for the frames
+at levels 2, 3, 4, 6, 7, 8, and then again on frame at level 3.
+
+@end table
+
+@end table
+
+Note that the frames on which @code{frame apply} applies a command are
+also influenced by the @code{set backtrace} settings such as @code{set
+backtrace past-main} and @code{set backtrace limit N}. See
+@xref{Backtrace,,Backtraces}.
+
+The @var{flag} arguments control what output to produce and how to handle
+errors raised when applying @var{command} to a frame. @var{flag}
+must start with a @code{-} directly followed by one letter in
+@code{qcs}. If several flags are provided, they must be given
+individually, such as @code{-c -q}.
+
+By default, @value{GDBN} displays some frame information before the
+output produced by @var{command}, and an error raised during the
+execution of a @var{command} will abort @code{frame apply}. The
+following flags can be used to fine-tune this behavior:
+
+@table @code
+@item -c
+The flag @code{-c}, which stands for @samp{continue}, causes any
+errors in @var{command} to be displayed, and the execution of
+@code{frame apply} then continues.
+@item -s
+The flag @code{-s}, which stands for @samp{silent}, causes any errors
+or empty output produced by a @var{command} to be silently ignored.
+That is, the execution continues, but the frame information and errors
+are not printed.
+@item -q
+The flag @code{-q} (@samp{quiet}) disables printing the frame
+information.
+@end table
+
+The following example shows how the flags @code{-c} and @code{-s} are
+working when applying the command @code{p j} to all frames, where
+variable @code{j} can only be successfully printed in the outermost
+@code{#1 main} frame.
+
+@smallexample
+@group
+(gdb) frame apply all p j
+#0 some_function (i=5) at fun.c:4
+No symbol "j" in current context.
+(gdb) frame apply all -c p j
+#0 some_function (i=5) at fun.c:4
+No symbol "j" in current context.
+#1 0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11
+$1 = 5
+(gdb) frame apply all -s p j
+#1 0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11
+$2 = 5
+(gdb)
+@end group
+@end smallexample
+
+By default, @samp{frame apply}, prints the frame location
+information before the command output:
+
+@smallexample
+@group
+(gdb) frame apply all p $sp
+#0 some_function (i=5) at fun.c:4
+$4 = (void *) 0xffffd1e0
+#1 0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11
+$5 = (void *) 0xffffd1f0
+(gdb)
+@end group
+@end smallexample
+
+If flag @code{-q} is given, no frame information is printed:
+@smallexample
+@group
+(gdb) frame apply all -q p $sp
+$12 = (void *) 0xffffd1e0
+$13 = (void *) 0xffffd1f0
+(gdb)
+@end group
+@end smallexample
+
+@table @code
+
+@kindex faas
+@cindex apply a command to all frames (ignoring errors and empty output)
+@item faas @var{command}
+Shortcut for @code{frame apply all -s @var{command}}.
+Applies @var{command} on all frames, ignoring errors and empty output.
+
+It can for example be used to print a local variable or a function
+argument without knowing the frame where this variable or argument
+is, using:
+@smallexample
+(@value{GDBP}) faas p some_local_var_i_do_not_remember_where_it_is
+@end smallexample
+
+Note that the command @code{tfaas @var{command}} applies @var{command}
+on all frames of all threads. See @xref{Threads,,Threads}.
+@end table
+
+
@node Frame Filter Management
@section Management of Frame Filters.
@cindex managing frame filters
the disassembler. For a list of valid options, please refer to the
@code{-M}/@code{--disassembler-options} section of the @samp{objdump}
manual and/or the output of @kbd{objdump --help}
-(@pxref{objdump,,objdump,binutils.info,The GNU Binary Utilities}).
+(@pxref{objdump,,objdump,binutils,The GNU Binary Utilities}).
The default value is the empty string.
If it is necessary to specify more than one disassembler option, then
multiple options can be placed together into a comma separated list.
-Currently this command is only supported on targets ARM, PowerPC
+Currently this command is only supported on targets ARM, MIPS, PowerPC
and S/390.
@kindex show disassembler-options
bar
bar1
bar2
-(gdb) disable pretty-printer library2 bar:bar1
+(gdb) disable pretty-printer library2 bar;bar1
1 printer disabled
1 of 3 printers enabled
(gdb) info pretty-printer library2
@item show debug compile
Displays the current state of displaying @value{GDBN} process of
compiling and injecting the code.
+
+@anchor{set debug compile-cplus-types}
+@item set debug compile-cplus-types
+@cindex compile C@t{++} type conversion
+Turns on or off the display of C@t{++} type conversion debugging information.
+The default is off.
+
+@item show debug compile-cplus-types
+Displays the current state of displaying debugging information for
+C@t{++} type conversion.
@end table
@subsection Compilation options for the @code{compile} command
discard information on the executable file.
@kindex symbol-file
-@item symbol-file @r{[} @var{filename} @r{]}
+@item symbol-file @r{[} @var{filename} @r{[} -o @var{offset} @r{]]}
Read symbol table information from file @var{filename}. @code{PATH} is
searched when necessary. Use the @code{file} command to get both symbol
table and program to run from the same file.
+If an optional @var{offset} is specified, it is added to the start
+address of each section in the symbol file. This is useful if the
+program is relocated at runtime, such as the Linux kernel with kASLR
+enabled.
+
@code{symbol-file} with no argument clears out @value{GDBN} information on your
program's symbol table.
@kindex add-symbol-file
@cindex dynamic linking
-@item add-symbol-file @var{filename} @var{address}
-@itemx add-symbol-file @var{filename} @var{address} @r{[} -readnow @r{|} -readnever @r{]}
-@itemx add-symbol-file @var{filename} @var{address} -s @var{section} @var{address} @dots{}
+@item add-symbol-file @var{filename} @r{[} -readnow @r{|} -readnever @r{]} @r{[} -o @var{offset} @r{]} @r{[} @var{textaddress} @r{]} @r{[} -s @var{section} @var{address} @dots{} @r{]}
The @code{add-symbol-file} command reads additional symbol table
information from the file @var{filename}. You would use this command
when @var{filename} has been dynamically loaded (by some other means)
-into the program that is running. The @var{address} should give the memory
-address at which the file has been loaded; @value{GDBN} cannot figure
-this out for itself. You can additionally specify an arbitrary number
-of @samp{-s @var{section} @var{address}} pairs, to give an explicit
-section name and base address for that section. You can specify any
-@var{address} as an expression.
+into the program that is running. The @var{textaddress} parameter gives
+the memory address at which the file's text section has been loaded.
+You can additionally specify the base address of other sections using
+an arbitrary number of @samp{-s @var{section} @var{address}} pairs.
+If a section is omitted, @value{GDBN} will use its default addresses
+as found in @var{filename}. Any @var{address} or @var{textaddress}
+can be given as an expression.
+
+If an optional @var{offset} is specified, it is added to the start
+address of each section, except those for which the address was
+specified explicitly.
The symbol table of the file @var{filename} is added to the symbol table
originally read with the @code{symbol-file} command. You can use the
only on some operating systems, when using the ELF or PE file formats
for binary files and the @sc{gnu} Binutils.) For more details about
this feature, see the description of the @option{--build-id}
-command-line option in @ref{Options, , Command Line Options, ld.info,
+command-line option in @ref{Options, , Command Line Options, ld,
The GNU Linker}. The debug info file's name is not specified
explicitly by the build ID, but can be computed from the build ID, see
below.
for DWARF debugging information, not stabs. And, they do not
currently work for programs using Ada.
+@subsection Automatic symbol index cache
+
+It is possible for @value{GDBN} to automatically save a copy of this index in a
+cache on disk and retrieve it from there when loading the same binary in the
+future. This feature can be turned on with @kbd{set index-cache on}. The
+following commands can be used to tweak the behavior of the index cache.
+
+@table @code
+
+@item set index-cache on
+@itemx set index-cache off
+Enable or disable the use of the symbol index cache.
+
+@item set index-cache directory @var{directory}
+@itemx show index-cache directory
+Set/show the directory where index files will be saved.
+
+The default value for this directory depends on the host platform. On
+most systems, the index is cached in the @file{gdb} subdirectory of
+the directory pointed to by the @env{XDG_CACHE_HOME} environment
+variable, if it is defined, else in the @file{.cache/gdb} subdirectory
+of your home directory. However, on some systems, the default may
+differ according to local convention.
+
+There is no limit on the disk space used by index cache. It is perfectly safe
+to delete the content of that directory to free up disk space.
+
+@item show index-cache stats
+Print the number of cache hits and misses since the launch of @value{GDBN}.
+
+@end table
+
@node Symbol Errors
@section Errors Reading Symbol Files
@end table
+If the @code{set endian auto} mode is in effect and no executable has
+been selected, then the endianness used is the last one chosen either
+by one of the @code{set endian big} and @code{set endian little}
+commands or by inferring from the last executable used. If no
+endianness has been previously chosen, then the default for this mode
+is inferred from the target @value{GDBN} has been built for, and is
+@code{little} if the name of the target CPU has an @code{el} suffix
+and @code{big} otherwise.
+
Note that these commands merely adjust interpretation of symbolic
data on the host, and that they have absolutely no effect on the
target system.
@code{target} command.
@item 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{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 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{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}}
@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 or a numeric @acronym{IP}
-address; @var{port} must be a decimal number. The @var{host} could be
-the target machine itself, if it is directly connected to the net, or
-it might be a terminal server which in turn has a serial line to the
-target.
+The @var{host} may be either a host name, a numeric @acronym{IPv4}
+address, or a numeric @acronym{IPv6} address (with or without the
+square brackets to separate the address from the port); @var{port}
+must be a decimal number. The @var{host} could be the target machine
+itself, if it is directly connected to the net, or it might be a
+terminal server which in turn has a serial line to the target.
For example, to connect to port 2828 on a terminal server named
@code{manyfarms}:
target remote manyfarms:2828
@end smallexample
+To connect to port 2828 on a terminal server whose address is
+@code{2001:0db8:85a3:0000:0000:8a2e:0370:7334}, you can either use the
+square bracket syntax:
+
+@smallexample
+target remote [2001:0db8:85a3:0000:0000:8a2e:0370:7334]:2828
+@end smallexample
+
+@noindent
+or explicitly specify the @acronym{IPv6} protocol:
+
+@smallexample
+target remote tcp6:2001:0db8:85a3:0000:0000:8a2e:0370:7334:2828
+@end smallexample
+
+This last example may be confusing to the reader, because there is no
+visible separation between the hostname and the port number.
+Therefore, we recommend the user to provide @acronym{IPv6} addresses
+using square brackets for clarity. However, it is important to
+mention that for @value{GDBN} there is no ambiguity: the number after
+the last colon is considered to be the port number.
+
If your remote target is actually running on the same machine as your
debugger session (e.g.@: a simulator for your target running on the
same host), you can omit the hostname. For example, to connect to
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{udp4:@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{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}}
@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}:
@anchor{set remote hardware-breakpoint-limit}
@item set remote hardware-watchpoint-limit @var{limit}
@itemx set remote hardware-breakpoint-limit @var{limit}
-Restrict @value{GDBN} to using @var{limit} remote hardware breakpoint or
-watchpoints. A limit of -1, the default, is treated as unlimited.
+Restrict @value{GDBN} to using @var{limit} remote hardware watchpoints
+or breakpoints. The @var{limit} can be set to 0 to disable hardware
+watchpoints or breakpoints, and @code{unlimited} for unlimited
+watchpoints or breakpoints.
+
+@item show remote hardware-watchpoint-limit
+@itemx show remote hardware-breakpoint-limit
+Show the current limit for the number of hardware watchpoints or
+breakpoints that @value{GDBN} can use.
@cindex limit hardware watchpoints length
@cindex remote target, limit watchpoints length
@anchor{set remote hardware-watchpoint-length-limit}
@item set remote hardware-watchpoint-length-limit @var{limit}
-Restrict @value{GDBN} to using @var{limit} bytes for the maximum length of
-a remote hardware watchpoint. A limit of -1, the default, is treated
-as unlimited.
+Restrict @value{GDBN} to using @var{limit} bytes for the maximum
+length of a remote hardware watchpoint. A @var{limit} of 0 disables
+hardware watchpoints and @code{unlimited} allows watchpoints of any
+length.
@item show remote hardware-watchpoint-length-limit
Show the current limit (in bytes) of the maximum length of
@cindex process ID
@item info proc
@itemx info proc @var{process-id}
-Summarize available information about any running process. If a
+Summarize available information about a process. If a
process ID is specified by @var{process-id}, display information about
that process; otherwise display information about the program being
debugged. The summary includes the debugged process ID, the command
Show the name of executable of the process. This command is supported
on @sc{gnu}/Linux and FreeBSD.
+@item info proc files
+@cindex info proc files
+Show the file descriptors open by the process. For each open file
+descriptor, @value{GDBN} shows its number, type (file, directory,
+character device, socket), file pointer offset, and the name of the
+resource open on the descriptor. The resource name can be a file name
+(for files, directories, and devices) or a protocol followed by socket
+address (for network connections). This command is supported on
+FreeBSD.
+
+This example shows the open file descriptors for a process using a
+tty for standard input and output as well as two network sockets:
+
+@smallexample
+(gdb) info proc files 22136
+process 22136
+Open files:
+
+ FD Type Offset Flags Name
+ text file - r-------- /usr/bin/ssh
+ ctty chr - rw------- /dev/pts/20
+ cwd dir - r-------- /usr/home/john
+ root dir - r-------- /
+ 0 chr 0x32933a4 rw------- /dev/pts/20
+ 1 chr 0x32933a4 rw------- /dev/pts/20
+ 2 chr 0x32933a4 rw------- /dev/pts/20
+ 3 socket 0x0 rw----n-- tcp4 10.0.1.2:53014 -> 10.0.1.10:22
+ 4 socket 0x0 rw------- unix stream:/tmp/ssh-FIt89oAzOn5f/agent.2456
+@end smallexample
+
@item info proc mappings
@cindex memory address space mappings
-Report the memory address space ranges accessible in the program. On
+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
@end table
+@subsubsection AArch64 SVE.
+@cindex AArch64 SVE.
+
+When @value{GDBN} is debugging the AArch64 architecture, if the Scalable Vector
+Extension (SVE) is present, then @value{GDBN} will provide the vector registers
+@code{$z0} through @code{$z31}, vector predicate registers @code{$p0} through
+@code{$p15}, and the @code{$ffr} register. In addition, the pseudo register
+@code{$vg} will be provided. This is the vector granule for the current thread
+and represents the number of 64-bit chunks in an SVE @code{z} register.
+
+If the vector length changes, then the @code{$vg} register will be updated,
+but the lengths of the @code{z} and @code{p} registers will not change. This
+is a known limitation of @value{GDBN} and does not affect the execution of the
+target process.
+
+
@node i386
@subsection x86 Architecture-specific Issues
Certain commands to @value{GDBN} may produce large amounts of
information output to the screen. To help you read all of it,
@value{GDBN} pauses and asks you for input at the end of each page of
-output. Type @key{RET} when you want to continue the output, or @kbd{q}
-to discard the remaining output. Also, the screen width setting
-determines when to wrap lines of output. Depending on what is being
-printed, @value{GDBN} tries to break the line at a readable place,
-rather than simply letting it overflow onto the following line.
+output. Type @key{RET} when you want to see one more page of output,
+@kbd{q} to discard the remaining output, or @kbd{c} to continue
+without paging for the rest of the current command. Also, the screen
+width setting determines when to wrap lines of output. Depending on
+what is being printed, @value{GDBN} tries to break the line at a
+readable place, rather than simply letting it overflow onto the
+following line.
Normally @value{GDBN} knows the size of the screen from the terminal
driver software. For example, on Unix @value{GDBN} uses the termcap data base
<- *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0",
frame=@{addr="0x08048564",func="main",
args=[@{name="argc",value="1"@},@{name="argv",value="0xbfc4d4d4"@}],
- file="myprog.c",fullname="/home/nickrob/myprog.c",line="68"@}
+ file="myprog.c",fullname="/home/nickrob/myprog.c",line="68",
+ arch="i386:x86_64"@}
<- (gdb)
-> -exec-continue
<- ^running
*stopped,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@},
value=@{old="-268439212",new="55"@},
frame=@{func="main",args=[],file="recursive2.c",
-fullname="/home/foo/bar/recursive2.c",line="5"@}
+fullname="/home/foo/bar/recursive2.c",line="5",arch="i386:x86_64"@}
(gdb)
@end smallexample
wpt=@{number="5",exp="C"@},value=@{old="-276895068",new="3"@},
frame=@{func="callee4",args=[],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13",
+arch="i386:x86_64"@}
(gdb)
-exec-continue
^running
frame=@{func="callee3",args=[@{name="strarg",
value="0x11940 \"A string argument.\""@}],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18",
+arch="i386:x86_64"@}
(gdb)
@end smallexample
value=@{old="-276895068",new="3"@},
frame=@{func="callee4",args=[],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13",
+arch="i386:x86_64"@}
(gdb)
-break-list
^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
frame=@{func="callee3",args=[@{name="strarg",
value="0x11940 \"A string argument.\""@}],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18",
+arch="i386:x86_64"@}
(gdb)
-break-list
^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
@{id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",
frame=@{level="0",addr="0x0804891f",func="foo",
args=[@{name="i",value="10"@}],
- file="/tmp/a.c",fullname="/tmp/a.c",line="158"@},
+ file="/tmp/a.c",fullname="/tmp/a.c",line="158",arch="i386:x86_64"@},
state="running"@}],
current-thread-id="1"
(gdb)
^done,new-thread-id="3",
frame=@{level="0",func="vprintf",
args=[@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@},
-@{name="arg",value="0x2"@}],file="vprintf.c",line="31"@}
+@{name="arg",value="0x2"@}],file="vprintf.c",line="31",arch="i386:x86_64"@}
(gdb)
@end smallexample
@@Hello world
*stopped,reason="breakpoint-hit",disp="keep",bkptno="2",frame=@{
func="foo",args=[],file="hello.c",fullname="/home/foo/bar/hello.c",
-line="13"@}
+line="13",arch="i386:x86_64"@}
(gdb)
@end smallexample
(gdb)
@@hello from foo
*stopped,reason="function-finished",frame=@{func="main",args=[],
-file="hello.c",fullname="/home/foo/bar/hello.c",line="7"@}
+file="hello.c",fullname="/home/foo/bar/hello.c",line="7",arch="i386:x86_64"@}
(gdb)
@end smallexample
(gdb)
*stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo",
args=[@{name="a",value="1"],@{name="b",value="9"@}@},
-file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
+arch="i386:x86_64"@},
gdb-result-var="$1",return-value="0"
(gdb)
@end smallexample
(gdb)
111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
frame=@{addr="0x00010140",func="foo",args=[],file="try.c",
-fullname="/home/foo/bar/try.c",line="13"@}
+fullname="/home/foo/bar/try.c",line="13",arch="i386:x86_64"@}
(gdb)
(gdb)
000*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",
frame=@{func="callee4",args=[],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8",
+arch="i386:x86_64"@}
(gdb)
205-break-delete
205^done
args=[@{name="strarg",
value="0x11940 \"A string argument.\""@}],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18",
+arch="i386:x86_64"@}
(gdb)
@end smallexample
(gdb)
*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",
frame=@{func="main",args=[],file="recursive2.c",
-fullname="/home/foo/bar/recursive2.c",line="4"@}
+fullname="/home/foo/bar/recursive2.c",line="4",arch="i386:x86_64"@}
(gdb)
@end smallexample
*stopped,reason="end-stepping-range",
frame=@{func="foo",args=[@{name="a",value="10"@},
@{name="b",value="0"@}],file="recursive2.c",
-fullname="/home/foo/bar/recursive2.c",line="11"@}
+fullname="/home/foo/bar/recursive2.c",line="11",arch="i386:x86_64"@}
(gdb)
@end smallexample
(gdb)
*stopped,reason="end-stepping-range",
frame=@{func="foo",args=[],file="try.c",
-fullname="/home/foo/bar/try.c",line="10"@}
+fullname="/home/foo/bar/try.c",line="10",arch="i386:x86_64"@}
(gdb)
-exec-step-instruction
^running
(gdb)
*stopped,reason="end-stepping-range",
frame=@{addr="0x000100f4",func="foo",args=[],file="try.c",
-fullname="/home/foo/bar/try.c",line="10"@}
+fullname="/home/foo/bar/try.c",line="10",arch="i386:x86_64"@}
(gdb)
@end smallexample
(gdb)
x = 55
*stopped,reason="location-reached",frame=@{func="main",args=[],
-file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6"@}
+file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6",
+arch="i386:x86_64"@}
(gdb)
@end smallexample
-stack-info-frame
^done,frame=@{level="1",addr="0x0001076c",func="callee3",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"@}
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17",
+arch="i386:x86_64"@}
(gdb)
@end smallexample
stack=[
frame=@{level="0",addr="0x00010734",func="callee4",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"@},
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8",
+arch="i386:x86_64"@},
frame=@{level="1",addr="0x0001076c",func="callee3",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"@},
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17",
+arch="i386:x86_64"@},
frame=@{level="2",addr="0x0001078c",func="callee2",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22"@},
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22",
+arch="i386:x86_64"@},
frame=@{level="3",addr="0x000107b4",func="callee1",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27"@},
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27",
+arch="i386:x86_64"@},
frame=@{level="4",addr="0x000107e0",func="main",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32"@}]
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32",
+arch="i386:x86_64"@}]
(gdb)
-stack-list-arguments 0
^done,
@item @var{from}
The shared library where this function is defined. This is only given
if the frame's function is not known.
+@item @var{arch}
+Frame's architecture.
@end table
If invoked without arguments, this command prints a backtrace for the
-stack-list-frames
^done,stack=
[frame=@{level="0",addr="0x0001076c",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11",
+ arch="i386:x86_64"@},
frame=@{level="1",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
+ arch="i386:x86_64"@},
frame=@{level="2",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
+ arch="i386:x86_64"@},
frame=@{level="3",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
+ arch="i386:x86_64"@},
frame=@{level="4",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
+ arch="i386:x86_64"@},
frame=@{level="5",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
+ arch="i386:x86_64"@},
frame=@{level="6",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
+ arch="i386:x86_64"@},
frame=@{level="7",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
+ arch="i386:x86_64"@},
frame=@{level="8",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
+ arch="i386:x86_64"@},
frame=@{level="9",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
+ arch="i386:x86_64"@},
frame=@{level="10",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
+ arch="i386:x86_64"@},
frame=@{level="11",addr="0x00010738",func="main",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4"@}]
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4",
+ arch="i386:x86_64"@}]
(gdb)
@end smallexample
-stack-list-frames 3 5
^done,stack=
[frame=@{level="3",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
+ arch="i386:x86_64"@},
frame=@{level="4",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
+ arch="i386:x86_64"@},
frame=@{level="5",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}]
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
+ arch="i386:x86_64"@}]
(gdb)
@end smallexample
-stack-list-frames 3 3
^done,stack=
[frame=@{level="3",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}]
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
+ arch="i386:x86_64"@}]
(gdb)
@end smallexample
@smallexample
-data-disassemble
[ -s @var{start-addr} -e @var{end-addr} ]
+ | [ -a @var{addr} ]
| [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ]
-- @var{mode}
@end smallexample
is the beginning address (or @code{$pc})
@item @var{end-addr}
is the end address
+@item @var{addr}
+is an address anywhere within (or the name of) the function to
+disassemble. If an address is specified, the whole function
+surrounding that address will be disassembled. If a name is
+specified, the whole function with that name will be disassembled.
@item @var{filename}
is the name of the file to disassemble
@item @var{linenum}
(gdb)
*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",frame=@{
func="main",args=[],file="try.c",fullname="/home/foo/bar/try.c",
-line="5"@}
+line="5",arch="powerpc"@}
(gdb)
-data-list-changed-registers
^done,changed-registers=["0","1","2","4","5","6","7","8","9",
@item exec-run-start-option
Indicates that the @code{-exec-run} command supports the @option{--start}
option (@pxref{GDB/MI Program Execution}).
+@item data-disassemble-a-option
+Indicates that the @code{-data-disassemble} command supports the @option{-a}
+option (@pxref{GDB/MI Data Manipulation}).
@end ftable
@subheading The @code{-list-target-features} Command
frame=@{level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]@},state="running"@},
@{id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",
frame=@{level="0",addr="0x0804891f",func="foo",args=[@{name="i",value="10"@}],
- file="/tmp/a.c",fullname="/tmp/a.c",line="158"@},state="running"@}]]
+ file="/tmp/a.c",fullname="/tmp/a.c",line="158",arch="i386:x86_64"@},state="running"@}]]
-list-thread-groups --available
^done,groups=[@{id="17",type="process",pid="yyy",num_children="2",cores=[1,2]@}]
-list-thread-groups --available --recurse 1
*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0",
frame=@{addr="0x080484ed",func="main",args=[@{name="argc",value="1"@},
@{name="argv",value="0xbfb60364"@}],file="myprog.c",
-fullname="/home/nickrob/myprog.c",line="73"@}
+fullname="/home/nickrob/myprog.c",line="73",arch="i386:x86_64"@}
(gdb)
@end smallexample
Check that the target descriptions dynamically created by @value{GDBN}
equal the descriptions created from XML files found in @var{dir}.
+@anchor{maint check libthread-db}
+@kindex maint check libthread-db
+@item maint check libthread-db
+Run integrity checks on the current inferior's thread debugging
+library. This exercises all @code{libthread_db} functionality used by
+@value{GDBN} on GNU/Linux systems, and by extension also exercises the
+@code{proc_service} functions provided by @value{GDBN} that
+@code{libthread_db} uses. Note that parts of the test may be skipped
+on some platforms when debugging core files.
+
@kindex maint print dummy-frames
@item maint print dummy-frames
Prints the contents of @value{GDBN}'s internal dummy-frame stack.
memory will be used. Setting it to zero disables caching, which will
slow down @value{GDBN} startup, but reduce memory consumption.
+@kindex maint set dwarf unwinders
+@kindex maint show dwarf unwinders
+@item maint set dwarf unwinders
+@itemx maint show dwarf unwinders
+Control use of the DWARF frame unwinders.
+
+@cindex DWARF frame unwinders
+Many targets that support DWARF debugging use @value{GDBN}'s DWARF
+frame unwinders to build the backtrace. Many of these targets will
+also have a second mechanism for building the backtrace for use in
+cases where DWARF information is not available, this second mechanism
+is often an analysis of a function's prologue.
+
+In order to extend testing coverage of the second level stack
+unwinding mechanisms it is helpful to be able to disable the DWARF
+stack unwinders, this can be done with this switch.
+
+In normal use of @value{GDBN} disabling the DWARF unwinders is not
+advisable, there are cases that are better handled through DWARF than
+prologue analysis, and the debug experience is likely to be better
+with the DWARF frame unwinders enabled.
+
+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 profile
@kindex maint show profile
@cindex profiling GDB
@end enumerate
@end table
+@kindex maint set check-libthread-db
+@kindex maint show check-libthread-db
+@item maint set check-libthread-db [on|off]
+@itemx maint show check-libthread-db
+Control whether @value{GDBN} should run integrity checks on inferior
+specific thread debugging libraries as they are loaded. The default
+is not to perform such checks. If any check fails @value{GDBN} will
+unload the library and continue searching for a suitable candidate as
+described in @ref{set libthread-db-search-path}. For more information
+about the tests, see @ref{maint check libthread-db}.
+
@kindex maint space
@cindex memory used by commands
@item maint space @var{value}
@item int8
@itemx int16
+@itemx int24
@itemx int32
@itemx int64
@itemx int128
@item uint8
@itemx uint16
+@itemx uint24
@itemx uint32
@itemx uint64
@itemx uint128
it should contain registers @samp{v0} through @samp{v31}, @samp{fpsr},
and @samp{fpcr}.
+The @samp{org.gnu.gdb.aarch64.sve} feature is optional. If present,
+it should contain registers @samp{z0} through @samp{z31}, @samp{p0}
+through @samp{p15}, @samp{ffr} and @samp{vg}.
+
@node ARC Features
@subsection ARC Features
@cindex target descriptions, ARC Features
@format
@c man begin SYNOPSIS gcore
-gcore [-a] [-o @var{filename}] @var{pid}
+gcore [-a] [-o @var{prefix}] @var{pid1} [@var{pid2}...@var{pidN}]
@c man end
@end format
@c man begin DESCRIPTION gcore
-Generate a core dump of a running program with process ID @var{pid}.
-Produced file is equivalent to a kernel produced core file as if the process
-crashed (and if @kbd{ulimit -c} were used to set up an appropriate core dump
-limit). Unlike after a crash, after @command{gcore} the program remains
-running without any change.
+Generate core dumps of one or more running programs with process IDs
+@var{pid1}, @var{pid2}, etc. A core file produced by @command{gcore}
+is equivalent to one produced by the kernel when the process crashes
+(and when @kbd{ulimit -c} was used to set up an appropriate core dump
+limit). However, unlike after a crash, after @command{gcore} finishes
+its job the program remains running without any change.
@c man end
@c man begin OPTIONS gcore
enable @code{dump-excluded-mappings} (@pxref{set
dump-excluded-mappings}).
-@item -o @var{filename}
-The optional argument
-@var{filename} specifies the file name where to put the core dump.
-If not specified, the file name defaults to @file{core.@var{pid}},
-where @var{pid} is the running program process ID.
+@item -o @var{prefix}
+The optional argument @var{prefix} specifies the prefix to be used
+when composing the file names of the core dumps. The file name is
+composed as @file{@var{prefix}.@var{pid}}, where @var{pid} is the
+process ID of the running program being analyzed by @command{gcore}.
+If not specified, @var{prefix} defaults to @var{gcore}.
@end table
@c man end