man: explain in more detail how SYSTEMD_READY= influences SYSTEMD_WANTS= in udev...

[elogind.git] / man / systemd.device.xml

diff --git a/man/systemd.device.xml b/man/systemd.device.xml
index 1c29aa4e79fa0c0374233f635fa11e7cb51d5027..002b647ff9d3d62235c51a346f3238b743c680e0 100644 (file)
--- a/man/systemd.device.xml
+++ b/man/systemd.device.xml
@@ -55,7 +55,7 @@
                 <title>Description</title>
 
                 <para>A unit configuration file whose name ends in
                 <title>Description</title>
 
                 <para>A unit configuration file whose name ends in

-                <filename>.device</filename> encodes information about
+                <literal>.device</literal> encodes information about

                 a device unit as exposed in the
                 sysfs/<citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                 device tree.</para>
                 a device unit as exposed in the
                 sysfs/<citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                 device tree.</para>


@@ -70,12 +70,15 @@
                 since no device-specific options may be
                 configured.</para>
 
                 since no device-specific options may be
                 configured.</para>
 

-                <para>systemd will automatically create dynamic device
-                units for all kernel devices that are marked with the
-                "systemd" udev tag (by default all block and network
-                devices, and a few others). This may be used to define
-                dependencies between devices and other
-                units.</para>
+                <para>systemd will dynamically create device units for
+                all kernel devices that are marked with the "systemd"
+                udev tag (by default all block and network devices,
+                and a few others). This may be used to define
+                dependencies between devices and other units. To tag a
+                udev device use <literal>TAG+="systemd"</literal> in
+                the udev rules file, see
+                <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+                for details.</para>

 
                 <para>Device units are named after the
                 <filename>/sys</filename> and
 
                 <para>Device units are named after the
                 <filename>/sys</filename> and


@@ -93,7 +96,7 @@
 
                 <para>The settings of device units may either be
                 configured via unit files, or directly from the udev
 
                 <para>The settings of device units may either be
                 configured via unit files, or directly from the udev

-                database (which is recommended). The following udev
+                database (which is recommended). The following udev device

                 properties are understood by systemd:</para>
 
                 <variablelist class='udev-directives'>
                 properties are understood by systemd:</para>
 
                 <variablelist class='udev-directives'>


@@ -101,16 +104,26 @@
                                 <term><varname>SYSTEMD_WANTS=</varname></term>
                                 <listitem><para>Adds dependencies of
                                 type <varname>Wants</varname> from
                                 <term><varname>SYSTEMD_WANTS=</varname></term>
                                 <listitem><para>Adds dependencies of
                                 type <varname>Wants</varname> from

-                                this unit to all listed units. This
+                                the device unit to all listed units. This

                                 may be used to activate arbitrary
                                 may be used to activate arbitrary

-                                units, when a specific device becomes
+                                units when a specific device becomes

                                 available. Note that this and the
                                 other tags are not taken into account
                                 unless the device is tagged with the
                                 <literal>systemd</literal> string in
                                 the udev database, because otherwise
                                 the device is not exposed as systemd
                                 available. Note that this and the
                                 other tags are not taken into account
                                 unless the device is tagged with the
                                 <literal>systemd</literal> string in
                                 the udev database, because otherwise
                                 the device is not exposed as systemd

-                                unit.</para></listitem>
+                                unit (see above). Note that systemd
+                                will only act on
+                                <varname>Wants</varname> dependencies
+                                when a device first becomes active, it
+                                will not act on them if they are added
+                                to devices that are already
+                                active. Use
+                                <varname>SYSTEMD_READY=</varname> (see
+                                below) to influence on which udev
+                                event to trigger the device
+                                dependencies.</para></listitem>

                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>


@@ -124,21 +137,25 @@
 
                         <varlistentry>
                                 <term><varname>SYSTEMD_READY=</varname></term>
 
                         <varlistentry>
                                 <term><varname>SYSTEMD_READY=</varname></term>

-                                <listitem><para>If set to 0 systemd
+                                <listitem><para>If set to 0, systemd

                                 will consider this device unplugged
                                 even if it shows up in the udev
                                 tree. If this property is unset or set
                                 will consider this device unplugged
                                 even if it shows up in the udev
                                 tree. If this property is unset or set

-                                to 1 the device will be considered
+                                to 1, the device will be considered

                                 plugged the moment it shows up in the
                                 udev tree. This property has no
                                 influence on the behavior when a
                                 device disappears from the udev
                                 tree. This option is useful to support
                                 devices that initially show up in an
                                 plugged the moment it shows up in the
                                 udev tree. This property has no
                                 influence on the behavior when a
                                 device disappears from the udev
                                 tree. This option is useful to support
                                 devices that initially show up in an

-                                uninitialized state in the tree, and for
-                                which a changed event is generated the
-                                moment they are fully set
-                                up.</para></listitem>
+                                uninitialized state in the tree, and
+                                for which a <literal>changed</literal>
+                                event is generated the moment they are
+                                fully set up. Note that
+                                <varname>SYSTEMD_WANTS=</varname> (see
+                                above) is not acted on as long as
+                                <varname>SYSTEMD_READY=0</varname> is
+                                set for a device.</para></listitem>

                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>