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