From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
To: mtk.manpages@gmail.com
Cc: linux-man@vger.kernel.org, libc-alpha@sourceware.org
Subject: [PATCH] pldd.1: Document glibc's unbreakage of tool.
Date: Sat, 11 May 2019 17:20:52 +1000 [thread overview]
Message-ID: <20190511072049.2w7pp723iszp3gra@localhost.localdomain> (raw)
[-- Attachment #1.1: Type: text/plain, Size: 148 bytes --]
...plus a patch with some suggested wording fixes.
...plus a patch with some suggestions on improving the formatting and
markup.
Regards,
Branden
[-- Attachment #1.2: 0001-pldd.1-Document-glibc-s-unbreakage-of-tool.patch --]
[-- Type: text/x-diff, Size: 1229 bytes --]
From fddc56cb731f711143bad6202210d974ace7b7fe Mon Sep 17 00:00:00 2001
From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Date: Sat, 11 May 2019 16:25:54 +1000
Subject: [PATCH 1/3] pldd.1: Document glibc's unbreakage of tool.
glibc 2.30 isn't released yet, but a fix has been committed, and Debian
has even cherry-picked it for Debian GNU/Linux 10 ("buster"). pldd
works nicely now.
Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>
---
man1/pldd.1 | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/man1/pldd.1 b/man1/pldd.1
index 90e259989..dab6cb32c 100644
--- a/man1/pldd.1
+++ b/man1/pldd.1
@@ -97,11 +97,11 @@ $ \fBgdb \-ex "set confirm off" \-ex "set height 0" \-ex "info shared" \e\fP
.EE
.in
.SH BUGS
-Since glibc 2.19,
+From glibc 2.19 to 2.29,
.B pldd
-is broken: it just hangs when executed.
-.\" FIXME . https://sourceware.org/bugzilla/show_bug.cgi?id=18035
-It is unclear if it will ever be fixed.
+was broken: it just hung when executed.
+.\" glibc commit 1a4c27355e146b6d8cc6487b998462c7fdd1048f
+This problem was fixed in glibc 2.30.
.SH EXAMPLE
.EX
$ \fBecho $$\fP # Display PID of shell
--
2.20.1
[-- Attachment #1.3: 0002-pldd.1-wfix.patch --]
[-- Type: text/x-diff, Size: 1676 bytes --]
From d1ee216ecb3400c2f14aed4a8689b34ec9d2d3da Mon Sep 17 00:00:00 2001
From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Date: Sat, 11 May 2019 16:30:10 +1000
Subject: [PATCH 2/3] pldd.1: wfix
* Establish the abbreviations DSO and PID in the lead paragraph since
they are used later.
* Parallelize descriptions of help, usage, and version options with the
"and exit" language used in getent(1), iconv(1), locale(1),
localedef(1), memusage(1), memusagestat(1), mtrace(1), pldd(1),
sprof(1), time(1), iconvconfig(8), zdump(8), and zic(8).
Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>
---
man1/pldd.1 | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/man1/pldd.1 b/man1/pldd.1
index dab6cb32c..035368e20 100644
--- a/man1/pldd.1
+++ b/man1/pldd.1
@@ -33,20 +33,20 @@ pldd \- display dynamic shared objects linked into a process
.SH DESCRIPTION
The
.B pldd
-command displays a list of the dynamic shared objects that are
-linked into the process with the specified process ID.
+command displays a list of the dynamic shared objects (DSOs) that are
+linked into the process with the specified process ID (PID).
The list includes the libraries that have been dynamically loaded using
.BR dlopen (3).
.SH OPTIONS
.TP
.BR \-? ", " \-\-help
-Display program help message.
+Display a help message and exit.
.TP
.B \-\-usage
-Display a short usage message.
+Display a short usage message and exit.
.TP
.BR \-V ", " \-\-version
-Display the program version.
+Display program version information and exit.
.SH EXIT STATUS
On success,
.B pldd
--
2.20.1
[-- Attachment #1.4: 0003-pldd.1-srcfix-ffix-wfix-wsfix.patch --]
[-- Type: text/x-diff, Size: 3941 bytes --]
From 9285fe1b80cfbb52cfeff33372338a8c4728d47b Mon Sep 17 00:00:00 2001
From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Date: Sat, 11 May 2019 16:38:39 +1000
Subject: [PATCH 3/3] pldd.1: srcfix, ffix, wfix, wsfix
* [srcfix] Migrate Synopsis section from no-fill mode to no-adjust mode.
This way you can break the pieces of a synopsis output line across
multiple input lines, use the easy one-font macros, and worry less
about quotation issues. (My best recommendation would be to go ahead
and use groff_man's .SY/.YS extensions--but not .OP--for synopsis
sections, but I think this was considered and rejected a couple of
years ago.)
* [wfix] Actually list the available options in the synopsis. There
aren't many for pldd and they won't even line-wrap on an 80-column
terminal. (not technically a ffix)
* [srcfix] Use .RS for indentation instead of low-level .in requests.
It's my belief that .RS and .RE pairs require less bookkeeping.
* [srcfix] Use \c (the output line continuation escape) in examples to
facilitate style (bold, italic) changes within a line. The result is
more attractive and intuitive, particularly enabling italicization of
paramaters in examples.
* [srcfix] Use font macros instead of font escapes in examples. This is
more readable, and helped to expose the next problem.
* [ffix] Consistently escape all hyphens used as option dashes in gdb
example.
* [wsfix] Eliminate hard tab from input file, replacing it (in an
example) with an appropriate number of non-adjustable spaces.
(Whether this is a srcfix or wsfix depends on the output device and
user configuration, which is, I submit, why we don't want to use hard
tabs in the first place.)
Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>
---
man1/pldd.1 | 48 +++++++++++++++++++++++++++++++-----------------
1 file changed, 31 insertions(+), 17 deletions(-)
diff --git a/man1/pldd.1 b/man1/pldd.1
index 035368e20..33245d0d5 100644
--- a/man1/pldd.1
+++ b/man1/pldd.1
@@ -26,10 +26,15 @@
.SH NAME
pldd \- display dynamic shared objects linked into a process
.SH SYNOPSIS
-.nf
-.BI "pldd " "pid"
-.BI pldd " option"
-.fi
+.na
+.B pldd
+.I pid
+.PP
+.B pldd
+.RB [ \-? | \-\-help ]
+.RB [ \-\-usage ]
+.RB [ \-V | \-\-version ]
+.ad
.SH DESCRIPTION
The
.B pldd
@@ -71,14 +76,17 @@ have a similar command.
.SH NOTES
The command
.PP
-.in +4n
+.RS 4n
.EX
-lsof \-p PID
+$ \c
+.B lsof \-p \c
+.I pid
.EE
-.in
+.RE
.PP
also shows output that includes the dynamic shared objects
-that are linked into a process.
+that are linked into the process
+.IR pid .
.PP
The
.BR gdb (1)
@@ -87,15 +95,19 @@ command also shows the shared libraries being used by a process,
so that one can obtain similar output to
.B pldd
using a command such as the following
-(to monitor the process with the specified
-.IR pid ):
+(to monitor the process with the specified PID):
.PP
-.in +4n
+.RS 4n
.EX
-$ \fBgdb \-ex "set confirm off" \-ex "set height 0" \-ex "info shared" \e\fP
- \fB-ex "quit" \-p $pid | grep '^0x.*0x'\fP
+$ \c
+.B gdb \-ex "set confirm off" \-ex "set height 0" \-ex "info shared" \e
+.RS 8n
+.B \-ex quit \-p \c
+.I pid \c
+.B | grep \(aq\(ti0x.*0x\(aq
+.RE
.EE
-.in
+.RE
.SH BUGS
From glibc 2.19 to 2.29,
.B pldd
@@ -104,10 +116,12 @@ was broken: it just hung when executed.
This problem was fixed in glibc 2.30.
.SH EXAMPLE
.EX
-$ \fBecho $$\fP # Display PID of shell
+$ \c
+.BR "echo $$" " # Display PID of the running shell."
1143
-$ \fBpldd $$\fP # Display DSOs linked into the shell
-1143: /usr/bin/bash
+$ \c
+.BR "pldd $$" " # Display DSOs linked into the shell."
+1143:\ \ \ /usr/bin/bash
linux\-vdso.so.1
/lib64/libtinfo.so.5
/lib64/libdl.so.2
--
2.20.1
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
next reply other threads:[~2019-05-11 7:21 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-05-11 7:20 G. Branden Robinson [this message]
2019-05-13 9:48 ` [PATCH] pldd.1: Document glibc's unbreakage of tool Florian Weimer
2019-05-13 14:17 ` G. Branden Robinson
2019-05-17 15:44 ` Florian Weimer
2019-05-17 15:51 ` G. Branden Robinson
2019-05-17 15:56 ` Carlos O'Donell
2019-05-20 16:58 ` Joseph Myers
2019-07-29 19:32 ` Michael Kerrisk (man-pages)
2019-07-29 19:18 ` Michael Kerrisk (man-pages)
2019-07-29 19:27 ` Carlos O'Donell
2019-05-13 14:34 ` walter harms
2019-07-29 19:07 ` Michael Kerrisk (man-pages)
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/libc/involved.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20190511072049.2w7pp723iszp3gra@localhost.localdomain \
--to=g.branden.robinson@gmail.com \
--cc=libc-alpha@sourceware.org \
--cc=linux-man@vger.kernel.org \
--cc=mtk.manpages@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).