1nbd_set_opt_mode(3)                 LIBNBD                 nbd_set_opt_mode(3)
2
3
4

NAME

6       nbd_set_opt_mode - control option mode, for pausing during option
7       negotiation
8

SYNOPSIS

10        #include <libnbd.h>
11
12        int nbd_set_opt_mode (struct nbd_handle *h, bool enable);
13

DESCRIPTION

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
21       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

RETURN VALUE

31       If the call is successful the function returns 0.
32

ERRORS

34       On error "-1" is returned.
35
36       Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
37       of the error.
38

HANDLE STATE

40       The handle must be newly created, otherwise this call will return an
41       error.
42

VERSION

44       This function first appeared in libnbd 1.4.
45
46       If you need to test if this function is available at compile time check
47       if the following macro is defined:
48
49        #define LIBNBD_HAVE_NBD_SET_OPT_MODE 1
50

EXAMPLE

52       This example is also available as examples/list-exports.c in the libnbd
53       source code.
54
55        /* 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
83        #include <stdio.h>
84        #include <stdlib.h>
85        #include <stdint.h>
86        #include <string.h>
87        #include <inttypes.h>
88        #include <errno.h>
89
90        #include <libnbd.h>
91
92        struct export_list {
93          int i;
94          char **names;
95        };
96
97        /* 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
105          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
124        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
133          if (argc != 2) {
134            fprintf (stderr, "%s socket\n", argv[0]);
135            exit (EXIT_FAILURE);
136          }
137
138          /* 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
145          /* Set opt mode. */
146          nbd_set_opt_mode (nbd, true);
147
148          /* 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
163          /* 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
172          /* 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
190          /* 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
201          /* 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
210          /* Close the libnbd handle. */
211          nbd_close (nbd);
212
213          for (i = 0; i < list.i; i++)
214            free (list.names[i]);
215          free (list.names);
216
217          exit (EXIT_SUCCESS);
218        }
219

SEE ALSO

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

AUTHORS

226       Eric Blake
227
228       Richard W.M. Jones
229
231       Copyright (C) 2019-2021 Red Hat Inc.
232

LICENSE

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
239       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
244       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
248
249
250
251libnbd-1.7.12                     2021-05-29               nbd_set_opt_mode(3)
Impressum