From 60c2820d0f6d3497975b6488e2599f8f611d8b95 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 8 Jul 2016 11:40:06 -0300 Subject: doc_rst: rename the media Sphinx suff to Documentation/media The name of the subsystem is "media", and not "linux_tv". Also, as we plan to add other stuff there in the future, let's rename also the media uAPI book to media_uapi, to make it clearer. No functional changes. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/v4l/func-select.rst | 106 +++++++++++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 Documentation/media/uapi/v4l/func-select.rst (limited to 'Documentation/media/uapi/v4l/func-select.rst') diff --git a/Documentation/media/uapi/v4l/func-select.rst b/Documentation/media/uapi/v4l/func-select.rst new file mode 100644 index 000000000000..954dd00b8301 --- /dev/null +++ b/Documentation/media/uapi/v4l/func-select.rst @@ -0,0 +1,106 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _func-select: + +************* +V4L2 select() +************* + +Name +==== + +v4l2-select - Synchronous I/O multiplexing + + +Synopsis +======== + +.. code-block:: c + + #include + #include + #include + + +.. cpp:function:: int select( int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout ) + + +Arguments +========= + + + +Description +=========== + +With the :ref:`select() ` function applications can suspend +execution until the driver has captured data or is ready to accept data +for output. + +When streaming I/O has been negotiated this function waits until a +buffer has been filled or displayed and can be dequeued with the +:ref:`VIDIOC_DQBUF ` ioctl. When buffers are already in +the outgoing queue of the driver the function returns immediately. + +On success :ref:`select() ` returns the total number of bits set in +:c:func:`struct fd_set`. When the function timed out it returns +a value of zero. On failure it returns -1 and the ``errno`` variable is +set appropriately. When the application did not call +:ref:`VIDIOC_QBUF` or +:ref:`VIDIOC_STREAMON` yet the :ref:`select() ` +function succeeds, setting the bit of the file descriptor in ``readfds`` +or ``writefds``, but subsequent :ref:`VIDIOC_DQBUF ` +calls will fail. [1]_ + +When use of the :ref:`read() ` function has been negotiated and the +driver does not capture yet, the :ref:`select() ` function starts +capturing. When that fails, :ref:`select() ` returns successful and +a subsequent :ref:`read() ` call, which also attempts to start +capturing, will return an appropriate error code. When the driver +captures continuously (as opposed to, for example, still images) and +data is already available the :ref:`select() ` function returns +immediately. + +When use of the :ref:`write() ` function has been negotiated the +:ref:`select() ` function just waits until the driver is ready for a +non-blocking :ref:`write() ` call. + +All drivers implementing the :ref:`read() ` or :ref:`write() ` +function or streaming I/O must also support the :ref:`select() ` +function. + +For more details see the :ref:`select() ` manual page. + + +Return Value +============ + +On success, :ref:`select() ` returns the number of descriptors +contained in the three returned descriptor sets, which will be zero if +the timeout expired. On error -1 is returned, and the ``errno`` variable +is set appropriately; the sets and ``timeout`` are undefined. Possible +error codes are: + +EBADF + One or more of the file descriptor sets specified a file descriptor + that is not open. + +EBUSY + The driver does not support multiple read or write streams and the + device is already in use. + +EFAULT + The ``readfds``, ``writefds``, ``exceptfds`` or ``timeout`` pointer + references an inaccessible memory area. + +EINTR + The call was interrupted by a signal. + +EINVAL + The ``nfds`` argument is less than zero or greater than + ``FD_SETSIZE``. + +.. [1] + The Linux kernel implements :ref:`select() ` like the + :ref:`poll() ` function, but :ref:`select() ` cannot + return a ``POLLERR``. -- cgit v1.2.3