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