GNU Linux-libre 4.14.262-gnu1
[releases.git] / 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
30
31 Description
32 ===========
33
34 To change link properties applications fill a struct
35 :c:type:`media_link_desc` with link identification
36 information (source and sink pad) and the new requested link flags. They
37 then call the MEDIA_IOC_SETUP_LINK ioctl with a pointer to that
38 structure.
39
40 The only configurable property is the ``ENABLED`` link flag to
41 enable/disable a link. Links marked with the ``IMMUTABLE`` link flag can
42 not be enabled or disabled.
43
44 Link configuration has no side effect on other links. If an enabled link
45 at the sink pad prevents the link from being enabled, the driver returns
46 with an ``EBUSY`` error code.
47
48 Only links marked with the ``DYNAMIC`` link flag can be enabled/disabled
49 while streaming media data. Attempting to enable or disable a streaming
50 non-dynamic link will return an ``EBUSY`` error code.
51
52 If the specified link can't be found the driver returns with an ``EINVAL``
53 error code.
54
55
56 Return Value
57 ============
58
59 On success 0 is returned, on error -1 and the ``errno`` variable is set
60 appropriately. The generic error codes are described at the
61 :ref:`Generic Error Codes <gen-errors>` chapter.
62
63 EINVAL
64     The struct :c:type:`media_link_desc` references a
65     non-existing link, or the link is immutable and an attempt to modify
66     its configuration was made.