[RFAv2,3/3] NEWS and documentation for $_gdb_setting and $_gdb_int_setting.

Message ID 20190705195823.3472-4-philippe.waroquiers@skynet.be
State New
Headers show
Series
  • Convenience functions $_gdb_setting/$_gdb_int_setting
Related show

Commit Message

Philippe Waroquiers July 5, 2019, 7:58 p.m.
---
 gdb/ChangeLog       |  3 +++
 gdb/NEWS            |  5 +++++
 gdb/doc/ChangeLog   |  5 +++++
 gdb/doc/gdb.texinfo | 48 +++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 61 insertions(+)

-- 
2.20.1

Comments

Eli Zaretskii July 6, 2019, 6:23 a.m. | #1
> From: Philippe Waroquiers <philippe.waroquiers@skynet.be>

> Cc: Philippe Waroquiers <philippe.waroquiers@skynet.be>

> Date: Fri,  5 Jul 2019 21:58:23 +0200

> 

> +@item $_gdb_setting (@var{setting})

> +@findex $_gdb_setting@r{, convenience function}

> +Return the value of the @value{GDBN} @var{setting} as a string.

> +@var{setting} is any setting that can be used in a @code{set} or

> +@code{show} command (@pxref{Controlling GDB}).


After reading the description of $_gdb_int_setting, a question I have
about this function is whether it works for settings whose values are
integers.  The examples answer that question, but I think the text
should be explicit about that.

> +@item $_gdb_int_setting (@var{setting})

> +@findex $_gdb_int_setting@r{, convenience function}

> +Return the value of the @value{GDBN} @var{setting} as an integer.

> +This only works for boolean, auto boolean and integer settings.

> +The boolean values @code{on} and @code{off} are converted to

> +the integer values @code{0} and @code{1}.


The correspondence of ON and OFF to zero and 1 respectively surprised
me.  Why not the other way around?

>                                             The value @code{auto} is

> +converted to the value  @code{2}.

> +Some integer settings accepts an @code{unlimited} value.

> +Depending on the setting, the unlimited value is converted to a @code{0}

> +or a @code{-1} value.


The last part begs a question how to know whether 'unlimited' will
yield zero or -1?  Can't we always return -1?

Markup-wise, please use @code{@minus{}1}, it will look better in print.

Btw, do we have a way of determining whether a given convenience
function exists in the current GDB?  For variables, one can use
$_isvoid, I think, but what about functions?

Thanks.
Philippe Waroquiers July 6, 2019, 10:54 a.m. | #2
Thanks for the comments, I have just sent a v3 that handles
them.

(note that v2 did not change anything compared to v1, as I forgot
to commit the changes before sending the mail).

Some more feedback below.


On Sat, 2019-07-06 at 09:23 +0300, Eli Zaretskii wrote:
> > From: Philippe Waroquiers <philippe.waroquiers@skynet.be>

> > Cc: Philippe Waroquiers <philippe.waroquiers@skynet.be>

> > Date: Fri,  5 Jul 2019 21:58:23 +0200

> > 

> > +@item $_gdb_setting (@var{setting})

> > +@findex $_gdb_setting@r{, convenience function}

> > +Return the value of the @value{GDBN} @var{setting} as a string.

> > +@var{setting} is any setting that can be used in a @code{set} or

> > +@code{show} command (@pxref{Controlling GDB}).

> 

> After reading the description of $_gdb_int_setting, a question I have

> about this function is whether it works for settings whose values are

> integers.  The examples answer that question, but I think the text

> should be explicit about that.

I have tried to clarify this in the description in RFAv3.

> 

> > +@item $_gdb_int_setting (@var{setting})

> > +@findex $_gdb_int_setting@r{, convenience function}

> > +Return the value of the @value{GDBN} @var{setting} as an integer.

> > +This only works for boolean, auto boolean and integer settings.

> > +The boolean values @code{on} and @code{off} are converted to

> > +the integer values @code{0} and @code{1}.

> 

> The correspondence of ON and OFF to zero and 1 respectively surprised

> me.  Why not the other way around?

That was an error in the doc, fixed in RFAv3.  It now describes
that 0 is off and 1 is on.

> 

> >                                             The value @code{auto} is

> > +converted to the value  @code{2}.

> > +Some integer settings accepts an @code{unlimited} value.

> > +Depending on the setting, the unlimited value is converted to a @code{0}

> > +or a @code{-1} value.

> 

> The last part begs a question how to know whether 'unlimited' will

> yield zero or -1?  Can't we always return -1?

I think it is better to keep the same convention as what is accepted
by the "set" command: some settings are using 0 to mean unlimited
and some are using -1.
I have tried to describe this in the doc RFAv3.

> 

> Markup-wise, please use @code{@minus{}1}, it will look better in print.

> 

> Btw, do we have a way of determining whether a given convenience

> function exists in the current GDB?  For variables, one can use

> $_isvoid, I think, but what about functions?


