tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
1.. -*- coding: utf-8; mode: rst -*-
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
34
35Description
36===========
37
38Subscribe or unsubscribe V4L2 event. Subscribed events are dequeued by
39using the :ref:`VIDIOC_DQEVENT` ioctl.
40
41
42.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
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
75.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
76
77.. _event-flags:
78
79.. flat-table:: Event Flags
80 :header-rows: 0
81 :stub-columns: 0
82 :widths: 3 1 4
83
84 * - ``V4L2_EVENT_SUB_FL_SEND_INITIAL``
85 - 0x0001
86 - When this event is subscribed an initial event will be sent
87 containing the current status. This only makes sense for events
88 that are triggered by a status change such as ``V4L2_EVENT_CTRL``.
89 Other events will ignore this flag.
90 * - ``V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK``
91 - 0x0002
92 - If set, then events directly caused by an ioctl will also be sent
93 to the filehandle that called that ioctl. For example, changing a
94 control using :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` will cause
95 a V4L2_EVENT_CTRL to be sent back to that same filehandle.
96 Normally such events are suppressed to prevent feedback loops
97 where an application changes a control to a one value and then
98 another, and then receives an event telling it that that control
99 has changed to the first value.
100
101 Since it can't tell whether that event was caused by another
102 application or by the :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>`
103 call it is hard to decide whether to set the control to the value
104 in the event, or ignore it.
105
106 Think carefully when you set this flag so you won't get into
107 situations like that.
108
109
110Return Value
111============
112
113On success 0 is returned, on error -1 and the ``errno`` variable is set
114appropriately. The generic error codes are described at the
115:ref:`Generic Error Codes <gen-errors>` chapter.