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