I do not know of any way to see if a user defined function or convenience
function is defined.
For the GDB convenience function, the GDB major/minor can be used to 
determine what is available.

Philippe
Eli Zaretskii July 6, 2019, 11:21 a.m. | #3
> From: Philippe Waroquiers <philippe.waroquiers@skynet.be>

> Cc: gdb-patches@sourceware.org

> Date: Sat, 06 Jul 2019 12:54:39 +0200

> 

> > The last part begs a question how to know whether 'unlimited' will

> > yield zero or -1?  Can't we always return -1?

> I think it is better to keep the same convention as what is accepted

> by the "set" command: some settings are using 0 to mean unlimited

> and some are using -1.

> I have tried to describe this in the doc RFAv3.


The new text is OK, but I'd suggest to say in addition something like
"See the documentation of the corresponding @code{set} command for
the numerical value equivalent to @code{unlimited}."

> > Btw, do we have a way of determining whether a given convenience

> > function exists in the current GDB?  For variables, one can use

> > $_isvoid, I think, but what about functions?

> 

> I do not know of any way to see if a user defined function or convenience

> function is defined.

> For the GDB convenience function, the GDB major/minor can be used to 

> determine what is available.


OK, thanks.

Patch

diff --git a/gdb/ChangeLog b/gdb/ChangeLog
index ab414dca9f..bfde05e363 100644
--- a/gdb/ChangeLog
+++ b/gdb/ChangeLog
@@ -9111,6 +9111,9 @@  fill-column: 74
 version-control: never
 coding: utf-8
 End:
+2019-04-28  Philippe Waroquiers  <philippe.waroquiers@skynet.be>
+
+	* NEWS: Mention $_gdb_setting and $_gdb_int_setting.
 
 2019-04-28  Philippe Waroquiers  <philippe.waroquiers@skynet.be>
 
diff --git a/gdb/NEWS b/gdb/NEWS
index 34c544c3d5..d17d37ceff 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -11,6 +11,11 @@ 
   scripts that should work error-free with many different versions,
   such as in system-wide init files.
 
+* New built-in convenience functions $_gdb_setting and $_gdb_int_setting
+  provide access to values of the GDB settings.  They are handy
+  for changing the logic of user defined commands depending on the
+  current GDB settings.
+
 * GDB now supports Thread Local Storage (TLS) variables on several
   FreeBSD architectures (amd64, i386, powerpc, riscv).  Other
   architectures require kernel changes.  TLS is not yet supported for
diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index 1025916003..536444f628 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -12944,3 +12944,8 @@  fill-column: 74
 version-control: never
 coding: utf-8
 End:
+2019-04-27  Philippe Waroquiers  <philippe.waroquiers@skynet.be>
+
+	* gdb.texinfo (Convenience Funs): Document the new
+	$_gdb_setting and $_gdb_int_setting convenience functions.
+
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 299c4a12a1..e122fbb77b 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -11820,6 +11820,54 @@  $3 = void
 $4 = 1
 @end smallexample
 
+@item $_gdb_setting (@var{setting})
+@findex $_gdb_setting@r{, convenience function}
+Return the value of the @value{GDBN} @var{setting} as a string.
+@var{setting} is any setting that can be used in a @code{set} or
+@code{show} command (@pxref{Controlling GDB}).
+
+@smallexample
+(@value{GDBP}) show print frame-arguments
+Printing of non-scalar frame arguments is "scalars".
+(@value{GDBP}) p $_gdb_setting("print frame-arguments")
+$2 = "scalars"
+(@value{GDBP}) p $_gdb_setting("height")
+$3 = "30"
+((@value{GDBP})
+@end smallexample
+
+@item $_gdb_int_setting (@var{setting})
+@findex $_gdb_int_setting@r{, convenience function}
+Return the value of the @value{GDBN} @var{setting} as an integer.
+This only works for boolean, auto boolean and integer settings.
+The boolean values @code{on} and @code{off} are converted to
+the integer values @code{0} and @code{1}.  The value @code{auto} is
+converted to the value  @code{2}.
+Some integer settings accepts an @code{unlimited} value.
+Depending on the setting, the unlimited value is converted to a @code{0}
+or a @code{-1} value.
+
+@smallexample
+@group
+(@value{GDBP}) p $_gdb_setting("height")
+$3 = "30"
+(@value{GDBP}) p $_gdb_int_setting("height")
+$4 = 30
+(@value{GDBP}) set height unlimited
+(@value{GDBP}) p $_gdb_setting("height")
+$5 = "unlimited"
+(@value{GDBP}) p $_gdb_int_setting("height")
+$6 = 0
+@end group
+@group
+(@value{GDBP}) p $_gdb_setting("remote hardware-watchpoint-limit")
+$7 = "unlimited"
+(@value{GDBP}) p $_gdb_int_setting("remote hardware-watchpoint-limit")
+$8 = -1
+(@value{GDBP})
+@end group
+@end smallexample
+
 @end table
 
 These functions require @value{GDBN} to be configured with