1nbd_opt_set_meta_context(3) LIBNBD nbd_opt_set_meta_context(3)
2
6 nbd_opt_set_meta_context - select specific meta contexts, using
7 implicit query list
8
10 #include <libnbd.h>
11 typedef struct {
13 int (*callback) (void *user_data, const char *name);
14 void *user_data;
15 void (*free) (void *user_data);
16 } nbd_context_callback;
17 int nbd_opt_set_meta_context (
19 struct nbd_handle *h,
20 nbd_context_callback context_callback
21 );
22
24 Request that the server supply all recognized meta contexts registered
25 through prior calls to nbd_add_meta_context(3), in conjunction with the
26 export previously specified by the most recent nbd_set_export_name(3)
27 or nbd_connect_uri(3). This can only be used if nbd_set_opt_mode(3)
28 enabled option mode. Normally, this function is redundant, as
29 nbd_opt_go(3) automatically does the same task if structured replies
30 have already been negotiated. But manual control over meta context
31 requests can be useful for fine-grained testing of how a server handles
32 unusual negotiation sequences. Often, use of this function is coupled
33 with nbd_set_request_meta_context(3) to bypass the automatic context
34 request normally performed by nbd_opt_go(3).
35 The NBD protocol allows a client to decide how many queries to ask the
37 server. Rather than taking that list of queries as a parameter to this
38 function, libnbd reuses the current list of requested meta contexts as
39 set by nbd_add_meta_context(3); you can use nbd_clear_meta_contexts(3)
40 to set up a different list of queries (see
41 nbd_opt_set_meta_context_queries(3) to pass an explicit list of
42 contexts instead). Since this function is primarily designed for
43 testing servers, libnbd does not prevent the use of this function on an
44 empty list or when nbd_set_request_structured_replies(3) has disabled
45 structured replies, in order to see how a server behaves.
46 The "context" function is called once per server reply, with any
48 "user_data" passed to this function, and with "name" supplied by the
49 server. Additionally, each server name will remain visible through
50 nbd_can_meta_context(3) until the next attempt at
51 nbd_set_export_name(3) or nbd_opt_set_meta_context(3), as well as
52 nbd_opt_go(3) or nbd_opt_info(3) that trigger an automatic meta context
53 request. Remember that it is not safe to call any "nbd_*" APIs from
54 within the context of the callback function. At present, the return
55 value of the callback is ignored, although a return of -1 should be
56 avoided.
57 For convenience, when this function succeeds, it returns the number of
59 replies returned by the server.
60 Not all servers understand this request, and even when it is
62 understood, the server might intentionally send an empty list because
63 it does not support the requested context, or may encounter a failure
64 after delivering partial results. Thus, this function may succeed even
65 when no contexts are reported, or may fail but have a non-empty list.
66
68 This call returns an integer ≥ 0.
69
71 On error -1 is returned.
72 Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
74 of the error.
75 The following parameters must not be NULL: "h". For more information
77 see "Non-NULL parameters" in libnbd(3).
78
80 The handle must be negotiating, otherwise this call will return an
81 error.
82
84 This function first appeared in libnbd 1.16.
85 If you need to test if this function is available at compile time check
87 if the following macro is defined:
88 #define LIBNBD_HAVE_NBD_OPT_SET_META_CONTEXT 1
90
92 nbd_add_meta_context(3), nbd_aio_opt_set_meta_context(3),
93 nbd_can_meta_context(3), nbd_clear_meta_contexts(3),
94 nbd_connect_uri(3), nbd_create(3), nbd_opt_go(3), nbd_opt_info(3),
95 nbd_opt_list_meta_context(3), nbd_opt_set_meta_context(3),
96 nbd_opt_set_meta_context_queries(3), nbd_set_export_name(3),
97 nbd_set_opt_mode(3), nbd_set_request_meta_context(3),
98 nbd_set_request_structured_replies(3), libnbd(3).
99
101 Eric Blake
102 Richard W.M. Jones
104
106 Copyright Red Hat
107
109 This library is free software; you can redistribute it and/or modify it
110 under the terms of the GNU Lesser General Public License as published
111 by the Free Software Foundation; either version 2 of the License, or
112 (at your option) any later version.
113 This library is distributed in the hope that it will be useful, but
115 WITHOUT ANY WARRANTY; without even the implied warranty of
116 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
117 Lesser General Public License for more details.
118 You should have received a copy of the GNU Lesser General Public
120 License along with this library; if not, write to the Free Software
121 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
122 02110-1301 USA
123libnbd-1.16.5 2023-09-26 nbd_opt_set_meta_context(3)