[PATCH 0/5] multipath-tools: clean up man pages II

[PATCH 0/5] multipath-tools: clean up man pages II

[Xose Vazquez Perez]

It performs general cleanups, updates, and formatting fixes
across the man pages, incorporating feedback from Martin and Ben.

Xose Vazquez Perez (5):
  multipath-tools: remove legacy syntax check comments from man pages
  multipath-tools: clarify path selector descriptions in multipath.conf.5
  multipath-tools: specify file paths using variables and add FILES
                   section in multipath.conf.5
  multipath-tools: clarify user_friendly_names prefix behavior in
                   multipath.conf.5
  multipath-tools: fix mandoc errors/warnings in man pages

 kpartx/kpartx.8                               |  4 -
 libmpathpersist/mpath_persistent_reserve_in.3 |  5 --
 .../mpath_persistent_reserve_out.3            |  5 --
 mpathpersist/mpathpersist.8.in                |  6 --
 multipath/multipath.8.in                      |  4 -
 multipath/multipath.conf.5.in                 | 87 +++++++++++--------
 multipathd/multipathc.8                       |  6 +-
 multipathd/multipathd.8.in                    |  5 --
 8 files changed, 54 insertions(+), 68 deletions(-)

Cc: Martin Wilck <mwilck@suse.com>
Cc: Benjamin Marzinski <bmarzins@redhat.com>
Cc: Christophe Varoqui <christophe.varoqui@opensvc.com>
Cc: DM_DEVEL-ML <dm-devel@lists.linux.dev>
Signed-off-by: Xose Vazquez Perez <xose.vazquez@gmail.com>
-- 
2.54.0

[PATCH 1/5] multipath-tools: remove syntax check comments from man pages

[Xose Vazquez Perez]

Remove the embedded groff/man command lines from the header comments
of all man pages.

Suggested-by: Martin Wilck <mwilck@suse.com>
Cc: Martin Wilck <mwilck@suse.com>
Cc: Benjamin Marzinski <bmarzins@redhat.com>
Cc: Christophe Varoqui <christophe.varoqui@opensvc.com>
Cc: DM_DEVEL-ML <dm-devel@lists.linux.dev>
Signed-off-by: Xose Vazquez Perez <xose.vazquez@gmail.com>
---
 kpartx/kpartx.8                                | 4 ----
 libmpathpersist/mpath_persistent_reserve_in.3  | 4 ----
 libmpathpersist/mpath_persistent_reserve_out.3 | 4 ----
 mpathpersist/mpathpersist.8.in                 | 4 ----
 multipath/multipath.8.in                       | 4 ----
 multipath/multipath.conf.5.in                  | 4 ----
 multipathd/multipathc.8                        | 4 ----
 multipathd/multipathd.8.in                     | 4 ----
 8 files changed, 32 deletions(-)

diff --git a/kpartx/kpartx.8 b/kpartx/kpartx.8
index ef8051a5..fbc8f726 100644
--- a/kpartx/kpartx.8
+++ b/kpartx/kpartx.8
@@ -1,8 +1,4 @@
 .\" ----------------------------------------------------------------------------
-.\" Make sure there are no errors with:
-.\" groff -z -wall -b -e -t kpartx/kpartx.8
-.\" man --warnings -E UTF-8 -l -Tutf8 -Z  kpartx/kpartx.8 > /dev/null
-.\"
 .\" Update the date below if you make any significant change.
 .\" ----------------------------------------------------------------------------
 .
diff --git a/libmpathpersist/mpath_persistent_reserve_in.3 b/libmpathpersist/mpath_persistent_reserve_in.3
index 871242d5..5109fb03 100644
--- a/libmpathpersist/mpath_persistent_reserve_in.3
+++ b/libmpathpersist/mpath_persistent_reserve_in.3
@@ -1,8 +1,4 @@
 .\" ----------------------------------------------------------------------------
-.\" Make sure there are no errors with:
-.\" groff -z -wall -b -e -t libmpathpersist/mpath_persistent_reserve_in.3
-.\" man --warnings -E UTF-8 -l -Tutf8 -Z libmpathpersist/mpath_persistent_reserve_in.3 > /dev/null
-.\"
 .\" Update the date below if you make any significant change.
 .\" ----------------------------------------------------------------------------
 .
diff --git a/libmpathpersist/mpath_persistent_reserve_out.3 b/libmpathpersist/mpath_persistent_reserve_out.3
index bf44777c..09708b93 100644
--- a/libmpathpersist/mpath_persistent_reserve_out.3
+++ b/libmpathpersist/mpath_persistent_reserve_out.3
@@ -1,8 +1,4 @@
 .\" ----------------------------------------------------------------------------
-.\" Make sure there are no errors with:
-.\" groff -z -wall -b -e -t libmpathpersist/mpath_persistent_reserve_out.3
-.\" man --warnings -E UTF-8 -l -Tutf8 -Z libmpathpersist/mpath_persistent_reserve_out.3 > /dev/null
-.\"
 .\" Update the date below if you make any significant change.
 .\" ----------------------------------------------------------------------------
 .
diff --git a/mpathpersist/mpathpersist.8.in b/mpathpersist/mpathpersist.8.in
index 9a5a716b..d5f5a452 100644
--- a/mpathpersist/mpathpersist.8.in
+++ b/mpathpersist/mpathpersist.8.in
@@ -1,8 +1,4 @@
 .\" ----------------------------------------------------------------------------
