[PATCHv2] gdb: add support for %V to printf command

  Tom Tromey <tom@tromey.com> writes:

>>>>>> "Andrew" == Andrew Burgess via Gdb-patches <gdb-patches@sourceware.org> writes:
>
> Andrew> This commit adds a new format for the printf and dprintf commands:
> Andrew> '%V'.  This new format takes any GDB expression and formats it as a
> Andrew> string, just as GDB would for a 'print' command, e.g.:
>
> Thank you for doing this.  I'm definitely a fan of the idea.
>
> Andrew> --- a/gdb/printcmd.c
> Andrew> +++ b/gdb/printcmd.c
> Andrew> @@ -2733,7 +2733,7 @@ ui_printf (const char *arg, struct ui_file *stream)
> Andrew>    if (*s++ != '"')
> Andrew>      error (_("Bad format string, missing '\"'."));
>  
> Andrew> -  format_pieces fpieces (&s);
> Andrew> +  format_pieces fpieces (&s, false, true);
>
> I was going to ask if there is a spot that sets gdb_extensions=false and
> the new flag=true.  This setting seems odd to me, but I didn't dig
> through to find out why it's needed.

I'm not 100% sure what you're asking here, so apologies if I just go
broad with my reply hoping I address your question.

The gdb_extensions flag turns on/off features are format_pieces that are
used internal by GDB, e.g. field width support and styling support.  We
don't want to allow these within printf/dprintf hence the first flag
being false in the above.

The new flag (value_extension) is separate, this is something (I
propose) we offer in printf/dprintf, but isn't something that I think we
should offer to GDB's internal print routines -- though that is
potentially an interesting idea?  But is more than I wanted to take on
in a first cut of this work.

Hopefully that explains why we have two separate flags, and why we see
the false/true combo above -- this is the printf code, so we don't want
the GDB internal printf features, but we do want the %V value extension.

>
> Andrew> +	      string_file buffer;
> Andrew> +	      print_formatted (val_args[i], 0, &print_opts, &buffer);
> Andrew> +	      gdb_puts (buffer.string ().c_str ());
>
> Why is a second stream needed here?  Like, couldn't print_formatted be
> called with 'stream'?  Wouldn't that preserve any styling done by
> print_formatted?  Or is the intention to strip styling?

The intention was to remove any styling.  But thinking about it a little
more, I don't think we actually style any value text right now.  So
given the extra overhead, it's probably best to just go directly to
stream.

... but I'm glad you said something, notice the gdb_puts call doesn't
actually write to stream, but instead always writes to gdb_stdout --
that's a bug :/

Anyway, simplified to write directly to stream now.

