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
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
=head1 NAME
nbd_get_block_size - return a specific server block size constraint
=head1 SYNOPSIS
#include <libnbd.h>
int64_t nbd_get_block_size (
struct nbd_handle *h, int size_type
);
=head1 DESCRIPTION
Returns a specific block size constraint
advertised by the server.
If zero is returned it means the server did not advertise a constraint.
Constraints are hints. Servers differ in their behaviour as to
whether they enforce constraints or not.
The C<size_type> parameter selects which constraint to read.
It can be one of:
=over 4
=item C<LIBNBD_SIZE_MINIMUM> = 0
If non-zero, this will be a power of 2 between 1 and 64k; any client
request that is not aligned in length or offset to this size is likely
to fail with C<EINVAL>. The image size will generally also be a
multiple of this value (if not, the final few bytes are inaccessible
while obeying alignment constraints).
If zero (meaning no information was returned by the server), it is
safest to assume a minimum block size of 512, although many servers
support a minimum block size of 1.
If the server provides a constraint, then libnbd defaults to honoring
that constraint client-side unless C<LIBNBD_STRICT_ALIGN> is cleared
in C<nbd_set_strict_mode(3)>.
=item C<LIBNBD_SIZE_PREFERRED> = 1
If non-zero, this is a power of 2 representing the preferred size for
efficient I/O. Smaller requests may incur overhead such as
read-modify-write cycles that will not be present when using I/O that
is a multiple of this value. This value may be larger than the size
of the export.
If zero (meaning no information was returned by the server), using 4k
as a preferred block size tends to give decent performance.
=item C<LIBNBD_SIZE_MAXIMUM> = 2
If non-zero, this represents the maximum length that the server is
willing to handle during L<nbd_pread(3)> or L<nbd_pwrite(3)>. Other
functions like L<nbd_zero(3)> may still be able to use larger sizes.
Note that this function returns what the server advertised, but libnbd
itself imposes a maximum of 64M.
If zero (meaning no information was returned by the server), some NBD
servers will abruptly disconnect if a transaction sends or receives
more than 32M of data.
=item C<LIBNBD_SIZE_PAYLOAD> = 3
This value is not advertised by the server, but rather represents
the maximum outgoing payload size for a given connection that
libnbd will enforce unless C<LIBNBD_STRICT_PAYLOAD> is cleared
in C<nbd_set_strict_mode(3)>. It is always non-zero: never
smaller than 1M, never larger than 64M, and matches
C<LIBNBD_SIZE_MAXIMUM> when possible.
=back
Future NBD extensions may result in additional C<size_type> values.
Note that by default, libnbd requests all available block sizes,
but that a server may differ in what sizes it chooses to report
if L<nbd_set_request_block_size(3)> alters whether the client
requests sizes.
This call does not block, because it returns data that is saved in
the handle from the NBD protocol handshake.
=head1 RETURN VALUE
This call returns a 64 bit signed integer E<ge> 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>.
For more information see L<libnbd(3)/Non-NULL parameters>.
=head1 HANDLE STATE
nbd_get_block_size
can be called when the handle is in the following states:
┌─────────────────────────────────────┬─────────────────────────┐
│ Handle created, before connecting │ ❌ error │
│ Connecting │ ❌ error │
│ Connecting & handshaking (opt_mode) │ ✅ allowed │
│ Connected to the server │ ✅ allowed │
│ Connection shut down │ ✅ allowed │
│ Handle dead │ ❌ error │
└─────────────────────────────────────┴─────────────────────────┘
=head1 VERSION
This function first appeared in libnbd 1.4.
If you need to test if this function is available at compile time
check if the following macro is defined:
#define LIBNBD_HAVE_NBD_GET_BLOCK_SIZE 1
=head1 SEE ALSO
L<nbd_create(3)>,
L<nbd_get_protocol(3)>,
L<nbd_get_size(3)>,
L<nbd_opt_info(3)>,
L<nbd_pread(3)>,
L<nbd_pwrite(3)>,
L<nbd_set_request_block_size(3)>,
L<nbd_zero(3)>,
L<libnbd(3)>.
=head1 AUTHORS
Eric Blake
Richard W.M. Jones
=head1 COPYRIGHT
Copyright Red Hat
|