-.\" Make sure there are no errors with:
-.\" groff -z -wall -b -e -t mpathpersist/mpathpersist.8
-.\" man --warnings -E UTF-8 -l -Tutf8 -Z mpathpersist/mpathpersist.8 > /dev/null
-.\"
 .\" Update the date below if you make any significant change.
 .\" ----------------------------------------------------------------------------
 .
diff --git a/multipath/multipath.8.in b/multipath/multipath.8.in
index 0b170101..da5effb0 100644
--- a/multipath/multipath.8.in
+++ b/multipath/multipath.8.in
@@ -1,8 +1,4 @@
 .\" ----------------------------------------------------------------------------
-.\" Make sure there are no errors with:
-.\" groff -z -wall -b -e -t multipath/multipath.8
-.\" man --warnings -E UTF-8 -l -Tutf8 -Z multipath/multipath.8 > /dev/null
-.\"
 .\" Update the date below if you make any significant change.
 .\" ----------------------------------------------------------------------------
 .
diff --git a/multipath/multipath.conf.5.in b/multipath/multipath.conf.5.in
index 6990d2bf..422ab120 100644
--- a/multipath/multipath.conf.5.in
+++ b/multipath/multipath.conf.5.in
@@ -1,8 +1,4 @@
 .\" ----------------------------------------------------------------------------
-.\" Make sure there are no errors with:
-.\" groff -z -wall -b -e -t multipath/multipath.conf.5
-.\" man --warnings -E UTF-8 -l -Tutf8 -Z multipath/multipath.conf.5 > /dev/null
-.\"
 .\" Update the date below if you make any significant change.
 .\" ----------------------------------------------------------------------------
 .
diff --git a/multipathd/multipathc.8 b/multipathd/multipathc.8
index cf7ae5be..5e97fb81 100644
--- a/multipathd/multipathc.8
+++ b/multipathd/multipathc.8
@@ -1,8 +1,4 @@
 .\" ----------------------------------------------------------------------------
-.\" Make sure there are no errors with:
-.\" groff -z -wall -b -e -t multipathd/multipathc.8
-.\" man --warnings -E UTF-8 -l -Tutf8 -Z multipathd/multipathc.8 > /dev/null
-.\"
 .\" Update the date below if you make any significant change.
 .\" ----------------------------------------------------------------------------
 .
diff --git a/multipathd/multipathd.8.in b/multipathd/multipathd.8.in
index d766dc65..93625a90 100644
--- a/multipathd/multipathd.8.in
+++ b/multipathd/multipathd.8.in
@@ -1,8 +1,4 @@
 .\" ----------------------------------------------------------------------------
-.\" Make sure there are no errors with:
-.\" groff -z -wall -b -e -t multipathd/multipathd.8
-.\" man --warnings -E UTF-8 -l -Tutf8 -Z multipathd/multipathd.8 > /dev/null
-.\"
 .\" Update the date below if you make any significant change.
 .\" ----------------------------------------------------------------------------
 .
-- 
2.54.0

[PATCH 2/5] multipath-tools: clarify path selector descriptions in multipath.conf.5

[Xose Vazquez Perez]

Selectors operate on the next individual I/O request rather
than a "bunch" of I/O.

Suggested-by: Benjamin Marzinski <bmarzins@redhat.com>
Cc: Martin Wilck <mwilck@suse.com>
Cc: Benjamin Marzinski <bmarzins@redhat.com>
Cc: Christophe Varoqui <christophe.varoqui@opensvc.com>
Cc: DM_DEVEL-ML <dm-devel@lists.linux.dev>
Signed-off-by: Xose Vazquez Perez <xose.vazquez@gmail.com>
---
 multipath/multipath.conf.5.in | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

diff --git a/multipath/multipath.conf.5.in b/multipath/multipath.conf.5.in
index 422ab120..287441bd 100644
--- a/multipath/multipath.conf.5.in
+++ b/multipath/multipath.conf.5.in
@@ -2,7 +2,7 @@
 .\" Update the date below if you make any significant change.
 .\" ----------------------------------------------------------------------------
 .
-.TH MULTIPATH.CONF 5 2026-05-27 Linux
+.TH MULTIPATH.CONF 5 2026-06-13 Linux
 .
 .
 .\" ----------------------------------------------------------------------------
@@ -193,20 +193,18 @@ kernel multipath target:
 .RS
 .TP
 .I "round-robin 0"
-Choose the path for the next bunch of I/O by looping through every path in the
-path group, sending \fBthe same number of I/O requests\fR to each path.
-
+Choose the path for the next I/O request by \fBcycling through the path group\fR.
 .TP
 .I "queue-length 0"
-(Since 2.6.31 kernel) Choose the path for the next bunch of I/O based on \fBthe lowest
+(Since 2.6.31 kernel) Choose the path for the next I/O request based on \fBthe lowest
 number of outstanding in-flight I/O requests\fR to the path.
 .TP
 .I "service-time 0"
-(Since 2.6.31 kernel) Choose the path for the next bunch of I/O based on \fBthe
+(Since 2.6.31 kernel) Choose the path for the next I/O request based on \fBthe
 lowest total size (in bytes) of outstanding in-flight I/O requests\fR to the path.
 .TP
 .I "historical-service-time 0"
