1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2
3.. _DMX_QUERYBUF:
4
5******************
6ioctl DMX_QUERYBUF
7******************
8
9Name
10====
11
12DMX_QUERYBUF - Query the status of a buffer
13
14.. warning:: this API is still experimental
15
16
17Synopsis
18========
19
20.. c:function:: int ioctl( int fd, DMX_QUERYBUF, struct dvb_buffer *argp )
21    :name: DMX_QUERYBUF
22
23
24Arguments
25=========
26
27``fd``
28    File descriptor returned by :ref:`open() <dmx_fopen>`.
29
30``argp``
31    Pointer to struct :c:type:`dvb_buffer`.
32
33
34Description
35===========
36
37This ioctl is part of the mmap streaming I/O method. It can
38be used to query the status of a buffer at any time after buffers have
39been allocated with the :ref:`DMX_REQBUFS` ioctl.
40
41Applications set the ``index`` field. Valid index numbers range from zero
42to the number of buffers allocated with :ref:`DMX_REQBUFS`
43(struct :c:type:`dvb_requestbuffers` ``count``) minus one.
44
45After calling :ref:`DMX_QUERYBUF` with a pointer to this structure,
46drivers return an error code or fill the rest of the structure.
47
48On success, the ``offset`` will contain the offset of the buffer from the
49start of the device memory, the ``length`` field its size, and the
50``bytesused`` the number of bytes occupied by data in the buffer (payload).
51
52Return Value
53============
54
55On success 0 is returned, the ``offset`` will contain the offset of the
56buffer from the start of the device memory, the ``length`` field its size,
57and the ``bytesused`` the number of bytes occupied by data in the buffer
58(payload).
59
60On error it returns -1 and the ``errno`` variable is set
61appropriately. The generic error codes are described at the
62:ref:`Generic Error Codes <gen-errors>` chapter.
63
64EINVAL
65    The ``index`` is out of bounds.
66