| KQUEUE(2) | System Calls Manual | KQUEUE(2) |
kqueue, kevent,
kevent64 and kevent_qos
— kernel event notification mechanism
Standard C Library (libc, -lc)
#include
<sys/types.h>
#include <sys/event.h>
#include <sys/time.h>
int
kqueue(void);
int
kevent(int
kq, const struct kevent
*changelist, int
nchanges, struct kevent
*eventlist, int
nevents, const struct
timespec *timeout);
int
kevent64(int
kq, const struct
kevent64_s *changelist,
int nchanges,
struct kevent64_s
*eventlist, int
nevents, unsigned int
flags, const struct
timespec *timeout);
int
kevent_qos(int
kq, const struct
kevent_qos_s *changelist,
int nchanges,
struct kevent_qos_s
*eventlist, int
nevents, void
*data_out, size_t
*data_available, unsigned
int flags);
EV_SET(&kev,
ident,
filter,
flags,
fflags,
data,
udata);
EV_SET64(&kev,
ident,
filter,
flags,
fflags,
data,
udata,
ext[0],
ext[1]);
EV_SET_QOS(&kev,
ident,
filter,
flags,
qos,
udata,
fflags,
xflags,
data,
ext[0],
ext[1],
ext[2],
ext[3]);
The
kqueue()
system call allocates a kqueue file descriptor. This file descriptor
provides a generic method of notifying the user when a kernel event (kevent)
happens or a condition holds, based on the results of small pieces of kernel
code termed filters.
A kevent is identified by an (ident, filter, and optional udata value) tuple. It specifies the interesting conditions to be notified about for that tuple. An (ident, filter, and optional udata value) tuple can only appear once in a given kqueue. Subsequent attempts to register the same tuple for a given kqueue will result in the replacement of the conditions being watched, not an addition. Whether the udata value is considered as part of the tuple is controlled by the EV_UDATA_SPECIFIC flag on the kevent.
The filter identified in a kevent is executed upon the initial registration of that event in order to detect whether a preexisting condition is present, and is also executed whenever an event is passed to the filter for evaluation. If the filter determines that the condition should be reported, then the kevent is placed on the kqueue for the user to retrieve.
The filter is also run when the user attempts to retrieve the kevent from the kqueue. If the filter indicates that the condition that triggered the event no longer holds, the kevent is removed from the kqueue and is not returned.
Multiple events which trigger the filter do not result
in multiple kevents being placed on the kqueue; instead, the filter will
aggregate the events into a single struct kevent. Calling
close() on a
file descriptor will remove any kevents that reference the descriptor.
The
kqueue()
system call creates a new kernel event queue and returns a descriptor. The
queue is not inherited by a child created with
fork(2).
The
kevent,()
kevent64() and
kevent_qos()
system calls are used to register events with the queue, and return any
pending events to the user. The changelist argument is
a pointer to an array of kevent,
kevent64_s or kevent_qos_s
structures, as defined in
⟨sys/event.h⟩. All changes contained
in the changelist are applied before any pending
events are read from the queue. The nchanges argument
gives the size of changelist.
The eventlist argument is a pointer to an array of out kevent, kevent64_s or kevent_qos_s structures. The nevents argument determines the size of eventlist.
The data_out argument provides space for extra out data provided by specific filters. The data_available argument's contents specified the space available in the data pool on input, and contains the amount still remaining on output. If the KEVENT_FLAG_STACK_DATA flag is specified on the system call, the data is allocated from the pool in stack order instead of typical heap order.
If timeout is a non-NULL
pointer, it specifies a maximum interval to wait for an event, which will be
interpreted as a struct timespec. If timeout is a NULL
pointer, both
kevent() and
kevent64() wait indefinitely. To effect a poll, the
flags argument to kevent64()
or kevent_qos() can include the
KEVENT_FLAG_IMMEDIATE value to indicate an immediate timeout. Alternatively,
the timeout argument should be non-NULL, pointing to a
zero-valued timespec structure. The same array may be
used for the changelist and
eventlist.
The
EV_SET()
macro is provided for ease of initializing a kevent
structure. Similarly,
EV_SET64()
initializes a kevent64_s structure and
EV_SET_QOS()
initializes a kevent_qos_s structure.
The kevent, kevent64_s and kevent_qos_s structures are defined as:
struct kevent {
uintptr_t ident; /* identifier for this event */
int16_t filter; /* filter for event */
uint16_t flags; /* general flags */
uint32_t fflags; /* filter-specific flags */
intptr_t data; /* filter-specific data */
void *udata; /* opaque user data identifier */
};
struct kevent64_s {
uint64_t ident; /* identifier for this event */
int16_t filter; /* filter for event */
uint16_t flags; /* general flags */
uint32_t fflags; /* filter-specific flags */
int64_t data; /* filter-specific data */
uint64_t udata; /* opaque user data identifier */
uint64_t ext[2]; /* filter-specific extensions */
};
struct kevent_qos_s {
uint64_t ident; /* identifier for this event */
int16_t filter; /* filter for event */
uint16_t flags; /* general flags */
uint32_t qos; /* quality of service when servicing event */
uint64_t udata; /* opaque user data identifier */
uint32_t fflags; /* filter-specific flags */
uint32_t xflags; /* extra filter-specific flags */
int64_t data; /* filter-specific data */
uint64_t ext[4]; /* filter-specific extensions */
};
----
The fields of struct kevent, struct kevent64_s and struct kevent_qos_s are:
In addition, struct kevent64_s contains:
In addition, struct kevent_qos_s contains:
----
The flags field can contain the following values:
kevent,()
kevent64() and
kevent_qos()
to return the event if it is triggered.kevent,()
kevent64() and
kevent_qos() will not return it. The filter itself
is not disabled.----
The predefined system filters are listed below. Arguments may be passed to and from the filter via the data, fflags and optionally xflags fields in the kevent, kevent64_s or kevent_qos_s structure.
listen()
return when there is an incoming connection pending.
data contains the size of the listen backlog.
Other socket descriptors return when there is data to be
read, subject to the SO_RCVLOWAT value of
the socket buffer. This may be overridden with a per-filter low
water mark at the time the filter is added by setting the NOTE_LOWAT
flag in fflags, and specifying the new low
water mark in data. The derived per filter low
water mark value is, however, bounded by socket receive buffer's
high and low water mark values. On return,
data contains the number of bytes of protocol
data available to read.
The presence of EV_OOBAND in flags, indicates the presence of out of band data on the socket data equal to the potential number of OOB bytes availble to read.
If the read direction of the socket has shutdown, then the filter also sets EV_EOF in flags, and returns the socket error (if any) in fflags. It is possible for EOF to be returned (indicating the connection is gone) while there is still data pending in the socket buffer.
When the last writer disconnects, the filter will set EV_EOF in flags. This may be cleared by passing in EV_CLEAR, at which point the filter will resume waiting for data to become available before returning.
EVFILT_EXCEPTNOTE_OOB.
If the read direction of the socket has shutdown, then the filter also sets EV_EOF in flags, and returns the socket error (if any) in fflags.
For sockets, the low water mark and socket error handling is identical to the EVFILT_READ case.
unlink()
system call was called on the file referenced by the descriptor.On return, fflags contains the filter-specific flags which are associated with the triggered events seen by this filter.
On return, fflags contains the events which triggered the filter.
signal()
and
sigaction()
facilities, and has a lower precedence. Only signals sent to the process,
not to a particular thread, will trigger the filter. The filter will
record all attempts to deliver a signal to a process, even if the signal
has been marked as SIG_IGN. Event notification happens before normal
signal delivery processing. data returns the number
of times the signal has been generated since the last call to
kevent(). This filter automatically sets the
EV_CLEAR flag internally.kevent_qos() if there is
enough space remaining there.fflags can include one of the following flags to specify a different unit:
fflags can also
include NOTE_ABSOLUTE, which establishes an
EV_ONESHOT timer with an absolute deadline
instead of an interval. The absolute deadline is expressed in terms of
gettimeofday(2). With
NOTE_MACHTIME, the deadline is expressed in
terms of
mach_absolute_time().
The timer can be coalesced with other timers to save power. The following flags can be set in fflags to modify this behavior:
The timer will be periodic unless
EV_ONESHOT is specified. On return,
data contains the number of times the timeout has
expired since the last arming or last delivery of the timer event.
This filter automatically sets the
EV_CLEAR flag.
----
In the ext[2] field of the
kevent64_s struture, ext[0] is
only used with the EVFILT_MACHPORT filter. With other filters,
ext[0] is passed through
kevent64()
much like udata. ext[1] can
always be used like udata. For the use of ext[0], see
the EVFILT_MACHPORT filter above.
The kqueue() system call creates a new
kernel event queue and returns a file descriptor. If there was an error
creating the kernel event queue, a value of -1 is returned and errno
set.
The kevent(),
kevent64() and kevent_qos()
system calls return the number of events placed in the
eventlist, up to the value given by
nevents. If an error occurs while processing an
element of the changelist and there is enough room in
the eventlist, then the event will be placed in the
eventlist with EV_ERROR set in
flags and the system error in
data. Otherwise, -1 will be
returned, and errno will be set to indicate the
error condition. If the time limit expires, then
kevent(), kevent64() and
kevent_qos() return 0.
The kqueue() system call fails if:
ENOMEM]EMFILE]ENFILE]The kevent() and
kevent64() system calls fail if:
EACCES]EFAULT]EBADF]EINTR]EINVAL]ENOENT]ENOMEM]ESRCH]aio_error(2), aio_read(2), aio_return(2), read(2), select(2), sigaction(2), write(2), signal(3)
The kqueue() and
kevent() system calls first appeared in
FreeBSD 4.1.
The kqueue() system and this manual page
were written by Jonathan Lemon
⟨jlemon@FreeBSD.org⟩.
Not all filesystem types support kqueue-style notifications. And even some that do, like some remote filesystems, may only support a subset of the notification semantics described here.
| October 21, 2008 | macOS 15.0 |