Documentation/media/uapi/v4l/vidioc-g-priority.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _VIDIOC_G_PRIORITY:
   4
   5 ******************************************
   6 ioctl VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY
   7 ******************************************
   8
   9 Name
  10 ====
  11
  12 VIDIOC_G_PRIORITY - VIDIOC_S_PRIORITY - Query or request the access priority associated with a file descriptor
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. cpp:function:: int ioctl( int fd, int request, enum v4l2_priority *argp )
  19
  20 .. cpp:function:: int ioctl( int fd, int request, const enum v4l2_priority *argp )
  21
  22
  23 Arguments
  24 =========
  25
  26 ``fd``
  27     File descriptor returned by :ref:`open() <func-open>`.
  28
  29 ``request``
  30     VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY
  31
  32 ``argp``
  33     Pointer to an enum v4l2_priority type.
  34
  35
  36 Description
  37 ===========
  38
  39 To query the current access priority applications call the
  40 :ref:`VIDIOC_G_PRIORITY <VIDIOC_G_PRIORITY>` ioctl with a pointer to an enum v4l2_priority
  41 variable where the driver stores the current priority.
  42
  43 To request an access priority applications store the desired priority in
  44 an enum v4l2_priority variable and call :ref:`VIDIOC_S_PRIORITY <VIDIOC_G_PRIORITY>` ioctl
  45 with a pointer to this variable.
  46
  47
  48 .. _v4l2-priority:
  49
  50 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
  51
  52 .. flat-table:: enum v4l2_priority
  53     :header-rows:  0
  54     :stub-columns: 0
  55     :widths:       3 1 4
  56
  57
  58     -  .. row 1
  59
  60        -  ``V4L2_PRIORITY_UNSET``
  61
  62        -  0
  63
  64        -
  65
  66     -  .. row 2
  67
  68        -  ``V4L2_PRIORITY_BACKGROUND``
  69
  70        -  1
  71
  72        -  Lowest priority, usually applications running in background, for
  73           example monitoring VBI transmissions. A proxy application running
  74           in user space will be necessary if multiple applications want to
  75           read from a device at this priority.
  76
  77     -  .. row 3
  78
  79        -  ``V4L2_PRIORITY_INTERACTIVE``
  80
  81        -  2
  82
  83        -
  84
  85     -  .. row 4
  86
  87        -  ``V4L2_PRIORITY_DEFAULT``
  88
  89        -  2
  90
  91        -  Medium priority, usually applications started and interactively
  92           controlled by the user. For example TV viewers, Teletext browsers,
  93           or just "panel" applications to change the channel or video
  94           controls. This is the default priority unless an application
  95           requests another.
  96
  97     -  .. row 5
  98
  99        -  ``V4L2_PRIORITY_RECORD``
 100
 101        -  3
 102
 103        -  Highest priority. Only one file descriptor can have this priority,
 104           it blocks any other fd from changing device properties. Usually
 105           applications which must not be interrupted, like video recording.
 106
 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.
 114
 115 EINVAL
 116     The requested priority value is invalid.
 117
 118 EBUSY
 119     Another application already requested higher priority.