(such as wildcard expansion or variable substitution) in describing
the arguments.
In Unix systems, you can control which shell is used with the
-@code{SHELL} environment variable.
-@xref{Arguments, ,Your Program's Arguments}.
+@code{SHELL} environment variable. If you do not define @code{SHELL},
+@value{GDBN} uses the default shell (@file{/bin/sh}). You can disable
+use of any shell with the @code{set startup-with-shell} command (see
+below for details).
@item The @emph{environment.}
Your program normally inherits its environment from @value{GDBN}, but you can
This command is available when debugging locally on most targets, excluding
@sc{djgpp}, Cygwin, MS Windows, and QNX Neutrino.
+@kindex set startup-with-shell
+@item set startup-with-shell
+@itemx set startup-with-shell on
+@itemx set startup-with-shell off
+@itemx show set startup-with-shell
+On Unix systems, by default, if a shell is available on your target,
+@value{GDBN}) uses it to start your program. Arguments of the
+@code{run} command are passed to the shell, which does variable
+substitution, expands wildcard characters and performs redirection of
+I/O. In some circumstances, it may be useful to disable such use of a
+shell, for example, when debugging the shell itself or diagnosing
+startup failures such as:
+
+@smallexample
+(@value{GDBP}) run
+Starting program: ./a.out
+During startup program terminated with signal SIGSEGV, Segmentation fault.
+@end smallexample
+
+@noindent
+which indicates the shell or the wrapper specified with
+@samp{exec-wrapper} crashed, not your program. Most often, this is
+caused by something odd in your shell's non-interactive mode
+initialization file---such as @file{.cshrc} for C-shell,
+$@file{.zshenv} for the Z shell, or the file specified in the
+@samp{BASH_ENV} environment variable for BASH.
+
@kindex set disable-randomization
@item set disable-randomization
@itemx set disable-randomization on
@end table
@emph{Warning:} On Unix systems, @value{GDBN} runs your program using
-the shell indicated
-by your @code{SHELL} environment variable if it exists (or
-@code{/bin/sh} if not). If your @code{SHELL} variable names a shell
-that runs an initialization file---such as @file{.cshrc} for C-shell, or
-@file{.bashrc} for BASH---any variables you set in that file affect
-your program. You may wish to move setting of environment variables to
-files that are only run when you sign on, such as @file{.login} or
-@file{.profile}.
+the shell indicated by your @code{SHELL} environment variable if it
+exists (or @code{/bin/sh} if not). If your @code{SHELL} variable
+names a shell that runs an initialization file when started
+non-interactively---such as @file{.cshrc} for C-shell, $@file{.zshenv}
+for the Z shell, or the file specified in the @samp{BASH_ENV}
+environment variable for BASH---any variables you set in that file
+affect your program. You may wish to move setting of environment
+variables to files that are only run when you sign on, such as
+@file{.login} or @file{.profile}.
@node Working Directory
@section Your Program's Working Directory
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
@code{add-symbol-file} command any number of times; the new symbol data
-thus read keeps adding to the old. To discard all old symbol data
-instead, use the @code{symbol-file} command without any arguments.
+thus read is kept in addition to the old.
+
+Changes can be reverted using the command @code{remove-symbol-file}.
@cindex relocatable object files, reading symbols from
@cindex object files, relocatable, reading symbols from
@code{add-symbol-file} does not repeat if you press @key{RET} after using it.
+@kindex remove-symbol-file
+@item remove-symbol-file @var{filename}
+@item remove-symbol-file -a @var{address}
+Remove a symbol file added via the @code{add-symbol-file} command. The
+file to remove can be identified by its @var{filename} or by an @var{address}
+that lies within the boundaries of this symbol file in memory. Example:
+
+@smallexample
+(gdb) add-symbol-file /home/user/gdb/mylib.so 0x7ffff7ff9480
+add symbol table from file "/home/user/gdb/mylib.so" at
+ .text_addr = 0x7ffff7ff9480
+(y or n) y
+Reading symbols from /home/user/gdb/mylib.so...done.
+(gdb) remove-symbol-file -a 0x7ffff7ff9480
+Remove symbol table from file "/home/user/gdb/mylib.so"? (y or n) y
+(gdb)
+@end smallexample
+
+
+@code{remove-symbol-file} does not repeat if you press @key{RET} after using it.
+
@kindex add-symbol-file-from-memory
@cindex @code{syscall DSO}
@cindex load symbols from memory
@item set debug symtab-create
@cindex symbol table creation
Turns on or off display of debugging messages related to symbol table creation.
-The default is off.
+The default is 0 (off).
+A value of 1 provides basic information.
+A value greater than 1 provides more verbose information.
@item show debug symtab-create
Show the current state of symbol table creation debugging.
@item set debug target
@item gdb.COMPLETE_SYMBOL
This constant means that completion should be done using symbol names
as the source.
+
+@findex COMPLETE_EXPRESSION
+@findex gdb.COMPLETE_EXPRESSION
+@item gdb.COMPLETE_EXPRESSION
+This constant means that completion should be done on expressions.
+Often this means completing on symbol names, but some language
+parsers also have support for completing on field names.
@end table
The following code snippet shows how a trivial CLI command can be
Python code can manipulate breakpoints via the @code{gdb.Breakpoint}
class.
-@defun Breakpoint.__init__ (spec @r{[}, type @r{[}, wp_class @r{[},internal@r{]]]})
-Create a new breakpoint. @var{spec} is a string naming the
-location of the breakpoint, or an expression that defines a
-watchpoint. The contents can be any location recognized by the
-@code{break} command, or in the case of a watchpoint, by the @code{watch}
-command. The optional @var{type} denotes the breakpoint to create
-from the types defined later in this chapter. This argument can be
-either: @code{gdb.BP_BREAKPOINT} or @code{gdb.BP_WATCHPOINT}. @var{type}
-defaults to @code{gdb.BP_BREAKPOINT}. The optional @var{internal} argument
-allows the breakpoint to become invisible to the user. The breakpoint
-will neither be reported when created, nor will it be listed in the
-output from @code{info breakpoints} (but will be listed with the
-@code{maint info breakpoints} command). The optional @var{wp_class}
-argument defines the class of watchpoint to create, if @var{type} is
-@code{gdb.BP_WATCHPOINT}. If a watchpoint class is not provided, it is
-assumed to be a @code{gdb.WP_WRITE} class.
+@defun Breakpoint.__init__ (spec @r{[}, type @r{[}, wp_class @r{[},internal @r{[},temporary@r{]]]]})
+Create a new breakpoint. @var{spec} is a string naming the location
+of the breakpoint, or an expression that defines a watchpoint. The
+contents can be any location recognized by the @code{break} command,
+or in the case of a watchpoint, by the @code{watch} command. The
+optional @var{type} denotes the breakpoint to create from the types
+defined later in this chapter. This argument can be either:
+@code{gdb.BP_BREAKPOINT} or @code{gdb.BP_WATCHPOINT}. @var{type}
+defaults to @code{gdb.BP_BREAKPOINT}. The optional @var{internal}
+argument allows the breakpoint to become invisible to the user. The
+breakpoint will neither be reported when created, nor will it be
+listed in the output from @code{info breakpoints} (but will be listed
+with the @code{maint info breakpoints} command). The optional
+@var{temporary} argument makes the breakpoint a temporary breakpoint.
+Temporary breakpoints are deleted after they have been hit. Any
+further access to the Python breakpoint after it has been hit will
+result in a runtime error (as that breakpoint has now been
+automatically deleted). The optional @var{wp_class} argument defines
+the class of watchpoint to create, if @var{type} is
+@code{gdb.BP_WATCHPOINT}. If a watchpoint class is not provided, it
+is assumed to be a @code{gdb.WP_WRITE} class.
@end defun
@defun Breakpoint.stop (self)
attribute is not writable.
@end defvar
+@defvar Breakpoint.temporary
+This attribute indicates whether the breakpoint was created as a
+temporary breakpoint. Temporary breakpoints are automatically deleted
+after that breakpoint has been hit. Access to this attribute, and all
+other attributes and functions other than the @code{is_valid}
+function, will result in an error after the breakpoint has been hit
+(as it has been automatically deleted). This attribute is not
+writable.
+@end defvar
+
The available types are represented by constants defined in the @code{gdb}
module:
This section documents @sc{gdb/mi} commands for manipulating
catchpoints.
+@menu
+* Shared Library GDB/MI Catchpoint Commands::
+* Ada Exception GDB/MI Catchpoint Commands::
+@end menu
+
+@node Shared Library GDB/MI Catchpoint Commands
+@subsection Shared Library @sc{gdb/mi} Catchpoints
+
@subheading The @code{-catch-load} Command
@findex -catch-load
(gdb)
@end smallexample
+@node Ada Exception GDB/MI Catchpoint Commands
+@subsection Ada Exception @sc{gdb/mi} Catchpoints
+
+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
+
+@subsubheading Synopsis
+
+@smallexample
+ -catch-assert [ -c @var{condition}] [ -d ] [ -t ]
+@end smallexample
+
+Add a catchpoint for failed Ada assertions.
+
+The possible optional parameters for this command are:
+
+@table @samp
+@item -c @var{condition}
+Make the catchpoint conditional on @var{condition}.
+@item -d
+Create a disabled catchpoint.
+@item -t
+Create a temporary catchpoint.
+@end table
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{catch assert}.
+
+@subsubheading Example
+
+@smallexample
+-catch-assert
+^done,bkptno="5",bkpt=@{number="5",type="breakpoint",disp="keep",
+enabled="y",addr="0x0000000000404888",what="failed Ada assertions",
+thread-groups=["i1"],times="0",
+original-location="__gnat_debug_raise_assert_failure"@}
+(gdb)
+@end smallexample
+
+@subheading The @code{-catch-exception} Command
+@findex -catch-exception
+
+@subsubheading Synopsis
+
+@smallexample
+ -catch-exception [ -c @var{condition}] [ -d ] [ -e @var{exception-name} ]
+ [ -t ] [ -u ]
+@end smallexample
+
+Add a catchpoint stopping when Ada exceptions are raised.
+By default, the command stops the program when any Ada exception
+gets raised. But it is also possible, by using some of the
+optional parameters described below, to create more selective
+catchpoints.
+
+The possible optional parameters for this command are:
+
+@table @samp
+@item -c @var{condition}
+Make the catchpoint conditional on @var{condition}.
+@item -d
+Create a disabled catchpoint.
+@item -e @var{exception-name}
+Only stop when @var{exception-name} is raised. This option cannot
+be used combined with @samp{-u}.
+@item -t
+Create a temporary catchpoint.
+@item -u
+Stop only when an unhandled exception gets raised. This option
+cannot be used combined with @samp{-e}.
+@end table
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} commands are @samp{catch exception}
+and @samp{catch exception unhandled}.
+
+@subsubheading Example
+
+@smallexample
+-catch-exception -e Program_Error
+^done,bkptno="4",bkpt=@{number="4",type="breakpoint",disp="keep",
+enabled="y",addr="0x0000000000404874",
+what="`Program_Error' Ada exception", thread-groups=["i1"],
+times="0",original-location="__gnat_debug_raise_exception"@}
+(gdb)
+@end smallexample
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Program Context
@end smallexample
@noindent
-Here, the values of @code{lang} can be @code{@{"C" | "C++" | "Java"@}}.
+Here, the value of @code{lang} is the language name, which can be
+found in @ref{Supported Languages}.
Note that the output of the @code{-var-list-children} command also
includes those expressions, so the @code{-var-info-expression} command
projects / binutils-gdb.git / blobdiff