86 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2.. c:namespace:: DTV.dmx3 4.. _DMX_QBUF:5 6*************************7ioctl DMX_QBUF, DMX_DQBUF8*************************9 10Name11====12 13DMX_QBUF - DMX_DQBUF - Exchange a buffer with the driver14 15.. warning:: this API is still experimental16 17Synopsis18========19 20.. c:macro:: DMX_QBUF21 22``int ioctl(int fd, DMX_QBUF, struct dmx_buffer *argp)``23 24.. c:macro:: DMX_DQBUF25 26``int ioctl(int fd, DMX_DQBUF, struct dmx_buffer *argp)``27 28Arguments29=========30 31``fd``32 File descriptor returned by :c:func:`open()`.33 34``argp``35 Pointer to struct :c:type:`dmx_buffer`.36 37Description38===========39 40Applications call the ``DMX_QBUF`` ioctl to enqueue an empty41(capturing) or filled (output) buffer in the driver's incoming queue.42The semantics depend on the selected I/O method.43 44To enqueue a buffer applications set the ``index`` field. Valid index45numbers range from zero to the number of buffers allocated with46:ref:`DMX_REQBUFS` (struct :c:type:`dmx_requestbuffers` ``count``) minus47one. The contents of the struct :c:type:`dmx_buffer` returned48by a :ref:`DMX_QUERYBUF` ioctl will do as well.49 50When ``DMX_QBUF`` is called with a pointer to this structure, it locks the51memory pages of the buffer in physical memory, so they cannot be swapped52out to disk. Buffers remain locked until dequeued, until the53device is closed.54 55Applications call the ``DMX_DQBUF`` ioctl to dequeue a filled56(capturing) buffer from the driver's outgoing queue.57They just set the ``index`` field with the buffer ID to be queued.58When ``DMX_DQBUF`` is called with a pointer to struct :c:type:`dmx_buffer`,59the driver fills the remaining fields or returns an error code.60 61By default ``DMX_DQBUF`` blocks when no buffer is in the outgoing62queue. When the ``O_NONBLOCK`` flag was given to the63:c:func:`open()` function, ``DMX_DQBUF`` returns64immediately with an ``EAGAIN`` error code when no buffer is available.65 66The struct :c:type:`dmx_buffer` structure is specified in67:ref:`buffer`.68 69Return Value70============71 72On success 0 is returned, on error -1 and the ``errno`` variable is set73appropriately. The generic error codes are described at the74:ref:`Generic Error Codes <gen-errors>` chapter.75 76EAGAIN77 Non-blocking I/O has been selected using ``O_NONBLOCK`` and no78 buffer was in the outgoing queue.79 80EINVAL81 The ``index`` is out of bounds, or no buffers have been allocated yet.82 83EIO84 ``DMX_DQBUF`` failed due to an internal error. Can also indicate85 temporary problems like signal loss or CRC errors.86