Add documentation for the sigevent structure.
ClosedPublic
Actions

Authored by jhb on Jul 5 2016, 8:01 PM.

Details

Reviewers

kib
wblock

Group Reviewers

manpages

Commits

rS302899: Add documentation for the sigevent structure.

Summary

Add documentation for the sigevent structure.

Add a sigevent(3) manpage to give a general overview of the sigevent structure and the available notification mechanisms.
Document that AIO requests contain a nested sigevent structure that can be used to request completion notification.
Expand the sigevent details in other manuals to note details such as the extra values stored in a queued signal's information or in a posted kevent.

Note, I don't have any Dd bumps in the diffs yet as I'd just have to
update them prior to commit, but I will bump them prior to commit.

Repository

rS FreeBSD src repository - subversion

Lint

Lint Not Applicable

Unit

Tests Not Applicable

jhb retitled this revision from to Add documentation for the sigevent structure..

jhb updated this object.

jhb edited the test plan for this revision. (Show Details)

jhb added reviewers: kib, wblock.

kib added inline comments.Jul 6 2016, 2:55 AM

lib/libc/sys/aio_fsync.2
77 ↗	(On Diff #18164)	locking ?
86 ↗	(On Diff #18164)	Might be, say use of stack variables for these objects should ensure that the scope is alive until the request completion. Discouraged is too strong IMO.
92 ↗	(On Diff #18164)	Uhh, do we rally have such requirement ? This seems to be not needed in POSIX.
lib/libc/sys/aio_read.2
85 ↗	(On Diff #18164)	locking
lib/libc/sys/aio_write.2
91 ↗	(On Diff #18164)	locking
share/man/man3/sigevent.3
68 ↗	(On Diff #18164)	Might be, add words about real-time behaviour of the delivery, even without expanding the meaning. This should give enough context to follow references in POSIX.

jhb marked 3 inline comments as done.Jul 15 2016, 2:36 AM

jhb added inline comments.

lib/libc/sys/aio_fsync.2
77 ↗	(On Diff #18164)	Oops, copy and paste.
86 ↗	(On Diff #18164)	I copied this language from the other aio pages (it was missing only in this one). We can refine that language in a followup to all of the pages. I also don't read discouraged as strongly though. We could possibly just drop the entire sentence about stack variables. C programmers should be already realize this. Note that we don't advise them to avoid putting the I/O buffer for aio_read/write on the stack, we just provide a similar statement about the buffer needing to be valid until the request has completed.
92 ↗	(On Diff #18164)	We effectively do, though really all we need is for aio_sigevent to be initialized (sigev_notify set to SIGEV_NONE). The fact that aio_sigevent was previously undocumented made this more important. As with the note above, this language was copied from the other pages and was only missing in the fsync page.
share/man/man3/sigevent.3
68 ↗	(On Diff #18164)	I was sort of hoping "signal ... queued" was sufficiently magic as I thought queued signals implied the real-time stuff. I could easily be wrong though (I don't really know how queued / realtime signals differ from "plain" ones). Is it correct to say "queued as a real-time signal to the calling process"?

kib accepted this revision.Jul 15 2016, 2:57 AM

kib edited edge metadata.

kib added inline comments.

share/man/man3/sigevent.3
68 ↗	(On Diff #18164)	On FreeBSD, all signals are queued, i.e. they all have realtime semantic, until memory or limits are exhausted. The later rewording looks good.