There is no man page for xenstore-list, add it.

Signed-off-by: Juergen Gross <jgross@suse.com>
---
 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@lists.xenproject.org, see
+https://wiki.xenproject.org/wiki/Reporting_Bugs_against_Xen_Project on how to send bug reports.
-- 
2.53.0

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@suse.com>
> ---
>  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@lists.xenproject.org, 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?

Even for the options; xenstore-ls uses -f for full path and -p for
permissions.


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.

~Andrew

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@suse.com>
>> ---
>>   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@lists.xenproject.org, 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