select.rst 27.6 KB
Newer Older
1 2 3 4 5 6
:mod:`select` --- Waiting for I/O completion
============================================

.. module:: select
   :synopsis: Wait for I/O completion on multiple streams.

7
--------------
8

9
This module provides access to the :c:func:`select` and :c:func:`poll` functions
10 11
available in most operating systems, :c:func:`devpoll` available on
Solaris and derivatives, :c:func:`epoll` available on Linux 2.5+ and
12
:c:func:`kqueue` available on most BSD.
Christian Heimes's avatar
Christian Heimes committed
13 14 15 16
Note that on Windows, it only works for sockets; on other operating systems,
it also works for other file types (in particular, on Unix, it works on pipes).
It cannot be used on regular files to determine whether a file has grown since
it was last read.
17

18 19 20 21 22 23 24 25
.. note::

   The :mod:`selectors` module allows high-level and efficient I/O
   multiplexing, built upon the :mod:`select` module primitives. Users are
   encouraged to use the :mod:`selectors` module instead, unless they want
   precise control over the OS-level primitives used.


26 27 28 29 30
The module defines the following:


.. exception:: error

31 32 33 34
   A deprecated alias of :exc:`OSError`.

   .. versionchanged:: 3.3
      Following :pep:`3151`, this class was made an alias of :exc:`OSError`.
35 36


37
.. function:: devpoll()
Jesus Cea's avatar
Jesus Cea committed
38

39 40 41 42 43 44 45
   (Only supported on Solaris and derivatives.)  Returns a ``/dev/poll``
   polling object; see section :ref:`devpoll-objects` below for the
   methods supported by devpoll objects.

   :c:func:`devpoll` objects are linked to the number of file
   descriptors allowed at the time of instantiation. If your program
   reduces this value, :c:func:`devpoll` will fail. If your program
Jesus Cea's avatar
Jesus Cea committed
46
   increases this value, :c:func:`devpoll` may return an
47 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 55
   .. versionchanged:: 3.4
      The new file descriptor is now non-inheritable.

56
.. function:: epoll(sizehint=-1, flags=0)
Christian Heimes's avatar
Christian Heimes committed
57

58 59
   (Only supported on Linux 2.5.44 and newer.) Return an edge polling object,
   which can be used as Edge or Level Triggered interface for I/O
60 61 62 63 64 65 66 67 68 69
   events.

   *sizehint* informs epoll about the expected number of events to be
   registered.  It must be positive, or `-1` to use the default. It is only
   used on older systems where :c:func:`epoll_create1` is not available;
   otherwise it has no effect (though its value is still checked).

   *flags* is deprecated and completely ignored.  However, when supplied, its
   value must be ``0`` or ``select.EPOLL_CLOEXEC``, otherwise ``OSError`` is
   raised.
70 71 72 73 74 75 76

   See the :ref:`epoll-objects` section below for the methods supported by
   epolling objects.

   ``epoll`` objects support the context management protocol: when used in a
   :keyword:`with` statement, the new file descriptor is automatically closed
   at the end of the block.
77

78 79
   The new file descriptor is :ref:`non-inheritable <fd_inheritance>`.

80 81
   .. versionchanged:: 3.3
      Added the *flags* parameter.
Christian Heimes's avatar
Christian Heimes committed
82

83 84
   .. versionchanged:: 3.4
      Support for the :keyword:`with` statement was added.
85
      The new file descriptor is now non-inheritable.
86

87 88 89 90
   .. deprecated:: 3.4
      The *flags* parameter.  ``select.EPOLL_CLOEXEC`` is used by default now.
      Use :func:`os.set_inheritable` to make the file descriptor inheritable.

Christian Heimes's avatar
Christian Heimes committed
91

92 93 94 95 96 97 98 99
.. function:: poll()

   (Not supported by all operating systems.)  Returns a polling object, which
   supports registering and unregistering file descriptors, and then polling them
   for I/O events; see section :ref:`poll-objects` below for the methods supported
   by polling objects.


Christian Heimes's avatar
Christian Heimes committed
100
.. function:: kqueue()
Christian Heimes's avatar
Christian Heimes committed
101

102
   (Only supported on BSD.)  Returns a kernel queue object; see section
Christian Heimes's avatar
Christian Heimes committed
103
   :ref:`kqueue-objects` below for the methods supported by kqueue objects.
