Libguestfs - Aug 2019 - [PATCH libnbd 1/3] api: Change nbd_read_only -> nbd_is_read_only.

One API change, some small documentation changes.

This makes it consistent with other nbd_is_* and nbd_can_* APIs.

Suggested by Thomas Haller.
---
 docs/libnbd.pod                      | 2 +-
 examples/batched-read-write.c        | 2 +-
 examples/simple-reads-and-writes.c   | 2 +-
 examples/threaded-reads-and-writes.c | 2 +-
 generator/generator                  | 2 +-
 lib/flags.c                          | 2 +-
 lib/rw.c                             | 6 +++---
 tests/aio-parallel-load.c            | 2 +-
 tests/aio-parallel.c                 | 2 +-
 tests/read-only-flag.c               | 4 ++--
 tests/read-write-flag.c              | 4 ++--
 tests/synch-parallel.c               | 2 +-
 12 files changed, 16 insertions(+), 16 deletions(-)

diff --git a/docs/libnbd.pod b/docs/libnbd.pod
index 74227fd..6a329d6 100644
--- a/docs/libnbd.pod
+++ b/docs/libnbd.pod
@@ -383,7 +383,7 @@ the export, such as whether it is writable and if it can
support flush
 to permanent storage.  These flags can be accessed from libnbd using
 APIs such as:
 
- int is_read_only = nbd_read_only (nbd);
+ int is_read_only = nbd_is_read_only (nbd);
  int can_flush = nbd_can_flush (nbd);
 
 (and several more, see L<libnbd-api(3)>).
diff --git a/examples/batched-read-write.c b/examples/batched-read-write.c
index 9d2c02b..d39a1e5 100644
--- a/examples/batched-read-write.c
+++ b/examples/batched-read-write.c
@@ -160,7 +160,7 @@ main (int argc, char *argv[])
     }
   }
 
-  if (nbd_read_only (nbd) == 1) {
+  if (nbd_is_read_only (nbd) == 1) {
     fprintf (stderr, "%s: error: this NBD export is read-only\n",
argv[0]);
     exit (EXIT_FAILURE);
   }
diff --git a/examples/simple-reads-and-writes.c
b/examples/simple-reads-and-writes.c
index 0c80e6d..b429d2f 100644
--- a/examples/simple-reads-and-writes.c
+++ b/examples/simple-reads-and-writes.c
@@ -47,7 +47,7 @@ main (int argc, char *argv[])
   }
   assert (exportsize >= sizeof buf);
 
-  if (nbd_read_only (nbd) == 1) {
+  if (nbd_is_read_only (nbd) == 1) {
     fprintf (stderr, "%s: error: this NBD export is read-only\n",
argv[0]);
     exit (EXIT_FAILURE);
   }
diff --git a/examples/threaded-reads-and-writes.c
b/examples/threaded-reads-and-writes.c
index 5fff50c..85d6e42 100644
--- a/examples/threaded-reads-and-writes.c
+++ b/examples/threaded-reads-and-writes.c
@@ -116,7 +116,7 @@ main (int argc, char *argv[])
     exit (EXIT_FAILURE);
   }
 
-  if (nbd_read_only (nbd) == 1) {
+  if (nbd_is_read_only (nbd) == 1) {
     fprintf (stderr, "%s: error: this NBD export is read-only\n",
argv[0]);
     exit (EXIT_FAILURE);
   }
diff --git a/generator/generator b/generator/generator
index 7328438..132d6cb 100755
--- a/generator/generator
+++ b/generator/generator
@@ -1231,7 +1231,7 @@ behave like inetd clients, such as C<nbdkit
--single>.
 See also C<nbd_kill_command>.";
   };
 
