[deliverable/linux.git] / Documentation / linux_tv / media / mediactl / media-ioc-enum-links.rst

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

.. _media-ioc-enum-links:

**************************
ioctl MEDIA_IOC_ENUM_LINKS
**************************

*man MEDIA_IOC_ENUM_LINKS(2)*

Enumerate all pads and links for a given entity


Synopsis
========

.. cpp:function:: int ioctl( int fd, int request, struct media_links_enum *argp )

Arguments
=========

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

``request``
    MEDIA_IOC_ENUM_LINKS

``argp``


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

To enumerate pads and/or links for a given entity, applications set the
entity field of a struct :ref:`media_links_enum <media-links-enum>`
structure and initialize the struct
:ref:`media_pad_desc <media-pad-desc>` and struct
:ref:`media_link_desc <media-link-desc>` structure arrays pointed by
the ``pads`` and ``links`` fields. They then call the
MEDIA_IOC_ENUM_LINKS ioctl with a pointer to this structure.

If the ``pads`` field is not NULL, the driver fills the ``pads`` array
with information about the entity's pads. The array must have enough
room to store all the entity's pads. The number of pads can be retrieved
with the :ref:`MEDIA_IOC_ENUM_ENTITIES <media-ioc-enum-entities>`
ioctl.

If the ``links`` field is not NULL, the driver fills the ``links`` array
with information about the entity's outbound links. The array must have
enough room to store all the entity's outbound links. The number of
outbound links can be retrieved with the
:ref:`MEDIA_IOC_ENUM_ENTITIES <media-ioc-enum-entities>` ioctl.

Only forward links that originate at one of the entity's source pads are
returned during the enumeration process.


.. _media-links-enum:

.. flat-table:: struct media_links_enum
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2


    -  .. row 1

       -  __u32

       -  ``entity``

       -  Entity id, set by the application.

    -  .. row 2

       -  struct :ref:`media_pad_desc <media-pad-desc>`

       -  \*\ ``pads``

       -  Pointer to a pads array allocated by the application. Ignored if
	  NULL.

    -  .. row 3

       -  struct :ref:`media_link_desc <media-link-desc>`

       -  \*\ ``links``

       -  Pointer to a links array allocated by the application. Ignored if
	  NULL.


.. _media-pad-desc:

.. flat-table:: struct media_pad_desc
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2


    -  .. row 1

       -  __u32

       -  ``entity``

       -  ID of the entity this pad belongs to.

    -  .. row 2

       -  __u16

       -  ``index``

       -  0-based pad index.

    -  .. row 3

       -  __u32

       -  ``flags``

       -  Pad flags, see :ref:`media-pad-flag` for more details.


.. _media-link-desc:

.. flat-table:: struct media_link_desc
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2


    -  .. row 1

       -  struct :ref:`media_pad_desc <media-pad-desc>`

       -  ``source``

       -  Pad at the origin of this link.

    -  .. row 2

       -  struct :ref:`media_pad_desc <media-pad-desc>`

       -  ``sink``

       -  Pad at the target of this link.

    -  .. row 3

       -  __u32

       -  ``flags``

       -  Link flags, see :ref:`media-link-flag` for more details.


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 struct :ref:`media_links_enum <media-links-enum>` ``id``
    references a non-existing entity.
Commit	Line	Data
5377d91f MH	1	.. -- coding: utf-8; mode: rst --
	2
	3	.. _media-ioc-enum-links:
	4
	5	**************************
	6	ioctl MEDIA_IOC_ENUM_LINKS
	7	**************************
	8
	9	man MEDIA_IOC_ENUM_LINKS(2)
	10
	11	Enumerate all pads and links for a given entity
	12
	13
	14	Synopsis
	15	========
	16
b7e67f6c	17	.. cpp:function:: int ioctl( int fd, int request, struct media_links_enum *argp )
5377d91f MH	18
	19	Arguments
	20	=========
	21
	22	``fd``
	23	File descriptor returned by :ref:`open() <media-func-open>`.
	24
	25	``request``
	26	MEDIA_IOC_ENUM_LINKS
	27
	28	``argp``
	29
	30
	31	Description
	32	===========
	33
	34	To enumerate pads and/or links for a given entity, applications set the
	35	entity field of a struct :ref:`media_links_enum <media-links-enum>`
	36	structure and initialize the struct
	37	:ref:`media_pad_desc <media-pad-desc>` and struct
	38	:ref:`media_link_desc <media-link-desc>` structure arrays pointed by
	39	the ``pads`` and ``links`` fields. They then call the
	40	MEDIA_IOC_ENUM_LINKS ioctl with a pointer to this structure.
	41
	42	If the ``pads`` field is not NULL, the driver fills the ``pads`` array
	43	with information about the entity's pads. The array must have enough
	44	room to store all the entity's pads. The number of pads can be retrieved
	45	with the :ref:`MEDIA_IOC_ENUM_ENTITIES <media-ioc-enum-entities>`
	46	ioctl.
	47
	48	If the ``links`` field is not NULL, the driver fills the ``links`` array
	49	with information about the entity's outbound links. The array must have
	50	enough room to store all the entity's outbound links. The number of
	51	outbound links can be retrieved with the
	52	:ref:`MEDIA_IOC_ENUM_ENTITIES <media-ioc-enum-entities>` ioctl.
	53
	54	Only forward links that originate at one of the entity's source pads are
	55	returned during the enumeration process.
	56
	57
	58	.. _media-links-enum:
	59
	60	.. flat-table:: struct media_links_enum
	61	:header-rows: 0
	62	:stub-columns: 0
	63	:widths: 1 1 2
	64
	65
	66	- .. row 1
	67
	68	- __u32
	69
	70	- ``entity``
	71
	72	- Entity id, set by the application.
	73
	74	- .. row 2
	75
	76	- struct :ref:`media_pad_desc <media-pad-desc>`
	77
5d2b3f12	78	- \*\ ``pads``
5377d91f MH	79
5377d91f MH	80	- Pointer to a pads array allocated by the application. Ignored if
0579e6e3	81	NULL.
5377d91f MH	82
	83	- .. row 3
	84
	85	- struct :ref:`media_link_desc <media-link-desc>`
	86
5d2b3f12	87	- \*\ ``links``
5377d91f MH	88
5377d91f MH	89	- Pointer to a links array allocated by the application. Ignored if
0579e6e3	90	NULL.
5377d91f MH	91
	92
	93
	94	.. _media-pad-desc:
	95
	96	.. flat-table:: struct media_pad_desc
	97	:header-rows: 0
	98	:stub-columns: 0
	99	:widths: 1 1 2
	100
	101
	102	- .. row 1
	103
	104	- __u32
	105
	106	- ``entity``
	107
	108	- ID of the entity this pad belongs to.
	109
	110	- .. row 2
	111
	112	- __u16
	113
	114	- ``index``
	115
	116	- 0-based pad index.
	117
	118	- .. row 3
	119
	120	- __u32
	121
	122	- ``flags``
	123
	124	- Pad flags, see :ref:`media-pad-flag` for more details.
	125
	126
	127
	128	.. _media-link-desc:
	129
	130	.. flat-table:: struct media_link_desc
	131	:header-rows: 0
	132	:stub-columns: 0
	133	:widths: 1 1 2
	134
	135
	136	- .. row 1
	137
	138	- struct :ref:`media_pad_desc <media-pad-desc>`
	139
	140	- ``source``
	141
	142	- Pad at the origin of this link.
	143
	144	- .. row 2
	145
	146	- struct :ref:`media_pad_desc <media-pad-desc>`
	147
	148	- ``sink``
	149
	150	- Pad at the target of this link.
	151
	152	- .. row 3
	153
	154	- __u32
155
156	- ``flags``
157
158	- Link flags, see :ref:`media-link-flag` for more details.
159
160
161
162	Return Value
163	============
164
165	On success 0 is returned, on error -1 and the ``errno`` variable is set
166	appropriately. The generic error codes are described at the
167	:ref:`Generic Error Codes <gen-errors>` chapter.
168
169	EINVAL
170	The struct :ref:`media_links_enum <media-links-enum>` ``id``
171	references a non-existing entity.