From patchwork Sat May 5 19:28:03 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Philippe Waroquiers X-Patchwork-Id: 27128 Received: (qmail 16223 invoked by alias); 5 May 2018 19:28:35 -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 15903 invoked by uid 89); 5 May 2018 19:28:32 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-27.6 required=5.0 tests=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=affected, Command, continued, UD:fun.c X-HELO: mailsec109.isp.belgacom.be Received: from mailsec109.isp.belgacom.be (HELO mailsec109.isp.belgacom.be) (195.238.20.105) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Sat, 05 May 2018 19:28:30 +0000 IronPort-PHdr: =?us-ascii?q?9a23=3AX1jyFhYZKDM5QB6dbs3NVqb/LSx+4OfEezUN459i?= =?us-ascii?q?sYplN5qZr8iybnLW6fgltlLVR4KTs6sC17KN9fi4EUU7or+5+EgYd5JNUxJXwe?= =?us-ascii?q?43pCcHRPC/NEvgMfTxZDY7FskRHHVs/nW8LFQHUJ2mPw6arXK99yMdFQviPgRp?= =?us-ascii?q?OOv1BpTSj8Oq3Oyu5pHfeQpFiCazbL9oMBm6sRjau9ULj4dlNqs/0AbCrGFSe+?= =?us-ascii?q?RRy2NoJFaTkAj568yt4pNt8Dletuw4+cJYXqr0Y6o3TbpDDDQ7KG81/9HktQPC?= =?us-ascii?q?TQSU+HQRVHgdnwdSDAjE6BH6WYrxsjf/u+Fg1iSWIdH6QLYpUjmk8qxlSgLniD?= =?us-ascii?q?0fOjA57m/Zl8J+gqFcrh2jqRxy2JLYbJ2POfZiZK7RYc8WSGxcVchRTSxBBYa8?= =?us-ascii?q?YpMVAeoBPOZYq4j9p0MWrRSgGAKjBPngyiVPhn/vwK060vouERvd3Ac9GN8OqH?= =?us-ascii?q?TUrNTxNKcTSeC11LfHwS/NbvxMwzf975HIcg0gof6SR7JwatHcyVIsFwLFiFWf?= =?us-ascii?q?t5DlMymO2esTqmWW6fdrW+G3i2M/tg19vjyiyt0xhoTHmo4Z0E3I+Tt4zYovO9?= =?us-ascii?q?G1RlB3bNi5G5VKrS6aLZF5QsY6TmFtvyY116MJtIagfCgP1JQn3xnfa+Gbc4SQ?= =?us-ascii?q?4hLsSuKRITBgiXJgZb2znRay8U+lyuLiTsW00VBKoTRZktTUq3wByxje5tKaRv?= =?us-ascii?q?Zz4kutwyuD2x7S5+1eP0w5m7TXJ4YkwrEql5oTtUrDHjXxmEXzlKKWbkUk+ums?= =?us-ascii?q?6+TmerXmvoGTO5V6iw7kKKQundW/Afk5MgcQRWib4v+x1Kbg/Uz5RrVFkOE2nr?= =?us-ascii?q?PCv5/EPcgbvLK2AxdJ0oY/7BayFzim38kDknUeNFJKYg6HgJTpO17QO/D1Fuy/?= =?us-ascii?q?g1OxkDdx2//JILPgDY/XLnfdirvheqx960FEwgop0d9f/45UCq0GIP/rQk/xtN?= =?us-ascii?q?3YDhs4Mwys2+boFs9x140EVmKVBa+ZKb7SsV6W6eI1OOmBf5QVuDX9Kvgj+fHu?= =?us-ascii?q?kWU1lkQDcvrh4ZxCZ3yyW+xvP06ZbGHEmdAcC2wHoQMkQartklLRfyRUYiOKX6?= =?us-ascii?q?M45ykjBcqZBJ3EX52sjaaalHOjHpxSZ3heBxaTGG3vbpiFVu0XQDmRM8lsjnoO?= =?us-ascii?q?WO7yGMcayRiyuVqimPJcJe3O93hAuA=3D=3D?= X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: =?us-ascii?q?A2CpCAAkBe5a/+h+gm1cHAEBAQQBAQoBA?= =?us-ascii?q?YNEgVuMdowVAYIpAUMalRwLKwGEQAKCNyI3FQECAQEBAQEBAgFrKII1IoJSBlY?= =?us-ascii?q?jED8SOR6FPqobhFiDaYI4iXk/gQ+CVoUChVogAowSjBIIgWWGUoYLC4xikEmBJ?= =?us-ascii?q?TIigVJtU4JEgh8Xjhk9gSgBGgGMXoJFAQE?= X-IPAS-Result: =?us-ascii?q?A2CpCAAkBe5a/+h+gm1cHAEBAQQBAQoBAYNEgVuMdowVAYI?= =?us-ascii?q?pAUMalRwLKwGEQAKCNyI3FQECAQEBAQEBAgFrKII1IoJSBlYjED8SOR6FPqobh?= =?us-ascii?q?FiDaYI4iXk/gQ+CVoUChVogAowSjBIIgWWGUoYLC4xikEmBJTIigVJtU4JEgh8?= =?us-ascii?q?Xjhk9gSgBGgGMXoJFAQE?= Received: from 232.126-130-109.adsl-dyn.isp.belgacom.be (HELO md.home) ([109.130.126.232]) by relay.skynet.be with ESMTP/TLS/DHE-RSA-AES128-GCM-SHA256; 05 May 2018 21:28:17 +0200 From: Philippe Waroquiers To: gdb-patches@sourceware.org Cc: Philippe Waroquiers Subject: [RFC 4/5] Documentation changes for 'frame apply' and 'thread apply' Date: Sat, 5 May 2018 21:28:03 +0200 Message-Id: <20180505192804.12731-5-philippe.waroquiers@skynet.be> In-Reply-To: <20180505192804.12731-1-philippe.waroquiers@skynet.be> References: <20180505192804.12731-1-philippe.waroquiers@skynet.be> X-IsSubscribed: yes 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(-) diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 28f083f96e..71f71e94a0 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -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.