Documentation/userspace-api/media/mediactl/media-ioc-setup-link.rst

   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_setup_link:
  11
  12 **************************
  13 ioctl MEDIA_IOC_SETUP_LINK
  14 **************************
  15
  16 Name
  17 ====
  18
  19 MEDIA_IOC_SETUP_LINK - Modify the properties of a link
  20
  21
  22 Synopsis
  23 ========
  24
  25 .. c:function:: int ioctl( int fd, MEDIA_IOC_SETUP_LINK, struct media_link_desc *argp )
  26     :name: MEDIA_IOC_SETUP_LINK
  27
  28
  29 Arguments
  30 =========
  31
  32 ``fd``
  33     File descriptor returned by :ref:`open() <media-func-open>`.
  34
  35 ``argp``
  36     Pointer to struct :c:type:`media_link_desc`.
  37
  38
  39 Description
  40 ===========
  41
  42 To change link properties applications fill a struct
  43 :c:type:`media_link_desc` with link identification
  44 information (source and sink pad) and the new requested link flags. They
  45 then call the MEDIA_IOC_SETUP_LINK ioctl with a pointer to that
  46 structure.
  47
  48 The only configurable property is the ``ENABLED`` link flag to
  49 enable/disable a link. Links marked with the ``IMMUTABLE`` link flag can
  50 not be enabled or disabled.
  51
  52 Link configuration has no side effect on other links. If an enabled link
  53 at the sink pad prevents the link from being enabled, the driver returns
  54 with an ``EBUSY`` error code.
  55
  56 Only links marked with the ``DYNAMIC`` link flag can be enabled/disabled
  57 while streaming media data. Attempting to enable or disable a streaming
  58 non-dynamic link will return an ``EBUSY`` error code.
  59
  60 If the specified link can't be found the driver returns with an ``EINVAL``
  61 error code.
  62
  63
  64 Return Value
  65 ============
  66
  67 On success 0 is returned, on error -1 and the ``errno`` variable is set
  68 appropriately. The generic error codes are described at the
  69 :ref:`Generic Error Codes <gen-errors>` chapter.
  70
  71 EINVAL
  72     The struct :c:type:`media_link_desc` references a
  73     non-existing link, or the link is immutable and an attempt to modify
  74     its configuration was made.