From fc58fa65d454ce87cfa87a532f2c4f5d0b57d252 Mon Sep 17 00:00:00 2001 From: Andrew Burgess Date: Thu, 10 Sep 2015 17:59:58 +0100 Subject: [PATCH] gdb/doc: Restructure frame command documentation. 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 2ce91861471..4c1697d6555 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,11 @@ +2015-10-12 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-09-25 Doug Evans * gdb.texinfo (Process Record and Replay): Fix syntax of diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index f298172da27..3c1f7857393 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -6951,23 +6951,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 @@ -7167,149 +7150,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 @@ -7377,6 +7217,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} @@ -7453,6 +7300,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 -- 2.30.2