[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.
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
0579e6e3	61	-
5377d91f MH	62
	63	- .. row 2
	64
	65	- ``V4L2_PRIORITY_BACKGROUND``
	66
	67	- 1
	68
	69	- Lowest priority, usually applications running in background, for
0579e6e3 MCC	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.
5377d91f MH	73
	74	- .. row 3
	75
	76	- ``V4L2_PRIORITY_INTERACTIVE``
	77
	78	- 2
	79
0579e6e3	80	-
5377d91f MH	81
	82	- .. row 4
	83
	84	- ``V4L2_PRIORITY_DEFAULT``
	85
	86	- 2
	87
	88	- Medium priority, usually applications started and interactively
0579e6e3 MCC	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.
5377d91f MH	93
	94	- .. row 5
	95
	96	- ``V4L2_PRIORITY_RECORD``
	97
	98	- 3
	99
	100	- Highest priority. Only one file descriptor can have this priority,
0579e6e3 MCC	101	it blocks any other fd from changing device properties. Usually
0579e6e3 MCC	102	applications which must not be interrupted, like video recording.
5377d91f MH	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.