=head1 NAME

nbd_aio_block_status - send block status command, with 32-bit callback

=head1 SYNOPSIS

 #include <libnbd.h>

 typedef struct {
   int (*callback) (void *user_data,
                    const char *metacontext,
                    uint64_t offset, uint32_t *entries,
                    size_t nr_entries, int *error);
   void *user_data;
   void (*free) (void *user_data);
 } nbd_extent_callback;

 typedef struct {
   int (*callback) (void *user_data, int *error);
   void *user_data;
   void (*free) (void *user_data);
 } nbd_completion_callback;

 int64_t nbd_aio_block_status (
           struct nbd_handle *h, uint64_t count,
           uint64_t offset,
           nbd_extent_callback extent_callback,
           nbd_completion_callback completion_callback,
           uint32_t flags
         );

=head1 DESCRIPTION

Send the block status command to the NBD server.

To check if the command completed, call L<nbd_aio_command_completed(3)>.
Or supply the optional C<completion_callback> which will be invoked
as described in L<libnbd(3)/Completion callbacks>.

Other parameters behave as documented in L<nbd_block_status(3)>.

This function is inherently limited to 32-bit values.  If the
server replies with a larger extent, the length of that extent
will be truncated to just below 32 bits and any further extents
from the server will be ignored.  If the server replies with a
status value larger than 32 bits (only possible when extended
headers are in use), the callback function will be passed an
C<EOVERFLOW> error.  To get the full extent information from a
server that supports 64-bit extents, you must use
L<nbd_aio_block_status_64(3)>.


By default, libnbd will reject attempts to use this function with
parameters that are likely to result in server failure, such as
requesting an unknown command flag.  The L<nbd_set_strict_mode(3)>
function can be used to alter which scenarios should await a server
reply rather than failing fast.

=head1 RETURN VALUE

This call returns the 64 bit cookie of the command.
The cookie is E<ge> C<1>.
Cookies are unique (per libnbd handle, not globally).

=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_aio_block_status
can be called when the handle is in the following state:

 ┌─────────────────────────────────────┬─────────────────────────┐
 │ Handle created, before connecting   │ ❌ error                │
 │ Connecting                          │ ❌ error                │
 │ Connecting & handshaking (opt_mode) │ ❌ error                │
 │ Connected to the server             │ ✅ allowed              │
 │ Connection shut down                │ ❌ error                │
 │ Handle dead                         │ ❌ error                │
 └─────────────────────────────────────┴─────────────────────────┘

=head1 VERSION

This function first appeared in libnbd 1.0.

If you need to test if this function is available at compile time
check if the following macro is defined:

 #define LIBNBD_HAVE_NBD_AIO_BLOCK_STATUS 1

=head1 SEE ALSO

L<nbd_aio_block_status_64(3)>,
L<nbd_aio_command_completed(3)>,
L<nbd_block_status(3)>,
L<nbd_can_meta_context(3)>,
L<nbd_create(3)>,
L<nbd_set_strict_mode(3)>,
L<libnbd(3)/Issuing asynchronous commands>,
L<libnbd(3)>.

=head1 AUTHORS

Eric Blake

Richard W.M. Jones

=head1 COPYRIGHT

Copyright Red Hat
