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/userspace-api/media/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**********
13cec poll()
14**********
15
16Name
17====
18
19cec-poll - Wait for some event on a file descriptor
20
21
22Synopsis
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
33Arguments
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
46Description
47===========
48
49With the :c:func:`poll() <cec-poll>` function applications can wait for CEC
50events.
51
52On success :c:func:`poll() <cec-poll>` returns the number of file descriptors
53that have been selected (that is, file descriptors for which the
54``revents`` field of the respective struct :c:type:`pollfd`
55is non-zero). CEC devices set the ``POLLIN`` and ``POLLRDNORM`` flags in
56the ``revents`` field if there are messages in the receive queue. If the
57transmit queue has room for new messages, the ``POLLOUT`` and
58``POLLWRNORM`` flags are set. If there are events in the event queue,
59then the ``POLLPRI`` flag is set. When the function times out it returns
60a value of zero, on failure it returns -1 and the ``errno`` variable is
61set appropriately.
62
63For more details see the :c:func:`poll() <cec-poll>` manual page.
64
65
66Return Value
67============
68
69On success, :c:func:`poll() <cec-poll>` returns the number structures which have
70non-zero ``revents`` fields, or zero if the call timed out. On error -1
71is 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.
86