Christian Heimes's avatar
Christian Heimes committed
104

105 106 107 108 109
   The new file descriptor is :ref:`non-inheritable <fd_inheritance>`.

   .. versionchanged:: 3.4
      The new file descriptor is now non-inheritable.

Christian Heimes's avatar
Christian Heimes committed
110

Benjamin Peterson's avatar
Benjamin Peterson committed
111
.. function:: kevent(ident, filter=KQ_FILTER_READ, flags=KQ_EV_ADD, fflags=0, data=0, udata=0)
Christian Heimes's avatar
Christian Heimes committed
112

113 114
   (Only supported on BSD.)  Returns a kernel event object; see section
   :ref:`kevent-objects` below for the methods supported by kevent objects.
Christian Heimes's avatar
Christian Heimes committed
115 116


Georg Brandl's avatar
Georg Brandl committed
117
.. function:: select(rlist, wlist, xlist[, timeout])
118

119
   This is a straightforward interface to the Unix :c:func:`select` system call.
120 121
   The first three arguments are sequences of 'waitable objects': either
   integers representing file descriptors or objects with a parameterless method
122
   named :meth:`~io.IOBase.fileno` returning such an integer:
Georg Brandl's avatar
Georg Brandl committed
123 124 125 126 127 128 129 130 131 132 133 134

   * *rlist*: wait until ready for reading
   * *wlist*: wait until ready for writing
   * *xlist*: wait for an "exceptional condition" (see the manual page for what
     your system considers such a condition)

   Empty sequences are allowed, but acceptance of three empty sequences is
   platform-dependent. (It is known to work on Unix but not on Windows.)  The
   optional *timeout* argument specifies a time-out as a floating point number
   in seconds.  When the *timeout* argument is omitted the function blocks until
   at least one file descriptor is ready.  A time-out value of zero specifies a
   poll and never blocks.
135 136 137 138 139 140 141 142 143

   The return value is a triple of lists of objects that are ready: subsets of the
   first three arguments.  When the time-out is reached without a file descriptor
   becoming ready, three empty lists are returned.

   .. index::
      single: socket() (in module socket)
      single: popen() (in module os)

144 145 146 147
   Among the acceptable object types in the sequences are Python :term:`file
   objects <file object>` (e.g. ``sys.stdin``, or objects returned by
   :func:`open` or :func:`os.popen`), socket objects returned by
   :func:`socket.socket`.  You may also define a :dfn:`wrapper` class yourself,
148 149
   as long as it has an appropriate :meth:`~io.IOBase.fileno` method (that
   really returns a file descriptor, not just a random integer).
150 151 152 153 154

   .. note::

      .. index:: single: WinSock

Georg Brandl's avatar
Georg Brandl committed
155
      File objects on Windows are not acceptable, but sockets are.  On Windows,
156
      the underlying :c:func:`select` function is provided by the WinSock
Georg Brandl's avatar
Georg Brandl committed
157 158
      library, and does not handle file descriptors that don't originate from
      WinSock.
159

160 161 162 163 164 165 166
   .. versionchanged:: 3.5
      The function is now retried with a recomputed timeout when interrupted by
      a signal, except if the signal handler raises an exception (see
      :pep:`475` for the rationale), instead of raising
      :exc:`InterruptedError`.


167
.. attribute:: PIPE_BUF
168

169
   The minimum number of bytes which can be written without blocking to a pipe
170
   when the pipe has been reported as ready for writing by :func:`~select.select`,
171 172 173
   :func:`poll` or another interface in this module.  This doesn't apply
   to other kind of file-like objects such as sockets.

174 175 176
   This value is guaranteed by POSIX to be at least 512.

   .. availability:: Unix
177

178
   .. versionadded:: 3.2
179

180

181 182 183
.. _devpoll-objects:

``/dev/poll`` Polling Objects
184
-----------------------------
185 186 187 188 189 190 191 192 193

Solaris and derivatives have ``/dev/poll``. While :c:func:`select` is
O(highest file descriptor) and :c:func:`poll` is O(number of file
descriptors), ``/dev/poll`` is O(active file descriptors).

``/dev/poll`` behaviour is very close to the standard :c:func:`poll`
object.


194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214
.. method:: devpoll.close()

   Close the file descriptor of the polling object.

   .. versionadded:: 3.4


