162 lines
5.9 KiB
Groff
162 lines
5.9 KiB
Groff
'\"macro stdmacro
|
|
.TH AIO_WRITE 3
|
|
.SH NAME
|
|
aio_write, aio_write64 \- asynchronous I/O write
|
|
.Op c p a
|
|
.SH C SYNOPSIS
|
|
.nf
|
|
.B #include <aio.h>
|
|
.PP
|
|
.B "int aio_write(aiocb_t *aiocbp);
|
|
.PP
|
|
.B "int aio_write64(aiocb64_t *aiocbp);
|
|
.fi
|
|
.PP
|
|
.Op
|
|
.SH DESCRIPTION
|
|
.PP
|
|
The \f4aio_write()\f1
|
|
function allows the calling process to write \f3aiocbp->aio_nbytes\f1
|
|
from the file associated with \f3aiocbp->aio_fildes\f1
|
|
into the buffer pointed to by \f3aiocbp->aio_buf\f1 (see \f3write(2)\f1).
|
|
The function call returns when the write request has been initiated or,
|
|
at a minimum, queued for the file or device.
|
|
.P
|
|
The \f3aiocb->aio_sigevent\f1 defines how the calling process will be
|
|
notified upon I/O completion.
|
|
.P
|
|
If \f3sigev_notify\f1
|
|
is \f3SIGEV_NONE\f1, then no notification will be posted to the calling
|
|
application.
|
|
.P
|
|
If \f3sigev_notify\f1 is
|
|
\f3SIGEV_SIGNAL\f1, then the signal specified in
|
|
\f3sigev_signo\f1 will be sent to the calling
|
|
process. If \f3SA_SIGINFO\f1 is set for the signal (see
|
|
\f3sigaction(2)\f1) and the signal is in the range of \f3SIGRTMIN\f1
|
|
and \f3SIGRTMAX\f1 then the signal will be queued to the process and
|
|
the value in \f3sigev_value\f1 will be the \f3si_value\f1
|
|
in the generated signal.
|
|
.P
|
|
If \f3sigev_notify\f1 is \f3SIGEV_CALLBACK\f1 then
|
|
the function \f3sigev_func\f1 will be called
|
|
with \f3sigev_value\f1 as the argument. Only one callback
|
|
will be called at a time, however programs should be careful to note
|
|
that a callback may be run in parallel with the calling process.
|
|
.P
|
|
If \f3sigev_notify\f1 is \f3SIGEV_THREAD\f1 then
|
|
the function \f3sigev_notify_function\f1 will be called
|
|
by a new thread (see \f3pthreads(5)\f1)
|
|
with \f3sigev_value\f1 as the argument.
|
|
This thread is created when the event arrives with the attributes
|
|
specified in \f3sigev_notify_attributes\f1 except that
|
|
it is automatically detached.
|
|
The calling process should ensure there are sufficient resources to
|
|
create the thread.
|
|
.P
|
|
All \f3aio_write()\f1 calls must supply a complete
|
|
\f3aiocb->aio_sigevent\f1 structure.
|
|
.P
|
|
The \f3aiocbp->aio_lio_opcode\f1 field is ignored by \f3aio_write()\f1.
|
|
.P
|
|
Prioritized I/O is not currently supported among asynchronous file
|
|
operations. \f3aiocbp->aio_reqprio\f1
|
|
must be set to 0, otherwise the call will fail.
|
|
.P
|
|
The I/O requests submitted in an unspecified
|
|
order unless the file was opened with the \f3O_APPEND\f1 in which case
|
|
the write operations will happen in the order that they were submitted.
|
|
.P
|
|
After a call to \f3aio_write\f1 the \f3aiocbp\f1
|
|
may be used as an argument to \f3aio_error()\f1
|
|
and \f3aio_return()\f1
|
|
in order to determine the error status and return status,
|
|
respectively, of the asynchronous operation while it is proceeding. If
|
|
an error condition is encountered during queueing, the function call
|
|
returns without having initiated or queued the request. After a
|
|
successful call to enqueue an asynchronous I/O operation, the value of
|
|
the file offset for the file is undefined.
|
|
.sp
|
|
If the buffer pointed to by \f3aiocbp->aio_buf\f1
|
|
or the control block pointed to by \f3aiocbp\f1 changes or
|
|
becomes an illegal address prior to asynchronous
|
|
I/O completion then the behavior is undefined.
|
|
Simultaneous asynchronous operations using the same \f3aiocbp\f1
|
|
produce undefined results.
|
|
.sp
|
|
For any system action that changes the process memory space while an
|
|
asynchronous I/O is outstanding to the address range being changed,
|
|
the result of that asynchronous I/O is undefined.
|
|
.P
|
|
The \f3aio_write64\f1() function is identical to \f3aio_write()\f1 except
|
|
that it takes an \f3aiocb64_t\f1 * (see <\f3aio.h\f1>).
|
|
This structure allows for the specification of a file offset greater than
|
|
2 Gigabytes.
|
|
.sp
|
|
.SH "SEE ALSO"
|
|
aio_read(3), lio_listio(3), aio_error(3), aio_return(3), aio_hold(3),
|
|
aio_cancel(3), aio_sgi_init(3), aio_fsync(3), write(2), lseek(2), close(2),
|
|
_exit(2), exec(2), fork(2), pthreads(5), sysconf(3C).
|
|
.SH "DIAGNOSTICS"
|
|
.PP
|
|
The \f3aio_write()\f1
|
|
returns the value 0 to the calling process if the I/O operation is successfully queued; otherwise, the function shall return the value -1 and shall set
|
|
.I errno
|
|
to indicate the error.
|
|
.TP 15
|
|
.SM
|
|
\%[EAGAIN]
|
|
The requested asynchronous I/O operation was not queued due to system
|
|
resource limitations. Often this is due to exceeding the maximum
|
|
number of asynchronous I/O operations for the system. The maximum can be
|
|
checked with a call to
|
|
.I
|
|
sysconf()
|
|
with an argument of \f3_SC_AIO_MAX.\f1
|
|
.P
|
|
Each of the following conditions may be detected synchronously at the
|
|
time of the call to \f3aio_write()\f1
|
|
, or asynchronously. If any of the conditions below are detected
|
|
synchronously at the time of the call,
|
|
the \f3aio_write()\f1 function shall return -1 and set
|
|
.I errno
|
|
to the corresponding value. If any of the conditions below are
|
|
detected asynchronously, the return status of the asynchronous
|
|
operation shall be set to -1 and the error status of the asynchronous
|
|
operation shall be set to the corresponding value.
|
|
.TP 15
|
|
.SM
|
|
\%[EBADF]
|
|
The \f3aiocbp->aio_fildes\f1
|
|
argument is not a valid file descriptor open for writing.
|
|
.TP 15
|
|
.SM
|
|
\%[EINVAL]
|
|
The file offset value implied by \f3aiocbp->aio_offset\f1
|
|
would be invalid, \f3aiocbp->aio_reqprio\f1 is not a valid value, or
|
|
\f3aiocbp->aio_nbytes\f1 is an invalid value.
|
|
.P
|
|
In the case that the \f3aio_write()\f1
|
|
successfully queues the I/O operation, the return status of the asynchronous operation shall be one of the values normally returned by the
|
|
.I write(2)
|
|
function call. If the operation is successfully queued, but is subsequently
|
|
canceled or encounters an error, the error status for the asynchronous operation shall contain one of the values normally set by the
|
|
.I write(2)
|
|
function call, or one of the following:
|
|
.TP 15
|
|
.SM
|
|
\%[EBADF]
|
|
The \f3aiocbp->aio_fildes\f1
|
|
argument is not a valid file descriptor open for writing.
|
|
.TP 15
|
|
.SM
|
|
\%[EINVAL]
|
|
The file offset value implied by \f3aiocbp->aio_offset\f1
|
|
would be invalid.
|
|
.TP 15
|
|
.SM
|
|
\%[ECANCELED]
|
|
The requested I/O was canceled before the I/O completed due to an explicit
|
|
\f3aio_cancel(3)\f1
|
|
request.
|