1.. Permission is granted to copy, distribute and/or modify this 2.. document under the terms of the GNU Free Documentation License, 3.. Version 1.1 or any later version published by the Free Software 4.. Foundation, with no Invariant Sections, no Front-Cover Texts 5.. and no Back-Cover Texts. A copy of the license is included at 6.. Documentation/userspace-api/media/fdl-appendix.rst. 7.. 8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections 9 10.. _DMX_QBUF: 11 12************************* 13ioctl DMX_QBUF, DMX_DQBUF 14************************* 15 16Name 17==== 18 19DMX_QBUF - DMX_DQBUF - Exchange a buffer with the driver 20 21.. warning:: this API is still experimental 22 23 24Synopsis 25======== 26 27.. c:function:: int ioctl( int fd, DMX_QBUF, struct dmx_buffer *argp ) 28 :name: DMX_QBUF 29 30.. c:function:: int ioctl( int fd, DMX_DQBUF, struct dmx_buffer *argp ) 31 :name: DMX_DQBUF 32 33 34Arguments 35========= 36 37``fd`` 38 File descriptor returned by :ref:`open() <dmx_fopen>`. 39 40``argp`` 41 Pointer to struct :c:type:`dmx_buffer`. 42 43 44Description 45=========== 46 47Applications call the ``DMX_QBUF`` ioctl to enqueue an empty 48(capturing) or filled (output) buffer in the driver's incoming queue. 49The semantics depend on the selected I/O method. 50 51To enqueue a buffer applications set the ``index`` field. Valid index 52numbers range from zero to the number of buffers allocated with 53:ref:`DMX_REQBUFS` (struct :c:type:`dmx_requestbuffers` ``count``) minus 54one. The contents of the struct :c:type:`dmx_buffer` returned 55by a :ref:`DMX_QUERYBUF` ioctl will do as well. 56 57When ``DMX_QBUF`` is called with a pointer to this structure, it locks the 58memory pages of the buffer in physical memory, so they cannot be swapped 59out to disk. Buffers remain locked until dequeued, until the 60the device is closed. 61 62Applications call the ``DMX_DQBUF`` ioctl to dequeue a filled 63(capturing) buffer from the driver's outgoing queue. 64They just set the ``index`` field with the buffer ID to be queued. 65When ``DMX_DQBUF`` is called with a pointer to struct :c:type:`dmx_buffer`, 66the driver fills the remaining fields or returns an error code. 67 68By default ``DMX_DQBUF`` blocks when no buffer is in the outgoing 69queue. When the ``O_NONBLOCK`` flag was given to the 70:ref:`open() <dmx_fopen>` function, ``DMX_DQBUF`` returns 71immediately with an ``EAGAIN`` error code when no buffer is available. 72 73The struct :c:type:`dmx_buffer` structure is specified in 74:ref:`buffer`. 75 76 77Return Value 78============ 79 80On success 0 is returned, on error -1 and the ``errno`` variable is set 81appropriately. The generic error codes are described at the 82:ref:`Generic Error Codes <gen-errors>` chapter. 83 84EAGAIN 85 Non-blocking I/O has been selected using ``O_NONBLOCK`` and no 86 buffer was in the outgoing queue. 87 88EINVAL 89 The ``index`` is out of bounds, or no buffers have been allocated yet. 90 91EIO 92 ``DMX_DQBUF`` failed due to an internal error. Can also indicate 93 temporary problems like signal loss or CRC errors. 94