1nbd_set_opt_mode(3) LIBNBD nbd_set_opt_mode(3)
2
6 nbd_set_opt_mode - control option mode, for pausing during option
7 negotiation
8
10 #include <libnbd.h>
11 int nbd_set_opt_mode (struct nbd_handle *h, bool enable);
13
15 Set this flag to true in order to request that a connection command
16 "nbd_connect_*" will pause for negotiation options rather than
17 proceeding all the way to the ready state, when communicating with a
18 newstyle server. This setting has no effect when connecting to an
19 oldstyle server.
20 When option mode is enabled, you have fine-grained control over which
22 options are negotiated, compared to the default of the server
23 negotiating everything on your behalf using settings made before
24 starting the connection. To leave the mode and proceed on to the ready
25 state, you must use nbd_opt_go(3) successfully; a failed nbd_opt_go(3)
26 returns to the negotiating state to allow a change of export name
27 before trying again. You may also use nbd_opt_abort(3) to end the
28 connection without finishing negotiation.
29
31 If the call is successful the function returns 0.
32
34 On error "-1" is returned.
35 Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
37 of the error.
38
40 The handle must be newly created, otherwise this call will return an
41 error.
42
44 This function first appeared in libnbd 1.4.
45 If you need to test if this function is available at compile time check
47 if the following macro is defined:
48 #define LIBNBD_HAVE_NBD_SET_OPT_MODE 1
50
52 This example is also available as examples/list-exports.c in the libnbd
53 source code.
54 /* This example shows how to list NBD exports.
56 *
57 * To test this with qemu-nbd:
58 * $ qemu-nbd -x "hello" -t -k /tmp/sock disk.img
59 * $ ./run examples/list-exports /tmp/sock
60 * [0] hello
61 * Which export to connect to (-1 to quit)? 0
62 * Connecting to hello ...
63 * /tmp/sock: hello: size = 2048 bytes
64 *
65 * To test this with nbdkit (requires 1.22):
66 * $ nbdkit -U /tmp/sock sh - <<\EOF
67 * case $1 in
68 * list_exports) echo NAMES; echo foo; echo foobar ;;
69 * open) echo "$3" ;;
70 * get_size) echo "$2" | wc -c ;;
71 * pread) echo "$2" | dd bs=1 skip=$4 count=$3 ;;
72 * *) exit 2 ;;
73 * esac
74 * EOF
75 * $ ./run examples/list-exports /tmp/sock
76 * [0] foo
77 * [1] foobar
78 * Which export to connect to (-1 to quit)? 1
79 * Connecting to foobar ...
80 * /tmp/sock: foobar: size = 7 bytes
81 */
82 #include <stdio.h>
84 #include <stdlib.h>
85 #include <stdint.h>
86 #include <string.h>
87 #include <inttypes.h>
88 #include <errno.h>
89 #include <libnbd.h>
91 struct export_list {
93 int i;
94 char **names;
95 };
96 /* Callback function for nbd_opt_list */
98 static int
99 list_one (void *opaque, const char *name,
100 const char *description)
101 {
102 struct export_list *l = opaque;
103 char **names;
104 printf ("[%d] %s\n", l->i, name);
106 if (*description)
107 printf(" (%s)\n", description);
108 names = realloc (l->names,
109 (l->i + 1) * sizeof *names);
110 if (!names) {
111 perror ("realloc");
112 exit (EXIT_FAILURE);
113 }
114 names[l->i] = strdup (name);
115 if (!names[l->i]) {
116 perror ("strdup");
117 exit (EXIT_FAILURE);
118 }
119 l->names = names;
120 l->i++;
121 return 0;
122 }
123 int
125 main (int argc, char *argv[])
126 {
127 struct nbd_handle *nbd;
128 int i;
129 const char *name;
130 int64_t size;
131 struct export_list list = { 0 };
132 if (argc != 2) {
134 fprintf (stderr, "%s socket\n", argv[0]);
135 exit (EXIT_FAILURE);
136 }
137 /* Create the libnbd handle. */
139 nbd = nbd_create ();
140 if (nbd == NULL) {
141 fprintf (stderr, "%s\n", nbd_get_error ());
142 exit (EXIT_FAILURE);
143 }
144 /* Set opt mode. */
146 nbd_set_opt_mode (nbd, true);
147 /* Connect to the NBD server over a
149 * Unix domain socket. If we did not
150 * end up in option mode, then a
151 * listing is not possible.
152 */
153 if (nbd_connect_unix (nbd, argv[1]) == -1) {
154 fprintf (stderr, "%s\n", nbd_get_error ());
155 exit (EXIT_FAILURE);
156 }
157 if (!nbd_aio_is_negotiating (nbd)) {
158 fprintf (stderr, "Server does not support "
159 "listing exports.\n");
160 exit (EXIT_FAILURE);
161 }
162 /* Print the export list. */
164 if (nbd_opt_list (nbd,
165 (nbd_list_callback) {
166 .callback = list_one,
167 .user_data = &list, }) == -1) {
168 fprintf (stderr, "%s\n", nbd_get_error ());
169 exit (EXIT_FAILURE);
170 }
171 /* Display the list of exports. */
173 printf ("Which export to connect to? ");
174 if (scanf ("%d", &i) != 1) exit (EXIT_FAILURE);
175 if (i == -1) {
176 if (nbd_opt_abort (nbd) == -1) {
177 fprintf (stderr, "%s\n", nbd_get_error ());
178 exit (EXIT_FAILURE);
179 }
180 nbd_close (nbd);
181 exit (EXIT_SUCCESS);
182 }
183 if (i < 0 || i >= list.i) {
184 fprintf (stderr, "index %d out of range", i);
185 exit (EXIT_FAILURE);
186 }
187 name = list.names[i];
188 printf ("Connecting to %s ...\n", name);
189 /* Resume connecting to the chosen export. */
191 if (nbd_set_export_name (nbd, name) == -1 ||
192 nbd_opt_go (nbd) == -1) {
193 fprintf (stderr, "%s\n", nbd_get_error ());
194 exit (EXIT_FAILURE);
195 }
196 if (!nbd_aio_is_ready (nbd)) {
197 fprintf (stderr, "server closed early\n");
198 exit (EXIT_FAILURE);
199 }
200 /* Read the size in bytes and print it. */
202 size = nbd_get_size (nbd);
203 if (size == -1) {
204 fprintf (stderr, "%s\n", nbd_get_error ());
205 exit (EXIT_FAILURE);
206 }
207 printf ("%s: %s: size = %" PRIi64 " bytes\n",
208 argv[1], name, size);
209 /* Close the libnbd handle. */
211 nbd_close (nbd);
212 for (i = 0; i < list.i; i++)
214 free (list.names[i]);
215 free (list.names);
216 exit (EXIT_SUCCESS);
218 }
219
221 nbd_aio_is_negotiating(3), nbd_create(3), nbd_get_opt_mode(3),
222 nbd_opt_abort(3), nbd_opt_go(3), nbd_opt_info(3), nbd_opt_list(3),
223 nbd_opt_list_meta_context(3), libnbd(3).
224
226 Eric Blake
227 Richard W.M. Jones
229
231 Copyright (C) 2019-2021 Red Hat Inc.
232
234 This library is free software; you can redistribute it and/or modify it
235 under the terms of the GNU Lesser General Public License as published
236 by the Free Software Foundation; either version 2 of the License, or
237 (at your option) any later version.
238 This library is distributed in the hope that it will be useful, but
240 WITHOUT ANY WARRANTY; without even the implied warranty of
241 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
242 Lesser General Public License for more details.
243 You should have received a copy of the GNU Lesser General Public
245 License along with this library; if not, write to the Free Software
246 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
247 02110-1301 USA
248libnbd-1.7.12 2021-05-29 nbd_set_opt_mode(3)