1 <refentry id="media-ioc-enum-entities">
3 <refentrytitle>ioctl MEDIA_IOC_ENUM_ENTITIES</refentrytitle>
8 <refname>MEDIA_IOC_ENUM_ENTITIES</refname>
9 <refpurpose>Enumerate entities and their properties</refpurpose>
15 <funcdef>int <function>ioctl</function></funcdef>
16 <paramdef>int <parameter>fd</parameter></paramdef>
17 <paramdef>int <parameter>request</parameter></paramdef>
18 <paramdef>struct media_entity_desc *<parameter>argp</parameter></paramdef>
24 <title>Arguments</title>
28 <term><parameter>fd</parameter></term>
30 <para>File descriptor returned by
31 <link linkend='media-func-open'><function>open()</function></link>.</para>
35 <term><parameter>request</parameter></term>
37 <para>MEDIA_IOC_ENUM_ENTITIES</para>
41 <term><parameter>argp</parameter></term>
50 <title>Description</title>
51 <para>To query the attributes of an entity, applications set the id field
52 of a &media-entity-desc; structure and call the MEDIA_IOC_ENUM_ENTITIES
53 ioctl with a pointer to this structure. The driver fills the rest of the
54 structure or returns an &EINVAL; when the id is invalid.</para>
55 <para>Entities can be enumerated by or'ing the id with the
56 <constant>MEDIA_ENT_ID_FLAG_NEXT</constant> flag. The driver will return
57 information about the entity with the smallest id strictly larger than the
58 requested one ('next entity'), or the &EINVAL; if there is none.</para>
59 <para>Entity IDs can be non-contiguous. Applications must
60 <emphasis>not</emphasis> try to enumerate entities by calling
61 MEDIA_IOC_ENUM_ENTITIES with increasing id's until they get an error.</para>
63 <table pgwide="1" frame="none" id="media-entity-desc">
64 <title>struct <structname>media_entity_desc</structname></title>
66 <colspec colname="c1" />
67 <colspec colname="c2" />
68 <colspec colname="c3" />
69 <colspec colname="c4" />
70 <colspec colname="c5" />
74 <entry><structfield>id</structfield></entry>
77 <entry>Entity id, set by the application. When the id is or'ed with
78 <constant>MEDIA_ENT_ID_FLAG_NEXT</constant>, the driver clears the
79 flag and returns the first entity with a larger id.</entry>
83 <entry><structfield>name</structfield>[32]</entry>
86 <entry>Entity name as an UTF-8 NULL-terminated string.</entry>
90 <entry><structfield>type</structfield></entry>
93 <entry>Entity type, see <xref linkend="media-entity-type" /> for details.</entry>
97 <entry><structfield>revision</structfield></entry>
100 <entry>Entity revision. Always zero (obsolete)</entry>
104 <entry><structfield>flags</structfield></entry>
107 <entry>Entity flags, see <xref linkend="media-entity-flag" /> for details.</entry>
111 <entry><structfield>group_id</structfield></entry>
114 <entry>Entity group ID. Always zero (obsolete)</entry>
118 <entry><structfield>pads</structfield></entry>
121 <entry>Number of pads</entry>
125 <entry><structfield>links</structfield></entry>
128 <entry>Total number of outbound links. Inbound links are not counted
129 in this field.</entry>
136 <entry>struct</entry>
137 <entry><structfield>dev</structfield></entry>
139 <entry>Valid for (sub-)devices that create a single device node.</entry>
145 <entry><structfield>major</structfield></entry>
146 <entry>Device node major number.</entry>
152 <entry><structfield>minor</structfield></entry>
153 <entry>Device node minor number.</entry>
158 <entry><structfield>raw</structfield>[184]</entry>
172 <term><errorcode>EINVAL</errorcode></term>
174 <para>The &media-entity-desc; <structfield>id</structfield> references
175 a non-existing entity.</para>