NAME

nbd_connect_uri - connect to NBD URI

SYNOPSIS

 #include <libnbd.h>
 int nbd_connect_uri (
       struct nbd_handle *h, const char *uri
     );

DESCRIPTION

Connect (synchronously) to an NBD server and export by specifying the NBD URI. NBD URIs are a standard way to specify a network block device endpoint, using a syntax like "nbd://example.com" which is convenient, well defined and future proof.

This call works by parsing the URI parameter and calling nbd_set_export_name(3) and nbd_set_tls(3) and other calls as needed, followed by nbd_connect_tcp(3), nbd_connect_unix(3) or nbd_connect_vsock(3).

This call returns when the connection has been made. By default, this proceeds all the way to transmission phase, but nbd_set_opt_mode(3) can be used for manual control over option negotiation performed before transmission phase.

RETURN VALUE

If the call is successful the function returns 0.

ERRORS

On error -1 is returned.

Refer to "ERROR HANDLING" in libnbd(3) for how to get further details of the error.

The following parameters must not be NULL: "h", "uri". For more information see "Non-NULL parameters" in libnbd(3).

HANDLE STATE

nbd_connect_uri can be called when the handle is in the following state:

 ┌─────────────────────────────────────┬─────────────────────────┐
 │ Handle created, before connecting   │ ✅ allowed              │
 │ Connecting                          │ ❌ error                │
 │ Connecting & handshaking (opt_mode) │ ❌ error                │
 │ Connected to the server             │ ❌ error                │
 │ Connection shut down                │ ❌ error                │
 │ Handle dead                         │ ❌ error                │
 └─────────────────────────────────────┴─────────────────────────┘

VERSION

This function first appeared in libnbd 1.0.

If you need to test if this function is available at compile time check if the following macro is defined:

 #define LIBNBD_HAVE_NBD_CONNECT_URI 1

EXAMPLE

This example is also available as examples/connect-uri.c in the libnbd source code.

 /* This example shows how to connect to an NBD
  * server using the server's NBD URI.
  *
  * To test this with a recent version of nbdkit
  * that supports the '$uri' syntax, do:
  *
  * nbdkit -U - random 1M \
  *   --run './connect-uri $uri'
  *
  * To test connecting to a remote NBD server
  * listening on port 10809, do:
  *
  * ./connect-uri nbd://remote/
  */
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
 #include <stdint.h>
 #include <inttypes.h>
 #include <libnbd.h>
 int
 main (int argc, char *argv[])
 {
   struct nbd_handle *nbd;
   char *s;
   int64_t size;
   if (argc != 2) {
     fprintf (stderr, "usage: %s URI\n",
              argv[0]);
     exit (EXIT_FAILURE);
   }
   /* Create the libnbd handle. */
   nbd = nbd_create ();
   if (nbd == NULL) {
     fprintf (stderr, "%s\n", nbd_get_error ());
     exit (EXIT_FAILURE);
   }
   /* Request full information
    * (for nbd_get_canonical_export_name below)
    */
 #if LIBNBD_HAVE_NBD_SET_FULL_INFO
   if (nbd_set_full_info (nbd, true) == -1) {
     fprintf (stderr, "%s\n", nbd_get_error ());
     exit (EXIT_FAILURE);
   }
 #endif
   /* Connect to the NBD URI. */
   printf ("connecting to %s ...\n", argv[1]);
   fflush (stdout);
   if (nbd_connect_uri (nbd, argv[1]) == -1) {
     fprintf (stderr, "%s\n", nbd_get_error ());
     exit (EXIT_FAILURE);
   }
   printf ("connected\n");
   /* Print the URI, export name, size and other info. */
   printf ("requested URI: %s\n", argv[1]);
   s = nbd_get_uri (nbd);
   printf ("generated URI: %s\n", s ? s : "NULL");
   free (s);
   size = nbd_get_size (nbd);
   if (size == -1) {
     fprintf (stderr, "%s\n", nbd_get_error ());
     exit (EXIT_FAILURE);
   }
   printf ("size: %" PRIi64 "\n", size);
   s = nbd_get_export_name (nbd);
   printf ("requested export name: %s\n", s ? s : "NULL");
   free (s);
 #if LIBNBD_HAVE_NBD_GET_CANONICAL_EXPORT_NAME
   s = nbd_get_canonical_export_name (nbd);
   printf ("canonical export name: %s\n", s ? s : "NULL");
   free (s);
 #endif
 #if LIBNBD_HAVE_NBD_GET_EXPORT_DESCRIPTION
   s = nbd_get_export_description (nbd);
   printf ("export description: %s\n", s ? s : "NULL");
   free (s);
 #endif
   /* Close the libnbd handle. */
   nbd_close (nbd);
   exit (EXIT_SUCCESS);
 }

SEE ALSO

nbd_aio_connect_uri(3), nbd_connect_tcp(3), nbd_connect_unix(3), nbd_connect_uri(3), nbd_connect_vsock(3), nbd_create(3), nbd_get_uri(3), nbd_opt_go(3), nbd_set_export_name(3), nbd_set_opt_mode(3), nbd_set_tls(3), nbd_set_tls_certificates(3), nbd_set_tls_psk_file(3), nbd_set_uri_allow_local_file(3), nbd_set_uri_allow_tls(3), nbd_set_uri_allow_transports(3), nbd_supports_tls(3), nbd_supports_uri(3), nbd_supports_vsock(3), libnbd(3), https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md.

AUTHORS

Eric Blake

Richard W.M. Jones

COPYRIGHT

Copyright Red Hat

LICENSE

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA