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