114 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2.. c:namespace:: V4L3 4.. _VIDIOC_SUBSCRIBE_EVENT:5.. _VIDIOC_UNSUBSCRIBE_EVENT:6 7******************************************************8ioctl VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT9******************************************************10 11Name12====13 14VIDIOC_SUBSCRIBE_EVENT - VIDIOC_UNSUBSCRIBE_EVENT - Subscribe or unsubscribe event15 16Synopsis17========18 19.. c:macro:: VIDIOC_SUBSCRIBE_EVENT20 21``int ioctl(int fd, VIDIOC_SUBSCRIBE_EVENT, struct v4l2_event_subscription *argp)``22 23.. c:macro:: VIDIOC_UNSUBSCRIBE_EVENT24 25``int ioctl(int fd, VIDIOC_UNSUBSCRIBE_EVENT, struct v4l2_event_subscription *argp)``26 27Arguments28=========29 30``fd``31 File descriptor returned by :c:func:`open()`.32 33``argp``34 Pointer to struct :c:type:`v4l2_event_subscription`.35 36Description37===========38 39Subscribe or unsubscribe V4L2 event. Subscribed events are dequeued by40using the :ref:`VIDIOC_DQEVENT` ioctl.41 42.. tabularcolumns:: |p{2.6cm}|p{4.4cm}|p{10.3cm}|43 44.. c:type:: v4l2_event_subscription45 46.. flat-table:: struct v4l2_event_subscription47 :header-rows: 048 :stub-columns: 049 :widths: 1 1 250 51 * - __u3252 - ``type``53 - Type of the event, see :ref:`event-type`.54 55 .. note::56 57 ``V4L2_EVENT_ALL`` can be used with58 :ref:`VIDIOC_UNSUBSCRIBE_EVENT <VIDIOC_SUBSCRIBE_EVENT>` for59 unsubscribing all events at once.60 * - __u3261 - ``id``62 - ID of the event source. If there is no ID associated with the63 event source, then set this to 0. Whether or not an event needs an64 ID depends on the event type.65 * - __u3266 - ``flags``67 - Event flags, see :ref:`event-flags`.68 * - __u3269 - ``reserved``\ [5]70 - Reserved for future extensions. Drivers and applications must set71 the array to zero.72 73 74.. tabularcolumns:: |p{7.5cm}|p{2.0cm}|p{7.8cm}|75 76.. _event-flags:77 78.. flat-table:: Event Flags79 :header-rows: 080 :stub-columns: 081 :widths: 3 1 482 83 * - ``V4L2_EVENT_SUB_FL_SEND_INITIAL``84 - 0x000185 - When this event is subscribed an initial event will be sent86 containing the current status. This only makes sense for events87 that are triggered by a status change such as ``V4L2_EVENT_CTRL``.88 Other events will ignore this flag.89 * - ``V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK``90 - 0x000291 - If set, then events directly caused by an ioctl will also be sent92 to the filehandle that called that ioctl. For example, changing a93 control using :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` will cause94 a V4L2_EVENT_CTRL to be sent back to that same filehandle.95 Normally such events are suppressed to prevent feedback loops96 where an application changes a control to a one value and then97 another, and then receives an event telling it that that control98 has changed to the first value.99 100 Since it can't tell whether that event was caused by another101 application or by the :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>`102 call it is hard to decide whether to set the control to the value103 in the event, or ignore it.104 105 Think carefully when you set this flag so you won't get into106 situations like that.107 108Return Value109============110 111On success 0 is returned, on error -1 and the ``errno`` variable is set112appropriately. The generic error codes are described at the113:ref:`Generic Error Codes <gen-errors>` chapter.114