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