1nbd_block_status(3) LIBNBD nbd_block_status(3)
2
3
4
6 nbd_block_status - send block status command, with 32-bit callback
7
9 #include <libnbd.h>
10
11 typedef struct {
12 int (*callback) (void *user_data,
13 const char *metacontext,
14 uint64_t offset, uint32_t *entries,
15 size_t nr_entries, int *error);
16 void *user_data;
17 void (*free) (void *user_data);
18 } nbd_extent_callback;
19
20 int nbd_block_status (
21 struct nbd_handle *h, uint64_t count,
22 uint64_t offset, nbd_extent_callback extent_callback,
23 uint32_t flags
24 );
25
27 Issue the block status command to the NBD server. If supported by the
28 server, this causes metadata context information about blocks beginning
29 from the specified offset to be returned. The "count" parameter is a
30 hint: the server may choose to return less status, or the final block
31 may extend beyond the requested range. If multiple contexts are
32 supported, the number of blocks and cumulative length of those blocks
33 need not be identical between contexts.
34
35 Note that not all servers can support a "count" of 4GiB or larger;
36 nbd_get_extended_headers_negotiated(3) indicates which servers will
37 parse a request larger than 32 bits. The NBD protocol does not yet
38 have a way for a client to learn if the server will enforce an even
39 smaller maximum block status size, although a future extension may add
40 a constraint visible in nbd_get_block_size(3). Furthermore, this
41 function is inherently limited to 32-bit values. If the server replies
42 with a larger extent, the length of that extent will be truncated to
43 just below 32 bits and any further extents from the server will be
44 ignored. If the server replies with a status value larger than 32 bits
45 (only possible when extended headers are in use), the callback function
46 will be passed an "EOVERFLOW" error. To get the full extent
47 information from a server that supports 64-bit extents, you must use
48 nbd_block_status_64(3).
49
50 Depending on which metadata contexts were enabled before connecting
51 (see nbd_add_meta_context(3)) and which are supported by the server
52 (see nbd_can_meta_context(3)) this call returns information about
53 extents by calling back to the "extent" function. The callback cannot
54 call "nbd_*" APIs on the same handle since it holds the handle lock and
55 will cause a deadlock. If the callback returns -1, and no earlier
56 error has been detected, then the overall block status command will
57 fail with any non-zero value stored into the callback's "error"
58 parameter (with a default of "EPROTO"); but any further contexts will
59 still invoke the callback.
60
61 The "extent" function is called once per type of metadata available,
62 with the "user_data" passed to this function. The "metacontext"
63 parameter is a string such as "base:allocation". The "entries" array
64 is an array of pairs of integers with the first entry in each pair
65 being the length (in bytes) of the block and the second entry being a
66 status/flags field which is specific to the metadata context. The
67 number of pairs passed to the function is "nr_entries/2". The NBD
68 protocol document in the section about "NBD_REPLY_TYPE_BLOCK_STATUS"
69 describes the meaning of this array; for contexts known to libnbd,
70 <libnbd.h> contains constants beginning with "LIBNBD_STATE_" that may
71 help decipher the values. On entry to the callback, the "error"
72 parameter contains the errno value of any previously detected error,
73 but even if an earlier error was detected, the current "metacontext"
74 and "entries" are valid.
75
76 It is possible for the extent function to be called more times than you
77 expect (if the server is buggy), so always check the "metacontext"
78 field to ensure you are receiving the data you expect. It is also
79 possible that the extent function is not called at all, even for
80 metadata contexts that you requested. This indicates either that the
81 server doesn't support the context or for some other reason cannot
82 return the data.
83
84 The "flags" parameter may be 0 for no flags, or may contain
85 "LIBNBD_CMD_FLAG_REQ_ONE" meaning that the server should return only
86 one extent per metadata context where that extent does not exceed
87 "count" bytes; however, libnbd does not validate that the server obeyed
88 the flag.
89
90 By default, libnbd will reject attempts to use this function with
91 parameters that are likely to result in server failure, such as
92 requesting an unknown command flag. The nbd_set_strict_mode(3)
93 function can be used to alter which scenarios should await a server
94 reply rather than failing fast.
95
97 If the call is successful the function returns 0.
98
100 On error -1 is returned.
101
102 Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
103 of the error.
104
105 The following parameters must not be NULL: "h". For more information
106 see "Non-NULL parameters" in libnbd(3).
107
109 The handle must be connected with the server, otherwise this call will
110 return an error.
111
113 This function first appeared in libnbd 1.0.
114
115 If you need to test if this function is available at compile time check
116 if the following macro is defined:
117
118 #define LIBNBD_HAVE_NBD_BLOCK_STATUS 1
119
121 nbd_add_meta_context(3), nbd_aio_block_status(3),
122 nbd_block_status_64(3), nbd_can_meta_context(3), nbd_create(3),
123 nbd_get_block_size(3), nbd_get_extended_headers_negotiated(3),
124 nbd_set_strict_mode(3), libnbd(3).
125
127 Eric Blake
128
129 Richard W.M. Jones
130
132 Copyright Red Hat
133
135 This library is free software; you can redistribute it and/or modify it
136 under the terms of the GNU Lesser General Public License as published
137 by the Free Software Foundation; either version 2 of the License, or
138 (at your option) any later version.
139
140 This library is distributed in the hope that it will be useful, but
141 WITHOUT ANY WARRANTY; without even the implied warranty of
142 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
143 Lesser General Public License for more details.
144
145 You should have received a copy of the GNU Lesser General Public
146 License along with this library; if not, write to the Free Software
147 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
148 02110-1301 USA
149
150
151
152libnbd-1.18.1 2023-10-31 nbd_block_status(3)