.. attribute:: devpoll.closed

   ``True`` if the polling object is closed.

   .. versionadded:: 3.4


.. method:: devpoll.fileno()

   Return the file descriptor number of the polling object.

   .. versionadded:: 3.4


215 216 217
.. method:: devpoll.register(fd[, eventmask])

   Register a file descriptor with the polling object.  Future calls to the
218 219 220 221
   :meth:`poll` method will then check whether the file descriptor has any
   pending I/O events.  *fd* can be either an integer, or an object with a
   :meth:`~io.IOBase.fileno` method that returns an integer.  File objects
   implement :meth:`!fileno`, so they can also be used as the argument.
222 223 224 225 226 227 228 229 230

   *eventmask* is an optional bitmask describing the type of events you want to
   check for. The constants are the same that with :c:func:`poll`
   object. The default value is a combination of the constants :const:`POLLIN`,
   :const:`POLLPRI`, and :const:`POLLOUT`.

   .. warning::

      Registering a file descriptor that's already registered is not an
231
      error, but the result is undefined. The appropriate action is to
232 233 234 235 236 237 238 239 240 241 242 243 244 245 246
      unregister or modify it first. This is an important difference
      compared with :c:func:`poll`.


.. method:: devpoll.modify(fd[, eventmask])

   This method does an :meth:`unregister` followed by a
   :meth:`register`. It is (a bit) more efficient that doing the same
   explicitly.


.. method:: devpoll.unregister(fd)

   Remove a file descriptor being tracked by a polling object.  Just like the
   :meth:`register` method, *fd* can be an integer or an object with a
247
   :meth:`~io.IOBase.fileno` method that returns an integer.
248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265

   Attempting to remove a file descriptor that was never registered is
   safely ignored.


.. method:: devpoll.poll([timeout])

   Polls the set of registered file descriptors, and returns a possibly-empty list
   containing ``(fd, event)`` 2-tuples for the descriptors that have events or
   errors to report. *fd* is the file descriptor, and *event* is a bitmask with
   bits set for the reported events for that descriptor --- :const:`POLLIN` for
   waiting input, :const:`POLLOUT` to indicate that the descriptor can be written
   to, and so forth. An empty list indicates that the call timed out and no file
   descriptors had any events to report. If *timeout* is given, it specifies the
   length of time in milliseconds which the system will wait for events before
   returning. If *timeout* is omitted, -1, or :const:`None`, the call will
   block until there is an event for this poll object.

266 267 268 269 270 271
   .. versionchanged:: 3.5
      The function is now retried with a recomputed timeout when interrupted by
      a signal, except if the signal handler raises an exception (see
      :pep:`475` for the rationale), instead of raising
      :exc:`InterruptedError`.

272

Christian Heimes's avatar
Christian Heimes committed
273 274 275 276 277
.. _epoll-objects:

Edge and Level Trigger Polling (epoll) Objects
----------------------------------------------

278
   https://linux.die.net/man/4/epoll
Christian Heimes's avatar
Christian Heimes committed
279 280 281

   *eventmask*

Benjamin Peterson's avatar
Benjamin Peterson committed
282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303
   +-------------------------+-----------------------------------------------+
   | Constant                | Meaning                                       |
   +=========================+===============================================+
   | :const:`EPOLLIN`        | Available for read                            |
   +-------------------------+-----------------------------------------------+
   | :const:`EPOLLOUT`       | Available for write                           |
   +-------------------------+-----------------------------------------------+
   | :const:`EPOLLPRI`       | Urgent data for read                          |
   +-------------------------+-----------------------------------------------+
   | :const:`EPOLLERR`       | Error condition happened on the assoc. fd     |
   +-------------------------+-----------------------------------------------+
   | :const:`EPOLLHUP`       | Hang up happened on the assoc. fd             |
   +-------------------------+-----------------------------------------------+
   | :const:`EPOLLET`        | Set Edge Trigger behavior, the default is     |
   |                         | Level Trigger behavior                        |
   +-------------------------+-----------------------------------------------+
   | :const:`EPOLLONESHOT`   | Set one-shot behavior. After one event is     |
   |                         | pulled out, the fd is internally disabled     |
   +-------------------------+-----------------------------------------------+
   | :const:`EPOLLEXCLUSIVE` | Wake only one epoll object when the           |
   |                         | associated fd has an event. The default (if   |
   |                         | this flag is not set) is to wake all epoll    |
