NAME

       nbd_get_block_size - return a specific server block size constraint

SYNOPSIS

        #include <libnbd.h>

        int64_t nbd_get_block_size (
                  struct nbd_handle *h, int size_type
                );

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 "size_type" parameter selects which constraint to read.  It can be one of:

       "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 "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 "LIBNBD_STRICT_ALIGN" is cleared in nbd_set_strict_mode(3).

       "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.

       "LIBNBD_SIZE_MAXIMUM" = 2
           If  non-zero,  this  represents  the  maximum  length  that  the  server  is willing to handle during
           nbd_pread(3) or nbd_pwrite(3).  Other functions like 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.

       "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  "LIBNBD_STRICT_PAYLOAD"  is  cleared  in
           nbd_set_strict_mode(3).   It  is  always  non-zero: never smaller than 1M, never larger than 64M, and
           matches "LIBNBD_SIZE_MAXIMUM" when possible.

       Future NBD extensions may result in additional "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
       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.

RETURN VALUE

       This call returns a 64 bit signed integer ≥ 0.

ERRORS

       On error -1 is returned.

       Refer to "ERROR HANDLING" in libnbd(3) for how to get further details of the error.

       The following parameters must not be NULL: "h".   For  more  information  see  "Non-NULL  parameters"  in
       libnbd(3).

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                │
        └─────────────────────────────────────┴─────────────────────────┘

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

SEE ALSO

       nbd_create(3),  nbd_get_protocol(3),  nbd_get_size(3),  nbd_opt_info(3),   nbd_pread(3),   nbd_pwrite(3),
       nbd_set_request_block_size(3), nbd_zero(3), libnbd(3).

AUTHORS

       Eric Blake

       Richard W.M. Jones

COPYRIGHT

       Copyright Red Hat

LICENSE

       This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser
       General  Public License as published by the Free Software Foundation; either version 2 of the License, or
       (at your option) any later version.

       This library is distributed in the hope that it will be useful, but WITHOUT ANY  WARRANTY;  without  even
       the  implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General
       Public License for more details.

       You should have received a copy of the GNU Lesser General Public License along with this library; if not,
       write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

libnbd-1.20.0                                      2024-04-05                              nbd_get_block_size(3)