| Standards / Extensions | C or C++ | Dependencies |
|---|---|---|
Single UNIX Specification, Version 2 |
both | OS/390 V2R7 |
#define _XOPEN_SOURCE 500
#include <aio.h>
int aio_write(struct aiocb *aiocbp);The aio_write() function initiates an asynchronous write as described by the aiocb structure (the asynchronous I/O control block).
The operation will write aio_nbytes from the buffer pointed to by aio_buf to the socket or file associated with aio_fildes. The call to aio_write() returns when the request has been initiated or queued to the file or device (even when the data cannot be delivered immediately).
Asynchronous I/O is currently only supported for sockets. The aio_offset field may be set but it will be ignored.
The aiocbp value may be used as an argument to aio_error() and aio_return() functions in order to determine the error status and return status, respectively, of the asynchronous operation. While the operation is proceeding, the error status retrieved by aio_error() is EINPROGRESS; the return status retrieved by aio_return() however is unpredictable.
If an error condition is encountered during the queueing, the function call returns without having initiated or queued the request.
When the operation completes asynchronously the program can be notified by a signal as specified in the aio_sigevent structure. It is significantly more efficient to receive these notifications with sigwaitinfo() or sigtimedwait() than to let them drive a signal handler. At this time the return and error status will have been updated to reflect the outcome of the operation. The sigevent structure's notification function fields are not supported. If a signal is not desired the program can occasionally poll the aiocb with aio_error() until the result is no longer EINPROGRESS.
Be aware that the operation may complete, and the signal handler may be delivered, before control returns from the call to aio_read(). Even when the operation does complete this quickly the return value from the call to aio_read() will be zero, reflecting the queueing of the I/O request not the results of the I/O itself.
An asynchronous operation may be canceled with aio_cancel() before its completion. Canceled operations complete with an error status of ECANCELED and any specified signal will be delivered. Due to timing, the operation may still complete naturally, either successfully or unsuccessfully, before it can be canceled by aio_cancel().
If the file descriptor of this operation is closed, the operation will be deleted if it has not completed or is not just about to complete. Signals specified for deleted operations will not be delivered. Close() will wait for asynchronous operations in progress for the descriptor to be deleted or completed.
You may use aio_suspend() to wait for the completion of asynchronous operations.
Sockets must be in blocking state or the operation may fail with EWOULDBLOCK.
If the control block pointed by aiocbp or the buffer pointed to by aio_buf becomes an illegal address before the asynchronous I/O completion, then the behavior of aio_read() is unpredictable
If the thread that makes the aio_read() request terminates before the I/O completes, the aiocb structure will still be updated with the return and error status, and any specified signal will be delivered to the process in which the thread was running. If thread related storage was used on the request the results are quite unpredictable.
Simultaneous asynchronous operations using the same aiocbp, attempting asynchronous operations using a non-valid aiocbp, or any system action, that changes the process memory space while asynchronous I/O is outstanding to that address range, will produce unpredictable results.
Simultaneous aio_write() operations on the same stream socket should not be done because the data may be transmitted on the network out of order. With UDP sockets each aio_write defines a single datagram and there is no implied order of arrival in UDP. Beware, though, of sending too many datagrams. If there is network congestion or the receiver is slow you can tie up a large amount of system storage with uncontrolled aio_writes, and eventually they may start to fail with ENOBUFS.
There are several sockets oriented extensions to asynchronous I/O available with the BPX1AIO callable service, such as asynchronous accept(), asynchronous accept_and_recv(), asynchronous forms of all five pairs of read and write type operations, and receiving I/O completion notifications via an ECB, exit program, or through a message queue. The <aio.h> header contains all the structure fields, constants, and prototypes necessary to use BPX1AIO from a C program. These extensions are exposed when the _AIO_OS390 feature test macro is defined. The BPX1AIO stub resides in SYS1.CSSLIB and must be bound with your program. For a more detailed description of asynchronous I/O services, see BPX1AIO in z/OS UNIX System Services Programming: Assembler Callable Services Reference.
The aio_lio_opcode field is set to LIO_WRITE by the function aio_write().
_POSIX_PRIORITIZED_IO is not supported. The aio_reqprio field may be set but it will be ignored.
_POSIX_SYNCHRONIZED_IO is not supported.
If the I/O operation is successfully queued, aio_write() returns 0 to the calling process.