=head1 NAME

nbd_aio_pread - read from 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_pread (
           struct nbd_handle *h, void *buf, size_t count,
           uint64_t offset,
           nbd_completion_callback completion_callback,
           uint32_t flags
         );

=head1 DESCRIPTION

Issue a read 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.  Furthermore, if the C<error> parameter to
C<completion_callback> is set or if L<nbd_aio_command_completed(3)>
reports failure, and if L<nbd_get_pread_initialize(3)> returns true,
then libnbd sanitized C<buf>, but it is unspecified whether the
contents of C<buf> will read as zero or as partial results from the
server.  If L<nbd_get_pread_initialize(3)> returns false, then
libnbd did not sanitize C<buf>, and the contents are undefined
on failure.

Other parameters behave as documented in L<nbd_pread(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_pread
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_PREAD 1

=head1 EXAMPLE

This example is also available as F<examples/aio-connect-read.c>
in the libnbd source code.

 /* This example shows how to use the AIO (asynchronous) low
  * level API to connect to a server and read the disk.
  *
  * Here are a few ways to try this example:
  *
  * nbdkit -U - linuxdisk . \
  *   --run './aio-connect-read $unixsocket'
  *
  * nbdkit -U - floppy . \
  *   --run './aio-connect-read $unixsocket'
  *
  * nbdkit -U - pattern size=1M \
  *   --run './aio-connect-read $unixsocket'
  */

 #include <stdio.h>
 #include <stdlib.h>
 #include <stdint.h>
 #include <inttypes.h>
 #include <errno.h>
 #include <assert.h>

 #include <libnbd.h>

 #define NR_SECTORS 32
 #define SECTOR_SIZE 512

 struct data {
   uint64_t offset;
   char sector[SECTOR_SIZE];
 };

 static int
 hexdump (void *user_data, int *error)
 {
   struct data *data = user_data;
   FILE *pp;

   if (*error) {
     errno = *error;
     perror ("failed to read");
     exit (EXIT_FAILURE);
   }

   printf ("sector at offset 0x%" PRIx64 ":\n",
           data->offset);
   pp = popen ("hexdump -C", "w");
   if (pp == NULL) {
     perror ("popen: hexdump");
     exit (EXIT_FAILURE);
   }
   fwrite (data->sector, SECTOR_SIZE, 1, pp);
   pclose (pp);
   printf ("\n");

   /* Returning 1 from the callback automatically retires
    * the command.
    */
   return 1;
 }

 static struct data data[NR_SECTORS];

 int
 main (int argc, char *argv[])
 {
   struct nbd_handle *nbd;
   size_t i;

   if (argc != 2) {
     fprintf (stderr, "%s socket\n", argv[0]);
     exit (EXIT_FAILURE);
   }

   /* Create the libnbd handle. */
   nbd = nbd_create ();
   if (nbd == NULL) {
     fprintf (stderr, "%s\n", nbd_get_error ());
     exit (EXIT_FAILURE);
   }

   /* Connect to the NBD server over a Unix domain socket.
    * This only starts the connection.
    */
   if (nbd_aio_connect_unix (nbd, argv[1]) == -1) {
     fprintf (stderr, "%s\n", nbd_get_error ());
     exit (EXIT_FAILURE);
   }

   /* Wait for the connection to complete.  The use of
    * nbd_poll here is only as an example.  You could also
    * integrate this with poll(2), glib or another main
    * loop.  Read libnbd(3) and the source file lib/poll.c.
    */
   while (!nbd_aio_is_ready (nbd)) {
     if (nbd_poll (nbd, -1) == -1) {
       fprintf (stderr, "%s\n", nbd_get_error ());
       exit (EXIT_FAILURE);
     }
   }

   assert (nbd_get_size (nbd) >= NR_SECTORS * SECTOR_SIZE);

   /* Issue read commands for the first NR sectors. */
   for (i = 0; i < NR_SECTORS; ++i) {
     data[i].offset = i * SECTOR_SIZE;

     /* The callback (hexdump) is called when the command
      * completes.  The buffer must continue to exist while
      * the command is running.
      */
     if (nbd_aio_pread (nbd, data[i].sector, SECTOR_SIZE,
                        data[i].offset,
                        (nbd_completion_callback) {
                          .callback = hexdump,
                          .user_data = &data[i],
                        }, 0) == -1) {
       fprintf (stderr, "%s\n", nbd_get_error ());
       exit (EXIT_FAILURE);
     }
   }

   /* Run the main loop until all the commands have
    * completed and retired.  Again the use of nbd_poll
    * here is only as an example.
    */
   while (nbd_aio_in_flight (nbd) > 0) {
     if (nbd_poll (nbd, -1) == -1) {
       fprintf (stderr, "%s\n", nbd_get_error ());
       exit (EXIT_FAILURE);
     }
   }

   /* Close the libnbd handle. */
   nbd_close (nbd);

   exit (EXIT_SUCCESS);
 }

=head1 SEE ALSO

L<nbd_aio_command_completed(3)>,
L<nbd_aio_pread_structured(3)>,
L<nbd_create(3)>,
L<nbd_get_pread_initialize(3)>,
L<nbd_pread(3)>,
L<nbd_set_pread_initialize(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