aio_write.2 (2010 09)

a
aio_write(2) aio_write(2)
NAME
aio_write() - start asynchronous write operation
SYNOPSIS
#include <aio.h>
int aio_write(struct aiocb *aiocbp);
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 pro-
cess 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 suc-
cessfully 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 asso-
ciated 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
,asiflseek() 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:
0 Successful completion, the operation has been enqueued.
-1 Failure. The requested operation was not enqueued. errno is set to indicate the error.
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 immedi-
ately detected, or if system resource limits prevent the request from being enqueued. All other error con-
ditions 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:
[EAGAIN] The request could not be queued either because of a resource shortage or because
the per-process or system-wide limit on asynchronous I/O operations or asynchro-
nous threads would have been exceeded.
[EEXIST] The aiocbp is already in use for another asynchronous I/O operation.
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.
HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1