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 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 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.El 220.Bl -tag 221.It Vnodes 222Returns when the file pointer is not at the end of file. 223.Va data 224contains the offset from current position to end of file, 225and may be negative. 226.El 227.Bl -tag 228.It Fifos, Pipes 229Returns when the there is data to read; 230.Va data 231contains the number of bytes available. 232.Pp 233When the last writer disconnects, the filter will set EV_EOF in 234.Va flags . 235This may be cleared by passing in EV_CLEAR, at which point the 236filter will resume waiting for data to become available before 237returning. 238.El 239.El 240.Bl -tag 241.It EVFILT_WRITE 242Takes a descriptor as the identifier, and returns whenever 243it is possible to write to the descriptor. For sockets, pipes 244and fifos, 245.Va data 246will contain the amount of space remaining in the write buffer. 247The filter will set EV_EOF when the reader disconnects, and for 248the fifo case, this may be cleared by use of EV_CLEAR. 249Note that this filter is not supported for vnodes. 250.El 251.Bl -tag 252.It EVFILT_AIO 253A kevent structure is initialized, with 254.Va ident 255containing the descriptor of the kqueue that the event should be 256attached to. The address of the kevent structure is then placed in the 257.Va aio_lio_opcode 258field of the AIO request, and the aio_* function is then called. 259The event will be registered with the specified kqueue, and the 260.Va ident 261argument set to the 262.Fa struct aiocb 263returned by the aio_* function. 264The filter returns under the same conditions as aio_error. 265.Pp 266NOTE: this interface is unstable and subject to change. 267.El 268.Bl -tag 269.It EVFILT_VNODE 270Takes a file descriptor as the identifier and the events to watch for in 271.Va fflags , 272and returns when one or more of the requested events occurs on the descriptor. 273The events to monitor are: 274.Bl -tag -width XXNOTE_RENAME 275.It NOTE_DELETE 276.Fn unlink 277was called on the file referenced by the descriptor. 278.It NOTE_WRITE 279A write occurred on the file referenced by the descriptor. 280.It NOTE_EXTEND 281The file referenced by the descriptor was extended. 282.It NOTE_ATTRIB 283The file referenced by the descriptor had its attributes changed. 284.It NOTE_LINK 285The link count on the file changed. 286.It NOTE_RENAME 287The file referenced by the descriptor was renamed. 288.El 289.Pp 290On return, 291.Va fflags 292contains the events which triggered the filter. 293.El 294.Bl -tag 295.It EVFILT_PROC 296Takes the process ID to monitor as the identifier and the events to watch for 297in 298.Va fflags , 299and returns when the process performs one or more of the requested events. 300If a process can normally see another process, it can attach an event to it. 301The events to monitor are: 302.Bl -tag -width XXNOTE_TRACKERR 303.It NOTE_EXIT 304The process has exited. 305.It NOTE_FORK 306The process has called 307.Fn fork . 308.It NOTE_EXEC 309The process has executed a new process via 310.Xr execve 2 311or similar call. 312.It NOTE_TRACK 313Follow a process across 314.Fn fork 315calls. The parent process will return with NOTE_TRACK set in the 316.Va fflags 317field, while the child process will return with NOTE_CHILD set in 318.Va fflags 319and the parent PID in 320.Va data . 321.It NOTE_TRACKERR 322This flag is returned if the system was unable to attach an event to 323the child process, usually due to resource limitations. 324.El 325.Pp 326On return, 327.Va fflags 328contains the events which triggered the filter. 329.It EVFILT_SIGNAL 330Takes the signal number to monitor as the identifier and returns 331when the given signal is delivered to the process. 332This coexists with the 333.Fn signal 334and 335.Fn sigaction 336facilities, and has a lower precedence. The filter will record 337all attempts to deliver a signal to a process, even if the signal has 338been marked as SIG_IGN. Event notification happens after normal 339signal delivery processing. 340.Va data 341returns the number of times the signal has occurred since the last call to 342.Fn kqueue . 343This filter automatically sets the EV_CLEAR flag internally. 344.El 345.Sh RETURN VALUES 346.Fn kqueue 347creates a new kernel event queue and returns a file descriptor. 348If there was an error creating the kernel event queue, a value of -1 is 349returned and errno set. 350.Pp 351.Fn kevent 352returns the number of events placed in the 353.Fa eventlist , 354up to the value given by 355.Fa nevents . 356If an error occurs while processing an element of the 357.Fa changelist 358and there is enough room in the 359.Fa eventlist , 360then the event will be placed in the 361.Fa eventlist 362with 363.Dv EV_ERROR 364set in 365.Va flags 366and the system error in 367.Va data . 368Otherwise, 369.Dv -1 370will be returned, and 371.Dv errno 372will be set to indicate the error condition. 373If the time limit expires, then 374.Fn kevent 375returns 0. 376.Sh ERRORS 377The 378.Fn kqueue 379function fails if: 380.Bl -tag -width Er 381.It Bq Er ENOMEM 382The kernel failed to allocate enough memory for the kernel queue. 383.It Bq Er EMFILE 384The per-process descriptor table is full. 385.It Bq Er ENFILE 386The system file table is full. 387.El 388.Pp 389The 390.Fn kevent 391function fails if: 392.Bl -tag -width Er 393.It Bq Er EACCES 394The process does not have permission to register a filter. 395.It Bq Er EFAULT 396There was an error reading or writing the 397.Va kevent 398structure. 399.It Bq Er EBADF 400The specified descriptor is invalid. 401.It Bq Er EINTR 402A signal was delivered before the timeout expired and before any 403events were placed on the kqueue for return. 404.It Bq Er EINVAL 405The specified time limit or filter is invalid. 406.It Bq Er ENOENT 407The event could not be found to be modified or deleted. 408.It Bq Er ENOMEM 409No memory was available to register the event. 410.It Bq Er ESRCH 411The specified process to attach to does not exist. 412.El 413.Sh SEE ALSO 414.Xr aio_error 2 , 415.Xr aio_read 2 , 416.Xr aio_return 2 , 417.Xr poll 2 , 418.Xr read 2 , 419.Xr select 2 , 420.Xr sigaction 2 , 421.Xr write 2 , 422.Xr signal 3 423.Sh HISTORY 424The 425.Fn kqueue 426and 427.Fn kevent 428functions first appeared in 429.Fx 4.1 . 430.Sh AUTHORS 431The 432.Fn kqueue 433system and this manual page were written by 434.An Jonathan Lemon Aq [email protected] . 435.Sh BUGS 436It is currently not possible to watch a 437.Xr vnode 9 438that resides on anything but 439a UFS file system. 440