[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
******************************************

NAME
====

VIDIOC_G_PRIORITY - 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
586027ce MCC	9	NAME
586027ce MCC	10	====
5377d91f	11
586027ce	12	VIDIOC_G_PRIORITY - VIDIOC_S_PRIORITY - Query or request the access priority associated with a file descriptor
5377d91f	13
586027ce	14	SYNOPSIS
5377d91f MH	15	========
	16
	17	.. c:function:: int ioctl( int fd, int request, enum v4l2_priority *argp )
	18
	19	.. c:function:: int ioctl( int fd, int request, const enum v4l2_priority *argp )
	20
586027ce MCC	21
586027ce MCC	22	ARGUMENTS
5377d91f MH	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
586027ce	35	DESCRIPTION
5377d91f MH	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
5377d91f MH	104
586027ce	105	RETURN VALUE
5377d91f MH	106	============
	107
	108	On success 0 is returned, on error -1 and the ``errno`` variable is set
	109	appropriately. The generic error codes are described at the
	110	:ref:`Generic Error Codes <gen-errors>` chapter.
	111
	112	EINVAL
	113	The requested priority value is invalid.
	114
	115	EBUSY
	116	Another application already requested higher priority.