Documentation/linux_tv/media/mediactl/media-ioc-enum-links.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _media-ioc-enum-links:
   4
   5 **************************
   6 ioctl MEDIA_IOC_ENUM_LINKS
   7 **************************
   8
   9 *man MEDIA_IOC_ENUM_LINKS(2)*
  10
  11 Enumerate all pads and links for a given entity
  12
  13
  14 Synopsis
  15 ========
  16
  17 .. cpp:function:: int ioctl( int fd, int request, struct media_links_enum *argp )
  18
  19 Arguments
  20 =========
  21
  22 ``fd``
  23     File descriptor returned by :ref:`open() <media-func-open>`.
  24
  25 ``request``
  26     MEDIA_IOC_ENUM_LINKS
  27
  28 ``argp``
  29
  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 :ref:`media_links_enum <media-links-enum>`
  36 structure and initialize the struct
  37 :ref:`media_pad_desc <media-pad-desc>` and struct
  38 :ref:`media_link_desc <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 the :ref:`MEDIA_IOC_ENUM_ENTITIES <media-ioc-enum-entities>`
  46 ioctl.
  47
  48 If the ``links`` field is not NULL, the driver fills the ``links`` array
  49 with information about the entity's outbound links. The array must have
  50 enough room to store all the entity's outbound links. The number of
  51 outbound links can be retrieved with the
  52 :ref:`MEDIA_IOC_ENUM_ENTITIES <media-ioc-enum-entities>` ioctl.
  53
  54 Only forward links that originate at one of the entity's source pads are
  55 returned during the enumeration process.
  56
  57
  58 .. _media-links-enum:
  59
  60 .. flat-table:: struct media_links_enum
  61     :header-rows:  0
  62     :stub-columns: 0
  63     :widths:       1 1 2
  64
  65
  66     -  .. row 1
  67
  68        -  __u32
  69
  70        -  ``entity``
  71
  72        -  Entity id, set by the application.
  73
  74     -  .. row 2
  75
  76        -  struct :ref:`media_pad_desc <media-pad-desc>`
  77
  78        -  \*\ ``pads``
  79
  80        -  Pointer to a pads array allocated by the application. Ignored if
  81           NULL.
  82
  83     -  .. row 3
  84
  85        -  struct :ref:`media_link_desc <media-link-desc>`
  86
  87        -  \*\ ``links``
  88
  89        -  Pointer to a links array allocated by the application. Ignored if
  90           NULL.
  91
  92
  93
  94 .. _media-pad-desc:
  95
  96 .. flat-table:: struct media_pad_desc
  97     :header-rows:  0
  98     :stub-columns: 0
  99     :widths:       1 1 2
 100
 101
 102     -  .. row 1
 103
 104        -  __u32
 105
 106        -  ``entity``
 107
 108        -  ID of the entity this pad belongs to.
 109
 110     -  .. row 2
 111
 112        -  __u16
 113
 114        -  ``index``
 115
 116        -  0-based pad index.
 117
 118     -  .. row 3
 119
 120        -  __u32
 121
 122        -  ``flags``
 123
 124        -  Pad flags, see :ref:`media-pad-flag` for more details.
 125
 126
 127
 128 .. _media-link-desc:
 129
 130 .. flat-table:: struct media_link_desc
 131     :header-rows:  0
 132     :stub-columns: 0
 133     :widths:       1 1 2
 134
 135
 136     -  .. row 1
 137
 138        -  struct :ref:`media_pad_desc <media-pad-desc>`
 139
 140        -  ``source``
 141
 142        -  Pad at the origin of this link.
 143
 144     -  .. row 2
 145
 146        -  struct :ref:`media_pad_desc <media-pad-desc>`
 147
 148        -  ``sink``
 149
 150        -  Pad at the target of this link.
 151
 152     -  .. row 3
 153
 154        -  __u32
 155
 156        -  ``flags``
 157
 158        -  Link flags, see :ref:`media-link-flag` for more details.
 159
 160
 161
 162 Return Value
 163 ============
 164
 165 On success 0 is returned, on error -1 and the ``errno`` variable is set
 166 appropriately. The generic error codes are described at the
 167 :ref:`Generic Error Codes <gen-errors>` chapter.
 168
 169 EINVAL
 170     The struct :ref:`media_links_enum <media-links-enum>` ``id``
 171     references a non-existing entity.