1nbd_opt_go(3) LIBNBD nbd_opt_go(3)
2
6 nbd_opt_go - end negotiation and move on to using an export
7
9 #include <libnbd.h>
10 int nbd_opt_go (
12 struct nbd_handle *h
13 );
14
16 Request that the server finish negotiation and move on to serving the
17 export previously specified by the most recent nbd_set_export_name(3)
18 or nbd_connect_uri(3). This can only be used if nbd_set_opt_mode(3)
19 enabled option mode.
20 By default, libnbd will automatically request all meta contexts
22 registered by nbd_add_meta_context(3) as part of this call; but this
23 can be suppressed with nbd_set_request_meta_context(3), particularly if
24 nbd_opt_set_meta_context(3) was used earlier in the negotiation
25 sequence.
26 If this fails, the server may still be in negotiation, where it is
28 possible to attempt another option such as a different export name;
29 although older servers will instead have killed the connection.
30
32 If the call is successful the function returns 0.
33
35 On error -1 is returned.
36 Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
38 of the error.
39 The following parameters must not be NULL: "h". For more information
41 see "Non-NULL parameters" in libnbd(3).
42
44 The handle must be negotiating, otherwise this call will return an
45 error.
46
48 This function first appeared in libnbd 1.4.
49 If you need to test if this function is available at compile time check
51 if the following macro is defined:
52 #define LIBNBD_HAVE_NBD_OPT_GO 1
54
56 This example is also available as examples/list-exports.c in the libnbd
57 source code.
58 /* This example shows how to list NBD exports.
60 *
61 * To test this with qemu-nbd:
62 * $ qemu-nbd -x "hello" -t -k /tmp/sock disk.img
63 * $ ./run examples/list-exports /tmp/sock
64 * [0] hello
65 * Which export to connect to (-1 to quit)? 0
66 * Connecting to hello ...
67 * /tmp/sock: hello: size = 2048 bytes
68 *
69 * To test this with nbdkit (requires 1.22):
70 * $ nbdkit -U /tmp/sock sh - <<\EOF
71 * case $1 in
72 * list_exports) echo NAMES; echo foo; echo foobar ;;
73 * open) echo "$3" ;;
74 * get_size) echo "$2" | wc -c ;;
75 * pread) echo "$2" | dd bs=1 skip=$4 count=$3 ;;
76 * *) exit 2 ;;
77 * esac
78 * EOF
79 * $ ./run examples/list-exports /tmp/sock
80 * [0] foo
81 * [1] foobar
82 * Which export to connect to (-1 to quit)? 1
83 * Connecting to foobar ...
84 * /tmp/sock: foobar: size = 7 bytes
85 */
86 #include <stdio.h>
88 #include <stdlib.h>
89 #include <stdint.h>
90 #include <string.h>
91 #include <inttypes.h>
92 #include <errno.h>
93 #include <libnbd.h>
95 struct export_list {
97 int i;
98 char **names;
99 };
100 /* Callback function for nbd_opt_list */
102 static int
103 list_one (void *opaque, const char *name,
104 const char *description)
105 {
106 struct export_list *l = opaque;
107 char **names;
108 printf ("[%d] %s\n", l->i, name);
110 if (*description)
111 printf (" (%s)\n", description);
112 names = realloc (l->names,
113 (l->i + 1) * sizeof *names);
114 if (!names) {
115 perror ("realloc");
116 exit (EXIT_FAILURE);
117 }
118 names[l->i] = strdup (name);
119 if (!names[l->i]) {
120 perror ("strdup");
121 exit (EXIT_FAILURE);
122 }
123 l->names = names;
124 l->i++;
125 return 0;
126 }
127 int
129 main (int argc, char *argv[])
130 {
131 struct nbd_handle *nbd;
132 int i;
133 const char *name;
134 int64_t size;
135 struct export_list list = { 0 };
136 if (argc != 2) {
138 fprintf (stderr, "%s socket\n", argv[0]);
139 exit (EXIT_FAILURE);
140 }
141 /* Create the libnbd handle. */
143 nbd = nbd_create ();
144 if (nbd == NULL) {
145 fprintf (stderr, "%s\n", nbd_get_error ());
146 exit (EXIT_FAILURE);
147 }
148 /* Set opt mode. */
150 nbd_set_opt_mode (nbd, true);
151 /* Connect to the NBD server over a
153 * Unix domain socket. If we did not
154 * end up in option mode, then a
155 * listing is not possible.
156 */
157 if (nbd_connect_unix (nbd, argv[1]) == -1) {
158 fprintf (stderr, "%s\n", nbd_get_error ());
159 exit (EXIT_FAILURE);
160 }
161 if (!nbd_aio_is_negotiating (nbd)) {
162 fprintf (stderr, "Server does not support "
163 "listing exports.\n");
164 exit (EXIT_FAILURE);
165 }
166 /* Print the export list. */
168 if (nbd_opt_list (nbd,
169 (nbd_list_callback) {
170 .callback = list_one,
171 .user_data = &list, }) == -1) {
172 fprintf (stderr, "%s\n", nbd_get_error ());
173 exit (EXIT_FAILURE);
174 }
175 /* Display the list of exports. */
177 printf ("Which export to connect to? ");
178 if (scanf ("%d", &i) != 1) exit (EXIT_FAILURE);
179 if (i == -1) {
180 if (nbd_opt_abort (nbd) == -1) {
181 fprintf (stderr, "%s\n", nbd_get_error ());
182 exit (EXIT_FAILURE);
183 }
184 nbd_close (nbd);
185 exit (EXIT_SUCCESS);
186 }
187 if (i < 0 || i >= list.i) {
188 fprintf (stderr, "index %d out of range", i);
189 exit (EXIT_FAILURE);
190 }
191 name = list.names[i];
192 printf ("Connecting to %s ...\n", name);
193 /* Resume connecting to the chosen export. */
195 if (nbd_set_export_name (nbd, name) == -1 ||
196 nbd_opt_go (nbd) == -1) {
197 fprintf (stderr, "%s\n", nbd_get_error ());
198 exit (EXIT_FAILURE);
199 }
200 if (!nbd_aio_is_ready (nbd)) {
201 fprintf (stderr, "server closed early\n");
202 exit (EXIT_FAILURE);
203 }
204 /* Read the size in bytes and print it. */
206 size = nbd_get_size (nbd);
207 if (size == -1) {
208 fprintf (stderr, "%s\n", nbd_get_error ());
209 exit (EXIT_FAILURE);
210 }
211 printf ("%s: %s: size = %" PRIi64 " bytes\n",
212 argv[1], name, size);
213 /* Close the libnbd handle. */
215 nbd_close (nbd);
216 for (i = 0; i < list.i; i++)
218 free (list.names[i]);
219 free (list.names);
220 exit (EXIT_SUCCESS);
222 }
223
225 nbd_add_meta_context(3), nbd_aio_opt_go(3), nbd_connect_uri(3),
226 nbd_create(3), nbd_opt_abort(3), nbd_opt_info(3),
227 nbd_opt_set_meta_context(3), nbd_set_export_name(3),
228 nbd_set_opt_mode(3), nbd_set_request_meta_context(3), libnbd(3).
229
231 Eric Blake
232 Richard W.M. Jones
234
236 Copyright Red Hat
237
239 This library is free software; you can redistribute it and/or modify it
240 under the terms of the GNU Lesser General Public License as published
241 by the Free Software Foundation; either version 2 of the License, or
242 (at your option) any later version.
243 This library is distributed in the hope that it will be useful, but
245 WITHOUT ANY WARRANTY; without even the implied warranty of
246 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
247 Lesser General Public License for more details.
248 You should have received a copy of the GNU Lesser General Public
250 License along with this library; if not, write to the Free Software
251 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
252 02110-1301 USA
253libnbd-1.16.5 2023-09-26 nbd_opt_go(3)