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