Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > A

aio_read(2)

HP-UX 11i Version 3: February 2007
» 

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index

NAME

aio_read() — start an asynchronous read operation

SYNOPSIS

#include <aio.h>

int aio_read(struct aiocb *aiocbp);

DESCRIPTION

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.

RETURN VALUE

aio_read() returns the following values:

0

Successful completion, the operation has been enqueued.

-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

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 processed.

ECANCELED

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

EXAMPLES

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);

STANDARDS CONFORMANCE

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

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.