Libguestfs - Aug 2023 - [libnbd PATCH v4 15/25] info: Add --has alias for --can

'nbdinfo --has structured-reply' reads a bit more naturally than
'nbdinfo --can structured-reply'.  Even though the latter mirrors the
API name, it is not hard to add another alias to make our command-line
usage easier.

Suggested-by: Richard W.M. Jones <rjones at redhat.com>
Signed-off-by: Eric Blake <eblake at redhat.com>
---

v4: new patch
---
 info/nbdinfo.pod | 29 +++++++++++++++++++----------
 info/can.c       |  2 +-
 info/info-can.sh |  6 +++---
 info/main.c      |  4 +++-
 4 files changed, 26 insertions(+), 15 deletions(-)

diff --git a/info/nbdinfo.pod b/info/nbdinfo.pod
index 7eb3c1a0..72193c24 100644
--- a/info/nbdinfo.pod
+++ b/info/nbdinfo.pod
@@ -160,9 +160,9 @@ Test if we can connect to the NBD URI.

 Test if the NBD URI connection is using TLS.

-=item nbdinfo --can structured-reply URI
+=item nbdinfo --has structured-reply URI

-Test if server can respond with structured replies (a prerequisite
+Test if server has support for structured replies (a prerequisite
 for supporting block status commands).

 =item nbdinfo --is rotational URI
@@ -322,26 +322,23 @@ Display brief command line help and exit.

 =item B<--can read>

-=item B<--can structured-reply>
-
 =item B<--can trim>

 =item B<--can write>

 =item B<--can zero>

-Test properties of the NBD server export or the connection itself.
-The command does not print anything.  Instead it exits with success
-(S<exit code 0>) if true, or failure (S<exit code 2>) if false.
-(Other exit codes indicate an error querying the flag).
+Test properties of the NBD server export.  The command does not print
+anything.  Instead it exits with success (S<exit code 0>) if true, or
+failure (S<exit code 2>) if false.  (Other exit codes indicate an
+error querying the flag).

 For further information see the L<NBD
 protocol|https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md>
 and the following libnbd functions: L<nbd_can_cache(3)>,
 L<nbd_can_df(3)>, L<nbd_can_fast_zero(3)>,
L<nbd_can_flush(3)>,
 L<nbd_can_fua(3)>, L<nbd_can_multi_conn(3)>,
L<nbd_can_trim(3)>,
-L<nbd_can_zero(3)>, L<nbd_is_read_only(3)>,
-L<nbd_get_structured_replies_negotiated(3)>.
+L<nbd_can_zero(3)>, L<nbd_is_read_only(3)>.

 =item B<--color>

@@ -370,6 +367,18 @@ When using I<--list>, the default is
I<--no-content> (since
 downloading from each export is expensive).  To enable content probing
 use I<--list --content>.

+=item B<--has structured-reply>
+
+Test properties of the NBD server connection.  The command does not
+print anything.  Instead it exits with success (S<exit code 0>) if
+true, or failure (S<exit code 2>) if false.  (Other exit codes
+indicate an error querying the flag).
+
+For further information see the L<NBD
+protocol|https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md>
+and the following libnbd functions:
+L<nbd_get_structured_replies_negotiated(3)>.
+
 =item B<--is read-only>

 =item B<--is rotational>
diff --git a/info/can.c b/info/can.c
index 01ab4806..8514fd5a 100644
--- a/info/can.c
+++ b/info/can.c
@@ -92,7 +92,7 @@ do_can (void)
     feature = nbd_can_zero (nbd);

   else {
-    fprintf (stderr, "%s: unknown --can or --is option: %s\n",
+    fprintf (stderr, "%s: unknown --can/--is/--has option: %s\n",
              progname, can);
     exit (EXIT_FAILURE);
   }
diff --git a/info/info-can.sh b/info/info-can.sh
index 6cc8cbf4..13ef1032 100755
--- a/info/info-can.sh
+++ b/info/info-can.sh
@@ -38,11 +38,11 @@ requires bash -c "nbdkit sh --dump-plugin | grep
has_can_cache=1"
 # and oldstyle never, but that feels like depending a bit too much on
 # the implementation.

-# --can structured-reply is not a per-export setting, but rather
+# --has structured-reply is not a per-export setting, but rather
 # something set on the server as a whole.

 nbdkit -v -U - sh - \
-       --run '$VG nbdinfo --can structured-reply
"nbd+unix:///?socket=$unixsocket"' <<'EOF'
+       --run '$VG nbdinfo --has structured-reply
"nbd+unix:///?socket=$unixsocket"' <<'EOF'
 case "$1" in
   get_size) echo 1024 ;;
   pread) ;;
