NAME

aio_read, aio_write − asynchronous read and write operations

SYNOPSIS

cc [ flag ... ] file ... −lposix4 [ library ... ]

#include <aio.h>

int aio_read(struct aiocb ∗aiocbp);

int aio_write(struct aiocb ∗aiocbp);

struct aiocb {

};

struct sigevent {

};

union sigval {

};

DESCRIPTION

The aio_read() function queues an asynchronous read request and returns control immediately.  Rather than blocking until completion, the read operation continues concurrently with other activity of the process. 

Upon enqueuing the request, the calling process reads aiocbp->nbytes from the file referred to by aiocbp->fildes into the buffer pointed to by aiocbp->aio_buf. 
aiocbp->offset marks the absolute position from the beginning of the file (in bytes) at which the read begins. 

The aio_write() function queues an asynchronous write request, and returns control immediately.  Rather than blocking until completion, the write operation continues concurrently with other activity of the process. 

Upon enqueuing the request, the calling process writes aiocbp->nbytes from  the buffer pointed to by aiocbp->aio_buf into the file referred to by aiocbp->fildes.  If O_APPEND is set for aiocbp->fildes, aio_write() operations append to the file in the same order as the calls were made. 

If O_APPEND is not set for the file descriptor, then the write operation will occur at the absolute position from the beginning of the file plus aiocbp->offset (in bytes). 

These asynchronous operations are submitted at a priority equal to the calling process’ scheduling priority minus aiocbp->aio_reqprio. 

For regular files, no data transfer will occur past the offset maximum established in the open file description associated with aiocbp->fildes. 

aiocb->aio_sigevent defines both the signal to be generated and how the calling process will be notified upon I/O completion.  If aio_sigevent.sigev_notify is SIGEV_NONE, then no signal will be posted upon I/O completion, but the error status and the return status for the operation will be set appropriately.  If aio_sigevent.sigev_notify is SIGEV_SIGNAL, then the signal specified in aio_sigevent.sigev_signo will be sent to the process.  If the SA_SIGINFO flag is set for that signal number, then the signal will be queued to the process and the value specified in aio_sigevent.sigev_value will be the si_value component of the generated signal (see siginfo(5)). 

RETURN VALUES

If the I/O operation is successfully queued, aio_read() and aio_write() return 0; otherwise, they return −1, and set errno to indicate the error condition.  aiocbp may be used as an argument to aio_error(3R) and aio_return(3R) in order to determine the error status and the return status of the asynchronous operation while it is proceeding. 

ERRORS

The aio_read() and aio_write() function will fail if:

EAGAIN The requested asynchronous I/O operation was not queued due to system resource limitations. 

ENOSYS The aio_read() or aio_write() functions are not supported. 

EBADF If the calling function is aio_read(), and aiocbp->fildes is not a valid file descriptor open for reading.  If the calling function is aio_write(), and aiocbp->fildes is not a valid file descriptor open for writing. 

EINVAL • The file offset value implied by aiocbp->aio_offset would be invalid,
• aiocbp->aio_reqprio is not a valid value, or
• aiocbp->aio_nbytes is an invalid value. 

ECANCELED The requested I/O was canceled before the I/O completed due to an explicit aio_cancel(3R) request. 

EINVAL The file offset value implied by aiocbp->aio_offset would be invalid. 

The following are additional conditions which may be detected synchronously or asynchronously:

aio_read()

OVERFLOW The file is a regular file, aiocbp->aio_nbytes is greater than 0 and the starting offset in aiocbp->aio_offset is before the end-of-file and is at or beyond the offset maximum in the open file description associated with aiocbp->fildes. 

aio_write()

EFBIG The file is a regular file, aiocbp->aio_nbytes is greater than 0 and the starting offset in aiocbp->aio_offset is at or beyond the offset maximum in the open file description associated with aiocbp->fildes. 

USAGE

The aio_read() and aio_write() functions have explicit 64-bit equivalents.  See interface64(5). 

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

close(2), exec(2), exit(2), fork(2), lseek(2), read(2), write(2), aio_cancel(3R), aio_return(3R), lio_listio(3R), attributes(5), interface64(5), siginfo(5), standards(5)

NOTES

For portability, the application should set aiocb->aio_reqprio to 0. 

Applications compiled under Solaris 2.3 and 2.4 and using POSIX (see standards(5)) Asynchronous Input and Output option must be recompiled to work correctly when Solaris supports this option. 

BUGS

In Solaris 2.5, these functions always return −1 and set errno to ENOSYS, because this release does not support the Asynchronous Input and Output option.  Beginning with Solaris 2.6, these interfaces are supported. 

SunOS 5.6  —  Last change: 30 Dec 1996