1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2.. c:namespace:: V4L
3
4.. _VIDIOC_SUBSCRIBE_EVENT:
5.. _VIDIOC_UNSUBSCRIBE_EVENT:
6
7******************************************************
8ioctl VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT
9******************************************************
10
11Name
12====
13
14VIDIOC_SUBSCRIBE_EVENT - VIDIOC_UNSUBSCRIBE_EVENT - Subscribe or unsubscribe event
15
16Synopsis
17========
18
19.. c:macro:: VIDIOC_SUBSCRIBE_EVENT
20
21``int ioctl(int fd, VIDIOC_SUBSCRIBE_EVENT, struct v4l2_event_subscription *argp)``
22
23.. c:macro:: VIDIOC_UNSUBSCRIBE_EVENT
24
25``int ioctl(int fd, VIDIOC_UNSUBSCRIBE_EVENT, struct v4l2_event_subscription *argp)``
26
27Arguments
28=========
29
30``fd``
31    File descriptor returned by :c:func:`open()`.
32
33``argp``
34    Pointer to struct :c:type:`v4l2_event_subscription`.
35
36Description
37===========
38
39Subscribe or unsubscribe V4L2 event. Subscribed events are dequeued by
40using the :ref:`VIDIOC_DQEVENT` ioctl.
41
42.. tabularcolumns:: |p{2.6cm}|p{4.4cm}|p{10.3cm}|
43
44.. c:type:: v4l2_event_subscription
45
46.. flat-table:: struct v4l2_event_subscription
47    :header-rows:  0
48    :stub-columns: 0
49    :widths:       1 1 2
50
51    * - __u32
52      - ``type``
53      - Type of the event, see :ref:`event-type`.
54
55	.. note::
56
57	   ``V4L2_EVENT_ALL`` can be used with
58	   :ref:`VIDIOC_UNSUBSCRIBE_EVENT <VIDIOC_SUBSCRIBE_EVENT>` for
59	   unsubscribing all events at once.
60    * - __u32
61      - ``id``
62      - ID of the event source. If there is no ID associated with the
63	event source, then set this to 0. Whether or not an event needs an
64	ID depends on the event type.
65    * - __u32
66      - ``flags``
67      - Event flags, see :ref:`event-flags`.
68    * - __u32
69      - ``reserved``\ [5]
70      - Reserved for future extensions. Drivers and applications must set
71	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 Flags
79    :header-rows:  0
80    :stub-columns: 0
81    :widths:       3 1 4
82
83    * - ``V4L2_EVENT_SUB_FL_SEND_INITIAL``
84      - 0x0001
85      - When this event is subscribed an initial event will be sent
86	containing the current status. This only makes sense for events
87	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      - 0x0002
91      - If set, then events directly caused by an ioctl will also be sent
92	to the filehandle that called that ioctl. For example, changing a
93	control using :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` will cause
94	a V4L2_EVENT_CTRL to be sent back to that same filehandle.
95	Normally such events are suppressed to prevent feedback loops
96	where an application changes a control to a one value and then
97	another, and then receives an event telling it that that control
98	has changed to the first value.
99
100	Since it can't tell whether that event was caused by another
101	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 value
103	in the event, or ignore it.
104
105	Think carefully when you set this flag so you won't get into
106	situations like that.
107
108Return Value
109============
110
111On success 0 is returned, on error -1 and the ``errno`` variable is set
112appropriately. The generic error codes are described at the
113:ref:`Generic Error Codes <gen-errors>` chapter.
114