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