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