.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl)
.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
-.\" License along with this manual; if not, write to the Free
-.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
-.\" USA.
+.\" License along with this manual; if not, see
+.\" <http://www.gnu.org/licenses/>.
+.\" %%%LICENSE_END
.\"
-.TH AIO_WRITE 3 2003-11-14 "" "Linux Programmer's Manual"
+.TH AIO_WRITE 3 2012-05-08 "" "Linux Programmer's Manual"
.SH NAME
aio_write \- asynchronous write
.SH SYNOPSIS
.SH DESCRIPTION
The
.BR aio_write ()
-function requests an asynchronous "n = write(fd, buf, count)"
-with fd, buf, count given by
-.IR aiocbp\->aio_fildes ,
-.IR aiocbp\->aio_buf ,
-.IR aiocbp\->aio_nbytes ,
-respectively.
-The return status n can be retrieved upon completion using
-.BR aio_return (3).
+function queues the I/O request described by the buffer pointed to by
+.IR aiocbp .
+This function is the asynchronous analog of
+.BR write (2).
+The arguments of the call
+
+ write(fd, buf, count)
+
+correspond (in order) to the fields
+.IR aio_fildes ,
+.IR aio_buf ,
+and
+.IR aio_nbytes
+of the structure pointed to by
+.IR aiocbp .
+(See
+.BR aio (7)
+for a description of the
+.I aiocb
+structure.)
.LP
If
.B O_APPEND
is not set, the data is written starting at the
absolute file offset
.IR aiocbp\->aio_offset ,
-regardless of the current file position.
+regardless of the current file offset.
If
.B O_APPEND
-is set, the data is written at the end of the file.
-After this request, the value of the current file position is unspecified.
+is set, data is written at the end of the file in the same order as
+.BR aio_write ()
+calls are made.
+After the call, the value of the current file offset is unspecified.
.LP
The "asynchronous" means that this call returns as soon as the
request has been enqueued; the write may or may not have completed
when the call returns.
One tests for completion using
.BR aio_error (3).
+The return status of a completed I/O operation can be obtained
+.BR aio_return (3).
+Asynchronous notification of I/O completion can be obtained by setting
+.IR aiocbp\->aio_sigevent
+appropriately; see
+.BR sigevent (7)
+for details.
.LP
If
.B _POSIX_PRIORITIZED_IO
is ignored.
.LP
No data is written to a regular file beyond its maximum offset.
-.SH "RETURN VALUE"
+.SH RETURN VALUE
On success, 0 is returned.
-On error the request is not enqueued, \-1
+On error, the request is not enqueued, \-1
is returned, and
.I errno
is set appropriately.
-If an error is first detected later, it will
+If an error is detected only later, it will
be reported via
.BR aio_return (3)
(returns status \-1) and
.BR aio_error (3)
-(error status whatever one would have gotten in
+(error status\(emwhatever one would have gotten in
.IR errno ,
such as
.BR EBADF ).
are invalid.
.TP
.B ENOSYS
-This function is not supported.
-.SH "CONFORMING TO"
-POSIX.1-2001.
+.BR aio_write ()
+is not implemented.
+.SH VERSIONS
+The
+.BR aio_write ()
+function is available since glibc 2.1.
+.SH CONFORMING TO
+POSIX.1-2001, POSIX.1-2008.
.SH NOTES
It is a good idea to zero out the control block before use.
-This control block must not be changed while the write operation
+The control block must not be changed while the write operation
is in progress.
The buffer area being written out
.\" or the control block of the operation
-must not be accessed during the operation or undefined results may
-occur.
+must not be accessed during the operation or undefined results may occur.
The memory areas involved must remain valid.
-.SH "SEE ALSO"
+
+Simultaneous I/O operations specifying the same
+.I aiocb
+structure produce undefined results.
+.SH SEE ALSO
.BR aio_cancel (3),
.BR aio_error (3),
.BR aio_fsync (3),
.BR aio_read (3),
.BR aio_return (3),
-.BR aio_suspend (3)
+.BR aio_suspend (3),
+.BR lio_listio (3),
+.BR aio (7)
+.SH COLOPHON
+This page is part of release 3.68 of the Linux
+.I man-pages
+project.
+A description of the project,
+information about reporting bugs,
+and the latest version of this page,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.