man: document calendar timers

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

diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index bf22ca9bd0fdfe584b3f768f88476002bf3c0637..35644d38a666c68dd1b7c0d37aeabbca1a624e33 100644 (file)
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -75,10 +75,10 @@
                 inspired by Microsoft Windows
                 <filename>.ini</filename> files.</para>
 
                 inspired by Microsoft Windows
                 <filename>.ini</filename> files.</para>
 

-                <para>This man pages lists the common configuration
+                <para>This man page lists the common configuration

                 options of all the unit types. These options need to
                 options of all the unit types. These options need to

-                be configured in the [Unit] resp. [Install]
-                section of the unit files.</para>
+                be configured in the [Unit] or [Install]
+                sections of the unit files.</para>

 
                 <para>In addition to the generic [Unit] and [Install]
                 sections described here, each unit should have a
 
                 <para>In addition to the generic [Unit] and [Install]
                 sections described here, each unit should have a


@@ -111,7 +111,7 @@
                 the values are added up. Example: "50" refers to 50
                 seconds; "2min 200ms" refers to 2 minutes plus 200
                 milliseconds, i.e. 120200ms. The following time units
                 the values are added up. Example: "50" refers to 50
                 seconds; "2min 200ms" refers to 2 minutes plus 200
                 milliseconds, i.e. 120200ms. The following time units

-                are understood: s, min, h, d, w, ms, us.</para>
+                are understood: s, min, h, d, w, ms, us. For details see <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>

 
                 <para>Empty lines and lines starting with # or ; are
                 ignored. This may be used for commenting. Lines ending
 
                 <para>Empty lines and lines starting with # or ; are
                 ignored. This may be used for commenting. Lines ending


@@ -273,6 +273,21 @@
                         <entry>User shell</entry>
                         <entry>This is the shell of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
                       </row>
                         <entry>User shell</entry>
                         <entry>This is the shell of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
                       </row>

+                      <row>
+                        <entry><literal>%m</literal></entry>
+                        <entry>Machine ID</entry>
+                        <entry>The machine ID of the running system, formatted as string. See <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.</entry>
+                      </row>
+                      <row>
+                        <entry><literal>%b</literal></entry>
+                        <entry>Boot ID</entry>
+                        <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry>
+                      </row>
+                      <row>
+                        <entry><literal>%H</literal></entry>
+                        <entry>Host name</entry>
+                        <entry>The host name of the running system.</entry>
+                      </row>

                     </tbody>
                   </tgroup>
                 </table>
                     </tbody>
                   </tgroup>
                 </table>


@@ -323,7 +338,15 @@
                                 <literal>man:</literal>. For more
                                 information about the syntax of these
                                 URIs see
                                 <literal>man:</literal>. For more
                                 information about the syntax of these
                                 URIs see

-                                <citerefentry><refentrytitle>uri</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para></listitem>
+                                <citerefentry><refentrytitle>uri</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
+                                URIs should be listed in order of
+                                relevance, starting with the most
+                                relevant. It is a good idea to first
+                                reference documentation that explains
+                                what the unit's purpose is, followed
+                                by how it is configured, followed by
+                                any other related
+                                documentation.</para></listitem>

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


@@ -403,7 +426,7 @@
 
                                 <listitem><para>Similar to
                                 <varname>Requires=</varname>
 
                                 <listitem><para>Similar to
                                 <varname>Requires=</varname>

-                                resp. <varname>RequiresOverridable=</varname>. However,
+                                and <varname>RequiresOverridable=</varname>, respectively. However,

                                 if a unit listed here is not started
                                 already it will not be started and the
                                 transaction fails
                                 if a unit listed here is not started
                                 already it will not be started and the
                                 transaction fails


@@ -440,7 +463,7 @@
                                 <listitem><para>Configures requirement
                                 dependencies, very similar in style to
                                 <varname>Requires=</varname>, however
                                 <listitem><para>Configures requirement
                                 dependencies, very similar in style to
                                 <varname>Requires=</varname>, however

-                                in addition to this behaviour it also
+                                in addition to this behavior it also

                                 declares that this unit is stopped
                                 when any of the units listed suddenly
                                 disappears. Units can suddenly,
                                 declares that this unit is stopped
                                 when any of the units listed suddenly
                                 disappears. Units can suddenly,


@@ -551,7 +574,7 @@
                                 <varname>Before=</varname>. If two
                                 units have no ordering dependencies
                                 between them they are shut down
                                 <varname>Before=</varname>. If two
                                 units have no ordering dependencies
                                 between them they are shut down

