[doc patch] whatis vs. ptype - the difference

[doc patch] whatis vs. ptype - the difference

[Jan Kratochvil]

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

Re: [doc patch] whatis vs. ptype - the difference

[Eli Zaretskii]

> Date: Tue, 12 Jul 2011 20:31:30 +0200
> From: Jan Kratochvil <jan.kratochvil@redhat.com>
> 
> The patch just describes the current behavior.  With my English waiting for
> a doc review.

Thanks.

I must confess that the new description is not much clearer than the
old one.  After reading it (more than once), I still have no clear
idea of the differences between these two commands.  It's obvious that
ptype does a more thorough job that whatis, but what exactly each one
does and does not do is still in the fog for me.

Below I try to ask specific questions in the hope that they will allow
to make this issue more clear.

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

Why is this important?  It doesn't belong to the differences between
the two commands, AFAIK, does it?

>                                      @code{whatis} prints the type of
> +@var{arg} as used in the source code

The "as used in the source code" part is confusing.  What exactly does
it mean, and how, if at all, is that different from ptype?

>                                       possibly including any typedefs.

"Possibly"?  You mean it sometimes does and sometimes does not?  If
so, when does it?

> +@code{whatis} never prints fields of compound types like @samp{struct}s.

This part is clear.

> +@code{whatis} unrolls in such case only one layer of outer typedef at a time.

This sounds incorrect, because your example says:

> +complex_t v;
>  [...]
>  (@value{GDBP}) whatis v
> +type = complex_t

That is, there's no "unrolling" here, not even of a single layer.
Unless I misunderstood what you mean by "unrolling", that is.

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

Not clear what that means.  whatis doesn't show struct members at all,
does it?  If so, how can it "preserve" those fields?

Btw, a stylistic point: don't leave whitespace around "---", it looks
ugly in print.

> +@code{ptype} always unrolls all outer typedefs contrary to @code{whatis}.

Instead of talking about "unrolling", wouldn't it be better to say
that ptype recursively looks up the definition of each type until it
arrives at primitive data types, and prints the result only then?

> +@code{ptype} of an expression (variable) will not print its real type including
> +possible typedefs as present in the source code

Not clear.  The "real" part is getting in the way.  Don't you mean
"literal", not "real"?

>                                            -- use @code{whatis} for that
                                             ^^
Please use 3 dashes in a row, not 2.

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

Not clear: what are "inner typedefs"?  If a struct has a member that
is itself a struct, what will ptype show about this member?

Also, since whatis does not show struct members at all (AFAIU), saying
"both" here is confusing and misleading, no?

I hope answering these questions will allow to rephrase the text so it
is both accurate and clear.

Thanks again for working on this.

Re: [doc patch] whatis vs. ptype - the difference

[Tom Tromey]

>>>>> "Jan" == Jan Kratochvil <jan.kratochvil@redhat.com> writes:

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

I think it is handy to have both options available.  And, compatibility
usually wins.  So I'd rather not change it.

However, we could also give ptype and whatis options, to let the user
choose another way.

Tom

Re: [doc patch] whatis vs. ptype - the difference

[Jan Kratochvil]

On Tue, 12 Jul 2011 22:10:38 +0200, Eli Zaretskii wrote:
> > +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.
> 
> Why is this important?  It doesn't belong to the differences between
> the two commands, AFAIK, does it?

There was not and even after my change there is not any special part of the
text describing the difference.  There is a description of `whatis' and
a description of `ptype'.

I would like a real table there but `info' never shows any real table.
Such as:
       | outer typedefs unrolling           | compound types
----------------------------------------------------------------------
whatis | vars: no unroll, types: one unroll | displayed only type name
ptype  | all unrolled                       | displayed both name and its fields

GDB is missing the ultimate command which would do always the right thing:
dream  | vars: no unroll, types: one unroll | displayed both name and its fields
 - but that is outside of the scope of this doc-only patch.


> >                                      @code{whatis} prints the type of
> > +@var{arg} as used in the source code
> 
> The "as used in the source code" part is confusing.  What exactly does
> it mean, and how, if at all, is that different from ptype?

whatis v -> complex_t
ptype v -> struct complex

The source code uses type `complex_t' type for the variable `v'.


