chiark / gitweb /
Add man page and references to it.
authorDidier Roche <didrocks@ubuntu.com>
Mon, 26 Jan 2015 16:34:59 +0000 (17:34 +0100)
committerMartin Pitt <martin.pitt@ubuntu.com>
Wed, 18 Feb 2015 15:33:46 +0000 (16:33 +0100)
Add man page explaining the plymouth theme protocol, usage of the daemon
as well as the socket activation part.
Adapt existing fsck man page.

Makefile-man.am
man/systemd-fsck@.service.xml
man/systemd-fsckd.service.xml [new file with mode: 0644]
units/systemd-fsckd.service.in
units/systemd-fsckd.socket

index d0fb9aa..7a9612e 100644 (file)
@@ -66,6 +66,7 @@ MANPAGES += \
        man/systemd-efi-boot-generator.8 \
        man/systemd-escape.1 \
        man/systemd-fsck@.service.8 \
+       man/systemd-fsckd.service.8 \
        man/systemd-fstab-generator.8 \
        man/systemd-getty-generator.8 \
        man/systemd-gpt-auto-generator.8 \
@@ -209,6 +210,8 @@ MANPAGES_ALIAS += \
        man/systemd-ask-password-wall.service.8 \
        man/systemd-fsck-root.service.8 \
        man/systemd-fsck.8 \
+       man/systemd-fsckd.8 \
+       man/systemd-fsckd.socket.8 \
        man/systemd-hibernate-resume.8 \
        man/systemd-hibernate.service.8 \
        man/systemd-hybrid-sleep.service.8 \
@@ -321,6 +324,8 @@ man/systemd-ask-password-wall.path.8: man/systemd-ask-password-console.service.8
 man/systemd-ask-password-wall.service.8: man/systemd-ask-password-console.service.8
 man/systemd-fsck-root.service.8: man/systemd-fsck@.service.8
 man/systemd-fsck.8: man/systemd-fsck@.service.8
+man/systemd-fsckd.8: man/systemd-fsckd.service.8
+man/systemd-fsckd.socket.8: man/systemd-fsckd.service.8
 man/systemd-hibernate-resume.8: man/systemd-hibernate-resume@.service.8
 man/systemd-hibernate.service.8: man/systemd-suspend.service.8
 man/systemd-hybrid-sleep.service.8: man/systemd-suspend.service.8
@@ -601,6 +606,12 @@ man/systemd-fsck-root.service.html: man/systemd-fsck@.service.html
 man/systemd-fsck.html: man/systemd-fsck@.service.html
        $(html-alias)
 
+man/systemd-fsckd.html: man/systemd-fsckd.service.html
+       $(html-alias)
+
+man/systemd-fsckd.socket.html: man/systemd-fsckd.service.html
+       $(html-alias)
+
 man/systemd-hibernate-resume.html: man/systemd-hibernate-resume@.service.html
        $(html-alias)
 
@@ -1738,6 +1749,7 @@ EXTRA_DIST += \
        man/systemd-escape.xml \
        man/systemd-firstboot.xml \
        man/systemd-fsck@.service.xml \
+       man/systemd-fsckd.service.xml \
        man/systemd-fstab-generator.xml \
        man/systemd-getty-generator.xml \
        man/systemd-gpt-auto-generator.xml \
index 88e11e8..69b8fdd 100644 (file)
     last check, number of mounts, unclean unmount, etc.</para>
 
     <para><filename>systemd-fsck</filename> will forward file system
-    checking progress to the console. If a file system check fails for
-    a service without <option>nofail</option>, emergency mode is
-    activated, by isolating to
-    <filename>emergency.target</filename>.</para>
+    checking progress to <filename>systemd-fsckd.service</filename>
+    socket. If a file system check fails for a service without
+    <option>nofail</option>, emergency mode is activated, by isolating
+    to <filename>emergency.target</filename>.</para>
   </refsect1>
 
   <refsect1>
     <title>See Also</title>
     <para>
       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>fsck</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>fsck</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd-quotacheck.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>fsck.btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>fsck.cramfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>fsck.ext4</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>fsck.fat</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>fsck.hfsplus</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>fsck.minix</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>fsck.ntfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>fsck.xfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+      <citerefentry project='man-pages'><refentrytitle>fsck.btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>fsck.cramfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>fsck.ext4</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>fsck.fat</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>fsck.hfsplus</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>fsck.minix</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>fsck.ntfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>fsck.xfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
     </para>
   </refsect1>
 
