=head1 NAME

nbd_aio_pwrite - write to the NBD server

=head1 SYNOPSIS

 #include <libnbd.h>

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

 int64_t nbd_aio_pwrite (
           struct nbd_handle *h, const void *buf,
           size_t count, uint64_t offset,
           nbd_completion_callback completion_callback,
           uint32_t flags
         );

=head1 DESCRIPTION

Issue a write 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>.

Note that you must ensure C<buf> is valid until the command has
completed.  Other parameters behave as documented in L<nbd_pwrite(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>, C<buf>.
For more information see L<libnbd(3)/Non-NULL parameters>.

=head1 HANDLE STATE

nbd_aio_pwrite
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_PWRITE 1

=head1 SEE ALSO

L<nbd_aio_command_completed(3)>,
L<nbd_create(3)>,
L<nbd_is_read_only(3)>,
L<nbd_pwrite(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
