=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
