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