-(Since 5.8 kernel) Choose the path for the next bunch of I/O with \fBa dynamic
+(Since 5.8 kernel) Choose the path for the next I/O request with \fBa dynamic
 algorithm based on the historical service time and the number of outstanding
 in-flight I/O requests\fR to the path.
 .TP
-- 
2.54.0

Re: [PATCH 2/5] multipath-tools: clarify path selector descriptions in multipath.conf.5

[Martin Wilck]

On Sat, 2026-06-13 at 15:09 +0200, Xose Vazquez Perez wrote:
> Selectors operate on the next individual I/O request rather
> than a "bunch" of I/O.

This patch doesn't apply cleanly to any of my branches (master, queue,
tip).

> 
> Suggested-by: Benjamin Marzinski <bmarzins@redhat.com>
> Cc: Martin Wilck <mwilck@suse.com>
> Cc: Benjamin Marzinski <bmarzins@redhat.com>
> Cc: Christophe Varoqui <christophe.varoqui@opensvc.com>
> Cc: DM_DEVEL-ML <dm-devel@lists.linux.dev>
> Signed-off-by: Xose Vazquez Perez <xose.vazquez@gmail.com>
> ---
>  multipath/multipath.conf.5.in | 12 +++++-------
>  1 file changed, 5 insertions(+), 7 deletions(-)
> 
> diff --git a/multipath/multipath.conf.5.in
> b/multipath/multipath.conf.5.in
> index 422ab120..287441bd 100644
> --- a/multipath/multipath.conf.5.in
> +++ b/multipath/multipath.conf.5.in
> @@ -2,7 +2,7 @@
>  .\" Update the date below if you make any significant change.
>  .\" ----------------------------------------------------------------
> ------------
>  .
> -.TH MULTIPATH.CONF 5 2026-05-27 Linux
> +.TH MULTIPATH.CONF 5 2026-06-13 Linux
>  .
>  .
>  .\" ----------------------------------------------------------------
> ------------
> @@ -193,20 +193,18 @@ kernel multipath target:
>  .RS
>  .TP
>  .I "round-robin 0"
> -Choose the path for the next bunch of I/O by looping through every
> path in the
> -path group, sending \fBthe same number of I/O requests\fR to each
> path.
> -
> +Choose the path for the next I/O request by \fBcycling through the
> path group\fR.

I think "group" should be replaced by "groups" here.

Martin

Re: [PATCH 2/5] multipath-tools: clarify path selector descriptions in multipath.conf.5

[Xose Vazquez Perez]

On 6/15/26 10:16 AM, Martin Wilck wrote:

> On Sat, 2026-06-13 at 15:09 +0200, Xose Vazquez Perez wrote:
>> Selectors operate on the next individual I/O request rather
>> than a "bunch" of I/O.
> 
> This patch doesn't apply cleanly to any of my branches (master, queue,
> tip).
That quote is from the patch series I sent earlier. You might have missed it:

Xose Vazquez Perez (3):
   multipath-tools: delete obsolete information from multipath.conf.5
   multipath-tools: remove explicit width from .TP macros in multipath.conf.5
   multipath-tools: remove explicit widths from macros in the remaining man pages

  libmpathpersist/mpath_persistent_reserve_in.3 |   4 +-
  .../mpath_persistent_reserve_out.3            |   4 +-
  mpathpersist/mpathpersist.8.in                |   2 +-
  multipath/multipath.8.in                      |   6 +-
  multipath/multipath.conf.5.in                 | 135 +++++-------------
  multipathd/multipathd.8.in                    |   9 +-
  6 files changed, 51 insertions(+), 109 deletions(-)

Re: [PATCH 2/5] multipath-tools: clarify path selector descriptions in multipath.conf.5

[Martin Wilck]

On Mon, 2026-06-15 at 10:26 +0200, Xose Vazquez Perez wrote:
> On 6/15/26 10:16 AM, Martin Wilck wrote:
> 
> > On Sat, 2026-06-13 at 15:09 +0200, Xose Vazquez Perez wrote:
> > > Selectors operate on the next individual I/O request rather
> > > than a "bunch" of I/O.
> > 
> > This patch doesn't apply cleanly to any of my branches (master,
> > queue,
> > tip).
> That quote is from the patch series I sent earlier. You might have
> missed it:

No, but Ben had remarks on it, and I expected you to submit a v2.
So I am gathering that you want me to apply that series, and Ben's
points are addressed by the 2nd series on top. That wasn's obvious to
me, sorry.

Martin


> 
> Xose Vazquez Perez (3):
>    multipath-tools: delete obsolete information from multipath.conf.5
>    multipath-tools: remove explicit width from .TP macros in
> multipath.conf.5
>    multipath-tools: remove explicit widths from macros in the
> remaining man pages
> 
>   libmpathpersist/mpath_persistent_reserve_in.3 |   4 +-
>   .../mpath_persistent_reserve_out.3            |   4 +-
>   mpathpersist/mpathpersist.8.in                |   2 +-
>   multipath/multipath.8.in                      |   6 +-
>   multipath/multipath.conf.5.in                 | 135 +++++----------
> ---
>   multipathd/multipathd.8.in                    |   9 +-
>   6 files changed, 51 insertions(+), 109 deletions(-)

