1nbd_get_export_description(3) LIBNBD nbd_get_export_description(3)
2
3
4
6 nbd_get_export_description - return the export description, if the
7 server has one
8
10 #include <libnbd.h>
11
12 char * nbd_get_export_description (struct nbd_handle *h);
13
15 The NBD protocol permits a server to report an optional export
16 description. This function reports any description returned by the
17 server.
18
19 Some servers are unlikely to report a description unless the client
20 specifically hinted about wanting it, via nbd_set_full_info(3). For
21 qemu-nbd(8), a description is set with -D.
22
24 This call returns a string. The caller must free the returned string
25 to avoid a memory leak.
26
28 On error "NULL" is returned.
29
30 Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
31 of the error.
32
34 The handle must be negotiating, or connected with the server, or shut
35 down, otherwise this call will return an error.
36
38 This function first appeared in libnbd 1.4.
39
40 If you need to test if this function is available at compile time check
41 if the following macro is defined:
42
43 #define LIBNBD_HAVE_NBD_GET_EXPORT_DESCRIPTION 1
44
46 This example is also available as examples/server-flags.c in the libnbd
47 source code.
48
49 /* This example shows how to connect to an NBD
50 * server and print the export flags.
51 *
52 * You can test it with nbdkit like this:
53 *
54 * nbdkit -U - memory 1M \
55 * --run './server-flags $unixsocket'
56 */
57
58 #include <stdio.h>
59 #include <stdlib.h>
60
61 #include <libnbd.h>
62
63 int
64 main (int argc, char *argv[])
65 {
66 struct nbd_handle *nbd;
67 char *str;
68 int flag;
69
70 if (argc != 2) {
71 fprintf (stderr, "%s socket\n", argv[0]);
72 exit (EXIT_FAILURE);
73 }
74
75 /* Create the libnbd handle. */
76 nbd = nbd_create ();
77 if (nbd == NULL) {
78 fprintf (stderr, "%s\n", nbd_get_error ());
79 exit (EXIT_FAILURE);
80 }
81
82 /* Request full information. */
83 #if LIBNBD_HAVE_NBD_SET_FULL_INFO /* Added in 1.4 */
84 if (nbd_set_full_info (nbd, true) == -1) {
85 fprintf (stderr, "%s\n", nbd_get_error ());
86 exit (EXIT_FAILURE);
87 }
88 #endif
89
90 /* Connect to the NBD server over a
91 * Unix domain socket.
92 */
93 if (nbd_connect_unix (nbd, argv[1]) == -1) {
94 fprintf (stderr, "%s\n", nbd_get_error ());
95 exit (EXIT_FAILURE);
96 }
97
98 /* See if the server provided extra details,
99 * using functions added in 1.4
100 */
101 #if LIBNBD_HAVE_NBD_GET_EXPORT_DESCRIPTION
102 str = nbd_get_canonical_export_name (nbd);
103 if (str)
104 printf ("canonical_name = %s\n", str);
105 free (str);
106 str = nbd_get_export_description (nbd);
107 if (str)
108 printf ("description = %s\n", str);
109 free (str);
110 #endif
111
112 /* Read and print the flags. */
113 #define PRINT_FLAG(flag_fn) \
114 flag = flag_fn (nbd); \
115 if (flag == -1) { \
116 fprintf (stderr, "%s\n", nbd_get_error ()); \
117 exit (EXIT_FAILURE); \
118 } \
119 printf (#flag_fn " = %s\n", \
120 flag ? "true" : "false");
121
122 PRINT_FLAG (nbd_can_cache);
123 PRINT_FLAG (nbd_can_df);
124 PRINT_FLAG (nbd_can_flush);
125 PRINT_FLAG (nbd_can_fua);
126 PRINT_FLAG (nbd_can_multi_conn);
127 PRINT_FLAG (nbd_can_trim);
128 PRINT_FLAG (nbd_can_zero);
129 #if LIBNBD_HAVE_NBD_CAN_FAST_ZERO /* Added in 1.2 */
130 PRINT_FLAG (nbd_can_fast_zero);
131 #endif
132 PRINT_FLAG (nbd_is_read_only);
133 PRINT_FLAG (nbd_is_rotational);
134
135 /* Close the libnbd handle. */
136 nbd_close (nbd);
137
138 exit (EXIT_SUCCESS);
139 }
140
142 nbd_create(3), nbd_opt_info(3), nbd_set_full_info(3), libnbd(3).
143
145 Eric Blake
146
147 Richard W.M. Jones
148
150 Copyright (C) 2019-2021 Red Hat Inc.
151
153 This library is free software; you can redistribute it and/or modify it
154 under the terms of the GNU Lesser General Public License as published
155 by the Free Software Foundation; either version 2 of the License, or
156 (at your option) any later version.
157
158 This library is distributed in the hope that it will be useful, but
159 WITHOUT ANY WARRANTY; without even the implied warranty of
160 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
161 Lesser General Public License for more details.
162
163 You should have received a copy of the GNU Lesser General Public
164 License along with this library; if not, write to the Free Software
165 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
166 02110-1301 USA
167
168
169
170libnbd-1.7.12 2021-05-29 nbd_get_export_description(3)