1 .. -*- coding: utf-8; mode: rst -*-
3 .. _media_ioc_setup_link:
5 **************************
6 ioctl MEDIA_IOC_SETUP_LINK
7 **************************
12 MEDIA_IOC_SETUP_LINK - Modify the properties of a link
18 .. c:function:: int ioctl( int fd, MEDIA_IOC_SETUP_LINK, struct media_link_desc *argp )
19 :name: MEDIA_IOC_SETUP_LINK
26 File descriptor returned by :ref:`open() <media-func-open>`.
29 Pointer to struct :c:type:`media_link_desc`.
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
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.
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.
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.
53 If the specified link can't be found the driver returns with an ``EINVAL``
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.
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.