From patchwork Fri Sep 11 18:49:38 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Andrew Burgess X-Patchwork-Id: 8652 Received: (qmail 55595 invoked by alias); 11 Sep 2015 18:50:08 -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 55510 invoked by uid 89); 11 Sep 2015 18:50:07 -0000 Authentication-Results: sourceware.org; auth=none X-Spam-SWARE-Status: No, score=-1.2 required=5.0 tests=AWL, BAYES_00, KAM_LAZY_DOMAIN_SECURITY, RCVD_IN_DNSWL_LOW autolearn=no version=3.3.2 X-HELO: mail-wi0-f171.google.com Received: from mail-wi0-f171.google.com (HELO mail-wi0-f171.google.com) (209.85.212.171) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with (AES128-GCM-SHA256 encrypted) ESMTPS; Fri, 11 Sep 2015 18:49:58 +0000 Received: by wicgb1 with SMTP id gb1so73356617wic.1 for ; Fri, 11 Sep 2015 11:49:54 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:in-reply-to:references; bh=gHqqPogZW4wrFTXhCQUsA6mjukJE1LGTD5AIYKjw+y4=; b=Zb6+iMaa3q097DJLZQ0Ziao0Wqaz+DbrHBhZU0nPr1LZI4wI/r1gYemBN8a5zvcnwX kLCi5feGYSUrGxoKmaUL23nodaOJqBKWYFh+vnDFDfcARGU0OhdH0MEULF66uT536SQP ZnIYyLhtAoVmOP/F6HYN/FfaCxYh4q56VyiPeix94UJiDIZUaZfWQAPjUXMaGN1gy3Ak 0cfehKBr8ALDP65IZeqyhbNr+q+RYvcVkp2wxiH9iriYv8Ert6XnpbrhQUyUvn+Qgniy EBv88nqI2pDDMTyusGaKAd+6206miBRglposDwBelR1wmvFiYqPOZtJL5tK/0WSlFItu LKEw== X-Gm-Message-State: ALoCoQl61RDYx/XDrLAFIH46NUzZm1VgpXM6+AFGp7MQyPzG+wM5yWTCCsQDUZX+ICy5xJDcT85l X-Received: by 10.180.85.194 with SMTP id j2mr7066434wiz.11.1441997394445; Fri, 11 Sep 2015 11:49:54 -0700 (PDT) Received: from localhost (host81-131-206-173.range81-131.btcentralplus.com. [81.131.206.173]) by smtp.gmail.com with ESMTPSA id j7sm1694462wjz.11.2015.09.11.11.49.53 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 11 Sep 2015 11:49:53 -0700 (PDT) From: Andrew Burgess To: gdb-patches@sourceware.org Cc: Andrew Burgess Subject: [PATCH 4/9] gdb/doc: Restructure frame command documentation. Date: Fri, 11 Sep 2015 19:49:38 +0100 Message-Id: <3f336520c7dfa1cd62646a2e8c6ab37cfc99aa7c.1441996064.git.andrew.burgess@embecosm.com> In-Reply-To: References: In-Reply-To: References: X-IsSubscribed: yes The 'frame' command is documented in two places. The 'select-frame' command is only mentioned in one of these places. Of the two places, having the description of 'frame' and 'select-frame' in the section 'Selecting a Frame' seems like the most obvious choice, which is where things like 'up' and 'down' are also documented. This commit moves the documentation of 'frame' and 'select-frame' into the 'Selecting a Frame' section, and removes the duplicate documentation of the 'frame' command. At the same time I have reordered the sections in the 'Examining the Stack' chapter, moving the discussion of frame filters to the end of the chapter; it feels odd that we talk about frame filters before such basic things like navigating the stack, or examining stack frames in general. gdb/doc/ChangeLog: * gdb.texinfo (Frames): Remove 'frame' and 'select-frame' description. (Frame Filter Management): Move to later in the 'Examining the Stack' chapter. (Selection): Add entry for 'select-frame'. --- gdb/doc/ChangeLog | 8 ++ gdb/doc/gdb.texinfo | 309 +++++++++++++++++++++++++--------------------------- 2 files changed, 157 insertions(+), 160 deletions(-) diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 29c66b8..f7d7a94 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,11 @@ +2015-09-11 Andrew Burgess + + * gdb.texinfo (Frames): Remove 'frame' and 'select-frame' + description. + (Frame Filter Management): Move to later in the 'Examining the + Stack' chapter. + (Selection): Add entry for 'select-frame'. + 2015-08-24 Pedro Alves * gdb.texinfo (Remote Configuration): Document the "set/show diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index cd0abad..225e57d 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -6948,23 +6948,6 @@ it had a separate frame, which is numbered zero as usual, allowing correct tracing of the function call chain. However, @value{GDBN} has no provision for frameless functions elsewhere in the stack. -@table @code -@kindex frame@r{, command} -@cindex current stack frame -@item frame @r{[}@var{framespec}@r{]} -The @code{frame} command allows you to move from one stack frame to another, -and to print the stack frame you select. The @var{framespec} may be either the -address of the frame or the stack frame number. Without an argument, -@code{frame} prints the current stack frame. - -@kindex select-frame -@cindex selecting frame silently -@item select-frame -The @code{select-frame} command allows you to move from one stack frame -to another without printing the frame. This is the silent version of -@code{frame}. -@end table - @node Backtrace @section Backtraces @@ -7164,149 +7147,6 @@ Display an absolute filename. Show the current way to display filenames. @end table -@node Frame Filter Management -@section Management of Frame Filters. -@cindex managing frame filters - -Frame filters are Python based utilities to manage and decorate the -output of frames. @xref{Frame Filter API}, for further information. - -Managing frame filters is performed by several commands available -within @value{GDBN}, detailed here. - -@table @code -@kindex info frame-filter -@item info frame-filter -Print a list of installed frame filters from all dictionaries, showing -their name, priority and enabled status. - -@kindex disable frame-filter -@anchor{disable frame-filter all} -@item disable frame-filter @var{filter-dictionary} @var{filter-name} -Disable a frame filter in the dictionary matching -@var{filter-dictionary} and @var{filter-name}. The -@var{filter-dictionary} may be @code{all}, @code{global}, -@code{progspace}, or the name of the object file where the frame filter -dictionary resides. When @code{all} is specified, all frame filters -across all dictionaries are disabled. The @var{filter-name} is the name -of the frame filter and is used when @code{all} is not the option for -@var{filter-dictionary}. A disabled frame-filter is not deleted, it -may be enabled again later. - -@kindex enable frame-filter -@item enable frame-filter @var{filter-dictionary} @var{filter-name} -Enable a frame filter in the dictionary matching -@var{filter-dictionary} and @var{filter-name}. The -@var{filter-dictionary} may be @code{all}, @code{global}, -@code{progspace} or the name of the object file where the frame filter -dictionary resides. When @code{all} is specified, all frame filters across -all dictionaries are enabled. The @var{filter-name} is the name of the frame -filter and is used when @code{all} is not the option for -@var{filter-dictionary}. - -Example: - -@smallexample -(gdb) info frame-filter - -global frame-filters: - Priority Enabled Name - 1000 No PrimaryFunctionFilter - 100 Yes Reverse - -progspace /build/test frame-filters: - Priority Enabled Name - 100 Yes ProgspaceFilter - -objfile /build/test frame-filters: - Priority Enabled Name - 999 Yes BuildProgra Filter - -(gdb) disable frame-filter /build/test BuildProgramFilter -(gdb) info frame-filter - -global frame-filters: - Priority Enabled Name - 1000 No PrimaryFunctionFilter - 100 Yes Reverse - -progspace /build/test frame-filters: - Priority Enabled Name - 100 Yes ProgspaceFilter - -objfile /build/test frame-filters: - Priority Enabled Name - 999 No BuildProgramFilter - -(gdb) enable frame-filter global PrimaryFunctionFilter -(gdb) info frame-filter - -global frame-filters: - Priority Enabled Name - 1000 Yes PrimaryFunctionFilter - 100 Yes Reverse - -progspace /build/test frame-filters: - Priority Enabled Name - 100 Yes ProgspaceFilter - -objfile /build/test frame-filters: - Priority Enabled Name - 999 No BuildProgramFilter -@end smallexample - -@kindex set frame-filter priority -@item set frame-filter priority @var{filter-dictionary} @var{filter-name} @var{priority} -Set the @var{priority} of a frame filter in the dictionary matching -@var{filter-dictionary}, and the frame filter name matching -@var{filter-name}. The @var{filter-dictionary} may be @code{global}, -@code{progspace} or the name of the object file where the frame filter -dictionary resides. The @var{priority} is an integer. - -@kindex show frame-filter priority -@item show frame-filter priority @var{filter-dictionary} @var{filter-name} -Show the @var{priority} of a frame filter in the dictionary matching -@var{filter-dictionary}, and the frame filter name matching -@var{filter-name}. The @var{filter-dictionary} may be @code{global}, -@code{progspace} or the name of the object file where the frame filter -dictionary resides. - -Example: - -@smallexample -(gdb) info frame-filter - -global frame-filters: - Priority Enabled Name - 1000 Yes PrimaryFunctionFilter - 100 Yes Reverse - -progspace /build/test frame-filters: - Priority Enabled Name - 100 Yes ProgspaceFilter - -objfile /build/test frame-filters: - Priority Enabled Name - 999 No BuildProgramFilter - -(gdb) set frame-filter priority global Reverse 50 -(gdb) info frame-filter - -global frame-filters: - Priority Enabled Name - 1000 Yes PrimaryFunctionFilter - 50 Yes Reverse - -progspace /build/test frame-filters: - Priority Enabled Name - 100 Yes ProgspaceFilter - -objfile /build/test frame-filters: - Priority Enabled Name - 999 No BuildProgramFilter -@end smallexample -@end table - @node Selection @section Selecting a Frame @@ -7374,6 +7214,13 @@ editing program by typing @code{edit}. for details. @table @code +@kindex select-frame +@item select-frame +The @code{select-frame} command is a variant of @code{frame} that does +not display the new frame after selecting it. This command is +intended primarily for use in @value{GDBN} command scripts, where the +output might be unnecessary and distracting. + @kindex down-silently @kindex up-silently @item up-silently @var{n} @@ -7450,6 +7297,148 @@ accessible at the point of execution of the selected frame. @end table +@node Frame Filter Management +@section Management of Frame Filters. +@cindex managing frame filters + +Frame filters are Python based utilities to manage and decorate the +output of frames. @xref{Frame Filter API}, for further information. + +Managing frame filters is performed by several commands available +within @value{GDBN}, detailed here. + +@table @code +@kindex info frame-filter +@item info frame-filter +Print a list of installed frame filters from all dictionaries, showing +their name, priority and enabled status. + +@kindex disable frame-filter +@anchor{disable frame-filter all} +@item disable frame-filter @var{filter-dictionary} @var{filter-name} +Disable a frame filter in the dictionary matching +@var{filter-dictionary} and @var{filter-name}. The +@var{filter-dictionary} may be @code{all}, @code{global}, +@code{progspace}, or the name of the object file where the frame filter +dictionary resides. When @code{all} is specified, all frame filters +across all dictionaries are disabled. The @var{filter-name} is the name +of the frame filter and is used when @code{all} is not the option for +@var{filter-dictionary}. A disabled frame-filter is not deleted, it +may be enabled again later. + +@kindex enable frame-filter +@item enable frame-filter @var{filter-dictionary} @var{filter-name} +Enable a frame filter in the dictionary matching +@var{filter-dictionary} and @var{filter-name}. The +@var{filter-dictionary} may be @code{all}, @code{global}, +@code{progspace} or the name of the object file where the frame filter +dictionary resides. When @code{all} is specified, all frame filters across +all dictionaries are enabled. The @var{filter-name} is the name of the frame +filter and is used when @code{all} is not the option for +@var{filter-dictionary}. + +Example: + +@smallexample +(gdb) info frame-filter + +global frame-filters: + Priority Enabled Name + 1000 No PrimaryFunctionFilter + 100 Yes Reverse + +progspace /build/test frame-filters: + Priority Enabled Name + 100 Yes ProgspaceFilter + +objfile /build/test frame-filters: + Priority Enabled Name + 999 Yes BuildProgra Filter + +(gdb) disable frame-filter /build/test BuildProgramFilter +(gdb) info frame-filter + +global frame-filters: + Priority Enabled Name + 1000 No PrimaryFunctionFilter + 100 Yes Reverse + +progspace /build/test frame-filters: + Priority Enabled Name + 100 Yes ProgspaceFilter + +objfile /build/test frame-filters: + Priority Enabled Name + 999 No BuildProgramFilter + +(gdb) enable frame-filter global PrimaryFunctionFilter +(gdb) info frame-filter + +global frame-filters: + Priority Enabled Name + 1000 Yes PrimaryFunctionFilter + 100 Yes Reverse + +progspace /build/test frame-filters: + Priority Enabled Name + 100 Yes ProgspaceFilter + +objfile /build/test frame-filters: + Priority Enabled Name + 999 No BuildProgramFilter +@end smallexample + +@kindex set frame-filter priority +@item set frame-filter priority @var{filter-dictionary} @var{filter-name} @var{priority} +Set the @var{priority} of a frame filter in the dictionary matching +@var{filter-dictionary}, and the frame filter name matching +@var{filter-name}. The @var{filter-dictionary} may be @code{global}, +@code{progspace} or the name of the object file where the frame filter +dictionary resides. The @var{priority} is an integer. + +@kindex show frame-filter priority +@item show frame-filter priority @var{filter-dictionary} @var{filter-name} +Show the @var{priority} of a frame filter in the dictionary matching +@var{filter-dictionary}, and the frame filter name matching +@var{filter-name}. The @var{filter-dictionary} may be @code{global}, +@code{progspace} or the name of the object file where the frame filter +dictionary resides. + +Example: + +@smallexample +(gdb) info frame-filter + +global frame-filters: + Priority Enabled Name + 1000 Yes PrimaryFunctionFilter + 100 Yes Reverse + +progspace /build/test frame-filters: + Priority Enabled Name + 100 Yes ProgspaceFilter + +objfile /build/test frame-filters: + Priority Enabled Name + 999 No BuildProgramFilter + +(gdb) set frame-filter priority global Reverse 50 +(gdb) info frame-filter + +global frame-filters: + Priority Enabled Name + 1000 Yes PrimaryFunctionFilter + 50 Yes Reverse + +progspace /build/test frame-filters: + Priority Enabled Name + 100 Yes ProgspaceFilter + +objfile /build/test frame-filters: + Priority Enabled Name + 999 No BuildProgramFilter +@end smallexample +@end table @node Source @chapter Examining Source Files