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.Dd July 27, 2026 26.Dt KQUEUE 2 27.Os 28.Sh NAME 29.Nm kqueue , 30.Nm kevent 31.Nd kernel event notification mechanism 32.Sh LIBRARY 33.Lb libc 34.Sh SYNOPSIS 35.In sys/event.h 36.Ft int 37.Fn kqueue "void" 38.Ft int 39.Fn kqueuex "u_int flags" 40.Ft int 41.Fn kqueue1 "int flags" 42.Ft int 43.Fo kevent 44.Fa "int kq" 45.Fa "const struct kevent *changelist" 46.Fa "int nchanges" 47.Fa "struct kevent *eventlist" 48.Fa "int nevents" 49.Fa "const struct timespec *timeout" 50.Fc 51.Fn EV_SET "kev" ident filter flags fflags data udata 52.Sh DESCRIPTION 53The 54.Fn kqueue 55system call 56provides a generic method of notifying the user when an event 57happens or a condition holds, based on the results of small 58pieces of kernel code termed filters. 59A kevent is identified by the (ident, filter) pair; there may only 60be one unique kevent per kqueue. 61.Pp 62The filter is executed upon the initial registration of a kevent 63in order to detect whether a preexisting condition is present, and is also 64executed whenever an event is passed to the filter for evaluation. 65If the filter determines that the condition should be reported, 66then the kevent is placed on the kqueue for the user to retrieve. 67.Pp 68The filter is also run when the user attempts to retrieve the kevent 69from the kqueue. 70If the filter indicates that the condition that triggered 71the event no longer holds, the kevent is removed from the kqueue and 72is not returned. 73.Pp 74Multiple events which trigger the filter do not result in multiple 75kevents being placed on the kqueue; instead, the filter will aggregate 76the events into a single struct kevent. 77Calling 78.Fn close 79on a file descriptor will remove any kevents that reference the descriptor. 80.Pp 81The 82.Fn kqueue 83system call 84creates a new kernel event queue and returns a descriptor. 85The queue is not inherited by a child created with 86.Xr fork 2 . 87However, if 88.Xr rfork 2 89is called without the 90.Dv RFFDG 91flag, then the descriptor table is shared, 92which will allow sharing of the kqueue between two processes. 93.Pp 94The 95.Fn kqueuex 96system call also creates a new kernel event queue, and additionally takes 97a 98.Fa flags 99argument, which is a bitwise-inclusive OR of the following flags: 100.Bl -tag -width "KQUEUE_CPONFORK" 101.It Dv KQUEUE_CLOEXEC 102The returned file descriptor is automatically closed on 103.Xr execve 2 104.It Dv KQUEUE_CPONFORK 105When this flag is set, the created kqueue is copied into 106the child process on 107.Xr fork 2 108calls. 109The kqueue descriptor index of the new kqueue will be inherited by the child, 110that is, the numeric value of the descriptor will remain the same. 111.Pp 112Copying is deep, that is, each registered event in the original kqueue is 113copied (and not shared) into the new kqueue. 114This is contrary to how other descriptor types are handled upon 115.Xr fork 2 , 116where the copied file descriptor references the same file object 117as the source descriptor (shallow copy). 118.Pp 119By default, in other words, when the flag is not set, kqueues from 120the parent are not copied on fork to the child process. 121The corresponding file descriptor indeces are unused in the child. 122.Pp 123Registered events that reference file descriptors which are not 124duplicated on fork, are not copied into the new kqueue. 125For instance, if the event references a file descriptor opened with the 126.Dv O_CLOEXEC 127flag set, it is not copied. 128Similarly, if event references a kqueue opened without the 129.Dv KQUEUE_CPONFORK 130flag, the event is not copied. 131.El 132.Pp 133The 134.Fn kqueue 135system call is equivalent to calling 136.Fn kqueuex 137with 138.Fa flags 139set to 0. 140.Pp 141The 142.Fn kqueue1 143function exists for compatibility with 144.Nx . 145The 146.Fa flags 147argument accepts zero or more of the following values: 148.Bl -tag -width O_CLOEXEC 149.It Dv O_CLOEXEC 150The returned file descriptor is automatically closed on 151.Xr execve 2 152.El 153.Pp 154The 155.Fn kevent 156system call 157is used to register events with the queue, and return any pending 158events to the user. 159The 160.Fa changelist 161argument 162is a pointer to an array of 163.Va kevent 164structures, as defined in 165.In sys/event.h . 166All changes contained in the 167.Fa changelist 168are applied before any pending events are read from the queue. 169The 170.Fa nchanges 171argument 172gives the size of 173.Fa changelist . 174The 175.Fa eventlist 176argument 177is a pointer to an array of kevent structures. 178The 179.Fa nevents 180argument 181determines the size of 182.Fa eventlist . 183When 184.Fa nevents 185is zero, 186.Fn kevent 187will return immediately even if there is a 188.Fa timeout 189specified unlike 190.Xr select 2 . 191If 192.Fa timeout 193is a non-NULL pointer, it specifies a maximum interval to wait 194for an event, which will be interpreted as a struct timespec. 195If 196.Fa timeout 197is a NULL pointer, 198.Fn kevent 199waits indefinitely. 200To effect a poll, the 201.Fa timeout 202argument should be non-NULL, pointing to a zero-valued 203.Va timespec 204structure. 205The same array may be used for the 206.Fa changelist 207and 208.Fa eventlist . 209.Pp 210The 211.Fn EV_SET 212macro is provided for ease of initializing a 213kevent structure. 214.Pp 215The 216.Va kevent 217structure is defined as: 218.Bd -literal 219struct kevent { 220 uintptr_t ident; /* identifier for this event */ 221 short filter; /* filter for event */ 222 u_short flags; /* action flags for kqueue */ 223 u_int fflags; /* filter flag value */ 224 int64_t data; /* filter data value */ 225 void *udata; /* opaque user data identifier */ 226 uint64_t ext[4]; /* extensions */ 227}; 228.Ed 229.Pp 230The fields of 231.Fa struct kevent 232are: 233.Bl -tag -width "Fa filter" 234.It Fa ident 235Value used to identify this event. 236The exact interpretation is determined by the attached filter, 237but often is a file descriptor. 238.It Fa filter 239Identifies the kernel filter used to process this event. 240The pre-defined 241system filters are described below. 242.It Fa flags 243Actions to perform on the event. 244.It Fa fflags 245Filter-specific flags. 246.It Fa data 247Filter-specific data value. 248.It Fa udata 249Opaque user-defined value passed through the kernel unchanged. 250.It Fa ext 251Extended data passed to and from kernel. 252The meaning of the 253.Fa ext[0] 254and 255.Fa ext[1] 256members is defined by the filter. 257If a filter does not use them, 258these members are passed through the kernel unchanged. 259The 260.Fa ext[2] 261and 262.Fa ext[3] 263members are always passed through the kernel unchanged, 264providing additional user-defined values. 265.El 266.Pp 267The 268.Va flags 269field can contain the following values: 270.Bl -tag -width EV_KEEPUDATA 271.It Dv EV_ADD 272Adds the event to the kqueue. 273Re-adding an existing event 274will modify the parameters of the original event, and not result 275in a duplicate entry. 276Adding an event automatically enables it, 277unless overridden by the EV_DISABLE flag. 278.It Dv EV_ENABLE 279Permit 280.Fn kevent 281to return the event if it is triggered. 282.It Dv EV_DISABLE 283Disable the event so 284.Fn kevent 285will not return it. 286The filter itself is not disabled. 287.It Dv EV_DISPATCH 288Disable the event source immediately after delivery of an event. 289See 290.Dv EV_DISABLE 291above. 292.It Dv EV_DELETE 293Removes the event from the kqueue. 294Events which are attached to 295file descriptors are automatically deleted on the last close of 296the descriptor. 297.It Dv EV_RECEIPT 298This flag is useful for making bulk changes to a kqueue without draining 299any pending events. 300When passed as input, it forces 301.Dv EV_ERROR 302to always be returned. 303When a filter is successfully added the 304.Va data 305field will be zero. 306Note that if this flag is encountered and there is no remaining space in 307.Fa eventlist 308to hold the 309.Dv EV_ERROR 310event, then subsequent changes will not get processed. 311.It Dv EV_ONESHOT 312Return only the first occurrence of the filter 313being triggered. 314After the user retrieves the event from the kqueue, 315it is deleted. 316.It Dv EV_CLEAR 317Reset the state of the event after it is retrieved by the user. 318This is useful for filters which report state transitions 319instead of the current state. 320Note that some filters may automatically 321set this flag internally. 322.It Dv EV_EOF 323Filters may set this flag to indicate filter-specific EOF condition. 324.It Dv EV_ERROR 325See 326.Sx RETURN VALUES 327below. 328.It Dv EV_KEEPUDATA 329Preserve the 330.Fa udata 331associated with an existing event. 332This allows other aspects of the event to be modified without requiring the 333caller to know the 334.Fa udata 335value previously registered with the event. 336This is especially useful with 337.Dv NOTE_TRIGGER 338or 339.Dv EV_ENABLE . 340This flag may not be used with 341.Dv EV_ADD . 342.El 343.Pp 344The predefined system filters are listed below. 345Arguments may be passed to and from the filter via the 346.Va fflags 347and 348.Va data 349fields in the kevent structure. 350.Bl -tag -width "Dv EVFILT_PROCDESC" 351.It Dv EVFILT_READ 352Takes a descriptor as the identifier, and returns whenever 353there is data available to read. 354The behavior of the filter is slightly different depending 355on the descriptor type. 356.Bl -tag -width 2n 357.It Sockets 358Sockets which have previously been passed to 359.Xr listen 2 360return when there is an incoming connection pending. 361.Va data 362contains the size of the listen backlog. 363.Pp 364Other socket descriptors return when there is data to be read, 365subject to the 366.Dv SO_RCVLOWAT 367value of the socket buffer. 368This may be overridden with a per-filter low water mark at the 369time the filter is added by setting the 370.Dv NOTE_LOWAT 371flag in 372.Va fflags , 373and specifying the new low water mark in 374.Va data . 375On return, 376.Va data 377contains the number of bytes of protocol data available to read. 378.Pp 379If the read direction of the socket has shutdown, then the filter 380also sets 381.Dv EV_EOF 382in 383.Va flags , 384and returns the socket error (if any) in 385.Va fflags . 386It is possible for EOF to be returned (indicating the connection is gone) 387while there is still data pending in the socket buffer. 388.It Vnodes 389Returns when the file pointer is not at the end of file. 390.Va data 391contains the offset from current position to end of file, 392and may be negative. 393.Pp 394This behavior is different from 395.Xr poll 2 , 396where read events are triggered for regular files unconditionally. 397This event can be triggered unconditionally by setting the 398.Dv NOTE_FILE_POLL 399flag in 400.Va fflags . 401.It "Fifos, Pipes" 402Returns when the there is data to read; 403.Va data 404contains the number of bytes available. 405.Pp 406When the last writer disconnects, the filter will set 407.Dv EV_EOF 408in 409.Va flags . 410This will be cleared by the filter when a new writer connects, 411at which point the 412filter will resume waiting for data to become available before 413returning. 414.It "BPF devices" 415Returns when the BPF buffer is full, the BPF timeout has expired, or 416when the BPF has 417.Dq immediate mode 418enabled and there is any data to read; 419.Va data 420contains the number of bytes available. 421.It Eventfds 422Returns when the counter is greater than 0; 423.Va data 424contains the counter value, which must be cast to 425.Vt uint64_t . 426.It Kqueues 427Returns when pending events are present on the queue; 428.Va data 429contains the number of events available. 430.El 431.It Dv EVFILT_WRITE 432Takes a descriptor as the identifier, and returns whenever 433it is possible to write to the descriptor. 434For sockets, pipes 435and fifos, 436.Va data 437will contain the amount of space remaining in the write buffer. 438The filter will set 439.Dv EV_EOF 440when the reader disconnects, and for the fifo case, this will be cleared 441when a new reader connects. 442Note that this filter is not supported for vnodes. 443.Pp 444For sockets, the low water mark and socket error handling is 445identical to the 446.Dv EVFILT_READ 447case. 448.Pp 449For eventfds, 450.Va data 451will contain the maximum value that can be added to the counter 452without blocking. 453.Pp 454For BPF devices, when the descriptor is attached to an interface the filter 455always indicates that it is possible to write and 456.Va data 457will contain the MTU size of the underlying interface. 458.It Dv EVFILT_EMPTY 459Takes a descriptor as the identifier, and returns whenever 460there is no remaining data in the write buffer. 461.It Dv EVFILT_AIO 462Events for this filter are not registered with 463.Fn kevent 464directly but are registered via the 465.Va aio_sigevent 466member of an asynchronous I/O request when it is scheduled via an 467asynchronous I/O system call such as 468.Fn aio_read . 469The filter returns under the same conditions as 470.Fn aio_error . 471For more details on this filter see 472.Xr sigevent 3 and 473.Xr aio 4 . 474.It Dv EVFILT_VNODE 475Takes a file descriptor as the identifier and the events to watch for in 476.Va fflags , 477and returns when one or more of the requested events occurs on the descriptor. 478The events to monitor are: 479.Bl -tag -width "Dv NOTE_CLOSE_WRITE" 480.It Dv NOTE_ATTRIB 481The file referenced by the descriptor had its attributes changed. 482.It Dv NOTE_CLOSE 483A file descriptor referencing the monitored file, was closed. 484The closed file descriptor did not have write access. 485.It Dv NOTE_CLOSE_WRITE 486A file descriptor referencing the monitored file, was closed. 487The closed file descriptor had write access. 488.Pp 489This note, as well as 490.Dv NOTE_CLOSE , 491are not activated when files are closed forcibly by 492.Xr unmount 2 or 493.Xr revoke 2 . 494Instead, 495.Dv NOTE_REVOKE 496is sent for such events. 497.It Dv NOTE_DELETE 498The 499.Fn unlink 500system call was called on the file referenced by the descriptor. 501.It Dv NOTE_EXTEND 502For regular file, the file referenced by the descriptor was extended. 503.Pp 504For directory, reports that a directory entry was added or removed, 505as the result of rename operation. 506The 507.Dv NOTE_EXTEND 508event is not reported when a name is changed inside the directory. 509.It Dv NOTE_LINK 510The link count on the file changed. 511In particular, the 512.Dv NOTE_LINK 513event is reported if a subdirectory was created or deleted inside 514the directory referenced by the descriptor. 515.It Dv NOTE_OPEN 516The file referenced by the descriptor was opened. 517.It Dv NOTE_READ 518A read occurred on the file referenced by the descriptor. 519.It Dv NOTE_RENAME 520The file referenced by the descriptor was renamed. 521.It Dv NOTE_REVOKE 522Access to the file was revoked via 523.Xr revoke 2 524or the underlying file system was unmounted. 525.It Dv NOTE_WRITE 526A write occurred on the file referenced by the descriptor. 527.El 528.Pp 529On return, 530.Va fflags 531contains the events which triggered the filter. 532.It Dv EVFILT_PROC 533Takes the process ID to monitor as the identifier and the events to watch for 534in 535.Va fflags , 536and returns when the process performs one or more of the requested events. 537If a process can normally see another process, it can attach an event to it. 538The events to monitor are: 539.Bl -tag -width "Dv NOTE_TRACKERR" 540.It Dv NOTE_EXIT 541The process has exited. 542The exit status will be stored in 543.Va data 544in the same format as the status returned by 545.Xr wait 2 . 546.It Dv NOTE_REAP 547The process has been reaped by a call to the 548.Xr wait 2 549family of functions. 550.It Dv NOTE_FORK 551The process has called 552.Xr fork 2 553or 554.Xr vfork 2 . 555.It Dv NOTE_EXEC 556The process has executed a new process via 557.Xr execve 2 558or a similar call. 559.It Dv NOTE_TRACK 560Follow a process across 561.Fn fork 562calls. 563The parent process registers a new kevent to monitor the child process 564using the same 565.Va fflags 566as the original event. 567The child process will signal an event with 568.Dv NOTE_CHILD 569set in 570.Va fflags 571and the parent PID in 572.Va data . 573.Pp 574If the parent process fails to register a new kevent 575.Pq usually due to resource limitations , 576it will signal an event with 577.Dv NOTE_TRACKERR 578set in 579.Va fflags , 580and the child process will not signal a 581.Dv NOTE_CHILD 582event. 583.El 584.Pp 585On return, 586.Va fflags 587contains the events which triggered the filter. 588.It Dv EVFILT_PROCDESC 589Takes the process descriptor created by 590.Xr pdfork 2 591to monitor as the identifier and the events to watch for in 592.Va fflags , 593and returns when the associated process performs one or more of the 594requested events. 595The events to monitor are: 596.Bl -tag -width "Dv NOTE_PDSIGCHLD" 597.It Dv NOTE_EXIT 598The process has exited. 599The exit status will be stored in 600.Va data . 601.It Dv NOTE_FORK 602The process has forked. 603The process identifier 604.Pq PID 605of the most recently forked child is returned in the 606.Va data 607field. 608.Pp 609The identifier is advisory; 610if several children were spawned before the event is returned, 611only one of the PIDs is returned. 612Other mechanisms provide reliable reporting of fork events. 613For instance, debugging the process with a subscription for relevant 614events would serialize forks. 615See 616.Xr ptrace 2 617and the description of the 618.Dv PT_FOLLOW_FORK 619request. 620.Pp 621Unlike the 622.Dv EVFILT_PROC 623filter, 624the 625.Dv NOTE_TRACK 626pseudo-event is not supported. 627.Pp 628If both 629.Dv NOTE_EXIT 630and 631.Dv NOTE_FORK 632events are reported, then the 633.Va data 634field contains the exit status of the process, 635and the last child's PID is not returned. 636.It Dv NOTE_PDSIGCHLD 637Activates on events that are reported through 638.Xr pdwait 2 639on the process descriptor. 640After the event is reported, the 641.Xr pdwait 2 642can be called to obtain the information about the process 643status change. 644.El 645.Pp 646On return, 647.Va fflags 648contains the events which triggered the filter. 649.It Dv EVFILT_SIGNAL 650Takes the signal number to monitor as the identifier and returns 651when the given signal is delivered to the process. 652This coexists with the 653.Fn signal 654and 655.Fn sigaction 656facilities, and has a lower precedence. 657The filter will record 658all attempts to deliver a signal to a process, even if the signal has 659been marked as 660.Dv SIG_IGN , 661except for the 662.Dv SIGCHLD 663signal, which, if ignored, will not be recorded by the filter. 664Event notification happens before normal 665signal delivery processing. 666.Va data 667returns the number of times the signal has occurred since the last call to 668.Fn kevent . 669This filter automatically sets the 670.Dv EV_CLEAR 671flag internally. 672.It Dv EVFILT_JAIL 673Takes the jail ID to monitor as the identifier and the events to watch for 674in 675.Va fflags , 676and returns when the jail performs one or more of the requested events. 677If a process can normally see a jail, it can attach an event to it. 678An identifier of zero will watch the process's own jail. 679The events to monitor are: 680.Bl -tag -width "Dv NOTE_JAIL_ATTACH" 681.It Dv NOTE_JAIL_SET 682The jail has been changed via 683.Xr jail_set 2 . 684.It Dv NOTE_JAIL_ATTACH 685A process has attached to the jail via 686.Xr jail_attach 2 687or a similar call. 688The process ID will be stored in 689.Va data . 690If more than one process has attached since the last call to 691.Fn kevent , 692.Va data 693will be zero. 694.It Dv NOTE_JAIL_REMOVE 695The jail has been removed. 696.It Dv NOTE_JAIL_CHILD 697A child of the watched jail has been created. 698Its jail ID will be stored in 699.Va data . 700If more than one jail has been created since the last call to 701.Fn kevent , 702.Va data 703will be zero. 704.El 705.Pp 706On return, 707.Va fflags 708contains the events which triggered the filter. 709It will also contain 710.Dv NOTE_JAIL_MULTI 711if more than one 712.Dv NOTE_JAIL_ATTACH 713or 714.Dv NOTE_JAIL_CHILD 715event has been received since the last call to 716.Fn kevent . 717.It Dv EVFILT_JAILDESC 718Takes a jail descriptor returned by 719.Xr jail_set 2 720or 721.Xr jail_get 2 722as the identifier and the events to watch for in 723.Va fflags , 724and returns when the jail performs one or more of the requested events. 725The events to monitor and the resulting 726.Va fflags 727are the same as those listed in 728.Dv EVFILT_JAIL , 729above. 730.It Dv EVFILT_TIMER 731Establishes an arbitrary timer identified by 732.Va ident . 733When adding a timer, 734.Va data 735specifies the moment to fire the timer (for 736.Dv NOTE_ABSTIME ) 737or the timeout period. 738The timer will be periodic unless 739.Dv EV_ONESHOT 740or 741.Dv NOTE_ABSTIME 742is specified. 743On return, 744.Va data 745contains the number of times the timeout has expired since the last call to 746.Fn kevent . 747For non-monotonic timers, this filter automatically sets the 748.Dv EV_CLEAR 749flag internally. 750.Pp 751The filter accepts the following flags in the 752.Va fflags 753argument: 754.Bl -tag -width "Dv NOTE_MSECONDS" 755.It Dv NOTE_SECONDS 756.Va data 757is in seconds. 758.It Dv NOTE_MSECONDS 759.Va data 760is in milliseconds. 761.It Dv NOTE_USECONDS 762.Va data 763is in microseconds. 764.It Dv NOTE_NSECONDS 765.Va data 766is in nanoseconds. 767.It Dv NOTE_ABSTIME 768The specified expiration time is absolute. 769.El 770.Pp 771If 772.Va fflags 773is not set, the default is milliseconds. 774On return, 775.Va fflags 776contains the events which triggered the filter. 777.Pp 778Periodic timers with a specified timeout of 0 will be silently adjusted to 779timeout after 1 of the time units specified by the requested precision in 780.Va fflags . 781If an absolute time is specified that has already passed, then it is treated as 782if the current time were specified and the event will fire as soon as possible. 783.Pp 784If an existing timer is re-added, the existing timer will be 785effectively canceled (throwing away any undelivered record of previous 786timer expiration) and re-started using the new parameters contained in 787.Va data 788and 789.Va fflags . 790.Pp 791There is a system wide limit on the number of timers 792which is controlled by the 793.Va kern.kq_calloutmax 794sysctl. 795.It Dv EVFILT_USER 796Establishes a user event identified by 797.Va ident 798which is not associated with any kernel mechanism but is triggered by 799user level code. 800The lower 24 bits of the 801.Va fflags 802may be used for user defined flags and manipulated using the following: 803.Bl -tag -width "Dv NOTE_FFLAGSMASK" 804.It Dv NOTE_FFNOP 805Ignore the input 806.Va fflags . 807.It Dv NOTE_FFAND 808Bitwise AND 809.Va fflags . 810.It Dv NOTE_FFOR 811Bitwise OR 812.Va fflags . 813.It Dv NOTE_FFCOPY 814Copy 815.Va fflags . 816.It Dv NOTE_FFCTRLMASK 817Control mask for 818.Va fflags . 819.It Dv NOTE_FFLAGSMASK 820User defined flag mask for 821.Va fflags . 822.El 823.Pp 824A user event is triggered for output with the following: 825.Bl -tag -width "Dv NOTE_FFLAGSMASK" 826.It Dv NOTE_TRIGGER 827Cause the event to be triggered. 828.El 829.Pp 830On return, 831.Va fflags 832contains the users defined flags in the lower 24 bits. 833.El 834.Sh CANCELLATION BEHAVIOUR 835If 836.Fa nevents 837is non-zero, i.e., the function is potentially blocking, the call 838is a cancellation point. 839Otherwise, i.e., if 840.Fa nevents 841is zero, the call is not cancellable. 842Cancellation can only occur before any changes are made to the kqueue, 843or when the call was blocked and no changes to the queue were requested. 844.Sh RETURN VALUES 845The 846.Fn kqueue 847system call 848creates a new kernel event queue and returns a file descriptor. 849If there was an error creating the kernel event queue, a value of -1 is 850returned and errno set. 851.Pp 852The 853.Fn kevent 854system call 855returns the number of events placed in the 856.Fa eventlist , 857up to the value given by 858.Fa nevents . 859If an error occurs while processing an element of the 860.Fa changelist 861and there is enough room in the 862.Fa eventlist , 863then the event will be placed in the 864.Fa eventlist 865with 866.Dv EV_ERROR 867set in 868.Va flags 869and the system error in 870.Va data . 871Otherwise, 872.Dv -1 873will be returned, and 874.Dv errno 875will be set to indicate the error condition. 876If the time limit expires, then 877.Fn kevent 878returns 0. 879.Sh EXAMPLES 880.Bd -literal -compact 881#include <sys/event.h> 882#include <err.h> 883#include <fcntl.h> 884#include <stdio.h> 885#include <stdlib.h> 886#include <string.h> 887 888int 889main(int argc, char **argv) 890{ 891 struct kevent event; /* Event we want to monitor */ 892 struct kevent tevent; /* Event triggered */ 893 int kq, fd, ret; 894 895 if (argc != 2) 896 err(EXIT_FAILURE, "Usage: %s path\en", argv[0]); 897 fd = open(argv[1], O_RDONLY); 898 if (fd == -1) 899 err(EXIT_FAILURE, "Failed to open '%s'", argv[1]); 900 901 /* Create kqueue. */ 902 kq = kqueue(); 903 if (kq == -1) 904 err(EXIT_FAILURE, "kqueue() failed"); 905 906 /* Initialize kevent structure. */ 907 EV_SET(&event, fd, EVFILT_VNODE, EV_ADD | EV_CLEAR, NOTE_WRITE, 908 0, NULL); 909 /* Attach event to the kqueue. */ 910 ret = kevent(kq, &event, 1, NULL, 0, NULL); 911 if (ret == -1) 912 err(EXIT_FAILURE, "kevent register"); 913 914 for (;;) { 915 /* Sleep until something happens. */ 916 ret = kevent(kq, NULL, 0, &tevent, 1, NULL); 917 if (ret == -1) { 918 err(EXIT_FAILURE, "kevent wait"); 919 } else if (ret > 0) { 920 if (tevent.flags & EV_ERROR) 921 errx(EXIT_FAILURE, "Event error: %s", strerror(event.data)); 922 else 923 printf("Something was written in '%s'\en", argv[1]); 924 } 925 } 926 927 /* kqueues are destroyed upon close() */ 928 (void)close(kq); 929 (void)close(fd); 930} 931.Ed 932.Sh ERRORS 933The 934.Fn kqueue 935system call fails if: 936.Bl -tag -width Er 937.It Bq Er ENOMEM 938The kernel failed to allocate enough memory for the kernel queue. 939.It Bq Er ENOMEM 940The 941.Dv RLIMIT_KQUEUES 942rlimit 943(see 944.Xr getrlimit 2 ) 945for the current user would be exceeded. 946.It Bq Er EMFILE 947The per-process descriptor table is full. 948.It Bq Er ENFILE 949The system file table is full. 950.El 951.Pp 952The 953.Fn kevent 954system call fails if: 955.Bl -tag -width Er 956.It Bq Er EACCES 957The process does not have permission to register a filter. 958.It Bq Er EFAULT 959There was an error reading or writing the 960.Va kevent 961structure. 962.It Bq Er EBADF 963The specified descriptor is invalid. 964.It Bq Er EINTR 965A signal was delivered before the timeout expired and before any 966events were placed on the kqueue for return. 967.It Bq Er EINTR 968A cancellation request was delivered to the thread, but not yet handled. 969.It Bq Er EINVAL 970The specified time limit or filter is invalid. 971.It Bq Er EINVAL 972The specified length of the event or change lists is negative. 973.It Bq Er ENOENT 974The event could not be found to be modified or deleted. 975.It Bq Er ENOMEM 976No memory was available to register the event 977or, in the special case of a timer, the maximum number of 978timers has been exceeded. 979This maximum is configurable via the 980.Va kern.kq_calloutmax 981sysctl. 982.It Bq Er ESRCH 983The specified process to attach to does not exist. 984.El 985.Pp 986When 987.Fn kevent 988call fails with 989.Er EINTR 990error, all changes in the 991.Fa changelist 992have been applied. 993.Sh SEE ALSO 994.Xr aio_error 2 , 995.Xr aio_read 2 , 996.Xr aio_return 2 , 997.Xr poll 2 , 998.Xr read 2 , 999.Xr select 2 , 1000.Xr sigaction 2 , 1001.Xr write 2 , 1002.Xr pthread_setcancelstate 3 , 1003.Xr signal 3 1004.Rs 1005.%A Jonathan Lemon 1006.%T "Kqueue: A Generic and Scalable Event Notification Facility" 1007.%I USENIX Association 1008.%B Proceedings of the FREENIX Track: 2001 USENIX Annual Technical Conference 1009.%D June 25-30, 2001 1010.\".http://www.usenix.org/event/usenix01/freenix01/full_papers/lemon/lemon.pdf 1011.Re 1012.Sh HISTORY 1013The 1014.Fn kqueue 1015and 1016.Fn kevent 1017system calls first appeared in 1018.Fx 4.1 . 1019The 1020.Fn kqueuex 1021system call 1022and 1023.Fn kqueue1 1024function first appeared in 1025.Fx 14.0 . 1026.Sh AUTHORS 1027The 1028.Em kqueue 1029subsystem and this manual page were written by 1030.An Jonathan Lemon Aq Mt jlemon@FreeBSD.org . 1031.Sh BUGS 1032.Pp 1033In versions older than 1034.Fx 12.0 , 1035.In sys/event.h 1036failed to parse without including 1037.In sys/types.h 1038manually. 1039