@@ -52,7 +52,7 @@ EOF

 st=0
 nbdkit -v -U - --no-sr sh - \
-       --run '$VG nbdinfo --can structured-reply
"nbd+unix:///?socket=$unixsocket"' <<'EOF' || st=$?
+       --run '$VG nbdinfo --has structured-reply
"nbd+unix:///?socket=$unixsocket"' <<'EOF' || st=$?
 case "$1" in
   get_size) echo 1024 ;;
   pread) ;;
diff --git a/info/main.c b/info/main.c
index c6b3fca0..dbcc5a14 100644
--- a/info/main.c
+++ b/info/main.c
@@ -119,6 +119,8 @@ main (int argc, char *argv[])
     { "no-colours",         no_argument,       NULL, NO_COLOUR_OPTION
},
     { "content",            no_argument,       NULL, CONTENT_OPTION
},
     { "no-content",         no_argument,       NULL,
NO_CONTENT_OPTION },
+    { "has",                required_argument, NULL, CAN_OPTION },
+    { "have",               required_argument, NULL, CAN_OPTION },
     { "is",                 required_argument, NULL, CAN_OPTION },
     { "json",               no_argument,       NULL, JSON_OPTION },
     { "list",               no_argument,       NULL, 'L' },
@@ -296,7 +298,7 @@ main (int argc, char *argv[])

   if (size_only)                /* --size (!list_all) */
     do_size ();
-  else if (can)                 /* --is/--can (!list_all) */
+  else if (can)                 /* --is/--can/--has (!list_all) */
     do_can ();
   else if (map)                 /* --map (!list_all) */
     do_map ();
-- 
2.41.0

On Wed, Aug 02, 2023 at 08:50:35PM -0500, Eric Blake
wrote:
> 'nbdinfo --has structured-reply' reads a bit more naturally than
> 'nbdinfo --can structured-reply'.  Even though the latter mirrors
the
> API name, it is not hard to add another alias to make our command-line
> usage easier.
> 
> Suggested-by: Richard W.M. Jones <rjones at redhat.com>
> Signed-off-by: Eric Blake <eblake at redhat.com>
Reviewed-by: Richard W.M. Jones <rjones at redhat.com>

No reason I can see to delay pushing this patch upstream right away.

