Fix various nits in the aio operation manpages.

[jhb]

Summary

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).
• Rearrange 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.

Requested by: wblock (1), kib (4)
Submitted by: wblock (2)

[rpokala]

lib/libc/sys/aio_fsync.2

94 ↗

(On Diff #19186)

I think

"while the request has been enqueued but has not yet completed."

reads a little clearer.

[jhb]

• s/after/while/
• Don't require non-changes to the buffer for fsync/mlock.

[jhb]

lib/libc/sys/aio_fsync.2

94 ↗

(On Diff #19186)

Could we even just say "while the request is enqueued"? If that language is sufficiently clear (i.e. not too vague) to cover the request up until it is completed, then I think it would be less of a mouthful.

lib/libc/sys/aio_mlock.2

88 ↗

(On Diff #19296)

In this case, I didn't want to keep the prohibition on modifying the buffer (i.e. the memory mapped by the region being mlock'd) as modifying the data in the pages won't result in indeterminate behavior wrt mlock(). However, it's not clear if we should prohibit changes to the mapping (e.g. munmap(), mprotect(), etc.) while the request is pending?

[kib]

lib/libc/sys/aio_mlock.2

88 ↗

(On Diff #19296)

We should prohibit changes to mappings, since mappings are parsed at the moment the mlock() is performed. Or rather, the aio request would mlock whatever is mapped at the time of processing, rather at the time of issuing the request.

BTW, there is a difference between modifying buffers or mappings, and modifying the control block itself. The laguage above only talks about control block.

[rpokala]

lib/libc/sys/aio_fsync.2

94 ↗

(On Diff #19186)

I'm fine with "while the request is enqueued", IFF the aiocb still counts as "enqueued" after it has been dispatched but while it is still in-flight.

[jhb]

• Fix subject/verb disagreement.
• Use conciser "is queued" vs "has been enqueued but not yet completed"
• Prohibit modifications of the memory mapping while queued.

[wblock]