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