[doc patch] whatis vs. ptype - the difference

[Jan Kratochvil <jan.kratochvil@redhat.com>]

Hi,

another possibility is to fix it - that `ptype var' strips the typedefs looks
wrong.  But GDB people are used how it works.

The patch just describes the current behavior.  With my English waiting for
a doc review.


Thanks,
Jan


gdb/doc/
2011-07-12  Jan Kratochvil  <jan.kratochvil@redhat.com>

	* gdb.texinfo (whatis, ptype): Highlight their differences.  Describe
	typedefs unrolling.  Extend the sample code by an inned typedef and
	outer typedefs unrolling.

--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -13864,14 +13864,20 @@ __read_nocancel + 6 in section .text of /usr/lib64/libc.so.6
 @item whatis [@var{arg}]
 Print the data type of @var{arg}, which can be either an expression or
 a data type.  With no argument, print the data type of @code{$}, the
-last value in the value history.  If @var{arg} is an expression, it is
-not actually evaluated, and any side-effecting operations (such as
-assignments or function calls) inside it do not take place.  If
-@var{arg} is a type name, it may be the name of a type or typedef, or
-for C code it may have the form @samp{class @var{class-name}},
-@samp{struct @var{struct-tag}}, @samp{union @var{union-tag}} or
-@samp{enum @var{enum-tag}}.
-@xref{Expressions, ,Expressions}.
+last value in the value history.
+
+If @var{arg} is an expression (@pxref{Expressions, ,Expressions}), it is not
+actually evaluated, and any side-effecting operations (such as assignments or
+function calls) inside it do not take place.  @code{whatis} prints the type of
+@var{arg} as used in the source code, possibly including any typedefs.
+@code{whatis} never prints fields of compound types like @samp{struct}s.
+
+If @var{arg} is a type name, it may be the name of a type or typedef, or for
+C code it may have the form @samp{class @var{class-name}}, @samp{struct
+@var{struct-tag}}, @samp{union @var{union-tag}} or @samp{enum @var{enum-tag}}.
+@code{whatis} unrolls in such case only one layer of outer typedef at a time.
+Any inner typedefs --- such as fields of @samp{struct} or typedefs at the
+pointer target --- are always preserved by both @code{whatis} and @code{ptype}.
 
 @kindex ptype
 @item ptype [@var{arg}]
@@ -13879,10 +13885,18 @@ for C code it may have the form @samp{class @var{class-name}},
 detailed description of the type, instead of just the name of the type.
 @xref{Expressions, ,Expressions}.
 
-For example, for this variable declaration:
+@code{ptype} always unrolls all outer typedefs contrary to @code{whatis}.
+@code{ptype} of an expression (variable) will not print its real type including
+possible typedefs as present in the source code -- use @code{whatis} for that
+purpose.  Any inner typedefs --- such as fields of @samp{struct} or typedefs at
+the pointer target --- are always preserved by both @code{whatis} and
+@code{ptype}.
 
 @smallexample
-struct complex @{double real; double imag;@} v;
+typedef double real_t;
+struct complex @{ real_t real; double imag; @};
+typedef struct complex complex_t;
+complex_t v;
 @end smallexample
 
 @noindent
@@ -13891,10 +13905,19 @@ the two commands give this output:
 @smallexample
 @group
 (@value{GDBP}) whatis v
-type = struct complex
+type = complex_t
 (@value{GDBP}) ptype v
 type = struct complex @{
-    double real;
+    real_t real;
+    double imag;
+@}
+(@value{GDBP}) whatis complex_t
+type = struct complex
+(@value{GDBP}) whatis struct complex
+type = struct complex
+(@value{GDBP}) ptype struct complex
+type = struct complex @{
+    real_t real;
     double imag;
 @}
 @end group