2 .\" Copyright (c) 2008-2016 Apple Inc. All rights reserved.
4 .\" @APPLE_LICENSE_HEADER_START@
6 .\" This file contains Original Code and/or Modifications of Original Code
7 .\" as defined in and that are subject to the Apple Public Source License
8 .\" Version 2.0 (the 'License'). You may not use this file except in
9 .\" compliance with the License. Please obtain a copy of the License at
10 .\" http://www.opensource.apple.com/apsl/ and read it before using this
13 .\" The Original Code and all software distributed under the License are
14 .\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
15 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
16 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
17 .\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
18 .\" Please see the License for the specific language governing rights and
19 .\" limitations under the License.
21 .\" @APPLE_LICENSE_HEADER_END@
24 .\" Copyright (c) 2000 Jonathan Lemon
25 .\" All rights reserved.
27 .\" Redistribution and use in source and binary forms, with or without
28 .\" modification, are permitted provided that the following conditions
30 .\" 1. Redistributions of source code must retain the above copyright
31 .\" notice, this list of conditions and the following disclaimer.
32 .\" 2. Redistributions in binary form must reproduce the above copyright
33 .\" notice, this list of conditions and the following disclaimer in the
34 .\" documentation and/or other materials provided with the distribution.
36 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND
37 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
38 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
39 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
40 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
41 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
42 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
43 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
44 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
45 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
48 .\" $FreeBSD: src/lib/libc/sys/kqueue.2,v 1.32 2002/12/19 09:40:25 ru Exp $
59 .Nd kernel event notification mechanism
69 .Fn kevent "int kq" "const struct kevent *changelist" "int nchanges" "struct kevent *eventlist" "int nevents" "const struct timespec *timeout"
71 .Fn kevent64 "int kq" "const struct kevent64_s *changelist" "int nchanges" "struct kevent64_s *eventlist" "int nevents" "unsigned int flags" "const struct timespec *timeout"
73 .Fn 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"
74 .Fn EV_SET "&kev" ident filter flags fflags data udata
75 .Fn EV_SET64 "&kev" ident filter flags fflags data udata "ext[0]" "ext[1]"
76 .Fn EV_SET_QOS "&kev" ident filter flags qos udata fflags xflags data "ext[0]" "ext[1]" "ext[2]" "ext[3]"
80 system call allocates a kqueue file descriptor. This file descriptor
81 provides a generic method of notifying the user when a kernel
82 event (kevent) happens or a condition holds, based on the results
83 of small pieces of kernel code termed filters.
85 A kevent is identified by an (ident, filter, and optional udata value)
86 tuple. It specifies the interesting conditions to be notified about
87 for that tuple. An (ident, filter, and optional udata value) tuple can
88 only appear once in a given kqueue.
89 Subsequent attempts to register the same tuple for a given kqueue
90 will result in the replacement of the conditions being watched,
92 Whether the udata value is considered as part of the tuple is controlled
93 by the EV_UDATA_SPECIFIC flag on the kevent.
95 The filter identified in a kevent is executed upon the initial
96 registration of that event in order to detect whether a preexisting
97 condition is present, and is also executed whenever an event is
98 passed to the filter for evaluation.
99 If the filter determines that the condition should be reported,
100 then the kevent is placed on the kqueue for the user to retrieve.
102 The filter is also run when the user attempts to retrieve the kevent
104 If the filter indicates that the condition that triggered
105 the event no longer holds, the kevent is removed from the kqueue and
108 Multiple events which trigger the filter do not result in multiple
109 kevents being placed on the kqueue; instead, the filter will aggregate
110 the events into a single struct kevent.
113 on a file descriptor will remove any kevents that reference the descriptor.
118 creates a new kernel event queue and returns a descriptor.
119 The queue is not inherited by a child created with
128 are used to register events with the queue, and return any pending
133 is a pointer to an array of
138 structures, as defined in
140 All changes contained in the
142 are applied before any pending events are read from the queue.
151 is a pointer to an array of out
159 argument determines the size of
161 If the KEVENT_FLAG_STACK_EVENTS flag is provided on the system call,
162 the eventlist array is filled in in stack order (starting in the
163 highest available index) instead of typical array order.
166 argument provides space for extra out data provided by specific filters.
169 argument's contents specified the space available in the data pool on input,
170 and contains the amount still remaining on output.
171 If the KEVENT_FLAG_STACK_DATA flag is specified on the system call,
172 the data is allocated from the pool in stack order instead of typical heap order.
175 is a non-NULL pointer, it specifies a maximum interval to wait
176 for an event, which will be interpreted as a struct timespec. If
178 is a NULL pointer, both
182 wait indefinitely. To effect a poll, the
188 can include the KEVENT_FLAG_IMMEDIATE value to indicate an
189 immediate timeout. Alternatively, the
191 argument should be non-NULL, pointing to a zero-valued
193 structure. The same array may be used for the
200 macro is provided for ease of initializing a
202 structure. Similarly,
217 structures are defined as:
220 uintptr_t ident; /* identifier for this event */
221 int16_t filter; /* filter for event */
222 uint16_t flags; /* general flags */
223 uint32_t fflags; /* filter-specific flags */
224 intptr_t data; /* filter-specific data */
225 void *udata; /* opaque user data identifier */
229 uint64_t ident; /* identifier for this event */
230 int16_t filter; /* filter for event */
231 uint16_t flags; /* general flags */
232 uint32_t fflags; /* filter-specific flags */
233 int64_t data; /* filter-specific data */
234 uint64_t udata; /* opaque user data identifier */
235 uint64_t ext[2]; /* filter-specific extensions */
238 struct kevent_qos_s {
239 uint64_t ident; /* identifier for this event */
240 int16_t filter; /* filter for event */
241 uint16_t flags; /* general flags */
242 uint32_t qos; /* quality of service when servicing event */
243 uint64_t udata; /* opaque user data identifier */
244 uint32_t fflags; /* filter-specific flags */
245 uint32_t xflags; /* extra filter-specific flags */
246 int64_t data; /* filter-specific data */
247 uint64_t ext[4]; /* filter-specific extensions */
255 .Fa struct kevent64_s
257 .Fa struct kevent_qos_s
259 .Bl -tag -width XXXfilter
261 Value used to identify the source of the event.
262 The exact interpretation is determined by the attached filter,
263 but often is a file descriptor.
265 Identifies the kernel filter used to process this event. The pre-defined
266 system filters are described below.
268 Actions to perform on the event.
270 Filter-specific flags.
272 Filter-specific data value.
274 Opaque user-defined value passed through the kernel unchanged. It can
275 optionally be part of the uniquing decision of the kevent system
279 .Fa struct kevent64_s
281 .Bl -tag -width XXXfilter
283 This field stores extensions for the event's filter. What type of extension depends on
284 what type of filter is being used.
288 .Fa struct kevent_qos_s
290 .Bl -tag -width XXXfilter
292 Extra filter-specific flags.
294 The QoS variant provides twice as many extension values for filter-specific uses.
301 field can contain the following values:
302 .Bl -tag -width XXXEV_ONESHOT
304 Adds the event to the kqueue. Re-adding an existing event
305 will modify the parameters of the original event, and not result
306 in a duplicate entry. Adding an event automatically enables it,
307 unless overridden by the EV_DISABLE flag.
314 to return the event if it is triggered.
321 will not return it. The filter itself is not disabled.
323 Removes the event from the kqueue. Events which are attached to
324 file descriptors are automatically deleted on the last close of
327 This flag is useful for making bulk changes to a kqueue without draining any
328 pending events. When passed as input, it forces EV_ERROR to always be returned.
329 When a filter is successfully added, the
333 Causes the event to return only the first occurrence of the filter
334 being triggered. After the user retrieves the event from the kqueue,
337 After the event is retrieved by the user, its state is reset.
338 This is useful for filters which report state transitions
339 instead of the current state. Note that some filters may automatically
340 set this flag internally.
342 Filters may set this flag to indicate filter-specific EOF condition.
344 Read filter on socket may set this flag to indicate the presence of out of
345 band data on the descriptor.
354 The predefined system filters are listed below.
355 Arguments may be passed to and from the filter via the
366 .Bl -tag -width EVFILT_MACHPORT
368 Takes a file descriptor as the identifier, and returns whenever
369 there is data available to read.
370 The behavior of the filter is slightly different depending
371 on the descriptor type.
375 Sockets which have previously been passed to
377 return when there is an incoming connection pending.
379 contains the size of the listen backlog.
381 Other socket descriptors return when there is data to be read,
384 value of the socket buffer.
385 This may be overridden with a per-filter low water mark at the
386 time the filter is added by setting the
390 and specifying the new low water mark in
392 The derived per filter low water mark value is, however, bounded
393 by socket receive buffer's high and low water mark values.
396 contains the number of bytes of protocol data available to read.
398 The presence of EV_OOBAND in
400 indicates the presence of out of band data on the socket
402 equal to the potential number of OOB bytes availble to read.
404 If the read direction of the socket has shutdown, then the filter
407 and returns the socket error (if any) in
409 It is possible for EOF to be returned (indicating the connection is gone)
410 while there is still data pending in the socket buffer.
412 Returns when the file pointer is not at the end of file.
414 contains the offset from current position to end of file,
417 Returns when there is data to read;
419 contains the number of bytes available.
421 When the last writer disconnects, the filter will set EV_EOF in
423 This may be cleared by passing in EV_CLEAR, at which point the
424 filter will resume waiting for data to become available before
427 Returns when there is data to read from the device;
429 contains the number of bytes available. If the device does
430 not support returning number of bytes, it will not allow the
431 filter to be attached. However, if the NOTE_LOWAT flag is
434 field contains 1 on input, those devices will attach - but
435 cannot be relied upon to provide an accurate count of bytes
436 to be read on output.
439 Takes a descriptor as the identifier, and returns whenever one of the
440 specified exceptional conditions has occurred on the descriptor. Conditions
443 Currently, this filter can be used to monitor the arrival of
444 out-of-band data on a socket descriptor using the filter flag
447 If the read direction of the socket has shutdown, then the filter
450 and returns the socket error (if any) in
453 Takes a file descriptor as the identifier, and returns whenever
454 it is possible to write to the descriptor. For sockets, pipes
457 will contain the amount of space remaining in the write buffer.
458 The filter will set EV_EOF when the reader disconnects, and for
459 the fifo case, this may be cleared by use of EV_CLEAR.
460 Note that this filter is not supported for vnodes.
462 For sockets, the low water mark and socket error handling is
463 identical to the EVFILT_READ case.
465 This filter is currently unsupported.
466 .\"The sigevent portion of the AIO request is filled in, with
467 .\".Va sigev_notify_kqueue
468 .\"containing the descriptor of the kqueue that the event should
471 .\"containing the udata value, and
473 .\"set to SIGEV_KEVENT.
476 .\"system call is made, the event will be registered
477 .\"with the specified kqueue, and the
479 .\"argument set to the
484 .\"The filter returns under the same conditions as aio_error.
486 .\"Alternatively, a kevent structure may be initialized, with
488 .\"containing the descriptor of the kqueue, and the
489 .\"address of the kevent structure placed in the
490 .\".Va aio_lio_opcode
491 .\"field of the AIO request. However, this approach will not work on
492 .\"architectures with 64-bit pointers, and should be considered deprecated.
494 Takes a file descriptor as the identifier and the events to watch for in
496 and returns when one or more of the requested events occurs on the descriptor.
497 The events to monitor are:
498 .Bl -tag -width XXNOTE_RENAME
503 was called on the file referenced by the descriptor.
505 A write occurred on the file referenced by the descriptor.
507 The file referenced by the descriptor was extended.
509 The file referenced by the descriptor had its attributes changed.
511 The link count on the file changed.
513 The file referenced by the descriptor was renamed.
515 Access to the file was revoked via
517 or the underlying fileystem was unmounted.
519 The file was unlocked by calling
527 contains the filter-specific flags which are associated with
528 the triggered events seen by this filter.
530 Takes the process ID to monitor as the identifier and the events to watch for
533 and returns when the process performs one or more of the requested events.
534 If a process can normally see another process, it can attach an event to it.
535 The events to monitor are:
536 .Bl -tag -width NOTE_SIGNAL
538 The process has exited.
540 The process has exited and its exit status is in filter specific data. Valid only on child processes and to be used along with NOTE_EXIT.
542 The process created a child process via
546 The process executed a new process via
550 The process was sent a signal. Status can be checked via
554 The process was reaped by the parent via
556 or similar call. Deprecated, use NOTE_EXIT.
561 contains the events which triggered the filter.
563 Takes the signal number to monitor as the identifier and returns
564 when the given signal is generated for the process.
565 This coexists with the
569 facilities, and has a lower precedence. Only signals sent to the process,
570 not to a particular thread, will trigger the filter. The filter will record
571 all attempts to deliver a signal to a process, even if the signal has
572 been marked as SIG_IGN. Event notification happens before normal
573 signal delivery processing.
575 returns the number of times the signal has been generated since the last call to
577 This filter automatically sets the EV_CLEAR flag internally.
579 Takes the name of a mach port, or port set, in
581 and waits until a message is enqueued on the port or port set. When a message
582 is detected, but not directly received by the kevent call, the name of the
583 specific port where the message is enqueued is returned in
587 contains MACH_RCV_MSG, the ext[0] and ext[1] flags are assumed to contain
588 a pointer to the buffer where the message is to be received and the size
589 of the receive buffer, respectively. If MACH_RCV_MSG is specifed, yet the
590 buffer size in ext[1] is zero, The space for the buffer may be carved out
596 if there is enough space remaining there.
598 Establishes an interval timer identified by
602 specifies the timeout period (in milliseconds).
605 can include one of the following flags to specify a different unit:
606 .Bl -tag -width NOTE_NSECONDS
618 is in Mach absolute time units
626 timer with an absolute deadline instead of an interval.
627 The absolute deadline is expressed in terms of
631 the deadline is expressed in terms of
632 .Fn mach_absolute_time .
634 The timer can be coalesced with other timers to save power. The following flags can be set in
636 to modify this behavior:
637 .Bl -tag -width NOTE_BACKGROUND
639 override default power-saving techniques to more strictly respect the leeway value
641 apply more power-saving techniques to coalesce this timer with other timers
644 holds user-supplied slop in deadline for timer coalescing.
647 The timer will be periodic unless
652 contains the number of times the timeout has expired since the last arming or last delivery of the timer event.
654 This filter automatically sets the
667 is only used with the EVFILT_MACHPORT filter.
675 can always be used like
677 For the use of ext[0], see the EVFILT_MACHPORT filter above.
682 creates a new kernel event queue and returns a file descriptor.
683 If there was an error creating the kernel event queue, a value of -1 is
684 returned and errno set.
692 return the number of events placed in the
694 up to the value given by
696 If an error occurs while processing an element of the
698 and there is enough room in the
700 then the event will be placed in the
706 and the system error in
710 will be returned, and
712 will be set to indicate the error condition.
713 If the time limit expires, then
722 system call fails if:
725 The kernel failed to allocate enough memory for the kernel queue.
727 The per-process descriptor table is full.
729 The system file table is full.
736 system calls fail if:
739 The process does not have permission to register a filter.
741 There was an error reading or writing the
747 The specified descriptor is invalid.
749 A signal was delivered before the timeout expired and before any
750 events were placed on the kqueue for return.
752 The specified time limit or filter is invalid.
754 The event could not be found to be modified or deleted.
756 No memory was available to register the event.
758 The specified process to attach to does not exist.
774 system calls first appeared in
779 system and this manual page were written by
780 .An Jonathan Lemon Aq jlemon@FreeBSD.org .
782 Not all filesystem types support kqueue-style notifications.
783 And even some that do, like some remote filesystems, may only
784 support a subset of the notification semantics described
projects / apple / xnu.git / blob