1nbd_opt_list_meta_context_queries(3)LIBNBDnbd_opt_list_meta_context_queries(3)
2
3
4

NAME

6       nbd_opt_list_meta_context_queries - list available meta contexts, using
7       explicit query list
8

SYNOPSIS

10        #include <libnbd.h>
11
12        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
18        int nbd_opt_list_meta_context_queries (
19              struct nbd_handle *h, char **queries,
20              nbd_context_callback context_callback
21            );
22

DESCRIPTION

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 an explicit list
27       of queries provided as a parameter (see nbd_opt_list_meta_context(3) if
28       you want to reuse an implicit query list instead).  This can only be
29       used if nbd_set_opt_mode(3) enabled option mode.
30
31       The NBD protocol allows a client to decide how many queries to ask the
32       server.  For this function, the list is explicit in the "queries"
33       parameter.  When the list is empty, a server will typically reply with
34       all contexts that it supports; when the list is non-empty, the server
35       will reply only with supported contexts that match the client's
36       request.  Note that a reply by the server might be encoded to represent
37       several feasible contexts within one string, rather than multiple
38       strings per actual context name that would actually succeed during
39       nbd_opt_go(3); so it is still necessary to use nbd_can_meta_context(3)
40       after connecting to see which contexts are actually supported.
41
42       The "context" function is called once per server reply, with any
43       "user_data" passed to this function, and with "name" supplied by the
44       server.  Remember that it is not safe to call nbd_add_meta_context(3)
45       from within the context of the callback function; rather, your code
46       must copy any "name" needed for later use after this function
47       completes.  At present, the return value of the callback is ignored,
48       although a return of -1 should be avoided.
49
50       For convenience, when this function succeeds, it returns the number of
51       replies returned by the server.
52
53       Not all servers understand this request, and even when it is
54       understood, the server might intentionally send an empty list because
55       it does not support the requested context, or may encounter a failure
56       after delivering partial results.  Thus, this function may succeed even
57       when no contexts are reported, or may fail but have a non-empty list.
58       Likewise, the NBD protocol does not specify an upper bound for the
59       number of replies that might be advertised, so client code should be
60       aware that a server may send a lengthy list.
61

RETURN VALUE

63       This call returns an integer ≥ 0.
64

ERRORS

66       On error -1 is returned.
67
68       Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
69       of the error.
70
71       The following parameters must not be NULL: "h", "queries".  For more
72       information see "Non-NULL parameters" in libnbd(3).
73

HANDLE STATE

75       The handle must be negotiating, otherwise this call will return an
76       error.
77

VERSION

79       This function first appeared in libnbd 1.16.
80
81       If you need to test if this function is available at compile time check
82       if the following macro is defined:
83
84        #define LIBNBD_HAVE_NBD_OPT_LIST_META_CONTEXT_QUERIES 1
85

SEE ALSO

87       nbd_add_meta_context(3), nbd_aio_opt_list_meta_context_queries(3),
88       nbd_can_meta_context(3), nbd_connect_uri(3), nbd_create(3),
89       nbd_opt_go(3), nbd_opt_list_meta_context(3), nbd_set_export_name(3),
90       nbd_set_opt_mode(3), libnbd(3).
91

AUTHORS

93       Eric Blake
94
95       Richard W.M. Jones
96

98       Copyright Red Hat
99

LICENSE

101       This library is free software; you can redistribute it and/or modify it
102       under the terms of the GNU Lesser General Public License as published
103       by the Free Software Foundation; either version 2 of the License, or
104       (at your option) any later version.
105
106       This library is distributed in the hope that it will be useful, but
107       WITHOUT ANY WARRANTY; without even the implied warranty of
108       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
109       Lesser General Public License for more details.
110
111       You should have received a copy of the GNU Lesser General Public
112       License along with this library; if not, write to the Free Software
113       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
114       02110-1301 USA
115
116
117
118libnbd-1.16.5                     2023-09-2n6bd_opt_list_meta_context_queries(3)
Impressum