Documentation/userspace-api/media/cec/cec-func-poll.rst

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