1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
|
=head1 NAME
nbd_add_meta_context - ask server to negotiate metadata context
=head1 SYNOPSIS
#include <libnbd.h>
int nbd_add_meta_context (
struct nbd_handle *h, const char *name
);
=head1 DESCRIPTION
During connection libnbd can negotiate zero or more metadata
contexts with the server. Metadata contexts are features (such
as C<"base:allocation">) which describe information returned
by the L<nbd_block_status_64(3)> command (for C<"base:allocation">
this is whether blocks of data are allocated, zero or sparse).
This call adds one metadata context to the list to be negotiated.
You can call it as many times as needed. The list is initially
empty when the handle is created; you can check the contents of
the list with L<nbd_get_nr_meta_contexts(3)> and
L<nbd_get_meta_context(3)>, or clear it with
L<nbd_clear_meta_contexts(3)>.
The NBD protocol limits meta context names to 4096 bytes, but
servers may not support the full length. The encoding of meta
context names is always UTF-8.
Not all servers support all metadata contexts. To learn if a context
was actually negotiated, call L<nbd_can_meta_context(3)> after
connecting.
The single parameter is the name of the metadata context,
for example C<LIBNBD_CONTEXT_BASE_ALLOCATION>.
B<E<lt>libnbd.hE<gt>> includes defined constants beginning with
C<LIBNBD_CONTEXT_> for some well-known contexts, but you are free
to pass in other contexts.
Other metadata contexts are server-specific, but include
C<"qemu:dirty-bitmap:..."> and C<"qemu:allocation-depth"> for
qemu-nbd (see qemu-nbd I<-B> and I<-A> options).
=head1 RETURN VALUE
If the call is successful the function returns C<0>.
=head1 ERRORS
On error C<-1> is returned.
Refer to L<libnbd(3)/ERROR HANDLING>
for how to get further details of the error.
The following parameters must not be NULL: C<h>, C<name>.
For more information see L<libnbd(3)/Non-NULL parameters>.
=head1 HANDLE STATE
nbd_add_meta_context
can be called when the handle is in the following states:
┌─────────────────────────────────────┬─────────────────────────┐
│ Handle created, before connecting │ ✅ allowed │
│ Connecting │ ❌ error │
│ Connecting & handshaking (opt_mode) │ ✅ allowed │
│ Connected to the server │ ❌ error │
│ Connection shut down │ ❌ error │
│ Handle dead │ ❌ error │
└─────────────────────────────────────┴─────────────────────────┘
=head1 VERSION
This function first appeared in libnbd 1.0.
If you need to test if this function is available at compile time
check if the following macro is defined:
#define LIBNBD_HAVE_NBD_ADD_META_CONTEXT 1
=head1 SEE ALSO
L<nbd_block_status_64(3)>,
L<nbd_can_meta_context(3)>,
L<nbd_clear_meta_contexts(3)>,
L<nbd_create(3)>,
L<nbd_get_meta_context(3)>,
L<nbd_get_nr_meta_contexts(3)>,
L<libnbd(3)>.
=head1 AUTHORS
Eric Blake
Richard W.M. Jones
=head1 COPYRIGHT
Copyright Red Hat
|
