Re: [PATCH 2/4] docs: add man page for xenstore-list

[Jürgen Groß <jgross@xxxxxxxx>]

On 12.03.26 13:59, Andrew Cooper wrote:
> On 12/03/2026 12:22 pm, Juergen Gross wrote:
> > There is no man page for xenstore-list, add it.
> >
> > Signed-off-by: Juergen Gross <jgross@xxxxxxxx>
> > ---
> >   docs/man/xenstore-list.1.pod | 24 ++++++++++++++++++++++++
> >   1 file changed, 24 insertions(+)
> >   create mode 100644 docs/man/xenstore-list.1.pod
> >
> > diff --git a/docs/man/xenstore-list.1.pod b/docs/man/xenstore-list.1.pod
> > new file mode 100644
> > index 0000000000..4bc1ff9846
> > --- /dev/null
> > +++ b/docs/man/xenstore-list.1.pod
> > @@ -0,0 +1,24 @@
> > +=head1 NAME
> > +
> > +xenstore-list - list Xenstore key children
> > +
> > +=head1 SYNOPSIS
> > +
> > +B<xenstore-list> [I<OPTION>]... [I<PATH>]...
> > +
> > +=head1 DESCRIPTION
> > +
> > +List direct children of one or more Xenstore I<PATH>s, one child per line.
> > +
> > +=over
> > +
> > +=item B<-p>
> > +
> > +List the full Xenstore path of each listed path.
> > +
> > +=back
> > +
> > +=head1 BUGS
> > +
> > +Send bugs to xen-devel@xxxxxxxxxxxxxxxxxxxx, see
> > +https://wiki.xenproject.org/wiki/Reporting_Bugs_against_Xen_Project on how to 
> > send bug reports.
> I had no idea we even had this...  Why on earth do we have both
> xenstore-ls and xenstore-list, and for them to be different?
I would think the use cases are different, but this is pure speculation.

xenstore-list might be intended to be used by scripts, while xenstore-ls
seems to target human readers of the output.

> Even for the options; xenstore-ls uses -f for full path and -p for
> permissions.
Yes, this is weird. And "xenstore-list -p /" will print:

//local
//tools

which is not what I'd expect. :-(

> Having both is gross error on behalf of whomever accepted the code in
> the first place.  It's a bad enough usability problem that I think we
> should seriously consider deleting the binary rather than allowing
> accepting it's existance.
>
> But as I expect that to be controversial, at a minimum both of the
> manpages need some kind of "do not confuse $THIS with $OTHER" warning.
Its not as if one of those would cause any harm.


Juergen

Attachment: OpenPGP_0xB0DE9DD628BF132F.asc
Description: OpenPGP public key

Attachment: OpenPGP_signature.asc
Description: OpenPGP digital signature