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