> >                                       possibly including any typedefs.
> 
> "Possibly"?  You mean it sometimes does and sometimes does not?  If
> so, when does it?

"including any possible typedefs" may be right?

That is, if there are any typedefs they are included.  But sure there exist
variables having nothing to do with typedefs (`long x;').


> > +@code{whatis} never prints fields of compound types like @samp{struct}s.
> 
> This part is clear.
> 
> > +@code{whatis} unrolls in such case only one layer of outer typedef at a time.
> 
> This sounds incorrect, because your example says:
> 
> > +complex_t v;
> >  [...]
> >  (@value{GDBP}) whatis v
> > +type = complex_t
> 
> That is, there's no "unrolling" here, not even of a single layer.
> Unless I misunderstood what you mean by "unrolling", that is.

This "unrolls [...] only one layer" is in the paragraph "If @var{arg} is
a type name".  As `v' is a variable the paragraph "If @var{arg} is an
expression" applies instead (where no typedefs unrolling is stated).


> > +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}.
> 
> Not clear what that means.  whatis doesn't show struct members at all,
> does it?  If so, how can it "preserve" those fields?

That's true, my mistake, this should be removed from the `whatis' description.


> > +@code{ptype} always unrolls all outer typedefs contrary to @code{whatis}.
> 
> Instead of talking about "unrolling", wouldn't it be better to say
> that ptype recursively looks up the definition of each type until it
> arrives at primitive data types, and prints the result only then?

I would like to avoid "recursive" and keep more at the Frank Eigler's "unroll"
term to state that the first non-typedefs stops the "unrolling".  I found it
is a common confusion when explaining this difference that people think ptype
will display "double real" (and not "real_t real" as it displays).


> > +@code{ptype} of an expression (variable) will not print its real type including
> > +possible typedefs as present in the source code
> 
> Not clear.  The "real" part is getting in the way.  Don't you mean
> "literal", not "real"?

Maybe "literal".  I want to express the major defect of `ptype' - that `ptype v'
does not show `complex_t' anywhere.


> > +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}.
> 
> Not clear: what are "inner typedefs"?  If a struct has a member that
> is itself a struct, what will ptype show about this member?

I have demonstrated the behavior on the `real' field in the sample code.
Inside `struct[' - the `inner typedefs' - are never touched by `ptype'.


> Also, since whatis does not show struct members at all (AFAIU), saying
> "both" here is confusing and misleading, no?

Yes, right.


> I hope answering these questions will allow to rephrase the text so it
> is both accurate and clear.

Depending on your next mail I - or you if you wish - can update the patch.


Thanks,
Jan

Re: [doc patch] whatis vs. ptype - the difference

[Eli Zaretskii]

