| blob | 880339e1b03843d35b25115b6abb22e97bdec18b |
1 .\" $NetBSD: kqueue.2,v 1.34 2015/03/02 19:24:19 christos Exp $
2 .\"
3 .\" Copyright (c) 2000 Jonathan Lemon
4 .\" All rights reserved.
5 .\"
6 .\" Copyright (c) 2001, 2002, 2003 The NetBSD Foundation, Inc.
7 .\" All rights reserved.
8 .\"
9 .\" Portions of this documentation is derived from text contributed by
10 .\" Luke Mewburn.
11 .\"
12 .\" Redistribution and use in source and binary forms, with or without
13 .\" modification, are permitted provided that the following conditions
14 .\" are met:
15 .\" 1. Redistributions of source code must retain the above copyright
16 .\" notice, this list of conditions and the following disclaimer.
17 .\" 2. Redistributions in binary form must reproduce the above copyright
18 .\" notice, this list of conditions and the following disclaimer in the
19 .\" documentation and/or other materials provided with the distribution.
20 .\"
21 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND
22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31 .\" SUCH DAMAGE.
32 .\"
33 .\" $FreeBSD: src/lib/libc/sys/kqueue.2,v 1.22 2001/06/27 19:55:57 dd Exp $
34 .\"
35 .Dd March 2, 2015
36 .Dt KQUEUE 2
37 .Os
38 .Sh NAME
39 .Nm kqueue ,
40 .Nm kqueue1 ,
41 .Nm kevent
42 .Nd kernel event notification mechanism
43 .Sh LIBRARY
44 .Lb libc
45 .Sh SYNOPSIS
46 .In sys/event.h
47 .In sys/time.h
48 .Ft int
49 .Fn kqueue "void"
50 .Ft int
51 .Fn kqueue1 "int flags"
52 .Ft int
53 .Fn kevent "int kq" "const struct kevent *changelist" "size_t nchanges" "struct kevent *eventlist" "size_t nevents" "const struct timespec *timeout"
54 .Fn EV_SET "\*[Am]kev" ident filter flags fflags data udata
55 .Sh DESCRIPTION
56 .Fn kqueue
57 provides a generic method of notifying the user when an event
58 happens or a condition holds, based on the results of small
59 pieces of kernel code termed filters.
60 A kevent is identified by the (ident, filter) pair; there may only
61 be one unique kevent per kqueue.
62 .Pp
63 The filter is executed upon the initial registration of a kevent
64 in order to detect whether a preexisting condition is present, and is also
65 executed whenever an event is passed to the filter for evaluation.
66 If the filter determines that the condition should be reported,
67 then the kevent is placed on the kqueue for the user to retrieve.
68 .Pp
69 The filter is also run when the user attempts to retrieve the kevent
70 from the kqueue.
71 If the filter indicates that the condition that triggered
72 the event no longer holds, the kevent is removed from the kqueue and
73 is not returned.
74 .Pp
75 Multiple events which trigger the filter do not result in multiple
76 kevents being placed on the kqueue; instead, the filter will aggregate
77 the events into a single struct kevent.
78 Calling
79 .Fn close
80 on a file descriptor will remove any kevents that reference the descriptor.
81 .Pp
82 .Fn kqueue
83 creates a new kernel event queue and returns a descriptor.
84 .Pp
85 The
86 .Fn kqueue1
87 also allows to set the following
88 .Fa flags
89 on the returned file descriptor:
90 .Bl -column O_NONBLOCK -offset indent
91 .It Dv O_CLOEXEC
92 Set the close on exec property.
93 .It Dv O_NONBLOCK
94 Sets non-blocking I/O.
95 .It Dv O_NOSIGPIPE
96 Return
97 .Er EPIPE
98 instead of raising
99 .Dv SIGPIPE .
100 .El
101 The queue is not inherited by a child created with
102 .Xr fork 2 .
103 .\" However, if
104 .\" .Xr rfork 2
105 .\" is called without the
106 .\" .Dv RFFDG
107 .\" flag, then the descriptor table is shared,
108 .\" which will allow sharing of the kqueue between two processes.
109 .Pp
110 .Fn kevent
111 is used to register events with the queue, and return any pending
112 events to the user.
113 .Fa changelist
114 is a pointer to an array of
115 .Va kevent
116 structures, as defined in
117 .In sys/event.h .
118 All changes contained in the
119 .Fa changelist
120 are applied before any pending events are read from the queue.
121 .Fa nchanges
122 gives the size of
123 .Fa changelist .
124 .Fa eventlist
125 is a pointer to an array of kevent structures.
126 .Fa nevents
127 determines the size of
128 .Fa eventlist .
129 If
130 .Fa timeout
131 is a
132 .No non- Ns Dv NULL
133 pointer, it specifies a maximum interval to wait
134 for an event, which will be interpreted as a struct timespec.
135 If
136 .Fa timeout
137 is a
138 .Dv NULL
139 pointer,
140 .Fn kevent
141 waits indefinitely.
142 To effect a poll, the
143 .Fa timeout
144 argument should be
145 .No non- Ns Dv NULL ,
146 pointing to a zero-valued
147 .Va timespec
148 structure.
149 The same array may be used for the
150 .Fa changelist
151 and
152 .Fa eventlist .
153 .Pp
154 .Fn EV_SET
155 is a macro which is provided for ease of initializing a
156 kevent structure.
157 .Pp
158 The
159 .Va kevent
160 structure is defined as:
161 .Bd -literal
162 struct kevent {
163 uintptr_t ident; /* identifier for this event */
164 uint32_t filter; /* filter for event */
165 uint32_t flags; /* action flags for kqueue */
166 uint32_t fflags; /* filter flag value */
167 int64_t data; /* filter data value */
168 intptr_t udata; /* opaque user data identifier */
169 };
170 .Ed
171 .Pp
172 The fields of
173 .Fa struct kevent
174 are:
175 .Bl -tag -width XXXfilter -offset indent
176 .It ident
177 Value used to identify this event.
178 The exact interpretation is determined by the attached filter,
179 but often is a file descriptor.
180 .It filter
181 Identifies the kernel filter used to process this event.
182 There are pre-defined system filters (which are described below), and
183 other filters may be added by kernel subsystems as necessary.
184 .It flags
185 Actions to perform on the event.
186 .It fflags
187 Filter-specific flags.
188 .It data
189 Filter-specific data value.
190 .It udata
191 Opaque user-defined value passed through the kernel unchanged.
192 .El
193 .Pp
194 The
195 .Va flags
196 field can contain the following values:
197 .Bl -tag -width XXXEV_ONESHOT -offset indent
198 .It EV_ADD
199 Adds the event to the kqueue.
200 Re-adding an existing event will modify the parameters of the original
201 event, and not result in a duplicate entry.
202 Adding an event automatically enables it,
203 unless overridden by the EV_DISABLE flag.
204 .It EV_ENABLE
205 Permit
206 .Fn kevent
207 to return the event if it is triggered.
208 .It EV_DISABLE
209 Disable the event so
210 .Fn kevent
211 will not return it.
212 The filter itself is not disabled.
213 .It EV_DELETE
214 Removes the event from the kqueue.
215 Events which are attached to file descriptors are automatically deleted
216 on the last close of the descriptor.
217 .It EV_ONESHOT
218 Causes the event to return only the first occurrence of the filter
219 being triggered.
220 After the user retrieves the event from the kqueue, it is deleted.
221 .It EV_CLEAR
222 After the event is retrieved by the user, its state is reset.
223 This is useful for filters which report state transitions
224 instead of the current state.
225 Note that some filters may automatically set this flag internally.
226 .It EV_EOF
227 Filters may set this flag to indicate filter-specific EOF condition.
228 .It EV_ERROR
229 See
230 .Sx RETURN VALUES
231 below.
232 .El
233 .Ss Filters
234 Filters are identified by a number.
235 There are two types of filters; pre-defined filters which
236 are described below, and third-party filters that may be added with
237 .Xr kfilter_register 9
238 by kernel sub-systems, third-party device drivers, or loadable
239 kernel modules.
240 .Pp
241 As a third-party filter is referenced by a well-known name instead
242 of a statically assigned number, two
243 .Xr ioctl 2 Ns s
244 are supported on the file descriptor returned by
245 .Fn kqueue
246 to map a filter name to a filter number, and vice-versa (passing
247 arguments in a structure described below):
248 .Bl -tag -width KFILTER_BYFILTER -offset indent
249 .It KFILTER_BYFILTER
250 Map
251 .Va filter
252 to
253 .Va name ,
254 which is of size
255 .Va len .
256 .It KFILTER_BYNAME
257 Map
258 .Va name
259 to
260 .Va filter .
261 .Va len
262 is ignored.
263 .El
264 .Pp
265 The following structure is used to pass arguments in and out of the
266 .Xr ioctl 2 :
267 .Bd -literal -offset indent
268 struct kfilter_mapping {
269 char *name; /* name to lookup or return */
270 size_t len; /* length of name */
271 uint32_t filter; /* filter to lookup or return */
272 };
273 .Ed
274 .Pp
275 Arguments may be passed to and from the filter via the
276 .Va fflags
277 and
278 .Va data
279 fields in the kevent structure.
280 .Pp
281 The predefined system filters are:
282 .Bl -tag -width EVFILT_SIGNAL
283 .It EVFILT_READ
284 Takes a descriptor as the identifier, and returns whenever
285 there is data available to read.
286 The behavior of the filter is slightly different depending
287 on the descriptor type.
288 .Pp
289 .Bl -tag -width 2n
290 .It Sockets
291 Sockets which have previously been passed to
292 .Fn listen
293 return when there is an incoming connection pending.
294 .Va data
295 contains the size of the listen backlog (i.e., the number of
296 connections ready to be accepted with
297 .Xr accept 2 . )
298 .Pp
299 Other socket descriptors return when there is data to be read,
300 subject to the
301 .Dv SO_RCVLOWAT
302 value of the socket buffer.
303 This may be overridden with a per-filter low water mark at the
304 time the filter is added by setting the
305 NOTE_LOWAT
306 flag in
307 .Va fflags ,
308 and specifying the new low water mark in
309 .Va data .
310 On return,
311 .Va data
312 contains the number of bytes in the socket buffer.
313 .Pp
314 If the read direction of the socket has shutdown, then the filter
315 also sets EV_EOF in
316 .Va flags ,
317 and returns the socket error (if any) in
318 .Va fflags .
319 It is possible for EOF to be returned (indicating the connection is gone)
320 while there is still data pending in the socket buffer.
321 .It Vnodes
322 Returns when the file pointer is not at the end of file.
323 .Va data
324 contains the offset from current position to end of file,
325 and may be negative.
326 .It "Fifos, Pipes"
327 Returns when there is data to read;
328 .Va data
329 contains the number of bytes available.
330 .Pp
331 When the last writer disconnects, the filter will set EV_EOF in
332 .Va flags .
333 This may be cleared by passing in EV_CLEAR, at which point the
334 filter will resume waiting for data to become available before
335 returning.
336 .El
337 .It EVFILT_WRITE
338 Takes a descriptor as the identifier, and returns whenever
339 it is possible to write to the descriptor.
340 For sockets, pipes, fifos, and ttys,
341 .Va data
342 will contain the amount of space remaining in the write buffer.
343 The filter will set EV_EOF when the reader disconnects, and for
344 the fifo case, this may be cleared by use of EV_CLEAR.
345 Note that this filter is not supported for vnodes.
346 .Pp
347 For sockets, the low water mark and socket error handling is
348 identical to the EVFILT_READ case.
349 .It EVFILT_AIO
350 This is not implemented in
351 .Nx .
352 .ig
353 The sigevent portion of the AIO request is filled in, with
354 .Va sigev_notify_kqueue
355 containing the descriptor of the kqueue that the event should
356 be attached to,
357 .Va sigev_value
358 containing the udata value, and
359 .Va sigev_notify
360 set to SIGEV_EVENT.
361 When the aio_* function is called, the event will be registered
362 with the specified kqueue, and the
363 .Va ident
364 argument set to the
365 .Fa struct aiocb
366 returned by the aio_* function.
367 The filter returns under the same conditions as aio_error.
368 .Pp
369 Alternatively, a kevent structure may be initialized, with
370 .Va ident
371 containing the descriptor of the kqueue, and the
372 address of the kevent structure placed in the
373 .Va aio_lio_opcode
374 field of the AIO request.
375 However, this approach will not work on
376 architectures with 64-bit pointers, and should be considered deprecated.
377 ..
378 .It EVFILT_VNODE
379 Takes a file descriptor as the identifier and the events to watch for in
380 .Va fflags ,
381 and returns when one or more of the requested events occurs on the descriptor.
382 The events to monitor are:
383 .Bl -tag -width XXNOTE_RENAME
384 .It NOTE_DELETE
385 .Fn unlink
386 was called on the file referenced by the descriptor.
387 .It NOTE_WRITE
388 A write occurred on the file referenced by the descriptor.
389 .It NOTE_EXTEND
390 The file referenced by the descriptor was extended.
391 .It NOTE_ATTRIB
392 The file referenced by the descriptor had its attributes changed.
393 .It NOTE_LINK
394 The link count on the file changed.
395 .It NOTE_RENAME
396 The file referenced by the descriptor was renamed.
397 .It NOTE_REVOKE
398 Access to the file was revoked via
399 .Xr revoke 2
400 or the underlying fileystem was unmounted.
401 .El
402 .Pp
403 On return,
404 .Va fflags
405 contains the events which triggered the filter.
406 .It EVFILT_PROC
407 Takes the process ID to monitor as the identifier and the events to watch for
408 in
409 .Va fflags ,
410 and returns when the process performs one or more of the requested events.
411 If a process can normally see another process, it can attach an event to it.
412 The events to monitor are:
413 .Bl -tag -width XXNOTE_TRACKERR
414 .It NOTE_EXIT
415 The process has exited.
416 The exit code of the process is stored in
417 .Va data .
418 .It NOTE_FORK
419 The process has called
420 .Fn fork .
421 .It NOTE_EXEC
422 The process has executed a new process via
423 .Xr execve 2
424 or similar call.
425 .It NOTE_TRACK
426 Follow a process across
427 .Fn fork
428 calls.
429 The parent process will return with NOTE_TRACK set in the
430 .Va fflags
431 field, while the child process will return with NOTE_CHILD set in
432 .Va fflags
433 and the parent PID in
434 .Va data .
435 .It NOTE_TRACKERR
436 This flag is returned if the system was unable to attach an event to
437 the child process, usually due to resource limitations.
438 .El
439 .Pp
440 On return,
441 .Va fflags
442 contains the events which triggered the filter.
443 .It EVFILT_SIGNAL
444 Takes the signal number to monitor as the identifier and returns
445 when the given signal is delivered to the current process.
446 This coexists with the
447 .Fn signal
448 and
449 .Fn sigaction
450 facilities, and has a lower precedence.
451 The filter will record
452 all attempts to deliver a signal to a process, even if the signal has
453 been marked as SIG_IGN.
454 Event notification happens after normal signal delivery processing.
455 .Va data
456 returns the number of times the signal has occurred since the last call to
457 .Fn kevent .
458 This filter automatically sets the EV_CLEAR flag internally.
459 .It EVFILT_TIMER
460 Establishes an arbitrary timer identified by
461 .Va ident .
462 When adding a timer,
463 .Va data
464 specifies the timeout period in milliseconds.
465 The timer will be periodic unless EV_ONESHOT is specified.
466 On return,
467 .Va data
468 contains the number of times the timeout has expired since the last call to
469 .Fn kevent .
470 This filter automatically sets the EV_CLEAR flag internally.
471 .El
472 .Sh RETURN VALUES
473 .Fn kqueue
474 creates a new kernel event queue and returns a file descriptor.
475 If there was an error creating the kernel event queue, a value of \-1 is
476 returned and errno set.
477 .Pp
478 .Fn kevent
479 returns the number of events placed in the
480 .Fa eventlist ,
481 up to the value given by
482 .Fa nevents .
483 If an error occurs while processing an element of the
484 .Fa changelist
485 and there is enough room in the
486 .Fa eventlist ,
487 then the event will be placed in the
488 .Fa eventlist
489 with
490 .Dv EV_ERROR
491 set in
492 .Va flags
493 and the system error in
494 .Va data .
495 Otherwise,
496 .Dv \-1
497 will be returned, and
498 .Dv errno
499 will be set to indicate the error condition.
500 If the time limit expires, then
501 .Fn kevent
502 returns 0.
503 .Sh EXAMPLES
504 The following example program monitors a file (provided to it as the first
505 argument) and prints information about some common events it receives
506 notifications for:
507 .Bd -literal -offset indent
508 #include \*[Lt]sys/types.h\*[Gt]
509 #include \*[Lt]sys/event.h\*[Gt]
510 #include \*[Lt]sys/time.h\*[Gt]
511 #include \*[Lt]stdio.h\*[Gt]
512 #include \*[Lt]unistd.h\*[Gt]
513 #include \*[Lt]stdlib.h\*[Gt]
514 #include \*[Lt]fcntl.h\*[Gt]
515 #include \*[Lt]err.h\*[Gt]
517 int
518 main(int argc, char *argv[])
519 {
520 int fd, kq, nev;
521 struct kevent ev;
522 static const struct timespec tout = { 1, 0 };
524 if ((fd = open(argv[1], O_RDONLY)) == -1)
525 err(1, "Cannot open `%s'", argv[1]);
527 if ((kq = kqueue()) == -1)
528 err(1, "Cannot create kqueue");
530 EV_SET(\*[Am]ev, fd, EVFILT_VNODE, EV_ADD | EV_ENABLE | EV_CLEAR,
531 NOTE_DELETE|NOTE_WRITE|NOTE_EXTEND|NOTE_ATTRIB|NOTE_LINK|
532 NOTE_RENAME|NOTE_REVOKE, 0, 0);
533 if (kevent(kq, \*[Am]ev, 1, NULL, 0, \*[Am]tout) == -1)
534 err(1, "kevent");
535 for (;;) {
536 nev = kevent(kq, NULL, 0, \*[Am]ev, 1, \*[Am]tout);
537 if (nev == -1)
538 err(1, "kevent");
539 if (nev == 0)
540 continue;
541 if (ev.fflags \*[Am] NOTE_DELETE) {
542 printf("deleted ");
543 ev.fflags \*[Am]= ~NOTE_DELETE;
544 }
545 if (ev.fflags \*[Am] NOTE_WRITE) {
546 printf("written ");
547 ev.fflags \*[Am]= ~NOTE_WRITE;
548 }
549 if (ev.fflags \*[Am] NOTE_EXTEND) {
550 printf("extended ");
551 ev.fflags \*[Am]= ~NOTE_EXTEND;
552 }
553 if (ev.fflags \*[Am] NOTE_ATTRIB) {
554 printf("chmod/chown/utimes ");
555 ev.fflags \*[Am]= ~NOTE_ATTRIB;
556 }
557 if (ev.fflags \*[Am] NOTE_LINK) {
558 printf("hardlinked ");
559 ev.fflags \*[Am]= ~NOTE_LINK;
560 }
561 if (ev.fflags \*[Am] NOTE_RENAME) {
562 printf("renamed ");
563 ev.fflags \*[Am]= ~NOTE_RENAME;
564 }
565 if (ev.fflags \*[Am] NOTE_REVOKE) {
566 printf("revoked ");
567 ev.fflags \*[Am]= ~NOTE_REVOKE;
568 }
569 printf("\\n");
570 if (ev.fflags)
571 warnx("unknown event 0x%x\\n", ev.fflags);
572 }
573 }
574 .Ed
575 .Sh ERRORS
576 The
577 .Fn kqueue
578 function fails if:
579 .Bl -tag -width Er
580 .It Bq Er EMFILE
581 The per-process descriptor table is full.
582 .It Bq Er ENFILE
583 The system file table is full.
584 .It Bq Er ENOMEM
585 The kernel failed to allocate enough memory for the kernel queue.
586 .El
587 .Pp
588 The
589 .Fn kevent
590 function fails if:
591 .Bl -tag -width Er
592 .It Bq Er EACCES
593 The process does not have permission to register a filter.
594 .It Bq Er EBADF
595 The specified descriptor is invalid.
596 .It Bq Er EFAULT
597 There was an error reading or writing the
598 .Va kevent
599 structure.
600 .It Bq Er EINTR
601 A signal was delivered before the timeout expired and before any
602 events were placed on the kqueue for return.
603 .It Bq Er EINVAL
604 The specified time limit or filter is invalid.
605 .It Bq Er ENOENT
606 The event could not be found to be modified or deleted.
607 .It Bq Er ENOMEM
608 No memory was available to register the event.
609 .It Bq Er EOPNOTSUPP
610 This type of file descriptor is not supported for
611 .Fn kevent
612 operations.
613 .It Bq Er ESRCH
614 The specified process to attach to does not exist.
615 .El
616 .Sh SEE ALSO
617 .\" .Xr aio_error 2 ,
618 .\" .Xr aio_read 2 ,
619 .\" .Xr aio_return 2 ,
620 .Xr ioctl 2 ,
621 .Xr poll 2 ,
622 .Xr read 2 ,
623 .Xr select 2 ,
624 .Xr sigaction 2 ,
625 .Xr write 2 ,
626 .Xr signal 3 ,
627 .Xr kfilter_register 9 ,
628 .Xr knote 9
629 .Rs
630 .%A Jonathan Lemon
631 .%T "Kqueue: A Generic and Scalable Event Notification Facility"
632 .%I USENIX Association
633 .%B Proceedings of the FREENIX Track: 2001 USENIX Annual Technical Conference
634 .%D June 25-30, 2001
635 .%U http://www.usenix.org/event/usenix01/freenix01/full_papers/lemon/lemon.pdf
636 .Re
637 .Sh HISTORY
638 The
639 .Fn kqueue
640 and
641 .Fn kevent
642 functions first appeared in
643 .Fx 4.1 ,
644 and then in
645 .Nx 2.0 .
646 The
647 .Fn kqueue1
648 function first appeared in
649 .Nx 6.0 .