chiark / gitweb /
man: add systemd.generator(7)
[elogind.git] / man / systemd.path.xml
index ccf16df..71f74d9 100644 (file)
@@ -1,7 +1,7 @@
 <?xml version='1.0'?> <!--*-nxml-*-->
 <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?>
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 
 <!--
   This file is part of systemd.
 -->
 
 <refentry id="systemd.path">
-        <refentryinfo>
-                <title>systemd.path</title>
-                <productname>systemd</productname>
-
-                <authorgroup>
-                        <author>
-                                <contrib>Developer</contrib>
-                                <firstname>Lennart</firstname>
-                                <surname>Poettering</surname>
-                                <email>lennart@poettering.net</email>
-                        </author>
-                </authorgroup>
-        </refentryinfo>
-
-        <refmeta>
-                <refentrytitle>systemd.path</refentrytitle>
-                <manvolnum>5</manvolnum>
-        </refmeta>
-
-        <refnamediv>
-                <refname>systemd.path</refname>
-                <refpurpose>Path unit configuration</refpurpose>
-        </refnamediv>
-
-        <refsynopsisdiv>
-                <para><filename>systemd.path</filename></para>
-        </refsynopsisdiv>
-
-        <refsect1>
-                <title>Description</title>
-
-                <para>A unit configuration file whose name ends in
-                <filename>.path</filename> encodes information about
-                a path monitored by systemd, for
-                path-based activation.</para>
-
-                <para>This man page lists the configuration options
-                specific to this unit type. See
-                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
-                for the common options of all unit configuration
-                files. The common configuration items are configured
-                in the generic [Unit] and [Install] sections. The
-                path specific configuration options are configured in
-                the [Path] section.</para>
-
-                <para>For each path file, a matching unit file must
-                exist, describing the unit to activate when the path
-                changes. By default, a service by the same name as the
-                path (except for the suffix) is activated. Example: a
-                path file <filename>foo.path</filename> activates a
-                matching service <filename>foo.service</filename>. The
-                unit to activate may be controlled by
-                <varname>Unit=</varname> (see below).</para>
-
-                <para>Internally, path units use the
-                <citerefentry><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry>
-                API to monitor file systems. Due to that, it suffers by the
-                same limitations as inotify, and for example cannot be
-                used to monitor files or directories changed by other
-                machines on remote NFS file systems.</para>
-
-                <para>If a path unit is beneath another mount
-                point in the file system hierarchy, a dependency
-                between both units is created automatically.</para>
-
-                <para>Unless <varname>DefaultDependencies=</varname>
-                is set to <option>false</option>, path units will
-                implicitly have dependencies of type
-                <varname>Conflicts=</varname> and
-                <varname>Before=</varname> on
-                <filename>shutdown.target</filename>. These ensure
-                that path units are terminated cleanly prior to system
-                shutdown. Only path units involved with early boot or
-                late system shutdown should disable this
-                option.</para>
-        </refsect1>
-
-        <refsect1>
-                <title>Options</title>
-
-                <para>Path files must include a [Path] section,
-                which carries information about the path(s) it
-                monitors. The options specific to the [Path] section
-                of path units are the following:</para>
-
-                <variablelist class='unit-directives'>
-                        <varlistentry>
-                                <term><varname>PathExists=</varname></term>
-                                <term><varname>PathExistsGlob=</varname></term>
-                                <term><varname>PathChanged=</varname></term>
-                                <term><varname>PathModified=</varname></term>
-                                <term><varname>DirectoryNotEmpty=</varname></term>
-
-                                <listitem><para>Defines paths to
-                                monitor for certain changes:
-                                <varname>PathExists=</varname> may be
-                                used to watch the mere existence of a
-                                file or directory. If the file
-                                specified exists the configured unit
-                                is
-                                activated. <varname>PathExistsGlob=</varname>
-                                works similar, but checks for the
-                                existence of at least one file
-                                matching the globbing pattern
-                                specified. <varname>PathChanged=</varname>
-                                may be used to watch a file or
-                                directory and activate the configured
-                                unit whenever it changes. It is not
-                                activated on every write to the
-                                watched file but it is activated if
-                                the file which was open for writing
-                                gets
-                                closed. <varname>PathModified=</varname>
-                                is similar, but additionally it is
-                                activated also on simple writes to the
-                                watched file.
-                                <varname>DirectoryNotEmpty=</varname>
-                                may be used to watch a directory and
-                                activate the configured unit whenever
-                                it contains at least one file.</para>
-
-                                <para>The arguments of these
-                                directives must be absolute file
-                                system paths.</para>
-
-                                <para>Multiple directives may be
-                                combined, of the same and of different
-                                types, to watch multiple paths. If the
-                                empty string is assigned to any of
-                                these options the list of paths to
-                                watch is reset, and any prior
-                                assignments of these options will not
-                                have any effect.</para>
-
-                                <para>If a path is already existing
-                                (in case of
-                                <varname>PathExists=</varname> and
-                                <varname>PathExistsGlob=</varname>) or
-                                a directory already is not empty (in
-                                case of
-                                <varname>DirectoryNotEmpty=</varname>)
-                                at the time the path unit is
-                                activated, then the configured unit is
-                                immediately activated as
-                                well. Something similar does not apply
-                                to <varname>PathChanged=</varname>.
-                                </para></listitem>
-                        </varlistentry>
-                        <varlistentry>
-                                <term><varname>Unit=</varname></term>
-
-                                <listitem><para>The unit to activate
-                                when any of the configured paths
-                                changes. The argument is a unit name,
-                                whose suffix is not
-                                <filename>.path</filename>. If not
-                                specified, this value defaults to a
-                                service that has the same name as the
-                                path unit, except for the suffix. (See
-                                above.) It is recommended that the
-                                unit name that is activated and the
-                                unit name of the path unit are named
-                                identical, except for the
-                                suffix.</para></listitem>
-                        </varlistentry>
-                        <varlistentry>
-                                <term><varname>MakeDirectory=</varname></term>
-
-                                <listitem><para>Takes a boolean
-                                argument. If true the directories to
-                                watch are created before
-                                watching. This option is ignored for
-                                <varname>PathExists=</varname>
-                                settings. Defaults to
-                                <option>false</option>.</para></listitem>
-                        </varlistentry>
-                        <varlistentry>
-                                <term><varname>DirectoryMode=</varname></term>
-
-                                <listitem><para>If
-                                <varname>MakeDirectory=</varname> is
-                                enabled use the mode specified here to
-                                create the directories in
-                                question. Takes an access mode in
-                                octal notation. Defaults to
-                                <option>0755</option>.</para></listitem>
-                        </varlistentry>
-                </variablelist>
-        </refsect1>
-
-        <refsect1>
-                  <title>See Also</title>
-                  <para>
-                          <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-                          <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
-                          <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-                          <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-                          <citerefentry><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
-                          <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
-                  </para>
-        </refsect1>
+  <refentryinfo>
+    <title>systemd.path</title>
+    <productname>systemd</productname>
+
+    <authorgroup>
+      <author>
+        <contrib>Developer</contrib>
+        <firstname>Lennart</firstname>
+        <surname>Poettering</surname>
+        <email>lennart@poettering.net</email>
+      </author>
+    </authorgroup>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>systemd.path</refentrytitle>
+    <manvolnum>5</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>systemd.path</refname>
+    <refpurpose>Path unit configuration</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <para><filename><replaceable>path</replaceable>.path</filename></para>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para>A unit configuration file whose name ends in
+    <literal>.path</literal> encodes information about a path
+    monitored by systemd, for path-based activation.</para>
+
+    <para>This man page lists the configuration options specific to
+    this unit type. See
+    <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+    for the common options of all unit configuration files. The common
+    configuration items are configured in the generic [Unit] and
+    [Install] sections. The path specific configuration options are
+    configured in the [Path] section.</para>
+
+    <para>For each path file, a matching unit file must exist,
+    describing the unit to activate when the path changes. By default,
+    a service by the same name as the path (except for the suffix) is
+    activated. Example: a path file <filename>foo.path</filename>
+    activates a matching service <filename>foo.service</filename>. The
+    unit to activate may be controlled by <varname>Unit=</varname>
+    (see below).</para>
+
+    <para>Internally, path units use the
+    <citerefentry><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+    API to monitor file systems. Due to that, it suffers by the same
+    limitations as inotify, and for example cannot be used to monitor
+    files or directories changed by other machines on remote NFS file
+    systems.</para>
+
+    <para>If a path unit is beneath another mount point in the file
+    system hierarchy, a dependency between both units is created
+    automatically.</para>
+
+    <para>Unless <varname>DefaultDependencies=false</varname> is used,
+    path units will implicitly have dependencies of type
+    <varname>Conflicts=</varname> and <varname>Before=</varname> on
+    <filename>shutdown.target</filename>. These ensure that path units
+    are terminated cleanly prior to system shutdown. Only path units
+    involved with early boot or late system shutdown should disable
+    this option.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Options</title>
+
+    <para>Path files must include a [Path] section, which carries
+    information about the path(s) it monitors. The options specific to
+    the [Path] section of path units are the following:</para>
+
+    <variablelist class='unit-directives'>
+      <varlistentry>
+        <term><varname>PathExists=</varname></term>
+        <term><varname>PathExistsGlob=</varname></term>
+        <term><varname>PathChanged=</varname></term>
+        <term><varname>PathModified=</varname></term>
+        <term><varname>DirectoryNotEmpty=</varname></term>
+
+        <listitem><para>Defines paths to monitor for certain changes:
+        <varname>PathExists=</varname> may be used to watch the mere
+        existence of a file or directory. If the file specified
+        exists, the configured unit is activated.
+        <varname>PathExistsGlob=</varname> works similar, but checks
+        for the existence of at least one file matching the globbing
+        pattern specified. <varname>PathChanged=</varname> may be used
+        to watch a file or directory and activate the configured unit
+        whenever it changes. It is not activated on every write to the
+        watched file but it is activated if the file which was open
+        for writing gets closed. <varname>PathModified=</varname> is
+        similar, but additionally it is activated also on simple
+        writes to the watched file.
+        <varname>DirectoryNotEmpty=</varname> may be used to watch a
+        directory and activate the configured unit whenever it
+        contains at least one file.</para>
+
+        <para>The arguments of these directives must be absolute file
+        system paths.</para>
+
+        <para>Multiple directives may be combined, of the same and of
+        different types, to watch multiple paths. If the empty string
+        is assigned to any of these options, the list of paths to
+        watch is reset, and any prior assignments of these options
+        will not have any effect.</para>
+
+        <para>If a path already exists (in case of
+        <varname>PathExists=</varname> and
+        <varname>PathExistsGlob=</varname>) or a directory already is
+        not empty (in case of <varname>DirectoryNotEmpty=</varname>)
+        at the time the path unit is activated, then the configured
+        unit is immediately activated as well. Something similar does
+        not apply to <varname>PathChanged=</varname> and
+        <varname>PathModified=</varname>.</para>
+
+        <para>If the path itself or any of the containing directories
+        are not accessible, <command>systemd</command> will watch for
+        permission changes and notice that conditions are satisfied
+        when permissions allow that. </para></listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><varname>Unit=</varname></term>
+
+        <listitem><para>The unit to activate when any of the
+        configured paths changes. The argument is a unit name, whose
+        suffix is not <literal>.path</literal>. If not specified, this
+        value defaults to a service that has the same name as the path
+        unit, except for the suffix. (See above.) It is recommended
+        that the unit name that is activated and the unit name of the
+        path unit are named identical, except for the
+        suffix.</para></listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><varname>MakeDirectory=</varname></term>
+
+        <listitem><para>Takes a boolean argument. If true, the
+        directories to watch are created before watching. This option
+        is ignored for <varname>PathExists=</varname> settings.
+        Defaults to <option>false</option>.</para></listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><varname>DirectoryMode=</varname></term>
+
+        <listitem><para>If <varname>MakeDirectory=</varname> is
+        enabled, use the mode specified here to create the directories
+        in question. Takes an access mode in octal notation. Defaults
+        to <option>0755</option>.</para></listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+      <title>See Also</title>
+      <para>
+        <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+        <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+        <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+        <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+        <citerefentry><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+        <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+      </para>
+  </refsect1>
 
 </refentry>