aio_write or aio_write64 Subroutine

Base Operating System and Extensions Technical Reference, Volume 1

aio_write or aio_write64 Subroutine

Purpose

Writes to a file asynchronously.

Library

Standard C Library (libc.a)

Syntax

#include <aio.h>

int aio_write(FileDescriptor, aiocbp)
int FileDescriptor;
struct aiocb *aiocbp;

int aio_write64(FileDescriptor, aiocbp)
int FileDescriptor;
struct aiocb64 *aiocbp;

Description

The aio_write subroutine writes asynchronously to a file. Specifically, the aio_write subroutine writes to the file associated with the FileDescriptor parameter from a buffer. To handle this, the subroutine uses information from the aio control block (aiocb) structure, which is pointed to by the aiocbp parameter. This information includes the following fields:

`aio_buf`	Indicates the buffer to use.
`aio_nbytes`	Indicates the number of bytes to write.

The aio_write64 subroutine is similar to the aio_write subroutine except that it takes an aiocb64 reference parameter. This allows the aio_write64 subroutine to specify offsets in excess of OFF_MAX (2 gigbytes minus 1).

In the large file enabled programming environment, aio_read is redefined to be aio_read64.

When the write request has been queued, the aio_write subroutine updates the file pointer specified by the aio_whence and aio_offset fields in the aiocb structure as if the requested I/O completed. It then returns to the calling program. The aio_whence and aio_offset fields have the same meaning as the whence and offset parameters in the lseek subroutine. The subroutine ignores them for file objects that are not capable of seeking.

If an error occurs during the call, the write request is not initiated or queued. To determine the status of a request, use the aio_error subroutine.

To have the calling process receive the SIGIO signal when the I/O operation completes, set the AIO_SIGNAL bit in the aio_flag field in the aiocb structure.

Note: The SIGIO signal will be replaced by real-time signals when they are available. The event structure in the aiocb structure is currently not in use but is included for future compatibility.

Parameters

FileDescriptor

Identifies the object to be written as returned from a call to open.

aiocbp

Points to the asynchronous I/O control block structure associated with the I/O operation.

The aiocb structure is defined in the aio.h file and contains the following members:

int               aio_whence
off_t             aio_offset
char              *aio_buf
size_t            aio_nbytes
int               aio_reqprio
struct event      aio_event
struct osigevent  aio_event
int               aio_flag
aio_handle_t      aio_handle

The aio_write and aio_write64 subroutines can be called from the process environment only.

Return Values

When the write request queues successfully, the aio_write subroutine returns a value of 0. Otherwise, it returns a value of -1 and sets the errno global variable to identify the error.

Return codes can be set to the following errno values:

EAGAIN	Indicates that the system resources required to queue the request are not available. Specifically, the transmit queue may be full, or the maximum number of opens may have been reached.
EBADF	Indicates that the FileDescriptor parameter is not valid.
EFAULT	Indicates that the address specified by the aiocbp parameter is not valid.
EINVAL	Indicates that the `aio_whence` field does not have a valid value or that the resulting pointer is not valid.

Note: Other error codes defined in the /usr/include/sys/errno.h file may be returned by the aio_error subroutine if an error during the I/O operation is encountered.

Implementation Specifics

The aio_write or aio_write64 subroutines are part of Base Operating System (BOS) Runtime.

Related Information

The aio_cancel or aio_cancel64 subroutine, aio_error or aio_error64 subroutine, aio_read or aio_read64 subroutine, aio_return or aio_return64 subroutine, aio_suspend or aio_suspend64 subroutine, lio_listio or lio_listio64 subroutine.

The Asynchronous I/O Overview and the Communications I/O Subsystem: Programming Introduction in AIX Version 4.3 Kernel Extensions and Device Support Programming Concepts.

The Input and Output Handling Programmer's Overview in AIX General Programming Concepts: Writing and Debugging Programs describes the files, commands, and subroutines used for low-level, stream, terminal, and asynchronous I/O interfaces.