Documentation/userspace-api/media/mediactl/request-func-poll.rst

   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 **************
  30 request poll()
  31 **************
  32
  33 Name
  34 ====
  35
  36 request-poll - Wait for some event on a file descriptor
  37
  38
  39 Synopsis
  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
  50 Arguments
  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
  63 Description
  64 ===========
  65
  66 With the :c:func:`poll() <request-func-poll>` function applications can wait
  67 for a request to complete.
  68
  69 On success :c:func:`poll() <request-func-poll>` returns the number of file
  70 descriptors that have been selected (that is, file descriptors for which the
  71 ``revents`` field of the respective struct :c:type:`pollfd`
  72 is non-zero). Request file descriptor set the ``POLLPRI`` flag in ``revents``
  73 when the request was completed.  When the function times out it returns
  74 a value of zero, on failure it returns -1 and the ``errno`` variable is
  75 set appropriately.
  76
  77 Attempting to poll for a request that is not yet queued will
  78 set the ``POLLERR`` flag in ``revents``.
  79
  80
  81 Return Value
  82 ============
  83
  84 On success, :c:func:`poll() <request-func-poll>` returns the number of
  85 structures which have non-zero ``revents`` fields, or zero if the call
  86 timed out. On error -1 is returned, and the ``errno`` variable is set
  87 appropriately:
  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.