Documentation/userspace-api/media/v4l/vidioc-subdev-g-client-cap.rst

   1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
   2 .. c:namespace:: V4L
   3
   4 .. _VIDIOC_SUBDEV_G_CLIENT_CAP:
   5
   6 ************************************************************
   7 ioctl VIDIOC_SUBDEV_G_CLIENT_CAP, VIDIOC_SUBDEV_S_CLIENT_CAP
   8 ************************************************************
   9
  10 Name
  11 ====
  12
  13 VIDIOC_SUBDEV_G_CLIENT_CAP - VIDIOC_SUBDEV_S_CLIENT_CAP - Get or set client
  14 capabilities.
  15
  16 Synopsis
  17 ========
  18
  19 .. c:macro:: VIDIOC_SUBDEV_G_CLIENT_CAP
  20
  21 ``int ioctl(int fd, VIDIOC_SUBDEV_G_CLIENT_CAP, struct v4l2_subdev_client_capability *argp)``
  22
  23 .. c:macro:: VIDIOC_SUBDEV_S_CLIENT_CAP
  24
  25 ``int ioctl(int fd, VIDIOC_SUBDEV_S_CLIENT_CAP, struct v4l2_subdev_client_capability *argp)``
  26
  27 Arguments
  28 =========
  29
  30 ``fd``
  31     File descriptor returned by :ref:`open() <func-open>`.
  32
  33 ``argp``
  34     Pointer to struct :c:type:`v4l2_subdev_client_capability`.
  35
  36 Description
  37 ===========
  38
  39 These ioctls are used to get and set the client (the application using the
  40 subdevice ioctls) capabilities. The client capabilities are stored in the file
  41 handle of the opened subdev device node, and the client must set the
  42 capabilities for each opened subdev separately.
  43
  44 By default no client capabilities are set when a subdev device node is opened.
  45
  46 The purpose of the client capabilities are to inform the kernel of the behavior
  47 of the client, mainly related to maintaining compatibility with different
  48 kernel and userspace versions.
  49
  50 The ``VIDIOC_SUBDEV_G_CLIENT_CAP`` ioctl returns the current client capabilities
  51 associated with the file handle ``fd``.
  52
  53 The ``VIDIOC_SUBDEV_S_CLIENT_CAP`` ioctl sets client capabilities for the file
  54 handle ``fd``. The new capabilities fully replace the current capabilities, the
  55 ioctl can therefore also be used to remove capabilities that have previously
  56 been set.
  57
  58 ``VIDIOC_SUBDEV_S_CLIENT_CAP`` modifies the struct
  59 :c:type:`v4l2_subdev_client_capability` to reflect the capabilities that have
  60 been accepted. A common case for the kernel not accepting a capability is that
  61 the kernel is older than the headers the userspace uses, and thus the capability
  62 is unknown to the kernel.
  63
  64 .. flat-table:: Client Capabilities
  65     :header-rows:  1
  66
  67     * - Capability
  68       - Description
  69     * - ``V4L2_SUBDEV_CLIENT_CAP_STREAMS``
  70       - The client is aware of streams. Setting this flag enables the use
  71         of 'stream' fields (referring to the stream number) with various
  72         ioctls. If this is not set (which is the default), the 'stream' fields
  73         will be forced to 0 by the kernel.
  74     * - ``V4L2_SUBDEV_CLIENT_CAP_INTERVAL_USES_WHICH``
  75       - The client is aware of the :c:type:`v4l2_subdev_frame_interval`
  76         ``which`` field. If this is not set (which is the default), the
  77         ``which`` field is forced to ``V4L2_SUBDEV_FORMAT_ACTIVE`` by the
  78         kernel.
  79
  80 Return Value
  81 ============
  82
  83 On success 0 is returned, on error -1 and the ``errno`` variable is set
  84 appropriately. The generic error codes are described at the
  85 :ref:`Generic Error Codes <gen-errors>` chapter.
  86
  87 ENOIOCTLCMD
  88    The kernel does not support this ioctl.