NAME

aio_write − Queue an asynchronous write request to the specified file descriptor (P1003.1b)

SYNOPSIS

#include <aio.h>

int aio_write (
struct aiocb ∗aiocbp);

PARAMETERS

∗aiocbp A pointer to an aiocb structure. 

DESCRIPTION

The aio_write function issues a write request and returns, even when the data cannot be written immediately. If the request cannot be initiated, the function returns with an error status. If an error condition occurs during queuing, the function call returns without initiating the queue request. 

The aiocbp argument points to an asynchronous control block structure, aiocb, used in the asynchronous I/O interfaces.  The aiocbp structure contains asynchronous operation information, such as  the number of bytes for the write operation as well as the buffer containing the data to be written to the file descriptor specified in the aio_fildes member of the aiocbp structure. 

The aiocb structure has the following members:

int aio_fildes;

off_t aio_offset;

volatile char ∗aio_buf;

size_t aio_nbytes;

int aio_reqprio;

struct sigevent aio_sigevent;

int aio_lio_opcode

The aio_fildes member is the file descriptor on which the asynchronous operation is to be performed. If O_APPEND is set for the file descriptor, write operations append to the file in the same order as the calls were made.  If O_APPEND is not set, then the requested operation takes place at the position in the file as given by aio_offset (as if the lseek function were called prior to the operation with an offset equal to aio_offset and a whence set to SEEK_SET.)  After any asynchronous I/O operation aio_offset member is undefined and must be set explicitly for every asynchronous I/O request. 

The aio_nbytes and aio_buf members are the same as the nbyte and buf arguments defined by POSIX.1 read, write and fsync functions. 

Prioritized asynchronous I/O is not supported. For portability reasons, the aio_reqprio member should be specified as AIO_PRIO_DFL, the default priority, as defined in the <limits.h> header file. 

The aio_sigevent member defines the signal generated once the I/O operation is complete. If aio_sigevent.sigev_signo is zero, no signal is posted on completion. 

The aio_lio_opcode member is ignored by aio_write(). 

Pending I/O operations are handled as follows:

•On close, outstanding I/O operations can be canceled. 

•On _exit and exec, outstanding asynchronous I/O operations can be canceled. 

•On fork, no asynchronous I/O is inherited. 

RETURN VALUES

On a successful call, a value of 0 is returned and the I/O operation is successfully queued. 

On an unsuccessful call, a value of −1 is returned and errno is set to indicate that an error occurred. 

ERRORS

The aio_write function fails under the following conditions:

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

[EBADF] The aiocbp−>aio_fildes argument 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. 

RELATED INFORMATION

Functions: close(2), exec(2), _exit(2), fork(2), lseek(2), read(2), write(2), aio_cancel(3), aio_error(3), aio_read(3), aio_return(3), lio_listio(3)