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