Documentation/media/uapi/cec/cec-func-poll.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _cec-func-poll:
   4
   5 **********
   6 cec poll()
   7 **********
   8
   9 Name
  10 ====
  11
  12 cec-poll - Wait for some event on a file descriptor
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. code-block:: c
  19
  20     #include <sys/poll.h>
  21
  22
  23 .. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout )
  24    :name: cec-poll
  25
  26 Arguments
  27 =========
  28
  29 ``ufds``
  30    List of FD events to be watched
  31
  32 ``nfds``
  33    Number of FD efents at the \*ufds array
  34
  35 ``timeout``
  36    Timeout to wait for events
  37
  38
  39 Description
  40 ===========
  41
  42 .. note::
  43
  44    This documents the proposed CEC API. This API is not yet finalized
  45    and is currently only available as a staging kernel module.
  46
  47 With the :c:func:`poll()` function applications can wait for CEC
  48 events.
  49
  50 On success :c:func:`poll()` returns the number of file descriptors
  51 that have been selected (that is, file descriptors for which the
  52 ``revents`` field of the respective struct :c:type:`pollfd`
  53 is non-zero). CEC devices set the ``POLLIN`` and ``POLLRDNORM`` flags in
  54 the ``revents`` field if there are messages in the receive queue. If the
  55 transmit queue has room for new messages, the ``POLLOUT`` and
  56 ``POLLWRNORM`` flags are set. If there are events in the event queue,
  57 then the ``POLLPRI`` flag is set. When the function timed out it returns
  58 a value of zero, on failure it returns -1 and the ``errno`` variable is
  59 set appropriately.
  60
  61 For more details see the :c:func:`poll()` manual page.
  62
  63
  64 Return Value
  65 ============
  66
  67 On success, :c:func:`poll()` returns the number structures which have
  68 non-zero ``revents`` fields, or zero if the call timed out. On error -1
  69 is returned, and the ``errno`` variable is set appropriately:
  70
  71 ``EBADF``
  72     One or more of the ``ufds`` members specify an invalid file
  73     descriptor.
  74
  75 ``EFAULT``
  76     ``ufds`` references an inaccessible memory area.
  77
  78 ``EINTR``
  79     The call was interrupted by a signal.
  80
  81 ``EINVAL``
  82     The ``nfds`` argument is greater than ``OPEN_MAX``.