The aio_write subroutine includes information for the POSIX AIO aio_write subroutine (as defined in the IEEE std 1003.1-2001), and the Legacy AIO aio_write subroutine.
POSIX AIO aio_write Subroutine
Asynchronously writes to a file.
Standard C Library (libc.a)
#include <aio.h> int aio_write (aiocbp) struct aiocb *aiocbp;
The aio_write subroutine writes aio_nbytes to the file associated with aio_fildes from the buffer pointed to by aio_buf. The subroutine returns when the write request has been initiated or queued to the file or device.
The aiocbp parameter may be used as an argument to the aio_error and aio_return subroutines in order to determine the error status and return status, respectively, of the asynchronous operation while it is proceeding.
The aiocbp parameter points to an aiocb structure. If the buffer pointed to by aio_buf or the control block pointed to by aiocbp becomes an illegal address prior to asynchronous I/O completion, the behavior is undefined.
If O_APPEND is not set for the aio_fildes file descriptor, the requested operation takes place at the absolute position in the file as given by aio_offset. This is done as if the lseek subroutine were called immediately prior to the operation with an offset equal to aio_offset and a whence equal to 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. After a successful call to enqueue an asynchronous I/O operation, the value of the file offset for the file is unspecified.
The aio_lio_opcode field is ignored by the aio_write subroutine.
Since prioritized I/O is not supported at this time the aio_reqprio field of the aiocb structure is not presently used.
Simultaneous asynchronous operations using the same aiocbp produce undefined results.
If synchronized I/O is enabled on the file associated with aio_fildes, the behavior of this subroutine is according to the definitions of synchronized I/O data integrity completion, and synchronized I/O file integrity completion.
For any system action that changes the process memory space while an asynchronous I/O is outstanding, the result of that action is undefined.
For regular files, no data transfer occurs past the offset maximum established in the open file description associated with aio_fildes.
| aiocbp | Points to the aiocb structure associated with the I/O operation. |
The aiocb structure is defined in the /usr/include/aio.h file and contains the following members:
int aio_fildes off_t aio_offset char *aio_buf size_t aio_nbytes int aio_reqprio struct sigevent aio_sigevent int aio_lio_opcode
The aio_write and aio_write64 subroutines can be called from the process environment only.
The aio_write subroutine returns a 0 to the calling process if the I/O operation is successfully queued. Otherwise, a -1 is returned and the errno global variable is set to indicate the error.
| EAGAIN | The requested asynchronous I/O operation was not queued due to system resource limitations. |
Each of the following conditions may be detected synchronously at the time of the call to aio_write, or asynchronously. If any of the conditions below are detected synchronously, the aio_write subroutine returns a -1 and sets the errno global variable to the corresponding value. If any of the conditions below 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 aio_fildes parameter is not a valid file descriptor open for writing. |
| EINVAL | The file offset value implied by aio_offset is invalid, aio_reqprio is not a valid value, or aio_nbytes is an invalid value. |
If the aio_write subroutine successfully queues the I/O operation, the return status of the asynchronous operation is one of the values normally returned by the write subroutine call. If the operation is successfully queued but is subsequently canceled or encounters an error, the error status for the asynchronous operation contains one of the values normally set by the write subroutine call, or one of the following:
| EBADF | The aio_fildes parameter is not a valid file descriptor open for writing. |
| EINVAL | The file offset value implied by aio_offset would be invalid. |
| ECANCELED | The requested I/O was canceled before the I/O completed due to an aio_cancel request. |
The following condition may be detected synchronously or asynchronously:
| EFBIG | The file is a regular file, aio_nbytes is greater than 0, and the starting offset in aio_offset is at or beyond the offset maximum in the open file description associated with aio_fildes. |
aio_cancel or aio_cancel64 Subroutine, aio_error or aio_error64 Subroutine, lio_listio or lio_listio64 Subroutine, aio_read or aio_read64 Subroutine, aio_suspend or aio_suspend64 Subroutine, aio_return or aio_return64 Subroutine, close Subroutine, exec: execl, execle, execlp, execv, execve, execvp, or exect Subroutine, exit, atexit, _exit, or _Exit Subroutine, fork, f_fork, or vfork Subroutine, and lseek, llseek or lseek64 Subroutine.
The read, readx, readv, readvx, or pread Subroutine in AIX 5L Version 5.2 Technical Reference: Base Operating System and Extensions Volume 2.
Legacy AIO aio_write Subroutine
Writes to a file asynchronously.
Standard C Library (libc.a)
#include <aio.h>
int aio_write( FileDescriptor, aiocbp)
int FileDescriptor;
struct aiocb *aiocbp;
int aio_write64( FileDescriptor, aiocbp)
int FileDescriptor;
struct aiocb64 *aiocbp;
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 (lseek, llseek or lseek64 Subroutine) 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 (aio_error or aio_error64 Subroutine) 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.
#define _AIO_AIX_SOURCE #include <sys/aio.h>or, on the command line when compiling enter:
->xlc ... -D_AIO_AIX_SOURCE ... legacy_aio_program.c
| 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 /usr/include/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 aiohandle_t aio_handle
The aio_write and aio_write64 subroutines can be called from the process environment only.
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:
The aio_cancel or aio_cancel64 (aio_cancel or aio_cancel64 Subroutine) subroutine, aio_error or aio_error64 (aio_error or aio_error64 Subroutine) subroutine, aio_read or aio_read64 (aio_read or aio_read64 Subroutine) subroutine, aio_return or aio_return64 (aio_return or aio_return64 Subroutine) subroutine, aio_suspend or aio_suspend64 (aio_suspend or aio_suspend64 Subroutine) subroutine, lio_listio or lio_listio64 (lio_listio or lio_listio64 Subroutine) subroutine.
The Asynchronous I/O Overview and the Communications I/O Subsystem: Programming Introduction in AIX 5L Version 5.2 Kernel Extensions and Device Support Programming Concepts.
The Input and Output Handling Programmer's Overview in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs describes the files, commands, and subroutines used for low-level, stream, terminal, and asynchronous I/O interfaces.