From: Philippe Waroquiers <philippe.waroquiers@skynet.be>
To: gdb-patches@sourceware.org
Cc: Philippe Waroquiers <philippe.waroquiers@skynet.be>
Subject: [RFVv4 3/5] Document changes to info [args|functions|locals|variables]
Date: Thu, 25 Oct 2018 20:11:00 -0000 [thread overview]
Message-ID: <20181025201107.24828-4-philippe.waroquiers@skynet.be> (raw)
In-Reply-To: <20181025201107.24828-1-philippe.waroquiers@skynet.be>
Document changes to info [args|functions|locals|variables]
gdb/doc/ChangeLog
2018-10-25 Philippe Waroquiers <philippe.waroquiers@skynet.be>
* gdb.texinfo (Information About a Frame): Document changes
to 'info args' and 'info locals'.
(Examining the Symbol Table): Document changes to 'info functions'
and 'info variables'.
---
gdb/doc/gdb.texinfo | 124 +++++++++++++++++++++++++++++++++++++++-----
1 file changed, 112 insertions(+), 12 deletions(-)
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 99276136d3..aaac8db5e1 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -7830,15 +7830,75 @@ same as for the @command{frame} command (@pxref{Selection, ,Selecting
a Frame}). The selected frame remains unchanged by this command.
@kindex info args
-@item info args
+@item info args [-q]
Print the arguments of the selected frame, each on a separate line.
-@item info locals
+The optional flag @samp{-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 selected
+with the provided regexp(s).
+
+If @var{regexp} is provided, print only the arguments whose names
+match the regular expression @var{regexp}.
+
+If @var{type_regexp} is provided, print only the arguments whose
+types, as printed by the @code{whatis} command, match
+the regular expression @var{type_regexp}.
+If @var{type_regexp} contains space(s), it should be enclosed in
+quote characters. If needed, use backslash to escape the meaning
+of special characters or quotes.
+
+If both @var{regexp} and @var{type_regexp} are provided, an argument
+is printed only if its name matches @var{regexp} and its type matches
+@var{type_regexp}.
+
+@item info locals [-q]
@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.
+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
+match the regular expression @var{regexp}.
+
+If @var{type_regexp} is provided, print only the local variables whose
+types, as printed by the @code{whatis} command, match
+the regular expression @var{type_regexp}.
+If @var{type_regexp} contains space(s), it should be enclosed in
+quote characters. If needed, use backslash to escape the meaning
+of special characters or quotes.
+
+If both @var{regexp} and @var{type_regexp} are provided, a local variable
+is printed only if its name matches @var{regexp} and its type matches
+@var{type_regexp}.
+
+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
+@noindent
+or the equivalent shorter form
+@smallexample
+tfaas i lo -q -t lock_something_t
+@end smallexample
+
@end table
@node Frame Apply
@@ -17920,32 +17980,72 @@ 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}
-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 optional flag @samp{-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 the functions selected with the provided regexp(s).
+
+If @var{regexp} is provided, print 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, print only the functions whose
+types, as printed by the @code{whatis} command, contain a match
+for regular expression @var{type_regexp}.
+If @var{type_regexp} contains space(s), it should be enclosed in
+quote characters. If needed, use backslash to escape the meaning
+of special characters or quotes.
+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 return
+int.
+
+If both @var{regexp} and @var{type_regexp} are provided, a function
+is printed only if its name matches @var{regexp} and its type matches
+@var{type_regexp}.
+
+
@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}
-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}.
+The optional flag @samp{-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 variables selected
+with the provided regexp(s).
+
+If @var{regexp} is provided, print only the variables whose names
+contain a match for regular expression @var{regexp}.
+
+If @var{type_regexp} is provided, print only the variables whose
+types, as printed by the @code{whatis} command, contain a match
+for regular expression @var{type_regexp}.
+If @var{type_regexp} contains space(s), it should be enclosed in
+quote characters. If needed, use backslash to escape the meaning
+of special characters or quotes.
+
+If both @var{regexp} and @var{type_regexp} are provided, an argument
+is printed only if it matches the two regexps.
@kindex info classes
@cindex Objective-C, classes and selectors
--
2.19.1
next prev parent reply other threads:[~2018-10-25 20:11 UTC|newest]
Thread overview: 13+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-10-25 20:11 [RFAv4 0/5] info [args|functions|locals|variables] [-q] [-t TYPEREGEXP] [NAMEREGEXP] Philippe Waroquiers
2018-10-25 20:11 ` [RFVv4 4/5] Announce changes in NEWS to info [args|functions|locals|variables] Philippe Waroquiers
2018-10-26 6:27 ` Eli Zaretskii
2018-10-25 20:11 ` [RFVv4 5/5] Add a test case for info args|functions|locals|variables [-q] [-t TYPEREGEXP] [NAMEREGEXP] Philippe Waroquiers
2018-10-26 18:06 ` Pedro Alves
2018-10-27 12:52 ` Philippe Waroquiers
2018-10-25 20:11 ` [RFVv4 1/5] New cli-utils.h/.c function extract_info_print_args Philippe Waroquiers
2018-10-26 18:04 ` Pedro Alves
2018-10-25 20:11 ` Philippe Waroquiers [this message]
2018-10-26 6:26 ` [RFVv4 3/5] Document changes to info [args|functions|locals|variables] Eli Zaretskii
2018-10-26 17:15 ` Philippe Waroquiers
2018-10-25 20:11 ` [RFVv4 2/5] Add [-q] [-t TYPEREGEXP] [NAMEREGEXP] args " Philippe Waroquiers
2018-10-26 18:05 ` Pedro Alves
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20181025201107.24828-4-philippe.waroquiers@skynet.be \
--to=philippe.waroquiers@skynet.be \
--cc=gdb-patches@sourceware.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).