Re: [PATCH 2/5] multipath-tools: clarify path selector descriptions in multipath.conf.5

[Martin Wilck]

On Mon, 2026-06-15 at 10:26 +0200, Xose Vazquez Perez wrote:
> On 6/15/26 10:16 AM, Martin Wilck wrote:
> 
> > On Sat, 2026-06-13 at 15:09 +0200, Xose Vazquez Perez wrote:
> > > Selectors operate on the next individual I/O request rather
> > > than a "bunch" of I/O.
> > 
> > This patch doesn't apply cleanly to any of my branches (master,
> > queue,
> > tip).
> That quote is from the patch series I sent earlier. You might have
> missed it:
> 
> Xose Vazquez Perez (3):
>    multipath-tools: delete obsolete information from multipath.conf.5
>    multipath-tools: remove explicit width from .TP macros in
> multipath.conf.5
>    multipath-tools: remove explicit widths from macros in the
> remaining man pages

I was about to apply this (5-part) series to the queue branch. But I do
have an issue with the other series, as I just wrote, so I'm postponing
this again. I would like to ask you to send a consolidated series. But
first I guess we need to reach consensus what to do with the rr_minio
patch.

Martin

Re: [PATCH 2/5] multipath-tools: clarify path selector descriptions in multipath.conf.5

[Xose Vazquez Perez]

On 6/15/26 11:15 AM, Martin Wilck wrote:

> On Mon, 2026-06-15 at 10:26 +0200, Xose Vazquez Perez wrote:
>> On 6/15/26 10:16 AM, Martin Wilck wrote:
>>
>>> On Sat, 2026-06-13 at 15:09 +0200, Xose Vazquez Perez wrote:
>>>> Selectors operate on the next individual I/O request rather
>>>> than a "bunch" of I/O.
>>>
>>> This patch doesn't apply cleanly to any of my branches (master,
>>> queue,
>>> tip).
>> That quote is from the patch series I sent earlier. You might have
>> missed it:
>>
>> Xose Vazquez Perez (3):
>>     multipath-tools: delete obsolete information from multipath.conf.5
>>     multipath-tools: remove explicit width from .TP macros in
>> multipath.conf.5
>>     multipath-tools: remove explicit widths from macros in the
>> remaining man pages
> 
> I was about to apply this (5-part) series to the queue branch. But I do
> have an issue with the other series, as I just wrote, so I'm postponing
> this again. I would like to ask you to send a consolidated series. But
> first I guess we need to reach consensus what to do with the rr_minio
> patch.
With git 2.54.0 and a clean environment (no ~/.gitconfig), all parches
apply cleanly on my end over the queue branch:

$ git clone https://github.com/openSUSE/multipath-tools.git
Cloning into 'multipath-tools'...
remote: Enumerating objects: 40696, done.
remote: Counting objects: 100% (240/240), done.
remote: Compressing objects: 100% (126/126), done.
remote: Total 40696 (delta 141), reused 180 (delta 114), pack-reused 40456 (from 1)
Receiving objects: 100% (40696/40696), 8.00 MiB | 23.14 MiB/s, done.
Resolving deltas: 100% (31803/31803), done.

$ cd multipath-tools/

$ git branch
* queue

