MFC 304476: 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).

4 files changed, 15 insertions, 26 deletions

diff --git a/lib/libc/sys/aio_fsync.2 b/lib/libc/sys/aio_fsync.2
index 7eb1a3b..b271dbf 100644
--- a/lib/libc/sys/aio_fsync.2
+++ b/lib/libc/sys/aio_fsync.2
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd July 15, 2016
+.Dd August 19, 2016
 .Dt AIO_FSYNC 2
 .Os
 .Sh NAME
@@ -74,16 +74,14 @@ the call returns without having enqueued the request.
 .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
diff --git a/lib/libc/sys/aio_mlock.2 b/lib/libc/sys/aio_mlock.2
index 03e2df7..76f67ef 100644
--- a/lib/libc/sys/aio_mlock.2
+++ b/lib/libc/sys/aio_mlock.2
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd July 15, 2016
+.Dd August 19, 2016
 .Dt AIO_MLOCK 2
 .Os
 .Sh NAME
@@ -67,7 +67,7 @@ then the call returns without having enqueued the request.
 .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
diff --git a/lib/libc/sys/aio_read.2 b/lib/libc/sys/aio_read.2
index 69960d5..96d84cc 100644
--- a/lib/libc/sys/aio_read.2
+++ b/lib/libc/sys/aio_read.2
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd July 15, 2016
+.Dd August 19, 2016
 .Dt AIO_READ 2
 .Os
 .Sh NAME
@@ -82,7 +82,7 @@ not be referenced after the request is 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
@@ -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
diff --git a/lib/libc/sys/aio_write.2 b/lib/libc/sys/aio_write.2
index 076ce50..2148913 100644
--- a/lib/libc/sys/aio_write.2
+++ b/lib/libc/sys/aio_write.2
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd July 15, 2016
+.Dd August 19, 2016
 .Dt AIO_WRITE 2
 .Os
 .Sh NAME
@@ -88,7 +88,7 @@ be referenced after the request is 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
@@ -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