svn commit: r304476 - head/lib/libc/sys

Fri Aug 19 17:37:34 UTC 2016

Author: jhb
Date: Fri Aug 19 17:37:32 2016
New Revision: 304476
URL: https://svnweb.freebsd.org/changeset/base/304476

Log:
  Fix various nits in the aio operation manpages.
  
  - Avoid double use of "request" in a single sentence.  Instead, describe
    aio_sigevent as being used to request notification of the associated
    operation's completion.  This matches the language used to describe
    aio_sigevent in aio(4).
  - Simplify the prohibition on modifying buffers while requests are in
    flight.
  - Fix case mismatch.
  - Drop note about not using stack variables. C programmers should be able
    to figure out if a stack variable is safe based on the later warning
    about the life cycle requirements of control blocks.
  - Remove prohibition on modifying the I/O buffer for aio_fsync() since
    it does not use an I/O buffer.  For aio_mlock(), prohibit modifications
    to the mapping (e.g. due to mprotect, munmap, mmap, etc.) but do not
    prohibit modifications to the memory backing the buffer (stores into
    the pages backing the buffer).
  
  Requested by:	wblock (1,2), kib (4)
  Reviewed by:	kib, rpokala, wblock
  MFC after:	3 days
  Sponsored by:	Chelsio Communications
  Differential Revision:	https://reviews.freebsd.org/D7462

Modified:
  head/lib/libc/sys/aio_fsync.2
  head/lib/libc/sys/aio_mlock.2
  head/lib/libc/sys/aio_read.2
  head/lib/libc/sys/aio_write.2

Modified: head/lib/libc/sys/aio_fsync.2
==============================================================================

--- head/lib/libc/sys/aio_fsync.2	Fri Aug 19 17:03:14 2016	(r304475)
+++ head/lib/libc/sys/aio_fsync.2	Fri Aug 19 17:37:32 2016	(r304476)
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd July 21, 2016
+.Dd August 19, 2016
 .Dt AIO_FSYNC 2
 .Os
 .Sh NAME
@@ -74,16 +74,14 @@ the call returns without having enqueued
 .Pp
 The
 .Fa iocb->aio_sigevent
-structure can be used to request notification of the request's
+structure can be used to request notification of the operation's
 completion as described in
 .Xr aio 4 .
 .Sh RESTRICTIONS
-The asynchronous I/O Control Block structure pointed to by
+The Asynchronous I/O Control Block structure pointed to by
 .Fa iocb
 must remain valid until the
 operation has completed.
-For this reason, use of auto (stack) variables
-for these objects is discouraged.
 .Pp
 The asynchronous I/O control buffer
 .Fa iocb
@@ -91,9 +89,8 @@ should be zeroed before the
 .Fn aio_fsync
 call to avoid passing bogus context information to the kernel.
 .Pp
-Modifications of the Asynchronous I/O Control Block structure or the
-buffer contents after the request has been enqueued, but before the
-request has completed, are not allowed.
+Modification of the Asynchronous I/O Control Block structure is not allowed
+while the request is queued.
 .Sh RETURN VALUES
 .Rv -std aio_fsync
 .Sh ERRORS

Modified: head/lib/libc/sys/aio_mlock.2
==============================================================================
--- head/lib/libc/sys/aio_mlock.2	Fri Aug 19 17:03:14 2016	(r304475)
+++ head/lib/libc/sys/aio_mlock.2	Fri Aug 19 17:37:32 2016	(r304476)
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd July 21, 2016
+.Dd August 19, 2016
 .Dt AIO_MLOCK 2
 .Os
 .Sh NAME
@@ -67,7 +67,7 @@ then the call returns without having enq
 .Pp
 The
 .Fa iocb->aio_sigevent
-structure can be used to request notification of the request's
+structure can be used to request notification of the operation's
 completion as described in
 .Xr aio 4 .
 .Sh RESTRICTIONS
@@ -77,8 +77,6 @@ and the buffer that the
 .Fa iocb->aio_buf
 member of that structure references must remain valid until the
 operation has completed.
-For this reason, use of auto (stack) variables
-for these objects is discouraged.
 .Pp
 The asynchronous I/O control buffer
 .Fa iocb
@@ -87,8 +85,8 @@ should be zeroed before the
 call to avoid passing bogus context information to the kernel.
 .Pp
 Modifications of the Asynchronous I/O Control Block structure or the
-buffer contents after the request has been enqueued, but before the
-request has completed, are not allowed.
+memory mapping described by the virtual address range are not allowed
+while the request is queued.
 .Sh RETURN VALUES
 .Rv -std aio_mlock
 .Sh ERRORS

Modified: head/lib/libc/sys/aio_read.2
==============================================================================
--- head/lib/libc/sys/aio_read.2	Fri Aug 19 17:03:14 2016	(r304475)
+++ head/lib/libc/sys/aio_read.2	Fri Aug 19 17:37:32 2016	(r304476)
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd July 21, 2016
+.Dd August 19, 2016
 .Dt AIO_READ 2
 .Os
 .Sh NAME
@@ -82,7 +82,7 @@ not be referenced after the request is e
 .Pp
 The
 .Fa iocb->aio_sigevent
-structure can be used to request notification of the request's
+structure can be used to request notification of the operation's
 completion as described in
 .Xr aio 4 .
 .Sh RESTRICTIONS
@@ -92,8 +92,6 @@ and the buffer that the
 .Fa iocb->aio_buf
 member of that structure references must remain valid until the
 operation has completed.
-For this reason, use of auto (stack) variables
-for these objects is discouraged.
 .Pp
 The asynchronous I/O control buffer
 .Fa iocb
@@ -102,8 +100,7 @@ should be zeroed before the
 call to avoid passing bogus context information to the kernel.
 .Pp
 Modifications of the Asynchronous I/O Control Block structure or the
-buffer contents after the request has been enqueued, but before the
-request has completed, are not allowed.
+buffer contents are not allowed while the request is queued.
 .Pp
 If the file offset in
 .Fa iocb->aio_offset

Modified: head/lib/libc/sys/aio_write.2
==============================================================================
--- head/lib/libc/sys/aio_write.2	Fri Aug 19 17:03:14 2016	(r304475)
+++ head/lib/libc/sys/aio_write.2	Fri Aug 19 17:37:32 2016	(r304476)
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd July 21, 2016
+.Dd August 19, 2016
 .Dt AIO_WRITE 2
 .Os
 .Sh NAME
@@ -88,7 +88,7 @@ be referenced after the request is enque
 .Pp
 The
 .Fa iocb->aio_sigevent
-structure can be used to request notification of the request's
+structure can be used to request notification of the operation's
 completion as described in
 .Xr aio 4 .
 .Sh RESTRICTIONS
@@ -98,8 +98,6 @@ and the buffer that the
 .Fa iocb->aio_buf
 member of that structure references must remain valid until the
 operation has completed.
-For this reason, use of auto (stack) variables
-for these objects is discouraged.
 .Pp
 The asynchronous I/O control buffer
 .Fa iocb
@@ -108,8 +106,7 @@ should be zeroed before the
 system call to avoid passing bogus context information to the kernel.
 .Pp
 Modifications of the Asynchronous I/O Control Block structure or the
-buffer contents after the request has been enqueued, but before the
-request has completed, are not allowed.
+buffer contents are not allowed while the request is queued.
 .Pp
 If the file offset in
 .Fa iocb->aio_offset
