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 with the 77.Dv RFFDG 78flag, 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. 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. 112.Pp 113The 114.Va kevent 115structure is defined as: 116.Bd -literal 117struct kevent { 118 uintptr_t ident; /* identifier for this event */ 119 short filter; /* filter for event */ 120 u_short flags; /* action flags for kqueue */ 121 u_int fflags; /* filter flag value */ 122 intptr_t data; /* filter data value */ 123 void *udata; /* opaque user data identifier */ 124}; 125.Ed 126.Pp 127The fields of 128.Fa struct kevent 129are: 130.Bl -tag -width XXXfilter 131.It ident 132Value used to identify this event. 133The exact interpretation is determined by the attached filter, 134but often is a file descriptor. 135.It filter 136Identifies the kernel filter used to process this event. The pre-defined 137system filters are described below. 138.It flags 139Actions to perform on the event. 140.It fflags 141Filter-specific flags. 142.It data 143Filter-specific data value. 144.It udata 145Opaque user-defined value passed through the kernel unchanged. 146.El 147.Pp 148The 149.Va flags 150field can contain the following values: 151.Bl -tag -width XXXEV_ONESHOT 152.It EV_ADD 153Adds the event to the kqueue. Re-adding an existing event 154will modify the parameters of the original event, and not result 155in a duplicate entry. Adding an event automatically enables it, 156unless overridden by the EV_DISABLE flag. 157.It EV_ENABLE 158Permit 159.Fn kevent 160to return the event if it is triggered. 161.It EV_DISABLE 162Disable the event so 163.Fn kevent 164will not return it. The filter itself is not disabled. 165.It EV_DELETE 166Removes the event from the kqueue. Events which are attached to 167file descriptors are automatically deleted on the last close of 168the descriptor. 169.It EV_ONESHOT 170Causes the event to return only the first occurrence of the filter 171being triggered. After the user retrieves the event from the kqueue, 172it is deleted. 173.It EV_CLEAR 174After the event is retrieved by the user, its state is reset. 175This is useful for filters which report state transitions 176instead of the current state. Note that some filters may automatically 177set this flag internally. 178.It EV_EOF 179Filters may set this flag to indicate filter-specific EOF condition. 180.It EV_ERROR 181See 182.Sx RETURN VALUES 183below. 184.El 185.Pp 186The predefined system filters are listed below. 187Arguments may be passed to and from the filter via the 188.Va fflags 189and 190.Va data 191fields in the kevent structure. 192.Bl -tag 193.It EVFILT_READ 194Takes a descriptor as the identifier, and returns whenever 195there is data available to read. 196The behavior of the filter is slightly different depending 197on the descriptor type. 198.Bl -tag 199.It Sockets 200Sockets which have previously been passed to 201.Fn listen 202return when there is an incoming connection pending. 203.Va data 204contains the size of the listen backlog. 205.Pp 206Other socket descriptors return when there is data to be read, 207subject to the SO_RCVLOWAT value of the socket buffer. 208.Va data 209contains the number of bytes in the socket buffer. 210.Pp 211If the read direction of the socket has shutdown, then the filter 212also sets EV_EOF in 213.Va flags . 214It is possible for EOF to be returned (indicating the connection is gone) 215while there is still data pending in the socket buffer. 216.El 217.Bl -tag 218.It Vnodes 219Returns when the file pointer is not at the end of file. 220.Va data 221contains the offset from current position to end of file, 222and may be negative. 223.El 224.Bl -tag 225.It Fifos, Pipes 226Returns when the there is data to read; 227.Va data 228contains the number of bytes available. 229.Pp 230When the last writer disconnects, the filter will set EV_EOF in 231.Va flags . 232This may be cleared by passing in EV_CLEAR, at which point the 233filter will resume waiting for data to become available before 234returning. 235.El 236.El 237.Bl -tag 238.It EVFILT_WRITE 239Takes a descriptor as the identifier, and returns whenever 240it is possible to write to the descriptor. For sockets, pipes 241and fifos, 242.Va data 243will contain the amount of space remaining in the write buffer. 244The filter will set EV_EOF when the reader disconnects, and for 245the fifo case, this may be cleared by use of EV_CLEAR. 246Note that this filter is not supported for vnodes. 247.El 248.Bl -tag 249.It EVFILT_AIO 250A kevent structure is initialized, with 251.Va ident 252containing the descriptor of the kqueue that the event should be 253attached to. The address of the kevent structure is then placed in the 254.Va aio_lio_opcode 255field of the AIO request, and the aio_* function is then called. 256The event will be registered with the specified kqueue, and the 257.Va ident 258argument set to the 259.Fa struct aiocb 260returned by the aio_* function. 261The filter returns under the same conditions as aio_error. 262.Pp 263NOTE: this interface is unstable and subject to change. 264.El 265.Bl -tag 266.It EVFILT_VNODE 267Takes a file descriptor as the identifier and the events to watch for in 268.Va fflags , 269and returns when one or more of the requested events occurs on the descriptor. 270The events to monitor are: 271.Bl -tag -width XXNOTE_RENAME 272.It NOTE_DELETE 273.Fn unlink 274was called on the file referenced by the descriptor. 275.It NOTE_WRITE 276A write occurred on the file referenced by the descriptor. 277.It NOTE_EXTEND 278The file referenced by the descriptor was extended. 279.It NOTE_ATTRIB 280The file referenced by the descriptor had its attributes changed. 281.It NOTE_LINK 282The link count on the file changed. 283.It NOTE_RENAME 284The file referenced by the descriptor was renamed. 285.El 286.Pp 287On return, 288.Va fflags 289contains the events which triggered the filter. 290.El 291.Bl -tag 292.It EVFILT_PROC 293Takes the process ID to monitor as the identifier and the events to watch for 294in 295.Va fflags , 296and returns when the process performs one or more of the requested events. 297If a process can normally see another process, it can attach an event to it. 298The events to monitor are: 299.Bl -tag -width XXNOTE_TRACKERR 300.It NOTE_EXIT 301The process has exited. 302.It NOTE_FORK 303The process has called 304.Fn fork . 305.It NOTE_EXEC 306The process has executed a new process via 307.Xr execve 2 308or similar call. 309.It NOTE_TRACK 310Follow a process across 311.Fn fork 312calls. The parent process will return with NOTE_TRACK set in the 313.Va fflags 314field, while the child process will return with NOTE_CHILD set in 315.Va fflags 316and the parent PID in 317.Va data . 318.It NOTE_TRACKERR 319This flag is returned if the system was unable to attach an event to 320the child process, usually due to resource limitations. 321.El 322.Pp 323On return, 324.Va fflags 325contains the events which triggered the filter. 326.It EVFILT_SIGNAL 327Takes the signal number to monitor as the identifier and returns 328when the given signal is delivered to the process. 329This coexists with the 330.Fn signal 331and 332.Fn sigaction 333facilities, and has a lower precedence. The filter will record 334all attempts to deliver a signal to a process, even if the signal has 335been marked as SIG_IGN. Event notification happens after normal 336signal delivery processing. 337.Va data 338returns the number of times the signal has occurred since the last call to 339.Fn kqueue . 340This filter automatically sets the EV_CLEAR flag internally. 341.El 342.Sh RETURN VALUES 343.Fn kqueue 344creates a new kernel event queue and returns a file descriptor. 345If there was an error creating the kernel event queue, a value of -1 is 346returned and errno set. 347.Pp 348.Fn kevent 349returns the number of events placed in the 350.Fa eventlist , 351up to the value given by 352.Fa nevents . 353If an error occurs while processing an element of the 354.Fa changelist 355and there is enough room in the 356.Fa eventlist , 357then the event will be placed in the 358.Fa eventlist 359with 360.Dv EV_ERROR 361set in 362.Va flags 363and the system error in 364.Va data . 365Otherwise, 366.Dv -1 367will be returned, and 368.Dv errno 369will be set to indicate the error condition. 370If the time limit expires, then 371.Fn kevent 372returns 0. 373.Sh ERRORS 374The 375.Fn kqueue 376function fails if: 377.Bl -tag -width Er 378.It Bq Er ENOMEM 379The kernel failed to allocate enough memory for the kernel queue. 380.It Bq Er EMFILE 381The per-process descriptor table is full. 382.It Bq Er ENFILE 383The system file table is full. 384.El 385.Pp 386The 387.Fn kevent 388function fails if: 389.Bl -tag -width Er 390.It Bq Er EACCESS 391The process does not have permission to register a filter. 392.It Bq Er EFAULT 393There was an error reading or writing the 394.Va kevent 395structure. 396.It Bq Er EBADF 397The specified descriptor is invalid. 398.It Bq Er EINTR 399A signal was delivered before the timeout expired and before any 400events were placed on the kqueue for return. 401.It Bq Er EINVAL 402The specified time limit or filter is invalid. 403.It Bq Er ENOENT 404The event could not be found to be modified or deleted. 405.It Bq Er ENOMEM 406No memory was available to register the event. 407.It Bq Er ESRCH 408The specified process to attach to does not exist. 409.El 410.Sh SEE ALSO 411.Xr aio_error 2 , 412.Xr aio_read 2 , 413.Xr aio_return 2 , 414.Xr poll 2 , 415.Xr read 2 , 416.Xr select 2 , 417.Xr sigaction 2 , 418.Xr write 2 , 419.Xr signal 3 420.Sh HISTORY 421The 422.Fn kqueue 423and 424.Fn kevent 425functions first appeared in 426.Fx 4.1 . 427.Sh AUTHORS 428The 429.Fn kqueue 430system and this manual page were written by 431.An Jonathan Lemon Aq [email protected] . 432.Sh BUGS 433It is currently not possible to watch a 434.Xr vnode 9 435that resides on anything but 436a UFS file system. 437