304
   |                         | objects polling on a fd.                      |
Benjamin Peterson's avatar
Benjamin Peterson committed
305 306 307 308 309 310 311 312 313 314 315 316 317 318
   +-------------------------+-----------------------------------------------+
   | :const:`EPOLLRDHUP`     | Stream socket peer closed connection or shut  |
   |                         | down writing half of connection.              |
   +-------------------------+-----------------------------------------------+
   | :const:`EPOLLRDNORM`    | Equivalent to :const:`EPOLLIN`                |
   +-------------------------+-----------------------------------------------+
   | :const:`EPOLLRDBAND`    | Priority data band can be read.               |
   +-------------------------+-----------------------------------------------+
   | :const:`EPOLLWRNORM`    | Equivalent to :const:`EPOLLOUT`               |
   +-------------------------+-----------------------------------------------+
   | :const:`EPOLLWRBAND`    | Priority data may be written.                 |
   +-------------------------+-----------------------------------------------+
   | :const:`EPOLLMSG`       | Ignored.                                      |
   +-------------------------+-----------------------------------------------+
Christian Heimes's avatar
Christian Heimes committed
319

320 321 322
   .. versionadded:: 3.6
      :const:`EPOLLEXCLUSIVE` was added.  It's only supported by Linux Kernel 4.5
      or later.
Christian Heimes's avatar
Christian Heimes committed
323 324 325 326 327 328

.. method:: epoll.close()

   Close the control file descriptor of the epoll object.


329 330 331 332 333
.. attribute:: epoll.closed

   ``True`` if the epoll object is closed.


Christian Heimes's avatar
Christian Heimes committed
334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350
.. method:: epoll.fileno()

   Return the file descriptor number of the control fd.


.. method:: epoll.fromfd(fd)

   Create an epoll object from a given file descriptor.


.. method:: epoll.register(fd[, eventmask])

   Register a fd descriptor with the epoll object.


.. method:: epoll.modify(fd, eventmask)

Georg Brandl's avatar
Georg Brandl committed
351
   Modify a registered file descriptor.
Christian Heimes's avatar
Christian Heimes committed
352 353 354 355 356 357 358


.. method:: epoll.unregister(fd)

   Remove a registered file descriptor from the epoll object.


359
.. method:: epoll.poll(timeout=None, maxevents=-1)
Christian Heimes's avatar
Christian Heimes committed
360 361 362

   Wait for events. timeout in seconds (float)

363 364 365 366 367 368
   .. versionchanged:: 3.5
      The function is now retried with a recomputed timeout when interrupted by
      a signal, except if the signal handler raises an exception (see
      :pep:`475` for the rationale), instead of raising
      :exc:`InterruptedError`.

Christian Heimes's avatar
Christian Heimes committed
369

370 371 372 373 374
.. _poll-objects:

Polling Objects
---------------

375
The :c:func:`poll` system call, supported on most Unix systems, provides better
376
scalability for network servers that service many, many clients at the same
377 378
time. :c:func:`poll` scales better because the system call only requires listing
the file descriptors of interest, while :c:func:`select` builds a bitmap, turns
379
on bits for the fds of interest, and then afterward the whole bitmap has to be
380 381
linearly scanned again. :c:func:`select` is O(highest file descriptor), while
:c:func:`poll` is O(number of file descriptors).
382 383 384 385 386


.. method:: poll.register(fd[, eventmask])

   Register a file descriptor with the polling object.  Future calls to the
387 388 389 390
   :meth:`poll` method will then check whether the file descriptor has any
   pending I/O events.  *fd* can be either an integer, or an object with a
   :meth:`~io.IOBase.fileno` method that returns an integer.  File objects
   implement :meth:`!fileno`, so they can also be used as the argument.