-  "read_only", {
+  "is_read_only", {
     default_call with
     args = []; ret = RBool;
     permitted_states = [ Connected; Closed ];
diff --git a/lib/flags.c b/lib/flags.c
index cdbc28f..2bcacb8 100644
--- a/lib/flags.c
+++ b/lib/flags.c
@@ -65,7 +65,7 @@ get_flag (struct nbd_handle *h, uint16_t flag)
 }
 
 int
-nbd_unlocked_read_only (struct nbd_handle *h)
+nbd_unlocked_is_read_only (struct nbd_handle *h)
 {
   return get_flag (h, NBD_FLAG_READ_ONLY);
 }
diff --git a/lib/rw.c b/lib/rw.c
index bba62be..50ba23d 100644
--- a/lib/rw.c
+++ b/lib/rw.c
@@ -341,7 +341,7 @@ nbd_unlocked_aio_pwrite_callback (struct nbd_handle *h,
const void *buf,
 {
   struct command_cb cb = { .completion = completion, .user_data = user_data, };
 
-  if (nbd_unlocked_read_only (h) == 1) {
+  if (nbd_unlocked_is_read_only (h) == 1) {
     set_error (EINVAL, "server does not support write operations");
     return -1;
   }
@@ -406,7 +406,7 @@ nbd_unlocked_aio_trim_callback (struct nbd_handle *h,
 {
   struct command_cb cb = { .completion = completion, .user_data = user_data, };
 
-  if (nbd_unlocked_read_only (h) == 1) {
+  if (nbd_unlocked_is_read_only (h) == 1) {
     set_error (EINVAL, "server does not support write operations");
     return -1;
   }
@@ -482,7 +482,7 @@ nbd_unlocked_aio_zero_callback (struct nbd_handle *h,
 {
   struct command_cb cb = { .completion = completion, .user_data = user_data, };
 
-  if (nbd_unlocked_read_only (h) == 1) {
+  if (nbd_unlocked_is_read_only (h) == 1) {
     set_error (EINVAL, "server does not support write operations");
     return -1;
   }
diff --git a/tests/aio-parallel-load.c b/tests/aio-parallel-load.c
index ce39140..f4ba635 100644
--- a/tests/aio-parallel-load.c
+++ b/tests/aio-parallel-load.c
@@ -231,7 +231,7 @@ start_thread (void *arg)
 
   assert (nbd_get_size (nbd) == EXPORTSIZE);
   assert (nbd_can_multi_conn (nbd) > 0);
-  assert (nbd_read_only (nbd) == 0);
+  assert (nbd_is_read_only (nbd) == 0);
 
   /* Issue commands. */
   assert (nbd_aio_in_flight (nbd) == 0);
diff --git a/tests/aio-parallel.c b/tests/aio-parallel.c
index 166b560..f8d4891 100644
--- a/tests/aio-parallel.c
+++ b/tests/aio-parallel.c
@@ -239,7 +239,7 @@ start_thread (void *arg)
 
   assert (nbd_get_size (nbd) == EXPORTSIZE);
   assert (nbd_can_multi_conn (nbd) > 0);
-  assert (nbd_read_only (nbd) == 0);
+  assert (nbd_is_read_only (nbd) == 0);
 
   /* Issue commands. */
   assert (nbd_aio_in_flight (nbd) == 0);
diff --git a/tests/read-only-flag.c b/tests/read-only-flag.c
index da55bf8..7f51f74 100644
--- a/tests/read-only-flag.c
+++ b/tests/read-only-flag.c
@@ -16,7 +16,7 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  */
 
-/* Simple end-to-end test of nbdkit -r / nbd_read_only. */
+/* Simple end-to-end test of nbdkit -r / nbd_is_read_only. */
 
 #include <config.h>
 
@@ -43,7 +43,7 @@ main (int argc, char *argv[])
     exit (EXIT_FAILURE);
   }
 
-  if ((r = nbd_read_only (nbd)) == -1) {
+  if ((r = nbd_is_read_only (nbd)) == -1) {
     fprintf (stderr, "%s\n", nbd_get_error ());
     exit (EXIT_FAILURE);
   }
diff --git a/tests/read-write-flag.c b/tests/read-write-flag.c
index 3e33473..ad14a46 100644
--- a/tests/read-write-flag.c
+++ b/tests/read-write-flag.c
@@ -16,7 +16,7 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  */
 
-/* Simple end-to-end test of nbdkit without -r / nbd_read_only. */
+/* Simple end-to-end test of nbdkit without -r / nbd_is_read_only. */
 
 #include <config.h>
 
@@ -42,7 +42,7 @@ main (int argc, char *argv[])
     exit (EXIT_FAILURE);
   }
 
-  if ((r = nbd_read_only (nbd)) == -1) {
+  if ((r = nbd_is_read_only (nbd)) == -1) {
     fprintf (stderr, "%s\n", nbd_get_error ());
     exit (EXIT_FAILURE);
   }
diff --git a/tests/synch-parallel.c b/tests/synch-parallel.c
index 136bc60..40df85d 100644
--- a/tests/synch-parallel.c
+++ b/tests/synch-parallel.c
@@ -207,7 +207,7 @@ start_thread (void *arg)
 
   assert (nbd_get_size (nbd) == EXPORTSIZE);
   assert (nbd_can_multi_conn (nbd) > 0);
-  assert (nbd_read_only (nbd) == 0);
+  assert (nbd_is_read_only (nbd) == 0);
 
   /* Issue commands. */
   while (1) {
-- 
2.22.0

Suggested by Thomas Haller.
---
 generator/generator | 36 +++++++++++++++++++++++++-----------
 1 file changed, 25 insertions(+), 11 deletions(-)

diff --git a/generator/generator b/generator/generator
index 132d6cb..6621bee 100755
--- a/generator/generator
+++ b/generator/generator
@@ -893,6 +893,9 @@ let default_call = { args = []; ret = RErr;
                      permitted_states = [];
                      is_locked = true; may_set_error = true;
                      first_version = (1, 0) }
+let non_blocking_test_call_description = "\n
+This call does not block, because it returns data that is saved in
+the handle from the NBD protocol handshake."
 
 (* Calls.
  *
@@ -1238,7 +1241,8 @@ See also C<nbd_kill_command>.";
     shortdesc = "is the NBD export read-only?";
     longdesc = "\
 Returns true if the NBD export is read-only; writes and
-write-like operations will fail.";
+write-like operations will fail."
+^ non_blocking_test_call_description;
   };
 
   "can_flush", {
@@ -1249,7 +1253,8 @@ write-like operations will fail.";
     longdesc = "\
 Returns true if the server supports the flush command
 (see C<nbd_flush>, C<nbd_aio_flush>).  Returns false if
-the server does not.";
+the server does not."
+^ non_blocking_test_call_description;
   };
 
   "can_fua", {
@@ -1259,7 +1264,8 @@ the server does not.";
     shortdesc = "does the server support the FUA flag?";
     longdesc = "\
 Returns true if the server supports the FUA flag on
-certain commands (see C<nbd_pwrite>).";
+certain commands (see C<nbd_pwrite>)."
+^ non_blocking_test_call_description;
   };
 
   "is_rotational", {
@@ -1271,7 +1277,8 @@ certain commands (see C<nbd_pwrite>).";
 Returns true if the disk exposed over NBD is rotational
 (like a traditional floppy or hard disk).  Returns false if
 the disk has no penalty for random access (like an SSD or
-RAM disk).";
+RAM disk)."
+^ non_blocking_test_call_description;
   };
 
   "can_trim", {
@@ -1282,7 +1289,8 @@ RAM disk).";
     longdesc = "\
 Returns true if the server supports the trim command
 (see C<nbd_trim>, C<nbd_aio_trim>).  Returns false if
-the server does not.";
+the server does not."
+^ non_blocking_test_call_description;
   };
 
   "can_zero", {
@@ -1293,7 +1301,8 @@ the server does not.";
     longdesc = "\
 Returns true if the server supports the zero command
 (see C<nbd_zero>, C<nbd_aio_zero>).  Returns false if
-the server does not.";
+the server does not."
+^ non_blocking_test_call_description;
   };
 
   "can_df", {
@@ -1304,7 +1313,8 @@ the server does not.";
 Returns true if the server supports structured reads with an
 ability to request a non-fragmented read (see C<nbd_pread_structured>,
 C<nbd_aio_pread_structured>).  Returns false if the server either lacks
-structured reads or if it does not support a non-fragmented read
request.";
+structured reads or if it does not support a non-fragmented read request."
+^ non_blocking_test_call_description;
   };
 
   "can_multi_conn", {
@@ -1321,7 +1331,8 @@ same server if you will write to the server and the
 server does not advertize multi-conn support.  The safe
 way to check for this is to open one connection, check
 this flag is true, then open further connections as
-required.";
+required."
+^ non_blocking_test_call_description;
   };
 
   "can_cache", {
@@ -1332,7 +1343,8 @@ required.";
     longdesc = "\
 Returns true if the server supports the cache command
 (see C<nbd_cache>, C<nbd_aio_cache>).  Returns false if
-the server does not.";
+the server does not."
+^ non_blocking_test_call_description;
   };
 
   "can_meta_context", {
@@ -1349,7 +1361,8 @@ The single parameter is the name of the metadata context,
 for example C<LIBNBD_CONTEXT_BASE_ALLOCATION>.
 B<E<lt>libnbd.hE<gt>> includes defined constants for
well-known
 namespace contexts beginning with C<LIBNBD_CONTEXT_>, but you
-are free to pass in other contexts.";
+are free to pass in other contexts."
+^ non_blocking_test_call_description;
   };
 
   "get_size", {
@@ -1358,7 +1371,8 @@ are free to pass in other contexts.";
     permitted_states = [ Connected; Closed ];
     shortdesc = "return the export size";
     longdesc = "\
-Returns the size in bytes of the NBD export.";
+Returns the size in bytes of the NBD export."
+^ non_blocking_test_call_description;
   };
 
   "pread", {
-- 
2.22.0

Suggested by Nick Clifton.
---
 docs/libnbd.pod     | 10 ++++++++++
 generator/generator |  1 +
 2 files changed, 11 insertions(+)

diff --git a/docs/libnbd.pod b/docs/libnbd.pod
index 6a329d6..b42d000 100644
--- a/docs/libnbd.pod
+++ b/docs/libnbd.pod
@@ -13,6 +13,7 @@ libnbd - network block device (NBD) client library in
userspace
      nbd_connect_tcp (nbd, "server.example.com", "nbd") ==
-1 ||
      nbd_pread (nbd, buf, sizeof buf, 0, 0) == -1)
    fprintf (stderr, "%s\n", nbd_get_error ());
+   nbd_close (nbd);
    exit (EXIT_FAILURE);
  }
  nbd_close (nbd);
@@ -80,10 +81,12 @@ Create a handle and connect to the server:
  nbd = nbd_create ();
  if (!nbd) {
    fprintf (stderr, "%s\n", nbd_get_error ());
+   nbd_close (nbd);
    exit (EXIT_FAILURE);
  }
  if (nbd_connect_tcp (nbd, "server.example.com", "nbd") ==
-1) {
    fprintf (stderr, "%s\n", nbd_get_error ());
+   nbd_close (nbd);
    exit (EXIT_FAILURE);
  }
 
@@ -93,6 +96,7 @@ Read the first sector (512 bytes) from the NBD export:
  
  if (nbd_pread (nbd, buf, sizeof buf, 0, 0) == -1) {
    fprintf (stderr, "%s\n", nbd_get_error ());
+   nbd_close (nbd);
    exit (EXIT_FAILURE);
  }
 
@@ -125,6 +129,7 @@ example the asynchronous variant of C<nbd_pread> is:
  cookie = nbd_aio_pread (nbd, buf, sizeof buf, 0, 0);
  if (cookie == -1) {
    fprintf (stderr, "%s\n", nbd_get_error ());
+   nbd_close (nbd);
    exit (EXIT_FAILURE);
  }
 
@@ -222,6 +227,7 @@ As with the high level API, it all starts by creating a
handle:
  nbd = nbd_create ();
  if (nbd == NULL) {
    fprintf (stderr, "%s\n", nbd_get_error ());
+   nbd_close (nbd);
    exit (EXIT_FAILURE);
  }
 
@@ -237,11 +243,13 @@ until the connection becomes ready:
     then ... */
  if (nbd_aio_connect (nbd, &addr, len) == -1) {
    fprintf (stderr, "%s\n", nbd_get_error ());
+   nbd_close (nbd);
    exit (EXIT_FAILURE);
  }
  while (!nbd_aio_is_ready (nbd)) {
    if (nbd_poll (nbd, -1) == -1) {
      fprintf (stderr, "%s\n", nbd_get_error ());
+     nbd_close (nbd);
      exit (EXIT_FAILURE);
    }
  }
@@ -256,11 +264,13 @@ command has completed:
  cookie = nbd_aio_pread (nbd, buf, sizeof buf, offset, 0)
  if (cookie == -1) {
    fprintf (stderr, "%s\n", nbd_get_error ());
+   nbd_close (nbd);
    exit (EXIT_FAILURE);
  }
  while (!nbd_aio_command_completed (nbd, cookie)) {
    if (nbd_poll (nbd, -1) == -1) {
      fprintf (stderr, "%s\n", nbd_get_error ());
+     nbd_close (nbd);
      exit (EXIT_FAILURE);
    }
  }
diff --git a/generator/generator b/generator/generator
index 6621bee..29d0373 100755
--- a/generator/generator
+++ b/generator/generator
@@ -3773,6 +3773,7 @@ libnbd-api - libnbd C API
      nbd_connect_tcp (nbd, \"server.example.com\", \"nbd\")
== -1 ||
      nbd_pread (nbd, buf, sizeof buf, 0, 0) == -1)
    fprintf (stderr, \"%%s\\n\", nbd_get_error ());
+   nbd_close (nbd);
    exit (EXIT_FAILURE);
  }
  nbd_close (nbd);
-- 
2.22.0

On 8/6/19 8:38 AM, Richard W.M. Jones wrote:
> One API change, some small documentation changes.
ACK series

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org

On 8/6/19 8:38 AM, Richard W.M. Jones wrote:
> This makes it consistent with other nbd_is_* and nbd_can_* APIs.
> 
> Suggested by Thomas Haller.
> ---
>  docs/libnbd.pod                      | 2 +-
>  examples/batched-read-write.c        | 2 +-
>  examples/simple-reads-and-writes.c   | 2 +-
>  examples/threaded-reads-and-writes.c | 2 +-
>  generator/generator                  | 2 +-
>  lib/flags.c                          | 2 +-
>  lib/rw.c                             | 6 +++---
>  tests/aio-parallel-load.c            | 2 +-
>  tests/aio-parallel.c                 | 2 +-
>  tests/read-only-flag.c               | 4 ++--
>  tests/read-write-flag.c              | 4 ++--
>  tests/synch-parallel.c               | 2 +-
>  12 files changed, 16 insertions(+), 16 deletions(-)
The following patch lets nbdkit compile with any libnbd version >= 0.9.6
(since this libnbd patch will cause an API bump when we finally release
0.9.8...)

But I won't actually push anything to nbdkit until we actually release
the next libnbd, in case there's more tweaks to worry about in the
meantime.  And we may still decide to just bump the minimum required
version in configure.ac instead of doing this hack to support both versions.

diff --git i/plugins/nbd/nbd.c w/plugins/nbd/nbd.c
index f11e54d5..a83ded5e 100644
--- i/plugins/nbd/nbd.c
+++ w/plugins/nbd/nbd.c
@@ -566,11 +566,15 @@ nbdplug_get_size (void *handle)
   return size;
 }

+#ifndef LIBNBD_HAVE_NBD_IS_READ_ONLY
+# define nbd_is_read_only nbd_read_only
+#endif
+
 static int
 nbdplug_can_write (void *handle)
 {
   struct handle *h = handle;
-  int i = nbd_read_only (h->nbd);
+  int i = nbd_is_read_only (h->nbd);

   if (i == -1) {
     nbdkit_error ("failure to check readonly flag: %s", nbd_get_error
());


-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org