Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst

Source file repositories/reference/linux-study-clean/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst

File Facts

System
Linux kernel
Corpus path
Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst
Extension
.rst
Size
26221 bytes
Lines
719
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _VIDIOC_QUERYCTRL:

*******************************************************************
ioctls VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL and VIDIOC_QUERYMENU
*******************************************************************

Name
====

VIDIOC_QUERYCTRL - VIDIOC_QUERY_EXT_CTRL - VIDIOC_QUERYMENU - Enumerate controls and menu control items

Synopsis
========

.. c:macro:: VIDIOC_QUERY_CTRL

``int ioctl(int fd, int VIDIOC_QUERYCTRL, struct v4l2_queryctrl *argp)``

.. c:macro:: VIDIOC_QUERY_EXT_CTRL

``int ioctl(int fd, VIDIOC_QUERY_EXT_CTRL, struct v4l2_query_ext_ctrl *argp)``

.. c:macro:: VIDIOC_QUERYMENU

``int ioctl(int fd, VIDIOC_QUERYMENU, struct v4l2_querymenu *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_queryctrl`, :c:type:`v4l2_query_ext_ctrl`
    or :c:type:`v4l2_querymenu` (depending on the ioctl).

Description
===========

To query the attributes of a control applications set the ``id`` field
of a struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` and call the
``VIDIOC_QUERYCTRL`` ioctl with a pointer to this structure. The driver
fills the rest of the structure or returns an ``EINVAL`` error code when the
``id`` is invalid.

It is possible to enumerate controls by calling ``VIDIOC_QUERYCTRL``
with successive ``id`` values starting from ``V4L2_CID_BASE`` up to and
exclusive ``V4L2_CID_LASTP1``. Drivers may return ``EINVAL`` if a control in
this range is not supported. Further applications can enumerate private
controls, which are not defined in this specification, by starting at
``V4L2_CID_PRIVATE_BASE`` and incrementing ``id`` until the driver
returns ``EINVAL``.

In both cases, when the driver sets the ``V4L2_CTRL_FLAG_DISABLED`` flag
in the ``flags`` field this control is permanently disabled and should
be ignored by the application. [#f1]_

When the application ORs ``id`` with ``V4L2_CTRL_FLAG_NEXT_CTRL`` the
driver returns the next supported non-compound control, or ``EINVAL`` if
there is none. In addition, the ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` flag
can be specified to enumerate all compound controls (i.e. controls with
type ≥ ``V4L2_CTRL_COMPOUND_TYPES`` and/or array control, in other words
controls that contain more than one value). Specify both
``V4L2_CTRL_FLAG_NEXT_CTRL`` and ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` in
order to enumerate all controls, compound or not. Drivers which do not
support these flags yet always return ``EINVAL``.

Annotation

Implementation Notes