aio_write(2)

DESCRIPTION

The aio_write() function allows the calling process to perform an asynchronous write to a previously opened file. The function call returns when the write operation has been enqueued for processing. At this point, processing of the write operation may proceed concurrently with execution of the calling process or thread.

If an error condition is detected that prevents the write request from being enqueued, aio_write() returns -1 and sets errno to indicate the cause of the failure. Once the write 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 write(). The request remains enqueued and consumes process and system resources until aio_return() is called.

The aio_write() function allows the calling process to write aiocbp->aio_nbytes to the file associated with aiocbp->aio_fildes from the buffer pointed to by aiocbp->aio_buf. The priority of the write 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.

When the O_APPEND flag is not set for the file, the write 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. When the O_APPEND flag is set for the file, aiocbp->aio_offset is ignored, and asynchronous write operations append to the file in the same order as the requests were enqueued. 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 write 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 write operation completes.

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

RETURN VALUE

aio_write() returns the following values:

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

ERRORS

If aio_write() detects one of the following error conditions, errno is set to the indicated value:

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

EXAMPLES

The following code sequence and call to aio_write() starts an asynchronous write operation.

SEE ALSO

aio_cancel(2), aio_error(2), aio_fsync(2), aio_read(2), aio_return(2), aio_suspend(2), lio_listio(2), write(2), aio(5).

STANDARDS CONFORMANCE

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