| kqueue.2 (131365) | kqueue.2 (131504) |
|---|---|
| 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. --- 8 unchanged lines hidden (view full) --- 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.\" | 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. --- 8 unchanged lines hidden (view full) --- 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: head/lib/libc/sys/kqueue.2 131365 2004-06-30 20:09:10Z ru $ | 25.\" $FreeBSD: head/lib/libc/sys/kqueue.2 131504 2004-07-02 23:52:20Z ru $ |
| 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 --- 85 unchanged lines hidden (view full) --- 119.Fn kevent 120will return immediately even if there is a 121.Fa timeout 122specified unlike 123.Xr select 2 . 124If 125.Fa timeout 126is a non-NULL pointer, it specifies a maximum interval to wait | 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 --- 85 unchanged lines hidden (view full) --- 119.Fn kevent 120will return immediately even if there is a 121.Fa timeout 122specified unlike 123.Xr select 2 . 124If 125.Fa timeout 126is a non-NULL pointer, it specifies a maximum interval to wait |
| 127for an event, which will be interpreted as a struct timespec. If | 127for an event, which will be interpreted as a struct timespec. 128If |
| 128.Fa timeout 129is a NULL pointer, 130.Fn kevent | 129.Fa timeout 130is a NULL pointer, 131.Fn kevent |
| 131waits indefinitely. To effect a poll, the | 132waits indefinitely. 133To effect a poll, the |
| 132.Fa timeout 133argument should be non-NULL, pointing to a zero-valued 134.Va timespec | 134.Fa timeout 135argument should be non-NULL, pointing to a zero-valued 136.Va timespec |
| 135structure. The same array may be used for the | 137structure. 138The same array may be used for the |
| 136.Fa changelist 137and 138.Fa eventlist . 139.Pp 140The 141.Fn EV_SET 142macro is provided for ease of initializing a 143kevent structure. --- 16 unchanged lines hidden (view full) --- 160.Fa struct kevent 161are: 162.Bl -tag -width XXXfilter 163.It ident 164Value used to identify this event. 165The exact interpretation is determined by the attached filter, 166but often is a file descriptor. 167.It filter | 139.Fa changelist 140and 141.Fa eventlist . 142.Pp 143The 144.Fn EV_SET 145macro is provided for ease of initializing a 146kevent structure. --- 16 unchanged lines hidden (view full) --- 163.Fa struct kevent 164are: 165.Bl -tag -width XXXfilter 166.It ident 167Value used to identify this event. 168The exact interpretation is determined by the attached filter, 169but often is a file descriptor. 170.It filter |
| 168Identifies the kernel filter used to process this event. The pre-defined | 171Identifies the kernel filter used to process this event. 172The pre-defined |
| 169system filters are described below. 170.It flags 171Actions to perform on the event. 172.It fflags 173Filter-specific flags. 174.It data 175Filter-specific data value. 176.It udata 177Opaque user-defined value passed through the kernel unchanged. 178.El 179.Pp 180The 181.Va flags 182field can contain the following values: 183.Bl -tag -width XXXEV_ONESHOT 184.It EV_ADD | 173system filters are described below. 174.It flags 175Actions to perform on the event. 176.It fflags 177Filter-specific flags. 178.It data 179Filter-specific data value. 180.It udata 181Opaque user-defined value passed through the kernel unchanged. 182.El 183.Pp 184The 185.Va flags 186field can contain the following values: 187.Bl -tag -width XXXEV_ONESHOT 188.It EV_ADD |
| 185Adds the event to the kqueue. Re-adding an existing event | 189Adds the event to the kqueue. 190Re-adding an existing event |
| 186will modify the parameters of the original event, and not result | 191will modify the parameters of the original event, and not result |
| 187in a duplicate entry. Adding an event automatically enables it, | 192in a duplicate entry. 193Adding an event automatically enables it, |
| 188unless overridden by the EV_DISABLE flag. 189.It EV_ENABLE 190Permit 191.Fn kevent 192to return the event if it is triggered. 193.It EV_DISABLE 194Disable the event so 195.Fn kevent | 194unless overridden by the EV_DISABLE flag. 195.It EV_ENABLE 196Permit 197.Fn kevent 198to return the event if it is triggered. 199.It EV_DISABLE 200Disable the event so 201.Fn kevent |
| 196will not return it. The filter itself is not disabled. | 202will not return it. 203The filter itself is not disabled. |
| 197.It EV_DELETE | 204.It EV_DELETE |
| 198Removes the event from the kqueue. Events which are attached to | 205Removes the event from the kqueue. 206Events which are attached to |
| 199file descriptors are automatically deleted on the last close of 200the descriptor. 201.It EV_ONESHOT 202Causes the event to return only the first occurrence of the filter | 207file descriptors are automatically deleted on the last close of 208the descriptor. 209.It EV_ONESHOT 210Causes the event to return only the first occurrence of the filter |
| 203being triggered. After the user retrieves the event from the kqueue, | 211being triggered. 212After the user retrieves the event from the kqueue, |
| 204it is deleted. 205.It EV_CLEAR 206After the event is retrieved by the user, its state is reset. 207This is useful for filters which report state transitions | 213it is deleted. 214.It EV_CLEAR 215After the event is retrieved by the user, its state is reset. 216This is useful for filters which report state transitions |
| 208instead of the current state. Note that some filters may automatically | 217instead of the current state. 218Note that some filters may automatically |
| 209set this flag internally. 210.It EV_EOF 211Filters may set this flag to indicate filter-specific EOF condition. 212.It EV_ERROR 213See 214.Sx RETURN VALUES 215below. 216.El --- 61 unchanged lines hidden (view full) --- 278when the BPF has 279.Dq immediate mode 280enabled and there is any data to read; 281.Va data 282contains the number of bytes available. 283.El 284.It EVFILT_WRITE 285Takes a descriptor as the identifier, and returns whenever | 219set this flag internally. 220.It EV_EOF 221Filters may set this flag to indicate filter-specific EOF condition. 222.It EV_ERROR 223See 224.Sx RETURN VALUES 225below. 226.El --- 61 unchanged lines hidden (view full) --- 288when the BPF has 289.Dq immediate mode 290enabled and there is any data to read; 291.Va data 292contains the number of bytes available. 293.El 294.It EVFILT_WRITE 295Takes a descriptor as the identifier, and returns whenever |
| 286it is possible to write to the descriptor. For sockets, pipes | 296it is possible to write to the descriptor. 297For sockets, pipes |
| 287and fifos, 288.Va data 289will contain the amount of space remaining in the write buffer. 290The filter will set EV_EOF when the reader disconnects, and for 291the fifo case, this may be cleared by use of EV_CLEAR. 292Note that this filter is not supported for vnodes or BPF devices. 293.Pp 294For sockets, the low water mark and socket error handling is --- 19 unchanged lines hidden (view full) --- 314system call. 315The filter returns under the same conditions as aio_error. 316.Pp 317Alternatively, a kevent structure may be initialized, with 318.Va ident 319containing the descriptor of the kqueue, and the 320address of the kevent structure placed in the 321.Va aio_lio_opcode | 298and fifos, 299.Va data 300will contain the amount of space remaining in the write buffer. 301The filter will set EV_EOF when the reader disconnects, and for 302the fifo case, this may be cleared by use of EV_CLEAR. 303Note that this filter is not supported for vnodes or BPF devices. 304.Pp 305For sockets, the low water mark and socket error handling is --- 19 unchanged lines hidden (view full) --- 325system call. 326The filter returns under the same conditions as aio_error. 327.Pp 328Alternatively, a kevent structure may be initialized, with 329.Va ident 330containing the descriptor of the kqueue, and the 331address of the kevent structure placed in the 332.Va aio_lio_opcode |
| 322field of the AIO request. However, this approach will not work on | 333field of the AIO request. 334However, this approach will not work on |
| 323architectures with 64-bit pointers, and should be considered deprecated. 324.It EVFILT_VNODE 325Takes a file descriptor as the identifier and the events to watch for in 326.Va fflags , 327and returns when one or more of the requested events occurs on the descriptor. 328The events to monitor are: 329.Bl -tag -width XXNOTE_RENAME 330.It NOTE_DELETE --- 35 unchanged lines hidden (view full) --- 366.Fn fork . 367.It NOTE_EXEC 368The process has executed a new process via 369.Xr execve 2 370or similar call. 371.It NOTE_TRACK 372Follow a process across 373.Fn fork | 335architectures with 64-bit pointers, and should be considered deprecated. 336.It EVFILT_VNODE 337Takes a file descriptor as the identifier and the events to watch for in 338.Va fflags , 339and returns when one or more of the requested events occurs on the descriptor. 340The events to monitor are: 341.Bl -tag -width XXNOTE_RENAME 342.It NOTE_DELETE --- 35 unchanged lines hidden (view full) --- 378.Fn fork . 379.It NOTE_EXEC 380The process has executed a new process via 381.Xr execve 2 382or similar call. 383.It NOTE_TRACK 384Follow a process across 385.Fn fork |
| 374calls. The parent process will return with NOTE_TRACK set in the | 386calls. 387The parent process will return with NOTE_TRACK set in the |
| 375.Va fflags 376field, while the child process will return with NOTE_CHILD set in 377.Va fflags 378and the parent PID in 379.Va data . 380.It NOTE_TRACKERR 381This flag is returned if the system was unable to attach an event to 382the child process, usually due to resource limitations. --- 4 unchanged lines hidden (view full) --- 387contains the events which triggered the filter. 388.It EVFILT_SIGNAL 389Takes the signal number to monitor as the identifier and returns 390when the given signal is delivered to the process. 391This coexists with the 392.Fn signal 393and 394.Fn sigaction | 388.Va fflags 389field, while the child process will return with NOTE_CHILD set in 390.Va fflags 391and the parent PID in 392.Va data . 393.It NOTE_TRACKERR 394This flag is returned if the system was unable to attach an event to 395the child process, usually due to resource limitations. --- 4 unchanged lines hidden (view full) --- 400contains the events which triggered the filter. 401.It EVFILT_SIGNAL 402Takes the signal number to monitor as the identifier and returns 403when the given signal is delivered to the process. 404This coexists with the 405.Fn signal 406and 407.Fn sigaction |
| 395facilities, and has a lower precedence. The filter will record | 408facilities, and has a lower precedence. 409The filter will record |
| 396all attempts to deliver a signal to a process, even if the signal has | 410all attempts to deliver a signal to a process, even if the signal has |
| 397been marked as SIG_IGN. Event notification happens after normal | 411been marked as SIG_IGN. 412Event notification happens after normal |
| 398signal delivery processing. 399.Va data 400returns the number of times the signal has occurred since the last call to 401.Fn kevent . 402This filter automatically sets the EV_CLEAR flag internally. 403.It EVFILT_TIMER 404Establishes an arbitrary timer identified by 405.Va ident . --- 138 unchanged lines hidden --- | 413signal delivery processing. 414.Va data 415returns the number of times the signal has occurred since the last call to 416.Fn kevent . 417This filter automatically sets the EV_CLEAR flag internally. 418.It EVFILT_TIMER 419Establishes an arbitrary timer identified by 420.Va ident . --- 138 unchanged lines hidden --- |