391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409

   *eventmask* is an optional bitmask describing the type of events you want to
   check for, and can be a combination of the constants :const:`POLLIN`,
   :const:`POLLPRI`, and :const:`POLLOUT`, described in the table below.  If not
   specified, the default value used will check for all 3 types of events.

   +-------------------+------------------------------------------+
   | Constant          | Meaning                                  |
   +===================+==========================================+
   | :const:`POLLIN`   | There is data to read                    |
   +-------------------+------------------------------------------+
   | :const:`POLLPRI`  | There is urgent data to read             |
   +-------------------+------------------------------------------+
   | :const:`POLLOUT`  | Ready for output: writing will not block |
   +-------------------+------------------------------------------+
   | :const:`POLLERR`  | Error condition of some sort             |
   +-------------------+------------------------------------------+
   | :const:`POLLHUP`  | Hung up                                  |
   +-------------------+------------------------------------------+
410 411 412
   | :const:`POLLRDHUP`| Stream socket peer closed connection, or |
   |                   | shut down writing half of connection     |
   +-------------------+------------------------------------------+
413 414 415 416 417 418 419
   | :const:`POLLNVAL` | Invalid request: descriptor not open     |
   +-------------------+------------------------------------------+

   Registering a file descriptor that's already registered is not an error, and has
   the same effect as registering the descriptor exactly once.


Christian Heimes's avatar
Christian Heimes committed
420 421 422
.. method:: poll.modify(fd, eventmask)

   Modifies an already registered fd. This has the same effect as
423
   ``register(fd, eventmask)``.  Attempting to modify a file descriptor
424
   that was never registered causes an :exc:`OSError` exception with errno
Christian Heimes's avatar
Christian Heimes committed
425 426 427
   :const:`ENOENT` to be raised.


428 429 430 431
.. method:: poll.unregister(fd)

   Remove a file descriptor being tracked by a polling object.  Just like the
   :meth:`register` method, *fd* can be an integer or an object with a
432
   :meth:`~io.IOBase.fileno` method that returns an integer.
433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450

   Attempting to remove a file descriptor that was never registered causes a
   :exc:`KeyError` exception to be raised.


.. method:: poll.poll([timeout])

   Polls the set of registered file descriptors, and returns a possibly-empty list
   containing ``(fd, event)`` 2-tuples for the descriptors that have events or
   errors to report. *fd* is the file descriptor, and *event* is a bitmask with
   bits set for the reported events for that descriptor --- :const:`POLLIN` for
   waiting input, :const:`POLLOUT` to indicate that the descriptor can be written
   to, and so forth. An empty list indicates that the call timed out and no file
   descriptors had any events to report. If *timeout* is given, it specifies the
   length of time in milliseconds which the system will wait for events before
   returning. If *timeout* is omitted, negative, or :const:`None`, the call will
   block until there is an event for this poll object.

451 452 453 454 455 456
   .. versionchanged:: 3.5
      The function is now retried with a recomputed timeout when interrupted by
      a signal, except if the signal handler raises an exception (see
      :pep:`475` for the rationale), instead of raising
      :exc:`InterruptedError`.

Christian Heimes's avatar
Christian Heimes committed
457 458 459 460 461 462 463 464 465 466 467

.. _kqueue-objects:

Kqueue Objects
--------------

.. method:: kqueue.close()

   Close the control file descriptor of the kqueue object.


468 469 470 471 472
.. attribute:: kqueue.closed

   ``True`` if the kqueue object is closed.


Christian Heimes's avatar
Christian Heimes committed
473 474 475 476 477
.. method:: kqueue.fileno()

   Return the file descriptor number of the control fd.


Benjamin Peterson's avatar
Benjamin Peterson committed
478
.. method:: kqueue.fromfd(fd)
Christian Heimes's avatar
Christian Heimes committed
479 480 481 482

   Create a kqueue object from a given file descriptor.


483
.. method:: kqueue.control(changelist, max_events[, timeout=None]) -> eventlist
Christian Heimes's avatar
Christian Heimes committed
484 485 486

   Low level interface to kevent

487
   - changelist must be an iterable of kevent object or ``None``
Christian Heimes's avatar
Christian Heimes committed
488 489 490
   - max_events must be 0 or a positive integer
   - timeout in seconds (floats possible)

491 492 493 494 495 496
   .. versionchanged:: 3.5
      The function is now retried with a recomputed timeout when interrupted by
      a signal, except if the signal handler raises an exception (see
      :pep:`475` for the rationale), instead of raising
      :exc:`InterruptedError`.

Christian Heimes's avatar
Christian Heimes committed
497 498 499 500 501 502

.. _kevent-objects:

Kevent Objects
--------------

503
https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2
Christian Heimes's avatar
Christian Heimes committed
504

