1.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
2.. c:namespace:: MC
3
4.. _request-func-poll:
5
6**************
7request poll()
8**************
9
10Name
11====
12
13request-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 file descriptor events to be watched
29
30``nfds``
31   Number of file descriptor 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
40for a request to complete.
41
42On success :c:func:`poll()` returns the number of file
43descriptors that have been selected (that is, file descriptors for which the
44``revents`` field of the respective struct :c:type:`pollfd`
45is non-zero). Request file descriptor set the ``POLLPRI`` flag in ``revents``
46when the request was completed.  When the function times out it returns
47a value of zero, on failure it returns -1 and the ``errno`` variable is
48set appropriately.
49
50Attempting to poll for a request that is not yet queued will
51set the ``POLLERR`` flag in ``revents``.
52
53Return Value
54============
55
56On success, :c:func:`poll()` returns the number of
57structures which have non-zero ``revents`` fields, or zero if the call
58timed out. On error -1 is returned, and the ``errno`` variable is set
59appropriately:
60
61``EBADF``
62    One or more of the ``ufds`` members specify an invalid file
63    descriptor.
64
65``EFAULT``
66    ``ufds`` references an inaccessible memory area.
67
68``EINTR``
69    The call was interrupted by a signal.
70
71``EINVAL``
72    The ``nfds`` value exceeds the ``RLIMIT_NOFILE`` value. Use
73    ``getrlimit()`` to obtain this value.
74