From patchwork Sun Jun 24 18:37:04 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Philippe Waroquiers X-Patchwork-Id: 28005 Received: (qmail 40652 invoked by alias); 24 Jun 2018 18:37:44 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Delivered-To: mailing list gdb-patches@sourceware.org Received: (qmail 40538 invoked by uid 89); 24 Jun 2018 18:37:43 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-26.3 required=5.0 tests=AWL, BAYES_00, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, RCVD_IN_DNSWL_LOW, SPF_PASS autolearn=ham version=3.3.2 spammy=Frame, 68, Applying, Managing X-HELO: mailsec106.isp.belgacom.be Received: from mailsec106.isp.belgacom.be (HELO mailsec106.isp.belgacom.be) (195.238.20.102) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Sun, 24 Jun 2018 18:37:40 +0000 X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: =?us-ascii?q?A2DXBwCk5C9b/+ApQFdcHQEBBQELAYNJg?= =?us-ascii?q?U8SKIxdi2ABgjUBQ5YPCysBhEACgwIiNxUBAgEBAQEBAQIBbCiCNSKCUgZWIxA?= =?us-ascii?q?/EjkeGYMlggSuaIRbg2aBAopCP4EPglqFCYVcIAKMR4xoBwKBa4Z3hiQLjUkrk?= =?us-ascii?q?UKBVyKBUm1TgmmCIxeOGT0weAEaAYsOgkcBAQ?= X-IPAS-Result: =?us-ascii?q?A2DXBwCk5C9b/+ApQFdcHQEBBQELAYNJgU8SKIxdi2ABgjU?= =?us-ascii?q?BQ5YPCysBhEACgwIiNxUBAgEBAQEBAQIBbCiCNSKCUgZWIxA/EjkeGYMlggSua?= =?us-ascii?q?IRbg2aBAopCP4EPglqFCYVcIAKMR4xoBwKBa4Z3hiQLjUkrkUKBVyKBUm1Tgmm?= =?us-ascii?q?CIxeOGT0weAEaAYsOgkcBAQ?= Received: from 224.41-64-87.adsl-dyn.isp.belgacom.be (HELO md.home) ([87.64.41.224]) by relay.skynet.be with ESMTP/TLS/DHE-RSA-AES128-GCM-SHA256; 24 Jun 2018 20:37:16 +0200 From: Philippe Waroquiers To: gdb-patches@sourceware.org Cc: Philippe Waroquiers Subject: [RFA_v3 4/8] Documents the new commands 'frame apply', faas, taas, tfaas Date: Sun, 24 Jun 2018 20:37:04 +0200 Message-Id: <20180624183708.888-5-philippe.waroquiers@skynet.be> In-Reply-To: <20180624183708.888-1-philippe.waroquiers@skynet.be> References: <20180624183708.888-1-philippe.waroquiers@skynet.be> X-IsSubscribed: yes Documents the new commands 'frame apply', faas, taas, tfaas. Documents the new arguments [FLAG]... added to 'thread apply'. gdb/doc/ChangeLog 2018-06-24 Philippe Waroquiers * gdb.texinfo (Debugging Programs with Multiple Threads): Document changes to 'thread apply'. Document 'taas'. Document 'tfaas'. (Examining the Stack): Document 'frame apply'. Document 'faas'. --- gdb/doc/gdb.texinfo | 190 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 187 insertions(+), 3 deletions(-) diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index a6bad13d9d..a9cef2fd9c 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -2936,7 +2936,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} | 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 @@ -3173,7 +3173,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{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 @@ -3182,6 +3182,59 @@ 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{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 @@ -7304,6 +7357,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 @@ -7716,6 +7770,136 @@ 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} | id @var{id}@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{id} +Use @code{id} to apply @var{command} to the set of frames identified +by the @var{id} list. @var{id} is a frame id or a range of frame ids +as @var{id1}-@var{id2}. The frame id 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 +2, 3, 4, 6, 7, 8, and then again on frame 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 @@ -11094,7 +11278,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.