Documentation/media/uapi/dvb/video-get-event.rst

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