arguments. This is equivalent to @samp{shell make @var{make-args}}.
@end table
+@table @code
+@kindex pipe
+@kindex |
+@cindex send the output of a gdb command to a shell command
+@anchor{pipe}
+@item pipe [@var{command}] | @var{shell_command}
+@itemx | [@var{command}] | @var{shell_command}
+@itemx pipe -d @var{delim} @var{command} @var{delim} @var{shell_command}
+@itemx | -d @var{delim} @var{command} @var{delim} @var{shell_command}
+Executes @var{command} and sends its output to @var{shell_command}.
+Note that no space is needed around @code{|}.
+If no @var{command} is provided, the last command executed is repeated.
+
+In case the @var{command} contains a @code{|}, the option @code{-d @var{delim}}
+can be used to specify an alternate delimiter string @var{delim} that separates
+the @var{command} from the @var{shell_command}.
+
+Example:
+@smallexample
+@group
+(gdb) p var
+$1 = @{
+ black = 144,
+ red = 233,
+ green = 377,
+ blue = 610,
+ white = 987
+@}
+@end group
+@group
+(gdb) pipe p var|wc
+ 7 19 80
+(gdb) |p var|wc -l
+7
+@end group
+@group
+(gdb) p /x var
+$4 = @{
+ black = 0x90,
+ red = 0xe9,
+ green = 0x179,
+ blue = 0x262,
+ white = 0x3db
+@}
+(gdb) ||grep red
+ red => 0xe9,
+@end group
+@group
+(gdb) | -d ! echo this contains a | char\n ! sed -e 's/|/PIPE/'
+this contains a PIPE char
+(gdb) | -d xxx echo this contains a | char!\n xxx sed -e 's/|/PIPE/'
+this contains a PIPE char!
+(gdb)
+@end group
+@end smallexample
+@end table
+
+The convenience variables @code{$_shell_exitcode} and @code{$_shell_exitsignal}
+can be used to examine the exit status of the last shell command launched
+by @code{shell}, @code{make}, @code{pipe} and @code{|}.
+@xref{Convenience Vars,, Convenience Variables}.
+
@node Logging Output
@section Logging Output
@cindex logging @value{GDBN} output
@item set logging redirect [on|off]
By default, @value{GDBN} output will go to both the terminal and the logfile.
Set @code{redirect} if you want output to go only to the log file.
+@item set logging debugredirect [on|off]
+By default, @value{GDBN} debug output will go to both the terminal and the logfile.
+Set @code{debugredirect} if you want debug output to go only to the log file.
@kindex show logging
@item show logging
Show the current values of the logging settings.
@end table
+You can also redirect the output of a @value{GDBN} command to a
+shell command. @xref{pipe}.
@node Commands
@chapter @value{GDBN} Commands
short paragraph on how to use that command.
@kindex apropos
-@item apropos @var{args}
+@item apropos [-v] @var{regexp}
The @code{apropos} command searches through all of the @value{GDBN}
commands, and their documentation, for the regular expression specified in
-@var{args}. It prints out all matches found. For example:
+@var{args}. It prints out all matches found. The optional flag @samp{-v},
+which stands for @samp{verbose}, indicates to output the full documentation
+of the matching commands and highlight the parts of the documentation
+matching @var{regexp}. For example:
@smallexample
apropos alias
results in:
@smallexample
-@c @group
+@group
alias -- Define a new command that is an alias of an existing command
aliases -- Aliases of other commands
d -- Delete some breakpoints or auto-display expressions
del -- Delete some breakpoints or auto-display expressions
delete -- Delete some breakpoints or auto-display expressions
-@c @end group
+@end group
+@end smallexample
+
+@noindent
+while
+
+@smallexample
+apropos -v cut.*thread apply
+@end smallexample
+
+@noindent
+results in the below output, where @samp{cut for 'thread apply}
+is highlighted if styling is enabled.
+
+@smallexample
+@group
+taas -- Apply a command to all threads (ignoring errors
+and empty output).
+Usage: taas COMMAND
+shortcut for 'thread apply all -s COMMAND'
+
+tfaas -- Apply a command to all frames of all threads
+(ignoring errors and empty output).
+Usage: tfaas COMMAND
+shortcut for 'thread apply all -s frame apply all -s COMMAND'
+@end group
@end smallexample
@kindex complete
Contrast this with the @code{return} command (@pxref{Returning,
,Returning from a Function}).
+@kindex set print finish
+@kindex show print finish
+@item set print finish @r{[}on|off@r{]}
+@itemx show print finish
+By default the @code{finish} command will show the value that is
+returned by the function. This can be disabled using @code{set print
+finish off}. When disabled, the value is still entered into the value
+history (@pxref{Value History}), but not displayed.
+
@kindex until
@kindex u @r{(@code{until})}
@cindex run until specified location
@item show print frame-arguments
Show how the value of arguments should be displayed when printing a frame.
-@item set print raw frame-arguments on
+@item set print raw-frame-arguments on
Print frame arguments in raw, non pretty-printed, form.
-@item set print raw frame-arguments off
+@item set print raw-frame-arguments off
Print frame arguments in pretty-printed form, if there is a pretty-printer
for the value (@pxref{Pretty Printing}),
otherwise print the value in raw form.
This is the default.
-@item show print raw frame-arguments
+@item show print raw-frame-arguments
Show whether to print frame arguments in raw form.
@anchor{set print entry-values}
write scripts that work with different versions of @value{GDBN}
without errors caused by features unavailable in some of those
versions.
+
+@item $_shell_exitcode
+@itemx $_shell_exitsignal
+@vindex $_shell_exitcode@r{, convenience variable}
+@vindex $_shell_exitsignal@r{, convenience variable}
+@cindex shell command, exit code
+@cindex shell command, exit signal
+@cindex exit status of shell commands
+@value{GDBN} commands such as @code{shell} and @code{|} are launching
+shell commands. When a launched command terminates, @value{GDBN}
+automatically maintains the variables @code{$_shell_exitcode}
+and @code{$_shell_exitsignal} according to the exit status of the last
+launched command. These variables are set and used similarly to
+the variables @code{$_exitcode} and @code{$_exitsignal}.
+
@end table
@node Convenience Funs
@subsection Automatic symbol index cache
+@cindex 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
@table @code
+@kindex set index-cache
@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}
+@kindex show index-cache
@itemx show index-cache directory
Set/show the directory where index files will be saved.
(the default), @samp{bold}, and @samp{dim}.
@end table
+The @code{show style} command and its subcommands are styling
+a style name in their output using its own style.
+So, use @command{show style} to see the complete list of styles,
+their characteristics and the visual aspect of each style.
+
The style-able objects are:
@table @code
@item filename
Control the styling of addresses. These are managed with the
@code{set style address} family of commands. By default, this style's
foreground color is blue.
+
+@item title
+Control the styling of titles. These are managed with the
+@code{set style title} family of commands. By default, this style's
+intensity is bold. Commands are using the title style to improve
+the readibility of large output. For example, the commands
+@command{apropos} and @command{help} are using the title style
+for the command names.
+
+@item highlight
+Control the styling of highlightings. These are managed with the
+@code{set style highlight} family of commands. By default, this style's
+foreground color is red. Commands are using the highlight style to draw
+the user attention to some specific parts of their output. For example,
+the command @command{apropos -v REGEXP} uses the highlight style to
+mark the documentation parts matching @var{regexp}.
+
@end table
@node Numbers
(gdb)
@end smallexample
+@subheading The @code{-complete} Command
+@findex -complete
+
+@subheading Synopsis
+
+@smallexample
+-complete @var{command}
+@end smallexample
+
+Show a list of completions for partially typed CLI @var{command}.
+
+This command is intended for @sc{gdb/mi} frontends that cannot use two separate
+CLI and MI channels --- for example: because of lack of PTYs like on Windows or
+because @value{GDBN} is used remotely via a SSH connection.
+
+@subheading Result
+
+The result consists of two or three fields:
+
+@table @samp
+@item completion
+This field contains the completed @var{command}. If @var{command}
+has no known completions, this field is omitted.
+
+@item matches
+This field contains a (possibly empty) array of matches. It is always present.
+
+@item max_completions_reached
+This field contains @code{1} if number of known completions is above
+@code{max-completions} limit (@pxref{Completion}), otherwise it contains
+@code{0}. It is always present.
+
+@end table
+
+@subheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{complete}.
+
+@subheading Example
+
+@smallexample
+(gdb)
+-complete br
+^done,completion="break",
+ matches=["break","break-range"],
+ max_completions_reached="0"
+(gdb)
+-complete "b ma"
+^done,completion="b ma",
+ matches=["b madvise","b main"],max_completions_reached="0"
+(gdb)
+-complete "b push_b"
+^done,completion="b push_back(",
+ matches=[
+ "b A::push_back(void*)",
+ "b std::string::push_back(char)",
+ "b std::vector<int, std::allocator<int> >::push_back(int&&)"],
+ max_completions_reached="0"
+(gdb)
+-complete "nonexist"
+^done,matches=[],max_completions_reached="0"
+(gdb)
+
+@end smallexample
+
@node Annotations
@chapter @value{GDBN} Annotations
If a @var{filter} is passed, only the tests with @var{filter} in their
name will by ran.
-@kindex "maint info selftests"
+@kindex maint info selftests
@cindex self tests
@item maint info selftests
List the selftests compiled in to @value{GDBN}.
is also printed. For dynamically linked executables, the name of
executable or shared library containing the symbol is printed as well.
+@kindex maint test-settings
+@item maint test-settings set @var{kind}
+@itemx maint test-settings show @var{kind}
+These are representative commands for each @var{kind} of setting type
+@value{GDBN} supports. They are used by the testsuite for exercising
+the settings infrastructure.
@end table
The following command is useful for non-interactive invocations of
projects / deliverable / binutils-gdb.git / blobdiff