summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorjhb <jhb@FreeBSD.org>2016-08-22 20:23:39 +0000
committerjhb <jhb@FreeBSD.org>2016-08-22 20:23:39 +0000
commit1da1fd050f3e300872cb08c24302bb2bc9ccd4b7 (patch)
tree0e7f6d58024c61c06e96b19f8a716993234c0379
parent09b783544b2e35fb9b52ab18e16cfddb11fc4b8b (diff)
downloadFreeBSD-src-1da1fd050f3e300872cb08c24302bb2bc9ccd4b7.zip
FreeBSD-src-1da1fd050f3e300872cb08c24302bb2bc9ccd4b7.tar.gz
MF11 304617: 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). Approved by: re (kib)
-rw-r--r--lib/libc/sys/aio_fsync.213
-rw-r--r--lib/libc/sys/aio_mlock.210
-rw-r--r--lib/libc/sys/aio_read.29
-rw-r--r--lib/libc/sys/aio_write.29
4 files changed, 15 insertions, 26 deletions
diff --git a/lib/libc/sys/aio_fsync.2 b/lib/libc/sys/aio_fsync.2
index 52b47efb..9d5d143 100644
--- a/lib/libc/sys/aio_fsync.2
+++ b/lib/libc/sys/aio_fsync.2
@@ -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 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 cc588b5..f7f4a27 100644
--- a/lib/libc/sys/aio_mlock.2
+++ b/lib/libc/sys/aio_mlock.2
@@ -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 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 2f16809..bbf96cc 100644
--- a/lib/libc/sys/aio_read.2
+++ b/lib/libc/sys/aio_read.2
@@ -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 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 414f98f..a3268e5 100644
--- a/lib/libc/sys/aio_write.2
+++ b/lib/libc/sys/aio_write.2
@@ -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 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
OpenPOWER on IntegriCloud