Page MenuHomeFreeBSD

Bug 196844 - [patch][doc] Add EXAMPLES section to kqueue(2) man page
ClosedPublic

Authored by bcr on Apr 24 2016, 12:06 PM.
Tags
None
Referenced Files
F109256807: D6082.id15552.diff
Sun, Feb 2, 4:56 PM
F109256430: D6082.id15790.diff
Sun, Feb 2, 4:50 PM
F109247003: D6082.diff
Sun, Feb 2, 2:03 PM
Unknown Object (File)
Fri, Jan 24, 10:59 PM
Unknown Object (File)
Dec 16 2024, 10:32 AM
Unknown Object (File)
Dec 14 2024, 2:57 AM
Unknown Object (File)
Dec 9 2024, 10:25 AM
Unknown Object (File)
Nov 30 2024, 11:18 PM

Details

Summary

We (Christian Brueffer and I) looked at a bug report [1] about adding an EXAMPLE to kqueue(2). We want to know whether you think the example is correct so that we can commit the patch? We think having an example there would be good to have.

[1] https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=196844

Test Plan
  1. Apply the patch
  2. View resulting man page
  3. Review/run the code in the proposed EXAMPLE section

Diff Detail

Repository
rS FreeBSD src repository - subversion
Lint
Lint Not Applicable
Unit
Tests Not Applicable

Event Timeline

bcr retitled this revision from to Bug 196844 - [patch][doc] Add EXAMPLES section to kqueue(2) man page.
bcr updated this object.
bcr edited the test plan for this revision. (Show Details)
bcr added reviewers: kib, jhb.
bcr set the repository for this revision to rS FreeBSD src repository - subversion.
bcr added a subscriber: brueffer.

Remember to update .Dd, too.

lib/libc/sys/kqueue.2
574 ↗(On Diff #15552)

Plain backslashes are not rendered correctly in man pages. They have to be replaced with \e. So this line becomes:

fprintf(stderr, "Event error: %s\en", strerror(event.data));
576 ↗(On Diff #15552)

As above:

printf("Something was written in '%s'\en", argv[1]);
bcr edited edge metadata.

Update the patch to address Warren's helpful comments:

  • use \en for the backslashes
  • bump .Dd (will update to a later date if the commit does not happen today)
kqueue.2
627 ↗(On Diff #15555)

This is not a successfull execution. That said, we usually express that idiom (perror/exit) with err(3).

"dir" in the usage string is somewhat confusing. I do not see why the argument must name a directory.

642 ↗(On Diff #15555)

It looks strange to set event to one shot, and then loop around re-arming the event after each action.

654 ↗(On Diff #15555)

Arguably, if EV_ERROR is set, the even was not fired. Unconditionally print a message about 'written' is not quite correct, isn't it ?

658 ↗(On Diff #15555)

If this is point is not reached, then what is the sense in writing non-trivial code (and really useless if it is reached, since kernel takes care about closing every open descriptor). Note that you do not close fd in premature exit on kevent(2) error. And you do not close kq at all.

bcr edited edge metadata.

Updated patch from PR submitter. See the reply here: https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=196844#c3
Kib's comments on EV_ONESHOT and re-arming the event were not fully understood. Maybe the new patch is good enough now? Otherwise, more explanation is needed.

bcr edited edge metadata.

Add kib's updated example (thanks for that), which removes EV_ONESHOT. Do we need some kind of introductory text at the beginning of the example or do you think it is self-explantory? In the latter case, I'll go ahead and commit it.

In D6082#131323, @bcr wrote:

Do we need some kind of introductory text at the beginning of the example or do you think it is self-explantory? In the latter case, I'll go ahead and commit it.

An example without text is better than no example.

Also note that the example really shows untypical kqueue use. Typical is to use kqueue to manage a large set of sockets, but this would require much more boilerplate code for example to be copy/paste-ready.

kib edited edge metadata.
This revision is now accepted and ready to land.May 1 2016, 5:53 PM
This revision was automatically updated to reflect the committed changes.