LDP: Update original to LDP v3.68

[linuxjm/LDP_man-pages.git] / original / man3 / aio_write.3

diff --git a/original/man3/aio_write.3 b/original/man3/aio_write.3
index 7608861..caf6ebf 100644 (file)
--- a/original/man3/aio_write.3
+++ b/original/man3/aio_write.3
@@ -1,5 +1,6 @@
 .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl)
 .\"
 .\" 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
 .\" 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


@@ -16,11 +17,11 @@
 .\" GNU General Public License for more details.
 .\"
 .\" You should have received a copy of the GNU General Public
 .\" 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 NAME
 aio_write \- asynchronous write
 .SH SYNOPSIS


@@ -32,31 +33,52 @@ Link with \fI\-lrt\fP.
 .SH DESCRIPTION
 The
 .BR aio_write ()
 .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 ,
 .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
 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).
 .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
 .LP
 If
 .B _POSIX_PRIORITIZED_IO


@@ -70,18 +92,18 @@ The field
 is ignored.
 .LP
 No data is written to a regular file beyond its maximum offset.
 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 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.
 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)
 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 ).
 .IR errno ,
 such as
 .BR EBADF ).


@@ -106,22 +128,41 @@ One or more of
 are invalid.
 .TP
 .B ENOSYS
 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.
 .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
 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.
 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_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/.