Christian Heimes's avatar
Christian Heimes committed
505
.. attribute:: kevent.ident
Christian Heimes's avatar
Christian Heimes committed
506 507 508

   Value used to identify the event. The interpretation depends on the filter
   but it's usually the file descriptor. In the constructor ident can either
509 510
   be an int or an object with a :meth:`~io.IOBase.fileno` method. kevent
   stores the integer internally.
Christian Heimes's avatar
Christian Heimes committed
511

Christian Heimes's avatar
Christian Heimes committed
512
.. attribute:: kevent.filter
Christian Heimes's avatar
Christian Heimes committed
513

514
   Name of the kernel filter.
Christian Heimes's avatar
Christian Heimes committed
515 516 517 518 519 520 521 522

   +---------------------------+---------------------------------------------+
   | Constant                  | Meaning                                     |
   +===========================+=============================================+
   | :const:`KQ_FILTER_READ`   | Takes a descriptor and returns whenever     |
   |                           | there is data available to read             |
   +---------------------------+---------------------------------------------+
   | :const:`KQ_FILTER_WRITE`  | Takes a descriptor and returns whenever     |
523
   |                           | there is data available to write            |
Christian Heimes's avatar
Christian Heimes committed
524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540
   +---------------------------+---------------------------------------------+
   | :const:`KQ_FILTER_AIO`    | AIO requests                                |
   +---------------------------+---------------------------------------------+
   | :const:`KQ_FILTER_VNODE`  | Returns when one or more of the requested   |
   |                           | events watched in *fflag* occurs            |
   +---------------------------+---------------------------------------------+
   | :const:`KQ_FILTER_PROC`   | Watch for events on a process id            |
   +---------------------------+---------------------------------------------+
   | :const:`KQ_FILTER_NETDEV` | Watch for events on a network device        |
   |                           | [not available on Mac OS X]                 |
   +---------------------------+---------------------------------------------+
   | :const:`KQ_FILTER_SIGNAL` | Returns whenever the watched signal is      |
   |                           | delivered to the process                    |
   +---------------------------+---------------------------------------------+
   | :const:`KQ_FILTER_TIMER`  | Establishes an arbitrary timer              |
   +---------------------------+---------------------------------------------+

Christian Heimes's avatar
Christian Heimes committed
541
.. attribute:: kevent.flags
Christian Heimes's avatar
Christian Heimes committed
542

543
   Filter action.
Christian Heimes's avatar
Christian Heimes committed
544 545 546 547 548 549 550 551 552 553 554 555

   +---------------------------+---------------------------------------------+
   | Constant                  | Meaning                                     |
   +===========================+=============================================+
   | :const:`KQ_EV_ADD`        | Adds or modifies an event                   |
   +---------------------------+---------------------------------------------+
   | :const:`KQ_EV_DELETE`     | Removes an event from the queue             |
   +---------------------------+---------------------------------------------+
   | :const:`KQ_EV_ENABLE`     | Permitscontrol() to returns the event       |
   +---------------------------+---------------------------------------------+
   | :const:`KQ_EV_DISABLE`    | Disablesevent                               |
   +---------------------------+---------------------------------------------+
Georg Brandl's avatar
Georg Brandl committed
556
   | :const:`KQ_EV_ONESHOT`    | Removes event after first occurrence        |
Christian Heimes's avatar
Christian Heimes committed
557 558 559 560 561 562 563 564 565 566 567 568 569
   +---------------------------+---------------------------------------------+
   | :const:`KQ_EV_CLEAR`      | Reset the state after an event is retrieved |
   +---------------------------+---------------------------------------------+
   | :const:`KQ_EV_SYSFLAGS`   | internal event                              |
   +---------------------------+---------------------------------------------+
   | :const:`KQ_EV_FLAG1`      | internal event                              |
   +---------------------------+---------------------------------------------+
   | :const:`KQ_EV_EOF`        | Filter specific EOF condition               |
   +---------------------------+---------------------------------------------+
   | :const:`KQ_EV_ERROR`      | See return values                           |
   +---------------------------+---------------------------------------------+


Christian Heimes's avatar
Christian Heimes committed
570
.. attribute:: kevent.fflags
Christian Heimes's avatar
Christian Heimes committed
571

572
   Filter specific flags.
