1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2.. c:namespace:: CEC
3
4.. _cec-func-poll:
5
6**********
7cec poll()
8**********
9
10Name
11====
12
13cec-poll - Wait for some event on a file descriptor
14
15Synopsis
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
24Arguments
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
36Description
37===========
38
39With the :c:func:`poll()` function applications can wait for CEC
40events.
41
42On success :c:func:`poll()` returns the number of file descriptors
43that have been selected (that is, file descriptors for which the
44``revents`` field of the respective struct :c:type:`pollfd`
45is non-zero). CEC devices set the ``POLLIN`` and ``POLLRDNORM`` flags in
46the ``revents`` field if there are messages in the receive queue. If the
47transmit queue has room for new messages, the ``POLLOUT`` and
48``POLLWRNORM`` flags are set. If there are events in the event queue,
49then the ``POLLPRI`` flag is set. When the function times out it returns
50a value of zero, on failure it returns -1 and the ``errno`` variable is
51set appropriately.
52
53For more details see the :c:func:`poll()` manual page.
54
55Return Value
56============
57
58On success, :c:func:`poll()` returns the number structures which have
59non-zero ``revents`` fields, or zero if the call timed out. On error -1
60is 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.
75