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

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