[dm-devel] [PATCH 1/3] multipathd: add multipathc.8 manual page

[mwilck at suse.com]

From: Martin Wilck <mwilck at suse.com>

Document multipathc, and update the man page of multipathd to
describe the command mode correctly.

Signed-off-by: Martin Wilck <mwilck at suse.com>
---
 multipathd/multipathc.8 | 64 +++++++++++++++++++++++++++++++++++++++++
 multipathd/multipathd.8 | 34 +++++++++++++++++-----
 2 files changed, 91 insertions(+), 7 deletions(-)
 create mode 100644 multipathd/multipathc.8

diff --git a/multipathd/multipathc.8 b/multipathd/multipathc.8
new file mode 100644
index 0000000..6c57c6c
--- /dev/null
+++ b/multipathd/multipathc.8
@@ -0,0 +1,64 @@
+.\" ----------------------------------------------------------------------------
+.\" Update the date below if you make any significant change.
+.\" Make sure there are no errors with:
+.\" groff -z -wall -b -e -t multipathd/multipathd.8
+.\"
+.\" ----------------------------------------------------------------------------
+.
+.TH MULTIPATHC 8 2022-09-03 Linux
+.
+.
+.\" ----------------------------------------------------------------------------
+.SH NAME
+.\" ----------------------------------------------------------------------------
+.
+multipathc \- Interactive client for multipathd
+.
+.
+.\" ----------------------------------------------------------------------------
+.SH SYNOPSIS
+.\" ----------------------------------------------------------------------------
+.
+.B multipathc 
+.RB [\|
+.IR timeout
+.RB \|]
+.
+.
+.\" ----------------------------------------------------------------------------
+.SH DESCRIPTION
+.\" ----------------------------------------------------------------------------
+.
+The \fBmultipathc\fR tool provides an interactive shell for communicating
+with the \fBmultipathd\fR daemon.
+The command \fBmultipathd -k\fR invokes \fBmultipathc\fR.
+.P
+All commands documented in \fBmultipathd(8)\fR are supported.
+The available commands can be viewed by entering '\fIhelp\fR'.
+Use \fIquit\fR, \fIexit\fR, or \fBCTRL-D\fR to exit the shell.
+Keywords can be abbreviated with the first letters (for example,
+\fIshu\fR for \fIshutdown\fR), if the abbreviation is unique.
+Some commands support pretty-printing
+using \fBprintf\fR-style format specifiers. The supported format specifiers
+can be listed with the command \fBshow wildcards\fR.
+Depending on build options, the interactive shell
+may provide command completion and history expansion features.
+.P
+The optional parameter \fBtimeout\fR specifies the timeout to wait for
+a reply from \fBmultipathd\fR, in milliseconds. The default is 4000 ms.
+.
+.
+.\" ----------------------------------------------------------------------------
+.SH "SEE ALSO"
+.\" ----------------------------------------------------------------------------
+.
+.BR multipathd (8)
+.
+.
+.\" ----------------------------------------------------------------------------
+.SH AUTHORS
+.\" ----------------------------------------------------------------------------
+.
+\fImultipath-tools\fR was developed by Christophe Varoqui
+<christophe.varoqui at opensvc.com> and others.
+.\" EOF
diff --git a/multipathd/multipathd.8 b/multipathd/multipathd.8
index 1e318bd..a828864 100644
--- a/multipathd/multipathd.8
+++ b/multipathd/multipathd.8
@@ -5,7 +5,7 @@
 .\"
 .\" ----------------------------------------------------------------------------
 .
-.TH MULTIPATHD 8 2016-10-27 Linux
+.TH MULTIPATHD 8 2022-09-03 Linux
 .
 .
 .\" ----------------------------------------------------------------------------
@@ -20,14 +20,23 @@ multipathd \- Multipath daemon.
 .\" ----------------------------------------------------------------------------
 .
 .B multipathd
-.RB [\| \-d | \-k \|]
+.RB [\| \-d \|]
 .RB [\| \-s \|]
 .RB [\| \-v\ \c
 .IR verbosity \|]
 .RB [\| \-B \|]
 .RB [\| \-w \|]
-.
-.
+.LP
+.B multipathd
+.RB [\| \-v\ \c
+.IR verbosity \|]
+.B -k\fIcommand\fR
+.LP
+.B multipathd
+.RB [\| \-v\ \c
+.IR verbosity \|]
+.B -k
+
 .\" ----------------------------------------------------------------------------
 .SH DESCRIPTION
 .\" ----------------------------------------------------------------------------
@@ -36,6 +45,10 @@ The \fBmultipathd\fR daemon is in charge of checking for failed paths. When this
 happens, it will reconfigure the multipath map the path belongs to, so that this
 map regains its maximum performance and redundancy.
 
+With the \fB-k\fR option, \fBmultipathd\fR acts as a client utility that
+sends commands to a running instance of the multipathd daemon (see
+\fBCOMMANDS\fR below).
+
 This daemon executes the external \fBmultipath\fR tool when events occur.
 In turn, the multipath tool signals the multipathd daemon when it is done with
 devmap reconfiguration, so that it can refresh its failed path list.
@@ -66,10 +79,16 @@ bindings file. If a \fIuser_friendly_name\fR doesn't already exist for a device,
 will use its WWID as its alias.
 .
 .TP
+.B \-k\fIcommand\fB
+multipathd executes the given command (see \fBCOMMANDS\fR below). If the
+command contains whitespace or shell special characters, it needs to be quoted
+like in \fImultipathd -k'show topology'\fR. No whitespace is allowed between
+the \fB-k\fR and the command string.
+.
+.TP
 .B \-k
-multipathd will enter interactive mode. From this mode, the available commands can
-be viewed by entering '\fIhelp\fR'. When you are finished entering commands, press
-\fBCTRL-D\fR to quit.
+multipathd executes the \fBmultipathc\fR interactive shell for entering
+commands (see \fBCOMMANDS\fR below).
 .
 .TP
 .B \-n
@@ -346,6 +365,7 @@ Overrides the \fImax_fds\fR configuration setting.
 .SH "SEE ALSO"
 .\" ----------------------------------------------------------------------------
 .
+.BR multipathc (8),
 .BR multipath (8),
 .BR kpartx (8),
 .BR sd_notify (3),
-- 
2.37.1