0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: DTV.dmx
0003
0004 .. _DMX_QBUF:
0005
0006 *************************
0007 ioctl DMX_QBUF, DMX_DQBUF
0008 *************************
0009
0010 Name
0011 ====
0012
0013 DMX_QBUF - DMX_DQBUF - Exchange a buffer with the driver
0014
0015 .. warning:: this API is still experimental
0016
0017 Synopsis
0018 ========
0019
0020 .. c:macro:: DMX_QBUF
0021
0022 ``int ioctl(int fd, DMX_QBUF, struct dmx_buffer *argp)``
0023
0024 .. c:macro:: DMX_DQBUF
0025
0026 ``int ioctl(int fd, DMX_DQBUF, struct dmx_buffer *argp)``
0027
0028 Arguments
0029 =========
0030
0031 ``fd``
0032 File descriptor returned by :c:func:`open()`.
0033
0034 ``argp``
0035 Pointer to struct :c:type:`dmx_buffer`.
0036
0037 Description
0038 ===========
0039
0040 Applications call the ``DMX_QBUF`` ioctl to enqueue an empty
0041 (capturing) or filled (output) buffer in the driver's incoming queue.
0042 The semantics depend on the selected I/O method.
0043
0044 To enqueue a buffer applications set the ``index`` field. Valid index
0045 numbers range from zero to the number of buffers allocated with
0046 :ref:`DMX_REQBUFS` (struct :c:type:`dmx_requestbuffers` ``count``) minus
0047 one. The contents of the struct :c:type:`dmx_buffer` returned
0048 by a :ref:`DMX_QUERYBUF` ioctl will do as well.
0049
0050 When ``DMX_QBUF`` is called with a pointer to this structure, it locks the
0051 memory pages of the buffer in physical memory, so they cannot be swapped
0052 out to disk. Buffers remain locked until dequeued, until the
0053 device is closed.
0054
0055 Applications call the ``DMX_DQBUF`` ioctl to dequeue a filled
0056 (capturing) buffer from the driver's outgoing queue.
0057 They just set the ``index`` field with the buffer ID to be queued.
0058 When ``DMX_DQBUF`` is called with a pointer to struct :c:type:`dmx_buffer`,
0059 the driver fills the remaining fields or returns an error code.
0060
0061 By default ``DMX_DQBUF`` blocks when no buffer is in the outgoing
0062 queue. When the ``O_NONBLOCK`` flag was given to the
0063 :c:func:`open()` function, ``DMX_DQBUF`` returns
0064 immediately with an ``EAGAIN`` error code when no buffer is available.
0065
0066 The struct :c:type:`dmx_buffer` structure is specified in
0067 :ref:`buffer`.
0068
0069 Return Value
0070 ============
0071
0072 On success 0 is returned, on error -1 and the ``errno`` variable is set
0073 appropriately. The generic error codes are described at the
0074 :ref:`Generic Error Codes <gen-errors>` chapter.
0075
0076 EAGAIN
0077 Non-blocking I/O has been selected using ``O_NONBLOCK`` and no
0078 buffer was in the outgoing queue.
0079
0080 EINVAL
0081 The ``index`` is out of bounds, or no buffers have been allocated yet.
0082
0083 EIO
0084 ``DMX_DQBUF`` failed due to an internal error. Can also indicate
0085 temporary problems like signal loss or CRC errors.
