1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2.. c:namespace:: DTV.dmx 3 4.. _DMX_QBUF: 5 6************************* 7ioctl DMX_QBUF, DMX_DQBUF 8************************* 9 10Name 11==== 12 13DMX_QBUF - DMX_DQBUF - Exchange a buffer with the driver 14 15.. warning:: this API is still experimental 16 17Synopsis 18======== 19 20.. c:macro:: DMX_QBUF 21 22``int ioctl(int fd, DMX_QBUF, struct dmx_buffer *argp)`` 23 24.. c:macro:: DMX_DQBUF 25 26``int ioctl(int fd, DMX_DQBUF, struct dmx_buffer *argp)`` 27 28Arguments 29========= 30 31``fd`` 32 File descriptor returned by :c:func:`open()`. 33 34``argp`` 35 Pointer to struct :c:type:`dmx_buffer`. 36 37Description 38=========== 39 40Applications call the ``DMX_QBUF`` ioctl to enqueue an empty 41(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 index 45numbers range from zero to the number of buffers allocated with 46:ref:`DMX_REQBUFS` (struct :c:type:`dmx_requestbuffers` ``count``) minus 47one. The contents of the struct :c:type:`dmx_buffer` returned 48by a :ref:`DMX_QUERYBUF` ioctl will do as well. 49 50When ``DMX_QBUF`` is called with a pointer to this structure, it locks the 51memory pages of the buffer in physical memory, so they cannot be swapped 52out to disk. Buffers remain locked until dequeued, until the 53device is closed. 54 55Applications call the ``DMX_DQBUF`` ioctl to dequeue a filled 56(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 outgoing 62queue. When the ``O_NONBLOCK`` flag was given to the 63:c:func:`open()` function, ``DMX_DQBUF`` returns 64immediately with an ``EAGAIN`` error code when no buffer is available. 65 66The struct :c:type:`dmx_buffer` structure is specified in 67:ref:`buffer`. 68 69Return Value 70============ 71 72On success 0 is returned, on error -1 and the ``errno`` variable is set 73appropriately. The generic error codes are described at the 74:ref:`Generic Error Codes <gen-errors>` chapter. 75 76EAGAIN 77 Non-blocking I/O has been selected using ``O_NONBLOCK`` and no 78 buffer was in the outgoing queue. 79 80EINVAL 81 The ``index`` is out of bounds, or no buffers have been allocated yet. 82 83EIO 84 ``DMX_DQBUF`` failed due to an internal error. Can also indicate 85 temporary problems like signal loss or CRC errors. 86