[RFC,4/5] Documentation changes for 'frame apply' and 'thread apply'
Commit Message
Documents the new commands
'frame apply'
faas
taas
tfaas
Documents the new argument -FLAGS... added to 'thread apply'
---
gdb/doc/gdb.texinfo | 215 +++++++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 212 insertions(+), 3 deletions(-)
Comments
> From: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> Cc: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> Date: Sat, 5 May 2018 21:28:03 +0200
>
> +@table @asis
Since all the @item's in this table use @code, it is better to say
@table @code
> +@item Flags @code{c} and @code{s} : error handling when applying @var{command}.
This is not a good way of formatting a table. I suggest to use this
instead:
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
@vode{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 errors are not printed.
@item v
The flag @code{v} increases the verbosity of the info displayed for
each thread.
@item q
The flag @code{q} (@samp{quiet}) decreases the verbosity.
@end @table
Flags @code{c} and @code{s} cannot be used together.
The default value of verbosity, 1, prints the per-inferior thread
number and the target system's thread ID. Under verbosity 0, no
thread info is printed.
> +@item tfaas @var{command}
> +Shortcut for @code{thread apply all -s frame apply all -s @var{COMMAND}}.
Any reason why -s should be specified twice?
> +The @var{flags} control what output to produce and how to handle
> +errors raised when applying @var{command} to a frame. @var{flags}
> +must start with a @code{-} directly followed by one or more letters in
> +@code{vqcs}.
I suggest to use here the same paradigm as shown above for "thread
apply".
> +Some frame information is printed before the output or error produced
> +by applying @var{command} to a frame. The printed frame information
> +@footnote{Note that the way the frame information is printed can be changed
> +using the @code{set backtrace} settings such as @code{set
> +filename-display}. @ref{Backtrace,,Backtraces}}
Please use @xref here, and leave 2 spaces between sentences. (And I'm
not sure it's a good idea to have cross-references in footnotes. Did
you make sure this produces reasonable results in the printed manual?)
> +Note that the command @code{tfaas @var{command}} applies @var{command}
> +on all frames of all threads. @ref{Threads,,Threads}
Ditto.
Thanks.
@@ -2933,7 +2933,7 @@ programs:
@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} | @code{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
@@ -3170,7 +3170,7 @@ threads.
@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{-flags@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
@@ -3179,6 +3179,53 @@ command to all threads in descending order, type @kbd{thread apply all
@var{command}}. To apply a command to all threads in ascending order,
type @kbd{thread apply all -ascending @var{command}}.
+The @var{flags} control what output to produce and how to handle
+errors raised when applying @var{command} to a thread. @var{flags}
+must start with a @code{-} directly followed by one or more letters in
+@code{vqcs}.
+
+@table @asis
+@item Flags @code{c} and @code{s} : error handling when applying @var{command}.
+By default, an error raised during the execution of a @var{command}
+will abort @code{thread apply}. If the flag @code{c} (continue) is
+given, the error will be printed and the execution of @code{thread
+apply} is continued. The flag @code{s} (silent) means to silently
+ignore a @var{command} execution that raises an error or produces an
+empty output. The flags @code{c} and @code{s} cannot be given
+simultaneously.
+
+@item Flags @code{v} and @code{q} : change thread information printed when applying @var{command}.
+@noindent
+Some thread information is printed before the output or error produced
+by applying @var{command} to a thread. The printed thread information
+is controlled by the verbosity. A flag @code{v} increases the
+verbosity, a flag @code{q} decreases the verbosity.
+
+At verbosity 1 (the default value), the per-inferior thread number and
+target system's thread id are printed. At verbosity 0, no thread info
+is printed.
+
+@end table
+
+@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.
+
+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
@@ -7300,6 +7347,7 @@ currently executing frame and describes it briefly, similar to the
* 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
@@ -7712,6 +7760,167 @@ accessible at the point of execution of the selected frame.
@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} ] [@var{-flags@dots{}}] @var{command}
+The @code{frame apply} command allows you to apply the named
+@var{command} to one or more frames@footnote{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 @ref{Backtrace,,Backtraces}}.
+
+@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.
+@end table
+
+
+@end table
+
+The @var{flags} control what output to produce and how to handle
+errors raised when applying @var{command} to a frame. @var{flags}
+must start with a @code{-} directly followed by one or more letters in
+@code{vqcs}.
+
+@table @asis
+@item Flags @code{c} and @code{s} : error handling when applying @var{command}.
+By default, an error raised during the execution of a @var{command}
+will abort @code{frame apply}. If the flag @code{c} (continue) is
+given, the error will be printed and the execution of @code{frame
+apply} is continued. The flag @code{s} (silent) means to silently
+ignore a @var{command} execution that raises an error or produces an
+empty output. The flags @code{c} and @code{s} cannot be given
+simultaneously.
+
+
+The following example shows how these flags 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
+
+@item Flags @code{v} and @code{q} : change frame information printed when applying @var{command}.
+@noindent
+Some frame information is printed before the output or error produced
+by applying @var{command} to a frame. The printed frame information
+@footnote{Note that the way the frame information is printed can be changed
+using the @code{set backtrace} settings such as @code{set
+filename-display}. @ref{Backtrace,,Backtraces}}
+is controlled by the verbosity. A flag @code{v} increases the
+verbosity, a flag @code{q} decreases the verbosity.
+
+At verbosity 2 (the default value), the location is printed 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
+
+At verbosity 3, the location and address is printed:
+
+@smallexample
+@group
+(gdb) frame apply all -v p $sp
+#0 0x565555b1 in some_function (i=5) at fun.c:4
+$6 = (void *) 0xffffd1e0
+#1 0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11
+$7 = (void *) 0xffffd1f0
+(gdb)
+@end group
+@end smallexample
+
+At verbosity 4, the source line and address is printed:
+@smallexample
+@group
+(gdb) frame apply all -vv p $sp
+#0 some_function (i=5) at fun.c:4
+4 printf ("value of i is %d\n", i);
+$8 = (void *) 0xffffd1e0
+#1 0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11
+11 some_function (j);
+$9 = (void *) 0xffffd1f0
+(gdb)
+@end group
+@end smallexample
+
+At verbosity 1, only the source line is printed:
+
+@smallexample
+@group
+(gdb) frame apply all -q p $sp
+4 printf ("value of i is %d\n", i);
+$10 = (void *) 0xffffd1e0
+0x565555fb 11 some_function (j);
+$11 = (void *) 0xffffd1f0
+(gdb)
+@end group
+@end smallexample
+
+At verbosity 0, no frame information is printed:
+@smallexample
+@group
+(gdb) frame apply all -qq p $sp
+$12 = (void *) 0xffffd1e0
+$13 = (void *) 0xffffd1f0
+(gdb)
+@end group
+@end smallexample
+
+@end table
+
+@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. @ref{Threads,,Threads}
+@end table
+
+
@node Frame Filter Management
@section Management of Frame Filters.
@cindex managing frame filters
@@ -11090,7 +11299,7 @@ Visiting node of type NODE_INTEGER
convenience functions.
@table @code
-@item help function
+@item help functionu
@kindex help function
@cindex show all convenience functions
Print a list of all convenience functions.