d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Fix various nits in the aio operation manpages.

Browse Source 
- 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
This commit is contained in:
John Baldwin 2016-08-19 17:37:32 +00:00
parent c8442223b6
commit 4092a25cd0
Notes: svn2git 2020-12-20 02:59:44 +00:00 
svn path=/head/; revision=304476
4 changed files with 15 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
lib/libc/sys/aio_fsync.2
View File

@ -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

10
lib/libc/sys/aio_mlock.2
View File

@ -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

9
lib/libc/sys/aio_read.2
View File

@ -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

9
lib/libc/sys/aio_write.2
View File

@ -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