>From 6b13d8fb248bf4176f1ad7e1d4736683462bf196 Mon Sep 17 00:00:00 2001
From: Didier Roche <didro...@ubuntu.com>
Date: Mon, 26 Jan 2015 17:34:59 +0100
Subject: [PATCH 11/12] Add man page and references to it.
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 | 12 +++
man/systemd-f...@.service.xml | 6 +-
man/systemd-fsckd.service.xml | 170 +++++++++++++++++++++++++++++++++++++++++
units/systemd-fsckd.service.in | 1 +
units/systemd-fsckd.socket | 2 +-
5 files changed, 188 insertions(+), 3 deletions(-)
create mode 100644 man/systemd-fsckd.service.xml
diff --git a/Makefile-man.am b/Makefile-man.am
index 105853e..f2e13e8 100644
--- a/Makefile-man.am
+++ b/Makefile-man.am
@@ -67,6 +67,7 @@ MANPAGES += \
man/systemd-escape.1 \
man/systemd-firstboot.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 \
@@ -210,6 +211,8 @@ MANPAGES_ALIAS += \
man/systemd-firstboot.service.1 \
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 \
@@ -323,6 +326,8 @@ man/systemd-ask-password-wall.service.8: man/systemd-ask-password-console.servic
man/systemd-firstboot.service.1: man/systemd-firstboot.1
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
@@ -606,6 +611,12 @@ man/systemd-fsck-root.service.html: man/systemd-f...@.service.html
man/systemd-fsck.html: man/systemd-f...@.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-res...@.service.html
$(html-alias)
@@ -1732,6 +1743,7 @@ EXTRA_DIST += \
man/systemd-escape.xml \
man/systemd-firstboot.xml \
man/systemd-f...@.service.xml \
+ man/systemd-fsckd.service.xml \
man/systemd-fstab-generator.xml \
man/systemd-getty-generator.xml \
man/systemd-gpt-auto-generator.xml \
diff --git a/man/systemd-f...@.service.xml b/man/systemd-f...@.service.xml
index ee66f37..d366712 100644
--- a/man/systemd-f...@.service.xml
+++ b/man/systemd-f...@.service.xml
@@ -87,8 +87,9 @@
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
+ file system 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>
@@ -142,6 +143,7 @@
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>fsck</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd-fsckd.service</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>,
diff --git a/man/systemd-fsckd.service.xml b/man/systemd-fsckd.service.xml
new file mode 100644
index 0000000..befcc45
--- /dev/null
+++ b/man/systemd-fsckd.service.xml
@@ -0,0 +1,170 @@
+<?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>didro...@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 fetching file system check
+ progress, and communicating some consolidated data
+ to console and plymouth (if running). It also handles
+ possible check cancellations.</para>
+ <para><filename>systemd-fsck-root.service</filename> or
+ <filename>systemd-fsck@.service</filename> will get the
+ progress from fsck and send their individual progress to
+ <filename>systemd-fsckd</filename>, through socket activation
+ by <filename>systemd-fsckd.socket</filename>.</para>
+
+ <para><filename>systemd-fsckd</filename> accepts
+ <filename>systemd-fsck</filename> UNIX domain
+ sockets communication, fetches the lowest progress value of
+ all fsck running in parallel with the number of devices
+ being currently checked. It writes the result to
+ <filename>/dev/console</filename> if show status is enabled,
+ and communicates to the user translated strings to plymouth
+ ready to be used by scripted themes, not supporting i18n.
+ The compilted plymouth themes can use the raw data (see below)
+ to display their own custom messages.</para>
+
+ <para>The first time it connects to plymouth, a request
+ to grab c or C keypresses is sent, as well as a text message.
+ When the cancel key is pressed, all running fscks are terminated.
+ It will also any new fsck for the lifetime of
+ <filename>systemd-fsckd</filename>.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Protocol with plymouth</title>
+
+ <para><filename>systemd-fsckd</filename> passes the following
+ following messages to the theme via libplymouth:</para>
+
+ <para>Progress update, sent as a plymouth update message:
+ <literal>fsckd:<num_devices>:<progress>:<string></literal>
+ <variablelist>
+ <varlistentry>
+ <term><literal><num_devices></literal></term>
+ <listitem><para>the current number of devices
+ being checked (int)</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal><progress></literal></term>
+ <listitem><para>the current minimum percentage of
+ all devices being checking (float, from 0 to 100)</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal><string></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:<string></literal>
+ <variablelist>
+ <varlistentry>
+ <term><literal><strings></literal></term>
+ <listitem><para>a translated string ready to be displayed
+ by the plymouth theme indicating that c or 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><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>
+ </para>
+ </refsect1>
+
+</refentry>
diff --git a/units/systemd-fsckd.service.in b/units/systemd-fsckd.service.in
index 27c325f..9c7ed51 100644
--- a/units/systemd-fsckd.service.in
+++ b/units/systemd-fsckd.service.in
@@ -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
diff --git a/units/systemd-fsckd.socket b/units/systemd-fsckd.socket
index 96a034a..6f4badb 100644
--- a/units/systemd-fsckd.socket
+++ b/units/systemd-fsckd.socket
@@ -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
Before=sockets.target
--
2.1.4
_______________________________________________
systemd-devel mailing list
systemd-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/systemd-devel
