diff mbox

[RFAv3,3/5] Document changes to info [args|functions|locals|variables]

Message ID 20180923214209.985-4-philippe.waroquiers@skynet.be
State New
Headers show

Commit Message

Philippe Waroquiers Sept. 23, 2018, 9:42 p.m. UTC
Document changes to info [args|functions|locals|variables]

gdb/doc/ChangeLog
2018-09-23  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 | 121 +++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 109 insertions(+), 12 deletions(-)

Comments

Eli Zaretskii Sept. 24, 2018, 7:01 a.m. UTC | #1
> From: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> Cc: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> Date: Sun, 23 Sep 2018 23:42:07 +0200
> 
> Document changes to info [args|functions|locals|variables]
> 
> gdb/doc/ChangeLog
> 2018-09-23  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'.

Thanks, this is OK.
Pedro Alves Oct. 22, 2018, 2:17 p.m. UTC | #2
A few small suggestions below.

On 09/23/2018 10:42 PM, Philippe Waroquiers wrote:
> Document changes to info [args|functions|locals|variables]
> 
> gdb/doc/ChangeLog
> 2018-09-23  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 | 121 +++++++++++++++++++++++++++++++++++++++-----
>  1 file changed, 109 insertions(+), 12 deletions(-)
> 
> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
> index b5b6089153..cf4ffa2a94 100644
> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -7767,15 +7767,73 @@ 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.
>  
> +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
> +contain a match for regular expression @var{regexp}.

"contain a match for" gave me pause.  I'd suggest saying instead:

  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, contain a match
> +for regular expression @var{type_regexp}.

[....] 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 it matches the two regexps.
> +
>  @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.
>  
> +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}.

Likewise.

> +
> +If @var{type_regexp} is provided, print only the local 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, a local variable
> +is printed only if it matches the two regexps.

Likewise.

> +
> +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

Nice.  Thanks for the example.

> +
>  @end table
>  
>  @node Frame Apply
> @@ -17857,32 +17915,71 @@ 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 are returning
> +an int.

s/are returning an int/return int/

Thanks,
Pedro Alves

> +
> +If both @var{regexp} and @var{type_regexp} are provided, a function
> +is printed only if it matches the two regexps.
> +
> +
>  @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
>
diff mbox

Patch

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index b5b6089153..cf4ffa2a94 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -7767,15 +7767,73 @@  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.
 
+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
+contain a match for regular expression @var{regexp}.
+
+If @var{type_regexp} is provided, print only the arguments 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.
+
 @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.
 
+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, 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, a local variable
+is printed only if it matches 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
+@noindent
+or the equivalent shorter form
+@smallexample
+tfaas i lo -q -t lock_something_t
+@end smallexample
+
 @end table
 
 @node Frame Apply
@@ -17857,32 +17915,71 @@  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 are returning
+an int.
+
+If both @var{regexp} and @var{type_regexp} are provided, a function
+is printed only if it matches the two regexps.
+
+
 @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