source: trunk/packages/xen-3.1/xen-3.1/tools/libaio/man/aio_write.3 @ 34

.TH aio_write 3 2002-09-12 "Linux 2.4" Linux AIO"
.SH NAME
aio_write  \-  Initiate an asynchronous write operation
.SH SYNOPSYS
.nf
.B #include <errno.h>
.sp
.br 
.B #include <aio.h>
.sp
.br
.BI "int aio_write (struct aiocb * aiocbp);"
.fi
.SH DESCRIPTION
This function initiates an asynchronous write operation.  The function
call immediately returns after the operation was enqueued or if before
this happens an error was encountered.

The first 
.IR "aiocbp->aio_nbytes"
bytes from the buffer starting at
.IR "aiocbp->aio_buf"
are written to the file for which
.IR "aiocbp->aio_fildes"
is an descriptor, starting at the absolute
position 
.IR "aiocbp->aio_offset"
in the file.

If prioritized I/O is supported by the platform, the
.IR "aiocbp->aio_reqprio "
value is used to adjust the priority before
the request is actually enqueued.

The calling process is notified about the termination of the read
request according to the 
.IR "aiocbp->aio_sigevent"
value.

When 
.IR "aio_write"
returns, the return value is zero if no error
occurred that can be found before the process is enqueued.  If such an
early error is found the function returns 
.IR -1
and sets
.IR "errno"
to one of the following values.

.TP
.B EAGAIN
The request was not enqueued due to (temporarily) exceeded resource
limitations.
.TP
.B ENOSYS
The 
.IR "aio_write"
function is not implemented.
.TP
.B EBADF
The 
.IR "aiocbp->aio_fildes"
descriptor is not valid.  This condition
may not be recognized before enqueueing the request, and so this error
might also be signaled asynchronously.
.TP
.B EINVAL
The 
.IR "aiocbp->aio_offset"
or
.IR "aiocbp->aio_reqprio"
value is
invalid.  This condition may not be recognized before enqueueing the
request and so this error might also be signaled asynchronously.
.PP

In the case 
.IR "aio_write"
returns zero, the current status of the
request can be queried using 
.IR "aio_error"
and 
.IR "aio_return"
functions.  As long as the value returned by 
.IR "aio_error"
is
.IR "EINPROGRESS"
the operation has not yet completed.  If
.IR "aio_error"
returns zero, the operation successfully terminated,
otherwise the value is to be interpreted as an error code.  If the
function terminated, the result of the operation can be get using a call
to 
.IR "aio_return"
.  The returned value is the same as an equivalent
call to 
.IR "read"
would have returned.  Possible error codes returned
by 
.IR "aio_error"
are:

.TP
.B EBADF
The 
.IR "aiocbp->aio_fildes"
descriptor is not valid.
.TP
.B ECANCELED
The operation was canceled before the operation was finished.
.TP
.B EINVAL
The 
.IR "aiocbp->aio_offset"
value is invalid.
.PP
When the sources are compiled with 
.IR "_FILE_OFFSET_BITS == 64"
, this
function is in fact 
.IR "aio_write64"
since the LFS interface transparently
replaces the normal implementation.
.SH "RETURN VALUES"
When 
.IR "aio_write"
returns, the return value is zero if no error
occurred that can be found before the process is enqueued.  If such an
early error is found the function returns 
.IR -1
and sets
.IR "errno"
to one of the following values.
.SH ERRORS
.TP
.B EAGAIN
The request was not enqueued due to (temporarily) exceeded resource
limitations.
.TP
.B ENOSYS
The 
.IR "aio_write"
function is not implemented.
.TP
.B EBADF
The 
.IR "aiocbp->aio_fildes"
descriptor is not valid.  This condition
may not be recognized before enqueueing the request, and so this error
might also be signaled asynchronously.
.TP
.B EINVAL
The 
.IR "aiocbp->aio_offset"
or
.IR "aiocbp->aio_reqprio"
value is
invalid.  This condition may not be recognized before enqueueing the
request and so this error might also be signaled asynchronously.
.SH "SEE ALSO"
.BR aio(3),
.BR aio_cancel(3),
.BR aio_cancel64(3),
.BR aio_error(3),
.BR aio_error64(3),
.BR aio_fsync(3),
.BR aio_fsync64(3),
.BR aio_init(3),
.BR aio_read(3),
.BR aio_read64(3),
.BR aio_return(3),
.BR aio_return64(3),
.BR aio_suspend(3),
.BR aio_suspend64(3),
.BR aio_write64(3),
.BR errno(3),