6

The kqueue mechanism has an event flag, EV_RECEIPT, which according to the linked man page:

... is useful for making bulk changes to a kqueue without draining any pending events. When passed as input, it forces EV_ERROR to always be returned. When a filter is successfully added the data field will be zero.

My understanding however is that it is trivial to make bulk changes to a kqueue without draining any pending events, simply by passing 0 for the nevents parameter to kevent and thus drawing no events from the queue. With that in mind, why is EV_RECEIPT necesary?

Some sample code in Apple documentation for OS X actually uses EV_RECEIPT:

kq = kqueue();

EV_SET(&changes, gTargetPID, EVFILT_PROC, EV_ADD | EV_RECEIPT, NOTE_EXIT, 0, NULL);
(void) kevent(kq, &changes, 1, &changes, 1, NULL);

But, seeing as the changes array is never examined after the kevent call, it's totally unclear to me why EV_RECEIPT was used in this case.

Is EV_RECEIPT actually necessary? In what situation would it really be useful?

davmac
  • 20,150
  • 1
  • 40
  • 68

1 Answers1

4

If you are making bulk changes and one of them causes an error, then the event will be placed in the eventlist with EV_ERROR set in flags and the system error in data.

Therefore it is possible to identify which changelist element caused the error.

If you set nevents to zero, you get the error code but no indication of which event caused the error.

So EV_RECEIPT allows you to set nevents to a non-zero value without draining any pending events.

Richard Smith
  • 45,711
  • 6
  • 82
  • 81
  • Ok, this makes sense, but it doesn't correlate with the code in the Apple example that I linked. The comment in that code says: _Create the kqueue and set it up to watch for SIGCHLD. Use the new-in-10.5 EV_RECEIPT flag to ensure that we get what we expect_ - however, it calls `kevent` with just a single event, uses `EV_RECEIPT`, and checks neither the return from `kevent` nor the values in the return events. Any clue as to what the comment means by "we get what we expect"? - or is the use of `EV_RECEIPT` in this case bogus? – davmac Jun 09 '16 at 21:53
  • I think in this case, setting `nevents` to zero would achieve identical behaviour, as the return value is not checked. But this may be a pattern that is replicated in other code where the return value *is* checked. The expectation being that the new filter is returned and *not* a pending event. – Richard Smith Jun 10 '16 at 07:09
  • Is this code even entirely valid then, since it does not check the events list for errors? I seemed to be discovering that zombie processes return ESRCH when you try to add them to kqevent with NOTE_EXIT, but I cannot find many references or documentation online that describe what is supposed to happen in that case. – user1712368 Feb 01 '22 at 18:44