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 ******************************************************
8 ioctl VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT
9 ******************************************************
10
11 Name
12 ====
13
14 VIDIOC_SUBSCRIBE_EVENT - VIDIOC_UNSUBSCRIBE_EVENT - Subscribe or unsubscribe event
15
16 Synopsis
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
27 Arguments
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
36 Description
37 ===========
38
39 Subscribe or unsubscribe V4L2 event. Subscribed events are dequeued by
40 using 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
108 Return Value
109 ============
110
111 On success 0 is returned, on error -1 and the ``errno`` variable is set
112 appropriately. The generic error codes are described at the
113 :ref:`Generic Error Codes <gen-errors>` chapter.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.