Christian Heimes's avatar
Christian Heimes committed
573

574
   :const:`KQ_FILTER_READ` and  :const:`KQ_FILTER_WRITE` filter flags:
Christian Heimes's avatar
Christian Heimes committed
575 576 577 578 579 580 581

   +----------------------------+--------------------------------------------+
   | Constant                   | Meaning                                    |
   +============================+============================================+
   | :const:`KQ_NOTE_LOWAT`     | low water mark of a socket buffer          |
   +----------------------------+--------------------------------------------+

582
   :const:`KQ_FILTER_VNODE` filter flags:
Christian Heimes's avatar
Christian Heimes committed
583 584 585 586 587 588

   +----------------------------+--------------------------------------------+
   | Constant                   | Meaning                                    |
   +============================+============================================+
   | :const:`KQ_NOTE_DELETE`    | *unlink()* was called                      |
   +----------------------------+--------------------------------------------+
Georg Brandl's avatar
Georg Brandl committed
589
   | :const:`KQ_NOTE_WRITE`     | a write occurred                           |
Christian Heimes's avatar
Christian Heimes committed
590 591 592 593 594 595 596 597 598 599 600 601
   +----------------------------+--------------------------------------------+
   | :const:`KQ_NOTE_EXTEND`    | the file was extended                      |
   +----------------------------+--------------------------------------------+
   | :const:`KQ_NOTE_ATTRIB`    | an attribute was changed                   |
   +----------------------------+--------------------------------------------+
   | :const:`KQ_NOTE_LINK`      | the link count has changed                 |
   +----------------------------+--------------------------------------------+
   | :const:`KQ_NOTE_RENAME`    | the file was renamed                       |
   +----------------------------+--------------------------------------------+
   | :const:`KQ_NOTE_REVOKE`    | access to the file was revoked             |
   +----------------------------+--------------------------------------------+

602
   :const:`KQ_FILTER_PROC` filter flags:
Christian Heimes's avatar
Christian Heimes committed
603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624

   +----------------------------+--------------------------------------------+
   | Constant                   | Meaning                                    |
   +============================+============================================+
   | :const:`KQ_NOTE_EXIT`      | the process has exited                     |
   +----------------------------+--------------------------------------------+
   | :const:`KQ_NOTE_FORK`      | the process has called *fork()*            |
   +----------------------------+--------------------------------------------+
   | :const:`KQ_NOTE_EXEC`      | the process has executed a new process     |
   +----------------------------+--------------------------------------------+
   | :const:`KQ_NOTE_PCTRLMASK` | internal filter flag                       |
   +----------------------------+--------------------------------------------+
   | :const:`KQ_NOTE_PDATAMASK` | internal filter flag                       |
   +----------------------------+--------------------------------------------+
   | :const:`KQ_NOTE_TRACK`     | follow a process across *fork()*           |
   +----------------------------+--------------------------------------------+
   | :const:`KQ_NOTE_CHILD`     | returned on the child process for          |
   |                            | *NOTE_TRACK*                               |
   +----------------------------+--------------------------------------------+
   | :const:`KQ_NOTE_TRACKERR`  | unable to attach to a child                |
   +----------------------------+--------------------------------------------+

625
   :const:`KQ_FILTER_NETDEV` filter flags (not available on Mac OS X):
Christian Heimes's avatar
Christian Heimes committed
626 627 628 629 630 631 632 633 634 635 636 637

   +----------------------------+--------------------------------------------+
   | Constant                   | Meaning                                    |
   +============================+============================================+
   | :const:`KQ_NOTE_LINKUP`    | link is up                                 |
   +----------------------------+--------------------------------------------+
   | :const:`KQ_NOTE_LINKDOWN`  | link is down                               |
   +----------------------------+--------------------------------------------+
   | :const:`KQ_NOTE_LINKINV`   | link state is invalid                      |
   +----------------------------+--------------------------------------------+


Christian Heimes's avatar
Christian Heimes committed
638
.. attribute:: kevent.data
Christian Heimes's avatar
Christian Heimes committed
639

640
   Filter specific data.
Christian Heimes's avatar
Christian Heimes committed
641 642


Christian Heimes's avatar
Christian Heimes committed
643
.. attribute:: kevent.udata
Christian Heimes's avatar
Christian Heimes committed
644

645
   User defined value.