What exactly is kqueue's EV_RECEIPT for?

Question

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?

Answer 1

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.