Documentation/userspace-api/media/v4l/vidioc-querybuf.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 .. _VIDIOC_QUERYBUF:
  11
  12 *********************
  13 ioctl VIDIOC_QUERYBUF
  14 *********************
  15
  16 Name
  17 ====
  18
  19 VIDIOC_QUERYBUF - Query the status of a buffer
  20
  21
  22 Synopsis
  23 ========
  24
  25 .. c:function:: int ioctl( int fd, VIDIOC_QUERYBUF, struct v4l2_buffer *argp )
  26     :name: VIDIOC_QUERYBUF
  27
  28
  29 Arguments
  30 =========
  31
  32 ``fd``
  33     File descriptor returned by :ref:`open() <func-open>`.
  34
  35 ``argp``
  36     Pointer to struct :c:type:`v4l2_buffer`.
  37
  38
  39 Description
  40 ===========
  41
  42 This ioctl is part of the :ref:`streaming <mmap>` I/O method. It can
  43 be used to query the status of a buffer at any time after buffers have
  44 been allocated with the :ref:`VIDIOC_REQBUFS` ioctl.
  45
  46 Applications set the ``type`` field of a struct
  47 :c:type:`v4l2_buffer` to the same buffer type as was
  48 previously used with struct :c:type:`v4l2_format` ``type``
  49 and struct :c:type:`v4l2_requestbuffers` ``type``,
  50 and the ``index`` field. Valid index numbers range from zero to the
  51 number of buffers allocated with
  52 :ref:`VIDIOC_REQBUFS` (struct
  53 :c:type:`v4l2_requestbuffers` ``count``) minus
  54 one. The ``reserved`` and ``reserved2`` fields must be set to 0. When
  55 using the :ref:`multi-planar API <planar-apis>`, the ``m.planes``
  56 field must contain a userspace pointer to an array of struct
  57 :c:type:`v4l2_plane` and the ``length`` field has to be set
  58 to the number of elements in that array. After calling
  59 :ref:`VIDIOC_QUERYBUF` with a pointer to this structure drivers return an
  60 error code or fill the rest of the structure.
  61
  62 In the ``flags`` field the ``V4L2_BUF_FLAG_MAPPED``,
  63 ``V4L2_BUF_FLAG_PREPARED``, ``V4L2_BUF_FLAG_QUEUED`` and
  64 ``V4L2_BUF_FLAG_DONE`` flags will be valid. The ``memory`` field will be
  65 set to the current I/O method. For the single-planar API, the
  66 ``m.offset`` contains the offset of the buffer from the start of the
  67 device memory, the ``length`` field its size. For the multi-planar API,
  68 fields ``m.mem_offset`` and ``length`` in the ``m.planes`` array
  69 elements will be used instead and the ``length`` field of struct
  70 :c:type:`v4l2_buffer` is set to the number of filled-in
  71 array elements. The driver may or may not set the remaining fields and
  72 flags, they are meaningless in this context.
  73
  74 The struct :c:type:`v4l2_buffer` structure is specified in
  75 :ref:`buffer`.
  76
  77
  78 Return Value
  79 ============
  80
  81 On success 0 is returned, on error -1 and the ``errno`` variable is set
  82 appropriately. The generic error codes are described at the
  83 :ref:`Generic Error Codes <gen-errors>` chapter.
  84
  85 EINVAL
  86     The buffer ``type`` is not supported, or the ``index`` is out of
  87     bounds.