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