> Date: Tue, 12 Jul 2011 22:28:11 +0200
> From: Jan Kratochvil <jan.kratochvil@redhat.com>
> Cc: gdb-patches@sourceware.org
> 
> I would like a real table there but `info' never shows any real table.

??? We have @multitable, which is exactly what you want.

Thanks for the answers, I will try to suggest a rewording of the text
after I digest them.

Re: [doc patch] whatis vs. ptype - the difference

[Eli Zaretskii]

How about the text below?

The only nit that I'm not yet sure about is at the end: "typedefs
... at the pointer target".  What do you mean by that? can you show an
example?


 @item whatis [@var{arg}]
 Print the data type of @var{arg}, which can be either an expression
 or a name of 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 (@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.

 If @var{arg} is a variable or an expression, @code{whatis} prints its
 literal type as it is used in the source code.  If the type was
 defined using a @code{typedef}, @code{whatis} will @emph{not} print
 the data type underlying the @code{typedef}.  If the type of the
 variable or the expression is a compound data type, such as
 @code{struct} or  @code{class}, @code{whatis} never prints their
 fields or members.  It just prints the @code{struct}/@code{class}
 name (a.k.a.@: its @dfn{tag}).  If you want to see the members of
 such a compound data type, use @code{ptype}.

 If @var{arg} is a type name that was defined using @code{typedef},
 @code{whatis} @dfn{unrolls} only one level of that @code{typedef}.
 Unrolling means that @code{whatis} will show the underlying type used
 in the @code{typedef} declaration of @var{arg}.  However, if that
 underlying type is also a @code{typedef}, @code{whatis} will not
 unroll it.

 For C code, the type names may also have the form @samp{class
 @var{class-name}}, @samp{struct @var{struct-tag}}, @samp{union
 @var{union-tag}} or @samp{enum @var{enum-tag}}.
 [...]
 Contrary to @code{whatis}, @code{ptype} always unrolls any
 @code{typedef}s in its argument declaration, whether the argument is
 a variable, expression, or a data type.  This means that @code{ptype}
 of a variable or an expression will not print literally its type as
 present in the source code---use @code{whatis} for that.  Any
 @code{typedef}s in fields of a @samp{struct} or at the pointer target
 are always preserved by @code{ptype}.

Re: [doc patch] whatis vs. ptype - the difference

[Jan Kratochvil]

On Fri, 15 Jul 2011 11:04:51 +0200, Eli Zaretskii wrote:
> How about the text below?

Great; I just have changed there members->methods.

is a compound data type, such as
@code{struct} or  @code{class}, @code{whatis} never prints their
fields or [-members.-]{+methods.+}

IMO any "child" of a struct is a member.  Such member can be field, method or
typedef(*).  Therefore the text would either state just "member" or state
"field, method or typedef".  Stating "field or member" seems weird to me.

(*) That is a class typedef, not a subject of ptype unrolling.  class typedef
    is IMO an uncommon construct:
      class C { typedef int t; t i; } c;
    Plus whatis does not unroll one level, that is a bug, going to fix it.


> The only nit that I'm not yet sure about is at the end: "typedefs
> ... at the pointer target".  What do you mean by that? can you show an
> example?

Sorry, thanks for finding it.  So far I had wrong ptype expectation myself,
pointer target typedefs _are_ unrolled by typedef.  Changed the text + extended
the sample code accordingly.

First is included informal wdiff between Eli's text and this one.

The patch with ChangeLog at the bottom is against FSF GDB HEAD.


Thanks,
Jan


------------------------------------------------------------------------------
wdiff against Eli's text:

@@ -13876,7 +13876,7 @@ defined using a @code{typedef}, @code{whatis} will @emph{not} print
the data type underlying the @code{typedef}.  If the type of the
variable or the expression is a compound data type, such as
@code{struct} or  @code{class}, @code{whatis} never prints their
fields or [-members.-]{+methods.+}  It just prints the @code{struct}/@code{class}
name (a.k.a.@: its @dfn{tag}).  If you want to see the members of
such a compound data type, use @code{ptype}.

@@ -13901,9 +13901,10 @@ Contrary to @code{whatis}, @code{ptype} always unrolls any
@code{typedef}s in its argument declaration, whether the argument is
a variable, expression, or a data type.  This means that @code{ptype}
of a variable or an expression will not print literally its type as
present in the source code---use @code{whatis} for that.[-Any-]  @code{typedef}s[-in fields of a @samp{struct} or-] at
the pointer [-target-]{+or reference targets are also unrolled.  Only @code{typedef}s of+}
{+fields, methods and inner @code{class typedef}s of @code{struct}s,+}
{+@code{class}es and @code{union}s+} are [-always preserved by-]{+not unrolled even with+} @code{ptype}.

For example, for this variable declaration:

@@ -13911,7 +13912,8 @@ For example, for this variable declaration:
typedef double real_t;
struct complex @{ real_t real; double imag; @};
typedef struct complex complex_t;
complex_t [-v;-]{+var;+}
{+real_t *real_pointer_var;+}
@end smallexample

@noindent
@@ -13919,9 +13921,9 @@ the two commands give this output:

@smallexample
@group
(@value{GDBP}) whatis [-v-]{+var+}
type = complex_t
(@value{GDBP}) ptype [-v-]{+var+}
type = struct complex @{
    real_t real;
    double imag;
@@ -13935,6 +13937,10 @@ type = struct complex @{
    real_t real;
    double imag;
@}
{+(@value{GDBP}) whatis real_pointer_var+}
{+type = real_t *+}
{+(@value{GDBP}) ptype real_pointer_var+}
{+type = double *+}
@end group
@end smallexample


------------------------------------------------------------------------------
against FSF GDB HEAD:

2011-07-15  Jan Kratochvil  <jan.kratochvil@redhat.com>
	    Eli Zaretskii  <eliz@gnu.org>

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

--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -13862,16 +13862,34 @@ __read_nocancel + 6 in section .text of /usr/lib64/libc.so.6
 
 @kindex whatis
 @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}.
+Print the data type of @var{arg}, which can be either an expression
+or a name of 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 (@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.
+
+If @var{arg} is a variable or an expression, @code{whatis} prints its
+literal type as it is used in the source code.  If the type was
+defined using a @code{typedef}, @code{whatis} will @emph{not} print
+the data type underlying the @code{typedef}.  If the type of the
+variable or the expression is a compound data type, such as
+@code{struct} or  @code{class}, @code{whatis} never prints their
+fields or methods.  It just prints the @code{struct}/@code{class}
+name (a.k.a.@: its @dfn{tag}).  If you want to see the members of
+such a compound data type, use @code{ptype}.
+
+If @var{arg} is a type name that was defined using @code{typedef},
+@code{whatis} @dfn{unrolls} only one level of that @code{typedef}.
+Unrolling means that @code{whatis} will show the underlying type used
+in the @code{typedef} declaration of @var{arg}.  However, if that
+underlying type is also a @code{typedef}, @code{whatis} will not
+unroll it.
+
+For C code, the type names may also have the form @samp{class
+@var{class-name}}, @samp{struct @var{struct-tag}}, @samp{union
+@var{union-tag}} or @samp{enum @var{enum-tag}}.
 
 @kindex ptype
 @item ptype [@var{arg}]
@@ -13879,10 +13897,23 @@ 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}.
 
+Contrary to @code{whatis}, @code{ptype} always unrolls any
+@code{typedef}s in its argument declaration, whether the argument is
+a variable, expression, or a data type.  This means that @code{ptype}
+of a variable or an expression will not print literally its type as
+present in the source code---use @code{whatis} for that.  @code{typedef}s at
+the pointer or reference targets are also unrolled.  Only @code{typedef}s of
+fields, methods and inner @code{class typedef}s of @code{struct}s,
+@code{class}es and @code{union}s are not unrolled even with @code{ptype}.
+
 For example, for this variable declaration:
 
 @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 var;
+real_t *real_pointer_var;
 @end smallexample
 
 @noindent
@@ -13890,13 +13921,26 @@ the two commands give this output:
 
 @smallexample
 @group
-(@value{GDBP}) whatis v
+(@value{GDBP}) whatis var
+type = complex_t
+(@value{GDBP}) ptype var
+type = struct complex @{
+    real_t real;
+    double imag;
+@}
+(@value{GDBP}) whatis complex_t
+type = struct complex
+(@value{GDBP}) whatis struct complex
 type = struct complex
-(@value{GDBP}) ptype v
+(@value{GDBP}) ptype struct complex
 type = struct complex @{
-    double real;
+    real_t real;
     double imag;
 @}
+(@value{GDBP}) whatis real_pointer_var
+type = real_t *
+(@value{GDBP}) ptype real_pointer_var
+type = double *
 @end group
 @end smallexample
 

Re: [doc patch] whatis vs. ptype - the difference

[Pedro Alves]

On Friday 15 July 2011 16:33:35, Jan Kratochvil wrote:
> (*) That is a class typedef, not a subject of ptype unrolling.  class typedef
>     is IMO an uncommon construct:
>       class C { typedef int t; t i; } c;

It is very common with templates, things like:

template<class T> struct Foo {
  typedef std::map<std::string, T> MapType;
  ...
};

-- 
Pedro Alves

ping: Re: [doc patch] whatis vs. ptype - the difference

[Jan Kratochvil]

Hi Eli,

OK to check it in as is?

Thanks,
Jan


On Fri, 15 Jul 2011 17:33:35 +0200, Jan Kratochvil wrote:

On Fri, 15 Jul 2011 11:04:51 +0200, Eli Zaretskii wrote:
> How about the text below?

Great; I just have changed there members->methods.

is a compound data type, such as
@code{struct} or  @code{class}, @code{whatis} never prints their
fields or [-members.-]{+methods.+}

IMO any "child" of a struct is a member.  Such member can be field, method or
typedef(*).  Therefore the text would either state just "member" or state
"field, method or typedef".  Stating "field or member" seems weird to me.

(*) That is a class typedef, not a subject of ptype unrolling.  class typedef
    is IMO an uncommon construct:
      class C { typedef int t; t i; } c;
    Plus whatis does not unroll one level, that is a bug, going to fix it.


> The only nit that I'm not yet sure about is at the end: "typedefs
> ... at the pointer target".  What do you mean by that? can you show an
> example?

Sorry, thanks for finding it.  So far I had wrong ptype expectation myself,
pointer target typedefs _are_ unrolled by typedef.  Changed the text + extended
the sample code accordingly.

First is included informal wdiff between Eli's text and this one.

The patch with ChangeLog at the bottom is against FSF GDB HEAD.

------------------------------------------------------------------------------
wdiff against Eli's text:

@@ -13876,7 +13876,7 @@ defined using a @code{typedef}, @code{whatis} will @emph{not} print
the data type underlying the @code{typedef}.  If the type of the
variable or the expression is a compound data type, such as
@code{struct} or  @code{class}, @code{whatis} never prints their
fields or [-members.-]{+methods.+}  It just prints the @code{struct}/@code{class}
name (a.k.a.@: its @dfn{tag}).  If you want to see the members of
such a compound data type, use @code{ptype}.

@@ -13901,9 +13901,10 @@ Contrary to @code{whatis}, @code{ptype} always unrolls any
@code{typedef}s in its argument declaration, whether the argument is
a variable, expression, or a data type.  This means that @code{ptype}
of a variable or an expression will not print literally its type as
present in the source code---use @code{whatis} for that.[-Any-]  @code{typedef}s[-in fields of a @samp{struct} or-] at
the pointer [-target-]{+or reference targets are also unrolled.  Only @code{typedef}s of+}
{+fields, methods and inner @code{class typedef}s of @code{struct}s,+}
{+@code{class}es and @code{union}s+} are [-always preserved by-]{+not unrolled even with+} @code{ptype}.

For example, for this variable declaration:

@@ -13911,7 +13912,8 @@ For example, for this variable declaration:
typedef double real_t;
struct complex @{ real_t real; double imag; @};
typedef struct complex complex_t;
complex_t [-v;-]{+var;+}
{+real_t *real_pointer_var;+}
@end smallexample

@noindent
@@ -13919,9 +13921,9 @@ the two commands give this output:

@smallexample
@group
(@value{GDBP}) whatis [-v-]{+var+}
type = complex_t
(@value{GDBP}) ptype [-v-]{+var+}
type = struct complex @{
    real_t real;
    double imag;
@@ -13935,6 +13937,10 @@ type = struct complex @{
    real_t real;
    double imag;
@}
{+(@value{GDBP}) whatis real_pointer_var+}
{+type = real_t *+}
{+(@value{GDBP}) ptype real_pointer_var+}
{+type = double *+}
@end group
@end smallexample


------------------------------------------------------------------------------
against FSF GDB HEAD:

2011-07-15  Jan Kratochvil  <jan.kratochvil@redhat.com>
	    Eli Zaretskii  <eliz@gnu.org>

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

--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -13862,16 +13862,34 @@ __read_nocancel + 6 in section .text of /usr/lib64/libc.so.6
 
 @kindex whatis
 @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}.
+Print the data type of @var{arg}, which can be either an expression
+or a name of 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 (@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.
+
+If @var{arg} is a variable or an expression, @code{whatis} prints its
+literal type as it is used in the source code.  If the type was
+defined using a @code{typedef}, @code{whatis} will @emph{not} print
+the data type underlying the @code{typedef}.  If the type of the
+variable or the expression is a compound data type, such as
+@code{struct} or  @code{class}, @code{whatis} never prints their
+fields or methods.  It just prints the @code{struct}/@code{class}
+name (a.k.a.@: its @dfn{tag}).  If you want to see the members of
+such a compound data type, use @code{ptype}.
+
+If @var{arg} is a type name that was defined using @code{typedef},
+@code{whatis} @dfn{unrolls} only one level of that @code{typedef}.
+Unrolling means that @code{whatis} will show the underlying type used
+in the @code{typedef} declaration of @var{arg}.  However, if that
+underlying type is also a @code{typedef}, @code{whatis} will not
+unroll it.
+
+For C code, the type names may also have the form @samp{class
+@var{class-name}}, @samp{struct @var{struct-tag}}, @samp{union
+@var{union-tag}} or @samp{enum @var{enum-tag}}.
 
 @kindex ptype
 @item ptype [@var{arg}]
@@ -13879,10 +13897,23 @@ 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}.
 
+Contrary to @code{whatis}, @code{ptype} always unrolls any
+@code{typedef}s in its argument declaration, whether the argument is
+a variable, expression, or a data type.  This means that @code{ptype}
+of a variable or an expression will not print literally its type as
+present in the source code---use @code{whatis} for that.  @code{typedef}s at
+the pointer or reference targets are also unrolled.  Only @code{typedef}s of
+fields, methods and inner @code{class typedef}s of @code{struct}s,
+@code{class}es and @code{union}s are not unrolled even with @code{ptype}.
+
 For example, for this variable declaration:
 
 @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 var;
+real_t *real_pointer_var;
 @end smallexample
 
 @noindent
@@ -13890,13 +13921,26 @@ the two commands give this output:
 
 @smallexample
 @group
-(@value{GDBP}) whatis v
+(@value{GDBP}) whatis var
+type = complex_t
+(@value{GDBP}) ptype var
+type = struct complex @{
+    real_t real;
+    double imag;
+@}
+(@value{GDBP}) whatis complex_t
+type = struct complex
+(@value{GDBP}) whatis struct complex
 type = struct complex
-(@value{GDBP}) ptype v
+(@value{GDBP}) ptype struct complex
 type = struct complex @{
-    double real;
+    real_t real;
     double imag;
 @}
+(@value{GDBP}) whatis real_pointer_var
+type = real_t *
+(@value{GDBP}) ptype real_pointer_var
+type = double *
 @end group
 @end smallexample
 

Re: ping: Re: [doc patch] whatis vs. ptype - the difference

[Eli Zaretskii]

> Date: Tue, 26 Jul 2011 03:00:54 +0200
> From: Jan Kratochvil <jan.kratochvil@redhat.com>
> Cc: gdb-patches@sourceware.org
> 
> OK to check it in as is?

Yes, thanks.

Re: ping: Re: [doc patch] whatis vs. ptype - the difference

[Jan Kratochvil]

On Tue, 26 Jul 2011 04:55:01 +0200, Eli Zaretskii wrote:
> Yes, thanks.

Checked in:
	http://sourceware.org/ml/gdb-cvs/2011-07/msg00211.html


Thanks,
Jan