Based on the discussion at:

<https://sourceware.org/ml/gdb-patches/2013-09/msg00301.html>
<https://sourceware.org/ml/gdb-patches/2013-09/msg00383.html>

This patch adds a new convenience function called $_isvoid, whose
only purpose is to check whether an expression is void or not.
This became necessary because the new convenience variable
$_exitsignal (not yet approved) has a mutual exclusive behavior
with $_exitcode, i.e., when one is "defined" (i.e., non-void),
the other is cleared (i.e., becomes void).  Doug wanted a way to
identify which variable to use, and checking for voidness is the
obvious solution.

It is worth mentioning that my first attempt, after a conversation with
Doug, was to actually implement a new $_isdefined() convenience
function.  I would do that (for convenience variables) by calling
lookup_only_internalvar.  However, I found a few problems:

- Whenever I called $_isdefined ($variable), $variable became defined
  (with a void value), and $_isdefined always returned true.

- Then, I tried to implement $_isdefined ("variable"), and do the "$" +
  "variable" inside GDB, thus making it impossible for GDB to create the
  convenience variable.  However, it was hard to extract the string
  without having to mess with values and their idiossincrasies.
  Therefore, I decided to abandon this attempt (specially because I
  didn't want to spend too much time struggling with it).

Anyway, after talking to Doug again we decided that it would be easier
to implement $_isvoid, and this will probably help in cases like
<http://stackoverflow.com/questions/3744554/testing-if-a-gdb-convenience-variable-is-defined>.

I wrote a NEWS entry for it, and some new lines on the documentation.

gdb/
2013-09-16  Sergio Durigan Junior  <sergiodj@redhat.com>

	* NEWS: Mention new convenience function $_isvoid.
	* value.c (isvoid_internal_fn): New function.
	(_initialize_values): Add new convenience function $_isvoid.

gdb/doc/
2013-09-16  Sergio Durigan Junior  <sergiodj@redhat.com>

	* gdb.texinfo (Convenience Functions): Mention new convenience
	function $_isvoid.

gdb/testsuite/
2013-09-16  Sergio Durigan Junior  <sergiodj@redhat.com>

	* gdb.base/gdbvars.c (foo_void): New function.
	(foo_int): Likewise.
	* gdb.base/gdbvars.exp (test_convenience_functions): New
	function.  Call it.

2 files changed, 68 insertions, 0 deletions

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index 3e07eaa3c32..e183332fb9a 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,8 @@
+2013-09-16  Sergio Durigan Junior  <sergiodj@redhat.com>
+
+	* gdb.texinfo (Convenience Functions): Mention new convenience
+	function $_isvoid.
+
 2013-09-13  Andreas Arnez  <arnez@linux.vnet.ibm.com>
 
 	* gdb.texinfo (Decimal Floating Point format): Mention S/390.
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index a8c854e3745..65f63e4a9b7 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -9800,6 +9800,69 @@ function can be used in an expression just like an ordinary function;
 however, a convenience function is implemented internally to
 @value{GDBN}.
 
+These functions do not require @value{GDBN} to be configured with
+@code{Python} support, which means that they are always available.
+
+@table @code
+
+@item $_isvoid (@var{expr})
+@findex $_isvoid@r{, convenience function}
+Return one if the expression @var{expr} is @code{void}.  Otherwise it
+returns zero.
+
+A @code{void} expression is an expression where the type of the result
+is @code{void}.  For example, you can examine a convenience variable
+(see @ref{Convenience Vars,, Convenience Variables}) to check whether
+it is @code{void}:
+
+@smallexample
+(@value{GDBP}) print $_exitcode
+$1 = void
+(@value{GDBP}) print $_isvoid ($_exitcode)
+$2 = 1
+(@value{GDBP}) run
+Starting program: ./a.out
+[Inferior 1 (process 29572) exited normally]
+(@value{GDBP}) print $_exitcode
+$3 = 0
+(@value{GDBP}) print $_isvoid ($_exitcode)
+$4 = 0
+@end smallexample
+
+In the example above, we used @code{$_isvoid} to check whether
+@code{$_exitcode} is @code{void} before and after the execution of the
+program being debugged.  Before the execution there is no exit code to
+be examined, therefore @code{$_exitcode} is @code{void}.  After the
+execution the program being debugged returned zero, therefore
+@code{$_exitcode} is zero, which means that it is not @code{void}
+anymore.
+
+The @code{void} expression can also be a call of a function from the
+program being debugged.  For example, given the following function:
+
+@smallexample
+void
+foo (void)
+@{
+@}
+@end smallexample
+
+The result of calling it inside @value{GDBN} is @code{void}:
+
+@smallexample
+(@value{GDBP}) print foo ()
+$1 = void
+(@value{GDBP}) print $_isvoid (foo ())
+$2 = 1
+(@value{GDBP}) set $v = foo ()
+(@value{GDBP}) print $v
+$3 = void
+(@value{GDBP}) print $_isvoid ($v)
+$4 = 1
+@end smallexample
+
+@end table
+
 These functions require @value{GDBN} to be configured with
 @code{Python} support.