$ git am /mnt/datos/curre/arrays/p/enviados/cambios_man_tab/*.patch
Committer identity unknown

*** Please tell me who you are.

Run

   git config --global user.email "you@example.com"
   git config --global user.name "Your Name"

to set your account's default identity.
Omit --global to set the identity only in this repository.

fatal: empty ident name (for <you@example.com>) not allowed

$ git config --global user.email "you@example.com"

$ git config --global user.name "Your Name"

$ git am /mnt/datos/curre/arrays/p/enviados/cambios_man_tab/*.patch
Applying: multipath-tools: delete obsolete information from multipath.conf.5
Applying: multipath-tools: remove explicit width from .TP macros in multipath.conf.5
Applying: multipath-tools: remove explicit widths from macros in the remaining man pages

$ git am /mnt/datos/curre/arrays/p/enviados/cambios_man_II/*.patch
Applying: multipath-tools: remove syntax check comments from man pages
Applying: multipath-tools: clarify path selector descriptions in multipath.conf.5
Applying: multipath-tools: specify file paths using variables and add FILES section in multipath.conf.5
Applying: multipath-tools: clarify user_friendly_names prefix behavior in multipath.conf.5
Applying: multipath-tools: fix mandoc errors/warnings in man pages

$ git log -8 --oneline
fdd4549f (HEAD -> queue) multipath-tools: fix mandoc errors/warnings in man pages
b487df0e multipath-tools: clarify user_friendly_names prefix behavior in multipath.conf.5
cfe8681a multipath-tools: specify file paths using variables and add FILES section in multipath.conf.5
f6a59c26 multipath-tools: clarify path selector descriptions in multipath.conf.5
bf9e518c multipath-tools: remove syntax check comments from man pages
faf4dcb4 multipath-tools: remove explicit widths from macros in the remaining man pages
2b33e306 multipath-tools: remove explicit width from .TP macros in multipath.conf.5
fd084d8f multipath-tools: delete obsolete information from multipath.conf.5

Re: [PATCH 2/5] multipath-tools: clarify path selector descriptions in multipath.conf.5

[Martin Wilck]

On Mon, 2026-06-15 at 18:44 +0200, Xose Vazquez Perez wrote:
> On 6/15/26 11:15 AM, Martin Wilck wrote:
> 
> > On Mon, 2026-06-15 at 10:26 +0200, Xose Vazquez Perez wrote:
> > > On 6/15/26 10:16 AM, Martin Wilck wrote:
> > > 
> > > > On Sat, 2026-06-13 at 15:09 +0200, Xose Vazquez Perez wrote:
> > > > > Selectors operate on the next individual I/O request rather
> > > > > than a "bunch" of I/O.
> > > > 
> > > > This patch doesn't apply cleanly to any of my branches (master,
> > > > queue,
> > > > tip).
> > > That quote is from the patch series I sent earlier. You might
> > > have
> > > missed it:
> > > 
> > > Xose Vazquez Perez (3):
> > >     multipath-tools: delete obsolete information from
> > > multipath.conf.5
> > >     multipath-tools: remove explicit width from .TP macros in
> > > multipath.conf.5
> > >     multipath-tools: remove explicit widths from macros in the
> > > remaining man pages
> > 
> > I was about to apply this (5-part) series to the queue branch. But
> > I do
> > have an issue with the other series, as I just wrote, so I'm
> > postponing
> > this again. I would like to ask you to send a consolidated series.
> > But
> > first I guess we need to reach consensus what to do with the
> > rr_minio
> > patch.
> With git 2.54.0 and a clean environment (no ~/.gitconfig), all
> parches
> apply cleanly on my end over the queue branch:

It didn't for me this morning, but I can handle that. But I'd
appreciate a clean, complete series with all the man page fixes.

Please see Ben's latest reply. He is working on a patch that keeps
rr_min_io, and removes rr_min_io_rq and rr_weight. The man page should
reflect this correctly.

Regards
Martin

Re: [PATCH 2/5] multipath-tools: clarify path selector descriptions in multipath.conf.5

[Martin Wilck]

On Sat, 2026-06-13 at 15:09 +0200, Xose Vazquez Perez wrote:
> Selectors operate on the next individual I/O request rather
> than a "bunch" of I/O.

This patch doesn't apply cleanly to any of my branches (master, queue,
tip).

> 
> Suggested-by: Benjamin Marzinski <bmarzins@redhat.com>
> Cc: Martin Wilck <mwilck@suse.com>
> Cc: Benjamin Marzinski <bmarzins@redhat.com>
> Cc: Christophe Varoqui <christophe.varoqui@opensvc.com>
> Cc: DM_DEVEL-ML <dm-devel@lists.linux.dev>
> Signed-off-by: Xose Vazquez Perez <xose.vazquez@gmail.com>
> ---
>  multipath/multipath.conf.5.in | 12 +++++-------
>  1 file changed, 5 insertions(+), 7 deletions(-)
> 
> diff --git a/multipath/multipath.conf.5.in
> b/multipath/multipath.conf.5.in
> index 422ab120..287441bd 100644
> --- a/multipath/multipath.conf.5.in
> +++ b/multipath/multipath.conf.5.in
> @@ -2,7 +2,7 @@
>  .\" Update the date below if you make any significant change.
>  .\" ----------------------------------------------------------------
> ------------
>  .
> -.TH MULTIPATH.CONF 5 2026-05-27 Linux
> +.TH MULTIPATH.CONF 5 2026-06-13 Linux
>  .
>  .
>  .\" ----------------------------------------------------------------
> ------------
> @@ -193,20 +193,18 @@ kernel multipath target:
>  .RS
>  .TP
>  .I "round-robin 0"
> -Choose the path for the next bunch of I/O by looping through every
> path in the
> -path group, sending \fBthe same number of I/O requests\fR to each
> path.
> -
> +Choose the path for the next I/O request by \fBcycling through the
> path group\fR.

I think "group" should be replaced by "groups" here.

Martin

[PATCH 3/5] multipath-tools: specify file paths using variables and add FILES section in multipath.conf.5

[Xose Vazquez Perez]

Replace hardcoded file name references with their dynamic build variables.
Also, add a dedicated FILES section at the end of the man page to clearly
document configuration files/dirs.

Suggested-by: Benjamin Marzinski <bmarzins@redhat.com>
Cc: Martin Wilck <mwilck@suse.com>
Cc: Benjamin Marzinski <bmarzins@redhat.com>
Cc: Christophe Varoqui <christophe.varoqui@opensvc.com>
Cc: DM_DEVEL-ML <dm-devel@lists.linux.dev>
Signed-off-by: Xose Vazquez Perez <xose.vazquez@gmail.com>
---
 multipath/multipath.conf.5.in | 55 ++++++++++++++++++++++++++---------
 1 file changed, 42 insertions(+), 13 deletions(-)

diff --git a/multipath/multipath.conf.5.in b/multipath/multipath.conf.5.in
index 287441bd..9289b244 100644
--- a/multipath/multipath.conf.5.in
+++ b/multipath/multipath.conf.5.in
@@ -27,7 +27,7 @@ or \fBmultipathd show config\fR command.
 .
 .PP
 Additional configuration can be made in drop-in files under
-.B @CONFIGDIR@.
+.BR @CONFIGDIR@/ .
 Files ending in \fI.conf\fR in this directory are read
 in alphabetical order, after reading \fI@CONFIGFILE@\fR.
 They use the same syntax as \fI@CONFIGFILE@\fR itself,
@@ -831,11 +831,11 @@ to the end of the reservation key.
 .RS
 .PP
 Alternatively, this can be set to \fBfile\fR, which will store the RESERVATION
-KEY registered by mpathpersist in the \fIprkeys_file\fR. multipathd will then
-use this key to register additional paths as they appear.  When the
+KEY registered by mpathpersist in the \fI@STATE_DIR@/prkeys\fR file. multipathd
+will then use this key to register additional paths as they appear. When the
 registration is removed, the RESERVATION KEY is removed from the
-\fIprkeys_file\fR. The prkeys file will automatically keep track of whether
-the key was registered with \fI--param-aptpl\fR.
+\fI@STATE_DIR@/prkeys\fR file. The prkeys file will automatically keep track of
+whether the key was registered with \fI--param-aptpl\fR.
 .TP
 The default is: \fB<unset>\fR
 .RE
@@ -1152,9 +1152,9 @@ detects a new device. The following values are possible:
 .I strict
 Both multipath and multipathd treat only such devices as multipath devices
 which have been part of a multipath map previously, and which are therefore
-listed in the \fBwwids_file\fR. Users can manually set up multipath maps using the
-\fBmultipathd add map\fR command. Once set up manually, the map is
-remembered in the wwids file and will be set up automatically in the future.
+listed in the \fI@STATE_DIR@/wwids\fR file. Users can manually set up multipath
+maps using the \fBmultipathd add map\fR command. Once set up manually, the map is
+remembered in the WWIDs file and will be set up automatically in the future.
 .TP
 .I off
 Multipath behaves like \fBstrict\fR. Multipathd behaves like \fBgreedy\fR.
@@ -1513,8 +1513,8 @@ this is \fBnot\fR a regular expression or a substring; WWIDs must match
 exactly inside the multipaths section.
 .TP
 .B alias
-Symbolic name for the multipath map. This takes precedence over a an entry for
-the same WWID in the \fIbindings_file\fR.
+Symbolic name for the multipath map. This takes precedence over an entry for
+the same WWID in the \fI@STATE_DIR@/bindings\fR file.
 .LP
 .
 .
@@ -1598,9 +1598,9 @@ for more than 100 known multipath-capable storage devices. The devices section
 can be used to override these settings. If there are multiple matches for a
 given device, the attributes of all matching entries are applied to it.
 If an attribute is specified in several matching device subsections,
-later entries take precedence. Thus, entries in files under \fIconfig_dir\fR (in
-reverse alphabetical order) have the highest precedence, followed by entries
-in \fI@CONFIGFILE@\fR; the built-in hardware table has the lowest
+later entries take precedence. Thus, entries in files under the \fI@CONFIGDIR@/\fR
+directory (in reverse alphabetical order) have the highest precedence, followed
+by entries in \fI@CONFIGFILE@\fR; the built-in hardware table has the lowest
 precedence. Inside a configuration file, later entries have higher precedence
 than earlier ones.
 .LP
@@ -2028,6 +2028,35 @@ specified the order of precedence is \fIno_path_retry, queue_if_no_path, dev_los
 .
 .
 .\" ----------------------------------------------------------------------------
+.SH "FILES"
+.\" ----------------------------------------------------------------------------
+.
+Default paths for configuration files and directories:
+.TP
+.I @CONFIGFILE@
+Main configuration file.
+.TP
+.I @CONFIGDIR@/
+Directory for configuration drop-in files.
+.TP
+.I @STATE_DIR@/bindings
+Bindings file, used when the \fBuser_friendly_names\fR option is set to
+\fByes\fR to assign a persistent and unique alias to each multipath device.
+.TP
+.I @STATE_DIR@/prkeys
+Persistent reservation keys file, used by multipathd to keep track of the
+reservation key used for a specific WWID when \fBreservation_key\fR is set
+to \fBfile\fR.
+.TP
+.I @STATE_DIR@/wwids
+WWIDs file, used by multipath to keep track of the WWIDs of LUNs for which
+multipath devices have been created in the past.
+.TP
+.I @RUNTIME_DIR@/multipathd.pid
+PID file.
+.
+.
+.\" ----------------------------------------------------------------------------
 .SH "SEE ALSO"
 .\" ----------------------------------------------------------------------------
 .
-- 
2.54.0

[PATCH 4/5] multipath-tools: clarify user_friendly_names prefix behavior in multipath.conf.5

[Xose Vazquez Perez]

Clarify that the alias prefix depends on the alias_prefix setting.

Cc: Martin Wilck <mwilck@suse.com>
Cc: Benjamin Marzinski <bmarzins@redhat.com>
Cc: Christophe Varoqui <christophe.varoqui@opensvc.com>
Cc: DM_DEVEL-ML <dm-devel@lists.linux.dev>
Signed-off-by: Xose Vazquez Perez <xose.vazquez@gmail.com>
---
 multipath/multipath.conf.5.in | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/multipath/multipath.conf.5.in b/multipath/multipath.conf.5.in
index 9289b244..74447f8c 100644
--- a/multipath/multipath.conf.5.in
+++ b/multipath/multipath.conf.5.in
@@ -704,11 +704,13 @@ The default is: \fBunused\fR
 .B user_friendly_names
 If set to
 .I yes
-, using the bindings file \fI@STATE_DIR@/bindings\fR to assign a persistent
-and unique alias to the multipath, in the form of mpath<n>. If set to
+, the bindings file \fI@STATE_DIR@/bindings\fR is used to assign a persistent
+and unique alias to the multipath, in the form of \fIprefix\fR<n> (where
+\fIprefix\fR is defined by \fIalias_prefix\fR; by default \IBmpath<n>\fR).
+If set to
 .I no
-use the WWID as the alias. In either case this be will
-be overridden by any specific aliases in the \fImultipaths\fR section.
+, the WWID is used as the alias. In either case, this will be overridden
+by any specific aliases defined in the \fImultipaths\fR section.
 .RS
 .TP
 The default is: \fBno\fR
-- 
2.54.0

Re: [PATCH 4/5] multipath-tools: clarify user_friendly_names prefix behavior in multipath.conf.5

[Martin Wilck]

On Sat, 2026-06-13 at 15:09 +0200, Xose Vazquez Perez wrote:
> Clarify that the alias prefix depends on the alias_prefix setting.
> 
> Cc: Martin Wilck <mwilck@suse.com>
> Cc: Benjamin Marzinski <bmarzins@redhat.com>
> Cc: Christophe Varoqui <christophe.varoqui@opensvc.com>
> Cc: DM_DEVEL-ML <dm-devel@lists.linux.dev>
> Signed-off-by: Xose Vazquez Perez <xose.vazquez@gmail.com>
> ---
>  multipath/multipath.conf.5.in | 10 ++++++----
>  1 file changed, 6 insertions(+), 4 deletions(-)
> 
> diff --git a/multipath/multipath.conf.5.in
> b/multipath/multipath.conf.5.in
> index 9289b244..74447f8c 100644
> --- a/multipath/multipath.conf.5.in
> +++ b/multipath/multipath.conf.5.in
> @@ -704,11 +704,13 @@ The default is: \fBunused\fR
>  .B user_friendly_names
>  If set to
>  .I yes
> -, using the bindings file \fI@STATE_DIR@/bindings\fR to assign a
> persistent
> -and unique alias to the multipath, in the form of mpath<n>. If set
> to
> +, the bindings file \fI@STATE_DIR@/bindings\fR is used to assign a
> persistent
> +and unique alias to the multipath, in the form of \fIprefix\fR<n>
> (where
> +\fIprefix\fR is defined by \fIalias_prefix\fR; by default
> \IBmpath<n>\fR).

I think this should be "\fImpath\fR".

Martin

[PATCH 5/5] multipath-tools: fix mandoc errors/warnings in man pages

[Xose Vazquez Perez]

Fix the following errors and warnings reported by mandoc linting:
$ mandoc -W all -T lint man_page.X | grep -v "STYLE: input text line longer than 80 bytes"

mandoc: ./libmpathpersist/mpath_persistent_reserve_in.3:22:2: WARNING: skipping paragraph macro: PP empty
mandoc: ./libmpathpersist/mpath_persistent_reserve_out.3:22:2: WARNING: skipping paragraph macro: PP empty
mandoc: ./mpathpersist/mpathpersist.8.in:172:2: WARNING: skipping paragraph macro: PP after SH
mandoc: ./mpathpersist/mpathpersist.8.in:215:2: WARNING: skipping paragraph macro: PP after SH
mandoc: ./multipathd/multipathc.8:19:15: STYLE: whitespace at end of input line
mandoc: ./multipathd/multipathd.8.in:573:2: WARNING: skipping paragraph macro: PP empty
mandoc: ./multipathd/multipathd.8.in:573:2: WARNING: skipping paragraph macro: PP empty
mandoc: ./multipath/multipath.conf.5.in:130:2: ERROR: skipping end of block that is not open: RE
mandoc: ./multipath/multipath.conf.5.in:1979:2: ERROR: skipping end of block that is not open: RE
mandoc: ./multipath/multipath.conf.5.in:89:2: WARNING: skipping paragraph macro: PP empty
mandoc: ./multipath/multipath.conf.5.in:131:2: WARNING: skipping paragraph macro: PP empty
mandoc: ./multipath/multipath.conf.5.in:130:2: WARNING: skipping paragraph macro: br at the end of SH
mandoc: ./multipath/multipath.conf.5.in:1577:2: WARNING: skipping paragraph macro: PP empty
mandoc: ./multipath/multipath.conf.5.in:1770:2: WARNING: skipping paragraph macro: PP empty

Cc: Martin Wilck <mwilck@suse.com>
Cc: Benjamin Marzinski <bmarzins@redhat.com>
Cc: Christophe Varoqui <christophe.varoqui@opensvc.com>
Cc: DM_DEVEL-ML <dm-devel@lists.linux.dev>
Signed-off-by: Xose Vazquez Perez <xose.vazquez@gmail.com>
---
 libmpathpersist/mpath_persistent_reserve_in.3  | 1 -
 libmpathpersist/mpath_persistent_reserve_out.3 | 1 -
 mpathpersist/mpathpersist.8.in                 | 2 --
 multipath/multipath.conf.5.in                  | 6 ------
 multipathd/multipathc.8                        | 2 +-
 multipathd/multipathd.8.in                     | 1 -
 6 files changed, 1 insertion(+), 12 deletions(-)

diff --git a/libmpathpersist/mpath_persistent_reserve_in.3 b/libmpathpersist/mpath_persistent_reserve_in.3
index 5109fb03..36cc7815 100644
--- a/libmpathpersist/mpath_persistent_reserve_in.3
+++ b/libmpathpersist/mpath_persistent_reserve_in.3
@@ -19,7 +19,6 @@ mpath_persistent_reserve_in \- send PRIN command to DM device
 .B #include <mpath_persist.h>
 .P
 .BI "int mpath_persistent_reserve_in" "(int fd, int rq_servact, struct prin_resp *resp, int noisy, int verbose)"
-.P
 .
 .
 .\" ----------------------------------------------------------------------------
diff --git a/libmpathpersist/mpath_persistent_reserve_out.3 b/libmpathpersist/mpath_persistent_reserve_out.3
index 09708b93..1a2b9511 100644
--- a/libmpathpersist/mpath_persistent_reserve_out.3
+++ b/libmpathpersist/mpath_persistent_reserve_out.3
@@ -19,7 +19,6 @@ mpath_persistent_reserve_out \- send PROUT command to DM device
 .B #include <mpath_persist.h>
 .P
 .BI "int mpath_persistent_reserve_out" "(int fd, int rq_servact, int rq_scope, unsigned int rq_type, struct prout_param_descriptor *paramp, int noisy, int verbose)"
-.P
 .
 .
 .\" ----------------------------------------------------------------------------
diff --git a/mpathpersist/mpathpersist.8.in b/mpathpersist/mpathpersist.8.in
index d5f5a452..2208008c 100644
--- a/mpathpersist/mpathpersist.8.in
+++ b/mpathpersist/mpathpersist.8.in
@@ -169,7 +169,6 @@ PR In: maximum allocation length. LEN is a decimal number between 0 and 8192.
 .SH EXAMPLE
 .\" ----------------------------------------------------------------------------
 .
-.PP
 Register the key \(dq123abc\(dq for the /dev/mapper/mpath9 device:
 .RS
 \fBmpathpersist --out --register --param-sark=\fI123abc /dev/mapper/mpath9\fR
@@ -212,7 +211,6 @@ Remove current reservation, and unregister all registered keys from all I_T nexu
 .SH BATCH FILES
 .\" ----------------------------------------------------------------------------
 .
-.PP
 The option \fI--batch-file\fR (\fI-f\fR) sets an input file to be processed
 by \fBmpathpersist\fR. Grouping commands in batch files can provide a speed
 improvement in particular on large installments, because \fBmpathpersist\fR
diff --git a/multipath/multipath.conf.5.in b/multipath/multipath.conf.5.in
index 74447f8c..ff4eba4f 100644
--- a/multipath/multipath.conf.5.in
+++ b/multipath/multipath.conf.5.in
@@ -88,7 +88,6 @@ the indentation shown in the above example is helpful for human readers but
 not mandatory.
 .LP
 .
-.LP
 .B Note on regular expressions:
 The \fI@CONFIGFILE@\fR syntax allows many attribute values to be specified as POSIX
 Extended Regular Expressions (see \fBregex\fR(7)). These regular expressions
@@ -127,8 +126,6 @@ vendor, product, and revision.
 .B overrides
 This section defines values for attributes that should override the
 device-specific settings for all devices.
-.RE
-.LP
 .
 .
 .\" ----------------------------------------------------------------------------
@@ -1576,7 +1573,6 @@ section:
 .B ghost_delay
 .RE
 .PD
-.LP
 .
 .
 .\" ----------------------------------------------------------------------------
@@ -1769,7 +1765,6 @@ section:
 .B all_tg_pt
 .RE
 .PD
-.LP
 .
 .
 .\" ----------------------------------------------------------------------------
@@ -1978,7 +1973,6 @@ as integrity failures or congestion with so-called Fabric Performance
 Impact Notifications (FPINs).On receiving the fpin notifications through ELS
 multipathd will move the affected path and port states to marginal.
 .
-.RE
 .LP
 See the documentation
 of the individual options above for details.
diff --git a/multipathd/multipathc.8 b/multipathd/multipathc.8
index 5e97fb81..2187d1ed 100644
--- a/multipathd/multipathc.8
+++ b/multipathd/multipathc.8
@@ -16,7 +16,7 @@ multipathc \- Interactive client for multipathd
 .SH SYNOPSIS
 .\" ----------------------------------------------------------------------------
 .
-.B multipathc 
+.B multipathc
 .RB [\|
 .IR timeout
 .RB \|]
diff --git a/multipathd/multipathd.8.in b/multipathd/multipathd.8.in
index 93625a90..632cbe40 100644
--- a/multipathd/multipathd.8.in
+++ b/multipathd/multipathd.8.in
@@ -570,7 +570,6 @@ The device appears usable, but it being delayed for marginal path checking.
 .I undef
 The device either is not part of a multipath device, or its path checker has
 not yet run.
-.PP
 .RE
 .TP
 .B %s
-- 
2.54.0