diff --git a/man/systemd-fsckd.service.xml b/man/systemd-fsckd.service.xml
new file mode 100644 (file)
index 0000000..2ad7844
--- /dev/null
@@ -0,0 +1,162 @@
+<?xml version="1.0"?>
+<!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!--
+  This file is part of systemd.
+
+  Copyright 2015 Canonical
+
+  systemd is free software; you can redistribute it and/or modify it
+  under the terms of the GNU Lesser General Public License as published by
+  the Free Software Foundation; either version 2.1 of the License, or
+  (at your option) any later version.
+
+  systemd is distributed in the hope that it will be useful, but
+  WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+  Lesser General Public License for more details.
+
+  You should have received a copy of the GNU Lesser General Public License
+  along with systemd; If not, see <http://www.gnu.org/licenses/>.
+-->
+<refentry id="systemd-fsckd.service" xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>systemd-fsckd.service</title>
+    <productname>systemd</productname>
+
+    <authorgroup>
+      <author>
+        <contrib>Developer</contrib>
+        <firstname>Didier</firstname>
+        <surname>Roche</surname>
+        <email>didrocks@ubuntu.com</email>
+      </author>
+    </authorgroup>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>systemd-fsckd.service</refentrytitle>
+    <manvolnum>8</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>systemd-fsckd.service</refname>
+    <refname>systemd-fsckd.socket</refname>
+    <refname>systemd-fsckd</refname>
+    <refpurpose>File system check progress reporting</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <para><filename>systemd-fsckd.service</filename></para>
+    <para><filename>systemd-fsckd.socket</filename></para>
+    <para><filename>/usr/lib/systemd/systemd-fsckd</filename></para>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><filename>systemd-fsckd.service</filename> is a service responsible
+    for receiving file system check progress, and communicating some
+    consolidated data to console and plymouth (if running). It also handles
+    possible check cancellations.</para>
+
+    <para><command>systemd-fsckd</command> receives messages about file
+    system check progress from <command>systemd-fsck</command> through a
+    UNIX domain socket. It can display the progress of the least advanced
+    fsck as well as the total number of devices being checked in parallel
+    to the console. It will also send progress messages to plymouth.
+    Both the raw data and translated messages are sent, so compiled
+    plymouth themes can use the raw data to display custom messages, and
+    scripted themes, not supporting i18n, can display the translated
+    versions.</para>
+
+    <para><command>systemd-fsckd</command> will instruct plymouth to grab
+    Control+C keypresses. When the key is pressed, running checks will be
+    terminated. It will also cancel any newly connected fsck instances for
+    the lifetime of <filename>systemd-fsckd</filename>.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Protocol for communication with plymouth</title>
+
+    <para><filename>systemd-fsckd</filename> passes the
+    following messages to the theme:</para>
+
+    <para>Progress update, sent as a plymouth update message:
+      <literal>fsckd:&lt;num_devices&gt;:&lt;progress&gt;:&lt;string&gt;</literal>
+      <variablelist>
+        <varlistentry>
+          <term><literal>&lt;num_devices&gt;</literal></term>
+          <listitem><para>the current number of devices
+          being checked (int)</para></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><literal>&lt;progress&gt;</literal></term>
+          <listitem><para>the current minimum percentage of
+          all devices being checking (float, from 0 to 100)</para></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><literal>&lt;string&gt;</literal></term>
+          <listitem><para>a translated message ready to be displayed
+          by the plymouth theme displaying the data above. It can be overriden
+          by themes supporting i18n.</para></listitem>
+        </varlistentry>
+      </variablelist>
+    </para>
+
+    <para>Cancel message, sent as a traditional plymouth message:
+      <literal>fsckd-cancel-msg:&lt;string&gt;</literal>
+      <variablelist>
+        <varlistentry>
+          <term><literal>&lt;strings&gt;</literal></term>
+          <listitem><para>a translated string ready to be displayed
+          by the plymouth theme indicating that Control+C can be used to cancel
+          current checks. It can be overriden (matching only
+          <literal>fsckd-cancel-msg</literal> prefix)
+          by themes supporting i18n.</para></listitem>
+        </varlistentry>
+      </variablelist>
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Options</title>
+
+    <para>The following options are understood:</para>
+
+    <variablelist>
+      <xi:include href="standard-options.xml" xpointer="help" />
+      <xi:include href="standard-options.xml" xpointer="version" />
+    </variablelist>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Exit status</title>
+
+    <para>On success, 0 is returned, a non-zero failure
+    code otherwise. Note that the daemon stays idle for
+    a while to accept new <filename>systemd-fsck</filename>
+    connections before exiting.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+    <para>
+      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-fsck</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>fsck</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-quotacheck.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>fsck.btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>fsck.cramfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>fsck.ext4</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>fsck.fat</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>fsck.hfsplus</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>fsck.minix</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>fsck.ntfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>fsck.xfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>
index 27c325f..9c7ed51 100644 (file)
@@ -7,6 +7,7 @@
 
 [Unit]
 Description=File System Check Daemon to report status
+Documentation=man:systemd-fsckd.service(8)
 DefaultDependencies=no
 Requires=systemd-fsckd.socket
 Before=shutdown.target
index a8994a1..93c4ea9 100644 (file)
@@ -7,7 +7,7 @@
 
 [Unit]
 Description=fsck to fsckd communication Socket
-Documentation=man:systemd-fsck@.service(8) man:systemd-fsck-root.service(8)
+Documentation=man:systemd-fsckd.service(8) man:systemd-fsck@.service(8) man:systemd-fsck-root.service(8)
 DefaultDependencies=no
 
 [Socket]