[RFC,4/5] Document changes to info [args|functions|locals|variables]
Commit Message
Document changes to info [args|functions|locals|variables]
---
gdb/doc/gdb.texinfo | 98 ++++++++++++++++++++++++++++++++++++++++-----
1 file changed, 88 insertions(+), 10 deletions(-)
Comments
> From: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> Cc: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> Date: Sun, 1 Jul 2018 23:07:33 +0200
>
> Document changes to info [args|functions|locals|variables]
Thanks, I have a few comments:
> gdb/doc/gdb.texinfo | 98 ++++++++++++++++++++++++++++++++++++++++-----
> 1 file changed, 88 insertions(+), 10 deletions(-)
Please provide a ChangeLog entry for gdb/doc/ChangeLog.
> -@item info args
> +@item info args [-q]
> Print the arguments of the selected frame, each on a separate line.
>
> +Flag @code{-q}, which stands for @samp{quiet}, disables printing
> +header information and messages explaining why no argument have been
> +printed.
This sentence sounds awkward. Suggest to rephrase the beginning:
The optional flag @samp{-q}, which stands for @samp{quiet},
disables printing ...
> +@item info args [-q] [-t @var{type_regexp}] [@var{regexp}]
> +Like @kbd{info args}, but only print the arguments
> +that matches the provided regexp(s).
^^^^^^^
"match", in plural.
> +If @var{regexp} is provided, prints only the arguments whose names
^^^^^^
Please be consistent: or "print" everywhere, or "prints" everywhere.
> +If @var{type_regexp} is provided, prints only the arguments whose
> +types contain a match for regular expression @var{type_regexp}.
Is there any significance in "contain a match" vs just "match" above?
If not, I suggest to use the same wording.
Also, the above begs the question: what if I specify both REGEXP and
TYPE_REGEXP? Is that allowed?
> +The matching is done with the variable type as printed with the
> +@code{whatis} command. ^^^^
"by"
> +If @var{type_regexp} contains space(s), it should be enclosed in single
> +quote characters.
Only single quotes? Double quotes are not supported? Should they be?
Same comments to all the other commands where you introduce these
optional arguments.
> +The command @samp{info locals -q -t @var{type_regexp}} can usefully be
^^^^^
@kbd, not @samp. You are showing a command that the user would type.
> +combined with the commands @samp{frame apply} and @samp{thread apply}.
Likewise.
> +For example, if you have an RAII type @code{lock_something_t},
Do we have "RAII" explained anywhere in the manual? I don't think so,
in which case we should have here what it stands for.
> +you can list all locks in your program by doing
> +@samp{thread apply all -s frame apply all -s
> +info locals -q -t lock_something_t}, or the equivalent shorter form
> +@samp{tfaas i lo -q -t lock_something_t}.
It is best to show such long commands as @smallexample, broken into
several lines as needed.
Thanks.
On Mon, 2018-07-02 at 18:02 +0300, Eli Zaretskii wrote:
Thanks for your comments.
Find some feedback below (no feedback means the comment
was handled as you suggested).
I will resubmit the whole doc for review for the first RFA,
handling your
additional comments on the below, if you have some.
> > From: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> > Cc: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> > Date: Sun, 1 Jul 2018 23:07:33 +0200
> >
> > Document changes to info [args|functions|locals|variables]
>
> Thanks, I have a few comments:
>
> > gdb/doc/gdb.texinfo | 98 ++++++++++++++++++++++++++++++++++++++++-----
> > 1 file changed, 88 insertions(+), 10 deletions(-)
>
> Please provide a ChangeLog entry for gdb/doc/ChangeLog.
Will do for the RFA.
> Is there any significance in "contain a match" vs just "match" above?
> If not, I suggest to use the same wording.
Yes, I think that 'contain a match' is the precise condition verified.
Here is the (full) doc for the 'info locals', where I have reworded
the explanation. The other commands have been changed in the same
way.
@item info locals
@kindex info locals [-q]
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.
The optional flag @samp{-q}, which stands for @samp{quiet}, disables
printing header information and messages explaining why no local variables
have been printed.
@item info locals [-q] [-t @var{type_regexp}] [@var{regexp}]
Like @kbd{info locals}, but only print the local variables selected
with the provided regexp(s).
If @var{regexp} is provided, print only the local variables whose names
contain a match for regular expression @var{regexp}.
If @var{type_regexp} is provided, print only the local variables whose
types contain a match for regular expression @var{type_regexp}.
The matching is done with the local variable type as printed by the
@code{whatis} command.
If @var{type_regexp} contains space(s), it should be enclosed in single
quote characters.
If both @var{regexp} and @var{type_regexp} are provided, a local variable
is printed only if it respects the two regexps.
The command @kbd{info locals -q -t @var{type_regexp}} can usefully be
combined with the commands @kbd{frame apply} and @kbd{thread apply}.
For example, your program might use Resource Acquisition Is
Initialization types (RAII) such as @code{lock_something_t} : each
local variable of type @code{lock_something_t} automatically places a
lock that is destroyed when the variable goes out of scope. You can
then list all acquired locks in your program by doing
@smallexample
thread apply all -s frame apply all -s info locals -q -t lock_something_t
@end smallexample
or the equivalent shorter form
@smallexample
tfaas i lo -q -t lock_something_t
@end smallexample
>
> Also, the above begs the question: what if I specify both REGEXP and
> TYPE_REGEXP? Is that allowed?
Yes, it is allowed. The doc above now explicitly describes the behaviour
when both REGEXP are provided.
> > +If @var{type_regexp} contains space(s), it should be enclosed in single
> > +quote characters.
>
> Only single quotes? Double quotes are not supported? Should they be?
I do not think there is a need to support double quotes.
E.g. completer.c also only uses single quote to quote completion strings.
>
> Do we have "RAII" explained anywhere in the manual? I don't think so,
> in which case we should have here what it stands for.
I have tried to explain RAII in the doc above, but wondering if that
is clear enough.
If not, we might maybe put a reference to e.g. the wikipedia article
https://en.wikipedia.org/wiki/Resource_acquisition_is_initialization
if such references are deemed ok in the GDB manual.
Thanks again for the review
Philippe
> From: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> Cc: gdb-patches@sourceware.org
> Date: Mon, 02 Jul 2018 22:45:28 +0200
>
> If both @var{regexp} and @var{type_regexp} are provided, a local variable
> is printed only if it respects the two regexps.
I'd use "matches", not "respects".
> The command @kbd{info locals -q -t @var{type_regexp}} can usefully be
> combined with the commands @kbd{frame apply} and @kbd{thread apply}.
> For example, your program might use Resource Acquisition Is
> Initialization types (RAII) such as @code{lock_something_t} : each
> local variable of type @code{lock_something_t} automatically places a
> lock that is destroyed when the variable goes out of scope. You can
> then list all acquired locks in your program by doing
> @smallexample
> thread apply all -s frame apply all -s info locals -q -t lock_something_t
> @end smallexample
> or the equivalent shorter form
You want @noindent on a separate line before the "or the equivalent",
otherwise the printed manual will have that indented as if it were a
new paragraph (which it isn't).
> I have tried to explain RAII in the doc above, but wondering if that
> is clear enough.
I think it's enough, they can google it if they want to know more.
Thanks, I have no more comments to the new text except the above few
nits.
@@ -7705,15 +7705,60 @@ architectures) that you specify in the @code{frame} command.
@xref{Selection, ,Selecting a Frame}.
@kindex info args
-@item info args
+@item info args [-q]
Print the arguments of the selected frame, each on a separate line.
+Flag @code{-q}, which stands for @samp{quiet}, disables printing
+header information and messages explaining why no argument have been
+printed.
+
+@item info args [-q] [-t @var{type_regexp}] [@var{regexp}]
+Like @kbd{info args}, but only print the arguments
+that matches the provided regexp(s).
+
+If @var{regexp} is provided, prints only the arguments whose names
+contain a match for regular expression @var{regexp}.
+
+If @var{type_regexp} is provided, prints only the arguments whose
+types contain a match for regular expression @var{type_regexp}.
+The matching is done with the variable type as printed with the
+@code{whatis} command.
+If @var{type_regexp} contains space(s), it should be enclosed in single
+quote characters.
+
+
@item info locals
-@kindex info locals
+@kindex info locals [-q]
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.
+Flag @code{-q}, which stands for @samp{quiet}, disables printing
+header information and messages explaining why no local variables have been
+printed.
+
+@item info locals [-q] [-t @var{type_regexp}] [@var{regexp}]
+Like @kbd{info locals}, but only print the local variables
+that matches the provided regexp(s).
+
+If @var{regexp} is provided, prints only the local variables whose names
+contain a match for regular expression @var{regexp}.
+
+If @var{type_regexp} is provided, prints only the local variables whose
+types contain a match for regular expression @var{type_regexp}.
+The matching is done with the local variable type as printed with the
+@code{whatis} command.
+If @var{type_regexp} contains space(s), it should be enclosed in single
+quote characters.
+
+The command @samp{info locals -q -t @var{type_regexp}} can usefully be
+combined with the commands @samp{frame apply} and @samp{thread apply}.
+For example, if you have an RAII type @code{lock_something_t},
+you can list all locks in your program by doing
+@samp{thread apply all -s frame apply all -s
+info locals -q -t lock_something_t}, or the equivalent shorter form
+@samp{tfaas i lo -q -t lock_something_t}.
+
@end table
@node Frame Filter Management
@@ -17665,32 +17710,65 @@ debugging information, organized into two lists: files whose symbols
have already been read, and files whose symbols will be read when needed.
@kindex info functions
-@item info functions
+@item info functions [-q]
Print the names and data types of all defined functions.
Similarly to @samp{info types}, this command groups its output by source
files and annotates each function definition with its source line
number.
-@item info functions @var{regexp}
+Flag @code{-q}, which stands for @samp{quiet}, disables printing
+header information and messages explaining why no functions have been
+printed.
+
+@item info functions [-q] [-t @var{type_regexp}] [@var{regexp}]
Like @samp{info functions}, but only print the names and data types of
-functions whose names contain a match for regular expression
-@var{regexp}. Thus, @samp{info fun step} finds all functions whose
+the functions that matches the provided regexp(s).
+
+If @var{regexp} is provided, prints only the functions whose names
+contain a match for regular expression @var{regexp}.
+Thus, @samp{info fun step} finds all functions whose
names include @code{step}; @samp{info fun ^step} finds those whose names
start with @code{step}. If a function name contains characters that
conflict with the regular expression language (e.g.@:
@samp{operator*()}), they may be quoted with a backslash.
+If @var{type_regexp} is provided, prints only the functions whose
+types contain a match for regular expression @var{type_regexp}.
+The matching is done with the function type as printed with the
+@code{whatis} command.
+If @var{type_regexp} contains space(s), it should be enclosed in single
+quote characters.
+Thus, @samp{info fun -t '^int ('} finds the functions that return
+an integer; @samp{info fun -t '(.*int.*'} finds the functions that
+have an argument type containing int; @samp{info fun -t '^int (' ^step}
+finds the functions whose names start with @code{step} and that are returning
+an int.
+
+
@kindex info variables
-@item info variables
+@item info variables [-q]
Print the names and data types of all variables that are defined
outside of functions (i.e.@: excluding local variables).
The printed variables are grouped by source files and annotated with
their respective source line numbers.
-@item info variables @var{regexp}
+Flag @code{-q}, which stands for @samp{quiet}, disables printing
+header information and messages explaining why no variables have been
+printed.
+
+@item info variables [-q] [-t @var{type_regexp}] [@var{regexp}]
Like @kbd{info variables}, but only print the names and data types of
-non-local variables whose names contain a match for regular expression
-@var{regexp}.
+non-local variables that matches the provided regexp(s).
+
+If @var{regexp} is provided, prints only the variables whose names
+contain a match for regular expression @var{regexp}.
+
+If @var{type_regexp} is provided, prints only the variables whose
+types contain a match for regular expression @var{type_regexp}.
+The matching is done with the variable type as printed with the
+@code{whatis} command.
+If @var{type_regexp} contains space(s), it should be enclosed in single
+quote characters.
@kindex info classes
@cindex Objective-C, classes and selectors