1nbd_opt_list_meta_context(3) LIBNBD nbd_opt_list_meta_context(3)
2
6 nbd_opt_list_meta_context - list available 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_list_meta_context (
19 struct nbd_handle *h,
20 nbd_context_callback context_callback
21 );
22
24 Request that the server list available meta contexts associated with
25 the export previously specified by the most recent
26 nbd_set_export_name(3) or nbd_connect_uri(3), and with a list of
27 queries from prior calls to nbd_add_meta_context(3) (see
28 nbd_opt_list_meta_context_queries(3) if you want to supply an explicit
29 query list instead). This can only be used if nbd_set_opt_mode(3)
30 enabled option mode.
31 The NBD protocol allows a client to decide how many queries to ask the
33 server. Rather than taking that list of queries as a parameter to this
34 function, libnbd reuses the current list of requested meta contexts as
35 set by nbd_add_meta_context(3); you can use nbd_clear_meta_contexts(3)
36 to set up a different list of queries. When the list is empty, a
37 server will typically reply with all contexts that it supports; when
38 the list is non-empty, the server will reply only with supported
39 contexts that match the client's request. Note that a reply by the
40 server might be encoded to represent several feasible contexts within
41 one string, rather than multiple strings per actual context name that
42 would actually succeed during nbd_opt_go(3); so it is still necessary
43 to use nbd_can_meta_context(3) after connecting to see which contexts
44 are actually supported.
45 The "context" function is called once per server reply, with any
47 "user_data" passed to this function, and with "name" supplied by the
48 server. Remember that it is not safe to call nbd_add_meta_context(3)
49 from within the context of the callback function; rather, your code
50 must copy any "name" needed for later use after this function
51 completes. At present, the return value of the callback is ignored,
52 although a return of -1 should be avoided.
53 For convenience, when this function succeeds, it returns the number of
55 replies returned by the server.
56 Not all servers understand this request, and even when it is
58 understood, the server might intentionally send an empty list because
59 it does not support the requested context, or may encounter a failure
60 after delivering partial results. Thus, this function may succeed even
61 when no contexts are reported, or may fail but have a non-empty list.
62 Likewise, the NBD protocol does not specify an upper bound for the
63 number of replies that might be advertised, so client code should be
64 aware that a server may send a lengthy list.
65
67 This call returns an integer ≥ 0.
68
70 On error -1 is returned.
71 Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
73 of the error.
74 The following parameters must not be NULL: "h". For more information
76 see "Non-NULL parameters" in libnbd(3).
77
79 The handle must be negotiating, otherwise this call will return an
80 error.
81
83 This function first appeared in libnbd 1.6.
84 If you need to test if this function is available at compile time check
86 if the following macro is defined:
87 #define LIBNBD_HAVE_NBD_OPT_LIST_META_CONTEXT 1
89
91 nbd_add_meta_context(3), nbd_aio_opt_list_meta_context(3),
92 nbd_can_meta_context(3), nbd_clear_meta_contexts(3),
93 nbd_connect_uri(3), nbd_create(3), nbd_opt_go(3),
94 nbd_opt_list_meta_context_queries(3), nbd_opt_set_meta_context(3),
95 nbd_set_export_name(3), nbd_set_opt_mode(3), libnbd(3).
96
98 Eric Blake
99 Richard W.M. Jones
101
103 Copyright Red Hat
104
106 This library is free software; you can redistribute it and/or modify it
107 under the terms of the GNU Lesser General Public License as published
108 by the Free Software Foundation; either version 2 of the License, or
109 (at your option) any later version.
110 This library is distributed in the hope that it will be useful, but
112 WITHOUT ANY WARRANTY; without even the implied warranty of
113 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
114 Lesser General Public License for more details.
115 You should have received a copy of the GNU Lesser General Public
117 License along with this library; if not, write to the Free Software
118 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
119 02110-1301 USA
120libnbd-1.16.5 2023-09-26 nbd_opt_list_meta_context(3)