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