1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2 .. c:namespace:: MC
3
4 .. _media_ioc_enum_links:
5
6 **************************
7 ioctl MEDIA_IOC_ENUM_LINKS
8 **************************
9
10 Name
11 ====
12
13 MEDIA_IOC_ENUM_LINKS - Enumerate all pads and links for a given entity
14
15 Synopsis
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
22 Arguments
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
31 Description
32 ===========
33
34 To enumerate pads and/or links for a given entity, applications set the
35 entity field of a struct :c:type:`media_links_enum`
36 structure and initialize the struct
37 :c:type:`media_pad_desc` and struct
38 :c:type:`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 :ref:`MEDIA_IOC_ENUM_ENTITIES`.
46
47 If the ``links`` field is not NULL, the driver fills the ``links`` array
48 with information about the entity's outbound links. The array must have
49 enough room to store all the entity's outbound links. The number of
50 outbound links can be retrieved with :ref:`MEDIA_IOC_ENUM_ENTITIES`.
51
52 Only forward links that originate at one of the entity's source pads are
53 returned 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
136 Return Value
137 ============
138
139 On success 0 is returned, on error -1 and the ``errno`` variable is set
140 appropriately. The generic error codes are described at the
141 :ref:`Generic Error Codes <gen-errors>` chapter.
142
143 EINVAL
144 The struct :c:type:`media_links_enum` ``id``
145 references a non-existing entity.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.