Documentation/media/uapi/mediactl/request-func-poll.rst

   1 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections
   2
   3 .. _request-func-poll:
   4
   5 **************
   6 request poll()
   7 **************
   8
   9 Name
  10 ====
  11
  12 request-poll - Wait for some event on a file descriptor
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. code-block:: c
  19
  20     #include <sys/poll.h>
  21
  22
  23 .. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout )
  24    :name: request-poll
  25
  26 Arguments
  27 =========
  28
  29 ``ufds``
  30    List of file descriptor events to be watched
  31
  32 ``nfds``
  33    Number of file descriptor events at the \*ufds array
  34
  35 ``timeout``
  36    Timeout to wait for events
  37
  38
  39 Description
  40 ===========
  41
  42 With the :c:func:`poll() <request-func-poll>` function applications can wait
  43 for a request to complete.
  44
  45 On success :c:func:`poll() <request-func-poll>` returns the number of file
  46 descriptors that have been selected (that is, file descriptors for which the
  47 ``revents`` field of the respective struct :c:type:`pollfd`
  48 is non-zero). Request file descriptor set the ``POLLPRI`` flag in ``revents``
  49 when the request was completed.  When the function times out it returns
  50 a value of zero, on failure it returns -1 and the ``errno`` variable is
  51 set appropriately.
  52
  53 Attempting to poll for a request that is not yet queued will
  54 set the ``POLLERR`` flag in ``revents``.
  55
  56
  57 Return Value
  58 ============
  59
  60 On success, :c:func:`poll() <request-func-poll>` returns the number of
  61 structures which have non-zero ``revents`` fields, or zero if the call
  62 timed out. On error -1 is returned, and the ``errno`` variable is set
  63 appropriately:
  64
  65 ``EBADF``
  66     One or more of the ``ufds`` members specify an invalid file
  67     descriptor.
  68
  69 ``EFAULT``
  70     ``ufds`` references an inaccessible memory area.
  71
  72 ``EINTR``
  73     The call was interrupted by a signal.
  74
  75 ``EINVAL``
  76     The ``nfds`` value exceeds the ``RLIMIT_NOFILE`` value. Use
  77     ``getrlimit()`` to obtain this value.