1nbd_set_full_info(3) LIBNBD nbd_set_full_info(3)
2
3
4
6 nbd_set_full_info - control whether NBD_OPT_GO requests extra details
7
9 #include <libnbd.h>
10
11 int nbd_set_full_info (struct nbd_handle *h, bool request);
12
14 By default, when connecting to an export, libnbd only requests the
15 details it needs to service data operations. The NBD protocol says
16 that a server can supply optional information, such as a canonical name
17 of the export (see nbd_get_canonical_export_name(3)) or a description
18 of the export (see nbd_get_export_description(3)), but that a hint from
19 the client makes it more likely for this extra information to be
20 provided. This function controls whether libnbd will provide that
21 hint.
22
23 Note that even when full info is requested, the server is not obligated
24 to reply with all information that libnbd requested. Similarly, libnbd
25 will ignore any optional server information that libnbd has not yet
26 been taught to recognize.
27
29 If the call is successful the function returns 0.
30
32 On error "-1" is returned.
33
34 Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
35 of the error.
36
38 The handle must be newly created, or negotiating, otherwise this call
39 will return an error.
40
42 This function first appeared in libnbd 1.4.
43
44 If you need to test if this function is available at compile time check
45 if the following macro is defined:
46
47 #define LIBNBD_HAVE_NBD_SET_FULL_INFO 1
48
50 This example is also available as examples/server-flags.c in the libnbd
51 source code.
52
53 /* This example shows how to connect to an NBD
54 * server and print the export flags.
55 *
56 * You can test it with nbdkit like this:
57 *
58 * nbdkit -U - memory 1M \
59 * --run './server-flags $unixsocket'
60 */
61
62 #include <stdio.h>
63 #include <stdlib.h>
64
65 #include <libnbd.h>
66
67 int
68 main (int argc, char *argv[])
69 {
70 struct nbd_handle *nbd;
71 char *str;
72 int flag;
73
74 if (argc != 2) {
75 fprintf (stderr, "%s socket\n", argv[0]);
76 exit (EXIT_FAILURE);
77 }
78
79 /* Create the libnbd handle. */
80 nbd = nbd_create ();
81 if (nbd == NULL) {
82 fprintf (stderr, "%s\n", nbd_get_error ());
83 exit (EXIT_FAILURE);
84 }
85
86 /* Request full information. */
87 #if LIBNBD_HAVE_NBD_SET_FULL_INFO /* Added in 1.4 */
88 if (nbd_set_full_info (nbd, true) == -1) {
89 fprintf (stderr, "%s\n", nbd_get_error ());
90 exit (EXIT_FAILURE);
91 }
92 #endif
93
94 /* Connect to the NBD server over a
95 * Unix domain socket.
96 */
97 if (nbd_connect_unix (nbd, argv[1]) == -1) {
98 fprintf (stderr, "%s\n", nbd_get_error ());
99 exit (EXIT_FAILURE);
100 }
101
102 /* See if the server provided extra details,
103 * using functions added in 1.4
104 */
105 #if LIBNBD_HAVE_NBD_GET_EXPORT_DESCRIPTION
106 str = nbd_get_canonical_export_name (nbd);
107 if (str)
108 printf ("canonical_name = %s\n", str);
109 free (str);
110 str = nbd_get_export_description (nbd);
111 if (str)
112 printf ("description = %s\n", str);
113 free (str);
114 #endif
115
116 /* Read and print the flags. */
117 #define PRINT_FLAG(flag_fn) \
118 flag = flag_fn (nbd); \
119 if (flag == -1) { \
120 fprintf (stderr, "%s\n", nbd_get_error ()); \
121 exit (EXIT_FAILURE); \
122 } \
123 printf (#flag_fn " = %s\n", \
124 flag ? "true" : "false");
125
126 PRINT_FLAG (nbd_can_cache);
127 PRINT_FLAG (nbd_can_df);
128 PRINT_FLAG (nbd_can_flush);
129 PRINT_FLAG (nbd_can_fua);
130 PRINT_FLAG (nbd_can_multi_conn);
131 PRINT_FLAG (nbd_can_trim);
132 PRINT_FLAG (nbd_can_zero);
133 #if LIBNBD_HAVE_NBD_CAN_FAST_ZERO /* Added in 1.2 */
134 PRINT_FLAG (nbd_can_fast_zero);
135 #endif
136 PRINT_FLAG (nbd_is_read_only);
137 PRINT_FLAG (nbd_is_rotational);
138
139 /* Close the libnbd handle. */
140 nbd_close (nbd);
141
142 exit (EXIT_SUCCESS);
143 }
144
146 nbd_create(3), nbd_get_canonical_export_name(3),
147 nbd_get_export_description(3), nbd_get_full_info(3), libnbd(3).
148
150 Eric Blake
151
152 Richard W.M. Jones
153
155 Copyright (C) 2019-2021 Red Hat Inc.
156
158 This library is free software; you can redistribute it and/or modify it
159 under the terms of the GNU Lesser General Public License as published
160 by the Free Software Foundation; either version 2 of the License, or
161 (at your option) any later version.
162
163 This library is distributed in the hope that it will be useful, but
164 WITHOUT ANY WARRANTY; without even the implied warranty of
165 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
166 Lesser General Public License for more details.
167
168 You should have received a copy of the GNU Lesser General Public
169 License along with this library; if not, write to the Free Software
170 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
171 02110-1301 USA
172
173
174
175libnbd-1.7.12 2021-05-29 nbd_set_full_info(3)