On Wed, Jan 28, 2015 at 02:24:55PM +0100, Didier Roche wrote: > > From 6b13d8fb248bf4176f1ad7e1d4736683462bf196 Mon Sep 17 00:00:00 2001 > From: Didier Roche <[email protected]> > 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/[email protected] | 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/[email protected] \ > + 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/[email protected] > man/systemd-fsck.8: man/[email protected] > +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/[email protected] > 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/[email protected] > man/systemd-fsck.html: man/[email protected] > $(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/[email protected] > $(html-alias) > > @@ -1732,6 +1743,7 @@ EXTRA_DIST += \ > man/systemd-escape.xml \ > man/systemd-firstboot.xml \ > man/[email protected] \ > + 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/[email protected] b/man/[email protected] > index ee66f37..d366712 100644 > --- a/man/[email protected] > +++ b/man/[email protected] > @@ -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";> Please use 2ch indentation for new man pages.
> + > + <refentryinfo> > + <title>systemd-fsckd.service</title> > + <productname>systemd</productname> > + > + <authorgroup> > + <author> > + <contrib>Developer</contrib> > + <firstname>Didier</firstname> > + <surname>Roche</surname> > + <email>[email protected]</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 receiving, not fetching > + 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>[email protected]</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> I think we don't need this kind of detail in the man page. It might change anyway. > + > + <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 This sentence is missing some verb. > + <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> dup > + <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> This is very detailed too, but it is OK, we don't really have a good place for this kind of documentation. > + </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:[email protected](8) man:systemd-fsck-root.service(8) > +Documentation=man:systemd-fsckd.service(8) man:[email protected](8) > man:systemd-fsck-root.service(8) > DefaultDependencies=no > Before=sockets.target Zbyszek _______________________________________________ systemd-devel mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/systemd-devel
