aio_write(), aio_write64()

Asynchronously write to a file

#include <aio.h>

int aio_write( struct aiocb * aiocbptr );
int aio_write64( struct aiocb64 * aiocbptr );

Arguments:

aiocbptr

A pointer to an asynchronous I/O control block of type aiocb or aiocb64 that defines how much data to write, and where to write it.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The aio_write() and aio_write64() functions asynchronously write aiocbptr->aio_nbytes to the file associated with aiocbptr->aio_fildes from the buffer that aiocbptr->aio_buf points to. The functions return when the write request has been initiated or, at a minimum, queued to the file or device.

The asynchronous operation is submitted at the scheduling priority of the thread minus aiocbptr->aio_reqprio.

You can use the aiocbptr argument as an argument to aio_error() and aio_return() to determine the error status and return status of the asynchronous operation while it's in progress.

If O_APPEND isn't set for the file descriptor aio_fildes, then the requested operation takes place at the absolute position in the file as given by aio_offset, as if lseek() were called immediately before the operation with an offset of aio_offset and a whence of SEEK_SET.

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 synchronized I/O is enabled on the file associated with aiocbptr->aio_fildes, these functions behave in accordance with the definitions of synchronized I/O data integrity completion and synchronized I/O file integrity completion.

The following conditions may be detected synchronously at the time of the call to aio_write() or aio_write64(), or asynchronously. If any of these conditions are detected synchronously, these functions return -1 and set errno to the corresponding value. If any of these conditions are detected asynchronously, the return status of the asynchronous operation is set to -1, and the error status of the asynchronous operation is set to the corresponding value:

EBADF

The aiocbptr->aio_fildes argument isn't a valid file descriptor that's open for writing.

EINVAL

The file offset value implied by aiocbptr->aio_offset would be invalid, aiocbptr->aio_reqprio isn't a valid value, or aiocbptr->aio_nbytes is invalid.

If aio_write() or aio_write64() successfully queues the I/O operation, but the operation is subsequently canceled or encounters an error, the return status of the asynchronous operation is one of the values normally returned by write() . In addition, the error status of the asynchronous operation is set to one of the error statuses normally set by write(), or one of the following:

EBADF

The aiocbptr->aio_fildes isn't a valid file descriptor that's open for writing.

ECANCELED

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

EINVAL

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

The following condition may be detected synchronously or asynchronously:

EOVERFLOW

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

Returns:

0 if the I/O operation was successfully queued, or -1 if an error occurred (errno is set).

Errors:

EAGAIN

The requested asynchronous I/O operation wasn't queued because of system resource limitations.

Classification:

aio_write() is POSIX 1003.1 AIO; aio_write64() is Large-file support

Caveats:

The first time you call an aio_* function, a thread pool is created, making your process multithreaded if it isn't already. The thread pool isn't destroyed until your process ends.