>
> Andrew> +	    if (f[1] == '[')
> Andrew> +	      {
> Andrew> +		const char *tmp;
> Andrew> +		for (tmp = f; *tmp != ']' && *tmp != '\0'; ++tmp)
> Andrew> +		  ;
> Andrew> +		if (*tmp == ']')
> Andrew> +		  f = tmp;
>
> strchr if it simplifies things.

It does.  Done.

>
> I didn't dig into this either, but I don't think %V could work in
> dprintf's call or agent modes.  So, maybe gdb should reject this
> somewhere.  Or maybe this is already done by the default setting in the
> constructor?

You're right that %V isn't going to work with 'agent' mode.  For 'call'
mode, I think my answer is, well... maybe...

In call mode I don't think we should validate the format string at
all -- we certainly don't right now.  The user might be calling a
function that already supports custom format specifiers, maybe even
including '%V', and that's fine, I don't see any problem with that.  In
'call' mode we just forward the format string and arguments as the user
wrote them.  What I have done is extend the documentation to make it
clear in this case that support for '%V' (or any format specifier)
depends on the output function being used.

In agent mode the user will get an error just as they would with any
other unknown format specifier.  Currently the only place we accept '%V'
is when handling a 'printf' -- the 'agent-printf' code (which is used
when in 'agent' style) doesn't check for '%V' and so will error if one
is seen.  I've extended the documentation to make this clear.

So I think this last concern is addressed by extending the
documentation.

The updated patch is below.  Let me know what you think.

Thanks,
Andrew

---

Changes since V1:

  - Documentation extensions to explain support for %V in different
    dprintf styles,

  - Write value directly to stream in ui_printf (printcmd.c),

  - Use of strchr to simplify code in format_pieces::format_pieces
    (format.cc).

---

commit df87c78703e6b5585bb6a63fc2799fd0348e36c5
Author: Andrew Burgess <aburgess@redhat.com>
Date:   Thu Mar 23 12:12:38 2023 +0000

    gdb: add support for %V to printf command
    
    This commit adds a new format for the printf and dprintf commands:
    '%V'.  This new format takes any GDB expression and formats it as a
    string, just as GDB would for a 'print' command, e.g.:
    
      (gdb) print a1
      $a = {2, 4, 6, 8, 10, 12, 14, 16, 18, 20}
      (gdb) printf "%V\n", a1
      {2, 4, 6, 8, 10, 12, 14, 16, 18, 20}
      (gdb)
    
    It is also possible to pass the same options to %V as you might pass
    to the print command, e.g.:
    
      (gdb) print -elements 3 -- a1
      $4 = {2, 4, 6...}
      (gdb) printf "%V[-elements 3]\n", a1
      {2, 4, 6...}
      (gdb)
    
    This new feature would effectively replace an existing feature of GDB,
    the $_as_string builtin convenience function.  However, the
    $_as_string function has a few problems which this new feature solves:
    
    1. $_as_string doesn't currently work when the inferior is not
    running, e.g:
    
      (gdb) printf "%s", $_as_string(a1)
      You can't do that without a process to debug.
      (gdb)
    
    The reason for this is that $_as_string returns a value object with
    string type.  When we try to print this we call value_as_address,
    which ends up trying to push the string into the inferior's address
    space.
    
    Clearly we could solve this problem, the string data exists in GDB, so
    there's no reason why we have to push it into the inferior, but this
    is an existing problem that would need solving.
    
    2. $_as_string suffers from the fact that C degrades arrays to
    pointers, e.g.:
    
      (gdb) printf "%s\n", $_as_string(a1)
      0x404260 <a1>
      (gdb)
    
    The implementation of $_as_string is passed a gdb.Value object that is
    a pointer, it doesn't understand that it's actually an array.  Solving
    this would be harder than issue #1 I think.  The whole array to
    pointer transformation is part of our expression evaluation.  And in
    most cases this is exactly what we want.  It's not clear to me how
    we'd (easily) tell GDB that we didn't want this reduction in _some_
    cases.  But I'm sure this is solvable if we really wanted to.
    
    3. $_as_string is a gdb.Function sub-class, and as such is passed
    gdb.Value objects.  There's no super convenient way to pass formatting
    options to $_as_string.  By this I mean that the new %V feature
    supports print formatting options.  Ideally, we might want to add this
    feature to $_as_string, we might imagine it working something like:
    
      (gdb) printf "%s\n", $_as_string(a1,
                                       elements = 3,
                                       array_indexes = True)
    
    where the first item is the value to print, while the remaining
    options are the print formatting options.  However, this relies on
    Python calling syntax, which isn't something that convenience
    functions handle.  We could possibly rely on strictly positional
    arguments, like:
    
      (gdb) printf "%s\n", $_as_string(a1, 3, 1)
    
    But that's clearly terrible as there's far more print formatting
    options, and if you needed to set the 9th option you'd need to fill in
    all the previous options.
    
    And right now, the only way to pass these options to a gdb.Function is
    to have GDB first convert them all into gdb.Value objects, which is
    really overkill for what we want.
    
    The new %V format solves all these problems: the string is computed
    and printed entirely on the GDB side, we are able to print arrays as
    actual arrays rather than pointers, and we can pass named format
    arguments.
    
    Finally, the $_as_string is sold in the manual as allowing users to
    print the string representation of flag enums, so given:
    
      enum flags
        {
          FLAG_A = (1 << 0),
          FLAG_B = (1 << 1),
          FLAG_C = (1 << 1)
        };
    
      enum flags ff = FLAG_B;
    
    We can:
    
      (gdb) printf "%s\n", $_as_string(ff)
      FLAG_B
    
    This works just fine with %V too:
    
      (gdb) printf "%V\n", ff
      FLAG_B
    
    So all functionality of $_as_string is replaced by %V.  I'm not
    proposing to remove $_as_string, there might be users currently
    depending on it, but I am proposing that we don't push $_as_string in
    the documentation.
    
    As %V is a feature of printf, GDB's dprintf breakpoints naturally gain
    access to this feature too.  dprintf breakpoints can be operated in
    three different styles 'gdb' (use GDB's printf), 'call' (call a
    function in the inferior), or 'agent' (perform the dprintf on the
    remote).
    
    The use of '%V' will work just fine when dprintf-style is 'gdb'.
    
    When dprintf-style is 'call' the format string and arguments are
    passed to an inferior function (printf by default).  In this case GDB
    doesn't prevent use of '%V', but the documentation makes it clear that
    support for '%V' will depend on the inferior function being called.
    
    I chose this approach because the current implementation doesn't place
    any restrictions on the format string when operating in 'call' style.
    That is, the user might already be calling a function that supports
    custom print format specifiers (maybe including '%V') so, I claim, it
    would be wrong to block use of '%V' in this case.  The documentation
    does make it clear that users shouldn't expect this to "just work"
    though.
    
    When dprintf-style is 'agent' then GDB does no support the use of
    '%V' (right now).  This is handled at the point when GDB tries to
    process the format string and send the dprintf command to the remote,
    here's an example:
    
      Reading symbols from /tmp/hello.x...
      (gdb) dprintf call_me, "%V", a1
      Dprintf 1 at 0x401152: file /tmp/hello.c, line 8.
      (gdb) set sysroot /
      (gdb) target remote | gdbserver --once - /tmp/hello.x
      Remote debugging using | gdbserver --once - /tmp/hello.x
      stdin/stdout redirected
      Process /tmp/hello.x created; pid = 3088822
      Remote debugging using stdio
      Reading symbols from /lib64/ld-linux-x86-64.so.2...
      (No debugging symbols found in /lib64/ld-linux-x86-64.so.2)
      0x00007ffff7fd3110 in _start () from /lib64/ld-linux-x86-64.so.2
      (gdb) set dprintf-style agent
      (gdb) c
      Continuing.
      Unrecognized format specifier 'V' in printf
      Command aborted.
      (gdb)
    
    This is exactly how GDB would handle any other invalid format
    specifier, for example:
    
      Reading symbols from /tmp/hello.x...
      (gdb) dprintf call_me, "%Q", a1
      Dprintf 1 at 0x401152: file /tmp/hello.c, line 8.
      (gdb) set sysroot /
      (gdb) target remote | gdbserver --once - /tmp/hello.x
      Remote debugging using | gdbserver --once - /tmp/hello.x
      stdin/stdout redirected
      Process /tmp/hello.x created; pid = 3089193
      Remote debugging using stdio
      Reading symbols from /lib64/ld-linux-x86-64.so.2...
      (No debugging symbols found in /lib64/ld-linux-x86-64.so.2)
      0x00007ffff7fd3110 in _start () from /lib64/ld-linux-x86-64.so.2
      (gdb) set dprintf-style agent
      (gdb) c
      Continuing.
      Unrecognized format specifier 'Q' in printf
      Command aborted.
      (gdb)
    
    The error message isn't the greatest, but improving that can be put
    off for another day I hope.
  

> From: Andrew Burgess <aburgess@redhat.com>
> Date: Fri, 28 Apr 2023 14:14:18 +0100
> 
> --- a/gdb/NEWS
> +++ b/gdb/NEWS
> @@ -67,6 +67,15 @@
>      break foo thread 1 task 1
>      watch var thread 2 task 3
>  
> +* The printf command now accepts a '%V' output format which will
> +  format an expression just as the 'print' command would.  Print
> +  options can be placed withing '[...]' after the '%V' to modify how
> +  the value is printed.  E.g:
> +    printf "%V", some_array
> +    printf "%V[-array-indexes on]", some_array
> +  will print the array without, or with array indexes included, just
> +  as the array would be printed by the 'print' command.

Should this mention the effect on dprintf?

>  @kindex dprintf-style gdb
> -Handle the output using the @value{GDBN} @code{printf} command.
> +Handle the output using the @value{GDBN} @code{printf} command.  When
> +using this style it is possible to use the @samp{%V} format specifier
                   ^
A comma missing there.

> +Most of @value{GDB}'s format specifiers align with those supported by
> +the @code{printf} function, however, @value{GDB}'s @samp{%V} format
> +specifier extension is not supported by @code{printf}.  When using
> +@samp{call} style dprintf care should be taken to ensure that only
                            ^
Comma missing.

> +format specifiers supported by the output function are used otherwise
                                                              ^
And another one.

> +@anchor{%V Format Specifier}
> +Additionally, @code{printf} supports a special @samp{%V} output format.
> +This format prints the string representation of an expression just as
> +@value{GDBN} would produce with the standard @kbd{print} command
> +(@pxref{Data, ,Examining Data}):
> +
> +@smallexample
> +(@value{GDBP}) print array
> +$1 = @{0, 1, 2, 3, 4, 5@}
> +(@value{GDBP}) printf "Array is: %V\n", array
> +Array is: @{0, 1, 2, 3, 4, 5@}
> +@end smallexample
> +
> +Additionally, it is possible to include print options with the
> +@samp{%V} format by placing them in @samp{[...]} immediately after the
> +@samp{%V}, like this:

There are two "additionally" here, and I wonder whether replacing one
of tyhem with "also" would read better.

> +If you need to print a literal @samp{[} directly after a @samp{%V} then
                                                                     ^
Comma missing.

Thanks.

Reviewed-By: Eli Zaretskii <eliz@gnu.org>