Documentation/userspace-api/media/dvb/dmx-qbuf.rst

   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 *************************
  13 ioctl DMX_QBUF, DMX_DQBUF
  14 *************************
  15
  16 Name
  17 ====
  18
  19 DMX_QBUF - DMX_DQBUF - Exchange a buffer with the driver
  20
  21 .. warning:: this API is still experimental
  22
  23
  24 Synopsis
  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
  34 Arguments
  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
  44 Description
  45 ===========
  46
  47 Applications call the ``DMX_QBUF`` ioctl to enqueue an empty
  48 (capturing) or filled (output) buffer in the driver's incoming queue.
  49 The semantics depend on the selected I/O method.
  50
  51 To enqueue a buffer applications set the ``index`` field. Valid index
  52 numbers range from zero to the number of buffers allocated with
  53 :ref:`DMX_REQBUFS` (struct :c:type:`dmx_requestbuffers` ``count``) minus
  54 one. The contents of the struct :c:type:`dmx_buffer` returned
  55 by a :ref:`DMX_QUERYBUF` ioctl will do as well.
  56
  57 When ``DMX_QBUF`` is called with a pointer to this structure, it locks the
  58 memory pages of the buffer in physical memory, so they cannot be swapped
  59 out to disk. Buffers remain locked until dequeued, until the
  60 the device is closed.
  61
  62 Applications call the ``DMX_DQBUF`` ioctl to dequeue a filled
  63 (capturing) buffer from the driver's outgoing queue.
  64 They just set the ``index`` field with the buffer ID to be queued.
  65 When ``DMX_DQBUF`` is called with a pointer to struct :c:type:`dmx_buffer`,
  66 the driver fills the remaining fields or returns an error code.
  67
  68 By default ``DMX_DQBUF`` blocks when no buffer is in the outgoing
  69 queue. When the ``O_NONBLOCK`` flag was given to the
  70 :ref:`open() <dmx_fopen>` function, ``DMX_DQBUF`` returns
  71 immediately with an ``EAGAIN`` error code when no buffer is available.
  72
  73 The struct :c:type:`dmx_buffer` structure is specified in
  74 :ref:`buffer`.
  75
  76
  77 Return Value
  78 ============
  79
  80 On success 0 is returned, on error -1 and the ``errno`` variable is set
  81 appropriately. The generic error codes are described at the
  82 :ref:`Generic Error Codes <gen-errors>` chapter.
  83
  84 EAGAIN
  85     Non-blocking I/O has been selected using ``O_NONBLOCK`` and no
  86     buffer was in the outgoing queue.
  87
  88 EINVAL
  89     The ``index`` is out of bounds, or no buffers have been allocated yet.
  90
  91 EIO
  92     ``DMX_DQBUF`` failed due to an internal error. Can also indicate
  93     temporary problems like signal loss or CRC errors.