| blob | fa0347cf3116ea98d3a48bc88cf6ae2284cae392 |
1 .\" $NetBSD: kqueue.2,v 1.32 2012/01/25 00:28:35 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 January 23, 2012
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 .It NOTE_FORK
417 The process has called
418 .Fn fork .
419 .It NOTE_EXEC
420 The process has executed a new process via
421 .Xr execve 2
422 or similar call.
423 .It NOTE_TRACK
424 Follow a process across
425 .Fn fork
426 calls.
427 The parent process will return with NOTE_TRACK set in the
428 .Va fflags
429 field, while the child process will return with NOTE_CHILD set in
430 .Va fflags
431 and the parent PID in
432 .Va data .
433 .It NOTE_TRACKERR
434 This flag is returned if the system was unable to attach an event to
435 the child process, usually due to resource limitations.
436 .El
437 .Pp
438 On return,
439 .Va fflags
440 contains the events which triggered the filter.
441 .It EVFILT_SIGNAL
442 Takes the signal number to monitor as the identifier and returns
443 when the given signal is delivered to the current process.
444 This coexists with the
445 .Fn signal
446 and
447 .Fn sigaction
448 facilities, and has a lower precedence.
449 The filter will record
450 all attempts to deliver a signal to a process, even if the signal has
451 been marked as SIG_IGN.
452 Event notification happens after normal signal delivery processing.
453 .Va data
454 returns the number of times the signal has occurred since the last call to
455 .Fn kevent .
456 This filter automatically sets the EV_CLEAR flag internally.
457 .It EVFILT_TIMER
458 Establishes an arbitrary timer identified by
459 .Va ident .
460 When adding a timer,
461 .Va data
462 specifies the timeout period in milliseconds.
463 The timer will be periodic unless EV_ONESHOT is specified.
464 On return,
465 .Va data
466 contains the number of times the timeout has expired since the last call to
467 .Fn kevent .
468 This filter automatically sets the EV_CLEAR flag internally.
469 .El
470 .Sh RETURN VALUES
471 .Fn kqueue
472 creates a new kernel event queue and returns a file descriptor.
473 If there was an error creating the kernel event queue, a value of \-1 is
474 returned and errno set.
475 .Pp
476 .Fn kevent
477 returns the number of events placed in the
478 .Fa eventlist ,
479 up to the value given by
480 .Fa nevents .
481 If an error occurs while processing an element of the
482 .Fa changelist
483 and there is enough room in the
484 .Fa eventlist ,
485 then the event will be placed in the
486 .Fa eventlist
487 with
488 .Dv EV_ERROR
489 set in
490 .Va flags
491 and the system error in
492 .Va data .
493 Otherwise,
494 .Dv \-1
495 will be returned, and
496 .Dv errno
497 will be set to indicate the error condition.
498 If the time limit expires, then
499 .Fn kevent
500 returns 0.
501 .Sh EXAMPLES
502 The following example program monitors a file (provided to it as the first
503 argument) and prints information about some common events it receives
504 notifications for:
505 .Bd -literal -offset indent
506 #include \*[Lt]sys/types.h\*[Gt]
507 #include \*[Lt]sys/event.h\*[Gt]
508 #include \*[Lt]sys/time.h\*[Gt]
509 #include \*[Lt]stdio.h\*[Gt]
510 #include \*[Lt]unistd.h\*[Gt]
511 #include \*[Lt]stdlib.h\*[Gt]
512 #include \*[Lt]fcntl.h\*[Gt]
513 #include \*[Lt]err.h\*[Gt]
515 int
516 main(int argc, char *argv[])
517 {
518 int fd, kq, nev;
519 struct kevent ev;
520 static const struct timespec tout = { 1, 0 };
522 if ((fd = open(argv[1], O_RDONLY)) == -1)
523 err(1, "Cannot open `%s'", argv[1]);
525 if ((kq = kqueue()) == -1)
526 err(1, "Cannot create kqueue");
528 EV_SET(\*[Am]ev, fd, EVFILT_VNODE, EV_ADD | EV_ENABLE | EV_CLEAR,
529 NOTE_DELETE|NOTE_WRITE|NOTE_EXTEND|NOTE_ATTRIB|NOTE_LINK|
530 NOTE_RENAME|NOTE_REVOKE, 0, 0);
531 if (kevent(kq, \*[Am]ev, 1, NULL, 0, \*[Am]tout) == -1)
532 err(1, "kevent");
533 for (;;) {
534 nev = kevent(kq, NULL, 0, \*[Am]ev, 1, \*[Am]tout);
535 if (nev == -1)
536 err(1, "kevent");
537 if (nev == 0)
538 continue;
539 if (ev.fflags \*[Am] NOTE_DELETE) {
540 printf("deleted ");
541 ev.fflags \*[Am]= ~NOTE_DELETE;
542 }
543 if (ev.fflags \*[Am] NOTE_WRITE) {
544 printf("written ");
545 ev.fflags \*[Am]= ~NOTE_WRITE;
546 }
547 if (ev.fflags \*[Am] NOTE_EXTEND) {
548 printf("extended ");
549 ev.fflags \*[Am]= ~NOTE_EXTEND;
550 }
551 if (ev.fflags \*[Am] NOTE_ATTRIB) {
552 printf("chmod/chown/utimes ");
553 ev.fflags \*[Am]= ~NOTE_ATTRIB;
554 }
555 if (ev.fflags \*[Am] NOTE_LINK) {
556 printf("hardlinked ");
557 ev.fflags \*[Am]= ~NOTE_LINK;
558 }
559 if (ev.fflags \*[Am] NOTE_RENAME) {
560 printf("renamed ");
561 ev.fflags \*[Am]= ~NOTE_RENAME;
562 }
563 if (ev.fflags \*[Am] NOTE_REVOKE) {
564 printf("revoked ");
565 ev.fflags \*[Am]= ~NOTE_REVOKE;
566 }
567 printf("\\n");
568 if (ev.fflags)
569 warnx("unknown event 0x%x\\n", ev.fflags);
570 }
571 }
572 .Ed
573 .Sh ERRORS
574 The
575 .Fn kqueue
576 function fails if:
577 .Bl -tag -width Er
578 .It Bq Er EMFILE
579 The per-process descriptor table is full.
580 .It Bq Er ENFILE
581 The system file table is full.
582 .It Bq Er ENOMEM
583 The kernel failed to allocate enough memory for the kernel queue.
584 .El
585 .Pp
586 The
587 .Fn kevent
588 function fails if:
589 .Bl -tag -width Er
590 .It Bq Er EACCES
591 The process does not have permission to register a filter.
592 .It Bq Er EBADF
593 The specified descriptor is invalid.
594 .It Bq Er EFAULT
595 There was an error reading or writing the
596 .Va kevent
597 structure.
598 .It Bq Er EINTR
599 A signal was delivered before the timeout expired and before any
600 events were placed on the kqueue for return.
601 .It Bq Er EINVAL
602 The specified time limit or filter is invalid.
603 .It Bq Er ENOENT
604 The event could not be found to be modified or deleted.
605 .It Bq Er ENOMEM
606 No memory was available to register the event.
607 .It Bq Er ESRCH
608 The specified process to attach to does not exist.
609 .El
610 .Sh SEE ALSO
611 .\" .Xr aio_error 2 ,
612 .\" .Xr aio_read 2 ,
613 .\" .Xr aio_return 2 ,
614 .Xr ioctl 2 ,
615 .Xr poll 2 ,
616 .Xr read 2 ,
617 .Xr select 2 ,
618 .Xr sigaction 2 ,
619 .Xr write 2 ,
620 .Xr signal 3 ,
621 .Xr kfilter_register 9 ,
622 .Xr knote 9
623 .Rs
624 .%A Jonathan Lemon
625 .%T "Kqueue: A Generic and Scalable Event Notification Facility"
626 .%I USENIX Association
627 .%B Proceedings of the FREENIX Track: 2001 USENIX Annual Technical Conference
628 .%D June 25-30, 2001
629 .%U http://www.usenix.org/event/usenix01/freenix01/full_papers/lemon/lemon.pdf
630 .Re
631 .Sh HISTORY
632 The
633 .Fn kqueue
634 and
635 .Fn kevent
636 functions first appeared in
637 .Fx 4.1 ,
638 and then in
639 .Nx 2.0 .
640 The
641 .Fn kqueue1
642 function first appeared in
643 .Nx 6.0 .