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/media/uapi/fdl-appendix.rst. 7.. 8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections 9 10.. _media_ioc_enum_entities: 11 12***************************** 13ioctl MEDIA_IOC_ENUM_ENTITIES 14***************************** 15 16Name 17==== 18 19MEDIA_IOC_ENUM_ENTITIES - Enumerate entities and their properties 20 21 22Synopsis 23======== 24 25.. c:function:: int ioctl( int fd, MEDIA_IOC_ENUM_ENTITIES, struct media_entity_desc *argp ) 26 :name: MEDIA_IOC_ENUM_ENTITIES 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_entity_desc`. 37 38 39Description 40=========== 41 42To query the attributes of an entity, applications set the id field of a 43struct :c:type:`media_entity_desc` structure and 44call the MEDIA_IOC_ENUM_ENTITIES ioctl with a pointer to this 45structure. The driver fills the rest of the structure or returns an 46EINVAL error code when the id is invalid. 47 48.. _media-ent-id-flag-next: 49 50Entities can be enumerated by or'ing the id with the 51``MEDIA_ENT_ID_FLAG_NEXT`` flag. The driver will return information 52about the entity with the smallest id strictly larger than the requested 53one ('next entity'), or the ``EINVAL`` error code if there is none. 54 55Entity IDs can be non-contiguous. Applications must *not* try to 56enumerate entities by calling MEDIA_IOC_ENUM_ENTITIES with increasing 57id's until they get an error. 58 59 60.. c:type:: media_entity_desc 61 62.. tabularcolumns:: |p{1.5cm}|p{1.7cm}|p{1.6cm}|p{1.5cm}|p{11.2cm}| 63 64.. flat-table:: struct media_entity_desc 65 :header-rows: 0 66 :stub-columns: 0 67 :widths: 1 1 1 1 8 68 69 * - __u32 70 - ``id`` 71 - 72 - 73 - Entity ID, set by the application. When the ID is or'ed with 74 ``MEDIA_ENT_ID_FLAG_NEXT``, the driver clears the flag and returns 75 the first entity with a larger ID. Do not expect that the ID will 76 always be the same for each instance of the device. In other words, 77 do not hardcode entity IDs in an application. 78 79 * - char 80 - ``name``\ [32] 81 - 82 - 83 - Entity name as an UTF-8 NULL-terminated string. This name must be unique 84 within the media topology. 85 86 * - __u32 87 - ``type`` 88 - 89 - 90 - Entity type, see :ref:`media-entity-functions` for details. 91 92 * - __u32 93 - ``revision`` 94 - 95 - 96 - Entity revision. Always zero (obsolete) 97 98 * - __u32 99 - ``flags`` 100 - 101 - 102 - Entity flags, see :ref:`media-entity-flag` for details. 103 104 * - __u32 105 - ``group_id`` 106 - 107 - 108 - Entity group ID. Always zero (obsolete) 109 110 * - __u16 111 - ``pads`` 112 - 113 - 114 - Number of pads 115 116 * - __u16 117 - ``links`` 118 - 119 - 120 - Total number of outbound links. Inbound links are not counted in 121 this field. 122 123 * - __u32 124 - ``reserved[4]`` 125 - 126 - 127 - Reserved for future extensions. Drivers and applications must set 128 the array to zero. 129 130 * - union 131 132 * - 133 - struct 134 - ``dev`` 135 - 136 - Valid for (sub-)devices that create a single device node. 137 138 * - 139 - 140 - __u32 141 - ``major`` 142 - Device node major number. 143 144 * - 145 - 146 - __u32 147 - ``minor`` 148 - Device node minor number. 149 150 * - 151 - __u8 152 - ``raw``\ [184] 153 - 154 - 155 156 157Return Value 158============ 159 160On success 0 is returned, on error -1 and the ``errno`` variable is set 161appropriately. The generic error codes are described at the 162:ref:`Generic Error Codes <gen-errors>` chapter. 163 164EINVAL 165 The struct :c:type:`media_entity_desc` ``id`` 166 references a non-existing entity. 167