1.. This file is dual-licensed: you can use it either under the terms
2.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this
3.. dual licensing only applies to this file, and not this project as a
4.. whole.
5..
6.. a) This file is free software; you can redistribute it and/or
7..    modify it under the terms of the GNU General Public License as
8..    published by the Free Software Foundation version 2 of
9..    the License.
10..
11..    This file is distributed in the hope that it will be useful,
12..    but WITHOUT ANY WARRANTY; without even the implied warranty of
13..    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14..    GNU General Public License for more details.
15..
16.. Or, alternatively,
17..
18.. b) Permission is granted to copy, distribute and/or modify this
19..    document under the terms of the GNU Free Documentation License,
20..    Version 1.1 or any later version published by the Free Software
21..    Foundation, with no Invariant Sections, no Front-Cover Texts
22..    and no Back-Cover Texts. A copy of the license is included at
23..    Documentation/userspace-api/media/fdl-appendix.rst.
24..
25.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections
26
27.. _request-func-poll:
28
29**************
30request poll()
31**************
32
33Name
34====
35
36request-poll - Wait for some event on a file descriptor
37
38
39Synopsis
40========
41
42.. code-block:: c
43
44    #include <sys/poll.h>
45
46
47.. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout )
48   :name: request-poll
49
50Arguments
51=========
52
53``ufds``
54   List of file descriptor events to be watched
55
56``nfds``
57   Number of file descriptor events at the \*ufds array
58
59``timeout``
60   Timeout to wait for events
61
62
63Description
64===========
65
66With the :c:func:`poll() <request-func-poll>` function applications can wait
67for a request to complete.
68
69On success :c:func:`poll() <request-func-poll>` returns the number of file
70descriptors that have been selected (that is, file descriptors for which the
71``revents`` field of the respective struct :c:type:`pollfd`
72is non-zero). Request file descriptor set the ``POLLPRI`` flag in ``revents``
73when the request was completed.  When the function times out it returns
74a value of zero, on failure it returns -1 and the ``errno`` variable is
75set appropriately.
76
77Attempting to poll for a request that is not yet queued will
78set the ``POLLERR`` flag in ``revents``.
79
80
81Return Value
82============
83
84On success, :c:func:`poll() <request-func-poll>` returns the number of
85structures which have non-zero ``revents`` fields, or zero if the call
86timed out. On error -1 is returned, and the ``errno`` variable is set
87appropriately:
88
89``EBADF``
90    One or more of the ``ufds`` members specify an invalid file
91    descriptor.
92
93``EFAULT``
94    ``ufds`` references an inaccessible memory area.
95
96``EINTR``
97    The call was interrupted by a signal.
98
99``EINVAL``
100    The ``nfds`` value exceeds the ``RLIMIT_NOFILE`` value. Use
101    ``getrlimit()`` to obtain this value.
102