1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2.. c:namespace:: DTV.video
3
4.. _VIDEO_GET_EVENT:
5
6===============
7VIDEO_GET_EVENT
8===============
9
10Name
11----
12
13VIDEO_GET_EVENT
14
15.. attention:: This ioctl is deprecated.
16
17Synopsis
18--------
19
20.. c:macro:: VIDEO_GET_EVENT
21
22``int ioctl(fd, VIDEO_GET_EVENT, struct video_event *ev)``
23
24Arguments
25---------
26
27.. flat-table::
28    :header-rows:  0
29    :stub-columns: 0
30
31    -  .. row 1
32
33       -  int fd
34
35       -  File descriptor returned by a previous call to open().
36
37    -  .. row 2
38
39       -  int request
40
41       -  Equals VIDEO_GET_EVENT for this command.
42
43    -  .. row 3
44
45       -  struct video_event \*ev
46
47       -  Points to the location where the event, if any, is to be stored.
48
49Description
50-----------
51
52This ioctl is for Digital TV devices only. To get events from a V4L2 decoder
53use the V4L2 :ref:`VIDIOC_DQEVENT` ioctl instead.
54
55This ioctl call returns an event of type video_event if available. If
56an event is not available, the behavior depends on whether the device is
57in blocking or non-blocking mode. In the latter case, the call fails
58immediately with errno set to ``EWOULDBLOCK``. In the former case, the call
59blocks until an event becomes available. The standard Linux poll()
60and/or select() system calls can be used with the device file descriptor
61to watch for new events. For select(), the file descriptor should be
62included in the exceptfds argument, and for poll(), POLLPRI should be
63specified as the wake-up condition. Read-only permissions are sufficient
64for this ioctl call.
65
66.. c:type:: video_event
67
68.. code-block:: c
69
70	struct video_event {
71		__s32 type;
72	#define VIDEO_EVENT_SIZE_CHANGED	1
73	#define VIDEO_EVENT_FRAME_RATE_CHANGED	2
74	#define VIDEO_EVENT_DECODER_STOPPED 	3
75	#define VIDEO_EVENT_VSYNC 		4
76		long timestamp;
77		union {
78			video_size_t size;
79			unsigned int frame_rate;	/* in frames per 1000sec */
80			unsigned char vsync_field;	/* unknown/odd/even/progressive */
81		} u;
82	};
83
84Return Value
85------------
86
87On success 0 is returned, on error -1 and the ``errno`` variable is set
88appropriately. The generic error codes are described at the
89:ref:`Generic Error Codes <gen-errors>` chapter.
90
91.. flat-table::
92    :header-rows:  0
93    :stub-columns: 0
94
95    -  .. row 1
96
97       -  ``EWOULDBLOCK``
98
99       -  There is no event pending, and the device is in non-blocking mode.
100
101    -  .. row 2
102
103       -  ``EOVERFLOW``
104
105       -  Overflow in event queue - one or more events were lost.
106