1<refentry id="media-ioc-setup-link">
2  <refmeta>
3    <refentrytitle>ioctl MEDIA_IOC_SETUP_LINK</refentrytitle>
4    &manvol;
5  </refmeta>
6
7  <refnamediv>
8    <refname>MEDIA_IOC_SETUP_LINK</refname>
9    <refpurpose>Modify the properties of a link</refpurpose>
10  </refnamediv>
11
12  <refsynopsisdiv>
13    <funcsynopsis>
14      <funcprototype>
15	<funcdef>int <function>ioctl</function></funcdef>
16	<paramdef>int <parameter>fd</parameter></paramdef>
17	<paramdef>int <parameter>request</parameter></paramdef>
18	<paramdef>struct media_link_desc *<parameter>argp</parameter></paramdef>
19      </funcprototype>
20    </funcsynopsis>
21  </refsynopsisdiv>
22
23  <refsect1>
24    <title>Arguments</title>
25
26    <variablelist>
27      <varlistentry>
28	<term><parameter>fd</parameter></term>
29	<listitem>
30	  <para>File descriptor returned by
31	  <link linkend='media-func-open'><function>open()</function></link>.</para>
32	</listitem>
33      </varlistentry>
34      <varlistentry>
35	<term><parameter>request</parameter></term>
36	<listitem>
37	  <para>MEDIA_IOC_SETUP_LINK</para>
38	</listitem>
39      </varlistentry>
40      <varlistentry>
41	<term><parameter>argp</parameter></term>
42	<listitem>
43	  <para></para>
44	</listitem>
45      </varlistentry>
46    </variablelist>
47  </refsect1>
48
49  <refsect1>
50    <title>Description</title>
51
52    <para>To change link properties applications fill a &media-link-desc; with
53    link identification information (source and sink pad) and the new requested
54    link flags. They then call the MEDIA_IOC_SETUP_LINK ioctl with a pointer to
55    that structure.</para>
56    <para>The only configurable property is the <constant>ENABLED</constant>
57    link flag to enable/disable a link. Links marked with the
58    <constant>IMMUTABLE</constant> link flag can not be enabled or disabled.
59    </para>
60    <para>Link configuration has no side effect on other links. If an enabled
61    link at the sink pad prevents the link from being enabled, the driver
62    returns with an &EBUSY;.</para>
63    <para>Only links marked with the <constant>DYNAMIC</constant> link flag can
64    be enabled/disabled while streaming media data. Attempting to enable or
65    disable a streaming non-dynamic link will return an &EBUSY;.</para>
66    <para>If the specified link can't be found the driver returns with an
67    &EINVAL;.</para>
68  </refsect1>
69
70  <refsect1>
71    &return-value;
72
73    <variablelist>
74      <varlistentry>
75	<term><errorcode>EINVAL</errorcode></term>
76	<listitem>
77	  <para>The &media-link-desc; references a non-existing link, or the
78	  link is immutable and an attempt to modify its configuration was made.
79	  </para>
80	</listitem>
81      </varlistentry>
82    </variablelist>
83  </refsect1>
84</refentry>
85