1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2 3.. _DMX_QBUF: 4 5************************* 6ioctl DMX_QBUF, DMX_DQBUF 7************************* 8 9Name 10==== 11 12DMX_QBUF - DMX_DQBUF - Exchange a buffer with the driver 13 14.. warning:: this API is still experimental 15 16 17Synopsis 18======== 19 20.. c:function:: int ioctl( int fd, DMX_QBUF, struct dmx_buffer *argp ) 21 :name: DMX_QBUF 22 23.. c:function:: int ioctl( int fd, DMX_DQBUF, struct dmx_buffer *argp ) 24 :name: DMX_DQBUF 25 26 27Arguments 28========= 29 30``fd`` 31 File descriptor returned by :ref:`open() <dmx_fopen>`. 32 33``argp`` 34 Pointer to struct :c:type:`dmx_buffer`. 35 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 53the device 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:ref:`open() <dmx_fopen>` 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 69 70Return Value 71============ 72 73On success 0 is returned, on error -1 and the ``errno`` variable is set 74appropriately. The generic error codes are described at the 75:ref:`Generic Error Codes <gen-errors>` chapter. 76 77EAGAIN 78 Non-blocking I/O has been selected using ``O_NONBLOCK`` and no 79 buffer was in the outgoing queue. 80 81EINVAL 82 The ``index`` is out of bounds, or no buffers have been allocated yet. 83 84EIO 85 ``DMX_DQBUF`` failed due to an internal error. Can also indicate 86 temporary problems like signal loss or CRC errors. 87