From patchwork Mon May 21 11:06:47 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Philippe Waroquiers X-Patchwork-Id: 27350 Received: (qmail 86901 invoked by alias); 21 May 2018 11:07:20 -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 86815 invoked by uid 89); 21 May 2018 11:07:20 -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=Managing, displayed, Applying, Selection X-HELO: mailsec110.isp.belgacom.be Received: from mailsec110.isp.belgacom.be (HELO mailsec110.isp.belgacom.be) (195.238.20.106) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Mon, 21 May 2018 11:07:17 +0000 IronPort-PHdr: =?us-ascii?q?9a23=3AYUiXCB8fFrmugf9uRHKM819IXTAuvvDOBiVQ1KB3?= =?us-ascii?q?1+IcTK2v8tzYMVDF4r011RmVBd6ds6oMotGVmpioYXYH75eFvSJKW713fDhBt/?= =?us-ascii?q?8rmRc9CtWOE0zxIa2iRSU7GMNfSA0tpCnjYgBaF8nkelLdvGC54yIMFRXjLwp1?= =?us-ascii?q?Ifn+FpLPg8it2O2+55Pebx9UiDahfLh/MAi4oQLNu8cMnIBsMLwxyhzHontJf+?= =?us-ascii?q?RZ22ZlLk+Nkhj/+8m94odt/zxftPw9+cFAV776f7kjQrxDEDsmKWE169b1uhTF?= =?us-ascii?q?UACC+2ETUmQSkhpPHgjF8BT3VYr/vyfmquZw3jSRMMvrRr42RDui9b9mRh/2hi?= =?us-ascii?q?kaOTA382bZhc5+jK9AvB6tuwZyz5LObY2JKPZzeL7Wc9MARWpGW8ZcTzZPAoO9?= =?us-ascii?q?b4sLDuoBJf5YoJfgrFQOtxS+Hw6sBPryyj9JmHD2x7Y62PkmHAHe3AwgHtYOsH?= =?us-ascii?q?XMrNXtKqgeS+60w7PSzTXEdvNWxDb955bSchA6uvyMRrFwcMrXyUYxCwPJlE6f?= =?us-ascii?q?ppL8Mj6Ty+8DsHCb4vJ9We6zj2MrsRx9rzazyss2l4XFmIMYxkra+Sh33oo4I8?= =?us-ascii?q?CzRlRhbt6+CpRQsjmXN45xQsw/XW5loD06yrgauZ6jeygK1Ygnywbfa/OZd4iI?= =?us-ascii?q?5QruVOOMLjtihHJlf7e/iAiq/UihzO3zSNW03U5XoiZZltTArG0B2hLP5sSdV/?= =?us-ascii?q?dx4Eas1SyR2w3d9O1IOUU0mrDaK54lzL4wjJ0TsUHbEy/umEX2jauWdkQ8+uiw?= =?us-ascii?q?9evreLvnqYWGN49zkwH+L6UuldKlAeQjKQUORGub+OS61LL94U31Wq5FgeMunq?= =?us-ascii?q?nDrJ/aPdgbprK+AwJN3YYs9g2wAy6+0NsCgXkIMFJFdwycj4XyIFHOJ+34De2j?= =?us-ascii?q?jFuynjZk3erGMaP7DpXKNHjDn6/rfaxh5E5E1Aoz0ddf6opMCrEBIfLzXk7xtM?= =?us-ascii?q?TADhAnKQC1zfzoCM961oMHRGKPA7GWMLnJsVKT/eIvIOmNZIkLtzbhMfQq/ODh?= =?us-ascii?q?3jcFngoScaPsxZILY3C1Bdx9JFiDanfzi80MV2AQsVkQVuvv3WWCUDpSf26/F5?= =?us-ascii?q?01/DYiFYOrF5yLEpitgbiAxD+2WIJffGdfF1GBC2zAbIaVXfoQLiifdJwy2gcY?= =?us-ascii?q?XKSsHtdynSqlsxX3nuJq?= X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: =?us-ascii?q?A2DkBwBwpwJb/+h+gm1cHgEGDINDgV6NA?= =?us-ascii?q?IwTAYIpAUMalS4LKwGEQAKCFSI4FAECAQEBAQEBAgFrKII1IoJSBlYjED8SOR6?= =?us-ascii?q?DO4IFqHKEWINmgg+KCT+BD4JXhQKFWiACjCCMLAcCgWeGWIYNC4x9kHeBJTMhg?= =?us-ascii?q?VJtU4JEgh8Xjhk9gSgBGgGMWoJFAQE?= X-IPAS-Result: =?us-ascii?q?A2DkBwBwpwJb/+h+gm1cHgEGDINDgV6NAIwTAYIpAUMalS4?= =?us-ascii?q?LKwGEQAKCFSI4FAECAQEBAQEBAgFrKII1IoJSBlYjED8SOR6DO4IFqHKEWINmg?= =?us-ascii?q?g+KCT+BD4JXhQKFWiACjCCMLAcCgWeGWIYNC4x9kHeBJTMhgVJtU4JEgh8Xjhk?= =?us-ascii?q?9gSgBGgGMWoJFAQE?= 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; 21 May 2018 13:07:00 +0200 From: Philippe Waroquiers To: gdb-patches@sourceware.org Cc: Philippe Waroquiers Subject: [RFA 4/8] Documentation changes for 'frame apply' and 'thread apply' Date: Mon, 21 May 2018 13:06:47 +0200 Message-Id: <20180521110651.13842-5-philippe.waroquiers@skynet.be> In-Reply-To: <20180521110651.13842-1-philippe.waroquiers@skynet.be> References: <20180521110651.13842-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 | 225 +++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 222 insertions(+), 3 deletions(-) diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 28f083f96e..e80f52a66e 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} | 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,63 @@ 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}. + +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 v +The flag @code{v} (@samp{verbose}) increases the verbosity. +@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. + +@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 @@ -7300,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 @@ -7712,6 +7770,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. + +@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 + +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{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}. + +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 v +The flag @code{v} (@samp{verbose}) increases the verbosity. +@item q +The flag @code{q} (@samp{quiet}) decreases the verbosity. +@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 + +The default value of verbosity, 2, prints the location 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 + +The verbosity 3 prints the location and address: + +@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 + +The verbosity 4 prints the source line and address: +@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 + +@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 @@ -11090,7 +11309,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.