[RFA] (try to) consistently use 'frame level' concept instead of 'frame number'.
Commit Message
Following the discussion in the 'frame apply' patch and the patch proposed
in https://sourceware.org/ml/gdb-patches/2018-06/msg00170.html
the idea is rather to speak about 'frame level' to identify a frame,
rather than 'frame number'.
This patch changes a few occurences of 'frame number' (or 'number') to
'frame level' (or 'level') in the code and in gdb.texinfo.
Note that the doc still has some references to 'trace frame number',
but I think that this is really a number that is numbering a set
of traced frames, and it is not a level. So, such occurences are
kept unchanged.
gdb/doc/ChangeLog
2018-07-12 Philippe Waroquiers <philippe.waroquiers@skynet.be>
* gdb.texinfo (Stack Frames):
Change 'frame number' to 'frame level'.
(Backtrace): Likewise.
(Selecting a Frame): Likewise.
(GDB/MI Stack Manipulation): Likewise.
gdb/ChangeLog
* stack.c (backtrace_command_1): Change 'frame number' to
'frame level'.
(_initialize_stack): Likewise.
---
gdb/doc/gdb.texinfo | 25 ++++++++++++-------------
gdb/stack.c | 6 +++---
2 files changed, 15 insertions(+), 16 deletions(-)
Comments
> From: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> Cc: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> Date: Fri, 13 Jul 2018 00:15:36 +0200
>
> Following the discussion in the 'frame apply' patch and the patch proposed
> in https://sourceware.org/ml/gdb-patches/2018-06/msg00170.html
> the idea is rather to speak about 'frame level' to identify a frame,
> rather than 'frame number'.
I question the wisdom of changing such veteran terminology.
> -@cindex frame number
> -@value{GDBN} assigns numbers to all existing stack frames, starting with
> +@cindex frame level
> +In @value{GDBN}, each existing stack frame has a level, starting with
> zero for the innermost frame, one for the frame that called it,
> -and so on upward. These numbers do not really exist in your program;
> -they are assigned by @value{GDBN} to give you a way of designating stack
> +and so on upward. These levels give you a way of designating stack
> frames in @value{GDBN} commands.
If we are going to make this change, then I would suggest to keep the
index entry, _add_ to it an entry about "frame level", and explain
here what that level is, something like this:
@value{GDBN} labels each existing stack frame with a @dfn{level}, a
number that is zero for the innermost frame, one for the frame that
called it, and so on upward. These level numbers give you a way of
designating stack frames in @value{GDBN} commands.
> -it had a separate frame, which is numbered zero as usual, allowing
> +it had a separate frame, which has a level zero as usual, allowing
^^^^^^^^^^
"level of zero".
> -Select frame number @var{n}. Recall that frame zero is the innermost
> +Select frame level @var{n}. Recall that frame zero is the innermost
^^^^^^^^^^^^^^^^^^^^^^^^^^
"Select frame whose level is @var{n}."
Thanks.
On Fri, 2018-07-13 at 09:52 +0300, Eli Zaretskii wrote:
> > From: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> > Cc: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> > Date: Fri, 13 Jul 2018 00:15:36 +0200
> >
> > Following the discussion in the 'frame apply' patch and the patch proposed
> > in https://sourceware.org/ml/gdb-patches/2018-06/msg00170.html
> > the idea is rather to speak about 'frame level' to identify a frame,
> > rather than 'frame number'.
>
> I question the wisdom of changing such veteran terminology.
Yes, for sure, frame number was used since quite some time.
But the concept of frame level was also already used, and IMO
there is quite some confusions between the 2.
For example, in @node GDB/MI Frame Information.
We also have some places that are defining frame number
as being the level e.g.-stack-list-frames.
And IMO, at other places, level is used where it should
rather be number or count.
E.g.
'set backtrace limit N'
'set backtrace limit 0'
'set backtrace limit unlimited'
Limit the backtrace to N levels. A value of 'unlimited' or zero
means unlimited levels.
looks somewhat confusing, and should rather be limit the backtrace
to N entries, or N frames, or whatever
but probably not N levels.
To be further discussed it looks like ...
Thanks
Philippe
>
> > -@cindex frame number
> > -@value{GDBN} assigns numbers to all existing stack frames, starting with
> > +@cindex frame level
> > +In @value{GDBN}, each existing stack frame has a level, starting with
> > zero for the innermost frame, one for the frame that called it,
> > -and so on upward. These numbers do not really exist in your program;
> > -they are assigned by @value{GDBN} to give you a way of designating stack
> > +and so on upward. These levels give you a way of designating stack
> > frames in @value{GDBN} commands.
>
> If we are going to make this change, then I would suggest to keep the
> index entry, _add_ to it an entry about "frame level", and explain
> here what that level is, something like this:
>
> @value{GDBN} labels each existing stack frame with a @dfn{level}, a
> number that is zero for the innermost frame, one for the frame that
> called it, and so on upward. These level numbers give you a way of
> designating stack frames in @value{GDBN} commands.
>
> > -it had a separate frame, which is numbered zero as usual, allowing
> > +it had a separate frame, which has a level zero as usual, allowing
>
> ^^^^^^^^^^
> "level of zero".
>
> > -Select frame number @var{n}. Recall that frame zero is the innermost
> > +Select frame level @var{n}. Recall that frame zero is the innermost
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^
> "Select frame whose level is @var{n}."
>
> Thanks.
@@ -7393,11 +7393,10 @@ address serves as the address of the frame. Usually this address is kept
in a register called the @dfn{frame pointer register}
(@pxref{Registers, $fp}) while execution is going on in that frame.
-@cindex frame number
-@value{GDBN} assigns numbers to all existing stack frames, starting with
+@cindex frame level
+In @value{GDBN}, each existing stack frame has a level, starting with
zero for the innermost frame, one for the frame that called it,
-and so on upward. These numbers do not really exist in your program;
-they are assigned by @value{GDBN} to give you a way of designating stack
+and so on upward. These levels give you a way of designating stack
frames in @value{GDBN} commands.
@c The -fomit-frame-pointer below perennially causes hbox overflow
@@ -7413,7 +7412,7 @@ This is occasionally done with heavily used library functions to save
the frame setup time. @value{GDBN} has limited facilities for dealing
with these function invocations. If the innermost function invocation
has no stack frame, @value{GDBN} nevertheless regards it as though
-it had a separate frame, which is numbered zero as usual, allowing
+it had a separate frame, which has a level zero as usual, allowing
correct tracing of the function call chain. However, @value{GDBN} has
no provision for frameless functions elsewhere in the stack.
@@ -7486,7 +7485,7 @@ apply all backtrace}, @value{GDBN} will display the backtrace for all
the threads; this is handy when you debug a core dump of a
multi-threaded program.
-Each line in the backtrace shows the frame number and the function name.
+Each line in the backtrace shows the frame level and the function name.
The program counter value is also shown---unless you use @code{set
print address off}. The backtrace also shows the source file name and
line number, as well as the arguments to the function. The program
@@ -7633,16 +7632,16 @@ of the stack frame just selected.
@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
+Select frame level @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
+innermost one, and so on. The highest-level 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
+impossible for @value{GDBN} to assign levels 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.
@@ -7651,19 +7650,19 @@ specify the value of PC for the stack frame.
@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.
+frame levels, 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.
+lower frame levels, 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
+frame. The first line shows the frame level, 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.
@@ -30074,7 +30073,7 @@ following info:
@table @samp
@item @var{level}
-The frame number, 0 being the topmost frame, i.e., the innermost function.
+The frame level, 0 being the topmost frame, i.e., the innermost function.
@item @var{addr}
The @code{$pc} value for that frame.
@item @var{func}
@@ -1763,7 +1763,7 @@ backtrace_command_1 (const char *count_exp, frame_filter_flags flags,
{
py_start = 0;
/* The argument to apply_ext_lang_frame_filter is the number
- of the final frame to print, and frames start at 0. */
+ of frames to print, and frame levels start at 0. */
py_end = count - 1;
}
}
@@ -2746,7 +2746,7 @@ This is useful in command scripts."));
Select and print a stack frame.\nWith no argument, \
print the selected stack frame. (See also \"info frame\").\n\
An argument specifies the frame to select.\n\
-It can be a stack frame number or the address of the frame."),
+It can be a stack frame level or the address of the frame."),
&frame_cmd_list, "frame ", 1, &cmdlist);
add_com_alias ("f", "frame", class_stack, 1);
@@ -2792,7 +2792,7 @@ shortcut for 'frame apply all -s COMMAND'"));
add_com_suppress_notification ("select-frame", class_stack, select_frame_command, _("\
Select a stack frame without printing anything.\n\
An argument specifies the frame to select.\n\
-It can be a stack frame number or the address of the frame."),
+It can be a stack frame level or the address of the frame."),
&cli_suppress_notification.user_selected_context);
add_com ("backtrace", class_stack, backtrace_command, _("\