Documentation/media/uapi/mediactl/media-ioc-setup-link.rst

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