1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2
3.. _VIDIOC_G_PRIORITY:
4
5******************************************
6ioctl VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY
7******************************************
8
9Name
10====
11
12VIDIOC_G_PRIORITY - VIDIOC_S_PRIORITY - Query or request the access priority associated with a file descriptor
13
14
15Synopsis
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
25Arguments
26=========
27
28``fd``
29    File descriptor returned by :ref:`open() <func-open>`.
30
31``argp``
32    Pointer to an enum :c:type:`v4l2_priority` type.
33
34
35Description
36===========
37
38To 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
40variable where the driver stores the current priority.
41
42To request an access priority applications store the desired priority in
43an enum v4l2_priority variable and call :ref:`VIDIOC_S_PRIORITY <VIDIOC_G_PRIORITY>` ioctl
44with 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    * - ``V4L2_PRIORITY_UNSET``
57      - 0
58      -
59    * - ``V4L2_PRIORITY_BACKGROUND``
60      - 1
61      - Lowest priority, usually applications running in background, for
62	example monitoring VBI transmissions. A proxy application running
63	in user space will be necessary if multiple applications want to
64	read from a device at this priority.
65    * - ``V4L2_PRIORITY_INTERACTIVE``
66      - 2
67      -
68    * - ``V4L2_PRIORITY_DEFAULT``
69      - 2
70      - Medium priority, usually applications started and interactively
71	controlled by the user. For example TV viewers, Teletext browsers,
72	or just "panel" applications to change the channel or video
73	controls. This is the default priority unless an application
74	requests another.
75    * - ``V4L2_PRIORITY_RECORD``
76      - 3
77      - Highest priority. Only one file descriptor can have this priority,
78	it blocks any other fd from changing device properties. Usually
79	applications which must not be interrupted, like video recording.
80
81
82Return Value
83============
84
85On success 0 is returned, on error -1 and the ``errno`` variable is set
86appropriately. The generic error codes are described at the
87:ref:`Generic Error Codes <gen-errors>` chapter.
88
89EINVAL
90    The requested priority value is invalid.
91
92EBUSY
93    Another application already requested higher priority.
94