Rich.
> ---
> 
> v4: new patch
> ---
>  info/nbdinfo.pod | 29 +++++++++++++++++++----------
>  info/can.c       |  2 +-
>  info/info-can.sh |  6 +++---
>  info/main.c      |  4 +++-
>  4 files changed, 26 insertions(+), 15 deletions(-)
> 
> diff --git a/info/nbdinfo.pod b/info/nbdinfo.pod
> index 7eb3c1a0..72193c24 100644
> --- a/info/nbdinfo.pod
> +++ b/info/nbdinfo.pod
> @@ -160,9 +160,9 @@ Test if we can connect to the NBD URI.
> 
>  Test if the NBD URI connection is using TLS.
> 
> -=item nbdinfo --can structured-reply URI
> +=item nbdinfo --has structured-reply URI
> 
> -Test if server can respond with structured replies (a prerequisite
> +Test if server has support for structured replies (a prerequisite
>  for supporting block status commands).
> 
>  =item nbdinfo --is rotational URI
> @@ -322,26 +322,23 @@ Display brief command line help and exit.
> 
>  =item B<--can read>
> 
> -=item B<--can structured-reply>
> -
>  =item B<--can trim>
> 
>  =item B<--can write>
> 
>  =item B<--can zero>
> 
> -Test properties of the NBD server export or the connection itself.
> -The command does not print anything.  Instead it exits with success
> -(S<exit code 0>) if true, or failure (S<exit code 2>) if
false.
> -(Other exit codes indicate an error querying the flag).
> +Test properties of the NBD server export.  The command does not print
> +anything.  Instead it exits with success (S<exit code 0>) if true,
or
> +failure (S<exit code 2>) if false.  (Other exit codes indicate an
> +error querying the flag).
> 
>  For further information see the L<NBD
> 
protocol|https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md>
>  and the following libnbd functions: L<nbd_can_cache(3)>,
>  L<nbd_can_df(3)>, L<nbd_can_fast_zero(3)>,
L<nbd_can_flush(3)>,
>  L<nbd_can_fua(3)>, L<nbd_can_multi_conn(3)>,
L<nbd_can_trim(3)>,
> -L<nbd_can_zero(3)>, L<nbd_is_read_only(3)>,
> -L<nbd_get_structured_replies_negotiated(3)>.
> +L<nbd_can_zero(3)>, L<nbd_is_read_only(3)>.
> 
>  =item B<--color>
> 
> @@ -370,6 +367,18 @@ When using I<--list>, the default is
I<--no-content> (since
>  downloading from each export is expensive).  To enable content probing
>  use I<--list --content>.
> 
> +=item B<--has structured-reply>
> +
> +Test properties of the NBD server connection.  The command does not
> +print anything.  Instead it exits with success (S<exit code 0>) if
> +true, or failure (S<exit code 2>) if false.  (Other exit codes
> +indicate an error querying the flag).
> +
> +For further information see the L<NBD
>
+protocol|https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md>
> +and the following libnbd functions:
> +L<nbd_get_structured_replies_negotiated(3)>.
> +
>  =item B<--is read-only>
> 
>  =item B<--is rotational>
> diff --git a/info/can.c b/info/can.c
> index 01ab4806..8514fd5a 100644
> --- a/info/can.c
> +++ b/info/can.c
> @@ -92,7 +92,7 @@ do_can (void)
>      feature = nbd_can_zero (nbd);
> 
>    else {
> -    fprintf (stderr, "%s: unknown --can or --is option: %s\n",
> +    fprintf (stderr, "%s: unknown --can/--is/--has option:
%s\n",
>               progname, can);
>      exit (EXIT_FAILURE);
>    }
> diff --git a/info/info-can.sh b/info/info-can.sh
> index 6cc8cbf4..13ef1032 100755
> --- a/info/info-can.sh
> +++ b/info/info-can.sh
> @@ -38,11 +38,11 @@ requires bash -c "nbdkit sh --dump-plugin | grep
has_can_cache=1"
>  # and oldstyle never, but that feels like depending a bit too much on
>  # the implementation.
> 
> -# --can structured-reply is not a per-export setting, but rather
> +# --has structured-reply is not a per-export setting, but rather
>  # something set on the server as a whole.
> 
>  nbdkit -v -U - sh - \
> -       --run '$VG nbdinfo --can structured-reply
"nbd+unix:///?socket=$unixsocket"' <<'EOF'
> +       --run '$VG nbdinfo --has structured-reply
"nbd+unix:///?socket=$unixsocket"' <<'EOF'
>  case "$1" in
>    get_size) echo 1024 ;;
>    pread) ;;
> @@ -52,7 +52,7 @@ EOF
> 
>  st=0
>  nbdkit -v -U - --no-sr sh - \
> -       --run '$VG nbdinfo --can structured-reply
"nbd+unix:///?socket=$unixsocket"' <<'EOF' || st=$?
> +       --run '$VG nbdinfo --has structured-reply
"nbd+unix:///?socket=$unixsocket"' <<'EOF' || st=$?
>  case "$1" in
>    get_size) echo 1024 ;;
>    pread) ;;
> diff --git a/info/main.c b/info/main.c
> index c6b3fca0..dbcc5a14 100644
> --- a/info/main.c
> +++ b/info/main.c
> @@ -119,6 +119,8 @@ main (int argc, char *argv[])
>      { "no-colours",         no_argument,       NULL,
NO_COLOUR_OPTION },
>      { "content",            no_argument,       NULL,
CONTENT_OPTION },
>      { "no-content",         no_argument,       NULL,
NO_CONTENT_OPTION },
> +    { "has",                required_argument, NULL, CAN_OPTION
},
> +    { "have",               required_argument, NULL, CAN_OPTION
},
>      { "is",                 required_argument, NULL, CAN_OPTION
},
>      { "json",               no_argument,       NULL, JSON_OPTION
},
>      { "list",               no_argument,       NULL, 'L'
},
> @@ -296,7 +298,7 @@ main (int argc, char *argv[])
> 
>    if (size_only)                /* --size (!list_all) */
>      do_size ();
> -  else if (can)                 /* --is/--can (!list_all) */
> +  else if (can)                 /* --is/--can/--has (!list_all) */
>      do_can ();
>    else if (map)                 /* --map (!list_all) */
>      do_map ();
> -- 
> 2.41.0
-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
virt-p2v converts physical machines to virtual machines.  Boot with a
live CD or over the network (PXE) and turn machines into KVM guests.
http://libguestfs.org/virt-v2v