2 .\" Copyright (c) 2008-2015 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 file descriptor as the identifier, and returns whenever
440 it is possible to write to the descriptor. For sockets, pipes
443 will contain the amount of space remaining in the write buffer.
444 The filter will set EV_EOF when the reader disconnects, and for
445 the fifo case, this may be cleared by use of EV_CLEAR.
446 Note that this filter is not supported for vnodes.
448 For sockets, the low water mark and socket error handling is
449 identical to the EVFILT_READ case.
451 This filter is currently unsupported.
452 .\"The sigevent portion of the AIO request is filled in, with
453 .\".Va sigev_notify_kqueue
454 .\"containing the descriptor of the kqueue that the event should
457 .\"containing the udata value, and
459 .\"set to SIGEV_KEVENT.
462 .\"system call is made, the event will be registered
463 .\"with the specified kqueue, and the
465 .\"argument set to the
470 .\"The filter returns under the same conditions as aio_error.
472 .\"Alternatively, a kevent structure may be initialized, with
474 .\"containing the descriptor of the kqueue, and the
475 .\"address of the kevent structure placed in the
476 .\".Va aio_lio_opcode
477 .\"field of the AIO request. However, this approach will not work on
478 .\"architectures with 64-bit pointers, and should be considered deprecated.
480 Takes a file descriptor as the identifier and the events to watch for in
482 and returns when one or more of the requested events occurs on the descriptor.
483 The events to monitor are:
484 .Bl -tag -width XXNOTE_RENAME
489 was called on the file referenced by the descriptor.
491 A write occurred on the file referenced by the descriptor.
493 The file referenced by the descriptor was extended.
495 The file referenced by the descriptor had its attributes changed.
497 The link count on the file changed.
499 The file referenced by the descriptor was renamed.
501 Access to the file was revoked via
503 or the underlying fileystem was unmounted.
508 contains the filter-specific flags which are associated with
509 the triggered events seen by this filter.
511 Takes the process ID to monitor as the identifier and the events to watch for
514 and returns when the process performs one or more of the requested events.
515 If a process can normally see another process, it can attach an event to it.
516 The events to monitor are:
517 .Bl -tag -width NOTE_SIGNAL
519 The process has exited.
521 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.
523 The process created a child process via
527 The process executed a new process via
531 The process was sent a signal. Status can be checked via
535 The process was reaped by the parent via
537 or similar call. Deprecated, use NOTE_EXIT.
542 contains the events which triggered the filter.
544 Takes the signal number to monitor as the identifier and returns
545 when the given signal is generated for the process.
546 This coexists with the
550 facilities, and has a lower precedence. Only signals sent to the process,
551 not to a particular thread, will trigger the filter. The filter will record
552 all attempts to deliver a signal to a process, even if the signal has
553 been marked as SIG_IGN. Event notification happens before normal
554 signal delivery processing.
556 returns the number of times the signal has been generated since the last call to
558 This filter automatically sets the EV_CLEAR flag internally.
560 Takes the name of a mach port, or port set, in
562 and waits until a message is enqueued on the port or port set. When a message
563 is detected, but not directly received by the kevent call, the name of the
564 specific port where the message is enqueued is returned in
568 contains MACH_RCV_MSG, the ext[0] and ext[1] flags are assumed to contain
569 a pointer to the buffer where the message is to be received and the size
570 of the receive buffer, respectively. If MACH_RCV_MSG is specifed, yet the
571 buffer size in ext[1] is zero, The space for the buffer may be carved out
577 if there is enough space remaining there.
579 Establishes an interval timer with the data
584 specifies the timeout period and
586 can be set to one of the following:
587 .Bl -tag -width NOTE_ABSOLUTE
591 data is in microseconds
593 data is in nanoseconds
595 data is an absolute timeout
597 system makes a best effort to fire this timer as scheduled.
599 system has extra leeway to coalesce this timer.
601 ext[1] holds user-supplied slop in deadline for timer coalescing.
604 If fflags is not set, the default is milliseconds. The timer will be periodic unless EV_ONESHOT is specified.
607 contains the number of times the timeout has expired since the last call to
613 This filter automatically sets the EV_CLEAR flag internally.
624 is only used with the EVFILT_MACHPORT filter.
632 can always be used like
634 For the use of ext[0], see the EVFILT_MACHPORT filter above.
639 creates a new kernel event queue and returns a file descriptor.
640 If there was an error creating the kernel event queue, a value of -1 is
641 returned and errno set.
649 return the number of events placed in the
651 up to the value given by
653 If an error occurs while processing an element of the
655 and there is enough room in the
657 then the event will be placed in the
663 and the system error in
667 will be returned, and
669 will be set to indicate the error condition.
670 If the time limit expires, then
679 system call fails if:
682 The kernel failed to allocate enough memory for the kernel queue.
684 The per-process descriptor table is full.
686 The system file table is full.
693 system calls fail if:
696 The process does not have permission to register a filter.
698 There was an error reading or writing the
704 The specified descriptor is invalid.
706 A signal was delivered before the timeout expired and before any
707 events were placed on the kqueue for return.
709 The specified time limit or filter is invalid.
711 The event could not be found to be modified or deleted.
713 No memory was available to register the event.
715 The specified process to attach to does not exist.
731 system calls first appeared in
736 system and this manual page were written by
737 .An Jonathan Lemon Aq jlemon@FreeBSD.org .
739 Not all filesystem types support kqueue-style notifications.
740 And even some that do, like some remote filesystems, may only
741 support a subset of the notification semantics described
projects / apple / xnu.git / blob