@cindex shell escape
@item shell @var{command-string}
@itemx !@var{command-string}
-Invoke a standard shell to execute @var{command-string}.
+Invoke a shell to execute @var{command-string}.
Note that no space is needed between @code{!} and @var{command-string}.
On GNU and Unix systems, the environment variable @env{SHELL}, if it
exists, determines which shell to run. Otherwise @value{GDBN} uses
@file{cmd.exe} on MS-Windows, @file{COMMAND.COM} on MS-DOS, etc.).
@end table
+You may also invoke shell commands from expressions, using the
+@code{$_shell} convenience function. @xref{$_shell convenience
+function}.
+
The utility @code{make} is often needed in development environments.
You do not have to use the @code{shell} command for this purpose in
@value{GDBN}:
You can now simply switch focus to inferior 2 and run it.
+@anchor{remove_inferiors_cli}
@kindex remove-inferiors
@item remove-inferiors @var{infno}@dots{}
Removes the inferior or inferiors @var{infno}@dots{}. It is not
Setting @var{number-of-elements} to @code{unlimited} or zero means
that the number of elements to print is unlimited.
+When printing very large arrays, whose size is greater than
+@code{max-value-size} (@pxref{set max-value-size,,max-value-size}),
+if the @code{print elements} is set such that the size of the elements
+being printed is less than or equal to @code{max-value-size}, then
+@value{GDBN} will print the array (up to the @code{print elements} limit),
+and only @code{max-value-size} worth of data will be added into the value
+history (@pxref{Value History, ,Value History}).
+
@item show print elements
Display the number of elements of a large array that @value{GDBN} will print.
@table @code
-@item $_isvoid (@var{expr})
@findex $_isvoid@r{, convenience function}
+@item $_isvoid (@var{expr})
Return one if the expression @var{expr} is @code{void}. Otherwise it
returns zero.
$4 = 1
@end smallexample
-@item $_gdb_setting_str (@var{setting})
@findex $_gdb_setting_str@r{, convenience function}
+@item $_gdb_setting_str (@var{setting})
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}).
(@value{GDBP})
@end smallexample
-@item $_gdb_setting (@var{setting})
@findex $_gdb_setting@r{, convenience function}
+@item $_gdb_setting (@var{setting})
Return the value of the @value{GDBN} @var{setting}.
The type of the returned value depends on the setting.
are returned as string values.
-@item $_gdb_maint_setting_str (@var{setting})
@findex $_gdb_maint_setting_str@r{, convenience function}
+@item $_gdb_maint_setting_str (@var{setting})
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}
+@item $_gdb_maint_setting (@var{setting})
Like the @code{$_gdb_setting} function, but works with
@code{maintenance set} variables.
+@anchor{$_shell convenience function}
+@findex $_shell@r{, convenience function}
+@item $_shell (@var{command-string})
+
+Invoke a shell to execute @var{command-string}. @var{command-string}
+must be a string. The shell runs on the host machine, the machine
+@value{GDBN} is running on. Returns the command's exit status. On
+Unix systems, a command which exits with a zero exit status has
+succeeded, and non-zero exit status indicates failure. When a command
+terminates on a fatal signal whose number is @var{N}, @value{GDBN}
+uses the value 128+@var{N} as the exit status, as is standard in Unix
+shells. Note that @var{N} is a host signal number, not a target
+signal number. If you're native debugging, they will be the same, but
+if cross debugging, the host vs target signal numbers may be
+completely unrelated. Please consult your host operating system's
+documentation for the mapping between host signal numbers and signal
+names. The shell to run is determined in the same way as for the
+@code{shell} command. @xref{Shell Commands, ,Shell Commands}.
+
+@smallexample
+(@value{GDBP}) print $_shell("true")
+$1 = 0
+(@value{GDBP}) print $_shell("false")
+$2 = 1
+(@value{GDBP}) p $_shell("echo hello")
+hello
+$3 = 0
+(@value{GDBP}) p $_shell("foobar")
+bash: line 1: foobar: command not found
+$4 = 127
+@end smallexample
+
+This may also be useful in breakpoint conditions. For example:
+
+@smallexample
+(@value{GDBP}) break function if $_shell("some command") == 0
+@end smallexample
+
+In this scenario, you'll want to make sure that the shell command you
+run in the breakpoint condition takes the least amount of time
+possible. For example, avoid running a command that may block
+indefinitely, or that sleeps for a while before exiting. Prefer a
+command or script which analyzes some state and exits immediately.
+This is important because the debugged program stops for the
+breakpoint every time, and then @value{GDBN} evaluates the breakpoint
+condition. If the condition is false, the program is re-resumed
+transparently, without informing you of the stop. A quick shell
+command thus avoids significantly slowing down the debugged program
+unnecessarily.
+
+Note: unlike the @code{shell} command, the @code{$_shell} convenience
+function does not affect the @code{$_shell_exitcode} and
+@code{$_shell_exitsignal} convenience variables.
+
@end table
The following functions require @value{GDBN} to be configured with
@table @code
-@item $_memeq(@var{buf1}, @var{buf2}, @var{length})
@findex $_memeq@r{, convenience function}
+@item $_memeq(@var{buf1}, @var{buf2}, @var{length})
Returns one if the @var{length} bytes at the addresses given by
@var{buf1} and @var{buf2} are equal.
Otherwise it returns zero.
-@item $_regex(@var{str}, @var{regex})
@findex $_regex@r{, convenience function}
+@item $_regex(@var{str}, @var{regex})
Returns one if the string @var{str} matches the regular expression
@var{regex}. Otherwise it returns zero.
The syntax of the regular expression is that specified by @code{Python}'s
regular expression support.
-@item $_streq(@var{str1}, @var{str2})
@findex $_streq@r{, convenience function}
+@item $_streq(@var{str1}, @var{str2})
Returns one if the strings @var{str1} and @var{str2} are equal.
Otherwise it returns zero.
-@item $_strlen(@var{str})
@findex $_strlen@r{, convenience function}
+@item $_strlen(@var{str})
Returns the length of string @var{str}.
-@item $_caller_is(@var{name}@r{[}, @var{number_of_frames}@r{]})
@findex $_caller_is@r{, convenience function}
+@item $_caller_is(@var{name}@r{[}, @var{number_of_frames}@r{]})
Returns one if the calling function's name is equal to @var{name}.
Otherwise it returns zero.
$1 = 1
@end smallexample
-@item $_caller_matches(@var{regexp}@r{[}, @var{number_of_frames}@r{]})
@findex $_caller_matches@r{, convenience function}
+@item $_caller_matches(@var{regexp}@r{[}, @var{number_of_frames}@r{]})
Returns one if the calling function's name matches the regular expression
@var{regexp}. Otherwise it returns zero.
it is the number of frames up in the stack to look.
The default is 1.
-@item $_any_caller_is(@var{name}@r{[}, @var{number_of_frames}@r{]})
@findex $_any_caller_is@r{, convenience function}
+@item $_any_caller_is(@var{name}@r{[}, @var{number_of_frames}@r{]})
Returns one if any calling function's name is equal to @var{name}.
Otherwise it returns zero.
by @var{number_of_frames}, whereas @code{$_caller_is} only checks the
frame specified by @var{number_of_frames}.
-@item $_any_caller_matches(@var{regexp}@r{[}, @var{number_of_frames}@r{]})
@findex $_any_caller_matches@r{, convenience function}
+@item $_any_caller_matches(@var{regexp}@r{[}, @var{number_of_frames}@r{]})
Returns one if any calling function's name matches the regular expression
@var{regexp}. Otherwise it returns zero.
by @var{number_of_frames}, whereas @code{$_caller_matches} only checks the
frame specified by @var{number_of_frames}.
-@item $_as_string(@var{value})
@findex $_as_string@r{, convenience function}
+@item $_as_string(@var{value})
Return the string representation of @var{value}.
This function is useful to obtain the textual label (enumerator) of an
Visiting node of type NODE_INTEGER
@end smallexample
-@item $_cimag(@var{value})
-@itemx $_creal(@var{value})
@findex $_cimag@r{, convenience function}
@findex $_creal@r{, convenience function}
+@item $_cimag(@var{value})
+@itemx $_creal(@var{value})
Return the imaginary (@code{$_cimag}) or real (@code{$_creal}) part of
the complex number @var{value}.
@value{GDBN} to try and allocate an overly large amount of memory.
@table @code
+@anchor{set max-value-size}
@kindex set max-value-size
@item set max-value-size @var{bytes}
@itemx set max-value-size unlimited
subroutines:
@table @code
-@item set_debug_traps
@findex set_debug_traps
+@item set_debug_traps
@cindex remote serial stub, initialization
This routine arranges for @code{handle_exception} to run when your
program stops. You must call this subroutine explicitly in your
program's startup code.
-@item handle_exception
@findex handle_exception
+@item handle_exception
@cindex remote serial stub, main routine
This is the central workhorse, but your program never calls it
explicitly---the setup code arranges for @code{handle_exception} to
serial port.
@table @code
-@item int getDebugChar()
@findex getDebugChar
+@item int getDebugChar()
Write this subroutine to read a single character from the serial port.
It may be identical to @code{getchar} for your target system; a
different name is used to allow you to distinguish the two if you wish.
-@item void putDebugChar(int)
@findex putDebugChar
+@item void putDebugChar(int)
Write this subroutine to write a single character to the serial port.
It may be identical to @code{putchar} for your target system; a
different name is used to allow you to distinguish the two if you wish.
Other routines you need to supply are:
@table @code
-@item void exceptionHandler (int @var{exception_number}, void *@var{exception_address})
@findex exceptionHandler
+@item void exceptionHandler (int @var{exception_number}, void *@var{exception_address})
Write this function to install @var{exception_address} in the exception
handling tables. You need to do this because the stub does not have any
way of knowing what the exception handling tables on your target system
@sc{sparc} and 68k stubs are able to mask interrupts themselves without
help from @code{exceptionHandler}.
-@item void flush_i_cache()
@findex flush_i_cache
+@item void flush_i_cache()
On @sc{sparc} and @sc{sparclite} only, write this subroutine to flush the
instruction cache, if any, on your target machine. If there is no
instruction cache, this subroutine may be a no-op.
You must also make sure this library routine is available:
@table @code
-@item void *memset(void *, int, int)
@findex memset
+@item void *memset(void *, int, int)
This is the standard library function @code{memset} that sets an area of
memory to a known value. If you have one of the free versions of
@code{libc.a}, @code{memset} can be found there; otherwise, you must
The synchronous operation was successful, @code{@var{results}} are the return
values.
-@item "^running"
@findex ^running
+@item "^running"
This result record is equivalent to @samp{^done}. Historically, it
was output instead of @samp{^done} if the command has resumed the
target. This behaviour is maintained for backward compatibility, but
identically and rely on the @samp{*running} output record to determine
which threads are resumed.
-@item "^connected"
@findex ^connected
+@item "^connected"
@value{GDBN} has connected to a remote target.
-@item "^error" "," "msg=" @var{c-string} [ "," "code=" @var{c-string} ]
@findex ^error
+@item "^error" "," "msg=" @var{c-string} [ "," "code=" @var{c-string} ]
The operation failed. The @code{msg=@var{c-string}} variable contains
the corresponding error message.
Indicates that the command causing the error does not exist.
@end table
-@item "^exit"
@findex ^exit
+@item "^exit"
@value{GDBN} has terminated.
@end table
This section documents @sc{gdb/mi} commands for manipulating
breakpoints.
-@subheading The @code{-break-after} Command
@findex -break-after
+@subheading The @code{-break-after} Command
@subsubheading Synopsis
@end smallexample
@ignore
-@subheading The @code{-break-catch} Command
@findex -break-catch
+@subheading The @code{-break-catch} Command
@end ignore
-@subheading The @code{-break-commands} Command
@findex -break-commands
+@subheading The @code{-break-commands} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-break-condition} Command
@findex -break-condition
+@subheading The @code{-break-condition} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-break-delete} Command
@findex -break-delete
+@subheading The @code{-break-delete} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-break-disable} Command
@findex -break-disable
+@subheading The @code{-break-disable} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-break-enable} Command
@findex -break-enable
+@subheading The @code{-break-enable} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-break-info} Command
@findex -break-info
+@subheading The @code{-break-info} Command
@subsubheading Synopsis
@subsubheading Example
N.A.
-@subheading The @code{-break-insert} Command
@findex -break-insert
@anchor{-break-insert}
+@subheading The @code{-break-insert} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-dprintf-insert} Command
@findex -dprintf-insert
+@subheading The @code{-dprintf-insert} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-break-list} Command
@findex -break-list
+@subheading The @code{-break-list} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-break-passcount} Command
@findex -break-passcount
+@subheading The @code{-break-passcount} Command
@subsubheading Synopsis
is not a tracepoint, error is emitted. This corresponds to CLI
command @samp{passcount}.
-@subheading The @code{-break-watch} Command
@findex -break-watch
+@subheading The @code{-break-watch} Command
@subsubheading Synopsis
@node Shared Library GDB/MI Catchpoint Commands
@subsection Shared Library @sc{gdb/mi} Catchpoints
-@subheading The @code{-catch-load} Command
@findex -catch-load
+@subheading The @code{-catch-load} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-catch-unload} Command
@findex -catch-unload
+@subheading The @code{-catch-unload} Command
@subsubheading Synopsis
The following @sc{gdb/mi} commands can be used to create catchpoints
that stop the execution when Ada exceptions are being raised.
-@subheading The @code{-catch-assert} Command
@findex -catch-assert
+@subheading The @code{-catch-assert} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-catch-exception} Command
@findex -catch-exception
+@subheading The @code{-catch-exception} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-catch-handlers} Command
@findex -catch-handlers
+@subheading The @code{-catch-handlers} Command
@subsubheading Synopsis
that stop the execution when C@t{++} exceptions are being throw, rethrown,
or caught.
-@subheading The @code{-catch-throw} Command
@findex -catch-throw
+@subheading The @code{-catch-throw} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-catch-rethrow} Command
@findex -catch-rethrow
+@subheading The @code{-catch-rethrow} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-catch-catch} Command
@findex -catch-catch
+@subheading The @code{-catch-catch} Command
@subsubheading Synopsis
@node GDB/MI Program Context
@section @sc{gdb/mi} Program Context
-@subheading The @code{-exec-arguments} Command
@findex -exec-arguments
+@subheading The @code{-exec-arguments} Command
@subsubheading Synopsis
@ignore
-@subheading The @code{-exec-show-arguments} Command
@findex -exec-show-arguments
+@subheading The @code{-exec-show-arguments} Command
@subsubheading Synopsis
@end ignore
-@subheading The @code{-environment-cd} Command
@findex -environment-cd
+@subheading The @code{-environment-cd} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-environment-directory} Command
@findex -environment-directory
+@subheading The @code{-environment-directory} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-environment-path} Command
@findex -environment-path
+@subheading The @code{-environment-path} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-environment-pwd} Command
@findex -environment-pwd
+@subheading The @code{-environment-pwd} Command
@subsubheading Synopsis
@section @sc{gdb/mi} Thread Commands
-@subheading The @code{-thread-info} Command
@findex -thread-info
+@subheading The @code{-thread-info} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-thread-list-ids} Command
@findex -thread-list-ids
+@subheading The @code{-thread-list-ids} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-thread-select} Command
@findex -thread-select
+@subheading The @code{-thread-select} Command
@subsubheading Synopsis
@node GDB/MI Ada Tasking Commands
@section @sc{gdb/mi} Ada Tasking Commands
-@subheading The @code{-ada-task-info} Command
@findex -ada-task-info
+@subheading The @code{-ada-task-info} Command
@subsubheading Synopsis
asynchronously with remote targets and this interaction is mimicked in
other cases.
-@subheading The @code{-exec-continue} Command
@findex -exec-continue
+@subheading The @code{-exec-continue} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-exec-finish} Command
@findex -exec-finish
+@subheading The @code{-exec-finish} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-exec-interrupt} Command
@findex -exec-interrupt
+@subheading The @code{-exec-interrupt} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-exec-jump} Command
@findex -exec-jump
+@subheading The @code{-exec-jump} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-exec-next} Command
@findex -exec-next
+@subheading The @code{-exec-next} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-exec-next-instruction} Command
@findex -exec-next-instruction
+@subheading The @code{-exec-next-instruction} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-exec-return} Command
@findex -exec-return
+@subheading The @code{-exec-return} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-exec-run} Command
@findex -exec-run
+@subheading The @code{-exec-run} Command
@subsubheading Synopsis
@c @subheading -exec-signal
-@subheading The @code{-exec-step} Command
@findex -exec-step
+@subheading The @code{-exec-step} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-exec-step-instruction} Command
@findex -exec-step-instruction
+@subheading The @code{-exec-step-instruction} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-exec-until} Command
@findex -exec-until
+@subheading The @code{-exec-until} Command
@subsubheading Synopsis
@node GDB/MI Stack Manipulation
@section @sc{gdb/mi} Stack Manipulation Commands
-@subheading The @code{-enable-frame-filters} Command
@findex -enable-frame-filters
+@subheading The @code{-enable-frame-filters} Command
@smallexample
-enable-frame-filters
Note that if Python support has not been compiled into @value{GDBN},
this command will still succeed (and do nothing).
-@subheading The @code{-stack-info-frame} Command
@findex -stack-info-frame
+@subheading The @code{-stack-info-frame} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-stack-info-depth} Command
@findex -stack-info-depth
+@subheading The @code{-stack-info-depth} Command
@subsubheading Synopsis
@end smallexample
@anchor{-stack-list-arguments}
-@subheading The @code{-stack-list-arguments} Command
@findex -stack-list-arguments
+@subheading The @code{-stack-list-arguments} Command
@subsubheading Synopsis
@anchor{-stack-list-frames}
-@subheading The @code{-stack-list-frames} Command
@findex -stack-list-frames
+@subheading The @code{-stack-list-frames} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-stack-list-locals} Command
@findex -stack-list-locals
@anchor{-stack-list-locals}
+@subheading The @code{-stack-list-locals} Command
@subsubheading Synopsis
@end smallexample
@anchor{-stack-list-variables}
-@subheading The @code{-stack-list-variables} Command
@findex -stack-list-variables
+@subheading The @code{-stack-list-variables} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-stack-select-frame} Command
@findex -stack-select-frame
+@subheading The @code{-stack-select-frame} Command
@subsubheading Synopsis
@subheading Description And Use of Operations on Variable Objects
-@subheading The @code{-enable-pretty-printing} Command
@findex -enable-pretty-printing
+@subheading The @code{-enable-pretty-printing} Command
@smallexample
-enable-pretty-printing
Note that if Python support has not been compiled into @value{GDBN},
this command will still succeed (and do nothing).
-@subheading The @code{-var-create} Command
@findex -var-create
+@subheading The @code{-var-create} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-var-delete} Command
@findex -var-delete
+@subheading The @code{-var-delete} Command
@subsubheading Synopsis
Returns an error if the object @var{name} is not found.
-@subheading The @code{-var-set-format} Command
@findex -var-set-format
+@subheading The @code{-var-set-format} Command
@subsubheading Synopsis
For a variable with children, the format is set only on the
variable itself, and the children are not affected.
-@subheading The @code{-var-show-format} Command
@findex -var-show-format
+@subheading The @code{-var-show-format} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-var-info-num-children} Command
@findex -var-info-num-children
+@subheading The @code{-var-info-num-children} Command
@subsubheading Synopsis
be available.
-@subheading The @code{-var-list-children} Command
@findex -var-list-children
+@subheading The @code{-var-list-children} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-var-info-type} Command
@findex -var-info-type
+@subheading The @code{-var-info-type} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-var-info-expression} Command
@findex -var-info-expression
+@subheading The @code{-var-info-expression} Command
@subsubheading Synopsis
includes those expressions, so the @code{-var-info-expression} command
is of limited use.
-@subheading The @code{-var-info-path-expression} Command
@findex -var-info-path-expression
+@subheading The @code{-var-info-path-expression} Command
@subsubheading Synopsis
^done,path_expr=((Base)c).m_size)
@end smallexample
-@subheading The @code{-var-show-attributes} Command
@findex -var-show-attributes
+@subheading The @code{-var-show-attributes} Command
@subsubheading Synopsis
@noindent
where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}.
-@subheading The @code{-var-evaluate-expression} Command
@findex -var-evaluate-expression
+@subheading The @code{-var-evaluate-expression} Command
@subsubheading Synopsis
Note that one must invoke @code{-var-list-children} for a variable
before the value of a child variable can be evaluated.
-@subheading The @code{-var-assign} Command
@findex -var-assign
+@subheading The @code{-var-assign} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-var-update} Command
@findex -var-update
+@subheading The @code{-var-update} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-var-set-frozen} Command
@findex -var-set-frozen
@anchor{-var-set-frozen}
+@subheading The @code{-var-set-frozen} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-var-set-update-range} command
@findex -var-set-update-range
@anchor{-var-set-update-range}
+@subheading The @code{-var-set-update-range} command
@subsubheading Synopsis
^done
@end smallexample
-@subheading The @code{-var-set-visualizer} command
@findex -var-set-visualizer
@anchor{-var-set-visualizer}
+@subheading The @code{-var-set-visualizer} command
@subsubheading Synopsis
@c @subsubheading Example
@c N.A.
-@subheading The @code{-data-disassemble} Command
@findex -data-disassemble
+@subheading The @code{-data-disassemble} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-data-evaluate-expression} Command
@findex -data-evaluate-expression
+@subheading The @code{-data-evaluate-expression} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-data-list-changed-registers} Command
@findex -data-list-changed-registers
+@subheading The @code{-data-list-changed-registers} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-data-list-register-names} Command
@findex -data-list-register-names
+@subheading The @code{-data-list-register-names} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-data-list-register-values} Command
@findex -data-list-register-values
+@subheading The @code{-data-list-register-values} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-data-read-memory} Command
@findex -data-read-memory
+@subheading The @code{-data-read-memory} Command
This command is deprecated, use @code{-data-read-memory-bytes} instead.
(gdb)
@end smallexample
-@subheading The @code{-data-read-memory-bytes} Command
@findex -data-read-memory-bytes
+@subheading The @code{-data-read-memory-bytes} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-data-write-memory-bytes} Command
@findex -data-write-memory-bytes
+@subheading The @code{-data-write-memory-bytes} Command
@subsubheading Synopsis
The commands defined in this section implement MI support for
tracepoints. For detailed introduction, see @ref{Tracepoints}.
-@subheading The @code{-trace-find} Command
@findex -trace-find
+@subheading The @code{-trace-find} Command
@subsubheading Synopsis
The corresponding @value{GDBN} command is @samp{tfind}.
-@subheading -trace-define-variable
@findex -trace-define-variable
+@subheading -trace-define-variable
@subsubheading Synopsis
The corresponding @value{GDBN} command is @samp{tvariable}.
-@subheading The @code{-trace-frame-collected} Command
@findex -trace-frame-collected
+@subheading The @code{-trace-frame-collected} Command
@subsubheading Synopsis
@subsubheading Example
-@subheading -trace-list-variables
@findex -trace-list-variables
+@subheading -trace-list-variables
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading -trace-save
@findex -trace-save
+@subheading -trace-save
@subsubheading Synopsis
The corresponding @value{GDBN} command is @samp{tsave}.
-@subheading -trace-start
@findex -trace-start
+@subheading -trace-start
@subsubheading Synopsis
The corresponding @value{GDBN} command is @samp{tstart}.
-@subheading -trace-status
@findex -trace-status
+@subheading -trace-status
@subsubheading Synopsis
The corresponding @value{GDBN} command is @samp{tstatus}.
-@subheading -trace-stop
@findex -trace-stop
+@subheading -trace-stop
@subsubheading Synopsis
@ignore
-@subheading The @code{-symbol-info-address} Command
@findex -symbol-info-address
+@subheading The @code{-symbol-info-address} Command
@subsubheading Synopsis
N.A.
-@subheading The @code{-symbol-info-file} Command
@findex -symbol-info-file
+@subheading The @code{-symbol-info-file} Command
@subsubheading Synopsis
N.A.
@end ignore
-@subheading The @code{-symbol-info-functions} Command
@findex -symbol-info-functions
@anchor{-symbol-info-functions}
+@subheading The @code{-symbol-info-functions} Command
@subsubheading Synopsis
@end group
@end smallexample
-@subheading The @code{-symbol-info-module-functions} Command
@findex -symbol-info-module-functions
@anchor{-symbol-info-module-functions}
+@subheading The @code{-symbol-info-module-functions} Command
@subsubheading Synopsis
@end group
@end smallexample
-@subheading The @code{-symbol-info-module-variables} Command
@findex -symbol-info-module-variables
@anchor{-symbol-info-module-variables}
+@subheading The @code{-symbol-info-module-variables} Command
@subsubheading Synopsis
@end group
@end smallexample
-@subheading The @code{-symbol-info-modules} Command
@findex -symbol-info-modules
@anchor{-symbol-info-modules}
+@subheading The @code{-symbol-info-modules} Command
@subsubheading Synopsis
@end group
@end smallexample
-@subheading The @code{-symbol-info-types} Command
@findex -symbol-info-types
@anchor{-symbol-info-types}
+@subheading The @code{-symbol-info-types} Command
@subsubheading Synopsis
@end group
@end smallexample
-@subheading The @code{-symbol-info-variables} Command
@findex -symbol-info-variables
@anchor{-symbol-info-variables}
+@subheading The @code{-symbol-info-variables} Command
@subsubheading Synopsis
@end smallexample
@ignore
-@subheading The @code{-symbol-info-line} Command
@findex -symbol-info-line
+@subheading The @code{-symbol-info-line} Command
@subsubheading Synopsis
N.A.
-@subheading The @code{-symbol-info-symbol} Command
@findex -symbol-info-symbol
+@subheading The @code{-symbol-info-symbol} Command
@subsubheading Synopsis
N.A.
-@subheading The @code{-symbol-list-functions} Command
@findex -symbol-list-functions
+@subheading The @code{-symbol-list-functions} Command
@subsubheading Synopsis
@end ignore
-@subheading The @code{-symbol-list-lines} Command
@findex -symbol-list-lines
+@subheading The @code{-symbol-list-lines} Command
@subsubheading Synopsis
@ignore
-@subheading The @code{-symbol-list-types} Command
@findex -symbol-list-types
+@subheading The @code{-symbol-list-types} Command
@subsubheading Synopsis
N.A.
-@subheading The @code{-symbol-list-variables} Command
@findex -symbol-list-variables
+@subheading The @code{-symbol-list-variables} Command
@subsubheading Synopsis
N.A.
-@subheading The @code{-symbol-locate} Command
@findex -symbol-locate
+@subheading The @code{-symbol-locate} Command
@subsubheading Synopsis
N.A.
-@subheading The @code{-symbol-type} Command
@findex -symbol-type
+@subheading The @code{-symbol-type} Command
@subsubheading Synopsis
This section describes the GDB/MI commands to specify executable file names
and to read in and obtain symbol table information.
-@subheading The @code{-file-exec-and-symbols} Command
@findex -file-exec-and-symbols
+@subheading The @code{-file-exec-and-symbols} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-file-exec-file} Command
@findex -file-exec-file
+@subheading The @code{-file-exec-file} Command
@subsubheading Synopsis
@ignore
-@subheading The @code{-file-list-exec-sections} Command
@findex -file-list-exec-sections
+@subheading The @code{-file-list-exec-sections} Command
@subsubheading Synopsis
@end ignore
-@subheading The @code{-file-list-exec-source-file} Command
@findex -file-list-exec-source-file
+@subheading The @code{-file-list-exec-source-file} Command
@subsubheading Synopsis
@end smallexample
+@findex -file-list-exec-source-files
@subheading The @code{-file-list-exec-source-files} Command
@kindex info sources
-@findex -file-list-exec-source-files
@subsubheading Synopsis
sources=[]@}]
@end smallexample
-@subheading The @code{-file-list-shared-libraries} Command
@findex -file-list-shared-libraries
+@subheading The @code{-file-list-shared-libraries} Command
@subsubheading Synopsis
@ignore
-@subheading The @code{-file-list-symbol-files} Command
@findex -file-list-symbol-files
+@subheading The @code{-file-list-symbol-files} Command
@subsubheading Synopsis
@end ignore
-@subheading The @code{-file-symbol-file} Command
@findex -file-symbol-file
+@subheading The @code{-file-symbol-file} Command
@subsubheading Synopsis
@section @sc{gdb/mi} Target Manipulation Commands
-@subheading The @code{-target-attach} Command
@findex -target-attach
+@subheading The @code{-target-attach} Command
@subsubheading Synopsis
@end smallexample
@ignore
-@subheading The @code{-target-compare-sections} Command
@findex -target-compare-sections
+@subheading The @code{-target-compare-sections} Command
@subsubheading Synopsis
@end ignore
-@subheading The @code{-target-detach} Command
@findex -target-detach
+@subheading The @code{-target-detach} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-target-disconnect} Command
@findex -target-disconnect
+@subheading The @code{-target-disconnect} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-target-download} Command
@findex -target-download
+@subheading The @code{-target-download} Command
@subsubheading Synopsis
@ignore
-@subheading The @code{-target-exec-status} Command
@findex -target-exec-status
+@subheading The @code{-target-exec-status} Command
@subsubheading Synopsis
N.A.
-@subheading The @code{-target-list-available-targets} Command
@findex -target-list-available-targets
+@subheading The @code{-target-list-available-targets} Command
@subsubheading Synopsis
N.A.
-@subheading The @code{-target-list-current-targets} Command
@findex -target-list-current-targets
+@subheading The @code{-target-list-current-targets} Command
@subsubheading Synopsis
N.A.
-@subheading The @code{-target-list-parameters} Command
@findex -target-list-parameters
+@subheading The @code{-target-list-parameters} Command
@subsubheading Synopsis
@subsubheading Example
N.A.
-@subheading The @code{-target-flash-erase} Command
@findex -target-flash-erase
+@subheading The @code{-target-flash-erase} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-target-select} Command
@findex -target-select
+@subheading The @code{-target-select} Command
@subsubheading Synopsis
@section @sc{gdb/mi} File Transfer Commands
-@subheading The @code{-target-file-put} Command
@findex -target-file-put
+@subheading The @code{-target-file-put} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-target-file-get} Command
@findex -target-file-get
+@subheading The @code{-target-file-get} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-target-file-delete} Command
@findex -target-file-delete
+@subheading The @code{-target-file-delete} Command
@subsubheading Synopsis
@node GDB/MI Ada Exceptions Commands
@section Ada Exceptions @sc{gdb/mi} Commands
-@subheading The @code{-info-ada-exceptions} Command
@findex -info-ada-exceptions
+@subheading The @code{-info-ada-exceptions} Command
@subsubheading Synopsis
about support for these capabilities. Similarly, it is also possible
to query @value{GDBN} about target support of certain features.
-@subheading The @code{-info-gdb-mi-command} Command
@cindex @code{-info-gdb-mi-command}
@findex -info-gdb-mi-command
+@subheading The @code{-info-gdb-mi-command} Command
@subsubheading Synopsis
^done,command=@{exists="true"@}
@end smallexample
-@subheading The @code{-list-features} Command
@findex -list-features
@cindex supported @sc{gdb/mi} features, list
+@subheading The @code{-list-features} Command
Returns a list of particular features of the MI protocol that
this version of gdb implements. A feature can be a command,
option (@pxref{GDB/MI Data Manipulation}).
@end ftable
-@subheading The @code{-list-target-features} Command
@findex -list-target-features
+@subheading The @code{-list-target-features} Command
Returns a list of particular features that are supported by the
target. Those features affect the permitted MI commands, but
@c @subheading -gdb-complete
-@subheading The @code{-gdb-exit} Command
@findex -gdb-exit
+@subheading The @code{-gdb-exit} Command
@subsubheading Synopsis
@ignore
-@subheading The @code{-exec-abort} Command
@findex -exec-abort
+@subheading The @code{-exec-abort} Command
@subsubheading Synopsis
@end ignore
-@subheading The @code{-gdb-set} Command
@findex -gdb-set
+@subheading The @code{-gdb-set} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-gdb-show} Command
@findex -gdb-show
+@subheading The @code{-gdb-show} Command
@subsubheading Synopsis
@c @subheading -gdb-source
-@subheading The @code{-gdb-version} Command
@findex -gdb-version
+@subheading The @code{-gdb-version} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-list-thread-groups} Command
@findex -list-thread-groups
+@subheading The @code{-list-thread-groups} Command
@subheading Synopsis
@{id="2",target-id="Thread 0xb7e14b90",cores=[2]@}]@},...]
@end smallexample
-@subheading The @code{-info-os} Command
@findex -info-os
+@subheading The @code{-info-os} Command
@subsubheading Synopsis
popup menu, but is needless clutter on the command line, and
@code{info os} omits it.)
-@subheading The @code{-add-inferior} Command
@findex -add-inferior
+@subheading The @code{-add-inferior} Command
@subheading Synopsis
^done,inferior="i3"
@end smallexample
-@subheading The @code{-interpreter-exec} Command
+@findex -remove-inferior
+@subheading The @code{-remove-inferior} Command
+
+@subsubheading Synopsis
+
+@smallexample
+-remove-inferior @var{inferior-id}
+@end smallexample
+
+Removes an inferior (@pxref{Inferiors Connections and Programs}).
+Only inferiors that have exited can be removed. The @var{inferior-id}
+is the inferior to be removed, and should be the same id string as
+returned by the @samp{-add-inferior} command.
+
+When an inferior is successfully removed a
+@code{=thread-group-removed} notification (@pxref{GDB/MI Async
+Records}) is emitted, the @var{id} field of which contains the
+@var{inferior-id} for the removed inferior.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{remove-inferiors}
+(@pxref{remove_inferiors_cli,,@samp{remove-inferiors}}).
+
+@subsubheading Example
+
+@smallexample
+(@value{GDBP})
+-remove-inferior i3
+=thread-group-removed,id="i3"
+^done
+@end smallexample
+
@findex -interpreter-exec
+@subheading The @code{-interpreter-exec} Command
@subheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-inferior-tty-set} Command
@findex -inferior-tty-set
+@subheading The @code{-inferior-tty-set} Command
@subheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-inferior-tty-show} Command
@findex -inferior-tty-show
+@subheading The @code{-inferior-tty-show} Command
@subheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-enable-timings} Command
@findex -enable-timings
+@subheading The @code{-enable-timings} Command
@subheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-complete} Command
@findex -complete
+@subheading The @code{-complete} Command
@subheading Synopsis
Each byte of register data is described by two hex digits. The bytes
with the register are transmitted in target byte order. The size of
each register and their position within the @samp{g} packet are
-determined by the @value{GDBN} internal gdbarch functions
-@code{DEPRECATED_REGISTER_RAW_SIZE} and @code{gdbarch_register_name}.
-
-When reading registers from a trace frame (@pxref{Analyze Collected
-Data,,Using the Collected Data}), the stub may also return a string of
-literal @samp{x}'s in place of the register data digits, to indicate
-that the corresponding register has not been collected, thus its value
-is unavailable. For example, for an architecture with 4 registers of
+determined by the target description (@pxref{Target Descriptions}); in
+the absence of a target description, this is done using code internal
+to @value{GDBN}; typically this is some customary register layout for
+the architecture in question.
+
+When reading registers, the stub may also return a string of literal
+@samp{x}'s in place of the register data digits, to indicate that the
+corresponding register's value is unavailable. For example, when
+reading registers from a trace frame (@pxref{Analyze Collected
+Data,,Using the Collected Data}), this means that the register has not
+been collected in the trace frame. When reading registers from a live
+program, this indicates that the stub has no means to access the
+register contents, even though the corresponding register is known to
+exist. Note that if a register truly does not exist on the target,
+then it is better to not include it in the target description in the
+first place.
+
+For example, for an architecture with 4 registers of
4 bytes each, the following reply indicates to @value{GDBN} that
-registers 0 and 2 have not been collected, while registers 1 and 3
-have been collected, and both have zero value:
+registers 0 and 2 are unavailable, while registers 1 and 3
+are available, and both have zero value:
@smallexample
-> @code{g}
projects / binutils-gdb.git / blobdiff