[deliverable/linux.git] / Documentation / linux_tv / media / v4l / vidioc-g-priority.rst

.. -*- coding: utf-8; mode: rst -*-

.. _VIDIOC_G_PRIORITY:

******************************************
ioctl VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY
******************************************

*man VIDIOC_G_PRIORITY(2)*

VIDIOC_S_PRIORITY
Query or request the access priority associated with a file descriptor


Synopsis
========

.. c:function:: int ioctl( int fd, int request, enum v4l2_priority *argp )

.. c:function:: int ioctl( int fd, int request, const enum v4l2_priority *argp )

Arguments
=========

``fd``
    File descriptor returned by :ref:`open() <func-open>`.

``request``
    VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY

``argp``
    Pointer to an enum v4l2_priority type.


Description
===========

To query the current access priority applications call the
:ref:`VIDIOC_G_PRIORITY <VIDIOC_G_PRIORITY>` ioctl with a pointer to an enum v4l2_priority
variable where the driver stores the current priority.

To request an access priority applications store the desired priority in
an enum v4l2_priority variable and call :ref:`VIDIOC_S_PRIORITY <VIDIOC_G_PRIORITY>` ioctl
with a pointer to this variable.


.. _v4l2-priority:

.. flat-table:: enum v4l2_priority
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4


    -  .. row 1

       -  ``V4L2_PRIORITY_UNSET``

       -  0

       -  

    -  .. row 2

       -  ``V4L2_PRIORITY_BACKGROUND``

       -  1

       -  Lowest priority, usually applications running in background, for
          example monitoring VBI transmissions. A proxy application running
          in user space will be necessary if multiple applications want to
          read from a device at this priority.

    -  .. row 3

       -  ``V4L2_PRIORITY_INTERACTIVE``

       -  2

       -  

    -  .. row 4

       -  ``V4L2_PRIORITY_DEFAULT``

       -  2

       -  Medium priority, usually applications started and interactively
          controlled by the user. For example TV viewers, Teletext browsers,
          or just "panel" applications to change the channel or video
          controls. This is the default priority unless an application
          requests another.

    -  .. row 5

       -  ``V4L2_PRIORITY_RECORD``

       -  3

       -  Highest priority. Only one file descriptor can have this priority,
          it blocks any other fd from changing device properties. Usually
          applications which must not be interrupted, like video recording.


Return Value
============

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

EINVAL
    The requested priority value is invalid.

EBUSY
    Another application already requested higher priority.


.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------
Commit	Line	Data
5377d91f MH	1	.. -- coding: utf-8; mode: rst --
5377d91f MH	2
af4a4d0d	3	.. _VIDIOC_G_PRIORITY:
5377d91f MH	4
	5	******************************************
	6	ioctl VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY
	7	******************************************
	8
	9	man VIDIOC_G_PRIORITY(2)
	10
	11	VIDIOC_S_PRIORITY
	12	Query or request the access priority associated with a file descriptor
	13
	14
	15	Synopsis
	16	========
	17
	18	.. c:function:: int ioctl( int fd, int request, enum v4l2_priority *argp )
	19
	20	.. c:function:: int ioctl( int fd, int request, const enum v4l2_priority *argp )
	21
	22	Arguments
	23	=========
	24
	25	``fd``
	26	File descriptor returned by :ref:`open() <func-open>`.
	27
	28	``request``
	29	VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY
	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
4e03cb76	39	:ref:`VIDIOC_G_PRIORITY <VIDIOC_G_PRIORITY>` ioctl with a pointer to an enum v4l2_priority
5377d91f MH	40	variable where the driver stores the current priority.
	41
	42	To request an access priority applications store the desired priority in
2212ff25	43	an enum v4l2_priority variable and call :ref:`VIDIOC_S_PRIORITY <VIDIOC_G_PRIORITY>` ioctl
5377d91f MH	44	with a pointer to this variable.
	45
	46
	47	.. _v4l2-priority:
	48
	49	.. flat-table:: enum v4l2_priority
	50	:header-rows: 0
	51	:stub-columns: 0
	52	:widths: 3 1 4
	53
	54
	55	- .. row 1
	56
	57	- ``V4L2_PRIORITY_UNSET``
	58
	59	- 0
	60
	61	-
	62
	63	- .. row 2
	64
	65	- ``V4L2_PRIORITY_BACKGROUND``
	66
	67	- 1
	68
	69	- Lowest priority, usually applications running in background, for
	70	example monitoring VBI transmissions. A proxy application running
	71	in user space will be necessary if multiple applications want to
	72	read from a device at this priority.
	73
	74	- .. row 3
	75
	76	- ``V4L2_PRIORITY_INTERACTIVE``
	77
	78	- 2
	79
	80	-
	81
	82	- .. row 4
	83
	84	- ``V4L2_PRIORITY_DEFAULT``
	85
	86	- 2
	87
	88	- Medium priority, usually applications started and interactively
	89	controlled by the user. For example TV viewers, Teletext browsers,
	90	or just "panel" applications to change the channel or video
	91	controls. This is the default priority unless an application
	92	requests another.
	93
	94	- .. row 5
	95
	96	- ``V4L2_PRIORITY_RECORD``
	97
	98	- 3
	99
	100	- Highest priority. Only one file descriptor can have this priority,
	101	it blocks any other fd from changing device properties. Usually
	102	applications which must not be interrupted, like video recording.
	103
	104
	105
	106	Return Value
	107	============
108
109	On success 0 is returned, on error -1 and the ``errno`` variable is set
110	appropriately. The generic error codes are described at the
111	:ref:`Generic Error Codes <gen-errors>` chapter.
112
113	EINVAL
114	The requested priority value is invalid.
115
116	EBUSY
117	Another application already requested higher priority.
118
119
120	.. ------------------------------------------------------------------------------
121	.. This file was automatically converted from DocBook-XML with the dbxml
122	.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
123	.. from the linux kernel, refer to:
124	..
125	.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
126	.. ------------------------------------------------------------------------------