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************************************************************
  7ioctl VIDIOC_SUBDEV_G_CLIENT_CAP, VIDIOC_SUBDEV_S_CLIENT_CAP
  8************************************************************
  9
 10Name
 11====
 12
 13VIDIOC_SUBDEV_G_CLIENT_CAP - VIDIOC_SUBDEV_S_CLIENT_CAP - Get or set client
 14capabilities.
 15
 16Synopsis
 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
 27Arguments
 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
 36Description
 37===========
 38
 39These ioctls are used to get and set the client (the application using the
 40subdevice ioctls) capabilities. The client capabilities are stored in the file
 41handle of the opened subdev device node, and the client must set the
 42capabilities for each opened subdev separately.
 43
 44By default no client capabilities are set when a subdev device node is opened.
 45
 46The purpose of the client capabilities are to inform the kernel of the behavior
 47of the client, mainly related to maintaining compatibility with different
 48kernel and userspace versions.
 49
 50The ``VIDIOC_SUBDEV_G_CLIENT_CAP`` ioctl returns the current client capabilities
 51associated with the file handle ``fd``.
 52
 53The ``VIDIOC_SUBDEV_S_CLIENT_CAP`` ioctl sets client capabilities for the file
 54handle ``fd``. The new capabilities fully replace the current capabilities, the
 55ioctl can therefore also be used to remove capabilities that have previously
 56been set.
 57
 58``VIDIOC_SUBDEV_S_CLIENT_CAP`` modifies the struct
 59:c:type:`v4l2_subdev_client_capability` to reflect the capabilities that have
 60been accepted. A common case for the kernel not accepting a capability is that
 61the kernel is older than the headers the userspace uses, and thus the capability
 62is unknown to the kernel.
 63
 64.. tabularcolumns:: |p{1.5cm}|p{2.9cm}|p{12.9cm}|
 65
 66.. c:type:: v4l2_subdev_client_capability
 67
 68.. flat-table:: struct v4l2_subdev_client_capability
 69    :header-rows:  0
 70    :stub-columns: 0
 71    :widths:       3 4 20
 72
 73    * - __u64
 74      - ``capabilities``
 75      - Sub-device client capabilities of the opened device.
 76
 77.. tabularcolumns:: |p{6.8cm}|p{2.4cm}|p{8.1cm}|
 78
 79.. flat-table:: Client Capabilities
 80    :header-rows:  1
 81
 82    * - Capability
 83      - Description
 84    * - ``V4L2_SUBDEV_CLIENT_CAP_STREAMS``
 85      - The client is aware of streams. Setting this flag enables the use
 86        of 'stream' fields (referring to the stream number) with various
 87        ioctls. If this is not set (which is the default), the 'stream' fields
 88        will be forced to 0 by the kernel.
 89    * - ``V4L2_SUBDEV_CLIENT_CAP_INTERVAL_USES_WHICH``
 90      - The client is aware of the :c:type:`v4l2_subdev_frame_interval`
 91        ``which`` field. If this is not set (which is the default), the
 92        ``which`` field is forced to ``V4L2_SUBDEV_FORMAT_ACTIVE`` by the
 93        kernel.
 94
 95Return Value
 96============
 97
 98On success 0 is returned, on error -1 and the ``errno`` variable is set
 99appropriately. The generic error codes are described at the
100:ref:`Generic Error Codes <gen-errors>` chapter.
101
102ENOIOCTLCMD
103   The kernel does not support this ioctl.