-                                resp. started up simultaneously, and
+                                or started up simultaneously, and

                                 no ordering takes
                                 place. </para></listitem>
                         </varlistentry>
                                 no ordering takes
                                 place. </para></listitem>
                         </varlistentry>


@@ -657,13 +680,13 @@
                                 <listitem><para>Takes a boolean
                                 argument. If <option>true</option>
                                 this unit can only be activated
                                 <listitem><para>Takes a boolean
                                 argument. If <option>true</option>
                                 this unit can only be activated

-                                (resp. deactivated) indirectly. In
+                                or deactivated indirectly. In

                                 this case explicit start-up
                                 this case explicit start-up

-                                (resp. termination) requested by the
+                                or termination requested by the

                                 user is denied, however if it is
                                 user is denied, however if it is

-                                started (resp. stopped) as a
+                                started or stopped as a

                                 dependency of another unit, start-up
                                 dependency of another unit, start-up

-                                (resp. termination) will succeed. This
+                                or termination will succeed. This

                                 is mostly a safety feature to ensure
                                 that the user does not accidentally
                                 activate units that are not intended
                                 is mostly a safety feature to ensure
                                 that the user does not accidentally
                                 activate units that are not intended


@@ -755,6 +778,7 @@
                                 <term><varname>ConditionPathIsMountPoint=</varname></term>
                                 <term><varname>ConditionPathIsReadWrite=</varname></term>
                                 <term><varname>ConditionDirectoryNotEmpty=</varname></term>
                                 <term><varname>ConditionPathIsMountPoint=</varname></term>
                                 <term><varname>ConditionPathIsReadWrite=</varname></term>
                                 <term><varname>ConditionDirectoryNotEmpty=</varname></term>

+                                <term><varname>ConditionFileNotEmpty=</varname></term>

                                 <term><varname>ConditionFileIsExecutable=</varname></term>
                                 <term><varname>ConditionKernelCommandLine=</varname></term>
                                 <term><varname>ConditionVirtualization=</varname></term>
                                 <term><varname>ConditionFileIsExecutable=</varname></term>
                                 <term><varname>ConditionKernelCommandLine=</varname></term>
                                 <term><varname>ConditionVirtualization=</varname></term>


@@ -825,21 +849,28 @@
                                 (i.e. not mounted
                                 read-only).</para>
 
                                 (i.e. not mounted
                                 read-only).</para>
 

-                                <para><varname>ConditionFileIsExecutable=</varname>
+                                <para><varname>ConditionDirectoryNotEmpty=</varname>

                                 is similar to
                                 <varname>ConditionPathExists=</varname>
                                 but verifies whether a certain path
                                 is similar to
                                 <varname>ConditionPathExists=</varname>
                                 but verifies whether a certain path

-                                exists, is a regular file and marked
-                                executable.</para>
+                                exists and is a non-empty
+                                directory.</para>

 
 

-                                <para><varname>ConditionDirectoryNotEmpty=</varname>
+                                <para><varname>ConditionFileNotEmpty=</varname>

                                 is similar to
                                 <varname>ConditionPathExists=</varname>
                                 but verifies whether a certain path
                                 is similar to
                                 <varname>ConditionPathExists=</varname>
                                 but verifies whether a certain path

-                                exists and is a non-empty
-                                directory.</para>
+                                exists and refers to a regular file
+                                with a non-zero size.</para>
+
+                                <para><varname>ConditionFileIsExecutable=</varname>
+                                is similar to
+                                <varname>ConditionPathExists=</varname>
+                                but verifies whether a certain path
+                                exists, is a regular file and marked
+                                executable.</para>

 
 

-                                <para>Similarly,
+                                <para>Similar,

                                 <varname>ConditionKernelCommandLine=</varname>
                                 may be used to check whether a
                                 specific kernel command line option is
                                 <varname>ConditionKernelCommandLine=</varname>
                                 may be used to check whether a
                                 specific kernel command line option is


@@ -1000,8 +1031,8 @@
 
                                 <listitem><para>Installs a symlink in
                                 the <filename>.wants/</filename>
 
                                 <listitem><para>Installs a symlink in
                                 the <filename>.wants/</filename>

-                                resp. <filename>.requires/</filename>
-                                subdirectory for a unit. This has the
+                                or <filename>.requires/</filename>
+                                subdirectory for a unit, respectively. This has the

                                 effect that when the listed unit name
                                 is activated the unit listing it is
                                 activated
                                 effect that when the listed unit name
                                 is activated the unit listing it is
                                 activated


@@ -1046,6 +1077,7 @@
                         <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

+                        <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,

                         <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                 </para>
         </refsect1>
                         <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                 </para>
         </refsect1>