1:mod:`select` --- Waiting for I/O completion
2============================================
3
4.. module:: select
5   :synopsis: Wait for I/O completion on multiple streams.
6
7--------------
8
9This module provides access to the :c:func:`select` and :c:func:`poll` functions
10available in most operating systems, :c:func:`devpoll` available on
11Solaris and derivatives, :c:func:`epoll` available on Linux 2.5+ and
12:c:func:`kqueue` available on most BSD.
13Note that on Windows, it only works for sockets; on other operating systems,
14it also works for other file types (in particular, on Unix, it works on pipes).
15It cannot be used on regular files to determine whether a file has grown since
16it was last read.
17
18.. note::
19
20   The :mod:`selectors` module allows high-level and efficient I/O
21   multiplexing, built upon the :mod:`select` module primitives. Users are
22   encouraged to use the :mod:`selectors` module instead, unless they want
23   precise control over the OS-level primitives used.
24
25.. include:: ../includes/wasm-notavail.rst
26
27The module defines the following:
28
29
30.. exception:: error
31
32   A deprecated alias of :exc:`OSError`.
33
34   .. versionchanged:: 3.3
35      Following :pep:`3151`, this class was made an alias of :exc:`OSError`.
36
37
38.. function:: devpoll()
39
40   (Only supported on Solaris and derivatives.)  Returns a ``/dev/poll``
41   polling object; see section :ref:`devpoll-objects` below for the
42   methods supported by devpoll objects.
43
44   :c:func:`devpoll` objects are linked to the number of file
45   descriptors allowed at the time of instantiation. If your program
46   reduces this value, :c:func:`devpoll` will fail. If your program
47   increases this value, :c:func:`devpoll` may return an
48   incomplete list of active file descriptors.
49
50   The new file descriptor is :ref:`non-inheritable <fd_inheritance>`.
51
52   .. versionadded:: 3.3
53
54   .. versionchanged:: 3.4
55      The new file descriptor is now non-inheritable.
56
57.. function:: epoll(sizehint=-1, flags=0)
58
59   (Only supported on Linux 2.5.44 and newer.) Return an edge polling object,
60   which can be used as Edge or Level Triggered interface for I/O
61   events.
62
63   *sizehint* informs epoll about the expected number of events to be
64   registered.  It must be positive, or ``-1`` to use the default. It is only
65   used on older systems where :c:func:`epoll_create1` is not available;
66   otherwise it has no effect (though its value is still checked).
67
68   *flags* is deprecated and completely ignored.  However, when supplied, its
69   value must be ``0`` or ``select.EPOLL_CLOEXEC``, otherwise ``OSError`` is
70   raised.
71
72   See the :ref:`epoll-objects` section below for the methods supported by
73   epolling objects.
74
75   ``epoll`` objects support the context management protocol: when used in a
76   :keyword:`with` statement, the new file descriptor is automatically closed
77   at the end of the block.
78
79   The new file descriptor is :ref:`non-inheritable <fd_inheritance>`.
80
81   .. versionchanged:: 3.3
82      Added the *flags* parameter.
83
84   .. versionchanged:: 3.4
85      Support for the :keyword:`with` statement was added.
86      The new file descriptor is now non-inheritable.
87
88   .. deprecated:: 3.4
89      The *flags* parameter.  ``select.EPOLL_CLOEXEC`` is used by default now.
90      Use :func:`os.set_inheritable` to make the file descriptor inheritable.
91
92
93.. function:: poll()
94
95   (Not supported by all operating systems.)  Returns a polling object, which
96   supports registering and unregistering file descriptors, and then polling them
97   for I/O events; see section :ref:`poll-objects` below for the methods supported
98   by polling objects.
99
100
101.. function:: kqueue()
102
103   (Only supported on BSD.)  Returns a kernel queue object; see section
104   :ref:`kqueue-objects` below for the methods supported by kqueue objects.
105
106   The new file descriptor is :ref:`non-inheritable <fd_inheritance>`.
107
108   .. versionchanged:: 3.4
109      The new file descriptor is now non-inheritable.
110
111
112.. function:: kevent(ident, filter=KQ_FILTER_READ, flags=KQ_EV_ADD, fflags=0, data=0, udata=0)
113
114   (Only supported on BSD.)  Returns a kernel event object; see section
115   :ref:`kevent-objects` below for the methods supported by kevent objects.
116
117
118.. function:: select(rlist, wlist, xlist[, timeout])
119
120   This is a straightforward interface to the Unix :c:func:`select` system call.
121   The first three arguments are iterables of 'waitable objects': either
122   integers representing file descriptors or objects with a parameterless method
123   named :meth:`~io.IOBase.fileno` returning such an integer:
124
125   * *rlist*: wait until ready for reading
126   * *wlist*: wait until ready for writing
127   * *xlist*: wait for an "exceptional condition" (see the manual page for what
128     your system considers such a condition)
129
130   Empty iterables are allowed, but acceptance of three empty iterables is
131   platform-dependent. (It is known to work on Unix but not on Windows.)  The
132   optional *timeout* argument specifies a time-out as a floating point number
133   in seconds.  When the *timeout* argument is omitted the function blocks until
134   at least one file descriptor is ready.  A time-out value of zero specifies a
135   poll and never blocks.
136
137   The return value is a triple of lists of objects that are ready: subsets of the
138   first three arguments.  When the time-out is reached without a file descriptor
139   becoming ready, three empty lists are returned.
140
141   .. index::
142      single: socket() (in module socket)
143      single: popen() (in module os)
144
145   Among the acceptable object types in the iterables are Python :term:`file
146   objects <file object>` (e.g. ``sys.stdin``, or objects returned by
147   :func:`open` or :func:`os.popen`), socket objects returned by
148   :func:`socket.socket`.  You may also define a :dfn:`wrapper` class yourself,
149   as long as it has an appropriate :meth:`~io.IOBase.fileno` method (that
150   really returns a file descriptor, not just a random integer).
151
152   .. note::
153
154      .. index:: single: WinSock
155
156      File objects on Windows are not acceptable, but sockets are.  On Windows,
157      the underlying :c:func:`select` function is provided by the WinSock
158      library, and does not handle file descriptors that don't originate from
159      WinSock.
160
161   .. versionchanged:: 3.5
162      The function is now retried with a recomputed timeout when interrupted by
163      a signal, except if the signal handler raises an exception (see
164      :pep:`475` for the rationale), instead of raising
165      :exc:`InterruptedError`.
166
167
168.. attribute:: PIPE_BUF
169
170   The minimum number of bytes which can be written without blocking to a pipe
171   when the pipe has been reported as ready for writing by :func:`~select.select`,
172   :func:`poll` or another interface in this module.  This doesn't apply
173   to other kind of file-like objects such as sockets.
174
175   This value is guaranteed by POSIX to be at least 512.
176
177   .. availability:: Unix
178
179   .. versionadded:: 3.2
180
181
182.. _devpoll-objects:
183
184``/dev/poll`` Polling Objects
185-----------------------------
186
187Solaris and derivatives have ``/dev/poll``. While :c:func:`select` is
188O(highest file descriptor) and :c:func:`poll` is O(number of file
189descriptors), ``/dev/poll`` is O(active file descriptors).
190
191``/dev/poll`` behaviour is very close to the standard :c:func:`poll`
192object.
193
194
195.. method:: devpoll.close()
196
197   Close the file descriptor of the polling object.
198
199   .. versionadded:: 3.4
200
201
202.. attribute:: devpoll.closed
203
204   ``True`` if the polling object is closed.
205
206   .. versionadded:: 3.4
207
208
209.. method:: devpoll.fileno()
210
211   Return the file descriptor number of the polling object.
212
213   .. versionadded:: 3.4
214
215
216.. method:: devpoll.register(fd[, eventmask])
217
218   Register a file descriptor with the polling object.  Future calls to the
219   :meth:`poll` method will then check whether the file descriptor has any
220   pending I/O events.  *fd* can be either an integer, or an object with a
221   :meth:`~io.IOBase.fileno` method that returns an integer.  File objects
222   implement :meth:`!fileno`, so they can also be used as the argument.
223
224   *eventmask* is an optional bitmask describing the type of events you want to
225   check for. The constants are the same that with :c:func:`poll`
226   object. The default value is a combination of the constants :const:`POLLIN`,
227   :const:`POLLPRI`, and :const:`POLLOUT`.
228
229   .. warning::
230
231      Registering a file descriptor that's already registered is not an
232      error, but the result is undefined. The appropriate action is to
233      unregister or modify it first. This is an important difference
234      compared with :c:func:`poll`.
235
236
237.. method:: devpoll.modify(fd[, eventmask])
238
239   This method does an :meth:`unregister` followed by a
240   :meth:`register`. It is (a bit) more efficient that doing the same
241   explicitly.
242
243
244.. method:: devpoll.unregister(fd)
245
246   Remove a file descriptor being tracked by a polling object.  Just like the
247   :meth:`register` method, *fd* can be an integer or an object with a
248   :meth:`~io.IOBase.fileno` method that returns an integer.
249
250   Attempting to remove a file descriptor that was never registered is
251   safely ignored.
252
253
254.. method:: devpoll.poll([timeout])
255
256   Polls the set of registered file descriptors, and returns a possibly empty list
257   containing ``(fd, event)`` 2-tuples for the descriptors that have events or
258   errors to report. *fd* is the file descriptor, and *event* is a bitmask with
259   bits set for the reported events for that descriptor --- :const:`POLLIN` for
260   waiting input, :const:`POLLOUT` to indicate that the descriptor can be written
261   to, and so forth. An empty list indicates that the call timed out and no file
262   descriptors had any events to report. If *timeout* is given, it specifies the
263   length of time in milliseconds which the system will wait for events before
264   returning. If *timeout* is omitted, -1, or :const:`None`, the call will
265   block until there is an event for this poll object.
266
267   .. versionchanged:: 3.5
268      The function is now retried with a recomputed timeout when interrupted by
269      a signal, except if the signal handler raises an exception (see
270      :pep:`475` for the rationale), instead of raising
271      :exc:`InterruptedError`.
272
273
274.. _epoll-objects:
275
276Edge and Level Trigger Polling (epoll) Objects
277----------------------------------------------
278
279   https://linux.die.net/man/4/epoll
280
281   *eventmask*
282
283   +-------------------------+-----------------------------------------------+
284   | Constant                | Meaning                                       |
285   +=========================+===============================================+
286   | :const:`EPOLLIN`        | Available for read                            |
287   +-------------------------+-----------------------------------------------+
288   | :const:`EPOLLOUT`       | Available for write                           |
289   +-------------------------+-----------------------------------------------+
290   | :const:`EPOLLPRI`       | Urgent data for read                          |
291   +-------------------------+-----------------------------------------------+
292   | :const:`EPOLLERR`       | Error condition happened on the assoc. fd     |
293   +-------------------------+-----------------------------------------------+
294   | :const:`EPOLLHUP`       | Hang up happened on the assoc. fd             |
295   +-------------------------+-----------------------------------------------+
296   | :const:`EPOLLET`        | Set Edge Trigger behavior, the default is     |
297   |                         | Level Trigger behavior                        |
298   +-------------------------+-----------------------------------------------+
299   | :const:`EPOLLONESHOT`   | Set one-shot behavior. After one event is     |
300   |                         | pulled out, the fd is internally disabled     |
301   +-------------------------+-----------------------------------------------+
302   | :const:`EPOLLEXCLUSIVE` | Wake only one epoll object when the           |
303   |                         | associated fd has an event. The default (if   |
304   |                         | this flag is not set) is to wake all epoll    |
305   |                         | objects polling on a fd.                      |
306   +-------------------------+-----------------------------------------------+
307   | :const:`EPOLLRDHUP`     | Stream socket peer closed connection or shut  |
308   |                         | down writing half of connection.              |
309   +-------------------------+-----------------------------------------------+
310   | :const:`EPOLLRDNORM`    | Equivalent to :const:`EPOLLIN`                |
311   +-------------------------+-----------------------------------------------+
312   | :const:`EPOLLRDBAND`    | Priority data band can be read.               |
313   +-------------------------+-----------------------------------------------+
314   | :const:`EPOLLWRNORM`    | Equivalent to :const:`EPOLLOUT`               |
315   +-------------------------+-----------------------------------------------+
316   | :const:`EPOLLWRBAND`    | Priority data may be written.                 |
317   +-------------------------+-----------------------------------------------+
318   | :const:`EPOLLMSG`       | Ignored.                                      |
319   +-------------------------+-----------------------------------------------+
320
321   .. versionadded:: 3.6
322      :const:`EPOLLEXCLUSIVE` was added.  It's only supported by Linux Kernel 4.5
323      or later.
324
325.. method:: epoll.close()
326
327   Close the control file descriptor of the epoll object.
328
329
330.. attribute:: epoll.closed
331
332   ``True`` if the epoll object is closed.
333
334
335.. method:: epoll.fileno()
336
337   Return the file descriptor number of the control fd.
338
339
340.. method:: epoll.fromfd(fd)
341
342   Create an epoll object from a given file descriptor.
343
344
345.. method:: epoll.register(fd[, eventmask])
346
347   Register a fd descriptor with the epoll object.
348
349
350.. method:: epoll.modify(fd, eventmask)
351
352   Modify a registered file descriptor.
353
354
355.. method:: epoll.unregister(fd)
356
357   Remove a registered file descriptor from the epoll object.
358
359   .. versionchanged:: 3.9
360      The method no longer ignores the :data:`~errno.EBADF` error.
361
362
363.. method:: epoll.poll(timeout=None, maxevents=-1)
364
365   Wait for events. timeout in seconds (float)
366
367   .. versionchanged:: 3.5
368      The function is now retried with a recomputed timeout when interrupted by
369      a signal, except if the signal handler raises an exception (see
370      :pep:`475` for the rationale), instead of raising
371      :exc:`InterruptedError`.
372
373
374.. _poll-objects:
375
376Polling Objects
377---------------
378
379The :c:func:`poll` system call, supported on most Unix systems, provides better
380scalability for network servers that service many, many clients at the same
381time. :c:func:`poll` scales better because the system call only requires listing
382the file descriptors of interest, while :c:func:`select` builds a bitmap, turns
383on bits for the fds of interest, and then afterward the whole bitmap has to be
384linearly scanned again. :c:func:`select` is O(highest file descriptor), while
385:c:func:`poll` is O(number of file descriptors).
386
387
388.. method:: poll.register(fd[, eventmask])
389
390   Register a file descriptor with the polling object.  Future calls to the
391   :meth:`poll` method will then check whether the file descriptor has any
392   pending I/O events.  *fd* can be either an integer, or an object with a
393   :meth:`~io.IOBase.fileno` method that returns an integer.  File objects
394   implement :meth:`!fileno`, so they can also be used as the argument.
395
396   *eventmask* is an optional bitmask describing the type of events you want to
397   check for, and can be a combination of the constants :const:`POLLIN`,
398   :const:`POLLPRI`, and :const:`POLLOUT`, described in the table below.  If not
399   specified, the default value used will check for all 3 types of events.
400
401   +-------------------+------------------------------------------+
402   | Constant          | Meaning                                  |
403   +===================+==========================================+
404   | :const:`POLLIN`   | There is data to read                    |
405   +-------------------+------------------------------------------+
406   | :const:`POLLPRI`  | There is urgent data to read             |
407   +-------------------+------------------------------------------+
408   | :const:`POLLOUT`  | Ready for output: writing will not block |
409   +-------------------+------------------------------------------+
410   | :const:`POLLERR`  | Error condition of some sort             |
411   +-------------------+------------------------------------------+
412   | :const:`POLLHUP`  | Hung up                                  |
413   +-------------------+------------------------------------------+
414   | :const:`POLLRDHUP`| Stream socket peer closed connection, or |
415   |                   | shut down writing half of connection     |
416   +-------------------+------------------------------------------+
417   | :const:`POLLNVAL` | Invalid request: descriptor not open     |
418   +-------------------+------------------------------------------+
419
420   Registering a file descriptor that's already registered is not an error, and has
421   the same effect as registering the descriptor exactly once.
422
423
424.. method:: poll.modify(fd, eventmask)
425
426   Modifies an already registered fd. This has the same effect as
427   ``register(fd, eventmask)``.  Attempting to modify a file descriptor
428   that was never registered causes an :exc:`OSError` exception with errno
429   :const:`ENOENT` to be raised.
430
431
432.. method:: poll.unregister(fd)
433
434   Remove a file descriptor being tracked by a polling object.  Just like the
435   :meth:`register` method, *fd* can be an integer or an object with a
436   :meth:`~io.IOBase.fileno` method that returns an integer.
437
438   Attempting to remove a file descriptor that was never registered causes a
439   :exc:`KeyError` exception to be raised.
440
441
442.. method:: poll.poll([timeout])
443
444   Polls the set of registered file descriptors, and returns a possibly empty list
445   containing ``(fd, event)`` 2-tuples for the descriptors that have events or
446   errors to report. *fd* is the file descriptor, and *event* is a bitmask with
447   bits set for the reported events for that descriptor --- :const:`POLLIN` for
448   waiting input, :const:`POLLOUT` to indicate that the descriptor can be written
449   to, and so forth. An empty list indicates that the call timed out and no file
450   descriptors had any events to report. If *timeout* is given, it specifies the
451   length of time in milliseconds which the system will wait for events before
452   returning. If *timeout* is omitted, negative, or :const:`None`, the call will
453   block until there is an event for this poll object.
454
455   .. versionchanged:: 3.5
456      The function is now retried with a recomputed timeout when interrupted by
457      a signal, except if the signal handler raises an exception (see
458      :pep:`475` for the rationale), instead of raising
459      :exc:`InterruptedError`.
460
461
462.. _kqueue-objects:
463
464Kqueue Objects
465--------------
466
467.. method:: kqueue.close()
468
469   Close the control file descriptor of the kqueue object.
470
471
472.. attribute:: kqueue.closed
473
474   ``True`` if the kqueue object is closed.
475
476
477.. method:: kqueue.fileno()
478
479   Return the file descriptor number of the control fd.
480
481
482.. method:: kqueue.fromfd(fd)
483
484   Create a kqueue object from a given file descriptor.
485
486
487.. method:: kqueue.control(changelist, max_events[, timeout]) -> eventlist
488
489   Low level interface to kevent
490
491   - changelist must be an iterable of kevent objects or ``None``
492   - max_events must be 0 or a positive integer
493   - timeout in seconds (floats possible); the default is ``None``,
494     to wait forever
495
496   .. versionchanged:: 3.5
497      The function is now retried with a recomputed timeout when interrupted by
498      a signal, except if the signal handler raises an exception (see
499      :pep:`475` for the rationale), instead of raising
500      :exc:`InterruptedError`.
501
502
503.. _kevent-objects:
504
505Kevent Objects
506--------------
507
508https://man.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2
509
510.. attribute:: kevent.ident
511
512   Value used to identify the event. The interpretation depends on the filter
513   but it's usually the file descriptor. In the constructor ident can either
514   be an int or an object with a :meth:`~io.IOBase.fileno` method. kevent
515   stores the integer internally.
516
517.. attribute:: kevent.filter
518
519   Name of the kernel filter.
520
521   +---------------------------+---------------------------------------------+
522   | Constant                  | Meaning                                     |
523   +===========================+=============================================+
524   | :const:`KQ_FILTER_READ`   | Takes a descriptor and returns whenever     |
525   |                           | there is data available to read             |
526   +---------------------------+---------------------------------------------+
527   | :const:`KQ_FILTER_WRITE`  | Takes a descriptor and returns whenever     |
528   |                           | there is data available to write            |
529   +---------------------------+---------------------------------------------+
530   | :const:`KQ_FILTER_AIO`    | AIO requests                                |
531   +---------------------------+---------------------------------------------+
532   | :const:`KQ_FILTER_VNODE`  | Returns when one or more of the requested   |
533   |                           | events watched in *fflag* occurs            |
534   +---------------------------+---------------------------------------------+
535   | :const:`KQ_FILTER_PROC`   | Watch for events on a process id            |
536   +---------------------------+---------------------------------------------+
537   | :const:`KQ_FILTER_NETDEV` | Watch for events on a network device        |
538   |                           | [not available on macOS]                    |
539   +---------------------------+---------------------------------------------+
540   | :const:`KQ_FILTER_SIGNAL` | Returns whenever the watched signal is      |
541   |                           | delivered to the process                    |
542   +---------------------------+---------------------------------------------+
543   | :const:`KQ_FILTER_TIMER`  | Establishes an arbitrary timer              |
544   +---------------------------+---------------------------------------------+
545
546.. attribute:: kevent.flags
547
548   Filter action.
549
550   +---------------------------+---------------------------------------------+
551   | Constant                  | Meaning                                     |
552   +===========================+=============================================+
553   | :const:`KQ_EV_ADD`        | Adds or modifies an event                   |
554   +---------------------------+---------------------------------------------+
555   | :const:`KQ_EV_DELETE`     | Removes an event from the queue             |
556   +---------------------------+---------------------------------------------+
557   | :const:`KQ_EV_ENABLE`     | Permitscontrol() to returns the event       |
558   +---------------------------+---------------------------------------------+
559   | :const:`KQ_EV_DISABLE`    | Disablesevent                               |
560   +---------------------------+---------------------------------------------+
561   | :const:`KQ_EV_ONESHOT`    | Removes event after first occurrence        |
562   +---------------------------+---------------------------------------------+
563   | :const:`KQ_EV_CLEAR`      | Reset the state after an event is retrieved |
564   +---------------------------+---------------------------------------------+
565   | :const:`KQ_EV_SYSFLAGS`   | internal event                              |
566   +---------------------------+---------------------------------------------+
567   | :const:`KQ_EV_FLAG1`      | internal event                              |
568   +---------------------------+---------------------------------------------+
569   | :const:`KQ_EV_EOF`        | Filter specific EOF condition               |
570   +---------------------------+---------------------------------------------+
571   | :const:`KQ_EV_ERROR`      | See return values                           |
572   +---------------------------+---------------------------------------------+
573
574
575.. attribute:: kevent.fflags
576
577   Filter specific flags.
578
579   :const:`KQ_FILTER_READ` and  :const:`KQ_FILTER_WRITE` filter flags:
580
581   +----------------------------+--------------------------------------------+
582   | Constant                   | Meaning                                    |
583   +============================+============================================+
584   | :const:`KQ_NOTE_LOWAT`     | low water mark of a socket buffer          |
585   +----------------------------+--------------------------------------------+
586
587   :const:`KQ_FILTER_VNODE` filter flags:
588
589   +----------------------------+--------------------------------------------+
590   | Constant                   | Meaning                                    |
591   +============================+============================================+
592   | :const:`KQ_NOTE_DELETE`    | *unlink()* was called                      |
593   +----------------------------+--------------------------------------------+
594   | :const:`KQ_NOTE_WRITE`     | a write occurred                           |
595   +----------------------------+--------------------------------------------+
596   | :const:`KQ_NOTE_EXTEND`    | the file was extended                      |
597   +----------------------------+--------------------------------------------+
598   | :const:`KQ_NOTE_ATTRIB`    | an attribute was changed                   |
599   +----------------------------+--------------------------------------------+
600   | :const:`KQ_NOTE_LINK`      | the link count has changed                 |
601   +----------------------------+--------------------------------------------+
602   | :const:`KQ_NOTE_RENAME`    | the file was renamed                       |
603   +----------------------------+--------------------------------------------+
604   | :const:`KQ_NOTE_REVOKE`    | access to the file was revoked             |
605   +----------------------------+--------------------------------------------+
606
607   :const:`KQ_FILTER_PROC` filter flags:
608
609   +----------------------------+--------------------------------------------+
610   | Constant                   | Meaning                                    |
611   +============================+============================================+
612   | :const:`KQ_NOTE_EXIT`      | the process has exited                     |
613   +----------------------------+--------------------------------------------+
614   | :const:`KQ_NOTE_FORK`      | the process has called *fork()*            |
615   +----------------------------+--------------------------------------------+
616   | :const:`KQ_NOTE_EXEC`      | the process has executed a new process     |
617   +----------------------------+--------------------------------------------+
618   | :const:`KQ_NOTE_PCTRLMASK` | internal filter flag                       |
619   +----------------------------+--------------------------------------------+
620   | :const:`KQ_NOTE_PDATAMASK` | internal filter flag                       |
621   +----------------------------+--------------------------------------------+
622   | :const:`KQ_NOTE_TRACK`     | follow a process across *fork()*           |
623   +----------------------------+--------------------------------------------+
624   | :const:`KQ_NOTE_CHILD`     | returned on the child process for          |
625   |                            | *NOTE_TRACK*                               |
626   +----------------------------+--------------------------------------------+
627   | :const:`KQ_NOTE_TRACKERR`  | unable to attach to a child                |
628   +----------------------------+--------------------------------------------+
629
630   :const:`KQ_FILTER_NETDEV` filter flags (not available on macOS):
631
632   +----------------------------+--------------------------------------------+
633   | Constant                   | Meaning                                    |
634   +============================+============================================+
635   | :const:`KQ_NOTE_LINKUP`    | link is up                                 |
636   +----------------------------+--------------------------------------------+
637   | :const:`KQ_NOTE_LINKDOWN`  | link is down                               |
638   +----------------------------+--------------------------------------------+
639   | :const:`KQ_NOTE_LINKINV`   | link state is invalid                      |
640   +----------------------------+--------------------------------------------+
641
642
643.. attribute:: kevent.data
644
645   Filter specific data.
646
647
648.. attribute:: kevent.udata
649
650   User defined value.
651