1.\" Copyright (c) 2000 Jonathan Lemon 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd April 14, 2000 28.Dt KQUEUE 2 29.Os 30.Sh NAME 31.Nm kqueue , 32.Nm kevent 33.Nd kernel event notification mechanism 34.Sh LIBRARY 35.Lb libc 36.Sh SYNOPSIS 37.Fd #include <sys/types.h> 38.Fd #include <sys/event.h> 39.Ft int 40.Fn kqueue "void" 41.Ft int 42.Fn kevent "int kq" "const struct kevent *changelist" "int nchanges" "struct kevent *eventlist" "int nevents" "const struct timespec *timeout" 43.Sh DESCRIPTION 44.Fn kqueue 45provides a generic method of notifying the user when an event 46happens or a condition holds, based on the results of small 47pieces of kernel code termed filters. 48A kevent is identified by the (ident, filter) pair; there may only 49be one unique kevent per kqueue. 50.Pp 51The filter is executed upon the initial registration of a kevent 52in order to detect whether a preexisting condition is present, and is also 53executed whenever an event is passed to the filter for evaluation. 54If the filter determines that the condition should be reported, 55then the kevent is placed on the kqueue for the user to retrieve. 56.Pp 57The filter is also run when the user attempts to retrieve the kevent 58from the kqueue. 59If the filter indicates that the condition that triggered 60the event no longer holds, the kevent is removed from the kqueue and 61is not returned. 62.Pp 63Multiple events which trigger the filter do not result in multiple 64kevents being placed on the kqueue; instead, the filter will aggregate 65the events into a single struct kevent. 66Calling 67.Fn close 68on a file descriptor will remove any kevents that reference the descriptor. 69.Pp 70.Fn kqueue 71creates a new kernel event queue and returns a descriptor. 72The queue is not inherited by a child created with 73.Xr fork 2 . 74However, if 75.Xr rfork 2 76is called without the 77.Dv RFFDG 78flag, then the descriptor table is shared, 79which will allow sharing of the kqueue between two processes. 80.Pp 81.Fn kevent 82is used to register events with the queue, and return any pending 83events to the user. 84.Fa changelist 85is a pointer to an array of 86.Va kevent 87structures, as defined in 88.Aq Pa event.h . 89All changes contained in the 90.Fa changelist 91are applied before any pending events are read from the queue. 92.Fa nchanges 93gives the size of 94.Fa changelist . 95.Fa eventlist 96is a pointer to an array of kevent structures. 97.Fa nevents 98determines the size of 99.Fa eventlist . 100If 101.Fa timeout 102is a non-NULL pointer, it specifies a maximum interval to wait 103for an event, which will be interpreted as a struct timespec. If 104.Fa timeout 105is a NULL pointer, 106.Fn kevent 107waits indefinitely. To effect a poll, the 108.Fa timeout 109argument should be non-NULL, pointing to a zero-valued 110.Va timespec 111structure. The same array may be used for the 112.Fa changelist 113and 114.Fa eventlist . 115.Pp 116The 117.Va kevent 118structure is defined as: 119.Bd -literal 120struct kevent { 121 uintptr_t ident; /* identifier for this event */ 122 short filter; /* filter for event */ 123 u_short flags; /* action flags for kqueue */ 124 u_int fflags; /* filter flag value */ 125 intptr_t data; /* filter data value */ 126 void *udata; /* opaque user data identifier */ 127}; 128.Ed 129.Pp 130The fields of 131.Fa struct kevent 132are: 133.Bl -tag -width XXXfilter 134.It ident 135Value used to identify this event. 136The exact interpretation is determined by the attached filter, 137but often is a file descriptor. 138.It filter 139Identifies the kernel filter used to process this event. The pre-defined 140system filters are described below. 141.It flags 142Actions to perform on the event. 143.It fflags 144Filter-specific flags. 145.It data 146Filter-specific data value. 147.It udata 148Opaque user-defined value passed through the kernel unchanged. 149.El 150.Pp 151The 152.Va flags 153field can contain the following values: 154.Bl -tag -width XXXEV_ONESHOT 155.It EV_ADD 156Adds the event to the kqueue. Re-adding an existing event 157will modify the parameters of the original event, and not result 158in a duplicate entry. Adding an event automatically enables it, 159unless overridden by the EV_DISABLE flag. 160.It EV_ENABLE 161Permit 162.Fn kevent 163to return the event if it is triggered. 164.It EV_DISABLE 165Disable the event so 166.Fn kevent 167will not return it. The filter itself is not disabled. 168.It EV_DELETE 169Removes the event from the kqueue. Events which are attached to 170file descriptors are automatically deleted on the last close of 171the descriptor. 172.It EV_ONESHOT 173Causes the event to return only the first occurrence of the filter 174being triggered. After the user retrieves the event from the kqueue, 175it is deleted. 176.It EV_CLEAR 177After the event is retrieved by the user, its state is reset. 178This is useful for filters which report state transitions 179instead of the current state. Note that some filters may automatically 180set this flag internally. 181.It EV_EOF 182Filters may set this flag to indicate filter-specific EOF condition. 183.It EV_ERROR 184See 185.Sx RETURN VALUES 186below. 187.El 188.Pp 189The predefined system filters are listed below. 190Arguments may be passed to and from the filter via the 191.Va fflags 192and 193.Va data 194fields in the kevent structure. 195.Bl -tag -width EVFILT_SIGNAL 196.It EVFILT_READ 197Takes a descriptor as the identifier, and returns whenever 198there is data available to read. 199The behavior of the filter is slightly different depending 200on the descriptor type. 201.Bl -tag -width 2n 202.It Sockets 203Sockets which have previously been passed to 204.Fn listen 205return when there is an incoming connection pending. 206.Va data 207contains the size of the listen backlog. 208.Pp 209Other socket descriptors return when there is data to be read, 210subject to the SO_RCVLOWAT value of the socket buffer. 211.Va data 212contains the number of bytes in the socket buffer. 213.Pp 214If the read direction of the socket has shutdown, then the filter 215also sets EV_EOF in 216.Va flags . 217It is possible for EOF to be returned (indicating the connection is gone) 218while there is still data pending in the socket buffer. 219.It Vnodes 220Returns when the file pointer is not at the end of file. 221.Va data 222contains the offset from current position to end of file, 223and may be negative. 224.It "Fifos, Pipes" 225Returns when the there is data to read; 226.Va data 227contains the number of bytes available. 228.Pp 229When the last writer disconnects, the filter will set EV_EOF in 230.Va flags . 231This may be cleared by passing in EV_CLEAR, at which point the 232filter will resume waiting for data to become available before 233returning. 234.El 235.It EVFILT_WRITE 236Takes a descriptor as the identifier, and returns whenever 237it is possible to write to the descriptor. For sockets, pipes 238and fifos, 239.Va data 240will contain the amount of space remaining in the write buffer. 241The filter will set EV_EOF when the reader disconnects, and for 242the fifo case, this may be cleared by use of EV_CLEAR. 243Note that this filter is not supported for vnodes. 244.It EVFILT_AIO 245A kevent structure is initialized, with 246.Va ident 247containing the descriptor of the kqueue that the event should be 248attached to. The address of the kevent structure is then placed in the 249.Va aio_lio_opcode 250field of the AIO request, and the aio_* function is then called. 251The event will be registered with the specified kqueue, and the 252.Va ident 253argument set to the 254.Fa struct aiocb 255returned by the aio_* function. 256The filter returns under the same conditions as aio_error. 257.Pp 258NOTE: this interface is unstable and subject to change. 259.It EVFILT_VNODE 260Takes a file descriptor as the identifier and the events to watch for in 261.Va fflags , 262and returns when one or more of the requested events occurs on the descriptor. 263The events to monitor are: 264.Bl -tag -width XXNOTE_RENAME 265.It NOTE_DELETE 266.Fn unlink 267was called on the file referenced by the descriptor. 268.It NOTE_WRITE 269A write occurred on the file referenced by the descriptor. 270.It NOTE_EXTEND 271The file referenced by the descriptor was extended. 272.It NOTE_ATTRIB 273The file referenced by the descriptor had its attributes changed. 274.It NOTE_LINK 275The link count on the file changed. 276.It NOTE_RENAME 277The file referenced by the descriptor was renamed. 278.El 279.Pp 280On return, 281.Va fflags 282contains the events which triggered the filter. 283.It EVFILT_PROC 284Takes the process ID to monitor as the identifier and the events to watch for 285in 286.Va fflags , 287and returns when the process performs one or more of the requested events. 288If a process can normally see another process, it can attach an event to it. 289The events to monitor are: 290.Bl -tag -width XXNOTE_TRACKERR 291.It NOTE_EXIT 292The process has exited. 293.It NOTE_FORK 294The process has called 295.Fn fork . 296.It NOTE_EXEC 297The process has executed a new process via 298.Xr execve 2 299or similar call. 300.It NOTE_TRACK 301Follow a process across 302.Fn fork 303calls. The parent process will return with NOTE_TRACK set in the 304.Va fflags 305field, while the child process will return with NOTE_CHILD set in 306.Va fflags 307and the parent PID in 308.Va data . 309.It NOTE_TRACKERR 310This flag is returned if the system was unable to attach an event to 311the child process, usually due to resource limitations. 312.El 313.Pp 314On return, 315.Va fflags 316contains the events which triggered the filter. 317.It EVFILT_SIGNAL 318Takes the signal number to monitor as the identifier and returns 319when the given signal is delivered to the process. 320This coexists with the 321.Fn signal 322and 323.Fn sigaction 324facilities, and has a lower precedence. The filter will record 325all attempts to deliver a signal to a process, even if the signal has 326been marked as SIG_IGN. Event notification happens after normal 327signal delivery processing. 328.Va data 329returns the number of times the signal has occurred since the last call to 330.Fn kqueue . 331This filter automatically sets the EV_CLEAR flag internally. 332.El 333.Sh RETURN VALUES 334.Fn kqueue 335creates a new kernel event queue and returns a file descriptor. 336If there was an error creating the kernel event queue, a value of -1 is 337returned and errno set. 338.Pp 339.Fn kevent 340returns the number of events placed in the 341.Fa eventlist , 342up to the value given by 343.Fa nevents . 344If an error occurs while processing an element of the 345.Fa changelist 346and there is enough room in the 347.Fa eventlist , 348then the event will be placed in the 349.Fa eventlist 350with 351.Dv EV_ERROR 352set in 353.Va flags 354and the system error in 355.Va data . 356Otherwise, 357.Dv -1 358will be returned, and 359.Dv errno 360will be set to indicate the error condition. 361If the time limit expires, then 362.Fn kevent 363returns 0. 364.Sh ERRORS 365The 366.Fn kqueue 367function fails if: 368.Bl -tag -width Er 369.It Bq Er ENOMEM 370The kernel failed to allocate enough memory for the kernel queue. 371.It Bq Er EMFILE 372The per-process descriptor table is full. 373.It Bq Er ENFILE 374The system file table is full. 375.El 376.Pp 377The 378.Fn kevent 379function fails if: 380.Bl -tag -width Er 381.It Bq Er EACCES 382The process does not have permission to register a filter. 383.It Bq Er EFAULT 384There was an error reading or writing the 385.Va kevent 386structure. 387.It Bq Er EBADF 388The specified descriptor is invalid. 389.It Bq Er EINTR 390A signal was delivered before the timeout expired and before any 391events were placed on the kqueue for return. 392.It Bq Er EINVAL 393The specified time limit or filter is invalid. 394.It Bq Er ENOENT 395The event could not be found to be modified or deleted. 396.It Bq Er ENOMEM 397No memory was available to register the event. 398.It Bq Er ESRCH 399The specified process to attach to does not exist. 400.El 401.Sh SEE ALSO 402.Xr aio_error 2 , 403.Xr aio_read 2 , 404.Xr aio_return 2 , 405.Xr poll 2 , 406.Xr read 2 , 407.Xr select 2 , 408.Xr sigaction 2 , 409.Xr write 2 , 410.Xr signal 3 411.Sh HISTORY 412The 413.Fn kqueue 414and 415.Fn kevent 416functions first appeared in 417.Fx 4.1 . 418.Sh AUTHORS 419The 420.Fn kqueue 421system and this manual page were written by 422.An Jonathan Lemon Aq [email protected] . 423.Sh BUGS 424It is currently not possible to watch a 425.Xr vnode 9 426that resides on anything but 427a UFS file system. 428