NAME
nbd_get_canonical_export_name - return the canonical export name, if the server has one
SYNOPSIS
#include
<libnbd.h>
char * nbd_get_canonical_export_name (
struct nbd_handle *h
);
DESCRIPTION
The NBD protocol permits a server to report an optional canonical export name, which may differ from the client’s request (as set by nbd_set_export_name(3) or nbd_connect_uri(3)). This function accesses any name returned by the server; it may be the same as the client request, but is more likely to differ when the client requested a connection to the default export name (an empty string "").
Some servers are unlikely to report a canonical name unless the client specifically hinted about wanting it, via nbd_set_full_info(3).
RETURN VALUE
This call returns a string. The caller must free the returned string to avoid a memory leak.
ERRORS
On error "NULL" 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". For more information see "Non-NULL parameters" in libnbd(3).
HANDLE STATE
nbd_get_canonical_export_name can be called when the handle is in the following states:
┌─────────────────────────────────────┬─────────────────────────┐
│ Handle created, before connecting │ ❌
error │
│ Connecting │ ❌ error │
│ Connecting & handshaking (opt_mode) │
✅ allowed │
│ Connected to the server │ ✅ allowed
│
│ Connection shut down │ ✅ allowed │
│ Handle dead │ ❌ error │
└─────────────────────────────────────┴─────────────────────────┘
VERSION
This function first appeared in libnbd 1.4.
If you need to test if this function is available at compile time check if the following macro is defined:
#define LIBNBD_HAVE_NBD_GET_CANONICAL_EXPORT_NAME 1
EXAMPLE
This example is also available as examples/server-flags.c in the libnbd source code.
/* This example
shows how to connect to an NBD
* server and print the export flags.
*
* You can test it with nbdkit like this:
*
* nbdkit -U - memory 1M \
* --run './server-flags $unixsocket'
*/
#include <stdio.h>
#include <stdlib.h>
#include <stdbool.h>
#include <libnbd.h>
int
main (int argc, char *argv[])
{
struct nbd_handle *nbd;
char *str;
int flag;
if (argc != 2) {
fprintf (stderr, "%s socket\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. */
#if LIBNBD_HAVE_NBD_SET_FULL_INFO /* Added in 1.4 */
if (nbd_set_full_info (nbd, true) == -1) {
fprintf (stderr, "%s\n", nbd_get_error ());
exit (EXIT_FAILURE);
}
#endif
/* Connect to the NBD server over a
* Unix domain socket.
*/
if (nbd_connect_unix (nbd, argv[1]) == -1) {
fprintf (stderr, "%s\n", nbd_get_error ());
exit (EXIT_FAILURE);
}
/* See if the server provided extra details,
* using functions added in 1.4
*/
#if LIBNBD_HAVE_NBD_GET_EXPORT_DESCRIPTION
str = nbd_get_canonical_export_name (nbd);
if (str)
printf ("canonical_name = %s\n", str);
free (str);
str = nbd_get_export_description (nbd);
if (str)
printf ("description = %s\n", str);
free (str);
#endif
/* Read and print the flags. */
#define PRINT_FLAG(flag_fn) \
flag = flag_fn (nbd); \
if (flag == -1) { \
fprintf (stderr, "%s\n", nbd_get_error ()); \
exit (EXIT_FAILURE); \
} \
printf (#flag_fn " = %s\n", \
flag ? "true" : "false");
PRINT_FLAG (nbd_can_cache);
PRINT_FLAG (nbd_can_df);
PRINT_FLAG (nbd_can_flush);
PRINT_FLAG (nbd_can_fua);
PRINT_FLAG (nbd_can_multi_conn);
PRINT_FLAG (nbd_can_trim);
PRINT_FLAG (nbd_can_zero);
#if LIBNBD_HAVE_NBD_CAN_FAST_ZERO
/* Added in 1.2 */
PRINT_FLAG (nbd_can_fast_zero);
#endif
#if LIBNBD_HAVE_NBD_CAN_BLOCK_STATUS_PAYLOAD
/* Added in 1.18 */
PRINT_FLAG (nbd_can_block_status_payload);
#endif
PRINT_FLAG (nbd_is_read_only);
PRINT_FLAG (nbd_is_rotational);
/* Close the libnbd handle. */
nbd_close (nbd);
exit (EXIT_SUCCESS);
}
SEE ALSO
nbd_connect_uri(3), nbd_create(3), nbd_get_export_name(3), nbd_opt_info(3), nbd_set_export_name(3), nbd_set_full_info(3), libnbd(3).
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