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 size constraint advertised by the server, if any.  If the return is zero, the server
       did not advertise a constraint.  "size_type" must be one of the following constraints:

       "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,  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,
           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, some NBD servers will abruptly disconnect if a  transaction  involves  more
           than 32M.

       Future NBD extensions may result in additional "size_type" values.

       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.

HANDLE STATE

       The handle must be negotiating, or connected with the server, or shut  down,  otherwise  this  call  will
       return an 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_zero(3), libnbd(3).

AUTHORS

       Eric Blake

       Richard W.M. Jones

COPYRIGHT

       Copyright (C) 2019-2021 Red Hat Inc.

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.10.5                                      2022-02-11                              nbd_get_block_size(3)