*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->HP-UX 11i man pages -> aio_read (2)              


 aio_read(2)                                                     aio_read(2)

 NAME    [Toc]    [Back]
      aio_read() - start an asynchronous read operation

 SYNOPSIS    [Toc]    [Back]
      #include <aio.h>

      int aio_read(struct aiocb *aiocbp);

 DESCRIPTION    [Toc]    [Back]
      The aio_read() function allows the calling process to perform an
      asynchronous read from a previously opened file.  The function call
      returns when the read operation has been enqueued for processing.  At
      this point, processing of the read operation may proceed concurrently
      with execution of the calling process or thread.

      If an error condition is detected that prevents the read request from
      being enqueued, aio_read() returns -1 and sets errno to indicate the
      cause of the failure.  Once the read operation has been successfully
      enqueued, an aio_error() and aio_return() function referencing the
      aiocb referred to by aiocbp must be used to determine its status and
      any error conditions, including those normally reported by read().
      The request remains enqueued and consumes process and system resources
      until aio_return() is called.

      The aio_read() function allows the calling process to read aiocbp-
      >aio_nbytes from the file associated with aiocbp->aio_fildes into the
      buffer pointed to by aiocbp->aio_buf.  The priority of the read
      operation is reduced by the value of aiocbp->aio_reqprio, which must
      be a value between 0 (zero) and a maximum value which can be obtained
      using the sysconf() call with the argument _SC_AIO_PRIO_DELTA_MAX.  A
      value of 0 (zero) yields no reduction in priority.  The aiocbp-
      >aio_lio_opcode field is ignored.

      The read operation takes place at the absolute position in the file
      given by aiocbp->aio_offset, as if lseek() were called immediately
      prior to the operation with offset equal to aiocbp->aio_offset and
      whence set to SEEK_SET.  However, the value of the file offset is
      never changed by asynchronous I/O operations.

      Deallocating or altering the contents of memory referred to by aiocbp
      while an asynchronous read operation is outstanding (i.e. before
      aio_return() has been called) may produce unpredictable results.

      If aiocbp->aio_sigevent is a valid signal event structure, then the
      designated signal will be delivered when the requested asynchronous
      read operation completes.

      To use this function, link in the realtime library by specifying -lrt
      on the compiler or linker command line.

 Hewlett-Packard Company            - 1 -   HP-UX 11i Version 2: August 2003

 aio_read(2)                                                     aio_read(2)

 RETURN VALUE    [Toc]    [Back]
      aio_read() returns the following values:

            0             Successful completion, the operation has been

           -1             Failure.  The requested operation was not
                          enqueued.  errno is set to indicate the error.

      The return value from aio_read() reflects the success or failure of
      enqueuing the requested read operation for asynchronous processing.
      aio_read() fails if an error in the function call is immediately
      detected, or if system resource limits prevent the request from being
      enqueued.  Other error conditions are reported asynchronously and must
      be retrieved with aio_error() and aio_return().

 ERRORS    [Toc]    [Back]
      If aio_read() detects one of the following error conditions, errno is
      set to the indicated value:

           [EAGAIN]       The request could not be queued either because of
                          a resource shortage or because the per-process or
                          system-wide limit on asynchronous I/O operations
                          or asynchronous threads would have been exceeded.

           [EINVAL]       aiocb->aio_sigevent is not a valid address in the
                          process virtual address space.

           [EINVAL]       The parameters of the indicated sigevent in
                          aiocb->aio_sigevent are invalid.

           [EEXIST]       The aiocbp is already in use for another
                          asynchronous I/O operation.

      Once the read request has been enqueued by aio_read(), the following
      errors, in addition to all of the errors normally reported by the
      read() function, may be reported asynchronously by a subsequent call
      to aio_error() or aio_return() referencing its aiocb.

           [EBADF]        The aiocbp->aio_fildes was not a valid file
                          descriptor open for reading.

           [EINVAL]       The value of aiocbp->aio_reqprio is not valid.

           [EINVAL]       The value of aiocbp->aio_nbytes is invalid.

           [EINVAL]       The file offset implied by aiocbp->aio_offset or
                          aiocbp->aio_offset+aiocbp->aio_nbytes are not
                          valid for the file at the time the request is

 Hewlett-Packard Company            - 2 -   HP-UX 11i Version 2: August 2003

 aio_read(2)                                                     aio_read(2)

           [ECANCELED]    The read operation was canceled due to a
                          subsequent call to aio_cancel().

 EXAMPLES    [Toc]    [Back]
      The following code sequence and call to aio_read() starts an
      asynchronous read operation.

           #include <fcntl.h>
           #include <errno.h>
           #include <aio.h>
           char buf[4096];
           ssize_t retval; ssize_t nbytes;
           struct aiocb myaiocb;
           bzero( &myaiocb, sizeof (struct aiocb));
           myaiocb.aio_fildes = open( "/dev/null", O_RDONLY);
           myaiocb.aio_offset = 0;
           myaiocb.aio_buf = (void *) buf;
           myaiocb.aio_nbytes = sizeof (buf);
           myaiocb.aio_sigevent.sigev_notify = SIGEV_NONE;
           retval = aio_read( &myaiocb );
           if (retval) perror("aio_read:");
           /* continue processing */
           /* wait for completion */
           while ( (retval = aio_error( &myaiocb) ) == EINPROGRESS) ;
           /* free the aiocb */
           nbytes = aio_return( &myaiocb);

 SEE ALSO    [Toc]    [Back]
      aio_cancel(2), aio_error(2), aio_fsync(2), aio_return(2),
      aio_suspend(2), aio_write(2), lio_listio(2), read(2), aio(5).

      aio_read(): POSIX Realtime Extensions, IEEE Std 1003.1b

 Hewlett-Packard Company            - 3 -   HP-UX 11i Version 2: August 2003
[ Back ]
 Similar pages
Name OS Title
aio_write HP-UX start asynchronous write operation
lio_listio HP-UX start a list of asynchronous I/O operations
aio_cancel HP-UX cancel an asynchronous I/O operation
aio_suspend HP-UX wait for an asynchronous I/O operation to complete
aio_return HP-UX return status of an asynchronous I/O operation
aio_cancel FreeBSD cancel an outstanding asynchronous I/O operation (REALTIME)
aio_return Tru64 Returns the status of an asynchronous I/O operation (P1003.1b)
aio_return IRIX return error status of an asynchronous I/O operation
aio_error HP-UX return error status of an asynchronous I/O operation
aio_error IRIX return error status of an asynchronous I/O operation
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service