1nbd_add_meta_context(3)             LIBNBD             nbd_add_meta_context(3)
2
3
4

NAME

6       nbd_add_meta_context - ask server to negotiate metadata context
7

SYNOPSIS

9        #include <libnbd.h>
10
11        int nbd_add_meta_context (
12              struct nbd_handle *h, const char *name
13            );
14

DESCRIPTION

16       During connection libnbd can negotiate zero or more metadata contexts
17       with the server.  Metadata contexts are features (such as
18       "base:allocation") which describe information returned by the
19       nbd_block_status(3) command (for "base:allocation" this is whether
20       blocks of data are allocated, zero or sparse).
21
22       This call adds one metadata context to the list to be negotiated.  You
23       can call it as many times as needed.  The list is initially empty when
24       the handle is created; you can check the contents of the list with
25       nbd_get_nr_meta_contexts(3) and nbd_get_meta_context(3), or clear it
26       with nbd_clear_meta_contexts(3).
27
28       The NBD protocol limits meta context names to 4096 bytes, but servers
29       may not support the full length.  The encoding of meta context names is
30       always UTF-8.
31
32       Not all servers support all metadata contexts.  To learn if a context
33       was actually negotiated, call nbd_can_meta_context(3) after connecting.
34
35       The single parameter is the name of the metadata context, for example
36       "LIBNBD_CONTEXT_BASE_ALLOCATION".  <libnbd.h> includes defined
37       constants beginning with "LIBNBD_CONTEXT_" for some well-known
38       contexts, but you are free to pass in other contexts.
39
40       Other metadata contexts are server-specific, but include
41       "qemu:dirty-bitmap:..." and "qemu:allocation-depth" for qemu-nbd (see
42       qemu-nbd -B and -A options).
43

RETURN VALUE

45       If the call is successful the function returns 0.
46

ERRORS

48       On error -1 is returned.
49
50       Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
51       of the error.
52
53       The following parameters must not be NULL: "h", "name".  For more
54       information see "Non-NULL parameters" in libnbd(3).
55

HANDLE STATE

57       The handle must be newly created, or negotiating, otherwise this call
58       will return an error.
59

VERSION

61       This function first appeared in libnbd 1.0.
62
63       If you need to test if this function is available at compile time check
64       if the following macro is defined:
65
66        #define LIBNBD_HAVE_NBD_ADD_META_CONTEXT 1
67

SEE ALSO

69       nbd_block_status(3), nbd_can_meta_context(3),
70       nbd_clear_meta_contexts(3), nbd_create(3), nbd_get_meta_context(3),
71       nbd_get_nr_meta_contexts(3), libnbd(3).
72

AUTHORS

74       Eric Blake
75
76       Richard W.M. Jones
77

79       Copyright Red Hat
80

LICENSE

82       This library is free software; you can redistribute it and/or modify it
83       under the terms of the GNU Lesser General Public License as published
84       by the Free Software Foundation; either version 2 of the License, or
85       (at your option) any later version.
86
87       This library is distributed in the hope that it will be useful, but
88       WITHOUT ANY WARRANTY; without even the implied warranty of
89       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
90       Lesser General Public License for more details.
91
92       You should have received a copy of the GNU Lesser General Public
93       License along with this library; if not, write to the Free Software
94       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
95       02110-1301 USA
96
97
98
99libnbd-1.16.5                     2023-09-26           nbd_add_meta_context(3)
Impressum