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'.
This commit is contained in:
Andrew Burgess
parent
8d3fea161a
commit
fc58fa65d4
2 changed files with 158 additions and 161 deletions
|
|
@ -1,3 +1,11 @@
|
||||||
|
2015-10-12 Andrew Burgess <andrew.burgess@embecosm.com>
|
||||||
|
|
||||||
|
* 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 <dje@google.com>
|
2015-09-25 Doug Evans <dje@google.com>
|
||||||
|
|
||||||
* gdb.texinfo (Process Record and Replay): Fix syntax of
|
* gdb.texinfo (Process Record and Replay): Fix syntax of
|
||||||
|
|
|
||||||
|
|
@ -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
|
correct tracing of the function call chain. However, @value{GDBN} has
|
||||||
no provision for frameless functions elsewhere in the stack.
|
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
|
@node Backtrace
|
||||||
@section Backtraces
|
@section Backtraces
|
||||||
|
|
||||||
|
|
@ -7167,6 +7150,156 @@ Display an absolute filename.
|
||||||
Show the current way to display filenames.
|
Show the current way to display filenames.
|
||||||
@end table
|
@end table
|
||||||
|
|
||||||
|
@node Selection
|
||||||
|
@section Selecting a Frame
|
||||||
|
|
||||||
|
Most commands for examining the stack and other data in your program work on
|
||||||
|
whichever stack frame is selected at the moment. Here are the commands for
|
||||||
|
selecting a stack frame; all of them finish by printing a brief description
|
||||||
|
of the stack frame just selected.
|
||||||
|
|
||||||
|
@table @code
|
||||||
|
@kindex frame@r{, selecting}
|
||||||
|
@kindex f @r{(@code{frame})}
|
||||||
|
@item frame @var{n}
|
||||||
|
@itemx f @var{n}
|
||||||
|
Select frame number @var{n}. Recall that frame zero is the innermost
|
||||||
|
(currently executing) frame, frame one is the frame that called the
|
||||||
|
innermost one, and so on. The highest-numbered frame is the one for
|
||||||
|
@code{main}.
|
||||||
|
|
||||||
|
@item frame @var{stack-addr} [ @var{pc-addr} ]
|
||||||
|
@itemx f @var{stack-addr} [ @var{pc-addr} ]
|
||||||
|
Select the frame at address @var{stack-addr}. This is useful mainly if the
|
||||||
|
chaining of stack frames has been damaged by a bug, making it
|
||||||
|
impossible for @value{GDBN} to assign numbers properly to all frames. In
|
||||||
|
addition, this can be useful when your program has multiple stacks and
|
||||||
|
switches between them. The optional @var{pc-addr} can also be given to
|
||||||
|
specify the value of PC for the stack frame.
|
||||||
|
|
||||||
|
@kindex up
|
||||||
|
@item up @var{n}
|
||||||
|
Move @var{n} frames up the stack; @var{n} defaults to 1. For positive
|
||||||
|
numbers @var{n}, this advances toward the outermost frame, to higher
|
||||||
|
frame numbers, to frames that have existed longer.
|
||||||
|
|
||||||
|
@kindex down
|
||||||
|
@kindex do @r{(@code{down})}
|
||||||
|
@item down @var{n}
|
||||||
|
Move @var{n} frames down the stack; @var{n} defaults to 1. For
|
||||||
|
positive numbers @var{n}, this advances toward the innermost frame, to
|
||||||
|
lower frame numbers, to frames that were created more recently.
|
||||||
|
You may abbreviate @code{down} as @code{do}.
|
||||||
|
@end table
|
||||||
|
|
||||||
|
All of these commands end by printing two lines of output describing the
|
||||||
|
frame. The first line shows the frame number, the function name, the
|
||||||
|
arguments, and the source file and line number of execution in that
|
||||||
|
frame. The second line shows the text of that source line.
|
||||||
|
|
||||||
|
@need 1000
|
||||||
|
For example:
|
||||||
|
|
||||||
|
@smallexample
|
||||||
|
@group
|
||||||
|
(@value{GDBP}) up
|
||||||
|
#1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc)
|
||||||
|
at env.c:10
|
||||||
|
10 read_input_file (argv[i]);
|
||||||
|
@end group
|
||||||
|
@end smallexample
|
||||||
|
|
||||||
|
After such a printout, the @code{list} command with no arguments
|
||||||
|
prints ten lines centered on the point of execution in the frame.
|
||||||
|
You can also edit the program at the point of execution with your favorite
|
||||||
|
editing program by typing @code{edit}.
|
||||||
|
@xref{List, ,Printing Source Lines},
|
||||||
|
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}
|
||||||
|
@itemx down-silently @var{n}
|
||||||
|
These two commands are variants of @code{up} and @code{down},
|
||||||
|
respectively; they differ in that they do their work silently, without
|
||||||
|
causing display of the new frame. They are intended primarily for use
|
||||||
|
in @value{GDBN} command scripts, where the output might be unnecessary and
|
||||||
|
distracting.
|
||||||
|
@end table
|
||||||
|
|
||||||
|
@node Frame Info
|
||||||
|
@section Information About a Frame
|
||||||
|
|
||||||
|
There are several other commands to print information about the selected
|
||||||
|
stack frame.
|
||||||
|
|
||||||
|
@table @code
|
||||||
|
@item frame
|
||||||
|
@itemx f
|
||||||
|
When used without any argument, this command does not change which
|
||||||
|
frame is selected, but prints a brief description of the currently
|
||||||
|
selected stack frame. It can be abbreviated @code{f}. With an
|
||||||
|
argument, this command is used to select a stack frame.
|
||||||
|
@xref{Selection, ,Selecting a Frame}.
|
||||||
|
|
||||||
|
@kindex info frame
|
||||||
|
@kindex info f @r{(@code{info frame})}
|
||||||
|
@item info frame
|
||||||
|
@itemx info f
|
||||||
|
This command prints a verbose description of the selected stack frame,
|
||||||
|
including:
|
||||||
|
|
||||||
|
@itemize @bullet
|
||||||
|
@item
|
||||||
|
the address of the frame
|
||||||
|
@item
|
||||||
|
the address of the next frame down (called by this frame)
|
||||||
|
@item
|
||||||
|
the address of the next frame up (caller of this frame)
|
||||||
|
@item
|
||||||
|
the language in which the source code corresponding to this frame is written
|
||||||
|
@item
|
||||||
|
the address of the frame's arguments
|
||||||
|
@item
|
||||||
|
the address of the frame's local variables
|
||||||
|
@item
|
||||||
|
the program counter saved in it (the address of execution in the caller frame)
|
||||||
|
@item
|
||||||
|
which registers were saved in the frame
|
||||||
|
@end itemize
|
||||||
|
|
||||||
|
@noindent The verbose description is useful when
|
||||||
|
something has gone wrong that has made the stack format fail to fit
|
||||||
|
the usual conventions.
|
||||||
|
|
||||||
|
@item info frame @var{addr}
|
||||||
|
@itemx info f @var{addr}
|
||||||
|
Print a verbose description of the frame at address @var{addr}, without
|
||||||
|
selecting that frame. The selected frame remains unchanged by this
|
||||||
|
command. This requires the same kind of address (more than one for some
|
||||||
|
architectures) that you specify in the @code{frame} command.
|
||||||
|
@xref{Selection, ,Selecting a Frame}.
|
||||||
|
|
||||||
|
@kindex info args
|
||||||
|
@item info args
|
||||||
|
Print the arguments of the selected frame, each on a separate line.
|
||||||
|
|
||||||
|
@item info locals
|
||||||
|
@kindex info locals
|
||||||
|
Print the local variables of the selected frame, each on a separate
|
||||||
|
line. These are all variables (declared either static or automatic)
|
||||||
|
accessible at the point of execution of the selected frame.
|
||||||
|
|
||||||
|
@end table
|
||||||
|
|
||||||
@node Frame Filter Management
|
@node Frame Filter Management
|
||||||
@section Management of Frame Filters.
|
@section Management of Frame Filters.
|
||||||
@cindex managing frame filters
|
@cindex managing frame filters
|
||||||
|
|
@ -7310,150 +7443,6 @@ objfile /build/test frame-filters:
|
||||||
@end smallexample
|
@end smallexample
|
||||||
@end table
|
@end table
|
||||||
|
|
||||||
@node Selection
|
|
||||||
@section Selecting a Frame
|
|
||||||
|
|
||||||
Most commands for examining the stack and other data in your program work on
|
|
||||||
whichever stack frame is selected at the moment. Here are the commands for
|
|
||||||
selecting a stack frame; all of them finish by printing a brief description
|
|
||||||
of the stack frame just selected.
|
|
||||||
|
|
||||||
@table @code
|
|
||||||
@kindex frame@r{, selecting}
|
|
||||||
@kindex f @r{(@code{frame})}
|
|
||||||
@item frame @var{n}
|
|
||||||
@itemx f @var{n}
|
|
||||||
Select frame number @var{n}. Recall that frame zero is the innermost
|
|
||||||
(currently executing) frame, frame one is the frame that called the
|
|
||||||
innermost one, and so on. The highest-numbered frame is the one for
|
|
||||||
@code{main}.
|
|
||||||
|
|
||||||
@item frame @var{stack-addr} [ @var{pc-addr} ]
|
|
||||||
@itemx f @var{stack-addr} [ @var{pc-addr} ]
|
|
||||||
Select the frame at address @var{stack-addr}. This is useful mainly if the
|
|
||||||
chaining of stack frames has been damaged by a bug, making it
|
|
||||||
impossible for @value{GDBN} to assign numbers properly to all frames. In
|
|
||||||
addition, this can be useful when your program has multiple stacks and
|
|
||||||
switches between them. The optional @var{pc-addr} can also be given to
|
|
||||||
specify the value of PC for the stack frame.
|
|
||||||
|
|
||||||
@kindex up
|
|
||||||
@item up @var{n}
|
|
||||||
Move @var{n} frames up the stack; @var{n} defaults to 1. For positive
|
|
||||||
numbers @var{n}, this advances toward the outermost frame, to higher
|
|
||||||
frame numbers, to frames that have existed longer.
|
|
||||||
|
|
||||||
@kindex down
|
|
||||||
@kindex do @r{(@code{down})}
|
|
||||||
@item down @var{n}
|
|
||||||
Move @var{n} frames down the stack; @var{n} defaults to 1. For
|
|
||||||
positive numbers @var{n}, this advances toward the innermost frame, to
|
|
||||||
lower frame numbers, to frames that were created more recently.
|
|
||||||
You may abbreviate @code{down} as @code{do}.
|
|
||||||
@end table
|
|
||||||
|
|
||||||
All of these commands end by printing two lines of output describing the
|
|
||||||
frame. The first line shows the frame number, the function name, the
|
|
||||||
arguments, and the source file and line number of execution in that
|
|
||||||
frame. The second line shows the text of that source line.
|
|
||||||
|
|
||||||
@need 1000
|
|
||||||
For example:
|
|
||||||
|
|
||||||
@smallexample
|
|
||||||
@group
|
|
||||||
(@value{GDBP}) up
|
|
||||||
#1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc)
|
|
||||||
at env.c:10
|
|
||||||
10 read_input_file (argv[i]);
|
|
||||||
@end group
|
|
||||||
@end smallexample
|
|
||||||
|
|
||||||
After such a printout, the @code{list} command with no arguments
|
|
||||||
prints ten lines centered on the point of execution in the frame.
|
|
||||||
You can also edit the program at the point of execution with your favorite
|
|
||||||
editing program by typing @code{edit}.
|
|
||||||
@xref{List, ,Printing Source Lines},
|
|
||||||
for details.
|
|
||||||
|
|
||||||
@table @code
|
|
||||||
@kindex down-silently
|
|
||||||
@kindex up-silently
|
|
||||||
@item up-silently @var{n}
|
|
||||||
@itemx down-silently @var{n}
|
|
||||||
These two commands are variants of @code{up} and @code{down},
|
|
||||||
respectively; they differ in that they do their work silently, without
|
|
||||||
causing display of the new frame. They are intended primarily for use
|
|
||||||
in @value{GDBN} command scripts, where the output might be unnecessary and
|
|
||||||
distracting.
|
|
||||||
@end table
|
|
||||||
|
|
||||||
@node Frame Info
|
|
||||||
@section Information About a Frame
|
|
||||||
|
|
||||||
There are several other commands to print information about the selected
|
|
||||||
stack frame.
|
|
||||||
|
|
||||||
@table @code
|
|
||||||
@item frame
|
|
||||||
@itemx f
|
|
||||||
When used without any argument, this command does not change which
|
|
||||||
frame is selected, but prints a brief description of the currently
|
|
||||||
selected stack frame. It can be abbreviated @code{f}. With an
|
|
||||||
argument, this command is used to select a stack frame.
|
|
||||||
@xref{Selection, ,Selecting a Frame}.
|
|
||||||
|
|
||||||
@kindex info frame
|
|
||||||
@kindex info f @r{(@code{info frame})}
|
|
||||||
@item info frame
|
|
||||||
@itemx info f
|
|
||||||
This command prints a verbose description of the selected stack frame,
|
|
||||||
including:
|
|
||||||
|
|
||||||
@itemize @bullet
|
|
||||||
@item
|
|
||||||
the address of the frame
|
|
||||||
@item
|
|
||||||
the address of the next frame down (called by this frame)
|
|
||||||
@item
|
|
||||||
the address of the next frame up (caller of this frame)
|
|
||||||
@item
|
|
||||||
the language in which the source code corresponding to this frame is written
|
|
||||||
@item
|
|
||||||
the address of the frame's arguments
|
|
||||||
@item
|
|
||||||
the address of the frame's local variables
|
|
||||||
@item
|
|
||||||
the program counter saved in it (the address of execution in the caller frame)
|
|
||||||
@item
|
|
||||||
which registers were saved in the frame
|
|
||||||
@end itemize
|
|
||||||
|
|
||||||
@noindent The verbose description is useful when
|
|
||||||
something has gone wrong that has made the stack format fail to fit
|
|
||||||
the usual conventions.
|
|
||||||
|
|
||||||
@item info frame @var{addr}
|
|
||||||
@itemx info f @var{addr}
|
|
||||||
Print a verbose description of the frame at address @var{addr}, without
|
|
||||||
selecting that frame. The selected frame remains unchanged by this
|
|
||||||
command. This requires the same kind of address (more than one for some
|
|
||||||
architectures) that you specify in the @code{frame} command.
|
|
||||||
@xref{Selection, ,Selecting a Frame}.
|
|
||||||
|
|
||||||
@kindex info args
|
|
||||||
@item info args
|
|
||||||
Print the arguments of the selected frame, each on a separate line.
|
|
||||||
|
|
||||||
@item info locals
|
|
||||||
@kindex info locals
|
|
||||||
Print the local variables of the selected frame, each on a separate
|
|
||||||
line. These are all variables (declared either static or automatic)
|
|
||||||
accessible at the point of execution of the selected frame.
|
|
||||||
|
|
||||||
@end table
|
|
||||||
|
|
||||||
|
|
||||||
@node Source
|
@node Source
|
||||||
@chapter Examining Source Files
|
@chapter Examining Source Files
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue