1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2.. c:namespace:: MC
3
4.. _media_ioc_enum_links:
5
6**************************
7ioctl MEDIA_IOC_ENUM_LINKS
8**************************
9
10Name
11====
12
13MEDIA_IOC_ENUM_LINKS - Enumerate all pads and links for a given entity
14
15Synopsis
16========
17
18.. c:macro:: MEDIA_IOC_ENUM_LINKS
19
20``int ioctl(int fd, MEDIA_IOC_ENUM_LINKS, struct media_links_enum *argp)``
21
22Arguments
23=========
24
25``fd``
26    File descriptor returned by :c:func:`open()`.
27
28``argp``
29    Pointer to struct :c:type:`media_links_enum`.
30
31Description
32===========
33
34To enumerate pads and/or links for a given entity, applications set the
35entity field of a struct :c:type:`media_links_enum`
36structure and initialize the struct
37:c:type:`media_pad_desc` and struct
38:c:type:`media_link_desc` structure arrays pointed by
39the ``pads`` and ``links`` fields. They then call the
40MEDIA_IOC_ENUM_LINKS ioctl with a pointer to this structure.
41
42If the ``pads`` field is not NULL, the driver fills the ``pads`` array
43with information about the entity's pads. The array must have enough
44room to store all the entity's pads. The number of pads can be retrieved
45with :ref:`MEDIA_IOC_ENUM_ENTITIES`.
46
47If the ``links`` field is not NULL, the driver fills the ``links`` array
48with information about the entity's outbound links. The array must have
49enough room to store all the entity's outbound links. The number of
50outbound links can be retrieved with :ref:`MEDIA_IOC_ENUM_ENTITIES`.
51
52Only forward links that originate at one of the entity's source pads are
53returned during the enumeration process.
54
55.. c:type:: media_links_enum
56
57.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
58
59.. flat-table:: struct media_links_enum
60    :header-rows:  0
61    :stub-columns: 0
62    :widths:       1 1 2
63
64    *  -  __u32
65       -  ``entity``
66       -  Entity id, set by the application.
67
68    *  -  struct :c:type:`media_pad_desc`
69       -  \*\ ``pads``
70       -  Pointer to a pads array allocated by the application. Ignored if
71	  NULL.
72
73    *  -  struct :c:type:`media_link_desc`
74       -  \*\ ``links``
75       -  Pointer to a links array allocated by the application. Ignored if
76	  NULL.
77
78    *  -  __u32
79       -  ``reserved[4]``
80       -  Reserved for future extensions. Drivers and applications must set
81          the array to zero.
82
83.. c:type:: media_pad_desc
84
85.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
86
87.. flat-table:: struct media_pad_desc
88    :header-rows:  0
89    :stub-columns: 0
90    :widths:       1 1 2
91
92    *  -  __u32
93       -  ``entity``
94       -  ID of the entity this pad belongs to.
95
96    *  -  __u16
97       -  ``index``
98       -  Pad index, starts at 0.
99
100    *  -  __u32
101       -  ``flags``
102       -  Pad flags, see :ref:`media-pad-flag` for more details.
103
104    *  -  __u32
105       -  ``reserved[2]``
106       -  Reserved for future extensions. Drivers and applications must set
107          the array to zero.
108
109
110.. c:type:: media_link_desc
111
112.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
113
114.. flat-table:: struct media_link_desc
115    :header-rows:  0
116    :stub-columns: 0
117    :widths:       1 1 2
118
119    *  -  struct :c:type:`media_pad_desc`
120       -  ``source``
121       -  Pad at the origin of this link.
122
123    *  -  struct :c:type:`media_pad_desc`
124       -  ``sink``
125       -  Pad at the target of this link.
126
127    *  -  __u32
128       -  ``flags``
129       -  Link flags, see :ref:`media-link-flag` for more details.
130
131    *  -  __u32
132       -  ``reserved[2]``
133       -  Reserved for future extensions. Drivers and applications must set
134          the array to zero.
135
136Return Value
137============
138
139On success 0 is returned, on error -1 and the ``errno`` variable is set
140appropriately. The generic error codes are described at the
141:ref:`Generic Error Codes <gen-errors>` chapter.
142
143EINVAL
144    The struct :c:type:`media_links_enum` ``id``
145    references a non-existing entity.
146